@fifthrevision/axle 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -1,366 +1,6 @@
-import { A as FileResolveRequest, B as TracingContext, C as TurnStatus, D as FileKind, E as FileInfo, F as SpanData, I as SpanEvent, L as SpanOptions, M as ResolvedFileSource, N as loadFileContent, O as FileProviderId, P as EventLevel, R as SpanType, S as TurnPart, T as DeferredFileInfo, V as Stats, _ as TextPart, b as ToolAction, c as TurnEvent, d as Annotation, f as AnnotationPlacement, g as SubagentAction, h as ProviderToolAction, i as TurnAccumulatorState, j as FileResolver, k as FileResolveFormat, l as ActionPart, m as FilePart, n as TurnAccumulator, o as AnnotationEvent, p as AnnotationStatus, r as TurnAccumulatorResult, s as AnnotationTarget, t as AccumulatableEvent, u as ActionResult, v as ThinkingPart, w as ConcreteFileInfo, x as Turn, z as TraceWriter } from "./accumulator-D2NgIGxp.js";
+import { $ as ModelResult, A as AxleAssistantMessage, B as ContentPartProviderTool, C as TurnPart, D as ToolContext, E as ProviderTool, F as Citation, G as MessageMetadata, H as ContentPartThinking, I as CitationOutputSpan, J as AIProvider, K as ThinkingContinuity, L as CitationSource, M as AxleToolCallMessage, N as AxleToolCallResult, O as ToolDefinition, P as AxleUserMessage, Q as ModelError, R as ContentPart, S as TurnMetadata, T as ExecutableTool, U as ContentPartToolCall, V as ContentPartText, W as DocumentLocator, X as AxleStopReason, Y as AxleModelRequestOptions, Z as ContextUsage, _ as TextPart, _t as TraceWriter, at as FileKind, b as ToolAction, c as TurnEvent, ct as FileResolveRequest, d as Annotation, dt as loadFileContent, et as ProviderClientOptions, f as AnnotationPlacement, ft as EventLevel, g as SubagentAction, gt as SpanType, h as ProviderToolAction, ht as SpanOptions, i as TurnAccumulatorState, it as FileInfo, j as AxleMessage, k as ToolRegistry, l as ActionPart, lt as FileResolver, m as FilePart, mt as SpanEvent, n as TurnAccumulator, nt as ToolChoice, o as AnnotationEvent, ot as FileProviderId, p as AnnotationStatus, pt as SpanData, q as ToolResultPart, r as TurnAccumulatorResult, rt as DeferredFileInfo, s as AnnotationTarget, st as FileResolveFormat, t as AccumulatableEvent, tt as ProviderOptions, u as ActionResult, ut as ResolvedFileSource, v as ThinkingPart, vt as TracingContext, w as TurnStatus, x as Turn, yt as Stats, z as ContentPartFile } from "./accumulator-svhGVEwB.js";
 import * as z$2 from "zod";
-import { ZodObject, z } from "zod";
 
-//#region src/messages/stream.d.ts
-interface StreamChunk {
-  type: "start" | "text-start" | "text-delta" | "text-complete" | "tool-call-start" | "tool-call-args-delta" | "tool-call-complete" | "thinking-start" | "thinking-delta" | "thinking-summary-delta" | "thinking-complete" | "provider-tool-start" | "provider-tool-complete" | "complete" | "error";
-  id?: string;
-  data?: any;
-}
-interface StreamStartChunk extends StreamChunk {
-  type: "start";
-  id: string;
-  data: {
-    model: string;
-    timestamp: number;
-  };
-}
-interface StreamCompleteChunk extends StreamChunk {
-  type: "complete";
-  data: {
-    finishReason: AxleStopReason;
-    usage: Stats;
-  };
-}
-interface StreamErrorChunk extends StreamChunk {
-  type: "error";
-  data: {
-    type: string;
-    message: string;
-    usage?: Stats;
-    raw?: any;
-  };
-}
-interface StreamTextStartChunk extends StreamChunk {
-  type: "text-start";
-  data: {
-    index: number;
-  };
-}
-interface StreamTextDeltaChunk extends StreamChunk {
-  type: "text-delta";
-  data: {
-    index: number;
-    text: string;
-  };
-}
-interface StreamTextCompleteChunk extends StreamChunk {
-  type: "text-complete";
-  data: {
-    index: number;
-  };
-}
-interface StreamThinkingStartChunk extends StreamChunk {
-  type: "thinking-start";
-  data: {
-    index: number;
-    id?: string;
-    redacted?: boolean;
-    signature?: string;
-  };
-}
-interface StreamThinkingDeltaChunk extends StreamChunk {
-  type: "thinking-delta";
-  data: {
-    index: number;
-    text: string;
-  };
-}
-interface StreamThinkingSummaryDeltaChunk extends StreamChunk {
-  type: "thinking-summary-delta";
-  data: {
-    index: number;
-    text: string;
-  };
-}
-interface StreamThinkingCompleteChunk extends StreamChunk {
-  type: "thinking-complete";
-  data: {
-    index: number;
-  };
-}
-interface StreamToolCallStartChunk extends StreamChunk {
-  type: "tool-call-start";
-  data: {
-    index: number;
-    id: string;
-    name: string;
-  };
-}
-interface StreamToolCallArgsDeltaChunk extends StreamChunk {
-  type: "tool-call-args-delta";
-  data: {
-    index: number;
-    id: string;
-    name: string;
-    delta: string;
-    accumulated: string;
-  };
-}
-interface StreamToolCallCompleteChunk extends StreamChunk {
-  type: "tool-call-complete";
-  data: {
-    index: number;
-    id: string;
-    name: string;
-    arguments: any;
-    providerMetadata?: Record<string, unknown>;
-  };
-}
-interface StreamProviderToolStartChunk extends StreamChunk {
-  type: "provider-tool-start";
-  data: {
-    index: number;
-    id: string;
-    name: string;
-  };
-}
-interface StreamProviderToolCompleteChunk extends StreamChunk {
-  type: "provider-tool-complete";
-  data: {
-    index: number;
-    id: string;
-    name: string;
-    output?: unknown;
-  };
-}
-type AnyStreamChunk = StreamStartChunk | StreamCompleteChunk | StreamErrorChunk | StreamTextStartChunk | StreamTextDeltaChunk | StreamTextCompleteChunk | StreamThinkingStartChunk | StreamThinkingDeltaChunk | StreamThinkingSummaryDeltaChunk | StreamThinkingCompleteChunk | StreamToolCallStartChunk | StreamToolCallArgsDeltaChunk | StreamToolCallCompleteChunk | StreamProviderToolStartChunk | StreamProviderToolCompleteChunk;
-//#endregion
-//#region src/providers/types.d.ts
-/**
- * Internal services available to provider adapters while executing a model request.
- */
-interface ProviderRuntime {
-  /** Request-scoped tracing span used by provider adapters. */
-  tracer?: TracingContext;
-  /** Resolves file references before provider-specific request conversion. */
-  fileResolver?: FileResolver;
-}
-/**
- * Raw provider-specific request fields.
- *
- * Provider adapters apply this after Axle-normalized options, so these values
- * can intentionally override Axle's provider mappings.
- */
-interface ProviderOptions {
-  [key: string]: any;
-}
-/**
- * Controls how the model may use tools during a single model request.
- */
-type ToolChoice = "auto" | "none" | "required" | {
-  type: "tool";
-  name: string;
-};
-/**
- * Provider-portable options for a single model request.
- *
- * These fields are normalized by Axle and mapped to each provider's request
- * shape. Use `providerOptions` for provider-specific controls that are not
- * represented here.
- */
-interface AxleModelRequestOptions {
-  /** Enables or disables provider reasoning/thinking controls where supported. */
-  reasoning?: boolean;
-  /** Maximum output tokens to request from the model. */
-  maxOutputTokens?: number;
-  /** Sampling temperature, when supported by the provider/model. */
-  temperature?: number;
-  /** Nucleus sampling value, mapped to provider-specific casing. */
-  topP?: number;
-  /** Stop sequence or sequences for text generation. */
-  stop?: string | string[];
-  /** Constrains tool use for this model request. */
-  toolChoice?: ToolChoice;
-  /** Requests that the provider avoid parallel tool calls when supported. */
-  parallelToolCalls?: boolean;
-  /** Raw provider-specific request fields applied after normalized mappings. */
-  providerOptions?: ProviderOptions;
-  /** Abort signal for the in-flight model request. */
-  signal?: AbortSignal;
-}
-/**
- * Parameters passed to provider adapters for one non-streaming generation call.
- */
-interface ProviderGenerationParams extends AxleModelRequestOptions {
-  /** Conversation messages to send to the provider. */
-  messages: Array<AxleMessage>;
-  /** Optional system/developer instruction for the request. */
-  system?: string;
-  /** Executable tools exposed as provider function tools. */
-  tools?: Array<ToolDefinition>;
-  /** Provider-managed tools such as web search or code execution. */
-  providerTools?: Array<ProviderTool>;
-  /** Internal services available during provider request creation. */
-  runtime: ProviderRuntime;
-}
-/**
- * Parameters passed to provider adapters for one streaming generation call.
- */
-interface ProviderStreamParams extends ProviderGenerationParams {}
-interface ContextUsage {
-  total: number;
-  system: number;
-  tools: number;
-  mcpTools: number;
-  providerTools: number;
-  messages: number;
-  limit?: number;
-  free?: number;
-}
-interface AIProvider {
-  get name(): string;
-  /** @internal */
-  createGenerationRequest(model: string, params: ProviderGenerationParams): Promise<ModelResult>;
-  /** @internal */
-  createStreamingRequest(model: string, params: ProviderStreamParams): AsyncGenerator<AnyStreamChunk, void, unknown>;
-}
-interface ModelResponse {
-  type: "success";
-  role: "assistant";
-  id: string;
-  model: string;
-  text: string;
-  content: Array<ContentPartText | ContentPartThinking | ContentPartToolCall>;
-  finishReason: AxleStopReason;
-  usage: Stats;
-  raw: any;
-}
-interface ModelError {
-  type: "error";
-  error: {
-    type: string;
-    message: string;
-  };
-  usage?: Stats;
-  raw?: any;
-}
-type ModelResult = ModelResponse | ModelError;
-declare enum AxleStopReason {
-  Stop = "stop",
-  Length = "length",
-  FunctionCall = "function_call",
-  Error = "error",
-  Custom = "custom",
-  Cancelled = "cancelled"
-}
-//#endregion
-//#region src/messages/message.d.ts
-type AxleMessage = AxleUserMessage | AxleAssistantMessage | AxleToolCallMessage;
-type ToolResultPart = {
-  type: "text";
-  text: string;
-} | {
-  type: "file";
-  file: ConcreteFileInfo;
-};
-interface AxleUserMessage {
-  role: "user";
-  id?: string;
-  name?: string;
-  content: string | Array<ContentPart>;
-}
-interface AxleAssistantMessage {
-  role: "assistant";
-  id: string;
-  model?: string;
-  content: Array<ContentPartText | ContentPartThinking | ContentPartToolCall | ContentPartProviderTool>;
-  finishReason?: AxleStopReason;
-}
-interface AxleToolCallMessage {
-  role: "tool";
-  id: string;
-  content: Array<AxleToolCallResult>;
-}
-interface AxleToolCallResult {
-  id: string;
-  name: string;
-  content: string | ToolResultPart[];
-  isError?: boolean;
-}
-type ContentPart = ContentPartText | ContentPartFile | ContentPartToolCall | ContentPartThinking | ContentPartProviderTool;
-interface ContentPartText {
-  type: "text";
-  text: string;
-}
-interface ContentPartFile {
-  type: "file";
-  file: FileInfo;
-}
-interface ContentPartThinking {
-  type: "thinking";
-  id?: string;
-  text: string;
-  summary?: string;
-  redacted?: boolean;
-  encrypted?: string;
-  signature?: string;
-}
-interface ContentPartToolCall {
-  type: "tool-call";
-  id: string;
-  name: string;
-  parameters: Record<string, unknown>;
-  providerMetadata?: Record<string, unknown>;
-}
-interface ContentPartProviderTool {
-  type: "provider-tool";
-  id: string;
-  name: string;
-  input?: unknown;
-  output?: unknown;
-}
-//#endregion
-//#region src/tools/registry.d.ts
-declare class ToolRegistry {
-  private tools;
-  private mcpTools;
-  private providerTools;
-  constructor(init?: {
-    tools?: ExecutableTool[];
-    providerTools?: ProviderTool[];
-  });
-  add(tool: ExecutableTool): void;
-  add(tools: ExecutableTool[]): void;
-  addMcp(tool: ExecutableTool): void;
-  addMcp(tools: ExecutableTool[]): void;
-  addProvider(tool: ProviderTool): void;
-  addProvider(tools: ProviderTool[]): void;
-  remove(name: string): boolean;
-  has(name: string): boolean;
-  get(name: string): ExecutableTool | undefined;
-  getProvider(name: string): ProviderTool | undefined;
-  executable(): ExecutableTool[];
-  local(): ExecutableTool[];
-  mcp(): ExecutableTool[];
-  provider(): ProviderTool[];
-  get size(): number;
-}
-//#endregion
-//#region src/tools/types.d.ts
-interface ToolContext {
-  registry: ToolRegistry;
-  signal: AbortSignal;
-  emit: (chunk: string) => void;
-  tracer?: TracingContext;
-}
-interface ExecutableTool<TSchema extends ZodObject<any> = ZodObject<any>> {
-  type?: "function";
-  name: string;
-  description: string;
-  schema: TSchema;
-  execute(input: z.infer<TSchema>, ctx: ToolContext): Promise<string | ToolResultPart[]>;
-  configure?(config: Record<string, any>): void;
-  summarize?(input: z.infer<TSchema>): string;
-}
-interface ProviderTool {
-  type: "provider";
-  name: string;
-  config?: Record<string, unknown>;
-}
-type ToolDefinition = Pick<ExecutableTool, "name" | "description" | "schema">;
-//#endregion
 //#region src/mcp/MCP.d.ts
 interface MCPStdioConfig {
   transport: "stdio";
@@ -407,20 +47,89 @@ declare class MCP {
   private assertConnected;
 }
 //#endregion
-//#region src/store/types.d.ts
-interface FileStore {
-  read(path: string): Promise<string | null>;
-  write(path: string, content: string): Promise<void>;
+//#region src/core/parse.d.ts
+type OutputSchema = z$2.ZodTypeAny;
+type ParsedSchema<T extends OutputSchema> = z$2.output<T>;
+declare function parseResponse<T extends OutputSchema>(rawValue: string, schema?: T): ParsedSchema<T> | string;
+//#endregion
+//#region src/core/Instruct.d.ts
+type InstructInputs = Record<string, unknown>;
+type InstructVarsMode = "required" | "optional";
+interface InstructOptions<TSchema extends OutputSchema | undefined = OutputSchema | undefined> {
+  prompt: string;
+  schema?: TSchema;
+  vars?: InstructVarsMode;
+  metadata?: MessageMetadata;
+}
+declare class Instruct<TSchema extends OutputSchema | undefined = undefined> {
+  prompt: string;
+  inputs: InstructInputs;
+  files: FileInfo[];
+  textReferences: Array<{
+    content: string;
+    name?: string;
+  }>;
+  vars: InstructVarsMode;
+  metadata?: MessageMetadata;
+  schema: TSchema;
+  constructor(options: InstructOptions<TSchema>);
+  clone(): Instruct<TSchema>;
+  withInputs(inputs: InstructInputs): Instruct<TSchema>;
+  withInput(name: string, value: unknown): Instruct<TSchema>;
+  setInputs(inputs: InstructInputs): void;
+  addInput(name: string, value: unknown): void;
+  addFile(file: FileInfo | string, options?: {
+    name?: string;
+  }): void;
+  hasFiles(): boolean;
+  render(options?: {
+    vars?: InstructVarsMode;
+  }): string;
+}
+//#endregion
+//#region src/core/agent/history.d.ts
+/**
+ * In-memory conversation and presentation history for an agent.
+ *
+ * `log` is the canonical model-facing message history. `turns` and
+ * `sessionAnnotations` are renderable presentation state for consumers.
+ *
+ * @typeParam TAnnotation - Annotation union supported by the host renderer.
+ */
+declare class History<TAnnotation extends Annotation = Annotation> {
+  private _turns;
+  private _log;
+  private _sessionAnnotations;
+  constructor(init?: {
+    turns?: Turn<TAnnotation>[];
+    log?: AxleMessage[];
+    sessionAnnotations?: TAnnotation[];
+  });
+  get turns(): Turn<TAnnotation>[];
+  get log(): AxleMessage[];
+  get sessionAnnotations(): TAnnotation[];
+  addTurn(turn: Turn<TAnnotation>): void;
+  replaceTurns(turns: Turn<TAnnotation>[]): void;
+  replaceLog(messages: AxleMessage[]): void;
+  replaceSessionAnnotations(annotations?: TAnnotation[]): void;
+  appendToLog(messages: AxleMessage | AxleMessage[]): void;
+  latestTurn(): Turn<TAnnotation> | undefined;
+  toString(): string;
 }
 //#endregion
 //#region src/memory/types.d.ts
 interface MemoryContext {
-  name?: string;
-  scope?: Record<string, string>;
+  /** Optional agent name provided by the host. */
+  agentName?: string;
+  /** Stable conversation/session id from the agent. */
+  sessionId: string;
+  /** Current system prompt, before memory augmentation. */
   system?: string;
+  /** Full message context available for recall or extraction. */
   messages: AxleMessage[];
+  /** Newly produced messages to record after a turn completes. */
   newMessages?: AxleMessage[];
-  store: FileStore;
+  /** Optional tracing context. */
   tracer?: TracingContext;
 }
 interface RecallResult {
@@ -492,75 +201,153 @@ declare function createHandle<T>(queue: Promise<void>, work: (signal: AbortSigna
   settled: Promise<void>;
 };
 //#endregion
-//#region src/core/history.d.ts
-declare class History {
-  private _turns;
-  private _log;
-  constructor(init?: {
-    turns?: Turn[];
-    log?: AxleMessage[];
-  });
-  get turns(): Turn[];
-  get log(): AxleMessage[];
-  addTurn(turn: Turn): void;
-  replaceTurns(turns: Turn[]): void;
-  appendToLog(messages: AxleMessage | AxleMessage[]): void;
-  latestTurn(): Turn | undefined;
-  toString(): string;
-}
-//#endregion
-//#region src/core/parse.d.ts
-type OutputSchema = z$2.ZodTypeAny;
-type ParsedSchema<T extends OutputSchema> = z$2.output<T>;
-declare function parseResponse<T extends OutputSchema>(rawValue: string, schema?: T): ParsedSchema<T> | string;
-//#endregion
-//#region src/core/Instruct.d.ts
-type InstructInputs = Record<string, unknown>;
-type InstructVarsMode = "required" | "optional";
-interface InstructOptions<TSchema extends OutputSchema | undefined = OutputSchema | undefined> {
-  prompt: string;
-  schema?: TSchema;
-  vars?: InstructVarsMode;
-}
-declare class Instruct<TSchema extends OutputSchema | undefined = undefined> {
-  prompt: string;
-  inputs: InstructInputs;
-  files: FileInfo[];
-  textReferences: Array<{
-    content: string;
-    name?: string;
-  }>;
-  vars: InstructVarsMode;
-  schema: TSchema;
-  constructor(options: InstructOptions<TSchema>);
-  clone(): Instruct<TSchema>;
-  withInputs(inputs: InstructInputs): Instruct<TSchema>;
-  withInput(name: string, value: unknown): Instruct<TSchema>;
-  setInputs(inputs: InstructInputs): void;
-  addInput(name: string, value: unknown): void;
-  addFile(file: FileInfo | string, options?: {
-    name?: string;
-  }): void;
-  hasFiles(): boolean;
-  render(options?: {
-    vars?: InstructVarsMode;
-  }): string;
-}
-//#endregion
-//#region src/core/Agent.d.ts
+//#region src/core/agent/types.d.ts
+/**
+ * Runtime configuration for an `Agent`.
+ *
+ * This contains executable objects and process-local services. It is not meant
+ * to be serialized directly. Use `AgentDefinition` for a serializable recipe
+ * and `createAgentConfig()` to produce an `AgentConfig`.
+ */
 interface AgentConfig extends Omit<AxleModelRequestOptions, "signal"> {
+  /** Provider adapter used to execute model requests. */
   provider: AIProvider;
+  /** Model identifier passed to the provider. */
   model: string;
+  /** Stable conversation/session id. Generated when omitted. */
+  sessionId?: string;
+  /** Optional system/developer instruction. */
   system?: string;
+  /** Optional agent name passed to host services such as memory. */
   name?: string;
-  scope?: Record<string, string>;
+  /** Executable tools available to the agent. */
   tools?: ExecutableTool[];
+  /** Provider-managed tools such as hosted search or code execution. */
   providerTools?: ProviderTool[];
+  /** MCP clients whose tools should be lazily resolved. */
   mcps?: MCP[];
+  /** Optional memory implementation. */
   memory?: AgentMemory;
+  /** Optional tracing context. */
   tracer?: TracingContext;
+  /** Optional file resolver for request file references. */
   fileResolver?: FileResolver;
 }
+/**
+ * Serializable provider reference for an agent definition.
+ *
+ * `type` is host-defined. Common values are provider names such as `"openai"`,
+ * `"anthropic"`, `"gemini"`, or `"chatcompletions"`, but core does not
+ * interpret the value. `config` is passed through to the host resolver.
+ */
+interface ProviderDefinition {
+  /** Host-defined provider discriminator. */
+  type: string;
+  /** Serializable provider configuration or references, such as `apiKeyEnv`. */
+  config?: Record<string, unknown>;
+}
+/**
+ * Serializable reference to an executable tool.
+ */
+interface ToolDefinitionRef {
+  /** Host-defined tool name or id. */
+  name: string;
+  /** Optional serializable tool configuration passed to the resolver. */
+  config?: Record<string, unknown>;
+}
+/**
+ * Serializable reference to a provider-managed tool.
+ */
+interface ProviderToolDefinitionRef {
+  /** Provider tool name. */
+  name: string;
+  /** Optional provider tool configuration. */
+  config?: Record<string, unknown>;
+}
+/**
+ * Serializable request options for an agent definition.
+ */
+interface AgentDefinitionRequestOptions extends Omit<AxleModelRequestOptions, "signal"> {}
+/**
+ * Serializable recipe for reconstructing an agent.
+ *
+ * This is deliberately not executable by itself. Hosts resolve provider and
+ * tool references into runtime objects using an `AgentDefinitionResolver`.
+ * Harness concerns such as memory implementations, file resolvers, tracing,
+ * transport, and stores should be modeled outside this core definition.
+ */
+interface AgentDefinition {
+  /** Agent definition schema version. */
+  version: 1;
+  /** Optional agent name passed to host services such as memory. */
+  name?: string;
+  /** Provider reference resolved by the host. */
+  provider: ProviderDefinition;
+  /** Optional model identifier passed to the resolved provider. */
+  model?: string;
+  /** Optional system/developer instruction. */
+  system?: string;
+  /** Provider-portable request defaults. */
+  request?: AgentDefinitionRequestOptions;
+  /** Serializable executable tool references. */
+  tools?: ToolDefinitionRef[];
+  /** Serializable provider-managed tool references. */
+  providerTools?: ProviderToolDefinitionRef[];
+  /** Serializable MCP client configuration. */
+  mcps?: MCPConfig[];
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Executable dependencies resolved from an `AgentDefinition`.
+ */
+interface ResolvedAgentDefinition {
+  /** Provider adapter used to execute model requests. */
+  provider: AIProvider;
+  /** Model identifier used when `AgentDefinition.model` is omitted. */
+  model?: string;
+  /** Executable tools resolved from `AgentDefinition.tools`. */
+  tools?: ExecutableTool[];
+  /** Provider-managed tools resolved from `AgentDefinition.providerTools`. */
+  providerTools?: ProviderTool[];
+  /** MCP clients resolved from `AgentDefinition.mcps`. */
+  mcps?: MCP[];
+}
+/**
+ * Host function used to turn an `AgentDefinition` into executable dependencies.
+ */
+type AgentDefinitionResolver = (definition: AgentDefinition) => MaybePromise<ResolvedAgentDefinition>;
+/**
+ * Serializable continuation and presentation state for an `Agent`.
+ *
+ * This is the data needed to continue a model conversation and restore the
+ * renderable turn state. It intentionally does not include executable runtime
+ * objects such as providers, tools, MCP clients, memory implementations, file
+ * resolvers, or tracers. Recreate those from host-owned configuration, then
+ * call `agent.restore(session)`.
+ *
+ * @typeParam TAnnotation - Annotation union supported by the host renderer.
+ */
+interface AgentSession<TAnnotation extends Annotation = Annotation> {
+  /** Agent session schema version. */
+  version: 1;
+  /** Stable conversation/session id. */
+  sessionId: string;
+  /** Canonical model-facing message history used for continuation. */
+  messages: AxleMessage[];
+  /** Renderable turn state for exact UI restoration. */
+  turns?: Turn<TAnnotation>[];
+  /** Session-level annotations for generic renderer state. */
+  sessionAnnotations?: TAnnotation[];
+}
+/**
+ * Serializable saved agent payload: definition plus continuation state.
+ */
+interface SavedAgent<TAnnotation extends Annotation = Annotation> {
+  /** Serializable recipe used to reconstruct runtime config. */
+  definition: AgentDefinition;
+  /** Serializable continuation and presentation state. */
+  session: AgentSession<TAnnotation>;
+}
 interface AgentResult<T = string> {
   ok: true;
   response: T;
@@ -578,30 +365,58 @@ type AgentHandle<T = string> = Handle<AgentResult<T> | AgentErrorResult>;
 type TurnEventCallback = (event: TurnEvent) => void;
 interface SendMessageOptions extends AxleModelRequestOptions {
   fileResolver?: FileResolver;
+  /**
+   * Stable host-owned metadata attached to the user message and copied to the
+   * renderable user turn. Providers ignore this data.
+   */
+  metadata?: MessageMetadata;
 }
+//#endregion
+//#region src/core/agent/Agent.d.ts
 declare class Agent {
   readonly provider: AIProvider;
   readonly model: string;
   readonly history: History;
   readonly tracer?: TracingContext;
   readonly name?: string;
-  readonly scope?: Record<string, string>;
-  readonly store: FileStore;
   readonly fileResolver?: FileResolver;
   readonly requestOptions: Omit<AxleModelRequestOptions, "signal">;
   readonly registry: ToolRegistry;
+  sessionId: string;
   system: string | undefined;
   private mcps;
   private resolvedMcps;
   private memory?;
   private eventCallbacks;
   private sendQueue;
-  constructor(config: AgentConfig);
+  /**
+   * Create an agent from runtime config and, optionally, restore saved session state.
+   *
+   * When both `config.sessionId` and `session.sessionId` are supplied, the
+   * restored session id wins.
+   */
+  constructor(config: AgentConfig, session?: AgentSession);
   addMcp(mcp: MCP): void;
   addMcps(mcps: MCP[]): void;
   hasTools(): boolean;
   on(callback: TurnEventCallback): void;
   context(): ContextUsage;
+  /**
+   * Capture the serializable session state for later continuation.
+   *
+   * The returned object contains message history and renderable turn state, but
+   * not executable configuration such as providers, tools, MCP clients, memory,
+   * or tracers.
+   */
+  snapshot(): AgentSession;
+  /**
+   * Replace the agent's continuation and render state from a saved session.
+   *
+   * Restore does not change runtime configuration. The current provider, model,
+   * tools, MCP clients, memory, and other constructor-supplied objects remain in
+   * effect.
+   */
+  restore(session: AgentSession): void;
   send(message: string | Instruct<undefined>, options?: SendMessageOptions): AgentHandle<string>;
   send<TSchema extends OutputSchema>(instruct: Instruct<TSchema>, options?: SendMessageOptions): AgentHandle<ParsedSchema<TSchema>>;
   private resolveMcpTools;
@@ -610,6 +425,17 @@ declare class Agent {
   private run;
 }
 //#endregion
+//#region src/core/agent/createAgentConfig.d.ts
+/**
+ * Create executable `Agent` config from a serializable agent definition.
+ *
+ * Core resolves only what it can safely construct from serializable data. The
+ * host remains responsible for executable dependencies such as providers,
+ * tools, and MCP clients. Harness runtime services such as memory and file
+ * resolvers should be layered onto the returned config by the host.
+ */
+declare function createAgentConfig(definition: AgentDefinition, resolver: AgentDefinitionResolver): Promise<AgentConfig>;
+//#endregion
 //#region src/core/userTurn.d.ts
 type InstructResponse<TSchema extends OutputSchema | undefined> = TSchema extends OutputSchema ? ParsedSchema<TSchema> : string;
 //#endregion
@@ -739,11 +565,12 @@ declare class TaskError extends AxleError {
 }
 //#endregion
 //#region src/providers/anthropic/provider.d.ts
-declare function anthropic(apiKey: string): AIProvider;
+declare function anthropic(apiKey: string, options?: ProviderClientOptions): AIProvider;
 //#endregion
 //#region src/providers/anthropic/index.d.ts
 declare const Anthropic: {
   readonly Models: {
+    readonly CLAUDE_OPUS_4_8: "claude-opus-4-8";
     readonly CLAUDE_OPUS_4_7: "claude-opus-4-7";
     readonly CLAUDE_SONNET_4_6: "claude-sonnet-4-6";
     readonly CLAUDE_OPUS_4_6: "claude-opus-4-6";
@@ -764,6 +591,10 @@ declare const Anthropic: {
 };
 //#endregion
 //#region src/providers/chatcompletions/provider.d.ts
+interface ChatCompletionsOptions extends ProviderClientOptions {
+  apiKey?: string;
+}
+declare function chatCompletions(baseUrl: string, options?: ChatCompletionsOptions): AIProvider;
 declare function chatCompletions(baseUrl: string, apiKey?: string): AIProvider;
 //#endregion
 //#region src/providers/context.d.ts
@@ -778,7 +609,7 @@ interface ContextEstimateInput {
 declare function estimateContextUsage(input: ContextEstimateInput): ContextUsage;
 //#endregion
 //#region src/providers/gemini/provider.d.ts
-declare function gemini(apiKey: string): AIProvider;
+declare function gemini(apiKey: string, options?: ProviderClientOptions): AIProvider;
 //#endregion
 //#region src/providers/gemini/index.d.ts
 declare const Gemini: {
@@ -804,7 +635,7 @@ declare const Gemini: {
     readonly GEMINI_FLASH_LITE_LATEST: "gemini-flash-lite-latest";
     readonly GEMINI_PRO_LATEST: "gemini-pro-latest";
   };
-  readonly DefaultModel: "gemini-3.1-flash-lite-preview";
+  readonly DefaultModel: "gemini-3.5-flash";
 };
 //#endregion
 //#region src/providers/generate.d.ts
@@ -865,6 +696,11 @@ type StreamEvent = {
   index: number;
   delta: string;
   accumulated: string;
+} | {
+  type: "text:citation";
+  index: number;
+  citation: Citation;
+  citations: Citation[];
 } | {
   type: "text:end";
   index: number;
@@ -872,11 +708,25 @@ type StreamEvent = {
 } | {
   type: "thinking:start";
   index: number;
+  redacted?: boolean;
+  continuity?: ThinkingContinuity;
+  providerMetadata?: Record<string, unknown>;
 } | {
   type: "thinking:delta";
   index: number;
   delta: string;
   accumulated: string;
+} | {
+  type: "thinking:summary-delta";
+  index: number;
+  delta: string;
+  accumulated: string;
+} | {
+  type: "thinking:update";
+  index: number;
+  redacted?: boolean;
+  continuity?: ThinkingContinuity;
+  providerMetadata?: Record<string, unknown>;
 } | {
   type: "thinking:end";
   index: number;
@@ -957,7 +807,7 @@ declare function stream<TSchema extends OutputSchema | undefined>(options: Strea
 declare function stream(options: StreamParams): StreamHandle;
 //#endregion
 //#region src/providers/openai/provider.d.ts
-declare function openai(apiKey: string): AIProvider;
+declare function openai(apiKey: string, options?: ProviderClientOptions): AIProvider;
 //#endregion
 //#region src/providers/openai/index.d.ts
 declare const OpenAI: {
@@ -1014,94 +864,6 @@ declare const OpenAI: {
   readonly DefaultModel: "gpt-5.4-mini";
 };
 //#endregion
-//#region src/cli/configs/schemas.d.ts
-declare const BraveProviderConfigSchema: z.ZodObject<{
-  "api-key": z.ZodString;
-  rateLimit: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-type BraveProviderConfig = z.infer<typeof BraveProviderConfigSchema>;
-declare const ExecProviderConfigSchema: z.ZodObject<{
-  timeout: z.ZodOptional<z.ZodNumber>;
-  maxBuffer: z.ZodOptional<z.ZodNumber>;
-  cwd: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type ExecProviderConfig = z.infer<typeof ExecProviderConfigSchema>;
-//#endregion
-//#region src/tools/brave.d.ts
-declare const braveSearchSchema: z$2.ZodObject<{
-  searchTerm: z$2.ZodString;
-}, z$2.core.$strip>;
-declare class BraveSearchTool implements ExecutableTool<typeof braveSearchSchema> {
-  name: string;
-  description: string;
-  schema: z$2.ZodObject<{
-    searchTerm: z$2.ZodString;
-  }, z$2.core.$strip>;
-  apiKey: string | undefined;
-  throttle: number | undefined;
-  lastExecTime: number;
-  constructor(config?: BraveProviderConfig);
-  configure(config: BraveProviderConfig): void;
-  execute(params: z$2.infer<typeof braveSearchSchema>, ctx: ToolContext): Promise<string>;
-}
-declare const braveSearchTool: BraveSearchTool;
-//#endregion
-//#region src/tools/calculator.d.ts
-declare const calculatorSchema: z.ZodObject<{
-  operation: z.ZodEnum<{
-    add: "add";
-    subtract: "subtract";
-    multiply: "multiply";
-    divide: "divide";
-  }>;
-  a: z.ZodNumber;
-  b: z.ZodNumber;
-}, z.core.$strip>;
-declare const calculatorTool: ExecutableTool<typeof calculatorSchema>;
-//#endregion
-//#region src/tools/exec/index.d.ts
-declare const execSchema: z$2.ZodObject<{
-  command: z$2.ZodString;
-}, z$2.core.$strip>;
-declare class ExecTool implements ExecutableTool<typeof execSchema> {
-  name: string;
-  description: string;
-  schema: z$2.ZodObject<{
-    command: z$2.ZodString;
-  }, z$2.core.$strip>;
-  private timeout;
-  private maxBuffer;
-  private cwd?;
-  constructor(config?: ExecProviderConfig);
-  configure(config: ExecProviderConfig): void;
-  summarize(params: z$2.infer<typeof execSchema>): string;
-  execute(params: z$2.infer<typeof execSchema>, ctx: ToolContext): Promise<string>;
-}
-declare const execTool: ExecTool;
-//#endregion
-//#region src/tools/patch-file.d.ts
-declare const patchFileSchema: z.ZodObject<{
-  path: z.ZodString;
-  old_string: z.ZodString;
-  new_string: z.ZodString;
-  start_line: z.ZodNumber;
-  end_line: z.ZodNumber;
-}, z.core.$strip>;
-declare const patchFileTool: ExecutableTool<typeof patchFileSchema>;
-//#endregion
-//#region src/tools/read-file.d.ts
-declare const readFileSchema: z.ZodObject<{
-  path: z.ZodString;
-}, z.core.$strip>;
-declare const readFileTool: ExecutableTool<typeof readFileSchema>;
-//#endregion
-//#region src/tools/write-file.d.ts
-declare const writeFileSchema: z.ZodObject<{
-  path: z.ZodString;
-  content: z.ZodString;
-}, z.core.$strip>;
-declare const writeFileTool: ExecutableTool<typeof writeFileSchema>;
-//#endregion
 //#region src/turns/eventBuilder.d.ts
 declare class TurnEventBuilder {
   private currentTurnId;
@@ -1194,36 +956,14 @@ declare class SimpleWriter implements TraceWriter {
   onEvent(span: SpanData, event: SpanEvent): void;
 }
 //#endregion
-//#region src/memory/ProceduralMemory.d.ts
-interface ProceduralMemoryConfig {
-  provider: AIProvider;
-  model: string;
-  enableTools?: boolean;
-}
-declare class ProceduralMemory implements AgentMemory {
-  private provider;
-  private model;
-  private enableTools;
-  private lastStore?;
-  private lastName?;
-  private lastScope?;
-  constructor(config: ProceduralMemoryConfig);
-  recall(context: MemoryContext): Promise<RecallResult>;
-  record(context: MemoryContext): Promise<void>;
-  tools(): ExecutableTool[];
-  private formatMessages;
-  private parseInstructions;
-  private getStorePath;
-  private loadStore;
-  private saveStore;
-}
-//#endregion
-//#region src/store/LocalFileStore.d.ts
-declare class LocalFileStore implements FileStore {
-  readonly rootPath: string;
-  constructor(rootPath: string);
+//#region src/store/types.d.ts
+interface FileStore {
   read(path: string): Promise<string | null>;
   write(path: string, content: string): Promise<void>;
 }
 //#endregion
-export { type AIProvider, type AccumulatableEvent, type ActionPart, type ActionResult, Agent, type AgentConfig, type AgentHandle, type AgentMemory, type AgentResult, type Annotation, type AnnotationEvent, type AnnotationPlacement, type AnnotationStatus, type AnnotationTarget, Anthropic, AxleAbortError, AxleAgentAbortError, type AxleAssistantMessage, AxleError, type AxleMessage, type AxleModelRequestOptions, AxleStopReason, type AxleToolCallMessage, type AxleToolCallResult, AxleToolFatalError, type AxleUserMessage, type ContentPart, type ContentPartFile, type ContentPartProviderTool, type ContentPartText, type ContentPartThinking, type ContentPartToolCall, type ContextUsage, type DeferredFileInfo, type EventLevel, type ExecutableTool, type FileInfo, type FileKind, type FilePart, type FileProviderId, type FileResolveFormat, type FileResolveRequest, type FileResolver, type FileStore, Gemini, type GenerateInstructParams, type GenerateInstructResult, type GenerateParams, type Handle, History, Instruct, type InstructInputs, type InstructOptions, type InstructResponse, InstructVariableError, type InstructVarsMode, LocalFileStore, MCP, type MCPConfig, type MCPHttpConfig, type MCPStdioConfig, type MemoryContext, OpenAI, ProceduralMemory, type ProceduralMemoryConfig, type ProviderOptions, type ProviderTool, type ProviderToolAction, type RecallResult, type ResolvedFileSource, type SendMessageOptions, SimpleWriter, type SimpleWriterOptions, type SpanData, type SpanOptions, type SpanType, type StreamEvent, type StreamEventCallback, type StreamHandle, type StreamInstructHandle, type StreamInstructParams, type StreamInstructResult, type StreamParams, type StreamResult, type SubagentAction, TaskError, type TextPart, type ThinkingPart, type ToolAction, type ToolChoice, type ToolContext, type ToolDefinition, ToolRegistry, type ToolResultPart, type TraceWriter, Tracer, type TracingContext, type Turn, TurnAccumulator, type TurnAccumulatorResult, type TurnAccumulatorState, type TurnEvent, TurnEventBuilder, type TurnEventCallback, type TurnPart, type TurnStatus, anthropic, braveSearchTool, calculatorTool, chatCompletions, createHandle, estimateContextUsage, execTool, gemini, generate, generateTurn, loadFileContent, openai, parseResponse, patchFileTool, readFileTool, stream, writeFileTool };
+//#region src/utils/stats.d.ts
+declare function createStats(): Stats;
+declare function addStats(total: Stats, usage?: Stats): void;
+//#endregion
+export { type AIProvider, type AccumulatableEvent, type ActionPart, type ActionResult, Agent, type AgentConfig, type AgentDefinition, type AgentDefinitionRequestOptions, type AgentDefinitionResolver, type AgentErrorResult, type AgentHandle, type AgentMemory, type AgentResult, type AgentSession, type Annotation, type AnnotationEvent, type AnnotationPlacement, type AnnotationStatus, type AnnotationTarget, Anthropic, AxleAbortError, AxleAgentAbortError, type AxleAssistantMessage, AxleError, type AxleMessage, type AxleModelRequestOptions, AxleStopReason, type AxleToolCallMessage, type AxleToolCallResult, AxleToolFatalError, type AxleUserMessage, type ChatCompletionsOptions, type Citation, type CitationOutputSpan, type CitationSource, type ContentPart, type ContentPartFile, type ContentPartProviderTool, type ContentPartText, type ContentPartThinking, type ContentPartToolCall, type ContextUsage, type DeferredFileInfo, type DocumentLocator, type EventLevel, type ExecutableTool, type FileInfo, type FileKind, type FilePart, type FileProviderId, type FileResolveFormat, type FileResolveRequest, type FileResolver, type FileStore, Gemini, type GenerateInstructParams, type GenerateInstructResult, type GenerateParams, type Handle, History, Instruct, type InstructInputs, type InstructOptions, type InstructResponse, InstructVariableError, type InstructVarsMode, MCP, type MCPConfig, type MCPHttpConfig, type MCPStdioConfig, type MaybePromise, type MemoryContext, type MessageMetadata, OpenAI, type OutputSchema, type ParsedSchema, type ProviderClientOptions, type ProviderDefinition, type ProviderOptions, type ProviderTool, type ProviderToolAction, type ProviderToolDefinitionRef, type RecallResult, type ResolvedAgentDefinition, type ResolvedFileSource, type SavedAgent, type SendMessageOptions, SimpleWriter, type SimpleWriterOptions, type SpanData, type SpanOptions, type SpanType, type Stats, type StreamEvent, type StreamEventCallback, type StreamHandle, type StreamInstructHandle, type StreamInstructParams, type StreamInstructResult, type StreamParams, type StreamResult, type SubagentAction, TaskError, type TextPart, type ThinkingContinuity, type ThinkingPart, type ToolAction, type ToolChoice, type ToolContext, type ToolDefinition, type ToolDefinitionRef, ToolRegistry, type ToolResultPart, type TraceWriter, Tracer, type TracingContext, type Turn, TurnAccumulator, type TurnAccumulatorResult, type TurnAccumulatorState, type TurnEvent, TurnEventBuilder, type TurnEventCallback, type TurnMetadata, type TurnPart, type TurnStatus, addStats, anthropic, chatCompletions, createAgentConfig, createHandle, createStats, estimateContextUsage, gemini, generate, generateTurn, loadFileContent, openai, parseResponse, stream };