@vib-rato/agent-core 0.16.0

package/dist/types/agent.d.ts

@@ -0,0 +1,533 @@
+/** Agent class that uses the agent-loop directly.
+ * No transport abstraction - calls streamSimple via the loop.
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice, type UserMessage } from "@vib-rato/ai";
+import type { AppendOnlyContextManager } from "./append-only-context";
+import type { AttemptRunHandle, AttemptScope } from "./attempt-scope";
+import type { HarmonyAuditEvent } from "./harmony-leak";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentMetadataResolverContext, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunCancellationDomainBridge, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
+/**
+ * Whether persisted history ends at a point where a new model turn can resume.
+ * Assistant-ended histories require an in-memory queued message and are handled
+ * separately by `Agent.continue()`.
+ */
+export declare function canContinuePersistedHistory(messages: readonly AgentMessage[]): boolean;
+export declare class ManagedCursorInvariantError extends Error {
+    constructor(message?: string);
+}
+export declare class AgentBusyError extends Error {
+    constructor(message?: string);
+}
+export interface AgentOptions {
+    initialState?: Partial<AgentState>;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     * Default filters to user/assistant/toolResult and converts attachments.
+     */
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to context before convertToLlm.
+     * Use for context pruning, injecting external context, etc.
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal, scope?: AttemptScope) => Promise<AgentMessage[]>;
+    /**
+     * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
+     */
+    steeringMode?: "all" | "one-at-a-time";
+    /**
+     * Follow-up mode: "all" = send all follow-up messages at once, "one-at-a-time" = one per turn
+     */
+    followUpMode?: "all" | "one-at-a-time";
+    /**
+     * When to interrupt tool execution for steering messages.
+     * - "immediate": check after each tool call (default)
+     * - "wait": defer steering until the current turn completes
+     */
+    interruptMode?: "immediate" | "wait";
+    /** Cooperative pause checkpoint passed through to AgentLoopConfig.shouldPause. */
+    shouldPause?: AgentLoopConfig["shouldPause"];
+    /**
+     * API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic")
+     */
+    kimiApiFormat?: "openai" | "anthropic";
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+    /**
+     * Custom stream function (for proxy backends, etc.). Default uses streamSimple.
+     */
+    streamFn?: StreamFn;
+    /**
+     * Optional session identifier forwarded to LLM providers.
+     * Used by providers that support session-based caching (e.g., OpenAI code provider).
+     */
+    sessionId?: string;
+    /** Provider-facing cache/session affinity identifier. */
+    providerSessionId?: string;
+    /**
+     * Shared provider state map for session-scoped transport/session caches.
+     */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     * Useful for expiring tokens (e.g., GitHub Copilot OAuth).
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;
+    /**
+     * Inspect or replace provider payloads before they are sent.
+     */
+    onPayload?: SimpleStreamOptions["onPayload"];
+    /**
+     * Inspect provider response metadata after headers arrive and before streaming body consumption.
+     */
+    onResponse?: SimpleStreamOptions["onResponse"];
+    /**
+     * Inspect raw Server-Sent Events from HTTP streaming providers.
+     */
+    onSseEvent?: SimpleStreamOptions["onSseEvent"];
+    /**
+     * Inspect assistant streaming events before they are emitted to subscribers.
+     * Use this when abort decisions must happen before buffered events continue flowing.
+     */
+    onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+    /** Called for non-content tool-choice incapability stream events. */
+    onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];
+    /**
+     * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
+     */
+    onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
+    /**
+     * Custom token budgets for thinking levels (token-based providers only).
+     */
+    thinkingBudgets?: ThinkingBudgets;
+    /**
+     * Sampling temperature for LLM calls. `undefined` uses provider default.
+     */
+    temperature?: number;
+    /** Additional sampling controls for providers that support them. */
+    topP?: number;
+    topK?: number;
+    minP?: number;
+    presencePenalty?: number;
+    repetitionPenalty?: number;
+    serviceTier?: ServiceTier;
+    /**
+     * If true, request that the underlying provider omit reasoning/thinking summaries
+     * from the response. The model still reasons internally; only the human-readable
+     * summary stream is suppressed. Useful when the UI hides thinking blocks anyway.
+     */
+    hideThinkingSummary?: boolean;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately,
+     * allowing higher-level retry logic to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /** Provider request retry budget. Counts retries, not the initial attempt. */
+    requestMaxRetries?: number;
+    /** Provider stream replay retry budget. Counts retries, not the initial attempt. */
+    streamMaxRetries?: number;
+    /** Explicit first-event stream watchdog override in milliseconds. Set to 0 to disable. */
+    streamFirstEventTimeoutMs?: number;
+    /**
+     * Provides tool execution context, resolved per tool call.
+     * Use for late-bound UI or session state access.
+     */
+    getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
+    /**
+     * Optional transform applied to tool call arguments before execution.
+     * Use for deobfuscating secrets or rewriting arguments.
+     */
+    transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
+    /** Enable intent tracing schema injection/stripping in the harness. */
+    intentTracing?: boolean;
+    /** Dynamic tool choice override, resolved per LLM call. */
+    getToolChoice?: () => ToolChoice | undefined;
+    /**
+     * Cursor exec handlers for local tool execution.
+     */
+    cursorExecHandlers?: CursorExecHandlers;
+    /**
+     * Cursor tool result callback for exec tool responses.
+     */
+    cursorOnToolResult?: CursorToolResultHandler;
+    /**
+     * Called after a tool call has been validated and is about to execute.
+     * See {@link AgentLoopConfig.beforeToolCall} for full semantics.
+     */
+    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
+    /**
+     * Called after a tool finishes executing, before `tool_execution_end` and the tool-result
+     * message are emitted. See {@link AgentLoopConfig.afterToolCall} for full semantics.
+     */
+    afterToolCall?: AgentLoopConfig["afterToolCall"];
+    /** Invoked with the follow-up messages dequeued for the next turn (reassignable). */
+    onFollowUpConsumed?: AgentLoopConfig["onFollowUpConsumed"];
+    /** Invoked with the steering messages dequeued mid-run for the current turn (reassignable). */
+    onSteeringConsumed?: AgentLoopConfig["onSteeringConsumed"];
+    /**
+     * Opt-in OpenTelemetry instrumentation. Passing `{}` enables the loop's
+     * GenAI-semantic-convention spans using the global tracer provider. See
+     * {@link AgentLoopConfig.telemetry} for the full surface.
+     */
+    telemetry?: AgentLoopConfig["telemetry"];
+    /**
+     * Immutable context mode — stabilizes system prompt + tool spec bytes
+     * across turns so DeepSeek/Anthropic prefix caches hit at maximum rate.
+     */
+    appendOnlyContext?: AppendOnlyContextManager;
+}
+export interface AgentPromptOptions {
+    /** One-shot transient recovery instruction sent only to the provider for the next assistant request; never committed to durable history. */
+    transientRecoveryMessage?: UserMessage;
+    toolChoice?: ToolChoice;
+    /** Disable transport replay; fallback accounting is owned by the caller. */
+    fallbackManaged?: boolean;
+    /** Continue a cooperative maintenance checkpoint under its existing logical run and cancellation domain. */
+    maintenanceContinuation?: boolean;
+    /** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
+    onRunAccepted?: (handle: AttemptRunHandle, acceptance: {
+        consumedQueuedMessages: readonly AgentMessage[];
+    }) => void;
+    /** Called once immediately before every managed upstream request. */
+    nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
+    /** Called after a managed upstream request is accepted and committed. */
+    onManagedAttemptAccepted?: AgentLoopConfig["onManagedAttemptAccepted"];
+    /** Receives a discarded managed attempt without exposing assistant lifecycle events. */
+    onManagedAttemptOutcome?: AgentLoopConfig["onManagedAttemptOutcome"];
+}
+export type AgentQueueSnapshot = {
+    steering: AgentMessage[];
+    followUp: AgentMessage[];
+};
+export declare class Agent {
+    #private;
+    get intentTracing(): boolean;
+    readonly resourceLedger: RunResourceLedger;
+    bindRunCancellationDomainBridge(bridge: RunCancellationDomainBridge, agentSessionClaimKey?: object): void;
+    /** Mint a side-attempt scope and its authority unregister function. */
+    mintSideAttemptScope(): {
+        scope: AttemptScope;
+        dispose: () => void;
+    };
+    /** Return the Agent-owned attempt scope authority for session record injection. */
+    getAttemptScopeAuthority(): import("./attempt-scope").AttemptScopeAuthority;
+    /**
+     * Observe each main-attempt scope synchronously, before any provider or
+     * extension-capable lifecycle work can begin.
+     */
+    setMainAttemptScopeObserver(observer: ((scope: AttemptScope) => void) | undefined): void;
+    streamFn: StreamFn;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;
+    /**
+     * Hook invoked after tool arguments are validated and before execution.
+     * Reassign at any time to swap the implementation (e.g. on extension reload).
+     */
+    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
+    /**
+     * Hook invoked after tool execution and before `tool_execution_end` / tool-result
+     * message emission. Reassign at any time to swap the implementation.
+     */
+    afterToolCall?: AgentLoopConfig["afterToolCall"];
+    /** Invoked with the follow-up messages dequeued for the next turn. Reassign at any time. */
+    onFollowUpConsumed?: AgentLoopConfig["onFollowUpConsumed"];
+    /** Invoked with the steering messages dequeued mid-run for the current turn. Reassign at any time. */
+    onSteeringConsumed?: AgentLoopConfig["onSteeringConsumed"];
+    constructor(opts?: AgentOptions);
+    /**
+     * Get the current session ID used for provider caching.
+     */
+    get sessionId(): string | undefined;
+    /**
+     * Set the session ID for provider caching.
+     * Call this when switching sessions (new session, branch, resume).
+     */
+    set sessionId(value: string | undefined);
+    get providerSessionId(): string | undefined;
+    set providerSessionId(value: string | undefined);
+    /**
+     * Whether websocket transport is preferred when the provider implementation
+     * supports it. Read by maintenance one-shot calls (compaction, handoff,
+     * branch summary) so they forward the same transport preference as live turns.
+     */
+    get preferWebsockets(): boolean | undefined;
+    /**
+     * Static metadata forwarded to every API request when no resolver is installed
+     * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
+     * clears any installed resolver.
+     *
+     * For live/provider-aware metadata (e.g. Anthropic OAuth `account_uuid` that
+     * must reflect the credential selected per-request), use
+     * {@link setMetadataResolver} and read via {@link metadataForProvider}.
+     */
+    get metadata(): Record<string, unknown> | undefined;
+    set metadata(value: Record<string, unknown> | undefined);
+    /**
+     * Resolve request metadata for the given provider at call time. When a
+     * resolver is installed via {@link setMetadataResolver}, it is invoked with
+     * the provider string so the result can be scoped (e.g. `account_uuid` is
+     * only included for `"anthropic"` requests). Falls back to the static
+     * {@link metadata} value when no resolver is set.
+     */
+    metadataForProvider(provider: string, model?: Model, transport?: AgentMetadataResolverContext["transport"]): Record<string, unknown> | undefined;
+    /**
+     * Install a function that resolves request metadata at call time. The
+     * resolver receives the target provider string and can gate provider-specific
+     * fields (e.g. `account_uuid` only for `"anthropic"`). Invoked per LLM
+     * request by `agent-loop` after `getApiKey` selects the session-sticky
+     * credential. Pass `undefined` to clear and revert to the static
+     * {@link metadata} value.
+     */
+    setMetadataResolver(resolver: ((context: AgentMetadataResolverContext) => Record<string, unknown> | undefined) | undefined): void;
+    /**
+     * Read the active OpenTelemetry configuration. Returns `undefined` when
+     * instrumentation is disabled. Callers spawning child runs (e.g. subagent
+     * dispatch) forward this to the child's loop so its spans appear under the
+     * parent's active context with the subagent's own identity stamped.
+     */
+    get telemetry(): AgentLoopConfig["telemetry"] | undefined;
+    /**
+     * Replace the active OpenTelemetry configuration. Pass `undefined` to
+     * disable instrumentation. Applies to the *next* `agentLoop` invocation —
+     * in-flight loops keep the configuration they started with.
+     */
+    setTelemetry(telemetry: AgentLoopConfig["telemetry"] | undefined): void;
+    /**
+     * Get provider-scoped mutable session state store.
+     */
+    get providerSessionState(): Map<string, ProviderSessionState> | undefined;
+    /**
+     * Set provider-scoped mutable session state store.
+     */
+    set providerSessionState(value: Map<string, ProviderSessionState> | undefined);
+    /**
+     * Get the current thinking budgets.
+     */
+    get thinkingBudgets(): ThinkingBudgets | undefined;
+    /**
+     * Set custom thinking budgets for token-based providers.
+     */
+    set thinkingBudgets(value: ThinkingBudgets | undefined);
+    /**
+     * Get the current sampling temperature.
+     */
+    get temperature(): number | undefined;
+    /**
+     * Set sampling temperature for LLM calls. `undefined` uses provider default.
+     */
+    set temperature(value: number | undefined);
+    get topP(): number | undefined;
+    set topP(value: number | undefined);
+    get topK(): number | undefined;
+    set topK(value: number | undefined);
+    get minP(): number | undefined;
+    set minP(value: number | undefined);
+    get presencePenalty(): number | undefined;
+    set presencePenalty(value: number | undefined);
+    get repetitionPenalty(): number | undefined;
+    set repetitionPenalty(value: number | undefined);
+    get serviceTier(): ServiceTier | undefined;
+    set serviceTier(value: ServiceTier | undefined);
+    get hideThinkingSummary(): boolean | undefined;
+    set hideThinkingSummary(value: boolean | undefined);
+    /**
+     * Get the current max retry delay in milliseconds.
+     */
+    get maxRetryDelayMs(): number | undefined;
+    /**
+     * Set the maximum delay to wait for server-requested retries.
+     * Set to 0 to disable the cap.
+     */
+    set maxRetryDelayMs(value: number | undefined);
+    get requestMaxRetries(): number | undefined;
+    set requestMaxRetries(value: number | undefined);
+    get streamMaxRetries(): number | undefined;
+    set streamMaxRetries(value: number | undefined);
+    get streamFirstEventTimeoutMs(): number | undefined;
+    set streamFirstEventTimeoutMs(value: number | undefined);
+    get state(): AgentState;
+    get contextRevision(): number;
+    get appendOnlyContext(): AppendOnlyContextManager | undefined;
+    setAppendOnlyContext(manager?: AppendOnlyContextManager): void;
+    subscribe(fn: (e: AgentEvent) => void): () => void;
+    setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
+    setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
+    setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
+    setProvisionalAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
+    setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
+    setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void;
+    /** The currently installed cooperative pause checkpoint, if any. */
+    get shouldPause(): AgentLoopConfig["shouldPause"] | undefined;
+    /**
+     * Fence old-turn steering admission.
+     *
+     * The loop polls steering UPSTREAM of its pause checkpoint (and again on the
+     * immediate-interrupt path), so a cooperative stop alone cannot prevent one
+     * more old-turn model call once a steering message has already been dequeued.
+     * While the fence returns true the poll yields no messages AND does not
+     * dequeue, so the queue survives intact for the next turn.
+     */
+    setSteeringAdmissionFence(fn: (() => boolean) | undefined): void;
+    setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void;
+    /**
+     * Publish an event produced OUTSIDE the agent loop (a provider that executed the tool
+     * itself, a host bridge, a replay).
+     *
+     * Identity is the PRODUCER's to prove: whoever dispatched the call binds the tool object
+     * it actually ran (see `bindDispatchedToolIdentity`) before handing the event here, and
+     * that binding is never touched from this side. Re-resolving `event.toolName` against the
+     * mutable current tool list would let a mid-run `setTools`, MCP reload, or plain name
+     * collision overwrite a proven object with one that never ran — and would invent an
+     * identity for replays and host bridges that never executed an AgentTool at all. An
+     * unbound external event stays unbound; unproven provenance is `custom`.
+     */
+    emitExternalEvent(event: AgentEvent): void;
+    createExternalEventEmitterForCurrentRun(): ((event: AgentEvent) => void) | undefined;
+    setSystemPrompt(v: string[]): void;
+    setModel(m: Model | undefined): void;
+    setThinkingLevel(l: Effort | undefined): void;
+    setSteeringMode(mode: "all" | "one-at-a-time"): void;
+    getSteeringMode(): "all" | "one-at-a-time";
+    setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    getFollowUpMode(): "all" | "one-at-a-time";
+    setInterruptMode(mode: "immediate" | "wait"): void;
+    getInterruptMode(): "immediate" | "wait";
+    setTools(t: AgentTool<any>[]): void;
+    replaceMessages(ms: AgentMessage[], options?: {
+        historyRewrite?: {
+            reason: string;
+            preserveSeededPrefix?: boolean;
+        };
+    }): void;
+    appendMessage(m: AgentMessage): void;
+    popMessage(): AgentMessage | undefined;
+    /**
+     * For callers that mutate committed messages or the system prompt in place
+     * outside Agent-owned mutators.
+     */
+    touchContext(): void;
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     * Delivered after current tool execution, skips remaining tools.
+     */
+    steer(m: AgentMessage): void;
+    /**
+     * Resolves when a steering message is queued (or is already queued), or when
+     * `signal` aborts. The queue is not consumed. Long observation tools use this
+     * to end their wait early so a busy user message is handled at the next tool
+     * boundary instead of after the full wait window.
+     */
+    waitForSteeringArrival(signal: AbortSignal): Promise<void>;
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     * Delivered only when agent has no more tool calls or steering messages.
+     *
+     * `forceOneAtATime` lets UI composer queues preserve prompt-by-prompt
+     * delivery even when the session-wide follow-up mode is set to `all` for
+     * other integration paths.
+     */
+    followUp(m: AgentMessage, options?: {
+        forceOneAtATime?: boolean;
+    }): void;
+    clearSteeringQueue(): void;
+    clearFollowUpQueue(): void;
+    clearAllQueues(): void;
+    hasQueuedMessages(): boolean;
+    hasQueuedSteering(): boolean;
+    /**
+     * Snapshot the steering queue without mutating it. Used to preserve queued
+     * steering across maintenance ops (compaction/handoff) that call reset().
+     */
+    snapshotSteering(): AgentMessage[];
+    /**
+     * Restore previously snapshotted steering messages ahead of any newly
+     * queued ones. No-op for an empty snapshot.
+     */
+    restoreSteering(messages: AgentMessage[]): void;
+    /** Snapshot the follow-up queue without mutating it. */
+    snapshotFollowUp(): AgentMessage[];
+    /** Restore previously snapshotted follow-up messages ahead of any newly queued ones. */
+    restoreFollowUp(messages: AgentMessage[]): void;
+    /** Snapshot both executable queues as one atomic session-level view. */
+    snapshotQueues(): AgentQueueSnapshot;
+    /** Replace both executable queues with a prior snapshot. */
+    restoreQueues(snapshot: AgentQueueSnapshot): void;
+    /**
+     * Remove and return the last steering message from the queue (LIFO).
+     * Used by dequeue keybinding.
+     */
+    popLastSteer(): AgentMessage | undefined;
+    removeSteerAt(index: number): AgentMessage | undefined;
+    moveSteer(fromIndex: number, toIndex: number): boolean;
+    /**
+     * Remove and return the last follow-up message from the queue (LIFO).
+     * Used by dequeue keybinding.
+     */
+    popLastFollowUp(): AgentMessage | undefined;
+    removeFollowUpAt(index: number): AgentMessage | undefined;
+    moveFollowUp(fromIndex: number, toIndex: number): boolean;
+    /**
+     * Remove ALL queued STEERING messages without touching the follow-up queue.
+     * Used by the terminal-abort path to purge steering queued for the aborted
+     * turn (the loop may exit on the abort signal without polling it); the
+     * follow-up queue is preserved because it may carry owned-completion
+     * resumes that must still deliver.
+     */
+    clearSteeringMessages(): void;
+    /**
+     * Remove queued steering/follow-up messages matching `predicate`, preserving
+     * order of the rest. `scope` restricts the removal to one queue — the
+     * terminal-abort steering purge must not wipe the follow-up queue, which
+     * the owned-completion resume policy preserves.
+     */
+    removeQueuedMessages(predicate: (message: AgentMessage) => boolean, scope?: "both" | "steering" | "followUp"): {
+        steering: number;
+        followUp: number;
+        total: number;
+    };
+    clearMessages(): void;
+    abort(): void;
+    /**
+     * Force the current run out of the busy/streaming state when cooperative abort
+     * did not drain. The abandoned provider/tool stream may still settle later, so
+     * #runLoop guards every state mutation with a run id.
+     */
+    forceAbort(reason?: string, logicalRunId?: ManagedLogicalRunId | number): boolean;
+    waitForIdle(): Promise<void>;
+    /** The active per-attempt run identifier. */
+    get activeRunId(): number | undefined;
+    /** Stable resource ownership identifier for the active prompt run. */
+    get activeResourceRunId(): string | undefined;
+    /**
+     * Stable identifier for the active managed logical run, shared by every retry
+     * attempt. Pass this value to requestRunTerminal(); never retain activeRunId
+     * for managed terminal completion.
+     */
+    get currentManagedLogicalRunId(): ManagedLogicalRunId | undefined;
+    /**
+     * Request terminal completion through the single logical-run keyed finalizer.
+     *
+     * For managed runs, logicalRunId must be currentManagedLogicalRunId from any
+     * attempt in the retry chain. Non-managed runs use their activeRunId. Terminal
+     * requests with messages emit a committed message_start/message_end lifecycle
+     * for each diagnostic before agent_end. Requests without messages (such as
+     * cancellation) emit only agent_end.
+     */
+    requestRunTerminal(logicalRunId: ManagedLogicalRunId, request: RunTerminalRequest): boolean;
+    reset(): void;
+    /** Send a prompt with an AgentMessage */
+    prompt(message: AgentMessage | AgentMessage[], options?: AgentPromptOptions): Promise<void>;
+    prompt(input: string, options?: AgentPromptOptions): Promise<void>;
+    prompt(input: string, images?: ImageContent[], options?: AgentPromptOptions): Promise<void>;
+    /**
+     * Continue from current context (used for retries and resuming queued messages).
+     */
+    continue(options?: AgentPromptOptions): Promise<void>;
+    /**
+     * Continue by consuming queued steering/follow-up messages without replaying
+     * the current non-assistant tail.
+     */
+    continueQueuedMessages(options?: AgentPromptOptions): Promise<void>;
+}

package/dist/types/append-only-context.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Append-only context mode — stabilizes the byte prefix sent to the LLM
+ * across turns so provider prefix caches (DeepSeek, Anthropic, etc.)
+ * hit at the maximum possible rate.
+ *
+ * Two mechanisms:
+ *
+ * 1. **StablePrefix** — system prompt + tool specs are computed once
+ *    and frozen. Subsequent turns reuse the exact same byte sequence
+ *    unless `invalidate()` is called (e.g. after MCP reconnect).
+ *
+ * 2. **AppendOnlyLog** — messages only grow; prior turns are never
+ *    re-serialized. Combined with a stable prefix, only the user's new
+ *    message delta is a cache miss each turn.
+ */
+import type { Context, Message, Tool } from "@vib-rato/ai";
+import type { AgentContext } from "./types";
+/** Frozen system prompt + tool spec snapshot. */
+export interface StablePrefixSnapshot {
+    systemPrompt: string[];
+    tools: Tool[];
+    fingerprint: string;
+}
+/** Options threaded through `build()` so the snapshot reflects loop-time settings. */
+export interface BuildOptions {
+    /** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
+    intentTracing: boolean;
+}
+/**
+ * A frozen prefix (system prompt + tools) that produces stable byte
+ * sequences across `build()` calls.
+ *
+ * The first `build()` snapshots the live state. Subsequent calls reuse
+ * the cached copy until `invalidate()` is called or the live state's
+ * fingerprint changes.
+ */
+export declare class StablePrefix {
+    #private;
+    get fingerprint(): string;
+    get version(): number;
+    get built(): boolean;
+    exportSnapshot(): StablePrefixSnapshot | null;
+    importSnapshot(snapshot: StablePrefixSnapshot, options: BuildOptions): void;
+    /**
+     * Build or rebuild from live context.
+     * Returns `true` if the prefix actually changed (cache miss imminent).
+     */
+    build(context: AgentContext, options: BuildOptions): boolean;
+    /** Force rebuild on the next `build()` call. */
+    invalidate(): void;
+    /**
+     * Returns the cached prefix.
+     * @throws if `build()` was never called.
+     */
+    toContext(): {
+        systemPrompt: string[];
+        tools: Tool[];
+    };
+}
+/**
+ * Append-only message log at the `Message[]` (provider-level) layer.
+ *
+ * The only mutation path is `replaceTail()`, reserved for compaction.
+ * Every other operation is append-only.
+ */
+export declare class AppendOnlyLog {
+    #private;
+    get length(): number;
+    append(message: any): void;
+    extend(messages: any[]): void;
+    /** Replace the last entry — only legal for compaction. */
+    replaceTail(replacement: any): void;
+    /** Returns a shallow copy of all entries. */
+    toMessages(): Message[];
+    /** Direct readonly access for in-place inspection. */
+    entries(): readonly Message[];
+    clear(): void;
+}
+/**
+ * Manages a stable prefix + append-only log for the agent loop.
+ *
+ * Call `build(context)` each turn to get a `Context` with stable
+ * `systemPrompt` and `tools` and append-only messages. Call
+ * `syncMessages(normalizedMessages)` after `convertToLlm` each
+ * turn to keep the log in sync.
+ *
+ * Example:
+ * ```
+ * const mgr = new AppendOnlyContextManager();
+ * const ctx = mgr.build(context);  // first call snapshots prefix
+ * mgr.syncMessages(normalized);    // grow the log
+ * ctx = mgr.build(context);        // subsequent calls use cache
+ * ```
+ */
+export interface AppendOnlyContextManagerOptions {
+    /**
+     * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+     * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+     * not throw. `from` is `<unbuilt>` on the first build.
+     */
+    readonly onPrefixChange?: (info: {
+        from: string;
+        to: string;
+        version: number;
+    }) => void;
+}
+export declare class AppendOnlyContextManager {
+    #private;
+    readonly prefix: StablePrefix;
+    readonly log: AppendOnlyLog;
+    constructor(options?: AppendOnlyContextManagerOptions);
+    static forkFromSeed(args: {
+        prefixSnapshot?: StablePrefixSnapshot;
+        messages?: readonly Message[];
+        options: BuildOptions;
+    }): AppendOnlyContextManager;
+    build(context: AgentContext, options: BuildOptions): Context;
+    /**
+     * Sync normalized (provider-level) messages into the append-only log.
+     *
+     * Detects both compaction (shorter array) and in-place rewrites
+     * (same length, changed content via a rolling digest).
+     */
+    syncMessages(normalizedMessages: any[]): void;
+    seedNormalizedMessages(messages: readonly Message[], options?: {
+        reset?: boolean;
+    }): void;
+    /** Reset prefix + log for a model/provider switch while mode stays active. */
+    invalidateForModelChange(): void;
+    /** Reset the sync cursor AND clear the log. */
+    resetSyncCursor(): void;
+    appendMessage(message: any): void;
+    replaceTailMessage(message: any): void;
+    /** Release provider-normalized retainers as one history-rewrite transaction. */
+    releaseAfterHistoryRewrite(options?: {
+        preserveSeededPrefix?: boolean;
+    }): void;
+    invalidate(): void;
+    reset(context: AgentContext, options: BuildOptions): void;
+}
+export declare function cloneJson<T>(value: T): T;