@ponythewhite/base-context-agent 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,512 @@
+import type { AssistantMessage, AssistantMessageEvent, ImageContent, Message, Model, ServiceTier, SimpleStreamOptions, streamSimple, TextContent, Tool, ToolResultMessage } from "@ponythewhite/base-context-ai";
+import type { Static, TSchema } from "typebox";
+/**
+ * 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 = (...args: Parameters<typeof streamSimple>) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;
+export interface AgentContextProjection {
+    messages: AgentMessage[];
+    /**
+     * Adopt this complete working set in the owning Agent and loop, not only for inference.
+     * It must include the current turn and pending tool closure. This is not a last-N tail.
+     * Omitted/false preserves the existing inference-only projection behavior.
+     */
+    adoptMessages?: boolean;
+    streamContext?: unknown;
+    release?: () => Promise<void>;
+}
+export type AgentContextBuildResult = void | AgentContextProjection;
+export type AgentOwnedStreamFn = (...args: [...Parameters<StreamFn>, streamContext?: unknown]) => ReturnType<StreamFn>;
+/**
+ * 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";
+/** A 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.
+ */
+export interface BeforeToolCallResult {
+    block?: boolean;
+    reason?: string;
+}
+/**
+ * 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)[];
+    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` after arguments are validated. */
+export interface BeforeToolCallContext {
+    /** Assistant message that requested the call. */
+    assistantMessage: AssistantMessage;
+    /** Raw tool-call block from `assistantMessage.content`. */
+    toolCall: AgentToolCall;
+    /** Validated arguments for the target tool schema. */
+    args: unknown;
+    /** Agent context when this call is prepared. */
+    context: AgentContext;
+}
+/** Context passed to `afterToolCall`. */
+export interface AfterToolCallContext {
+    /** Assistant message that requested the call. */
+    assistantMessage: AssistantMessage;
+    /** Raw tool-call block from `assistantMessage.content`. */
+    toolCall: AgentToolCall;
+    /** Validated arguments for the target tool schema. */
+    args: unknown;
+    /** Executed result before any `afterToolCall` overrides. */
+    result: AgentToolResult<any>;
+    /** Whether the executed result is currently treated as an error. */
+    isError: boolean;
+    /** Agent context when this call is finalized. */
+    context: AgentContext;
+}
+/** What is known about the actual invocation, independently of middleware result overrides. */
+export type ToolExecutionOutcome = "not_started" | "completed" | "failed" | "outcome_unknown";
+/** Immutable invocation admitted by the execution owner before the tool can run. */
+export interface ToolInvocation {
+    readonly executionId: string;
+    readonly sourceOrder: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** Snapshot before argument preparation, validation, or tool middleware. */
+    readonly originalInput: unknown;
+    /** Arguments reserved for this invocation, not a live middleware object. */
+    readonly executedInput: unknown;
+    readonly toolExecution: ToolExecutionMode;
+}
+/** @internal Per-invocation owner closure; never serialized or supplied by result metadata. */
+export interface BoundToolExecution {
+    run(execute: () => Promise<AgentToolResult<unknown>>): Promise<AgentToolResult<unknown>>;
+    finalize(exchange: FinalizedToolExchange, signal?: AbortSignal): void | Promise<void>;
+}
+/** Finalized source evidence; parallel exchanges retain assistant call order via sourceOrder. */
+export interface FinalizedToolExchange extends Omit<ToolInvocation, "executedInput"> {
+    /** Snapshot at invocation; absent when execution never started. */
+    readonly executedInput?: unknown;
+    /** An aborted wait does not establish whether an external effect stopped. */
+    readonly executionOutcome: ToolExecutionOutcome;
+    readonly cancellationRequested: boolean;
+    /** Final middleware result, also used for the tool-result message. */
+    readonly result: ToolResultMessage;
+}
+/** Limits on the complete invocation result, not the working context or observer queues. */
+export interface AgentOutputLimits {
+    maxMessages: number;
+    maxSourceBytes: number;
+}
+export interface AgentOutputRefusal extends AgentOutputLimits {
+    kind: "output_limit";
+    limit: "messages" | "source_bytes" | "value_encoding";
+}
+export interface AgentOutputPolicy {
+    limits: AgentOutputLimits;
+    /** Optional native update feed. Its synchronous refresh never revokes an ACK or throws a quota error. */
+    bindUpdates?(refresh: (message: AgentMessage) => boolean): () => void;
+    /** Close update admission and join the updates already accepted at this terminal boundary. */
+    settleUpdates?(): Promise<void>;
+    /** Copy one finalized value within the supplied JSON-byte budget; undefined means it does not fit. */
+    snapshot(message: AgentMessage, maxSourceBytes: number): {
+        message: AgentMessage;
+        sourceBytes: number;
+    } | undefined;
+}
+/** Context passed to `shouldStopAfterTurn` and both continuation callbacks. */
+export interface ShouldStopAfterTurnContext {
+    /** Assistant message that completed the turn. */
+    message: AssistantMessage;
+    /** Tool-result messages included in the preceding `turn_end` event. */
+    toolResults: ToolResultMessage[];
+    /** Context after appending the turn's assistant message and tool results. */
+    context: AgentContext;
+    /** Messages returned by this invocation; prompts include initial prompts, continuations exclude prior context. */
+    newMessages: AgentMessage[];
+}
+/** The finalized loop decision, not a guess from the rendered message tail. */
+export interface GetTurnOutcomeContext extends ShouldStopAfterTurnContext {
+    hasMoreToolCalls: boolean;
+}
+/** Control before queue polling; proceed keeps the ordinary loop policy. */
+export type AgentTurnOutcome = {
+    kind: "proceed" | "finish" | "checkpoint_then_continue" | "cancelled";
+};
+export type GetContinuationMessagesContext = ShouldStopAfterTurnContext;
+/** Runtime control at a natural turn boundary; message payload does not decide whether to restart. */
+export type AgentContinuationOutcome = {
+    kind: "continue";
+    messages: AgentMessage[];
+} | {
+    kind: "finish" | "wait_for_owned_work" | "cancelled";
+};
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    /** Opt-in bounded finalized results. Native sinks must join their message_end job. */
+    outputPolicy?: AgentOutputPolicy;
+    model: Model<any>;
+    /** Native owner barrier before transform/convert. Rejection stops context construction. */
+    beforeContextBuild?: () => Promise<AgentContextBuildResult>;
+    /** Internal state mirror for adopted working sets. Awaited and excluded from provider options. */
+    onContextAdopted?: (messages: AgentMessage[]) => void | Promise<void>;
+    /** Native owner recovery after an unsent request's projection has been released. */
+    recoverRequestPreparation?: (error: unknown, signal?: AbortSignal) => Promise<boolean>;
+    /** Retry a settled provider failure within this invocation and its output allowance. */
+    recoverProviderFailure?: (message: AssistantMessage, signal?: AbortSignal) => Promise<boolean>;
+    /** Copied native owner callback; excluded from configured/provider stream options. */
+    ownedStreamFn?: AgentOwnedStreamFn;
+    /**
+     * 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 the system prompt immediately before each LLM call. */
+    getSystemPrompt?: () => string;
+    /**
+     * 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>;
+    /** When present, this typed owner replaces shouldStopAfterTurn; it does not replace natural continuation. */
+    getTurnOutcome?: (context: GetTurnOutcomeContext, signal?: AbortSignal) => AgentTurnOutcome | Promise<AgentTurnOutcome>;
+    /**
+     * Called synchronously after a completed turn and before polling work for another turn.
+     * Return true to emit `agent_end` without starting another provider call. Work returned by
+     * an asynchronous poll owns that boundary; queue owners must suppress stale continuation
+     * results if their higher-level stop condition changes while generating them.
+     * The hook is never checked before the initial assistant turn.
+     */
+    shouldStopBeforeTurn?: () => boolean;
+    /**
+     * 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[]>;
+    /**
+     * Returns continuation messages when the agent would otherwise stop.
+     *
+     * Called after follow-up messages have been polled and none are available.
+     * If messages are returned, they're added to the context and the agent
+     * continues with another turn.
+     *
+     * Use this for host-owned continuation policies such as long-running goals.
+     * Explicit follow-up messages always take precedence over continuation messages.
+     *
+     * Contract: must not throw or reject. Return [] when no continuation should run.
+     */
+    getContinuationMessages?: (context: GetContinuationMessagesContext, signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Authoritative runtime continuation control, after steering and explicit follow-ups.
+     * When present, only this callback is called; getContinuationMessages is not polled.
+     * Only continue restarts this invocation. Waiting leaves future work with its existing owner.
+     */
+    getContinuationOutcome?: (context: GetContinuationMessagesContext, signal?: AbortSignal) => Promise<AgentContinuationOutcome>;
+    /**
+     * Tool execution mode. Defaults to `"parallel"`.
+     * Parallel mode preflights calls sequentially, executes allowed calls concurrently, emits
+     * `tool_execution_end` in completion order, then emits tool-result messages in assistant source order.
+     */
+    toolExecution?: ToolExecutionMode;
+    /**
+     * Awaited before invoking the tool. Rejection prevents execution and stops the loop.
+     * The owner records intent here; admission is not proof that an external effect occurred.
+     */
+    onToolInvocationStarting?: (invocation: ToolInvocation, signal: AbortSignal | undefined, tool: AgentTool, execute: AgentTool["execute"], assistantMessage?: AssistantMessage) => void | BoundToolExecution | Promise<void> | Promise<BoundToolExecution | undefined>;
+    /**
+     * Native execution owner, awaited after final middleware and before observer/result events.
+     * Persist source evidence here. Rejection stops publication; this is not an observer hook.
+     * Cancellation does not skip settlement. The owner must bound its own persistence work.
+     */
+    onToolExchangeFinalized?: (exchange: FinalizedToolExchange, signal?: AbortSignal, owner?: BoundToolExecution) => void | Promise<void>;
+    /**
+     * 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" and "max" are only supported by selected model families. Use model
+ * thinking-level metadata from @ponythewhite/base-context-ai to detect support for a concrete model.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Extensible interface for custom app messages.
+ * Apps can extend via declaration merging:
+ *
+ * @example
+ * ```typescript
+ * declare module "@mariozechner/agent" {
+ *   interface CustomAgentMessages {
+ *     artifact: ArtifactMessage;
+ *     notification: NotificationMessage;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomAgentMessages {
+}
+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;
+    /** Model used for future turns. */
+    model: Model<any>;
+    /** Requested reasoning level for future turns. */
+    thinkingLevel: ThinkingLevel;
+    /** Requested provider service tier for future turns. */
+    serviceTier: ServiceTier;
+    /** Available tools. Assigning a new array copies its top-level array. */
+    set tools(tools: AgentTool<any>[]);
+    get tools(): AgentTool<any>[];
+    /** Conversation transcript. Assigning a new array copies its top-level array. */
+    set messages(messages: AgentMessage[]);
+    get messages(): AgentMessage[];
+    /** True while processing a prompt or continuation, including awaited `agent_end` listeners. */
+    readonly isStreaming: boolean;
+    /** Partial assistant message for the active streamed response, if any. */
+    readonly streamingMessage?: AgentMessage;
+    /** Tool-call IDs currently executing. */
+    readonly pendingToolCalls: ReadonlySet<string>;
+    /** Error from the most recent failed or aborted assistant turn, if any. */
+    readonly errorMessage?: string;
+}
+/** Final or partial result produced by a tool. */
+export interface AgentToolResult<T> {
+    /** Text or image content returned to the model. */
+    content: (TextContent | ImageContent)[];
+    /** Structured details for logs or UI rendering. */
+    details: T;
+    /**
+     * 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 publish partial execution updates. */
+export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+/** Tool definition used by the agent runtime. */
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
+    /** 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 default execution mode applies.
+     */
+    executionMode?: ToolExecutionMode;
+}
+/** Context snapshot passed to the low-level agent loop and tool hooks. */
+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<any>[];
+}
+/**
+ * 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 = 
+/** Starts and ends one agent run; `agent_end` carries all messages produced by that run. */
+{
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+    refusal?: never;
+} | {
+    type: "agent_end";
+    refusal: AgentOutputRefusal;
+    messages?: never;
+}
+/** One assistant response and its resulting tool calls. */
+ | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+    /** Always populated by native execution; historical observer events may omit it. */
+    toolExecution?: ToolExecutionMode;
+    /** Settled calls in source order. Absent historical evidence is not reconstructed. */
+    exchanges?: readonly FinalizedToolExchange[];
+}
+/** Lifecycle events for user, assistant, and tool-result messages. */
+ | {
+    type: "message_start";
+    message: AgentMessage;
+}
+/** Only emitted for assistant messages during streaming. */
+ | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+}
+/** Tool execution events; parallel calls may end in completion rather than source order. */
+ | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+    partialResult: any;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError: boolean;
+    /** Always populated by native execution; absent for older observer events. */
+    exchange?: FinalizedToolExchange;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tImageContent,\n\tMessage,\n\tModel,\n\tServiceTier,\n\tSimpleStreamOptions,\n\tstreamSimple,\n\tTextContent,\n\tTool,\n\tToolResultMessage,\n} from \"@ponythewhite/base-context-ai\";\nimport type { Static, TSchema } from \"typebox\";\n\n/**\n * Stream function used by the agent loop.\n *\n * Contract:\n * - Must not throw or return a rejected promise for request/model/runtime failures.\n * - Must return an AssistantMessageEventStream.\n * - Failures must be encoded in the returned stream via protocol events and a\n *   final AssistantMessage with stopReason \"error\" or \"aborted\" and errorMessage.\n */\nexport type StreamFn = (\n\t...args: Parameters<typeof streamSimple>\n) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;\n\nexport interface AgentContextProjection {\n\tmessages: AgentMessage[];\n\t/**\n\t * Adopt this complete working set in the owning Agent and loop, not only for inference.\n\t * It must include the current turn and pending tool closure. This is not a last-N tail.\n\t * Omitted/false preserves the existing inference-only projection behavior.\n\t */\n\tadoptMessages?: boolean;\n\tstreamContext?: unknown;\n\trelease?: () => Promise<void>;\n}\n\n// biome-ignore lint/suspicious/noConfusingVoidType: this return contract accepts existing Promise<void> context barriers.\nexport type AgentContextBuildResult = void | AgentContextProjection;\n\nexport type AgentOwnedStreamFn = (...args: [...Parameters<StreamFn>, streamContext?: unknown]) => ReturnType<StreamFn>;\n\n/**\n * Configuration for how tool calls from a single assistant message are executed.\n *\n * - \"sequential\": each tool call is prepared, executed, and finalized before the next one starts.\n * - \"parallel\": tool calls are prepared sequentially, then allowed tools execute concurrently.\n *   `tool_execution_end` is emitted in tool completion order after each tool is finalized,\n *   while tool-result message artifacts are emitted later in assistant source order.\n */\nexport type ToolExecutionMode = \"sequential\" | \"parallel\";\n\n/** A tool-call content block emitted by an assistant message. */\nexport type AgentToolCall = Extract<AssistantMessage[\"content\"][number], { type: \"toolCall\" }>;\n\n/**\n * Result returned from `beforeToolCall`.\n *\n * Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.\n * `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.\n */\nexport interface BeforeToolCallResult {\n\tblock?: boolean;\n\treason?: string;\n}\n\n/**\n * Partial override returned from `afterToolCall`.\n *\n * Merge semantics are field-by-field:\n * - `content`: if provided, replaces the tool result content array in full\n * - `details`: if provided, replaces the tool result details value in full\n * - `isError`: if provided, replaces the tool result error flag\n * - `terminate`: if provided, replaces the early-termination hint\n *\n * Omitted fields keep the original executed tool result values.\n * There is no deep merge for `content` or `details`.\n */\nexport interface AfterToolCallResult {\n\tcontent?: (TextContent | ImageContent)[];\n\tdetails?: unknown;\n\tisError?: boolean;\n\t/**\n\t * Hint that the agent should stop after the current tool batch.\n\t * Early termination only happens when every finalized tool result in the batch sets this to true.\n\t */\n\tterminate?: boolean;\n}\n\n/** Context passed to `beforeToolCall` after arguments are validated. */\nexport interface BeforeToolCallContext {\n\t/** Assistant message that requested the call. */\n\tassistantMessage: AssistantMessage;\n\t/** Raw tool-call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated arguments for the target tool schema. */\n\targs: unknown;\n\t/** Agent context when this call is prepared. */\n\tcontext: AgentContext;\n}\n\n/** Context passed to `afterToolCall`. */\nexport interface AfterToolCallContext {\n\t/** Assistant message that requested the call. */\n\tassistantMessage: AssistantMessage;\n\t/** Raw tool-call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated arguments for the target tool schema. */\n\targs: unknown;\n\t/** Executed result before any `afterToolCall` overrides. */\n\tresult: AgentToolResult<any>;\n\t/** Whether the executed result is currently treated as an error. */\n\tisError: boolean;\n\t/** Agent context when this call is finalized. */\n\tcontext: AgentContext;\n}\n\n/** What is known about the actual invocation, independently of middleware result overrides. */\nexport type ToolExecutionOutcome = \"not_started\" | \"completed\" | \"failed\" | \"outcome_unknown\";\n\n/** Immutable invocation admitted by the execution owner before the tool can run. */\nexport interface ToolInvocation {\n\treadonly executionId: string;\n\treadonly sourceOrder: number;\n\treadonly toolCallId: string;\n\treadonly toolName: string;\n\t/** Snapshot before argument preparation, validation, or tool middleware. */\n\treadonly originalInput: unknown;\n\t/** Arguments reserved for this invocation, not a live middleware object. */\n\treadonly executedInput: unknown;\n\treadonly toolExecution: ToolExecutionMode;\n}\n\n/** @internal Per-invocation owner closure; never serialized or supplied by result metadata. */\nexport interface BoundToolExecution {\n\trun(execute: () => Promise<AgentToolResult<unknown>>): Promise<AgentToolResult<unknown>>;\n\tfinalize(exchange: FinalizedToolExchange, signal?: AbortSignal): void | Promise<void>;\n}\n\n/** Finalized source evidence; parallel exchanges retain assistant call order via sourceOrder. */\nexport interface FinalizedToolExchange extends Omit<ToolInvocation, \"executedInput\"> {\n\t/** Snapshot at invocation; absent when execution never started. */\n\treadonly executedInput?: unknown;\n\t/** An aborted wait does not establish whether an external effect stopped. */\n\treadonly executionOutcome: ToolExecutionOutcome;\n\treadonly cancellationRequested: boolean;\n\t/** Final middleware result, also used for the tool-result message. */\n\treadonly result: ToolResultMessage;\n}\n\n/** Limits on the complete invocation result, not the working context or observer queues. */\nexport interface AgentOutputLimits {\n\tmaxMessages: number;\n\tmaxSourceBytes: number;\n}\n\nexport interface AgentOutputRefusal extends AgentOutputLimits {\n\tkind: \"output_limit\";\n\tlimit: \"messages\" | \"source_bytes\" | \"value_encoding\";\n}\n\nexport interface AgentOutputPolicy {\n\tlimits: AgentOutputLimits;\n\t/** Optional native update feed. Its synchronous refresh never revokes an ACK or throws a quota error. */\n\tbindUpdates?(refresh: (message: AgentMessage) => boolean): () => void;\n\t/** Close update admission and join the updates already accepted at this terminal boundary. */\n\tsettleUpdates?(): Promise<void>;\n\t/** Copy one finalized value within the supplied JSON-byte budget; undefined means it does not fit. */\n\tsnapshot(message: AgentMessage, maxSourceBytes: number): { message: AgentMessage; sourceBytes: number } | undefined;\n}\n\n/** Context passed to `shouldStopAfterTurn` and both continuation callbacks. */\nexport interface ShouldStopAfterTurnContext {\n\t/** Assistant message that completed the turn. */\n\tmessage: AssistantMessage;\n\t/** Tool-result messages included in the preceding `turn_end` event. */\n\ttoolResults: ToolResultMessage[];\n\t/** Context after appending the turn's assistant message and tool results. */\n\tcontext: AgentContext;\n\t/** Messages returned by this invocation; prompts include initial prompts, continuations exclude prior context. */\n\tnewMessages: AgentMessage[];\n}\n\n/** The finalized loop decision, not a guess from the rendered message tail. */\nexport interface GetTurnOutcomeContext extends ShouldStopAfterTurnContext {\n\thasMoreToolCalls: boolean;\n}\n\n/** Control before queue polling; proceed keeps the ordinary loop policy. */\nexport type AgentTurnOutcome = { kind: \"proceed\" | \"finish\" | \"checkpoint_then_continue\" | \"cancelled\" };\n\nexport type GetContinuationMessagesContext = ShouldStopAfterTurnContext;\n\n/** Runtime control at a natural turn boundary; message payload does not decide whether to restart. */\nexport type AgentContinuationOutcome =\n\t| { kind: \"continue\"; messages: AgentMessage[] }\n\t| { kind: \"finish\" | \"wait_for_owned_work\" | \"cancelled\" };\n\nexport interface AgentLoopConfig extends SimpleStreamOptions {\n\t/** Opt-in bounded finalized results. Native sinks must join their message_end job. */\n\toutputPolicy?: AgentOutputPolicy;\n\tmodel: Model<any>;\n\n\t/** Native owner barrier before transform/convert. Rejection stops context construction. */\n\tbeforeContextBuild?: () => Promise<AgentContextBuildResult>;\n\n\t/** Internal state mirror for adopted working sets. Awaited and excluded from provider options. */\n\tonContextAdopted?: (messages: AgentMessage[]) => void | Promise<void>;\n\n\t/** Native owner recovery after an unsent request's projection has been released. */\n\trecoverRequestPreparation?: (error: unknown, signal?: AbortSignal) => Promise<boolean>;\n\n\t/** Retry a settled provider failure within this invocation and its output allowance. */\n\trecoverProviderFailure?: (message: AssistantMessage, signal?: AbortSignal) => Promise<boolean>;\n\n\t/** Copied native owner callback; excluded from configured/provider stream options. */\n\townedStreamFn?: AgentOwnedStreamFn;\n\n\t/**\n\t * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.\n\t *\n\t * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage\n\t * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,\n\t * status messages) should be filtered out.\n\t *\n\t * Contract: must not throw or reject. Return a safe fallback value instead.\n\t * Throwing interrupts the low-level agent loop without producing a normal event sequence.\n\t *\n\t * @example\n\t * ```typescript\n\t * convertToLlm: (messages) => messages.flatMap(m => {\n\t *   if (m.role === \"custom\") {\n\t *     // Convert custom message to user message\n\t *     return [{ role: \"user\", content: m.content, timestamp: m.timestamp }];\n\t *   }\n\t *   if (m.role === \"notification\") {\n\t *     // Filter out UI-only messages\n\t *     return [];\n\t *   }\n\t *   // Pass through standard LLM messages\n\t *   return [m];\n\t * })\n\t * ```\n\t */\n\tconvertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;\n\n\t/**\n\t * Optional transform applied to the context before `convertToLlm`.\n\t *\n\t * Use this for operations that work at the AgentMessage level:\n\t * - Context window management (pruning old messages)\n\t * - Injecting context from external sources\n\t *\n\t * Contract: must not throw or reject. Return the original messages or another\n\t * safe fallback value instead.\n\t *\n\t * @example\n\t * ```typescript\n\t * transformContext: async (messages) => {\n\t *   if (estimateTokens(messages) > MAX_TOKENS) {\n\t *     return pruneOldMessages(messages);\n\t *   }\n\t *   return messages;\n\t * }\n\t * ```\n\t */\n\ttransformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;\n\n\t/** Resolves the system prompt immediately before each LLM call. */\n\tgetSystemPrompt?: () => string;\n\n\t/**\n\t * Resolves an API key dynamically for each LLM call.\n\t *\n\t * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire\n\t * during long-running tool execution phases.\n\t *\n\t * Contract: must not throw or reject. Return undefined when no key is available.\n\t */\n\tgetApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;\n\n\t/**\n\t * Called after each turn fully completes and `turn_end` has been emitted.\n\t *\n\t * If it returns true, the loop emits `agent_end` and exits before polling steering or follow-up queues,\n\t * without starting another LLM call. The current assistant response and any tool executions finish normally.\n\t *\n\t * Use this to request a graceful stop after the current turn, e.g. before context gets too full.\n\t *\n\t * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.\n\t */\n\tshouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;\n\n\t/** When present, this typed owner replaces shouldStopAfterTurn; it does not replace natural continuation. */\n\tgetTurnOutcome?: (\n\t\tcontext: GetTurnOutcomeContext,\n\t\tsignal?: AbortSignal,\n\t) => AgentTurnOutcome | Promise<AgentTurnOutcome>;\n\n\t/**\n\t * Called synchronously after a completed turn and before polling work for another turn.\n\t * Return true to emit `agent_end` without starting another provider call. Work returned by\n\t * an asynchronous poll owns that boundary; queue owners must suppress stale continuation\n\t * results if their higher-level stop condition changes while generating them.\n\t * The hook is never checked before the initial assistant turn.\n\t */\n\tshouldStopBeforeTurn?: () => boolean;\n\n\t/**\n\t * Returns steering messages to inject into the conversation mid-run.\n\t *\n\t * Called after the current assistant turn finishes executing its tool calls, unless `shouldStopAfterTurn` exits first.\n\t * If messages are returned, they are added to the context before the next LLM call.\n\t * Tool calls from the current assistant message are not skipped.\n\t *\n\t * Use this for \"steering\" the agent while it's working.\n\t *\n\t * Contract: must not throw or reject. Return [] when no steering messages are available.\n\t */\n\tgetSteeringMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Returns follow-up messages to process after the agent would otherwise stop.\n\t *\n\t * Called when the agent has no more tool calls and no steering messages.\n\t * If messages are returned, they're added to the context and the agent\n\t * continues with another turn.\n\t *\n\t * Use this for follow-up messages that should wait until the agent finishes.\n\t *\n\t * Contract: must not throw or reject. Return [] when no follow-up messages are available.\n\t */\n\tgetFollowUpMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Returns continuation messages when the agent would otherwise stop.\n\t *\n\t * Called after follow-up messages have been polled and none are available.\n\t * If messages are returned, they're added to the context and the agent\n\t * continues with another turn.\n\t *\n\t * Use this for host-owned continuation policies such as long-running goals.\n\t * Explicit follow-up messages always take precedence over continuation messages.\n\t *\n\t * Contract: must not throw or reject. Return [] when no continuation should run.\n\t */\n\tgetContinuationMessages?: (context: GetContinuationMessagesContext, signal?: AbortSignal) => Promise<AgentMessage[]>;\n\n\t/**\n\t * Authoritative runtime continuation control, after steering and explicit follow-ups.\n\t * When present, only this callback is called; getContinuationMessages is not polled.\n\t * Only continue restarts this invocation. Waiting leaves future work with its existing owner.\n\t */\n\tgetContinuationOutcome?: (\n\t\tcontext: GetContinuationMessagesContext,\n\t\tsignal?: AbortSignal,\n\t) => Promise<AgentContinuationOutcome>;\n\n\t/**\n\t * Tool execution mode. Defaults to `\"parallel\"`.\n\t * Parallel mode preflights calls sequentially, executes allowed calls concurrently, emits\n\t * `tool_execution_end` in completion order, then emits tool-result messages in assistant source order.\n\t */\n\ttoolExecution?: ToolExecutionMode;\n\n\t/**\n\t * Awaited before invoking the tool. Rejection prevents execution and stops the loop.\n\t * The owner records intent here; admission is not proof that an external effect occurred.\n\t */\n\tonToolInvocationStarting?: (\n\t\tinvocation: ToolInvocation,\n\t\tsignal: AbortSignal | undefined,\n\t\ttool: AgentTool,\n\t\texecute: AgentTool[\"execute\"],\n\t\tassistantMessage?: AssistantMessage,\n\t) => void | BoundToolExecution | Promise<void> | Promise<BoundToolExecution | undefined>;\n\n\t/**\n\t * Native execution owner, awaited after final middleware and before observer/result events.\n\t * Persist source evidence here. Rejection stops publication; this is not an observer hook.\n\t * Cancellation does not skip settlement. The owner must bound its own persistence work.\n\t */\n\tonToolExchangeFinalized?: (\n\t\texchange: FinalizedToolExchange,\n\t\tsignal?: AbortSignal,\n\t\towner?: BoundToolExecution,\n\t) => void | Promise<void>;\n\n\t/**\n\t * Called before a tool is executed, after arguments have been validated.\n\t *\n\t * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tbeforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;\n\n\t/**\n\t * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.\n\t *\n\t * Return an `AfterToolCallResult` to override parts of the executed tool result:\n\t * - `content` replaces the full content array\n\t * - `details` replaces the full details payload\n\t * - `isError` replaces the error flag\n\t * - `terminate` replaces the early-termination hint\n\t *\n\t * Any omitted fields keep their original values. No deep merge is performed.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tafterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" and \"max\" are only supported by selected model families. Use model\n * thinking-level metadata from @ponythewhite/base-context-ai to detect support for a concrete model.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n *   interface CustomAgentMessages {\n *     artifact: ArtifactMessage;\n *     notification: NotificationMessage;\n *   }\n * }\n * ```\n */\nexport interface CustomAgentMessages {}\n\nexport type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];\n\n/**\n * Public agent state.\n *\n * `tools` and `messages` use accessor properties so implementations can copy\n * assigned arrays before storing them.\n */\nexport interface AgentState {\n\t/** System prompt sent with each model request. */\n\tsystemPrompt: string;\n\t/** Model used for future turns. */\n\tmodel: Model<any>;\n\t/** Requested reasoning level for future turns. */\n\tthinkingLevel: ThinkingLevel;\n\t/** Requested provider service tier for future turns. */\n\tserviceTier: ServiceTier;\n\t/** Available tools. Assigning a new array copies its top-level array. */\n\tset tools(tools: AgentTool<any>[]);\n\tget tools(): AgentTool<any>[];\n\t/** Conversation transcript. Assigning a new array copies its top-level array. */\n\tset messages(messages: AgentMessage[]);\n\tget messages(): AgentMessage[];\n\t/** True while processing a prompt or continuation, including awaited `agent_end` listeners. */\n\treadonly isStreaming: boolean;\n\t/** Partial assistant message for the active streamed response, if any. */\n\treadonly streamingMessage?: AgentMessage;\n\t/** Tool-call IDs currently executing. */\n\treadonly pendingToolCalls: ReadonlySet<string>;\n\t/** Error from the most recent failed or aborted assistant turn, if any. */\n\treadonly errorMessage?: string;\n}\n\n/** Final or partial result produced by a tool. */\nexport interface AgentToolResult<T> {\n\t/** Text or image content returned to the model. */\n\tcontent: (TextContent | ImageContent)[];\n\t/** Structured details for logs or UI rendering. */\n\tdetails: T;\n\t/**\n\t * Hint that the agent should stop after the current tool batch.\n\t * Early termination only happens when every finalized tool result in the batch sets this to true.\n\t */\n\tterminate?: boolean;\n}\n\n/** Callback used by tools to publish partial execution updates. */\nexport type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;\n\n/** Tool definition used by the agent runtime. */\nexport interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {\n\t/** Human-readable label for UI display. */\n\tlabel: string;\n\t/**\n\t * Optional compatibility shim for raw tool-call arguments before schema validation.\n\t * Must return an object that matches `TParameters`.\n\t */\n\tprepareArguments?: (args: unknown) => Static<TParameters>;\n\t/** Execute the tool call. Throw on failure instead of encoding errors in `content`. */\n\texecute: (\n\t\ttoolCallId: string,\n\t\tparams: Static<TParameters>,\n\t\tsignal?: AbortSignal,\n\t\tonUpdate?: AgentToolUpdateCallback<TDetails>,\n\t) => Promise<AgentToolResult<TDetails>>;\n\t/**\n\t * Per-tool execution mode override.\n\t * - \"sequential\": this tool must execute one at a time with other tool calls.\n\t * - \"parallel\": this tool can execute concurrently with other tool calls.\n\t *\n\t * If omitted, the default execution mode applies.\n\t */\n\texecutionMode?: ToolExecutionMode;\n}\n\n/** Context snapshot passed to the low-level agent loop and tool hooks. */\nexport interface AgentContext {\n\t/** System prompt included with the request. */\n\tsystemPrompt: string;\n\t/** Transcript visible to the model. */\n\tmessages: AgentMessage[];\n\t/** Tools available for this run. */\n\ttools?: AgentTool<any>[];\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n *\n * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`\n * listeners for that event are still part of run settlement. The agent becomes\n * idle only after those listeners finish.\n */\nexport type AgentEvent =\n\t/** Starts and ends one agent run; `agent_end` carries all messages produced by that run. */\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AgentMessage[]; refusal?: never }\n\t| { type: \"agent_end\"; refusal: AgentOutputRefusal; messages?: never }\n\t/** One assistant response and its resulting tool calls. */\n\t| { type: \"turn_start\" }\n\t| {\n\t\t\ttype: \"turn_end\";\n\t\t\tmessage: AgentMessage;\n\t\t\ttoolResults: ToolResultMessage[];\n\t\t\t/** Always populated by native execution; historical observer events may omit it. */\n\t\t\ttoolExecution?: ToolExecutionMode;\n\t\t\t/** Settled calls in source order. Absent historical evidence is not reconstructed. */\n\t\t\texchanges?: readonly FinalizedToolExchange[];\n\t  }\n\t/** Lifecycle events for user, assistant, and tool-result messages. */\n\t| { type: \"message_start\"; message: AgentMessage }\n\t/** Only emitted for assistant messages during streaming. */\n\t| { type: \"message_update\"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AgentMessage }\n\t/** Tool execution events; parallel calls may end in completion rather than source order. */\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_update\"; toolCallId: string; toolName: string; args: any; partialResult: any }\n\t| {\n\t\t\ttype: \"tool_execution_end\";\n\t\t\ttoolCallId: string;\n\t\t\ttoolName: string;\n\t\t\tresult: any;\n\t\t\tisError: boolean;\n\t\t\t/** Always populated by native execution; absent for older observer events. */\n\t\t\texchange?: FinalizedToolExchange;\n\t  };\n"]}

package/dist/types.js

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

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tImageContent,\n\tMessage,\n\tModel,\n\tServiceTier,\n\tSimpleStreamOptions,\n\tstreamSimple,\n\tTextContent,\n\tTool,\n\tToolResultMessage,\n} from \"@ponythewhite/base-context-ai\";\nimport type { Static, TSchema } from \"typebox\";\n\n/**\n * Stream function used by the agent loop.\n *\n * Contract:\n * - Must not throw or return a rejected promise for request/model/runtime failures.\n * - Must return an AssistantMessageEventStream.\n * - Failures must be encoded in the returned stream via protocol events and a\n *   final AssistantMessage with stopReason \"error\" or \"aborted\" and errorMessage.\n */\nexport type StreamFn = (\n\t...args: Parameters<typeof streamSimple>\n) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;\n\nexport interface AgentContextProjection {\n\tmessages: AgentMessage[];\n\t/**\n\t * Adopt this complete working set in the owning Agent and loop, not only for inference.\n\t * It must include the current turn and pending tool closure. This is not a last-N tail.\n\t * Omitted/false preserves the existing inference-only projection behavior.\n\t */\n\tadoptMessages?: boolean;\n\tstreamContext?: unknown;\n\trelease?: () => Promise<void>;\n}\n\n// biome-ignore lint/suspicious/noConfusingVoidType: this return contract accepts existing Promise<void> context barriers.\nexport type AgentContextBuildResult = void | AgentContextProjection;\n\nexport type AgentOwnedStreamFn = (...args: [...Parameters<StreamFn>, streamContext?: unknown]) => ReturnType<StreamFn>;\n\n/**\n * Configuration for how tool calls from a single assistant message are executed.\n *\n * - \"sequential\": each tool call is prepared, executed, and finalized before the next one starts.\n * - \"parallel\": tool calls are prepared sequentially, then allowed tools execute concurrently.\n *   `tool_execution_end` is emitted in tool completion order after each tool is finalized,\n *   while tool-result message artifacts are emitted later in assistant source order.\n */\nexport type ToolExecutionMode = \"sequential\" | \"parallel\";\n\n/** A tool-call content block emitted by an assistant message. */\nexport type AgentToolCall = Extract<AssistantMessage[\"content\"][number], { type: \"toolCall\" }>;\n\n/**\n * Result returned from `beforeToolCall`.\n *\n * Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.\n * `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.\n */\nexport interface BeforeToolCallResult {\n\tblock?: boolean;\n\treason?: string;\n}\n\n/**\n * Partial override returned from `afterToolCall`.\n *\n * Merge semantics are field-by-field:\n * - `content`: if provided, replaces the tool result content array in full\n * - `details`: if provided, replaces the tool result details value in full\n * - `isError`: if provided, replaces the tool result error flag\n * - `terminate`: if provided, replaces the early-termination hint\n *\n * Omitted fields keep the original executed tool result values.\n * There is no deep merge for `content` or `details`.\n */\nexport interface AfterToolCallResult {\n\tcontent?: (TextContent | ImageContent)[];\n\tdetails?: unknown;\n\tisError?: boolean;\n\t/**\n\t * Hint that the agent should stop after the current tool batch.\n\t * Early termination only happens when every finalized tool result in the batch sets this to true.\n\t */\n\tterminate?: boolean;\n}\n\n/** Context passed to `beforeToolCall` after arguments are validated. */\nexport interface BeforeToolCallContext {\n\t/** Assistant message that requested the call. */\n\tassistantMessage: AssistantMessage;\n\t/** Raw tool-call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated arguments for the target tool schema. */\n\targs: unknown;\n\t/** Agent context when this call is prepared. */\n\tcontext: AgentContext;\n}\n\n/** Context passed to `afterToolCall`. */\nexport interface AfterToolCallContext {\n\t/** Assistant message that requested the call. */\n\tassistantMessage: AssistantMessage;\n\t/** Raw tool-call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated arguments for the target tool schema. */\n\targs: unknown;\n\t/** Executed result before any `afterToolCall` overrides. */\n\tresult: AgentToolResult<any>;\n\t/** Whether the executed result is currently treated as an error. */\n\tisError: boolean;\n\t/** Agent context when this call is finalized. */\n\tcontext: AgentContext;\n}\n\n/** What is known about the actual invocation, independently of middleware result overrides. */\nexport type ToolExecutionOutcome = \"not_started\" | \"completed\" | \"failed\" | \"outcome_unknown\";\n\n/** Immutable invocation admitted by the execution owner before the tool can run. */\nexport interface ToolInvocation {\n\treadonly executionId: string;\n\treadonly sourceOrder: number;\n\treadonly toolCallId: string;\n\treadonly toolName: string;\n\t/** Snapshot before argument preparation, validation, or tool middleware. */\n\treadonly originalInput: unknown;\n\t/** Arguments reserved for this invocation, not a live middleware object. */\n\treadonly executedInput: unknown;\n\treadonly toolExecution: ToolExecutionMode;\n}\n\n/** @internal Per-invocation owner closure; never serialized or supplied by result metadata. */\nexport interface BoundToolExecution {\n\trun(execute: () => Promise<AgentToolResult<unknown>>): Promise<AgentToolResult<unknown>>;\n\tfinalize(exchange: FinalizedToolExchange, signal?: AbortSignal): void | Promise<void>;\n}\n\n/** Finalized source evidence; parallel exchanges retain assistant call order via sourceOrder. */\nexport interface FinalizedToolExchange extends Omit<ToolInvocation, \"executedInput\"> {\n\t/** Snapshot at invocation; absent when execution never started. */\n\treadonly executedInput?: unknown;\n\t/** An aborted wait does not establish whether an external effect stopped. */\n\treadonly executionOutcome: ToolExecutionOutcome;\n\treadonly cancellationRequested: boolean;\n\t/** Final middleware result, also used for the tool-result message. */\n\treadonly result: ToolResultMessage;\n}\n\n/** Limits on the complete invocation result, not the working context or observer queues. */\nexport interface AgentOutputLimits {\n\tmaxMessages: number;\n\tmaxSourceBytes: number;\n}\n\nexport interface AgentOutputRefusal extends AgentOutputLimits {\n\tkind: \"output_limit\";\n\tlimit: \"messages\" | \"source_bytes\" | \"value_encoding\";\n}\n\nexport interface AgentOutputPolicy {\n\tlimits: AgentOutputLimits;\n\t/** Optional native update feed. Its synchronous refresh never revokes an ACK or throws a quota error. */\n\tbindUpdates?(refresh: (message: AgentMessage) => boolean): () => void;\n\t/** Close update admission and join the updates already accepted at this terminal boundary. */\n\tsettleUpdates?(): Promise<void>;\n\t/** Copy one finalized value within the supplied JSON-byte budget; undefined means it does not fit. */\n\tsnapshot(message: AgentMessage, maxSourceBytes: number): { message: AgentMessage; sourceBytes: number } | undefined;\n}\n\n/** Context passed to `shouldStopAfterTurn` and both continuation callbacks. */\nexport interface ShouldStopAfterTurnContext {\n\t/** Assistant message that completed the turn. */\n\tmessage: AssistantMessage;\n\t/** Tool-result messages included in the preceding `turn_end` event. */\n\ttoolResults: ToolResultMessage[];\n\t/** Context after appending the turn's assistant message and tool results. */\n\tcontext: AgentContext;\n\t/** Messages returned by this invocation; prompts include initial prompts, continuations exclude prior context. */\n\tnewMessages: AgentMessage[];\n}\n\n/** The finalized loop decision, not a guess from the rendered message tail. */\nexport interface GetTurnOutcomeContext extends ShouldStopAfterTurnContext {\n\thasMoreToolCalls: boolean;\n}\n\n/** Control before queue polling; proceed keeps the ordinary loop policy. */\nexport type AgentTurnOutcome = { kind: \"proceed\" | \"finish\" | \"checkpoint_then_continue\" | \"cancelled\" };\n\nexport type GetContinuationMessagesContext = ShouldStopAfterTurnContext;\n\n/** Runtime control at a natural turn boundary; message payload does not decide whether to restart. */\nexport type AgentContinuationOutcome =\n\t| { kind: \"continue\"; messages: AgentMessage[] }\n\t| { kind: \"finish\" | \"wait_for_owned_work\" | \"cancelled\" };\n\nexport interface AgentLoopConfig extends SimpleStreamOptions {\n\t/** Opt-in bounded finalized results. Native sinks must join their message_end job. */\n\toutputPolicy?: AgentOutputPolicy;\n\tmodel: Model<any>;\n\n\t/** Native owner barrier before transform/convert. Rejection stops context construction. */\n\tbeforeContextBuild?: () => Promise<AgentContextBuildResult>;\n\n\t/** Internal state mirror for adopted working sets. Awaited and excluded from provider options. */\n\tonContextAdopted?: (messages: AgentMessage[]) => void | Promise<void>;\n\n\t/** Native owner recovery after an unsent request's projection has been released. */\n\trecoverRequestPreparation?: (error: unknown, signal?: AbortSignal) => Promise<boolean>;\n\n\t/** Retry a settled provider failure within this invocation and its output allowance. */\n\trecoverProviderFailure?: (message: AssistantMessage, signal?: AbortSignal) => Promise<boolean>;\n\n\t/** Copied native owner callback; excluded from configured/provider stream options. */\n\townedStreamFn?: AgentOwnedStreamFn;\n\n\t/**\n\t * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.\n\t *\n\t * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage\n\t * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,\n\t * status messages) should be filtered out.\n\t *\n\t * Contract: must not throw or reject. Return a safe fallback value instead.\n\t * Throwing interrupts the low-level agent loop without producing a normal event sequence.\n\t *\n\t * @example\n\t * ```typescript\n\t * convertToLlm: (messages) => messages.flatMap(m => {\n\t *   if (m.role === \"custom\") {\n\t *     // Convert custom message to user message\n\t *     return [{ role: \"user\", content: m.content, timestamp: m.timestamp }];\n\t *   }\n\t *   if (m.role === \"notification\") {\n\t *     // Filter out UI-only messages\n\t *     return [];\n\t *   }\n\t *   // Pass through standard LLM messages\n\t *   return [m];\n\t * })\n\t * ```\n\t */\n\tconvertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;\n\n\t/**\n\t * Optional transform applied to the context before `convertToLlm`.\n\t *\n\t * Use this for operations that work at the AgentMessage level:\n\t * - Context window management (pruning old messages)\n\t * - Injecting context from external sources\n\t *\n\t * Contract: must not throw or reject. Return the original messages or another\n\t * safe fallback value instead.\n\t *\n\t * @example\n\t * ```typescript\n\t * transformContext: async (messages) => {\n\t *   if (estimateTokens(messages) > MAX_TOKENS) {\n\t *     return pruneOldMessages(messages);\n\t *   }\n\t *   return messages;\n\t * }\n\t * ```\n\t */\n\ttransformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;\n\n\t/** Resolves the system prompt immediately before each LLM call. */\n\tgetSystemPrompt?: () => string;\n\n\t/**\n\t * Resolves an API key dynamically for each LLM call.\n\t *\n\t * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire\n\t * during long-running tool execution phases.\n\t *\n\t * Contract: must not throw or reject. Return undefined when no key is available.\n\t */\n\tgetApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;\n\n\t/**\n\t * Called after each turn fully completes and `turn_end` has been emitted.\n\t *\n\t * If it returns true, the loop emits `agent_end` and exits before polling steering or follow-up queues,\n\t * without starting another LLM call. The current assistant response and any tool executions finish normally.\n\t *\n\t * Use this to request a graceful stop after the current turn, e.g. before context gets too full.\n\t *\n\t * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.\n\t */\n\tshouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;\n\n\t/** When present, this typed owner replaces shouldStopAfterTurn; it does not replace natural continuation. */\n\tgetTurnOutcome?: (\n\t\tcontext: GetTurnOutcomeContext,\n\t\tsignal?: AbortSignal,\n\t) => AgentTurnOutcome | Promise<AgentTurnOutcome>;\n\n\t/**\n\t * Called synchronously after a completed turn and before polling work for another turn.\n\t * Return true to emit `agent_end` without starting another provider call. Work returned by\n\t * an asynchronous poll owns that boundary; queue owners must suppress stale continuation\n\t * results if their higher-level stop condition changes while generating them.\n\t * The hook is never checked before the initial assistant turn.\n\t */\n\tshouldStopBeforeTurn?: () => boolean;\n\n\t/**\n\t * Returns steering messages to inject into the conversation mid-run.\n\t *\n\t * Called after the current assistant turn finishes executing its tool calls, unless `shouldStopAfterTurn` exits first.\n\t * If messages are returned, they are added to the context before the next LLM call.\n\t * Tool calls from the current assistant message are not skipped.\n\t *\n\t * Use this for \"steering\" the agent while it's working.\n\t *\n\t * Contract: must not throw or reject. Return [] when no steering messages are available.\n\t */\n\tgetSteeringMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Returns follow-up messages to process after the agent would otherwise stop.\n\t *\n\t * Called when the agent has no more tool calls and no steering messages.\n\t * If messages are returned, they're added to the context and the agent\n\t * continues with another turn.\n\t *\n\t * Use this for follow-up messages that should wait until the agent finishes.\n\t *\n\t * Contract: must not throw or reject. Return [] when no follow-up messages are available.\n\t */\n\tgetFollowUpMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Returns continuation messages when the agent would otherwise stop.\n\t *\n\t * Called after follow-up messages have been polled and none are available.\n\t * If messages are returned, they're added to the context and the agent\n\t * continues with another turn.\n\t *\n\t * Use this for host-owned continuation policies such as long-running goals.\n\t * Explicit follow-up messages always take precedence over continuation messages.\n\t *\n\t * Contract: must not throw or reject. Return [] when no continuation should run.\n\t */\n\tgetContinuationMessages?: (context: GetContinuationMessagesContext, signal?: AbortSignal) => Promise<AgentMessage[]>;\n\n\t/**\n\t * Authoritative runtime continuation control, after steering and explicit follow-ups.\n\t * When present, only this callback is called; getContinuationMessages is not polled.\n\t * Only continue restarts this invocation. Waiting leaves future work with its existing owner.\n\t */\n\tgetContinuationOutcome?: (\n\t\tcontext: GetContinuationMessagesContext,\n\t\tsignal?: AbortSignal,\n\t) => Promise<AgentContinuationOutcome>;\n\n\t/**\n\t * Tool execution mode. Defaults to `\"parallel\"`.\n\t * Parallel mode preflights calls sequentially, executes allowed calls concurrently, emits\n\t * `tool_execution_end` in completion order, then emits tool-result messages in assistant source order.\n\t */\n\ttoolExecution?: ToolExecutionMode;\n\n\t/**\n\t * Awaited before invoking the tool. Rejection prevents execution and stops the loop.\n\t * The owner records intent here; admission is not proof that an external effect occurred.\n\t */\n\tonToolInvocationStarting?: (\n\t\tinvocation: ToolInvocation,\n\t\tsignal: AbortSignal | undefined,\n\t\ttool: AgentTool,\n\t\texecute: AgentTool[\"execute\"],\n\t\tassistantMessage?: AssistantMessage,\n\t) => void | BoundToolExecution | Promise<void> | Promise<BoundToolExecution | undefined>;\n\n\t/**\n\t * Native execution owner, awaited after final middleware and before observer/result events.\n\t * Persist source evidence here. Rejection stops publication; this is not an observer hook.\n\t * Cancellation does not skip settlement. The owner must bound its own persistence work.\n\t */\n\tonToolExchangeFinalized?: (\n\t\texchange: FinalizedToolExchange,\n\t\tsignal?: AbortSignal,\n\t\towner?: BoundToolExecution,\n\t) => void | Promise<void>;\n\n\t/**\n\t * Called before a tool is executed, after arguments have been validated.\n\t *\n\t * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tbeforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;\n\n\t/**\n\t * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.\n\t *\n\t * Return an `AfterToolCallResult` to override parts of the executed tool result:\n\t * - `content` replaces the full content array\n\t * - `details` replaces the full details payload\n\t * - `isError` replaces the error flag\n\t * - `terminate` replaces the early-termination hint\n\t *\n\t * Any omitted fields keep their original values. No deep merge is performed.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tafterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" and \"max\" are only supported by selected model families. Use model\n * thinking-level metadata from @ponythewhite/base-context-ai to detect support for a concrete model.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n *   interface CustomAgentMessages {\n *     artifact: ArtifactMessage;\n *     notification: NotificationMessage;\n *   }\n * }\n * ```\n */\nexport interface CustomAgentMessages {}\n\nexport type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];\n\n/**\n * Public agent state.\n *\n * `tools` and `messages` use accessor properties so implementations can copy\n * assigned arrays before storing them.\n */\nexport interface AgentState {\n\t/** System prompt sent with each model request. */\n\tsystemPrompt: string;\n\t/** Model used for future turns. */\n\tmodel: Model<any>;\n\t/** Requested reasoning level for future turns. */\n\tthinkingLevel: ThinkingLevel;\n\t/** Requested provider service tier for future turns. */\n\tserviceTier: ServiceTier;\n\t/** Available tools. Assigning a new array copies its top-level array. */\n\tset tools(tools: AgentTool<any>[]);\n\tget tools(): AgentTool<any>[];\n\t/** Conversation transcript. Assigning a new array copies its top-level array. */\n\tset messages(messages: AgentMessage[]);\n\tget messages(): AgentMessage[];\n\t/** True while processing a prompt or continuation, including awaited `agent_end` listeners. */\n\treadonly isStreaming: boolean;\n\t/** Partial assistant message for the active streamed response, if any. */\n\treadonly streamingMessage?: AgentMessage;\n\t/** Tool-call IDs currently executing. */\n\treadonly pendingToolCalls: ReadonlySet<string>;\n\t/** Error from the most recent failed or aborted assistant turn, if any. */\n\treadonly errorMessage?: string;\n}\n\n/** Final or partial result produced by a tool. */\nexport interface AgentToolResult<T> {\n\t/** Text or image content returned to the model. */\n\tcontent: (TextContent | ImageContent)[];\n\t/** Structured details for logs or UI rendering. */\n\tdetails: T;\n\t/**\n\t * Hint that the agent should stop after the current tool batch.\n\t * Early termination only happens when every finalized tool result in the batch sets this to true.\n\t */\n\tterminate?: boolean;\n}\n\n/** Callback used by tools to publish partial execution updates. */\nexport type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;\n\n/** Tool definition used by the agent runtime. */\nexport interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {\n\t/** Human-readable label for UI display. */\n\tlabel: string;\n\t/**\n\t * Optional compatibility shim for raw tool-call arguments before schema validation.\n\t * Must return an object that matches `TParameters`.\n\t */\n\tprepareArguments?: (args: unknown) => Static<TParameters>;\n\t/** Execute the tool call. Throw on failure instead of encoding errors in `content`. */\n\texecute: (\n\t\ttoolCallId: string,\n\t\tparams: Static<TParameters>,\n\t\tsignal?: AbortSignal,\n\t\tonUpdate?: AgentToolUpdateCallback<TDetails>,\n\t) => Promise<AgentToolResult<TDetails>>;\n\t/**\n\t * Per-tool execution mode override.\n\t * - \"sequential\": this tool must execute one at a time with other tool calls.\n\t * - \"parallel\": this tool can execute concurrently with other tool calls.\n\t *\n\t * If omitted, the default execution mode applies.\n\t */\n\texecutionMode?: ToolExecutionMode;\n}\n\n/** Context snapshot passed to the low-level agent loop and tool hooks. */\nexport interface AgentContext {\n\t/** System prompt included with the request. */\n\tsystemPrompt: string;\n\t/** Transcript visible to the model. */\n\tmessages: AgentMessage[];\n\t/** Tools available for this run. */\n\ttools?: AgentTool<any>[];\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n *\n * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`\n * listeners for that event are still part of run settlement. The agent becomes\n * idle only after those listeners finish.\n */\nexport type AgentEvent =\n\t/** Starts and ends one agent run; `agent_end` carries all messages produced by that run. */\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AgentMessage[]; refusal?: never }\n\t| { type: \"agent_end\"; refusal: AgentOutputRefusal; messages?: never }\n\t/** One assistant response and its resulting tool calls. */\n\t| { type: \"turn_start\" }\n\t| {\n\t\t\ttype: \"turn_end\";\n\t\t\tmessage: AgentMessage;\n\t\t\ttoolResults: ToolResultMessage[];\n\t\t\t/** Always populated by native execution; historical observer events may omit it. */\n\t\t\ttoolExecution?: ToolExecutionMode;\n\t\t\t/** Settled calls in source order. Absent historical evidence is not reconstructed. */\n\t\t\texchanges?: readonly FinalizedToolExchange[];\n\t  }\n\t/** Lifecycle events for user, assistant, and tool-result messages. */\n\t| { type: \"message_start\"; message: AgentMessage }\n\t/** Only emitted for assistant messages during streaming. */\n\t| { type: \"message_update\"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AgentMessage }\n\t/** Tool execution events; parallel calls may end in completion rather than source order. */\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_update\"; toolCallId: string; toolName: string; args: any; partialResult: any }\n\t| {\n\t\t\ttype: \"tool_execution_end\";\n\t\t\ttoolCallId: string;\n\t\t\ttoolName: string;\n\t\t\tresult: any;\n\t\t\tisError: boolean;\n\t\t\t/** Always populated by native execution; absent for older observer events. */\n\t\t\texchange?: FinalizedToolExchange;\n\t  };\n"]}