@fifthrevision/axle 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -1,12 +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
-interface Stats {
-  in: number;
-  out: 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";
@@ -132,220 +127,94 @@ 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;
-}
-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>;
+//#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;
 }
 /**
- * Tracing context for a span. Created by Tracer.startSpan().
- * Can create child spans and log events within the span's scope.
+ * Raw provider-specific request fields.
+ *
+ * Provider adapters apply this after Axle-normalized options, so these values
+ * can intentionally override Axle's provider mappings.
  */
-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;
+interface ProviderOptions {
+  [key: string]: any;
 }
-//#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;
+/**
+ * Controls how the model may use tools during a single model request.
+ */
+type ToolChoice = "auto" | "none" | "required" | {
+  type: "tool";
   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
+ * 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.
  */
-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
-interface ProviderRequestContext {
-  tracer?: TracingContext;
-  fileResolver?: FileResolver;
-}
-interface GenerateTurnOptions {
+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;
-  top_p?: number;
-  max_tokens?: number;
-  frequency_penalty?: number;
-  presence_penalty?: number;
+  /** Nucleus sampling value, mapped to provider-specific casing. */
+  topP?: number;
+  /** Stop sequence or sequences for text generation. */
   stop?: string | string[];
-  [key: string]: any;
+  /** 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 GenerationRequestParams {
+/**
+ * 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>;
-  context: ProviderRequestContext;
-  options?: GenerateTurnOptions;
-  reasoning?: boolean;
-  signal?: AbortSignal;
+  /** Provider-managed tools such as web search or code execution. */
+  providerTools?: Array<ProviderTool>;
+  /** Internal services available during provider request creation. */
+  runtime: ProviderRuntime;
 }
-interface StreamingRequestParams extends GenerationRequestParams {
-  signal?: AbortSignal;
+/**
+ * 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: GenerationRequestParams): Promise<ModelResult>;
+  createGenerationRequest(model: string, params: ProviderGenerationParams): Promise<ModelResult>;
   /** @internal */
-  createStreamingRequest(model: string, params: StreamingRequestParams): AsyncGenerator<AnyStreamChunk, void, unknown>;
+  createStreamingRequest(model: string, params: ProviderStreamParams): AsyncGenerator<AnyStreamChunk, void, unknown>;
 }
 interface ModelResponse {
   type: "success";
@@ -445,7 +314,8 @@ interface ContentPartProviderTool {
 //#endregion
 //#region src/tools/registry.d.ts
 declare class ToolRegistry {
-  private executableTools;
+  private tools;
+  private mcpTools;
   private providerTools;
   constructor(init?: {
     tools?: ExecutableTool[];
@@ -453,6 +323,8 @@ declare class ToolRegistry {
   });
   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;
@@ -460,6 +332,8 @@ declare class ToolRegistry {
   get(name: string): ExecutableTool | undefined;
   getProvider(name: string): ProviderTool | undefined;
   executable(): ExecutableTool[];
+  local(): ExecutableTool[];
+  mcp(): ExecutableTool[];
   provider(): ProviderTool[];
   get size(): number;
 }
@@ -602,167 +476,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;
@@ -790,6 +503,7 @@ declare class History {
   get turns(): Turn[];
   get log(): AxleMessage[];
   addTurn(turn: Turn): void;
+  replaceTurns(turns: Turn[]): void;
   appendToLog(messages: AxleMessage | AxleMessage[]): void;
   latestTurn(): Turn | undefined;
   toString(): string;
@@ -834,7 +548,7 @@ declare class Instruct<TSchema extends OutputSchema | undefined = undefined> {
 }
 //#endregion
 //#region src/core/Agent.d.ts
-interface AgentConfig {
+interface AgentConfig extends Omit<AxleModelRequestOptions, "signal"> {
   provider: AIProvider;
   model: string;
   system?: string;
@@ -846,7 +560,6 @@ interface AgentConfig {
   memory?: AgentMemory;
   tracer?: TracingContext;
   fileResolver?: FileResolver;
-  reasoning?: boolean;
 }
 interface AgentResult<T = string> {
   ok: true;
@@ -862,11 +575,9 @@ interface AgentErrorResult {
   usage: Stats;
 }
 type AgentHandle<T = string> = Handle<AgentResult<T> | AgentErrorResult>;
-type AgentEventCallback = (event: AgentEvent) => void;
-interface SendMessageOptions {
-  signal?: AbortSignal;
+type TurnEventCallback = (event: TurnEvent) => void;
+interface SendMessageOptions extends AxleModelRequestOptions {
   fileResolver?: FileResolver;
-  reasoning?: boolean;
 }
 declare class Agent {
   readonly provider: AIProvider;
@@ -877,7 +588,7 @@ declare class Agent {
   readonly scope?: Record<string, string>;
   readonly store: FileStore;
   readonly fileResolver?: FileResolver;
-  readonly reasoning?: boolean;
+  readonly requestOptions: Omit<AxleModelRequestOptions, "signal">;
   readonly registry: ToolRegistry;
   system: string | undefined;
   private mcps;
@@ -889,11 +600,13 @@ declare class Agent {
   addMcp(mcp: MCP): void;
   addMcps(mcps: MCP[]): void;
   hasTools(): boolean;
-  on(callback: AgentEventCallback): void;
+  on(callback: TurnEventCallback): void;
+  context(): ContextUsage;
   send(message: string | Instruct<undefined>, options?: SendMessageOptions): AgentHandle<string>;
   send<TSchema extends OutputSchema>(instruct: Instruct<TSchema>, options?: SendMessageOptions): AgentHandle<ParsedSchema<TSchema>>;
   private resolveMcpTools;
   private emitEvent;
+  private toToolDefinitions;
   private run;
 }
 //#endregion
@@ -958,7 +671,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;
@@ -1053,6 +766,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
@@ -1068,6 +792,7 @@ declare const Gemini: {
     readonly GEMINI_3_PRO: "gemini-3-pro-preview";
     readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
     readonly GEMINI_3_FLASH: "gemini-3-flash-preview";
+    readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
     readonly GEMINI_2_5_PRO: "gemini-2.5-pro";
     readonly GEMINI_2_5_FLASH: "gemini-2.5-flash";
     readonly GEMINI_2_5_FLASH_LITE: "gemini-2.5-flash-lite";
@@ -1082,23 +807,8 @@ declare const Gemini: {
   readonly DefaultModel: "gemini-3.1-flash-lite-preview";
 };
 //#endregion
-//#region src/providers/generateTurn.d.ts
-interface GenerateTurnProps {
-  provider: AIProvider;
-  model: string;
-  messages: Array<AxleMessage>;
-  system?: string;
-  tools?: Array<ToolDefinition>;
-  tracer?: TracingContext;
-  fileResolver?: FileResolver;
-  options?: GenerateTurnOptions;
-  reasoning?: boolean;
-  signal?: AbortSignal;
-}
-declare function generateTurn(props: GenerateTurnProps): Promise<ModelResult>;
-//#endregion
 //#region src/providers/generate.d.ts
-interface GenerateOptions {
+interface GenerateParams extends AxleModelRequestOptions {
   provider: AIProvider;
   model: string;
   messages: Array<AxleMessage>;
@@ -1110,17 +820,27 @@ interface GenerateOptions {
   maxIterations?: number;
   tracer?: TracingContext;
   fileResolver?: FileResolver;
-  options?: GenerateTurnOptions;
-  reasoning?: boolean;
-  signal?: AbortSignal;
 }
-interface GenerateInstructOptions<TSchema extends OutputSchema | undefined> extends Omit<GenerateOptions, "messages"> {
+interface GenerateInstructParams<TSchema extends OutputSchema | undefined> extends Omit<GenerateParams, "messages"> {
   messages?: Array<AxleMessage>;
   instruct: Instruct<TSchema>;
 }
 type GenerateInstructResult<TSchema extends OutputSchema | undefined> = GenerateResult<InstructResponse<TSchema>>;
-declare function generate<TSchema extends OutputSchema | undefined>(options: GenerateInstructOptions<TSchema>): Promise<GenerateInstructResult<TSchema>>;
-declare function generate(options: GenerateOptions): Promise<GenerateResult>;
+declare function generate<TSchema extends OutputSchema | undefined>(options: GenerateInstructParams<TSchema>): Promise<GenerateInstructResult<TSchema>>;
+declare function generate(options: GenerateParams): Promise<GenerateResult>;
+//#endregion
+//#region src/providers/generateTurn.d.ts
+interface GenerateTurnParams extends AxleModelRequestOptions {
+  provider: AIProvider;
+  model: string;
+  messages: Array<AxleMessage>;
+  system?: string;
+  tools?: Array<ToolDefinition>;
+  providerTools?: Array<ProviderTool>;
+  tracer?: TracingContext;
+  fileResolver?: FileResolver;
+}
+declare function generateTurn(props: GenerateTurnParams): Promise<ModelResult>;
 //#endregion
 //#region src/providers/stream.d.ts
 type StreamEvent = {
@@ -1207,7 +927,7 @@ type StreamEvent = {
   error: GenerateError;
 };
 type StreamEventCallback = (event: StreamEvent) => void;
-interface StreamOptions {
+interface StreamParams extends AxleModelRequestOptions {
   provider: AIProvider;
   model: string;
   messages: Array<AxleMessage>;
@@ -1219,16 +939,13 @@ interface StreamOptions {
   maxIterations?: number;
   tracer?: TracingContext;
   fileResolver?: FileResolver;
-  options?: GenerateTurnOptions;
-  reasoning?: boolean;
-  signal?: AbortSignal;
 }
 interface StreamHandle {
   on(callback: StreamEventCallback): void;
   cancel(reason?: unknown): void;
   readonly final: Promise<StreamResult>;
 }
-interface StreamInstructOptions<TSchema extends OutputSchema | undefined> extends Omit<StreamOptions, "messages"> {
+interface StreamInstructParams<TSchema extends OutputSchema | undefined> extends Omit<StreamParams, "messages"> {
   messages?: Array<AxleMessage>;
   instruct: Instruct<TSchema>;
 }
@@ -1236,8 +953,8 @@ type StreamInstructResult<TSchema extends OutputSchema | undefined> = StreamResu
 interface StreamInstructHandle<TSchema extends OutputSchema | undefined> extends Omit<StreamHandle, "final"> {
   readonly final: Promise<StreamInstructResult<TSchema>>;
 }
-declare function stream<TSchema extends OutputSchema | undefined>(options: StreamInstructOptions<TSchema>): StreamInstructHandle<TSchema>;
-declare function stream(options: StreamOptions): StreamHandle;
+declare function stream<TSchema extends OutputSchema | undefined>(options: StreamInstructParams<TSchema>): StreamInstructHandle<TSchema>;
+declare function stream(options: StreamParams): StreamHandle;
 //#endregion
 //#region src/providers/openai/provider.d.ts
 declare function openai(apiKey: string): AIProvider;
@@ -1385,25 +1102,21 @@ declare const writeFileSchema: z.ZodObject<{
 }, 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
@@ -1513,4 +1226,4 @@ declare class LocalFileStore implements FileStore {
   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, AxleStopReason, type AxleToolCallMessage, type AxleToolCallResult, AxleToolFatalError, type AxleUserMessage, type ContentPart, type ContentPartFile, type ContentPartProviderTool, type ContentPartText, type ContentPartThinking, type ContentPartToolCall, type DeferredFileInfo, type EventLevel, type ExecutableTool, type FileInfo, type FileKind, type FilePart, type FileProviderId, type FileResolveFormat, type FileResolveRequest, type FileResolver, type FileStore, Gemini, type GenerateInstructOptions, type GenerateInstructResult, 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 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 StreamInstructOptions, type StreamInstructResult, type StreamResult, type SubagentAction, TaskError, type TextPart, type ThinkingPart, type ToolAction, type ToolContext, type ToolDefinition, ToolRegistry, type ToolResultPart, type TraceWriter, Tracer, type TracingContext, type Turn, TurnBuilder, type TurnPart, type TurnStatus, anthropic, braveSearchTool, calculatorTool, chatCompletions, createHandle, execTool, gemini, generate, generateTurn, loadFileContent, openai, parseResponse, patchFileTool, readFileTool, stream, writeFileTool };
+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 };