@fifthrevision/axle 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -1,23 +1,7 @@
+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 z$2 from "zod";
 import { ZodObject, z } from "zod";
 
-//#region src/types.d.ts
-/**
- * Token usage reported by a provider response.
- */
-interface Stats {
-  /** Total effective input tokens. Includes `cachedIn` and `cacheWriteIn` when reported. */
-  in: number;
-  /** Total output tokens. Includes `reasoningOut` when reported. */
-  out: number;
-  /** Input tokens served from provider prompt/context cache. Included in `in`. */
-  cachedIn?: number;
-  /** Input tokens written into provider prompt/context cache. Included in `in`. */
-  cacheWriteIn?: number;
-  /** Output tokens spent on reasoning/thinking. Included in `out`. */
-  reasoningOut?: number;
-}
-//#endregion
 //#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";
@@ -143,192 +127,24 @@ interface StreamProviderToolCompleteChunk extends StreamChunk {
 }
 type AnyStreamChunk = StreamStartChunk | StreamCompleteChunk | StreamErrorChunk | StreamTextStartChunk | StreamTextDeltaChunk | StreamTextCompleteChunk | StreamThinkingStartChunk | StreamThinkingDeltaChunk | StreamThinkingSummaryDeltaChunk | StreamThinkingCompleteChunk | StreamToolCallStartChunk | StreamToolCallArgsDeltaChunk | StreamToolCallCompleteChunk | StreamProviderToolStartChunk | StreamProviderToolCompleteChunk;
 //#endregion
-//#region src/tracer/types.d.ts
-type SpanStatus = "ok" | "error";
-type EventLevel = "debug" | "info" | "warn" | "error";
-type SpanType = string;
-interface SpanEvent {
-  name: string;
-  timestamp: number;
-  level: EventLevel;
-  attributes?: Record<string, unknown>;
-}
-interface SpanData {
-  traceId: string;
-  spanId: string;
-  parentSpanId?: string;
-  name: string;
-  type?: SpanType;
-  startTime: number;
-  endTime?: number;
-  status: SpanStatus;
-  attributes: Record<string, unknown>;
-  events: SpanEvent[];
-  result?: SpanResult;
-}
-interface SpanOptions {
-  type?: SpanType;
-}
-type SpanResult = LLMResult | ToolResult;
-interface LLMResult {
-  kind: "llm";
-  model: string;
-  request: LLMRequest;
-  response: LLMResponse;
-  usage?: TokenUsage;
-  finishReason?: string;
-}
-interface LLMRequest {
-  messages: unknown[];
-  system?: string;
-  tools?: unknown[];
-}
-interface LLMResponse {
-  content: unknown;
-}
-interface TokenUsage {
-  inputTokens?: number;
-  outputTokens?: number;
-  totalTokens?: number;
-  cachedInputTokens?: number;
-  cacheWriteInputTokens?: number;
-  reasoningOutputTokens?: number;
-}
-interface ToolResult {
-  kind: "tool";
-  name: string;
-  input: unknown;
-  output: unknown;
-}
-interface TraceWriter {
-  onSpanStart(span: SpanData): void;
-  onSpanUpdate?(span: SpanData): void;
-  onSpanEnd(span: SpanData): void;
-  onEvent?(span: SpanData, event: SpanEvent): void;
-  flush?(): Promise<void>;
-}
-/**
- * Tracing context for a span. Created by Tracer.startSpan().
- * Can create child spans and log events within the span's scope.
- */
-interface TracingContext {
-  startSpan(name: string, options?: SpanOptions): TracingContext;
-  end(status?: SpanStatus): void;
-  debug(message: string, attributes?: Record<string, unknown>): void;
-  info(message: string, attributes?: Record<string, unknown>): void;
-  warn(message: string, attributes?: Record<string, unknown>): void;
-  error(message: string, attributes?: Record<string, unknown>): void;
-  setAttribute(key: string, value: unknown): void;
-  setAttributes(attributes: Record<string, unknown>): void;
-  setResult(result: SpanResult): void;
-}
-//#endregion
-//#region src/utils/file.d.ts
-type FileKind = "image" | "document" | "text";
-type TextSource = {
-  type: "text";
-  content: string;
-} | {
-  type: "url";
-  url: string;
-} | {
-  type: "ref";
-  ref: unknown;
-};
-type BinarySource = {
-  type: "base64";
-  data: string;
-} | {
-  type: "url";
-  url: string;
-} | {
-  type: "ref";
-  ref: unknown;
-};
-interface BaseFile {
-  mimeType: string;
-  name: string;
-  size?: number;
-}
-type TextFileInfo = BaseFile & {
-  kind: "text";
-  source: TextSource;
-};
-type BinaryFileInfo = BaseFile & {
-  kind: "image" | "document";
-  source: BinarySource;
-};
-type FileInfo = TextFileInfo | BinaryFileInfo;
-type InlineTextFile = TextFileInfo & {
-  source: {
-    type: "text";
-    content: string;
-  };
-};
-type InlineBinaryFile = BinaryFileInfo & {
-  source: {
-    type: "base64";
-    data: string;
-  };
-};
-type DeferredFileInfo = FileInfo & {
-  source: {
-    type: "ref";
-    ref: unknown;
-  };
+//#region src/providers/types.d.ts
+type AnthropicProviderConfig = {
+  "api-key": string;
+  model?: string;
 };
-type ConcreteFileInfo = FileInfo & {
-  source: {
-    type: "text";
-  } | {
-    type: "base64";
-  } | {
-    type: "url";
-  };
+type OpenAIProviderConfig = {
+  "api-key": string;
+  model?: string;
 };
-type FileProviderId = "anthropic" | "openai" | "gemini" | "chatcompletions";
-type FileResolveFormat = "base64" | "url" | "text" | "gemini-file-uri";
-type ResolvedFileSource = {
-  type: "base64";
-  data: string;
-  mimeType?: string;
-  name?: string;
-} | {
-  type: "url";
-  url: string;
-  mimeType?: string;
-  name?: string;
-} | {
-  type: "text";
-  content: string;
-  mimeType?: string;
-  name?: string;
-} | {
-  type: "gemini-file-uri";
-  uri: string;
-  mimeType?: string;
-  name?: string;
+type GeminiProviderConfig = {
+  "api-key": string;
+  model?: string;
 };
-interface FileResolveRequest {
-  file: DeferredFileInfo;
-  ref: unknown;
-  provider: FileProviderId;
+type ChatCompletionsProviderConfig = {
+  "base-url": string;
   model: string;
-  accepted: FileResolveFormat[];
-  signal?: AbortSignal;
-}
-type FileResolver = (request: FileResolveRequest) => Promise<ResolvedFileSource>;
-/**
- * Load a file with the specified encoding or auto-detect based on file extension
- * @param filePath - Path to the file
- * @param encoding - How to load the file: "utf-8" for text, "base64" for binary, or omit for auto-detection
- * @returns FileInfo object with appropriate content based on encoding
- */
-declare function loadFileContent(filePath: string): Promise<FileInfo>;
-declare function loadFileContent(filePath: string, encoding: "utf-8"): Promise<InlineTextFile>;
-declare function loadFileContent(filePath: string, encoding: "base64"): Promise<InlineBinaryFile>;
-//#endregion
-//#region src/providers/types.d.ts
+  "api-key"?: string;
+};
 /**
  * Internal services available to provider adapters while executing a model request.
  */
@@ -608,20 +424,87 @@ 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;
+}
+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/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 {
@@ -677,167 +560,6 @@ type GenerateResult<TResponse = AxleAssistantMessage> = {
 };
 type StreamResult<TResponse = AxleAssistantMessage> = GenerateResult<TResponse>;
 //#endregion
-//#region src/turns/types.d.ts
-type TurnStatus = "streaming" | "complete" | "cancelled" | "error";
-interface TimingInfo {
-  start: string;
-  end?: string;
-}
-interface Turn {
-  id: string;
-  owner: "user" | "agent";
-  parts: TurnPart[];
-  status: TurnStatus;
-  timing?: TimingInfo;
-  usage?: Stats;
-}
-type TurnPart = TextPart | FilePart | ThinkingPart | ActionPart;
-interface TextPart {
-  id: string;
-  type: "text";
-  text: string;
-  timing?: TimingInfo;
-}
-interface FilePart {
-  id: string;
-  type: "file";
-  file: FileInfo;
-  timing?: TimingInfo;
-}
-interface ThinkingPart {
-  id: string;
-  type: "thinking";
-  text: string;
-  summary?: string;
-  redacted?: boolean;
-  timing?: TimingInfo;
-}
-interface ActionPartBase {
-  id: string;
-  type: "action";
-  kind: string;
-  status: "pending" | "running" | "complete" | "cancelled" | "error";
-  timing?: TimingInfo;
-}
-interface ToolAction extends ActionPartBase {
-  kind: "tool";
-  detail: {
-    name: string;
-    parameters: Record<string, unknown>;
-    pendingArgs?: string;
-    result?: ActionResult;
-  };
-}
-interface SubagentAction extends ActionPartBase {
-  kind: "agent";
-  detail: {
-    name: string;
-    config?: Record<string, unknown>;
-    children: Turn[];
-    result?: ActionResult;
-  };
-}
-interface ProviderToolAction extends ActionPartBase {
-  kind: "provider-tool";
-  detail: {
-    name: string;
-    input?: unknown;
-    result?: ActionResult;
-  };
-}
-type ActionPart = ToolAction | SubagentAction | ProviderToolAction;
-type ActionResult = {
-  type: "in-progress";
-  content: string;
-} | {
-  type: "success";
-  content: unknown;
-} | {
-  type: "error";
-  error: {
-    type: string;
-    message: string;
-  };
-};
-//#endregion
-//#region src/turns/events.d.ts
-type AgentEvent = {
-  type: "session:restore";
-  turns: Turn[];
-  config?: Record<string, unknown>;
-} | {
-  type: "turn:user";
-  turn: Turn;
-} | {
-  type: "turn:start";
-  turnId: string;
-} | {
-  type: "turn:end";
-  turnId: string;
-  status: TurnStatus;
-  usage: Stats;
-  timing?: TimingInfo;
-} | {
-  type: "part:start";
-  turnId: string;
-  part: TurnPart;
-} | {
-  type: "text:delta";
-  turnId: string;
-  partId: string;
-  delta: string;
-} | {
-  type: "thinking:delta";
-  turnId: string;
-  partId: string;
-  delta: string;
-} | {
-  type: "part:end";
-  turnId: string;
-  partId: string;
-  timing?: TimingInfo;
-} | {
-  type: "action:args-delta";
-  turnId: string;
-  partId: string;
-  delta: string;
-  accumulated: string;
-} | {
-  type: "action:running";
-  turnId: string;
-  partId: string;
-  parameters?: Record<string, unknown>;
-} | {
-  type: "action:progress";
-  turnId: string;
-  partId: string;
-  chunk: string;
-} | {
-  type: "action:complete";
-  turnId: string;
-  partId: string;
-  result: ActionResult;
-} | {
-  type: "action:error";
-  turnId: string;
-  partId: string;
-  error: {
-    type: string;
-    message: string;
-  };
-} | {
-  type: "action:child-event";
-  turnId: string;
-  partId: string;
-  event: AgentEvent;
-} | {
-  type: "error";
-  error: {
-    type: string;
-    message: string;
-  };
-};
-//#endregion
 //#region src/utils/utils.d.ts
 interface Handle<T> {
   cancel(reason?: unknown): void;
@@ -854,74 +576,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;
-  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;
@@ -936,21 +737,22 @@ interface AgentErrorResult {
   usage: Stats;
 }
 type AgentHandle<T = string> = Handle<AgentResult<T> | AgentErrorResult>;
-type AgentEventCallback = (event: AgentEvent) => void;
+type TurnEventCallback = (event: TurnEvent) => void;
 interface SendMessageOptions extends AxleModelRequestOptions {
   fileResolver?: FileResolver;
 }
+//#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;
@@ -961,8 +763,24 @@ declare class Agent {
   addMcp(mcp: MCP): void;
   addMcps(mcps: MCP[]): void;
   hasTools(): boolean;
-  on(callback: AgentEventCallback): void;
+  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;
@@ -971,6 +789,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
@@ -1032,7 +861,7 @@ declare class AxleAgentAbortError extends AxleAbortError {
     usage?: Stats;
   });
   toJSON(): {
-    turn?: Turn | undefined;
+    turn?: Turn<Annotation<unknown, string>> | undefined;
     usage?: Stats | undefined;
     partial?: AxleAssistantMessage | undefined;
     messages?: AxleMessage[] | undefined;
@@ -1127,6 +956,17 @@ declare const Anthropic: {
 //#region src/providers/chatcompletions/provider.d.ts
 declare function chatCompletions(baseUrl: string, apiKey?: string): AIProvider;
 //#endregion
+//#region src/providers/context.d.ts
+interface ContextEstimateInput {
+  system?: string;
+  tools?: ToolDefinition[];
+  providerTools?: ProviderTool[];
+  mcpTools?: ToolDefinition[];
+  messages: AxleMessage[];
+  limit?: number;
+}
+declare function estimateContextUsage(input: ContextEstimateInput): ContextUsage;
+//#endregion
 //#region src/providers/gemini/provider.d.ts
 declare function gemini(apiKey: string): AIProvider;
 //#endregion
@@ -1364,124 +1204,21 @@ declare const OpenAI: {
   readonly DefaultModel: "gpt-5.4-mini";
 };
 //#endregion
-//#region src/providers/context.d.ts
-interface ContextEstimateInput {
-  system?: string;
-  tools?: ToolDefinition[];
-  providerTools?: ProviderTool[];
-  mcpTools?: ToolDefinition[];
-  messages: AxleMessage[];
-  limit?: number;
-}
-declare function estimateContextUsage(input: ContextEstimateInput): ContextUsage;
-//#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/builder.d.ts
-declare class TurnBuilder {
-  private currentTurn;
+//#region src/turns/eventBuilder.d.ts
+declare class TurnEventBuilder {
+  private currentTurnId;
+  private currentTurnTiming;
   private currentTextPart;
   private currentThinkingPart;
   private toolIdMap;
   private accumulatedUsage;
-  createUserTurn(message: AxleUserMessage): {
-    turn: Turn;
-    events: AgentEvent[];
-  };
-  startAgentTurn(): {
-    turn: Turn;
-    events: AgentEvent[];
-  };
-  handleStreamEvent(event: StreamEvent): AgentEvent[];
-  finalizeTurn(outcome?: "complete" | "cancelled" | "error"): AgentEvent[];
+  createUserTurn(message: AxleUserMessage): TurnEvent[];
+  startAgentTurn(): Extract<TurnEvent, {
+    type: "turn:start";
+  }>;
+  handleStreamEvent(event: StreamEvent): TurnEvent[];
+  finalizeTurn(outcome?: "complete" | "cancelled" | "error"): TurnEvent[];
   private closeOpenParts;
-  private findActionPart;
 }
 //#endregion
 //#region src/tracer/tracer.d.ts
@@ -1559,36 +1296,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 ActionPart, type ActionResult, Agent, type AgentConfig, type AgentEvent, type AgentEventCallback, type AgentHandle, type AgentMemory, type AgentResult, 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, TurnBuilder, 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, type AnthropicProviderConfig, AxleAbortError, AxleAgentAbortError, type AxleAssistantMessage, AxleError, type AxleMessage, type AxleModelRequestOptions, AxleStopReason, type AxleToolCallMessage, type AxleToolCallResult, AxleToolFatalError, type AxleUserMessage, type ChatCompletionsProviderConfig, 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 GeminiProviderConfig, 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, OpenAI, type OpenAIProviderConfig, type OutputSchema, type ParsedSchema, 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 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 TurnPart, type TurnStatus, addStats, anthropic, chatCompletions, createAgentConfig, createHandle, createStats, estimateContextUsage, gemini, generate, generateTurn, loadFileContent, openai, parseResponse, stream };