@moureau/pipeflow 0.0.1 → 0.0.2

package/dist/types/conversations/stream/conversation-stream.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ConversationStream — the conversation's semantic reply stream.
+ *
+ * Turns a Conversation's event stream (LLM text fragments + generation
+ * completion) into FieldStream completion events: consumers act on partial
+ * reply text without waiting for the reply to finish.
+ *
+ *   const replies = new ConversationStream(conversation);
+ *   replies.whenItem("text", (fragment, i) => render(fragment));
+ *   replies.when("agent", (agent) => showSpeaker(agent));
+ *   replies.whenObjectDone((reply) => finalize(reply));
+ *   replies.cancel(); // aborts the current generation (interrupts the LLM)
+ *
+ * One semantic object per top-level generation (agent or coordination
+ * reply). The `text` field is an ordered sequence of completed text
+ * fragments — semantically "the next fragment of the reply arrived", not
+ * "whatever happened to be inside a provider SSE packet". Fragment sizes are
+ * an implementation detail of the producer and may be coalesced later.
+ *
+ * Lifecycle per reply:
+ *
+ *   first fragment ──▶ STREAMING ──generation-complete──▶ DONE
+ *                          ├──cancel()/interrupt──▶ CANCELLED
+ *                          └──provider error──────▶ FAILED
+ *
+ * Each boundary fires at most once; no completion event fires after a
+ * terminal state. Interruptions and errors leave already-delivered fragments
+ * as valid partial state. Delegated sub-generation results do not terminate
+ * the top-level reply — only the top-level generation's completion does.
+ */
+import { FieldStream } from "../../transport/streamobject/field-stream/field-stream.js";
+import type { Conversation } from "../conversation/conversation.js";
+export declare class ConversationStream extends FieldStream {
+    private readonly unsubscribers;
+    private active;
+    constructor(conversation: Conversation);
+    /** Stop listening to the conversation. */
+    dispose(): void;
+    private onDelta;
+    private completeReply;
+    private abortReply;
+}

package/dist/types/conversations/stream/index.d.ts

@@ -0,0 +1 @@
+export { ConversationStream } from "./conversation-stream.js";

package/dist/types/conversations/types.d.ts

@@ -24,6 +24,29 @@ export interface Turn {
     endedAt: number;
 }
 export type GenerationStatus = "streaming" | "completed" | "cancelled";
+/**
+ * Latency instrumentation for a generation. Times are epoch milliseconds;
+ * only `startedAt` is always present. The chain distinguishes each hop:
+ *
+ * ```text
+ * turn → first LLM token → first TTS text (buffering flush)
+ *     → TTS requested → TTS first audio → audio delivered → completed
+ * ```
+ */
+export interface GenerationTiming {
+    startedAt: number;
+    /** First LLM delta of this generation (first-token latency). */
+    firstTokenAt?: number;
+    /** First sentence flushed to TTS (text buffering latency). */
+    firstTtsTextAt?: number;
+    /** First TTS stream request issued (queue latency). */
+    firstTtsRequestAt?: number;
+    /** First audio chunk produced by the TTS provider (provider latency). */
+    firstTtsAudioAt?: number;
+    /** First TTS audio chunk delivered to the application (transport latency). */
+    firstAudioAt?: number;
+    completedAt?: number;
+}
 export interface Generation {
     id: string;
     conversationId: ConversationId;
@@ -32,6 +55,15 @@ export interface Generation {
     status: GenerationStatus;
     startedAt: number;
     endedAt?: number;
+    /**
+     * "sub" marks a task dispatched to another agent by the coordinator.
+     * Regular agent replies omit this field.
+     */
+    kind?: "sub";
+    /** For sub-generations: the id of the coordinator generation that dispatched them. */
+    parentGenerationId?: string;
+    /** Latency instrumentation, recorded as the generation streams. */
+    timing?: GenerationTiming;
 }
 export interface ToolCall {
     id: string;

package/dist/types/index.d.ts

@@ -1,44 +1,11 @@
-import { Agent, type AgentOptions } from "./agents/agent.js";
-import { Conversations } from "./conversations/conversations.js";
-import type { Persistence } from "./persistence/persistence.js";
-import type { LLM } from "./providers/llm/types.js";
-import type { STT } from "./providers/stt/types.js";
-import type { TTS } from "./providers/tts/types.js";
-export interface PipeflowOptions {
-    llm?: LLM;
-    stt?: STT;
-    tts?: TTS;
-    persistence?: Persistence;
-}
-/**
- * The Pipeflow entry point.
- *
- * ```ts
- * const pipeflow = new Pipeflow({ llm });
- * const agent = pipeflow.agent({ name: "Jarvis", context: "..." });
- * const conversation = await pipeflow.conversations.create({ agents: [agent] });
- * ```
- */
-export declare class Pipeflow {
-    readonly llm: LLM | undefined;
-    readonly stt: STT | undefined;
-    readonly tts: TTS | undefined;
-    readonly conversations: Conversations;
-    constructor(options?: PipeflowOptions);
-    /**
-     * Create an agent. Agents inherit the Pipeflow instance's LLM provider so
-     * `agent.run()` works out of the box.
-     */
-    agent(options: Omit<AgentOptions, "llm"> & {
-        llm?: LLM;
-    }): Agent;
-}
-export { Agent };
+export { Pipeflow } from "./pipeflow.js";
+export type { PipeflowOptions } from "./pipeflow.js";
+export { Agent } from "./agents/agent.js";
 export type { AgentOptions, AgentRunRequest, AgentRunResult, ExecutedToolCall, } from "./agents/agent.js";
 export { Tool, Tool as PipeflowTool } from "./agents/tools/tools.js";
 export type { ToolOptions } from "./agents/tools/tools.js";
-export { Conversation, Conversations, Orchestrator, Transcription, TranscriptEntry, } from "./conversations/index.js";
-export type { AudioChunk, ConversationEvents, ConversationId, ConversationOptions, ConversationState, ConversationStatus, CreateConversationOptions, Generation, GenerationStatus, OrchestratorOptions, Participant, ParticipantInput, ToolCall, ToolCallResult, TranscriptEntryInput, TranscriptSpeakerKind, Turn, TurnId, UserId, } from "./conversations/index.js";
+export { Conversation, Conversations, Transcription, TranscriptEntry, } from "./conversations/index.js";
+export type { AudioChunk, ConversationEvents, ConversationId, ConversationOptions, ConversationState, ConversationStatus, CreateConversationOptions, Generation, GenerationStatus, Participant, ParticipantInput, ToolCall, ToolCallResult, TranscriptEntryInput, TranscriptSpeakerKind, Turn, TurnId, UserId, } from "./conversations/index.js";
 export type { LLM, LLMMessage } from "./providers/llm/types.js";
 export type { STT } from "./providers/stt/types.js";
 export type { TTS } from "./providers/tts/types.js";

package/dist/types/pipeflow/index.d.ts

@@ -0,0 +1,2 @@
+export { Pipeflow } from "./pipeflow.js";
+export type { PipeflowOptions } from "./pipeflow.js";

package/dist/types/pipeflow/pipeflow.d.ts

@@ -0,0 +1,35 @@
+import { Agent, type AgentOptions } from "../agents/agent.js";
+import { Conversations } from "../conversations/conversations.js";
+import type { Persistence } from "../persistence/persistence.js";
+import type { LLM } from "../providers/llm/types.js";
+import type { STT } from "../providers/stt/types.js";
+import type { TTS } from "../providers/tts/types.js";
+export interface PipeflowOptions {
+    llm?: LLM;
+    stt?: STT;
+    tts?: TTS;
+    persistence?: Persistence;
+}
+/**
+ * The Pipeflow entry point.
+ *
+ * ```ts
+ * const pipeflow = new Pipeflow({ llm });
+ * const agent = pipeflow.agent({ name: "Jarvis", context: "..." });
+ * const conversation = await pipeflow.conversations.create({ agents: [agent] });
+ * ```
+ */
+export declare class Pipeflow {
+    readonly llm: LLM | undefined;
+    readonly stt: STT | undefined;
+    readonly tts: TTS | undefined;
+    readonly conversations: Conversations;
+    constructor(options?: PipeflowOptions);
+    /**
+     * Create an agent. Agents inherit the Pipeflow instance's LLM provider so
+     * `agent.run()` works out of the box.
+     */
+    agent(options: Omit<AgentOptions, "llm"> & {
+        llm?: LLM;
+    }): Agent;
+}

package/dist/types/providers/index.d.ts

@@ -1,6 +1,6 @@
 export type { LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition, LLMRequest } from "./llm/index.js";
 export type { STT, STTOptions, STTSession } from "./stt/index.js";
 export type { TTS, TTSRequest } from "./tts/index.js";
-export { complete, streamText, DeepSeekLLM } from "./llm/index.js";
+export { complete, streamText, DeepSeekLLM, OpenRouterLLM } from "./llm/index.js";
 export { DeepgramSTT } from "./stt/index.js";
 export { KokoroTTS } from "./tts/index.js";

package/dist/types/providers/llm/adapters/claude/claude.d.ts

@@ -0,0 +1,45 @@
+import type { LLM, LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback } from "../../types.js";
+import type { FetchLike } from "../../../shared.js";
+export interface ClaudeOptions {
+    apiKey: string;
+    /** Defaults to `claude-sonnet-4-5`. */
+    model?: string;
+    /** Defaults to `https://api.anthropic.com/v1`. */
+    baseUrl?: string;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetch?: FetchLike;
+    /** Provider-timeline hook: request-start / headers / first-chunk. */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Abort a stream that delivers no data for this long (default 8000ms) —
+     * protects against provider connections that go silent after the model
+     * already produced its output. Raise it for providers with slow TTFT.
+     */
+    idleTimeoutMs?: number;
+    /** Called with the provider-reported token usage (when included). */
+    onUsage?: LLMUsageCallback;
+}
+/**
+ * Claude LLM adapter (Anthropic Messages API over SSE).
+ *
+ * The wire format differs from the OpenAI-compatible adapters: tools are
+ * `input_schema` blocks, tool calls arrive as `tool_use` content blocks with
+ * `input_json_delta` fragments (reassembled here into `tool_call` events),
+ * tool results are `tool_result` blocks inside user messages, and `max_tokens`
+ * is required. There is no `response_format`, so `toolMode` is not supported —
+ * tool calling is always native.
+ */
+export declare class ClaudeLLM implements LLM {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly onTiming;
+    private readonly idleTimeoutMs;
+    private readonly onUsage;
+    private readonly streams;
+    constructor(options: ClaudeOptions);
+    /** Cancel every in-flight stream (parallel sub-generations included). */
+    stop(): void;
+    stream(request: LLMRequest): AsyncGenerator<LLMEvent>;
+}

package/dist/types/providers/llm/adapters/claude/index.d.ts

@@ -0,0 +1,2 @@
+export { ClaudeLLM } from "./claude.js";
+export type { ClaudeOptions } from "./claude.js";

package/dist/types/providers/llm/adapters/deepseek/deepseek.d.ts

@@ -1,4 +1,4 @@
-import type { LLM, LLMEvent, LLMRequest } from "../../types.js";
+import type { LLM, LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback, ToolMode } from "../../types.js";
 import type { FetchLike } from "../../../shared.js";
 export interface DeepSeekOptions {
     apiKey: string;
@@ -8,6 +8,22 @@ export interface DeepSeekOptions {
     baseUrl?: string;
     /** Injectable fetch implementation, mainly for tests. */
     fetch?: FetchLike;
+    /** Provider-timeline hook: request-start / headers / first-chunk. */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Abort a stream that delivers no data for this long (default 8000ms) —
+     * protects against provider connections that go silent after the model
+     * already produced its output. Raise it for providers with slow TTFT.
+     */
+    idleTimeoutMs?: number;
+    /** Called with the provider-reported token usage (when included). */
+    onUsage?: LLMUsageCallback;
+    /**
+     * Default tool encoding for requests that don't set `toolMode` (the
+     * request's `toolMode` wins). For models whose endpoints lack native tool
+     * calling.
+     */
+    toolMode?: ToolMode;
 }
 /**
  * DeepSeek LLM adapter (OpenAI-compatible chat completions over SSE).
@@ -17,8 +33,13 @@ export declare class DeepSeekLLM implements LLM {
     private readonly model;
     private readonly baseUrl;
     private readonly fetchImpl;
-    private abort;
+    private readonly onTiming;
+    private readonly idleTimeoutMs;
+    private readonly onUsage;
+    private readonly toolMode;
+    private readonly streams;
     constructor(options: DeepSeekOptions);
+    /** Cancel every in-flight stream (parallel sub-generations included). */
     stop(): void;
     stream(request: LLMRequest): AsyncGenerator<LLMEvent>;
 }

package/dist/types/providers/llm/adapters/index.d.ts

@@ -1 +1,4 @@
 export { DeepSeekLLM } from "./deepseek/deepseek.js";
+export { OpenRouterLLM } from "./openrouter/openrouter.js";
+export { OpenAILLM } from "./openai/openai.js";
+export { ClaudeLLM } from "./claude/claude.js";

package/dist/types/providers/llm/adapters/openai/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenAILLM } from "./openai.js";
+export type { OpenAIOptions } from "./openai.js";

package/dist/types/providers/llm/adapters/openai/openai.d.ts

@@ -0,0 +1,45 @@
+import type { LLM, LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback, ToolMode } from "../../types.js";
+import type { FetchLike } from "../../../shared.js";
+export interface OpenAIOptions {
+    apiKey: string;
+    /** Defaults to `gpt-4o-mini`. */
+    model?: string;
+    /** Defaults to `https://api.openai.com/v1`. */
+    baseUrl?: string;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetch?: FetchLike;
+    /** Provider-timeline hook: request-start / headers / first-chunk. */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Abort a stream that delivers no data for this long (default 8000ms) —
+     * protects against provider connections that go silent after the model
+     * already produced its output. Raise it for providers with slow TTFT.
+     */
+    idleTimeoutMs?: number;
+    /** Called with the provider-reported token usage (when included). */
+    onUsage?: LLMUsageCallback;
+    /**
+     * Default tool encoding for requests that don't set `toolMode` (the
+     * request's `toolMode` wins). For models whose endpoints lack native tool
+     * calling.
+     */
+    toolMode?: ToolMode;
+}
+/**
+ * OpenAI LLM adapter (OpenAI-compatible chat completions over SSE).
+ */
+export declare class OpenAILLM implements LLM {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly onTiming;
+    private readonly idleTimeoutMs;
+    private readonly onUsage;
+    private readonly toolMode;
+    private readonly streams;
+    constructor(options: OpenAIOptions);
+    /** Cancel every in-flight stream (parallel sub-generations included). */
+    stop(): void;
+    stream(request: LLMRequest): AsyncGenerator<LLMEvent>;
+}

package/dist/types/providers/llm/adapters/openai-compatible.d.ts

@@ -0,0 +1,44 @@
+import type { LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback, ToolMode } from "../types.js";
+import type { FetchLike } from "../../shared.js";
+export interface OpenAICompatibleStreamParams {
+    /** Provider base URL, e.g. `https://openrouter.ai/api/v1`. */
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetchImpl: FetchLike;
+    request: LLMRequest;
+    signal: AbortSignal;
+    /** Extra headers merged into the request (e.g. attribution headers). */
+    extraHeaders?: Record<string, string>;
+    /** Extra body fields merged after the standard ones. */
+    extraBody?: Record<string, unknown>;
+    /** Provider name used in error messages. */
+    label: string;
+    /** Optional provider-timeline hook (see `LLMStreamTimingPoint`). */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Default tool encoding for requests that do not set `toolMode`
+     * themselves (the request's `toolMode` wins when present). Useful for
+     * models whose endpoints lack native tool calling.
+     */
+    toolMode?: ToolMode;
+    /**
+     * Abort the stream if no data arrives for this long (default 8000ms).
+     * Protects against providers whose connection goes silent after the model
+     * has already produced its output (e.g. a tool call that is never followed
+     * by a terminating frame).
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Called with the provider-reported token usage when the stream includes
+     * it (OpenRouter sends usage in the final chunk).
+     */
+    onUsage?: LLMUsageCallback;
+}
+/**
+ * Stream a request through any OpenAI-compatible `/chat/completions`
+ * endpoint, reassembling fragmented tool calls and normalizing the SSE
+ * stream into `LLMEvent`s. Shared by the DeepSeek and OpenRouter adapters.
+ */
+export declare function openAICompatibleStream(params: OpenAICompatibleStreamParams): AsyncGenerator<LLMEvent>;

package/dist/types/providers/llm/adapters/openrouter/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenRouterLLM } from "./openrouter.js";
+export type { OpenRouterOptions } from "./openrouter.js";

package/dist/types/providers/llm/adapters/openrouter/openrouter.d.ts

@@ -0,0 +1,60 @@
+import type { FavoriteModel, LLM, LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback, ToolMode } from "../../types.js";
+import type { FetchLike } from "../../../shared.js";
+export interface OpenRouterOptions {
+    apiKey: string;
+    /**
+     * Any model hosted on OpenRouter, e.g. `anthropic/claude-sonnet-4`.
+     * Defaults to `openrouter/auto`, which routes the request to the best
+     * available model for its shape. The measured `FAVORITE_MODELS`
+     * autocomplete; any model id is accepted.
+     */
+    model?: FavoriteModel;
+    /** Defaults to `https://openrouter.ai/api/v1`. */
+    baseUrl?: string;
+    /**
+     * The site that credits the app on OpenRouter's leaderboard via
+     * `HTTP-Referer`. Defaults to `https://moureau.dev`.
+     */
+    appUrl?: string;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetch?: FetchLike;
+    /** Provider-timeline hook: request-start / headers / first-chunk. */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Abort a stream that delivers no data for this long (default 8000ms) —
+     * protects against provider connections that go silent after the model
+     * already produced its output. Raise it for providers with slow TTFT.
+     */
+    idleTimeoutMs?: number;
+    /** Called with the provider-reported token usage (when included). */
+    onUsage?: LLMUsageCallback;
+    /**
+     * Default tool encoding for requests that don't set `toolMode` (the
+     * request's `toolMode` wins). For models whose endpoints lack native tool
+     * calling — e.g. `sao10k/l3-lunaris-8b` -> `"envelope"`.
+     */
+    toolMode?: ToolMode;
+}
+/**
+ * OpenRouter LLM adapter (OpenAI-compatible chat completions over SSE).
+ *
+ * OpenRouter is a gateway: one API key and one wire format for hundreds of
+ * models from different vendors, so this adapter is a thin wrapper around
+ * the shared OpenAI-compatible streaming engine.
+ */
+export declare class OpenRouterLLM implements LLM {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly appUrl;
+    private readonly fetchImpl;
+    private readonly onTiming;
+    private readonly idleTimeoutMs;
+    private readonly onUsage;
+    private readonly toolMode;
+    private readonly streams;
+    constructor(options: OpenRouterOptions);
+    /** Cancel every in-flight stream (parallel sub-generations included). */
+    stop(): void;
+    stream(request: LLMRequest): AsyncGenerator<LLMEvent>;
+}

package/dist/types/providers/llm/index.d.ts

@@ -1,5 +1,6 @@
 import type { LLM, LLMRequest } from "./types.js";
-export type { LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition, LLMRequest, } from "./types.js";
+export type { FavoriteModel, LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition, LLMRequest, StringOr, } from "./types.js";
+export { FAVORITE_MODELS } from "./types.js";
 /**
  * Stream only the text deltas of an LLM generation, rethrowing any
  * streamed error.
@@ -7,4 +8,6 @@ export type { LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition
 export declare function streamText(llm: LLM, request: LLMRequest): AsyncGenerator<string>;
 /** Collect an entire LLM generation into a single string. */
 export declare function complete(llm: LLM, request: LLMRequest): Promise<string>;
-export { DeepSeekLLM } from "./adapters/index.js";
+export { ClaudeLLM, DeepSeekLLM, OpenAILLM, OpenRouterLLM } from "./adapters/index.js";
+export { ToolModeBenchmark } from "./toolmode.js";
+export type { ToolModeBenchmarkOptions, ToolModeBenchmarkResult, ToolModeBenchmarkRun, ToolModeReportEntry, ToolModeTiming, } from "./toolmode.js";

package/dist/types/providers/llm/toolmode/index.d.ts

@@ -0,0 +1,2 @@
+export { ToolModeBenchmark } from "./toolmode.js";
+export type { ToolModeBenchmarkOptions, ToolModeBenchmarkResult, ToolModeBenchmarkRun, ToolModeReportEntry, ToolModeTiming, } from "./toolmode.js";

package/dist/types/providers/llm/toolmode/toolmode.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Tool-mode benchmark: measures availability, latency (percentiles), and cost
+ * of each tool-call encoding (`native` | `envelope` | `prompted`) for a
+ * model, through the real adapter path (`llm.stream({ toolMode })`). A
+ * diagnostic utility for onboarding models — the runtime never calls it.
+ *
+ * ```ts
+ * const bench = new ToolModeBenchmark({ apiKey, model: "..." });
+ * const { fastest, cheapest, report } = await bench.run();
+ * console.log(report.envelope.time.p50);
+ * ```
+ */
+import { z } from "zod";
+import type { FetchLike } from "../../shared.js";
+import type { LLMMessage, LLMToolDefinition, ToolMode } from "../types.js";
+export interface ToolModeBenchmarkOptions {
+    apiKey: string;
+    model: string;
+    /** Override the OpenRouter base URL. */
+    baseUrl?: string;
+    /** Runs per mode (default 3). */
+    runs?: number;
+    /** Probe messages (default: a weather question). */
+    messages?: LLMMessage[];
+    /** Probe tool (default: get_weather). */
+    tools?: LLMToolDefinition[];
+    /**
+     * Validates each emitted tool call's arguments to count `correct` runs — a
+     * call that succeeds with garbage arguments (e.g. `{ "city": "?" }`) is a
+     * failed decision. Defaults to the weather probe's schema.
+     */
+    correctnessSchema?: z.ZodType;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetch?: FetchLike;
+}
+export interface ToolModeBenchmarkRun {
+    /** ms to the tool call (decision latency), or to stream end when none. */
+    latencyMs?: number;
+    toolCall: boolean;
+    /** Every emitted call's arguments parsed cleanly and validated. */
+    correct?: boolean;
+    prompt?: number;
+    completion?: number;
+    error?: string;
+}
+/** Latency percentiles over the runs that produced a tool call. */
+export interface ToolModeTiming {
+    p50: number;
+    p95: number;
+    p99: number;
+}
+export interface ToolModeReportEntry {
+    /** Median cost ($) per decision over runs with provider usage. */
+    cost?: number;
+    /** Decision-latency percentiles; absent when no run emitted a tool call. */
+    time?: ToolModeTiming;
+    /** How many runs produced a tool call. */
+    toolCalls: number;
+    /**
+     * How many runs emitted only schema-valid calls (undefined when no
+     * `correctnessSchema` was provided).
+     */
+    correct: number | undefined;
+    /** Cost per decision that was actually correct: `cost / (correct / runs)`. */
+    effectiveCost?: number;
+    /** How many runs failed outright (transport, envelope parse, …). */
+    errors: number;
+    /** The first run's error, when every run failed. */
+    error?: string;
+    /** Raw per-run rows, for diagnostics. */
+    runs: ToolModeBenchmarkRun[];
+}
+export interface ToolModeBenchmarkResult {
+    model: string;
+    /** Prompt/completion prices ($/token) from the registry, when available. */
+    pricing: {
+        in: number;
+        out: number;
+    } | undefined;
+    report: Record<ToolMode, ToolModeReportEntry>;
+    /** Fastest mode that actually emitted a tool call. */
+    fastest: ToolMode | null;
+    /** Cheapest mode that actually emitted a tool call. */
+    cheapest: ToolMode | null;
+}
+export declare class ToolModeBenchmark {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly runs;
+    private readonly messages;
+    private readonly tools;
+    private readonly correctnessSchema;
+    private readonly fetchImpl;
+    constructor(options: ToolModeBenchmarkOptions);
+    /** Benchmark every mode and return the structured report. */
+    run(): Promise<ToolModeBenchmarkResult>;
+    private benchmarkMode;
+}

package/dist/types/providers/llm/types.d.ts

@@ -21,15 +21,77 @@ export interface LLMToolDefinition {
     /** JSON schema describing the tool arguments. */
     parameters: Record<string, unknown>;
 }
+/**
+ * How tool calls are encoded on the wire. The semantic contract is the same
+ * in every mode — callers still pass `tools` and consume `tool_call` events —
+ * only the encoding differs. The right mode is a property of the model's
+ * endpoints, not the caller: use `ToolModeBenchmark` to measure a model and
+ * set the mode once at adapter construction.
+ *
+ * - `native` (default) — the provider's tool-calling contract: `tools` in
+ *   the request, `tool_calls` in the stream. Streaming deltas and
+ *   provider-enforced argument schemas, at the price of wire overhead: the
+ *   provider expands the schema into its native tool format, which bills
+ *   measurably more prompt tokens (often 5-10x the cost of the modes below).
+ * - `envelope` — no `tools`; `response_format` forces the model to emit a
+ *   JSON envelope (`{ answer?, calls: [{ name, arguments }] }`) that the
+ *   adapter translates back into `tool_call` events. Endpoint-guaranteed
+ *   JSON and a lean prompt (dramatically cheaper per decision), but nothing
+ *   is actionable until the whole envelope arrives — no streaming deltas.
+ *   Only for endpoints that support structured outputs.
+ * - `prompted` — no `tools`; the same envelope is requested by appending an
+ *   instruction to the last user message. The universal fallback: works on
+ *   any chat model, at the cost of extraction/repair/retry, higher token
+ *   use, and tail-latency risk.
+ */
+export type ToolMode = "native" | "envelope" | "prompted";
+/**
+ * A string that may also be one of the branded literal values — e.g. any
+ * model id, with the favorites offered for autocomplete. The `& {}` on the
+ * string side stops TypeScript from absorbing the literals into `string`
+ * (the reverse arrangement — `string | (T & {})` — collapses and loses the
+ * literals).
+ */
+export type StringOr<T extends string> = T | (string & {});
+/** Models measured as usable; offered for autocomplete where a model id is taken. */
+export declare const FAVORITE_MODELS: readonly ["meta-llama/llama-4-scout", "google/gemini-2.5-flash-lite", "amazon/nova-micro-v1", "amazon/nova-lite-v1", "inclusionai/ling-3.0-flash", "sao10k/l3-lunaris-8b", "openai/gpt-oss-20b"];
+/** Any model id, with the favorites offered for autocomplete. */
+export type FavoriteModel = StringOr<(typeof FAVORITE_MODELS)[number]>;
 export interface LLMRequest {
     messages: LLMMessage[];
     tools?: LLMToolDefinition[];
     temperature?: number;
     maxTokens?: number;
+    /** How tools are encoded on the wire. Default `native`. */
+    toolMode?: ToolMode;
+}
+/**
+ * Moments in the provider round trip that separate application delay from
+ * network/queue delay from model latency. The callback is invoked
+ * synchronously at each point, so `performance.now()` taken inside it is the
+ * event time.
+ *
+ * - `request-start` — immediately before the HTTP request is issued.
+ * - `headers` — the response headers arrived (2xx).
+ * - `first-chunk` — the first SSE chunk was parsed.
+ */
+export type LLMStreamTimingPoint = "request-start" | "headers" | "first-chunk";
+export type LLMStreamTimingCallback = (point: LLMStreamTimingPoint) => void;
+/** Token usage reported by the provider (when it includes usage in the stream). */
+export interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
 }
+export type LLMUsageCallback = (usage: LLMUsage) => void;
 export type LLMEvent = {
     type: "delta";
     content: string;
+    /**
+     * Reasoning/thinking tokens, when the provider streams them separately
+     * from content (OpenRouter `reasoning`, DeepSeek `reasoning_content`).
+     * Omitted when the model does not emit reasoning.
+     */
+    reasoning?: string;
 } | {
     type: "tool_call";
     id: string;