@fifthrevision/axle 0.19.0 → 0.21.0

package/dist/accumulator-svhGVEwB.d.ts

@@ -0,0 +1,1156 @@
+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-citation" | "text-complete" | "tool-call-start" | "tool-call-args-delta" | "tool-call-complete" | "thinking-start" | "thinking-delta" | "thinking-summary-delta" | "thinking-metadata" | "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 StreamTextCitationChunk extends StreamChunk {
+  type: "text-citation";
+  data: {
+    index: number;
+    citation: Citation;
+  };
+}
+interface StreamTextCompleteChunk extends StreamChunk {
+  type: "text-complete";
+  data: {
+    index: number;
+  };
+}
+interface StreamThinkingStartChunk extends StreamChunk {
+  type: "thinking-start";
+  data: {
+    index: number;
+    id?: string;
+    redacted?: boolean;
+    continuity?: ThinkingContinuity;
+    providerMetadata?: Record<string, unknown>;
+  };
+}
+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 StreamThinkingMetadataChunk extends StreamChunk {
+  type: "thinking-metadata";
+  data: {
+    index: number;
+    continuity?: ThinkingContinuity;
+    redacted?: boolean;
+    providerMetadata?: Record<string, unknown>;
+  };
+}
+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 | StreamTextCitationChunk | StreamTextCompleteChunk | StreamThinkingStartChunk | StreamThinkingDeltaChunk | StreamThinkingSummaryDeltaChunk | StreamThinkingMetadataChunk | 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;
+  };
+};
+type ConcreteFileInfo = FileInfo & {
+  source: {
+    type: "text";
+  } | {
+    type: "base64";
+  } | {
+    type: "url";
+  };
+};
+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;
+};
+interface FileResolveRequest {
+  file: DeferredFileInfo;
+  ref: unknown;
+  provider: FileProviderId;
+  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
+/**
+ * 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;
+}
+interface AIProvider {
+  get name(): string;
+  /** @internal */
+  createGenerationRequest(model: string, params: ProviderGenerationParams): Promise<ModelResult>;
+  /** @internal */
+  createStreamingRequest(model: string, params: ProviderStreamParams): AsyncGenerator<AnyStreamChunk, void, unknown>;
+}
+/**
+ * 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 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;
+interface ContextUsage {
+  total: number;
+  system: number;
+  tools: number;
+  mcpTools: number;
+  providerTools: number;
+  messages: number;
+  limit?: number;
+  free?: number;
+}
+/**
+ * Client-level transport options for provider adapters.
+ *
+ * These options are applied when the provider client is constructed, not per
+ * model request.
+ */
+interface ProviderClientOptions {
+  /**
+   * Number of retry attempts after the first request. Axle's built-in
+   * providers default to `2`; use `0` to disable retries.
+   */
+  maxRetries?: number;
+  /**
+   * Request timeout in milliseconds. Omit to use the provider SDK default.
+   */
+  timeoutMs?: number;
+}
+declare enum AxleStopReason {
+  Stop = "stop",
+  Length = "length",
+  FunctionCall = "function_call",
+  Error = "error",
+  Custom = "custom",
+  Cancelled = "cancelled"
+}
+//#endregion
+//#region src/messages/message.d.ts
+/**
+ * Model-facing conversation message.
+ *
+ * This is Axle's canonical conversation state. Providers consume these
+ * messages after adapter-specific conversion, while turns are derived from
+ * them for presentation.
+ */
+type AxleMessage = AxleUserMessage | AxleAssistantMessage | AxleToolCallMessage;
+/**
+ * Host-owned render metadata attached to a message.
+ *
+ * Providers ignore this data; it exists so hosts can carry stable presentation
+ * hints through history and into renderable turns.
+ */
+type MessageMetadata = Record<string, unknown>;
+/**
+ * Content returned by a tool call.
+ *
+ * Tool results may be simple text or structured parts when the result includes
+ * file data.
+ */
+type ToolResultPart = {
+  type: "text";
+  text: string;
+} | {
+  type: "file";
+  file: ConcreteFileInfo;
+};
+/**
+ * Message authored by the user or host application.
+ */
+interface AxleUserMessage {
+  /** Message role discriminator. */
+  role: "user";
+  /** Stable message id. Generated by Axle when a user turn is compiled. */
+  id?: string;
+  /** Optional user name passed through to providers that support it. */
+  name?: string;
+  /** User-authored text or mixed content parts. */
+  content: string | Array<ContentPart>;
+  /** Stable host-owned render metadata copied to the corresponding user turn. */
+  metadata?: MessageMetadata;
+}
+/**
+ * Message authored by the assistant/model.
+ */
+interface AxleAssistantMessage {
+  /** Message role discriminator. */
+  role: "assistant";
+  /** Stable assistant message id. */
+  id: string;
+  /** Model identifier that produced this message, when known. */
+  model?: string;
+  /** Assistant content parts in model order. */
+  content: Array<ContentPartText | ContentPartThinking | ContentPartToolCall | ContentPartProviderTool>;
+  /** Provider-normalized reason the assistant message stopped. */
+  finishReason?: AxleStopReason;
+}
+/**
+ * Message carrying results for one or more tool calls.
+ */
+interface AxleToolCallMessage {
+  /** Message role discriminator. */
+  role: "tool";
+  /** Stable tool-result message id. */
+  id: string;
+  /** Tool call results included in this message. */
+  content: Array<AxleToolCallResult>;
+}
+/**
+ * Result payload for a single tool call.
+ */
+interface AxleToolCallResult {
+  /** Tool call id this result answers. */
+  id: string;
+  /** Tool name that produced the result. */
+  name: string;
+  /** Tool result content. */
+  content: string | ToolResultPart[];
+  /** Whether the tool result represents an execution error. */
+  isError?: boolean;
+}
+/**
+ * Any content part Axle can carry in a user or assistant message.
+ */
+type ContentPart = ContentPartText | ContentPartFile | ContentPartToolCall | ContentPartThinking | ContentPartProviderTool;
+/**
+ * Plain text content.
+ */
+interface ContentPartText {
+  /** Part discriminator. */
+  type: "text";
+  /** Text content. */
+  text: string;
+  /** Source citations that support spans of this text, when supplied by the provider. */
+  citations?: Citation[];
+  /** Provider-specific metadata that is not part of Axle's normalized contract. */
+  providerMetadata?: Record<string, unknown>;
+}
+/**
+ * File attachment content.
+ */
+interface ContentPartFile {
+  /** Part discriminator. */
+  type: "file";
+  /** File metadata and source reference. */
+  file: FileInfo;
+}
+/**
+ * Model reasoning or thinking content.
+ */
+interface ContentPartThinking {
+  /** Part discriminator. */
+  type: "thinking";
+  /** Provider thinking block id, when supplied. */
+  id?: string;
+  /** Renderable reasoning text content, when the provider exposes it. */
+  text?: string;
+  /** Optional provider-supplied reasoning summary. */
+  summary?: string;
+  /** Whether the provider redacted the reasoning content. */
+  redacted?: boolean;
+  /** Provider continuity payload that should be preserved for future requests. */
+  continuity?: ThinkingContinuity;
+  /** Provider-specific metadata that is not part of Axle's normalized contract. */
+  providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Source attribution attached to model text.
+ *
+ * Providers expose citations with different source records and locator
+ * metadata. Axle keeps the common renderable surface small: what source is
+ * cited, and where that citation applies in the generated output text.
+ */
+interface Citation {
+  /** Source being cited. */
+  source: CitationSource;
+  /** Character/byte offsets in the generated output text, when supplied. */
+  outputSpan?: CitationOutputSpan;
+  /** Provider-specific citation payload fields not covered by the normalized shape. */
+  providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Citation source categories Axle currently normalizes from provider APIs.
+ */
+type CitationSource = {
+  type: "web";
+  title?: string;
+  url: string;
+  citedText?: string;
+} | {
+  type: "document";
+  title?: string;
+  fileId?: string;
+  citedText?: string;
+  locator?: DocumentLocator;
+} | {
+  type: "search-result";
+  title?: string;
+  url?: string;
+  citedText?: string;
+  locator?: DocumentLocator;
+} | {
+  type: "retrieved-context";
+  title?: string;
+  uri?: string;
+  citedText?: string;
+  locator?: DocumentLocator;
+} | {
+  type: "unknown";
+  citedText?: string;
+};
+/**
+ * Provider-reported location inside a cited source.
+ */
+type DocumentLocator = {
+  type: "char";
+  start?: number;
+  end?: number;
+} | {
+  type: "page";
+  start?: number;
+  end?: number;
+} | {
+  type: "block";
+  start?: number;
+  end?: number;
+} | {
+  type: "part";
+  index?: number;
+};
+/**
+ * Citation coordinates in generated output text.
+ */
+interface CitationOutputSpan {
+  /** Inclusive output offset. */
+  start?: number;
+  /** Exclusive output offset. */
+  end?: number;
+}
+/**
+ * Opaque provider state needed to continue reasoning across requests.
+ */
+type ThinkingContinuity = {
+  provider: "openai";
+  encrypted: string;
+} | {
+  provider: "anthropic";
+  signature?: string;
+  redactedData?: string;
+} | {
+  provider: "gemini";
+  thoughtSignature: string;
+};
+/**
+ * Axle-managed tool call request emitted by the assistant.
+ */
+interface ContentPartToolCall {
+  /** Part discriminator. */
+  type: "tool-call";
+  /** Tool call id used to pair the call with its result. */
+  id: string;
+  /** Tool name to execute. */
+  name: string;
+  /** Parsed tool parameters. */
+  parameters: Record<string, unknown>;
+  /** Provider-specific metadata associated with the tool call. */
+  providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Provider-managed built-in tool call or result.
+ */
+interface ContentPartProviderTool {
+  /** Part discriminator. */
+  type: "provider-tool";
+  /** Provider tool call id. */
+  id: string;
+  /** Provider tool name. */
+  name: string;
+  /** Provider-specific tool input. */
+  input?: unknown;
+  /** Provider-specific tool output. */
+  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/turns/types.d.ts
+/**
+ * Lifecycle state for a renderable turn.
+ *
+ * Turns are presentation state. They describe what a consumer can render, not
+ * the canonical model conversation state.
+ */
+type TurnStatus = "streaming" | "complete" | "cancelled" | "error";
+/**
+ * Host-owned stable render metadata attached to a turn.
+ *
+ * Metadata is not model state and has no lifecycle. Use annotations for
+ * mutable, async, or explicitly placed UI state.
+ */
+type TurnMetadata = Record<string, unknown>;
+/**
+ * ISO timestamp metadata for a turn, part, action, or annotation.
+ */
+interface TimingInfo {
+  /** ISO timestamp for when the item started. */
+  start: string;
+  /** ISO timestamp for when the item finished, when known. */
+  end?: string;
+}
+/**
+ * Where an annotation should render relative to its target.
+ */
+type AnnotationPlacement = "before" | "after";
+/**
+ * Lifecycle state for an annotation.
+ *
+ * Omit this for static/informational annotations that do not have a running or
+ * terminal state.
+ */
+type AnnotationStatus = "running" | "complete" | "cancelled" | "error";
+/**
+ * Render metadata attached to a session, turn, or turn part.
+ *
+ * Annotations let hosts attach out-of-band UI such as sandbox startup, eval
+ * results, or deployment state without turning that data into model state.
+ *
+ * @typeParam TData - Consumer-owned payload for the annotation kind.
+ * @typeParam TKind - Discriminator for the annotation kind.
+ */
+interface Annotation<TData = unknown, TKind extends string = string> {
+  /** Globally unique annotation id. */
+  id: string;
+  /** Consumer-defined annotation kind, used as a discriminator. */
+  kind: TKind;
+  /** Human-readable label for generic renderers. */
+  label: string;
+  /** Render placement relative to the target. Defaults to `"after"` when accumulated. */
+  placement?: AnnotationPlacement;
+  /** Optional lifecycle state for the annotation. */
+  status?: AnnotationStatus;
+  /** Consumer-owned annotation payload. */
+  data?: TData;
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * Renderable presentation state for one user or agent turn.
+ *
+ * `Turn` is the snapshot counterpart to `TurnEvent`: events describe changes,
+ * and turns are the accumulated render state. The model-facing conversation
+ * remains `AxleMessage[]`.
+ *
+ * @typeParam TAnnotation - Annotation union supported by the host renderer.
+ */
+interface Turn<TAnnotation extends Annotation = Annotation> {
+  /** Stable turn id. */
+  id: string;
+  /** Whether the turn was produced by the user or the agent. */
+  owner: "user" | "agent";
+  /** Renderable parts in display order. */
+  parts: TurnPart<TAnnotation>[];
+  /** Current lifecycle state for the turn. */
+  status: TurnStatus;
+  /** Annotations attached to the whole turn. */
+  annotations?: TAnnotation[];
+  /** Stable host-owned render metadata copied from the source message. */
+  metadata?: TurnMetadata;
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+  /** Token usage accumulated for this turn, when available. */
+  usage?: Stats;
+}
+/**
+ * Any renderable part within a turn.
+ */
+type TurnPart<TAnnotation extends Annotation = Annotation> = TextPart<TAnnotation> | FilePart<TAnnotation> | ThinkingPart<TAnnotation> | ActionPart<TAnnotation>;
+/**
+ * Assistant or user text content.
+ */
+interface TextPart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. */
+  id: string;
+  /** Part discriminator. */
+  type: "text";
+  /** Accumulated text content. */
+  text: string;
+  /** Source citations that support spans of this text, when supplied by the provider. */
+  citations?: Citation[];
+  /** Provider-specific metadata that is not part of Axle's normalized contract. */
+  providerMetadata?: Record<string, unknown>;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * File content attached to a user turn.
+ */
+interface FilePart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. */
+  id: string;
+  /** Part discriminator. */
+  type: "file";
+  /** File metadata and source reference. */
+  file: FileInfo;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * Model thinking or reasoning content when surfaced by the provider.
+ */
+interface ThinkingPart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. */
+  id: string;
+  /** Part discriminator. */
+  type: "thinking";
+  /** Accumulated renderable thinking text, when the provider exposes it. */
+  text?: string;
+  /** Optional provider-supplied summary. */
+  summary?: string;
+  /** Whether the provider marked the thinking content as redacted. */
+  redacted?: boolean;
+  /** Provider continuity payload that should be preserved for future requests. */
+  continuity?: ThinkingContinuity;
+  /** Provider-specific metadata that is not part of Axle's normalized contract. */
+  providerMetadata?: Record<string, unknown>;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * Shared fields for tool, subagent, and provider-managed actions.
+ *
+ * @internal
+ */
+interface ActionPartBase<TAnnotation extends Annotation = Annotation> {
+  id: string;
+  type: "action";
+  kind: string;
+  status: "pending" | "running" | "complete" | "cancelled" | "error";
+  annotations?: TAnnotation[];
+  timing?: TimingInfo;
+}
+/**
+ * Action part for an executable Axle tool call.
+ */
+interface ToolAction<TAnnotation extends Annotation = Annotation> extends ActionPartBase<TAnnotation> {
+  /** Action discriminator. */
+  kind: "tool";
+  /** Tool display and execution details. */
+  detail: {
+    /** Tool name. */name: string; /** Parsed tool parameters once execution starts. */
+    parameters: Record<string, unknown>; /** Accumulated JSON argument text before parameters are parsed. */
+    pendingArgs?: string; /** Tool result or in-progress output. */
+    result?: ActionResult;
+  };
+}
+/**
+ * Action part for a nested agent/subagent run.
+ */
+interface SubagentAction<TAnnotation extends Annotation = Annotation> extends ActionPartBase<TAnnotation> {
+  /** Action discriminator. */
+  kind: "agent";
+  /** Subagent display and result details. */
+  detail: {
+    /** Subagent name. */name: string; /** Optional subagent configuration shown to renderers. */
+    config?: Record<string, unknown>; /** Child turns produced by the subagent. */
+    children: Turn<TAnnotation>[]; /** Final subagent result, when available. */
+    result?: ActionResult;
+  };
+}
+/**
+ * Action part for provider-managed tools such as hosted web search or code
+ * execution.
+ */
+interface ProviderToolAction<TAnnotation extends Annotation = Annotation> extends ActionPartBase<TAnnotation> {
+  /** Action discriminator. */
+  kind: "provider-tool";
+  /** Provider tool display and result details. */
+  detail: {
+    /** Provider tool name. */name: string; /** Provider-specific input, when surfaced. */
+    input?: unknown; /** Provider tool result, when surfaced. */
+    result?: ActionResult;
+  };
+}
+/**
+ * Any action part in a turn.
+ */
+type ActionPart<TAnnotation extends Annotation = Annotation> = ToolAction<TAnnotation> | SubagentAction<TAnnotation> | ProviderToolAction<TAnnotation>;
+/**
+ * Renderable result for an action.
+ */
+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 AnnotationTarget = {
+  type: "session";
+} | {
+  type: "turn";
+  turnId: string;
+} | {
+  type: "part";
+  turnId: string;
+  partId: string;
+};
+type AnnotationEvent<TAnnotation extends Annotation = Annotation> = {
+  type: "annotation:start";
+  target: AnnotationTarget;
+  annotation: TAnnotation;
+} | {
+  type: "annotation:update";
+  target: AnnotationTarget;
+  annotation: TAnnotation;
+} | {
+  type: "annotation:end";
+  target: AnnotationTarget;
+  annotation: TAnnotation;
+};
+type TurnEvent<TAnnotation extends Annotation = Annotation> = {
+  type: "session:restore";
+  turns: Turn<TAnnotation>[];
+  sessionAnnotations?: TAnnotation[];
+  config?: Record<string, unknown>;
+} | {
+  type: "turn:user";
+  turn: Turn<TAnnotation>;
+} | {
+  type: "turn:start";
+  turnId: string;
+  timing?: TimingInfo;
+} | {
+  type: "turn:end";
+  turnId: string;
+  status: TurnStatus;
+  usage: Stats;
+  timing?: TimingInfo;
+} | {
+  type: "part:start";
+  turnId: string;
+  part: TurnPart<TAnnotation>;
+} | {
+  type: "text:delta";
+  turnId: string;
+  partId: string;
+  delta: string;
+} | {
+  type: "text:citation";
+  turnId: string;
+  partId: string;
+  citation: Citation;
+} | {
+  type: "thinking:delta";
+  turnId: string;
+  partId: string;
+  delta: string;
+} | {
+  type: "thinking:summary-delta";
+  turnId: string;
+  partId: string;
+  delta: string;
+} | {
+  type: "thinking:update";
+  turnId: string;
+  partId: string;
+  redacted?: boolean;
+  continuity?: ThinkingContinuity;
+  providerMetadata?: Record<string, unknown>;
+} | {
+  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;
+  timing?: TimingInfo;
+} | {
+  type: "action:error";
+  turnId: string;
+  partId: string;
+  error: {
+    type: string;
+    message: string;
+  };
+  timing?: TimingInfo;
+} | {
+  type: "action:child-event";
+  turnId: string;
+  partId: string;
+  event: TurnEvent<TAnnotation>;
+} | AnnotationEvent<TAnnotation> | {
+  type: "error";
+  error: {
+    type: string;
+    message: string;
+  };
+};
+//#endregion
+//#region src/turns/accumulator.d.ts
+interface TurnAccumulatorState<TAnnotation extends Annotation = Annotation> {
+  turns: Turn<TAnnotation>[];
+  sessionAnnotations?: TAnnotation[];
+}
+type UnknownEvent = {
+  type: string;
+};
+type AccumulatableEvent<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> = TurnEvent<TAnnotation> | THostEvent;
+type TurnAccumulatorResult<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> = {
+  handled: true;
+  state: TurnAccumulatorState<TAnnotation>;
+  event: TurnEvent<TAnnotation>;
+} | {
+  handled: false;
+  state: TurnAccumulatorState<TAnnotation>;
+  event: THostEvent;
+};
+declare class TurnAccumulator<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> {
+  private _state;
+  constructor(init?: TurnAccumulatorState<TAnnotation>);
+  get state(): TurnAccumulatorState<TAnnotation>;
+  apply(event: AccumulatableEvent<TAnnotation, THostEvent>): TurnAccumulatorResult<TAnnotation, THostEvent>;
+  private replaceState;
+  private replaceTurns;
+  private updateTurn;
+  private updatePart;
+  private addAnnotation;
+  private replaceAnnotation;
+  private handled;
+}
+//#endregion
+export { ModelResult as $, AxleAssistantMessage as A, ContentPartProviderTool as B, TurnPart as C, ToolContext as D, ProviderTool as E, Citation as F, MessageMetadata as G, ContentPartThinking as H, CitationOutputSpan as I, AIProvider as J, ThinkingContinuity as K, CitationSource as L, AxleToolCallMessage as M, AxleToolCallResult as N, ToolDefinition as O, AxleUserMessage as P, ModelError as Q, ContentPart as R, TurnMetadata as S, ExecutableTool as T, ContentPartToolCall as U, ContentPartText as V, DocumentLocator as W, AxleStopReason as X, AxleModelRequestOptions as Y, ContextUsage as Z, TextPart as _, TraceWriter as _t, UnknownEvent as a, FileKind as at, ToolAction as b, TurnEvent as c, FileResolveRequest as ct, Annotation as d, loadFileContent as dt, ProviderClientOptions as et, AnnotationPlacement as f, EventLevel as ft, SubagentAction as g, SpanType as gt, ProviderToolAction as h, SpanOptions as ht, TurnAccumulatorState as i, FileInfo as it, AxleMessage as j, ToolRegistry as k, ActionPart as l, FileResolver as lt, FilePart as m, SpanEvent as mt, TurnAccumulator as n, ToolChoice as nt, AnnotationEvent as o, FileProviderId as ot, AnnotationStatus as p, SpanData as pt, ToolResultPart as q, TurnAccumulatorResult as r, DeferredFileInfo as rt, AnnotationTarget as s, FileResolveFormat as st, AccumulatableEvent as t, ProviderOptions as tt, ActionResult as u, ResolvedFileSource as ut, ThinkingPart as v, TracingContext as vt, TurnStatus as w, Turn as x, TimingInfo as y, Stats as yt, ContentPartFile as z };