@linxiraos/pi-agent-core 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [Unreleased]
+## [1.0.5] - 2026-08-16
 
 ## [1.0.2] - 2026-08-15
 

package/dist/types/agent-loop.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+import { type AssistantMessage, type Context, EventStream, type ToolResultMessage } from "@linxiraos/pi-ai";
+import { type Dialect } from "@linxiraos/pi-ai/dialect";
+import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector.js";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+/** Stop-details marker for a provider error after assistant content/tool args already streamed. */
+export declare const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
+/**
+ * Cadence (ms) for polling queued steering while an `interruptible` tool is in
+ * flight, so a steer cuts the wait short instead of sitting idle until the
+ * tool's own window elapses. A cheap synchronous queue check; latency-bounded
+ * at one tick.
+ */
+/**
+ * Abort reason for a turn-wide interruption where only some tool calls caused
+ * the abort and sibling placeholders need neutral messages.
+ */
+export interface ToolScopedAbortReason {
+    readonly kind: "tool-scoped-abort";
+    readonly message: string;
+    readonly toolCallMessages: Record<string, string>;
+    readonly defaultToolCallMessage: string;
+}
+/** Creates an abort reason that labels matching tool calls separately from siblings. */
+export declare function createToolScopedAbortReason(message: string, toolCallMessages: Record<string, string>, defaultToolCallMessage: string): ToolScopedAbortReason;
+/**
+ * Marks an abort raised by a completed post-tool hook as terminal for the
+ * current run. External/user aborts still synthesize an aborted assistant
+ * boundary; this reason stops after persisting the completed tool batch.
+ */
+export declare const TERMINAL_TOOL_RESULT_ABORT_REASON: unique symbol;
+export declare function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined;
+/**
+ * Start an agent loop with a new prompt message.
+ * The prompt is added to the context and events are emitted for it.
+ */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Continue an agent loop from the current context without adding a new message.
+ * Used for retries - context already has user message or tool results.
+ *
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
+ */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
+ * run-level telemetry/coverage rollup to the existing `AgentMessage[]`
+ * payload without changing the resolved type of `stream.result()`.
+ */
+export interface AgentLoopDetailedResult {
+    readonly messages: AgentMessage[];
+    readonly telemetry: AgentRunSummary | undefined;
+    readonly coverage: AgentRunCoverage | undefined;
+}
+/**
+ * Convenience wrapper over {@link agentLoop} that exposes the run-level
+ * summary + coverage alongside the messages. The returned `stream` is the
+ * same `EventStream` callers already consume; `detailed()` awaits the
+ * stream's `agent_end` event and returns the additive fields.
+ *
+ * Existing `stream.result()` semantics are preserved — it still resolves to
+ * `AgentMessage[]`. Use {@link agentLoopDetailed} when you need the rollup;
+ * use {@link agentLoop} when you do not.
+ */
+export declare function agentLoopDetailed(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
+    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
+    readonly detailed: () => Promise<AgentLoopDetailedResult>;
+};
+/**
+ * Like {@link agentLoopDetailed} but built on top of
+ * {@link agentLoopContinue}.
+ */
+export declare function agentLoopContinueDetailed(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
+    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
+    readonly detailed: () => Promise<AgentLoopDetailedResult>;
+};
+export declare function normalizeMessagesForProvider(messages: Context["messages"], model: AgentLoopConfig["model"]): Context["messages"];
+export interface NormalizeToolsOptions {
+    /** Inject the `i` intent field into tool schemas (subject to `PI_NO_INTENT`). */
+    injectIntent: boolean;
+    /** Strip descriptions from the wire specs when the catalog rides in the system prompt. */
+    pruneDescriptions?: boolean;
+}
+export declare function normalizeTools(tools: AgentContext["tools"], options: NormalizeToolsOptions): Context["tools"];
+/** Resolve the human-readable reason an abort carried. A caller that aborts via
+ *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
+ *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the
+ *  synthesized assistant message's `errorMessage`; a bare `abort()` (whose
+ *  `signal.reason` is the default `AbortError` `DOMException`) falls back to the
+ *  generic sentinel that downstream renderers treat as "no specific reason". */
+export declare function abortReasonText(signal: AbortSignal | undefined): string;
+/**
+ * Discriminator embedded in {@link AgentToolResult.details} and
+ * {@link ToolResultMessage.details} for tool calls that were emitted by the
+ * assistant but never actually invoked locally.
+ *
+ * The synthetic result exists only to preserve the tool_use / tool_result
+ * pairing the provider API requires; no `tool.execute()` ran. UI, telemetry,
+ * and history consumers can key on `__synthetic === true` to render or
+ * classify these as "call emitted, not executed" instead of a real local
+ * tool failure — the mislabeling this discriminator was introduced to fix
+ * (#4321): a provider-side stream error after tool-call emission (e.g. Codex
+ * websocket close) was surfaced by the CLI as if the local tool had failed.
+ *
+ * `source` names the state that prevented execution — either an assistant-side
+ * turn termination (`assistant_stop_*`) or a mid-batch interrupt that skipped a
+ * still-pending call to service queued steering/peer input (`interrupt_skipped`).
+ * `upstreamError` is the provider-reported message when the turn ended with
+ * `stopReason === "error"`.
+ */
+export interface SyntheticToolResultDetails {
+    __synthetic: true;
+    source: "assistant_stop_aborted" | "assistant_stop_error" | "assistant_stop_skipped" | "assistant_stop_length" | "interrupt_skipped";
+    executed: false;
+    upstreamError?: string;
+}
+/**
+ * Narrow an {@link AgentMessage} to a synthetic {@link ToolResultMessage} —
+ * a tool_result emitted for a tool call the assistant never invoked (see
+ * {@link SyntheticToolResultDetails}). Consumers use this to look past the
+ * placeholder pairing back to the assistant turn that produced it, e.g.
+ * `AgentSession.retry()` walking back over the synthetic results a
+ * stalled/aborted mid-tool-call turn leaves behind.
+ */
+export declare function isSyntheticToolResultMessage(message: AgentMessage | undefined): message is ToolResultMessage<SyntheticToolResultDetails>;
+/**
+ * Create the persisted synthetic result for a tool call that was emitted by
+ * the assistant but never invoked locally.
+ */
+export declare function createSyntheticToolResultMessage(toolCall: Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>, reason: "aborted" | "error" | "skipped" | "length", errorMessage?: string): ToolResultMessage<SyntheticToolResultDetails>;

package/dist/types/agent.d.ts

@@ -0,0 +1,465 @@
+import { type ApiKey, type AssistantMessage, type AssistantMessageEvent, type Context, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@linxiraos/pi-ai";
+import type { Dialect } from "@linxiraos/pi-ai/dialect";
+import type { HarmonyAuditEvent } from "@linxiraos/pi-ai/utils/harmony-leak";
+import type { AppendOnlyContextManager } from "./append-only-context.js";
+import type { AgentBeforeModelCall, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
+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) => Promise<AgentMessage[]>;
+    /**
+     * Optional transform applied after provider context assembly and before
+     * telemetry capture/provider send.
+     */
+    transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+    /**
+     * 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";
+    /**
+     * 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;
+    /** Absolute wall-clock deadline in Unix epoch milliseconds. */
+    deadline?: number;
+    /**
+     * Optional session identifier forwarded to LLM providers.
+     * Used by providers that support session-based caching (e.g., OpenAI Codex).
+     */
+    sessionId?: string;
+    /**
+     * Optional prompt cache key forwarded to LLM providers.
+     * When omitted, providers may fall back to sessionId.
+     */
+    promptCacheKey?: string;
+    /**
+     * Shared provider state map for session-scoped transport/session caches.
+     */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /**
+     * Resolves an API key or resolver dynamically for each LLM call.
+     * Useful for expiring tokens and model-scoped credential routing.
+     */
+    getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | 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 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;
+    /**
+     * Per-call effective service-tier resolver. When set, it authoritatively
+     * supplies the request's tier (replacing the static `serviceTier` and its
+     * telemetry) per model — used to scope a provider/model into a priority
+     * serving path without mutating the shared session `serviceTier`.
+     */
+    serviceTierResolver?: (model: Model) => ServiceTier | undefined;
+    /**
+     * 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;
+    /**
+     * 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>;
+    /**
+     * Resolve a tool call whose name matched no advertised tool. Lets hosts
+     * route calls to tools exposed through side transports (e.g. `xd://`
+     * device mounts) instead of failing with "Tool not found".
+     */
+    resolveFallbackTool?: (name: string) => AgentTool<any> | undefined;
+    /** Enable intent tracing schema injection/stripping in the harness. */
+    intentTracing?: boolean;
+    /**
+     * Strip tool descriptions from provider-bound tool specs (top-level + nested
+     * schema annotations). Use when the full catalog is rendered into the system
+     * prompt so descriptions are not duplicated on the wire. Native tool calling only.
+     */
+    pruneToolDescriptions?: boolean;
+    /** Owned tool-calling dialect. Undefined keeps provider-native tool calling. */
+    dialect?: Dialect;
+    /**
+     * When owned tool calling is active and the model fabricates a tool result
+     * mid-turn: `true` (default) aborts the provider request immediately; `false`
+     * drains the request and discards the fabricated continuation. Forwarded to
+     * the loop's {@link AgentLoopConfig.abortOnFabricatedToolResult}.
+     */
+    abortOnFabricatedToolResult?: boolean;
+    /** Dynamic tool-choice directive (hard {@link ToolChoice} or {@link SoftToolRequirement}), resolved once per turn. */
+    getToolChoice?: () => ToolChoiceDirective | undefined;
+    /** Reject a deferred hard choice when its named tool is no longer active. */
+    onToolChoiceUnavailable?: () => void;
+    /**
+     * Cursor exec handlers for local tool execution.
+     */
+    cursorExecHandlers?: CursorExecHandlers;
+    /** Additional tools Cursor executes through its MCP request-context bridge, resolved before each provider call. */
+    getCursorTools?: () => AgentTool[];
+    /**
+     * Optional rewrite of Cursor exec-channel tool results. May return a Promise.
+     *
+     * The Agent reserves the original result in its Cursor result buffer first,
+     * then awaits this hook and patches the reserved entry in place. That keeps
+     * the call paired even if `message_end` arrives while the Promise is still
+     * pending, and `#emitCursorSplitAssistantMessage` waits for any transformer
+     * still in flight before persisting, so a late rewrite is not lost. A
+     * rejecting transformer is swallowed and the reserved payload stands in.
+     * Hosts that only pass `cursorExecHandlers` (the coding-agent path) never
+     * hit this hook.
+     */
+    cursorOnToolResult?: CursorToolResultHandler;
+    /** Current working directory used by local tool execution. */
+    cwd?: string;
+    /**
+     * Resolver for the live working directory, re-read on every turn. When set, it
+     * overrides the static {@link cwd} at config-build time so a session move
+     * (`/move`, which updates the host's cwd without reconstructing the Agent) is
+     * reflected in provider options — e.g. GitLab Duo Agent namespace/project
+     * discovery keys off this cwd's git remote. Falls back to `cwd` when it returns
+     * `undefined`.
+     */
+    cwdResolver?: () => string | undefined;
+    /**
+     * 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"];
+    /**
+     * Called once an assistant message is finalized, before it reaches the
+     * context, the UI, or tool dispatch. May mutate the message in place (text +
+     * tool-call arguments). See {@link AgentLoopConfig.transformAssistantMessage}.
+     */
+    transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+    /**
+     * 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 {
+    toolChoice?: ToolChoice;
+}
+export declare class Agent {
+    #private;
+    streamFn: StreamFn;
+    getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | 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"];
+    /**
+     * Hook invoked once an assistant message is finalized, before context append,
+     * UI emission, and tool dispatch. Reassign at any time to swap the implementation.
+     */
+    transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+    /**
+     * Hook that peeks whether interrupting IRC asides are queued for the next boundary.
+     */
+    hasIrcInterrupts?: AgentLoopConfig["hasIrcInterrupts"];
+    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 the prompt cache key forwarded to providers.
+     */
+    get promptCacheKey(): string | undefined;
+    /**
+     * Set the prompt cache key forwarded to providers.
+     */
+    set promptCacheKey(value: string | 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): 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: ((provider: string) => 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 serviceTierResolver(): ((model: Model) => ServiceTier | undefined) | undefined;
+    set serviceTierResolver(value: ((model: Model) => ServiceTier | undefined) | 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 state(): AgentState;
+    get appendOnlyContext(): AppendOnlyContextManager | undefined;
+    setAppendOnlyContext(manager?: AppendOnlyContextManager): void;
+    /**
+     * Assemble the provider Context for a side-channel (no-loop) request, mirroring
+     * the main loop's prefix (system + normalized tools) so it shares the prompt
+     * cache. Never touches the append-only log or the tool-choice queue. Owned/
+     * in-band dialect sessions stay tools-less (matching their no-native-tools wire
+     * shape and avoiding tool-markup leakage). `llmMessages` is already converted
+     * (and, in production, obfuscated) by the caller.
+     *
+     * `systemPrompt` defaults to the live agent prompt so the side request hits the
+     * same cached prefix as the main loop. Callers that must pin a different prompt
+     * (e.g. handoff generation, which uses the base prompt rather than a per-turn
+     * `before_agent_start` hook override) pass it explicitly.
+     */
+    buildSideRequestContext(llmMessages: Message[], systemPrompt?: string[]): Promise<Context>;
+    subscribe(fn: (e: AgentEvent) => void): () => void;
+    /** Register an independently removable hook that runs before queued messages are consumed. */
+    addBeforeQueuedMessageDequeueHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
+    /** Register an independently removable hook that runs immediately before each model call. */
+    addBeforeModelCallHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
+    setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
+    setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
+    setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
+    setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
+    setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void) | undefined): void;
+    /**
+     * Install or replace the host pre-model-call gate; pass `undefined` to
+     * remove it. Gates are sampled when a run starts: installing the first
+     * gate while a run is in flight takes effect on the next run.
+     */
+    setBeforeModelCall(fn: AgentBeforeModelCall | undefined): void;
+    /**
+     * Add a pre-model callback without replacing callbacks owned by the host.
+     * Returns a disposer that removes only this callback. Like
+     * {@link setBeforeModelCall}, the first gate installed while a run is in
+     * flight takes effect on the next run.
+     */
+    addBeforeModelCall(fn: AgentBeforeModelCall): () => void;
+    /**
+     * Provide a source of non-interrupting "aside" messages (e.g. background-job
+     * completions, late LSP diagnostics) drained at each step boundary. Never
+     * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+     */
+    setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void;
+    emitExternalEvent(event: AgentEvent): void;
+    setSystemPrompt(v: string[] | string): void;
+    setModel(m: Model): void;
+    setThinkingLevel(l: Effort | undefined): void;
+    setDisableReasoning(disabled: boolean): 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[]): void;
+    replaceQueues(steering: AgentMessage[], followUp: AgentMessage[]): void;
+    appendMessage(m: AgentMessage): void;
+    popMessage(): AgentMessage | undefined;
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     * Delivered after current tool execution, skips remaining tools.
+     */
+    steer(m: AgentMessage): 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.
+     */
+    followUp(m: AgentMessage): void;
+    clearSteeringQueue(): void;
+    clearFollowUpQueue(): void;
+    /**
+     * Drop tool-directive state retained across a gate-stopped run: the
+     * deferred hard choice and the soft-requirement lifecycle.
+     */
+    clearDeferredToolDirectives(): void;
+    clearAllQueues(): void;
+    hasQueuedMessages(): boolean;
+    /** Non-consuming view of the pending steering queue (insertion order, newest
+     *  last). The session layer derives its queued-message display/count from
+     *  this live view instead of a mirror, so the agent-core queue stays the
+     *  single source of truth. */
+    peekSteeringQueue(): readonly AgentMessage[];
+    /** Non-consuming view of the pending follow-up queue. See
+     *  {@link peekSteeringQueue}. */
+    peekFollowUpQueue(): readonly AgentMessage[];
+    get isAborting(): boolean;
+    /**
+     * Remove and return the last steering message from the queue (LIFO).
+     * Used by dequeue keybinding.
+     */
+    popLastSteer(): AgentMessage | undefined;
+    /**
+     * Remove and return the last follow-up message from the queue (LIFO).
+     * Used by dequeue keybinding.
+     */
+    popLastFollowUp(): AgentMessage | undefined;
+    clearMessages(): void;
+    abort(reason?: unknown): void;
+    waitForIdle(): Promise<void>;
+    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(signal?: AbortSignal): Promise<void>;
+}