@sema-ai/core 1.275.1

package/dist/engine/loop/types.d.ts

@@ -0,0 +1,609 @@
+import type { Static, TSchema } from "typebox";
+import type { AssistantMessage, AssistantMessageEvent, DocumentContent, ImageContent, Message, Model, SimpleStreamOptions, StreamFn as LlmStreamFn, TextContent, Tool, ToolResultMessage } from "../llm/index.js";
+/**
+ * Stream function used by the agent loop.
+ *
+ * Contract:
+ * - Must not throw or return a rejected promise for request/model/runtime failures.
+ * - Must return an AssistantMessageEventStream.
+ * - Failures must be encoded in the returned stream via protocol events and a
+ *   final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
+ */
+export type StreamFn = LlmStreamFn;
+/**
+ * Configuration for how tool calls from a single assistant message are executed.
+ *
+ * - "sequential": each tool call is prepared, executed, and finalized before the next one starts.
+ * - "parallel": tool calls are prepared sequentially, then allowed tools execute concurrently.
+ *   `tool_execution_end` is emitted in tool completion order after each tool is finalized,
+ *   while tool-result message artifacts are emitted later in assistant source order.
+ */
+export type ToolExecutionMode = "sequential" | "parallel";
+/**
+ * Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
+ *
+ * - "all": drain and inject every queued message at that point.
+ * - "one-at-a-time": drain and inject only the oldest queued message, leaving the rest queued for later drain points.
+ */
+export type QueueMode = "all" | "one-at-a-time";
+/** A single tool call content block emitted by an assistant message. */
+export type AgentToolCall = Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>;
+/**
+ * Result returned from `beforeToolCall`.
+ *
+ * Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.
+ * `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.
+ *
+ * Returning `{ updatedInput }` (without `block`) REWRITES the arguments the tool executes with — the
+ * loop replaces the validated args with `updatedInput` and **re-runs `validateToolArguments` on it**
+ * before execution, so a rewrite can never smuggle schema-invalid args into `tool.execute()`. This is
+ * the generic carrier the higher layer uses for arg redaction/clamping (design/37); the loop itself
+ * stays policy-agnostic. `block` wins over `updatedInput` if both are set.
+ *
+ * Keep in sync with the harness hook result `ToolCallResult` (harness/types.ts), which the harness's
+ * `beforeToolCall` callback returns verbatim.
+ */
+export interface BeforeToolCallResult {
+    block?: boolean;
+    reason?: string;
+    updatedInput?: unknown;
+}
+/**
+ * Partial override returned from `afterToolCall`.
+ *
+ * Merge semantics are field-by-field:
+ * - `content`: if provided, replaces the tool result content array in full
+ * - `details`: if provided, replaces the tool result details value in full
+ * - `isError`: if provided, replaces the tool result error flag
+ * - `terminate`: if provided, replaces the early-termination hint
+ *
+ * Omitted fields keep the original executed tool result values.
+ * There is no deep merge for `content` or `details`.
+ */
+export interface AfterToolCallResult {
+    content?: (TextContent | ImageContent | DocumentContent)[];
+    details?: unknown;
+    isError?: boolean;
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
+    terminate?: boolean;
+}
+/** Context passed to `beforeToolCall`. */
+export interface BeforeToolCallContext {
+    /** The assistant message that requested the tool call. */
+    assistantMessage: AssistantMessage;
+    /** The raw tool call block from `assistantMessage.content`. */
+    toolCall: AgentToolCall;
+    /** Validated tool arguments for the target tool schema. */
+    args: unknown;
+    /** Current agent context at the time the tool call is prepared. */
+    context: AgentContext;
+}
+/** Context passed to `afterToolCall`. */
+export interface AfterToolCallContext {
+    /** The assistant message that requested the tool call. */
+    assistantMessage: AssistantMessage;
+    /** The raw tool call block from `assistantMessage.content`. */
+    toolCall: AgentToolCall;
+    /** Validated tool arguments for the target tool schema. */
+    args: unknown;
+    /** The executed tool result before unknown `afterToolCall` overrides are applied. */
+    result: AgentToolResult<unknown>;
+    /** Whether the executed tool result is currently treated as an error. */
+    isError: boolean;
+    /** Current agent context at the time the tool call is finalized. */
+    context: AgentContext;
+}
+/** Context passed to `shouldStopAfterTurn`. */
+export interface ShouldStopAfterTurnContext {
+    /** The assistant message that completed the turn. */
+    message: AssistantMessage;
+    /** Tool result messages passed to the preceding `turn_end` event. */
+    toolResults: ToolResultMessage[];
+    /** Current agent context after the turn's assistant message and tool results have been appended. */
+    context: AgentContext;
+    /** Messages that this loop invocation will return if it exits at this point. Prompt runs include the initial prompt messages; continuation runs do not include pre-existing context messages. */
+    newMessages: AgentMessage[];
+}
+/** Replacement runtime state used by the agent loop before starting another provider request. */
+export interface AgentLoopTurnUpdate {
+    /** Context for the next provider request. */
+    context?: AgentContext;
+    /** Model for the next provider request. */
+    model?: Model;
+    /** Thinking level for the next provider request. */
+    thinkingLevel?: ThinkingLevel;
+}
+export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {
+}
+/**
+ * Prompt-too-long recovery seam (design/118 ④b, the CC reactive-compact chain adapted to sema's
+ * "brain outside" architecture). The LOOP owns the retry transition; the CALLER owns the policy —
+ * `recover` typically compacts/trims the transcript (the harness/runner wires it to the engine
+ * compaction machinery). Retries happen INSIDE the turn (no extra `turn_start`); the failed
+ * assistant is dropped from the retry context and never enters the run's returned messages.
+ */
+export interface LoopPromptTooLongRecovery {
+    /**
+     * Produce a replacement transcript to retry the provider request with (attempt starts at 1).
+     * Return undefined to give up — the loop then surfaces the original error unchanged.
+     * Contract: must not throw or reject.
+     */
+    recover: (messages: AgentMessage[], attempt: number) => Promise<AgentMessage[] | undefined>;
+    /** Override the prompt-too-long classifier. Default: a conservative provider-message pattern. */
+    detect?: (message: AssistantMessage) => boolean;
+    /** Max recovery retries per turn. Default: 2. */
+    maxRetries?: number;
+    /**
+     * M1 (docs/PARITY-CONTEXT-TRANSACTIONS-2026-07-10 §4): withhold the failed assistant's
+     * message_start/message_end stream events while a recovery attempt is pending — CC 198 holds
+     * these errors inside its stream decoder (`claude-cli-2.1.198.pretty.js:473371-473374`) and only
+     * leaks them once recovery's outcome is known. Recovery succeeded ⇒ the failure stays invisible
+     * to event consumers; failed/declined ⇒ the events leak at that point (terminal truth unchanged).
+     * Default true (CC-aligned). `false` restores the pre-M1 live leak of the interim error.
+     */
+    withholdErrorEvents?: boolean;
+}
+/**
+ * Truncated-output auto-continue (design/118 ④b, the CC max_output_tokens recovery). When a turn
+ * stops with `stopReason: "length"` and produced NO tool calls, the loop injects a synthetic
+ * continue nudge (a `custom` message, `display: false`) and runs another turn, up to `maxContinues`
+ * CONSECUTIVE times (the counter resets on any non-length turn). Absent ⇒ OFF (a "length" answer
+ * ends the run — the pre-④b behavior).
+ */
+export interface LoopTruncatedOutputRecovery {
+    /** Max consecutive auto-continues. Default: 3. */
+    maxContinues?: number;
+}
+/**
+ * Malformed-tool-use retry (design/119 S2, CC 2.1.198 :473745-473785). A turn that stops with
+ * `toolUse` but carries ZERO parseable tool calls (the brain dropped truncated/invalid ones) used to
+ * end the run silently mid-task. When enabled, inject a synthetic retry nudge and run another turn,
+ * up to `maxRetries` per run (CC: once). Absent ⇒ OFF (pre-S2 behavior).
+ */
+export interface LoopMalformedToolUseRecovery {
+    /** Max retries per run. Default: 1. */
+    maxRetries?: number;
+}
+/**
+ * Thinking-only retry (design/119 S2, CC 2.1.198 :473786-473825 — the adaptive-thinking era
+ * companion). A turn that stops normally with thinking block(s) but NO visible text and NO tool
+ * calls used to end the run as a silent empty success. When enabled, inject a "respond with visible
+ * output" nudge and run another turn, up to `maxRetries` per run (CC: once). Absent ⇒ OFF.
+ */
+export interface LoopThinkingOnlyRecovery {
+    /** Max retries per run. Default: 1. */
+    maxRetries?: number;
+}
+/** Recovery chains the loop can drive (design/118 ④b + design/119 S2). All absent ⇒ the zero-recovery loop. */
+export interface LoopRecoveryOptions {
+    promptTooLong?: LoopPromptTooLongRecovery;
+    truncatedOutput?: LoopTruncatedOutputRecovery;
+    malformedToolUse?: LoopMalformedToolUseRecovery;
+    thinkingOnly?: LoopThinkingOnlyRecovery;
+    /** TB 尸检 T1-4: a degenerate-repetition CUTOFF turn (the brain cancelled the stream and stamped the
+     *  turn errored) gets a bounded "take a different approach" continue instead of ending the run — the
+     *  salvaged prefix is real work, and one bad sampling run shouldn't void it. `detect` is caller-injected
+     *  (core owns the brain's DEGENERATE_MESSAGE constant; the loop stays brain-agnostic). Consecutive cap
+     *  `maxContinues` (default 2); a second consecutive degeneration falls through to the normal error
+     *  terminal (assemble → `output.degenerate` + salvagedOutput, unchanged). */
+    degenerateOutput?: {
+        detect: (message: AssistantMessage) => boolean;
+        maxContinues?: number;
+    };
+    /** design/130 P2b: a WALLTIME-CUTOFF turn (the brain cancelled the stream at the soft per-call
+     *  deadline and stamped the turn errored with the walltime sentinel) gets a bounded write-out
+     *  continue — the salvaged prefix is real work, and the remaining cushion fits one short final
+     *  turn. `detect` is caller-injected (core owns the brain's WALLTIME_CUTOFF_MESSAGE constant; the
+     *  loop stays brain-agnostic). `maxContinues` (default 1) bounds recoveries for the WHOLE run —
+     *  deliberately NOT reset on success (the deadline only gets nearer; a second cutoff falls through
+     *  to the error terminal, which the assembler maps to timeout + salvagedOutput). */
+    walltimeCutoff?: {
+        detect: (message: AssistantMessage) => boolean;
+        maxContinues?: number;
+    };
+}
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    model: Model;
+    /** Error-recovery chains (design/118 ④b). Absent ⇒ no recovery (errors end the run as before). */
+    recovery?: LoopRecoveryOptions;
+    /**
+     * design/130 P1: per-CALL dynamic output-token cap, evaluated immediately before EACH provider
+     * call (the static `maxTokens` from SimpleStreamOptions is snapshotted once per run — this seam
+     * exists so a wall-clock-aware host can shrink individual calls as the budget drains). A
+     * `number` return overrides `maxTokens` for that call only; `undefined` leaves the static chain
+     * untouched. The provider must be cheap and side-effect-light: it runs on the hot path.
+     */
+    maxTokensPerCall?: () => number | undefined;
+    /**
+     * design/130 P2b: per-CALL soft wall-clock deadline (absolute ms epoch), evaluated immediately
+     * before EACH provider call and passed to the provider as `StreamOptions.callDeadlineMs` — a
+     * brain that observes the wall clock crossing it cuts the stream (salvaging the prefix) instead
+     * of riding into the runner's hard abort. `undefined` leaves the call unbounded (only the hard
+     * abort applies). Must be cheap: it runs on the hot path. (Named like `maxTokensPerCall`: the
+     * static `callDeadlineMs` NUMBER on StreamOptions is the per-call wire field this provides.)
+     */
+    callDeadlineMsPerCall?: () => number | undefined;
+    /**
+     * design/120 P1: concurrency cap inside a parallel tool batch. Default 10 (CC 198's production
+     * default — its knob is the CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY env; sema takes config).
+     */
+    maxToolConcurrency?: number;
+    /**
+     * design/120 P2: in-stream tool execution (CC StreamingToolExecutor, admission narrowed).
+     * When true, a concurrency-safe tool call whose arguments completed mid-stream (`toolcall_end`)
+     * starts executing while the model is still streaming, instead of waiting for the full response.
+     *
+     * Default: OFF (undefined) — behavior is exactly the P1 partitioned batch pipeline.
+     *
+     * Setting this true is the HOST'S PROMISE that no `beforeToolCall` gate on this run can durably
+     * suspend (mint a checkpoint + abort): in-stream calls still run the full prepare chain (defense
+     * in depth — block/updatedInput work as normal), but a mid-stream durable suspend has no stable
+     * leaf to hang its checkpoint on. The harness wires this only when no `tool_call` hook handler
+     * is registered (snapshot per turn); registering a suspending handler mid-run after opting in is
+     * a host contract violation (undefined behavior). Admission per call additionally requires:
+     * `toolExecution !== "sequential"`, the tool's `executionMode !== "sequential"`, the source-order
+     * barrier (once any call bounces to the batch pipeline, every later call bounces too — the CC
+     * processQueue FIFO-break equivalent), and in-flight < `maxToolConcurrency`.
+     */
+    streamingToolExecution?: boolean;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     *
+     * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
+     * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
+     * status messages) should be filtered out.
+     *
+     * Contract: must not throw or reject. Return a safe fallback value instead.
+     * Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     *
+     * @example
+     * ```typescript
+     * convertToLlm: (messages) => messages.flatMap(m => {
+     *   if (m.role === "custom") {
+     *     // Convert custom message to user message
+     *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
+     *   }
+     *   if (m.role === "notification") {
+     *     // Filter out UI-only messages
+     *     return [];
+     *   }
+     *   // Pass through standard LLM messages
+     *   return [m];
+     * })
+     * ```
+     */
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to the context before `convertToLlm`.
+     *
+     * Use this for operations that work at the AgentMessage level:
+     * - Context window management (pruning old messages)
+     * - Injecting context from external sources
+     *
+     * Contract: must not throw or reject. Return the original messages or another
+     * safe fallback value instead.
+     *
+     * @example
+     * ```typescript
+     * transformContext: async (messages) => {
+     *   if (estimateTokens(messages) > MAX_TOKENS) {
+     *     return pruneOldMessages(messages);
+     *   }
+     *   return messages;
+     * }
+     * ```
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     *
+     * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
+     * during long-running tool execution phases.
+     *
+     * Contract: must not throw or reject. Return undefined when no key is available.
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Called after each turn fully completes and `turn_end` has been emitted.
+     *
+     * If it returns true, the loop emits `agent_end` and exits before polling steering or follow-up queues,
+     * without starting another LLM call. The current assistant response and any tool executions finish normally.
+     *
+     * Use this to request a graceful stop after the current turn, e.g. before context gets too full.
+     *
+     * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     */
+    shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
+    /**
+     * Called after `turn_end` and before the loop decides whether another provider request should start.
+     * Return replacement context/model/thinking state to affect the next turn in this run.
+     * Return undefined to keep using the current context/config.
+     */
+    prepareNextTurn?: (context: PrepareNextTurnContext) => AgentLoopTurnUpdate | undefined | Promise<AgentLoopTurnUpdate | undefined>;
+    /**
+     * Returns steering messages to inject into the conversation mid-run.
+     *
+     * Called after the current assistant turn finishes executing its tool calls, unless `shouldStopAfterTurn` exits first.
+     * If messages are returned, they are added to the context before the next LLM call.
+     * Tool calls from the current assistant message are not skipped.
+     *
+     * Use this for "steering" the agent while it's working.
+     *
+     * Contract: must not throw or reject. Return [] when no steering messages are available.
+     */
+    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Returns follow-up messages to process after the agent would otherwise stop.
+     *
+     * Called when the agent has no more tool calls and no steering messages.
+     * If messages are returned, they're added to the context and the agent
+     * continues with another turn.
+     *
+     * Use this for follow-up messages that should wait until the agent finishes.
+     *
+     * Contract: must not throw or reject. Return [] when no follow-up messages are available.
+     */
+    getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Tool execution mode.
+     * - "sequential": execute tool calls one by one
+     * - "parallel": preflight tool calls sequentially, then execute allowed tools concurrently;
+     *   emit `tool_execution_end` in tool completion order after each tool is finalized,
+     *   then emit tool-result message artifacts later in assistant source order
+     *
+     * Default: "parallel"
+     */
+    toolExecution?: ToolExecutionMode;
+    /**
+     * Called before a tool is executed, after arguments have been validated.
+     *
+     * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.
+     * The hook receives the agent abort signal and is responsible for honoring it.
+     */
+    beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+    /**
+     * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
+     *
+     * Return an `AfterToolCallResult` to override parts of the executed tool result:
+     * - `content` replaces the full content array
+     * - `details` replaces the full details payload
+     * - `isError` replaces the error flag
+     * - `terminate` replaces the early-termination hint
+     *
+     * Any omitted fields keep their original values. No deep merge is performed.
+     * The hook receives the agent abort signal and is responsible for honoring it.
+     */
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+}
+/**
+ * Thinking/reasoning level for models that support it.
+ * Note: "xhigh" is only supported by selected model families. Use model thinking-level metadata
+ * from openclaw/plugin-sdk/llm to detect support for a concrete model.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface BashExecutionMessage {
+    /** Harness role for shell command transcripts. */
+    role: "bashExecution";
+    /** Command line that was executed. */
+    command: string;
+    /** Captured command output, usually already truncated for context. */
+    output: string;
+    /** Process exit code when the command reached process exit. */
+    exitCode: number | undefined;
+    /** True when the command was interrupted before normal completion. */
+    cancelled: boolean;
+    /** True when output was shortened for transcript/context storage. */
+    truncated: boolean;
+    /** Optional path containing the complete output when truncation occurred. */
+    fullOutputPath?: string;
+    /** Millisecond timestamp for transcript ordering. */
+    timestamp: number;
+    /** Exclude this command transcript from model context while keeping it in session history. */
+    excludeFromContext?: boolean;
+}
+export interface CustomMessage<T = unknown> {
+    /** Harness role for application-defined transcript content. */
+    role: "custom";
+    /** Application-defined discriminator for rendering or handling this message. */
+    customType: string;
+    /** Content replayed into model context when this message is included. */
+    content: string | (TextContent | ImageContent)[];
+    /** Whether UI surfaces should display this message. */
+    display: boolean;
+    /** Optional application-specific metadata. */
+    details?: T;
+    /** Millisecond timestamp for transcript ordering. */
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    /** Harness role for summaries that replace compacted transcript history. */
+    role: "compactionSummary";
+    /** Summary text inserted back into model context. */
+    summary: string;
+    /** Estimated context tokens before compaction. */
+    tokensBefore: number;
+    /** Timestamp may be numeric in memory or string when loaded from older persisted rows. */
+    timestamp: number | string;
+    /** Optional estimated context tokens after compaction. */
+    tokensAfter?: number;
+    /** Optional first retained entry id from the compaction range. */
+    firstKeptEntryId?: string;
+    /** Optional implementation-specific compaction metadata. */
+    details?: unknown;
+}
+/**
+ * Extensible interface for custom app and harness messages.
+ * Apps can extend via declaration merging.
+ */
+export interface CustomAgentMessages {
+    bashExecution: BashExecutionMessage;
+    custom: CustomMessage;
+    compactionSummary: CompactionSummaryMessage;
+}
+/**
+ * AgentMessage: Union of LLM messages + custom messages.
+ * This abstraction allows apps to add custom message types while maintaining
+ * type safety and compatibility with the base LLM messages.
+ */
+export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+/**
+ * Public agent state.
+ *
+ * `tools` and `messages` use accessor properties so implementations can copy
+ * assigned arrays before storing them.
+ */
+export interface AgentState {
+    /** System prompt sent with each model request. */
+    systemPrompt: string;
+    /** Active model used for future turns. */
+    model: Model;
+    /** Requested reasoning level for future turns. */
+    thinkingLevel: ThinkingLevel;
+    /** Available tools. Assigning a new array copies the top-level array. */
+    set tools(tools: AgentTool[]);
+    get tools(): AgentTool[];
+    /** Conversation transcript. Assigning a new array copies the top-level array. */
+    set messages(messages: AgentMessage[]);
+    get messages(): AgentMessage[];
+    /**
+     * True while the agent is processing a prompt or continuation.
+     *
+     * This remains true until awaited `agent_end` listeners settle.
+     */
+    readonly isStreaming: boolean;
+    /** Partial assistant message for the current streamed response, if any. */
+    readonly streamingMessage?: AgentMessage;
+    /** Tool call ids currently executing. */
+    readonly pendingToolCalls: ReadonlySet<string>;
+    /** Error message from the most recent failed or aborted assistant turn, if any. */
+    readonly errorMessage?: string;
+}
+/** Channel-safe progress text emitted by a running tool. */
+export interface AgentToolProgress {
+    /** Public text suitable for user-facing progress surfaces. */
+    text: string;
+    /** Tool progress is rendered by channel progress UIs. */
+    visibility: "channel";
+    /** Progress text must not contain secrets, private args, or fetched content. */
+    privacy: "public";
+    /** Optional stable id for progress line replacement. */
+    id?: string;
+}
+/** Final or partial result produced by a tool. */
+export interface AgentToolResult<T> {
+    /** Text, image or document content returned to the model. */
+    content: (TextContent | ImageContent | DocumentContent)[];
+    /** Arbitrary structured details for logs or UI rendering. */
+    details: T;
+    /** Optional public progress hint for partial tool updates; never model content. */
+    progress?: AgentToolProgress;
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
+    terminate?: boolean;
+}
+/** Callback used by tools to stream partial execution updates. */
+export type AgentToolUpdateCallback<T = unknown> = (partialResult: AgentToolResult<T>) => void;
+/** Tool definition used by the agent runtime. */
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unknown> extends Tool<TParameters> {
+    /** VENDORED EDIT (design/115 P0): inherited from Tool; old wire names that dispatch to this canonical tool. */
+    aliases?: string[];
+    /** Human-readable label for UI display. */
+    label: string;
+    /**
+     * Optional compatibility shim for raw tool-call arguments before schema validation.
+     * Must return an object that matches `TParameters`.
+     */
+    prepareArguments?: (args: unknown) => Static<TParameters>;
+    /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
+    execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+    /**
+     * Per-tool execution mode override.
+     * - "sequential": this tool must execute one at a time with other tool calls.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the tool is treated as NOT concurrency-safe unless its input-level
+     * `isConcurrencySafe` hook opts a call in (fail-closed; CC 2.1.206 TOOL_DEFAULTS parity).
+     */
+    executionMode?: ToolExecutionMode;
+    /**
+     * MCP server self-declared result-size threshold (CC 198 `_meta["anthropic/maxResultSizeChars"]`,
+     * pretty.js:320015/:320061 — consumer caps at 500K). Set by the MCP materializer when the server
+     * declares it; consulted by the offload mount in prepare-task. Absent on non-MCP tools.
+     */
+    mcpMaxResultSizeChars?: number;
+    /**
+     * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): INPUT-level concurrency refinement
+     * for a tool whose safety depends on its arguments — CC's only real consumer is
+     * Bash (a read-only command is safe to parallelize; a write command is not). Consulted by the
+     * partitioner for every tool WITHOUT an explicit `executionMode:"parallel"` (a statically-parallel
+     * tool needs no refinement); `true` = treat THIS CALL as concurrency-safe. A throw = false
+     * (fail-closed, CC same). The partitioner validates the call's args against the tool schema FIRST
+     * (schema-invalid ⇒ unsafe, CC 206 safeParse parity) and hands the hook the validated+coerced
+     * args — still treat defensively (a direct caller may pass raw args). Omitted ⇒ the static mode stands.
+     */
+    isConcurrencySafe?: (args: unknown) => boolean;
+}
+/** Context snapshot passed into the low-level agent loop. */
+export interface AgentContext {
+    /** System prompt included with the request. */
+    systemPrompt: string;
+    /** Transcript visible to the model. */
+    messages: AgentMessage[];
+    /** Tools available for this run. */
+    tools?: AgentTool[];
+}
+/**
+ * Events emitted by the Agent for UI updates.
+ *
+ * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
+ * listeners for that event are still part of run settlement. The agent becomes
+ * idle only after those listeners finish.
+ */
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+    entryId?: string;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    partialResult: unknown;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/engine/loop/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engine/loop/types.ts"],"names":[],"mappings":"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"}

package/dist/engine/loop/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/engine/loop/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engine/loop/types.ts"],"names":[],"mappings":""}

package/dist/engine/lsp/frame-decoder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LSP base-protocol framing over a byte stream (stdio) — `Content-Length: <n>\r\n\r\n<n bytes of JSON>`. A
+ * language server speaks JSON-RPC over stdin/stdout with THIS framing (the part a WebSocket transport skips,
+ * since each WS message is already one message). Ported 1:1 from service's unit-tested `lsp-frames` bridge
+ * decoder + CC's `StreamMessageReader`/`StreamMessageWriter` (vscode-jsonrpc) — hand-rolled here to keep core
+ * dependency-free (the framing is trivial; a native LSP-client dep is not worth it).
+ */
+/** Encode a JSON-RPC message body as an LSP base-protocol frame (header + payload) ready to write to stdin. */
+export declare function encodeFrame(json: string): Buffer;
+/**
+ * A stateful decoder: feed it stdout chunks, get back complete JSON payloads (0+ per chunk — a frame can span
+ * chunks, and a chunk can hold several). `maxBytes` caps the buffer so a server that never emits a delimiter
+ * (or a corrupt Content-Length) can't grow it unboundedly — on overflow the buffer is dropped (fail-safe).
+ */
+export declare function makeFrameDecoder(maxBytes?: number): (chunk: Buffer) => string[];
+//# sourceMappingURL=frame-decoder.d.ts.map

package/dist/engine/lsp/frame-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-decoder.d.ts","sourceRoot":"","sources":["../../../src/engine/lsp/frame-decoder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+GAA+G;AAC/G,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,SAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,CA+BzF"}