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
- Variables
- func Admit(ctx context.Context, ...) (*engine.RequestAdmission, error)
- func CanonicalJSON(raw json.RawMessage) ([]byte, error)
- func ContextTokens(raw json.RawMessage) int
- func FoldSummary(ctx context.Context, prefix json.RawMessage, budget int, revision string, ...) (string, protocol.Usage, error)
- func InputMessages(messages []protocol.Message) ([]json.RawMessage, error)
- func PrefixDigest(messages []json.RawMessage) string
- func ProjectContent(raw json.RawMessage) (string, []protocol.ContentPart, []protocol.ToolCall, error)
- func ProjectMessage(raw json.RawMessage) (protocol.Message, error)
- func SameJSON(a, b json.RawMessage) bool
- func SummaryAllowance(prefix json.RawMessage, task string, budget int) (int, error)
- func SummaryView(messages []json.RawMessage, cut int, summary json.RawMessage) []json.RawMessage
- func ValidateMessages(raw json.RawMessage) error
- type CompactionPolicy
- type Compactor
- func (c *Compactor) Checkpoint() json.RawMessage
- func (c *Compactor) Prepare(ctx context.Context, raw json.RawMessage, policy CompactionPolicy) (json.RawMessage, error)
- func (c *Compactor) Restore(raw json.RawMessage) error
- func (c *Compactor) Transform(ctx context.Context, raw json.RawMessage) (out json.RawMessage)
- func (c *Compactor) TransformWithPolicy(ctx context.Context, raw json.RawMessage, policy CompactionPolicy) (out json.RawMessage)
- type CompactorOptions
- type ContextBudgetError
- type Summary
Constants ¶
const DefaultKeepRecentTokens = 20000
DefaultKeepRecentTokens is the host's default recent-context budget.
const ReserveTokens = 16384
ReserveTokens leaves room for the next response when deriving a model budget.
Variables ¶
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 ¶
func Admit(ctx context.Context, run func(context.Context, *ai.AssistantMessageEventStream, func(engine.Request)) (engine.Request, ai.AttemptOutcome, error)) (*engine.RequestAdmission, error)
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 ¶
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 ¶
ParseSummary validates a persisted summary envelope.