host

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package host supplies reusable policy and checkpoint utilities around the native engine. It owns request compaction and transcript identity/validation; engine owns scheduling, ai owns provider messages, and consumers own storage, credentials, model selection and the summarizer callback. InputMessages converts new host instructions, and ProjectMessage/ProjectContent produce detached display views for plugins and observers. Neither projection is a substitute for the native transcript.

A Compactor transforms only the provider request view. Keep the original native messages as the authoritative transcript and persist Checkpoint alongside them. Restore verifies the summary envelope/revision; Transform verifies that its prefix still matches before using it. A legacy agentcore.Message display projection is not a native checkpoint and must not be replayed as one.

Index

Constants

View Source
const DefaultKeepRecentTokens = 20000

DefaultKeepRecentTokens is the host's default recent-context budget.

View Source
const ReserveTokens = 16384

ReserveTokens leaves room for the next response when deriving a model budget.

Variables

View Source
var ErrUnsettledEffect = errors.New("Pi session has an unsettled tool effect")

ErrUnsettledEffect marks a missing physical effect receipt or native tool result.

Functions

func Admit

Admit runs AI fallback while waiting only for the selected prepared request. run calls accept after committing selection and before publishing visible events. Its returned request is the last prepared candidate, used when all candidates fail without committing. AI owns replay/retry/fallback decisions.

func CanonicalJSON

func CanonicalJSON(raw json.RawMessage) ([]byte, error)

CanonicalJSON normalizes object ordering and decimal spelling without rounding opaque native numbers through float64. It is only for identity checks; the original messages remain the replay payload.

func ContextTokens

func ContextTokens(raw json.RawMessage) int

ContextTokens uses settled provider usage plus the appended tail, floored by a local estimate. Rewritten views invalidate older usage anchors without modifying the original billable usage or signed native messages.

func FoldSummary

func FoldSummary(ctx context.Context, prefix json.RawMessage, budget int, revision string, summarize func(context.Context, json.RawMessage, string) (string, protocol.Usage, error)) (string, protocol.Usage, error)

FoldSummary treats oversized transcript JSON as source segments, not new native messages. Every bounded call includes the preceding summary. This keeps a smaller summarizer/fallback model from receiving the entire prefix at once while leaving the signed transcript and tool groups untouched.

func InputMessages

func InputMessages(messages []protocol.Message) ([]json.RawMessage, error)

These are newly authored host instructions, never provider/history messages. InputMessages converts newly authored host input only; provider history remains native.

func PrefixDigest

func PrefixDigest(messages []json.RawMessage) string

PrefixDigest hashes semantic JSON identity without rounding opaque numbers.

func ProjectContent

func ProjectContent(raw json.RawMessage) (string, []protocol.ContentPart, []protocol.ToolCall, error)

ProjectContent extracts display text, images and calls from native content.

func ProjectMessage

func ProjectMessage(raw json.RawMessage) (protocol.Message, error)

ProjectMessage produces a display/observer view. Never use it as a native checkpoint.

func SameJSON

func SameJSON(a, b json.RawMessage) bool

SameJSON compares opaque native JSON without modifying its replay bytes.

func SummaryAllowance

func SummaryAllowance(prefix json.RawMessage, task string, budget int) (int, error)

SummaryAllowance reserves the immutable host systems/tools and exact task before assigning output to the summary. Small budgets cannot spend a fixed fraction on summary text when tool declarations already fill most of them.

func SummaryView

func SummaryView(messages []json.RawMessage, cut int, summary json.RawMessage) []json.RawMessage

SummaryView replaces a validated prefix while preserving its system messages. The caller must supply a cut within the message slice and outside a tool batch.

func ValidateMessages

func ValidateMessages(raw json.RawMessage) error

ValidateMessages checks completed native tool batches without projecting or changing messages. Provider error/aborted partial calls require no results.

Types

type CompactionPolicy

type CompactionPolicy struct {
	// Approximate token counts. A nonpositive Budget disables new summaries;
	// ForWindow can derive or cap it from a model window. KeepRecent is bounded
	// to at least one token and at most half the effective budget.
	Budget, KeepRecent int
	// MaxInputTokens is the model's reserve-aware input ceiling. Budget remains
	// a compaction trigger/target; immutable host tools can exceed a very low
	// target while still fitting the model. Without a known ceiling, Budget is
	// also the fit bound.
	MaxInputTokens int
	// Force permits summarizing a completed latest turn after a confirmed
	// pre-output context rejection. It never replays tools or changes history.
	Force bool
	// Archive saves a full tool result before a request-only preview replaces
	// it. The returned locator must be readable by this run's retrieval tool.
	Archive func(context.Context, string, string, string) (string, error)
	// Task is the consumer's current user request, retained verbatim alongside
	// summaries. It is data, never a system instruction or extra permission.
	Task      string
	Summarize func(context.Context, json.RawMessage, string) (string, protocol.Usage, error)
}

CompactionPolicy configures the consumer's request-only transform. The original Agent retains its full transcript, including every tool result.

func (CompactionPolicy) ForWindow

func (p CompactionPolicy) ForWindow(window int) CompactionPolicy

ForWindow derives a request policy without mutating the original budget.

type Compactor

type Compactor struct {
	// contains filtered or unexported fields
}

Compactor owns one run's request view and persisted summary. Calls must be serialized.

func NewCompactor

func NewCompactor(options CompactorOptions) *Compactor

NewCompactor creates a run-owned compactor. Calls are serialized by the host.

func (*Compactor) Checkpoint

func (c *Compactor) Checkpoint() json.RawMessage

Checkpoint returns an independent copy of the latest persisted summary. A nil result means no summary has been accepted.

func (*Compactor) Prepare

func (c *Compactor) Prepare(ctx context.Context, raw json.RawMessage, policy CompactionPolicy) (json.RawMessage, error)

Prepare verifies the actual outgoing view after compaction. Oversized tool text is recoverable through the existing archive/retrieval seam, never lost. If the request still cannot fit, fail before sending it instead of repeatedly paying for a summary over the same tail. The original transcript is untouched.

func (*Compactor) Restore

func (c *Compactor) Restore(raw json.RawMessage) error

Restore validates a saved summary before replacing the current checkpoint. The next Transform additionally verifies its digest against the native input.

func (*Compactor) Transform

func (c *Compactor) Transform(ctx context.Context, raw json.RawMessage) (out json.RawMessage)

Request transforms are called serially by the original loop. A saved summary refers to a prefix of this exact view (after native host hooks), never to a Go text projection. On mismatch the full native context is the safe fallback.

func (*Compactor) TransformWithPolicy

func (c *Compactor) TransformWithPolicy(ctx context.Context, raw json.RawMessage, policy CompactionPolicy) (out json.RawMessage)

TransformWithPolicy applies the effective policy for this request, retaining the compactor's checkpoint and original policy for subsequent model changes.

type CompactorOptions

type CompactorOptions struct {
	Revision string
	Policy   CompactionPolicy
	Record   func(context.Context, json.RawMessage) error
	Usage    func(protocol.Usage)
}

CompactorOptions binds the host's persistence and usage accounting. Record must succeed before a new summary becomes visible to the provider.

type ContextBudgetError

type ContextBudgetError struct{ Estimated, Budget int }

ContextBudgetError contains only safe numeric diagnostics for public hosts.

func (*ContextBudgetError) Error

func (e *ContextBudgetError) Error() string

type Summary

type Summary struct {
	Revision     string          `json:"revision"`
	PrefixCount  int             `json:"prefix_count"`
	PrefixDigest string          `json:"prefix_digest"`
	Message      json.RawMessage `json:"message"`
}

Summary binds a persisted summary to an exact native transcript prefix.

func ParseSummary

func ParseSummary(raw string) (Summary, error)

ParseSummary validates a persisted summary envelope.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL