@yourgpt/llm-sdk 2.6.0-beta.0 → 2.6.0-beta.2

package/dist/{types-BkQCSiIt.d.ts → types-Dg1Bcg1k.d.ts}

@@ -1,5 +1,78 @@
 import { z } from 'zod';
 
+/** OpenAI reasoning controls. Omit to retain the model's default effort. */
+type OpenAIReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+interface OpenAIParameterOptions {
+    reasoningEffort?: OpenAIReasoningEffort;
+    /** Use passthrough for compatible servers with different model rules. */
+    parameterPolicy?: "openai" | "passthrough";
+    /** Receives omitted-option warnings; defaults to console.warn. */
+    onWarning?: (message: string) => void;
+}
+
+/** Responses-only options. Omitted values retain the API's defaults. */
+interface OpenAIResponsesOptions {
+    store?: boolean;
+    /** Send only new input after this stored response; do not also resend its history. */
+    previousResponseId?: string;
+    include?: string[];
+    reasoningSummary?: "auto" | "concise" | "detailed";
+    promptCacheKey?: string;
+    /** Legacy retention option for models that support it. */
+    promptCacheRetention?: "in_memory" | "24h";
+    /** GPT-5.6+ cache mode and minimum lifetime; provider/model support varies. */
+    promptCacheOptions?: {
+        mode?: "implicit" | "explicit";
+        ttl?: "30m";
+    };
+}
+interface OpenAITransportOptions {
+    /** auto preserves existing routing; responses also works without function tools. */
+    api?: "auto" | "chat" | "responses";
+    responses?: OpenAIResponsesOptions;
+}
+/** Opaque provider items: retain their complete contents and order for replay. */
+interface OpenAIResponseItem {
+    type: string;
+    [key: string]: unknown;
+}
+interface OpenAIResponseMetadata {
+    id?: string;
+    model?: string;
+    status?: string;
+    output: OpenAIResponseItem[];
+    usage?: Record<string, unknown>;
+    store?: boolean;
+    refusals: string[];
+}
+interface ProviderMetadata {
+    openai?: {
+        response?: OpenAIResponseMetadata;
+    };
+    [provider: string]: unknown;
+}
+
+/** Explicit model-facing output; the application's raw tool result stays separate. */
+type ToolOutputPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string | Uint8Array;
+    mediaType: string;
+} | {
+    type: "image";
+    url: string;
+} | {
+    type: "image";
+    fileId: string;
+    provider: "openai";
+};
+interface ToolModelOutput {
+    type: "content";
+    content: ToolOutputPart[];
+}
+
 /**
  * Stream event types for llm-sdk
  * These types are used internally by the SDK for streaming responses
@@ -32,6 +105,7 @@ interface MessageDeltaEvent extends BaseEvent {
  * Message finished streaming
  */
 interface MessageEndEvent extends BaseEvent {
+    providerMetadata?: ProviderMetadata;
     type: "message:end";
 }
 /**
@@ -77,6 +151,7 @@ interface ActionArgsEvent extends BaseEvent {
  * Action execution completed
  */
 interface ActionEndEvent extends BaseEvent {
+    modelOutput?: ToolModelOutput;
     type: "action:end";
     id: string;
     name?: string;
@@ -90,6 +165,12 @@ interface ErrorEvent extends BaseEvent {
     type: "error";
     message: string;
     code?: string;
+    status?: number;
+    providerCode?: string;
+    param?: string;
+    requestId?: string;
+    /** In-process cause, omitted from serialized error events. */
+    cause?: unknown;
 }
 /**
  * Tool call information
@@ -107,6 +188,7 @@ interface ToolCallInfo {
  * Assistant message with tool calls
  */
 interface AssistantToolMessage {
+    providerMetadata?: ProviderMetadata;
     role: "assistant";
     content: string | null;
     tool_calls: Array<{
@@ -182,6 +264,8 @@ interface CitationEvent extends BaseEvent {
  * Message format for done event (API format with snake_case)
  */
 interface DoneEventMessage {
+    modelOutput?: ToolModelOutput;
+    providerMetadata?: ProviderMetadata;
     role: "assistant" | "tool";
     content: string | null;
     tool_calls?: Array<{
@@ -216,6 +300,7 @@ interface ThreadCreatedEvent extends BaseEvent {
  * Stream completed
  */
 interface DoneEvent extends BaseEvent {
+    providerMetadata?: ProviderMetadata;
     type: "done";
     requiresAction?: boolean;
     messages?: DoneEventMessage[];
@@ -249,6 +334,7 @@ type ResponseFormat = {
  * LLM configuration
  */
 interface LLMConfig {
+    reasoningEffort?: OpenAIReasoningEffort;
     temperature?: number;
     maxTokens?: number;
     responseFormat?: ResponseFormat;
@@ -293,6 +379,8 @@ interface MessageMetadata {
  * Message type (simplified for llm-sdk)
  */
 interface Message {
+    modelOutput?: ToolModelOutput;
+    providerMetadata?: ProviderMetadata;
     id: string;
     thread_id?: string;
     role: MessageRole;
@@ -363,7 +451,10 @@ interface AIContent {
     type?: "text" | "image";
     text?: string;
     mediaType?: string;
-    data?: string;
+    data?: string | Uint8Array;
+    url?: string;
+    fileId?: string;
+    provider?: "openai";
     summary?: string;
     details?: string;
 }
@@ -379,6 +470,7 @@ interface ToolInputSchema {
  * Tool definition
  */
 interface ToolDefinition<TParams = Record<string, unknown>> {
+    toModelOutput?: (result: unknown) => ToolModelOutput | undefined;
     name: string;
     description: string;
     location: ToolLocation;
@@ -608,11 +700,14 @@ interface UserMessage {
     content: string | UserContentPart[];
 }
 interface AssistantMessage {
+    /** Provider state retained for continuation and inspection. */
+    providerMetadata?: ProviderMetadata;
     role: "assistant";
     content: string | null;
     toolCalls?: ToolCall[];
 }
 interface ToolMessage {
+    modelOutput?: ToolModelOutput;
     role: "tool";
     toolCallId: string;
     content: string;
@@ -633,6 +728,7 @@ interface ImagePart {
     mimeType?: string;
 }
 interface FilePart {
+    filename?: string;
     type: "file";
     /** Base64 data or URL */
     data: string;
@@ -649,6 +745,8 @@ interface Tool<TParams = unknown, TResult = unknown> {
     parameters: z.ZodType<TParams>;
     /** Execute function */
     execute: (params: TParams, context: ToolContext) => Promise<TResult>;
+    /** Map the raw result to explicit text/image content for the model. */
+    toModelOutput?: (result: TResult) => ToolModelOutput | undefined;
     /**
      * Hide this tool's execution from the chat UI.
      * When true, tool calls and results won't be displayed to the user,
@@ -683,6 +781,7 @@ interface ToolCall {
  * Tool execution result
  */
 interface ToolResult {
+    modelOutput?: ToolModelOutput;
     /** Tool call ID this result corresponds to */
     toolCallId: string;
     /** Result data (will be JSON stringified for LLM) */
@@ -692,10 +791,14 @@ interface ToolResult {
  * Parameters for model.doGenerate() and model.doStream()
  */
 interface DoGenerateParams {
+    /** OpenAI endpoint and Responses options. */
+    openai?: OpenAITransportOptions;
     /** Messages to send to LLM */
     messages: CoreMessage[];
     /** Tools available to the LLM (already formatted for provider) */
     tools?: unknown[];
+    /** OpenAI reasoning effort. Omit to preserve the model default. */
+    reasoningEffort?: OpenAIReasoningEffort;
     /** Temperature (0-2) */
     temperature?: number;
     /** Maximum tokens to generate */
@@ -709,6 +812,8 @@ interface DoGenerateParams {
  * Result from model.doGenerate()
  */
 interface DoGenerateResult {
+    /** Provider state retained for continuation and inspection. */
+    providerMetadata?: ProviderMetadata;
     /** Generated text content */
     text: string;
     /** Tool calls requested by the LLM */
@@ -745,11 +850,14 @@ interface ToolCallChunk {
     toolCall: ToolCall;
 }
 interface ToolResultChunk {
+    modelOutput?: ToolModelOutput;
     type: "tool-result";
     toolCallId: string;
     result: unknown;
 }
 interface FinishChunk {
+    /** Provider state retained for continuation and inspection. */
+    providerMetadata?: ProviderMetadata;
     type: "finish";
     finishReason: FinishReason;
     usage?: TokenUsage;
@@ -762,6 +870,8 @@ interface ErrorChunk {
  * Parameters for generateText()
  */
 interface GenerateTextParams {
+    /** OpenAI endpoint and Responses options. */
+    openai?: OpenAITransportOptions;
     /** Language model to use */
     model: LanguageModel;
     /** Simple prompt (converted to user message) */
@@ -771,9 +881,11 @@ interface GenerateTextParams {
     /** Full message history */
     messages?: CoreMessage[];
     /** Tools available to the LLM */
-    tools?: Record<string, Tool>;
+    tools?: Record<string, Tool<any, any>>;
     /** Maximum agentic steps (tool call loops) */
     maxSteps?: number;
+    /** OpenAI reasoning effort. Omit to preserve the model default. */
+    reasoningEffort?: OpenAIReasoningEffort;
     /** Temperature (0-2) */
     temperature?: number;
     /** Maximum tokens to generate */
@@ -787,6 +899,8 @@ interface GenerateTextParams {
  * Result from generateText()
  */
 interface GenerateTextResult {
+    /** Provider state retained for continuation and inspection. */
+    providerMetadata?: ProviderMetadata;
     /** Final text output */
     text: string;
     /** Token usage */
@@ -808,6 +922,8 @@ interface GenerateTextResult {
  * A single step in the generation process
  */
 interface GenerateStep {
+    /** Provider state retained for continuation and inspection. */
+    providerMetadata?: ProviderMetadata;
     /** Text generated in this step */
     text: string;
     /** Tool calls made in this step */
@@ -827,6 +943,11 @@ type StreamTextParams = GenerateTextParams;
  * Result from streamText()
  */
 interface StreamTextResult {
+    /** Final conversation, including opaque provider state for replay. */
+    readonly response: Promise<{
+        messages: CoreMessage[];
+    }>;
+    readonly providerMetadata: Promise<ProviderMetadata | undefined>;
     /** Async iterable of text chunks only */
     textStream: AsyncIterable<string>;
     /** Async iterable of all stream parts */
@@ -863,6 +984,7 @@ type StreamPart = {
     type: "tool-result";
     toolCallId: string;
     result: unknown;
+    modelOutput?: ToolModelOutput;
 } | {
     type: "step-start";
     step: number;
@@ -870,10 +992,12 @@ type StreamPart = {
     type: "step-finish";
     step: number;
     finishReason: FinishReason;
+    providerMetadata?: ProviderMetadata;
 } | {
     type: "finish";
     finishReason: FinishReason;
     usage: TokenUsage;
+    providerMetadata?: ProviderMetadata;
 } | {
     type: "error";
     error: Error;
@@ -960,4 +1084,4 @@ interface StorageFile {
     filename?: string;
 }
 
-export { type ToolExecution as $, type ActionDefinition as A, type ToolResultChunk as B, type CoreMessage as C, type DoneEventMessage as D, type FinishChunk as E, type FilePart as F, type GenerateTextParams as G, type ErrorChunk as H, type ImagePart as I, type TokenUsage as J, type KnowledgeBaseConfig as K, type LanguageModel as L, type Message as M, type FinishReason as N, type ResponseOptions as O, type ProviderToolRuntimeOptions as P, type StorageFile as Q, type ResponseFormat as R, type StreamTextParams as S, type ToolContext as T, type UserMessage as U, DEFAULT_CAPABILITIES as V, type WebSearchConfig as W, type LLMConfig as X, type ToolLocation as Y, type UnifiedToolCall as Z, type UnifiedToolResult as _, type GenerateTextResult as a, type OpenAIToolSelectionHints as a0, type AnthropicToolSelectionHints as a1, type ToolNativeProviderHints as a2, type OpenAIProviderToolOptions as a3, type AnthropicProviderToolOptions as a4, type Citation as a5, type MessageAttachment as a6, type StreamTextResult as b, type Tool as c, type ToolDefinition as d, type ToolProfile as e, type StorageAdapter as f, type StreamEvent as g, type ToolCallInfo as h, type TokenUsageRaw as i, type ToolResponse as j, type StorageMessage as k, type ModelCapabilities as l, type DoGenerateParams as m, type DoGenerateResult as n, type SystemMessage as o, type AssistantMessage as p, type ToolMessage as q, type UserContentPart as r, type TextPart as s, type ToolCall as t, type ToolResult as u, type GenerateStep as v, type StreamPart as w, type StreamChunk as x, type TextDeltaChunk as y, type ToolCallChunk as z };
+export { type LLMConfig as $, type ActionDefinition as A, type StreamChunk as B, type CoreMessage as C, type DoneEventMessage as D, type TextDeltaChunk as E, type FilePart as F, type GenerateTextParams as G, type ToolCallChunk as H, type ImagePart as I, type ToolResultChunk as J, type KnowledgeBaseConfig as K, type LanguageModel as L, type Message as M, type FinishChunk as N, type OpenAITransportOptions as O, type ProviderMetadata as P, type ErrorChunk as Q, type ResponseFormat as R, type StreamTextParams as S, type ToolContext as T, type UserMessage as U, type TokenUsage as V, type WebSearchConfig as W, type FinishReason as X, type ResponseOptions as Y, type StorageFile as Z, DEFAULT_CAPABILITIES as _, type GenerateTextResult as a, type ToolLocation as a0, type UnifiedToolCall as a1, type UnifiedToolResult as a2, type ToolExecution as a3, type OpenAIToolSelectionHints as a4, type AnthropicToolSelectionHints as a5, type ToolNativeProviderHints as a6, type OpenAIProviderToolOptions as a7, type AnthropicProviderToolOptions as a8, type Citation as a9, type OpenAIResponsesOptions as aa, type OpenAIResponseItem as ab, type OpenAIResponseMetadata as ac, type ToolOutputPart as ad, type OpenAIParameterOptions as ae, type MessageAttachment as af, type StreamTextResult as b, type ToolModelOutput as c, type Tool as d, type ToolDefinition as e, type ToolProfile as f, type StorageAdapter as g, type OpenAIReasoningEffort as h, type StreamEvent as i, type ToolCallInfo as j, type TokenUsageRaw as k, type ProviderToolRuntimeOptions as l, type ToolResponse as m, type StorageMessage as n, type ModelCapabilities as o, type DoGenerateParams as p, type DoGenerateResult as q, type SystemMessage as r, type AssistantMessage as s, type ToolMessage as t, type UserContentPart as u, type TextPart as v, type ToolCall as w, type ToolResult as x, type GenerateStep as y, type StreamPart as z };

package/dist/{types-BSSiJW2o.d.mts → types-Dikj3En4.d.ts}

@@ -1,13 +1,5 @@
-import { d as ToolDefinition, Z as UnifiedToolCall, _ as UnifiedToolResult } from './types-BkQCSiIt.mjs';
-import { L as LLMAdapter } from './base-tNgbBaSo.mjs';
-
-/**
- * Provider Types
- *
- * Defines interfaces for:
- * 1. Provider Formatters (for tool transformations in agent loop)
- * 2. Multi-provider architecture (AIProvider, capabilities, configs)
- */
+import { ae as OpenAIParameterOptions, O as OpenAITransportOptions, e as ToolDefinition, a1 as UnifiedToolCall, a2 as UnifiedToolResult } from './types-Dg1Bcg1k.js';
+import { L as LLMAdapter } from './base-CpRPB8u8.js';
 
 /**
  * Provider formatter interface
@@ -259,7 +251,7 @@ interface BaseProviderConfig {
 /**
  * OpenAI provider configuration
  */
-interface OpenAIProviderConfig extends BaseProviderConfig {
+interface OpenAIProviderConfig extends BaseProviderConfig, OpenAIParameterOptions, OpenAITransportOptions {
     /** OpenAI organization ID */
     organization?: string;
     /** OpenAI project ID */

package/dist/yourgpt/index.d.mts

@@ -1,4 +1,4 @@
-import { k as StorageMessage, f as StorageAdapter, Q as StorageFile } from '../types-BkQCSiIt.mjs';
+import { n as StorageMessage, g as StorageAdapter, Z as StorageFile } from '../types-Dg1Bcg1k.mjs';
 import 'zod';
 
 /**

package/dist/yourgpt/index.d.ts

@@ -1,4 +1,4 @@
-import { k as StorageMessage, f as StorageAdapter, Q as StorageFile } from '../types-BkQCSiIt.js';
+import { n as StorageMessage, g as StorageAdapter, Z as StorageFile } from '../types-Dg1Bcg1k.js';
 import 'zod';
 
 /**

package/docs/multimodal-and-audio.md

@@ -0,0 +1,170 @@
+# Image tool results and recorded audio
+
+These APIs are additive. Chat configuration, ordinary JSON/string tool results, and the existing screenshot `addAsUserMessage` attachment path retain their behavior. Native image tool output requires OpenAI **Responses** or Anthropic. TTS and recorded-file STT currently have an OpenAI implementation; other providers can implement the separate `SpeechModel` / `TranscriptionModel` contracts.
+
+## Tools that return images
+
+A tool still receives schema-validated JSON arguments. Pass an authorized image ID, URL, or crop reference in those arguments; resolve the actual bytes inside your handler. Do not ask the model to reproduce image base64 in function arguments.
+
+```ts
+import { generateText, tool } from "@yourgpt/llm-sdk";
+import { openai } from "@yourgpt/llm-sdk/openai";
+import { z } from "zod";
+
+const result = await generateText({
+  model: openai("gpt-5.2", { api: "responses", responses: { store: false } }),
+  prompt: "Inspect image sample.",
+  maxSteps: 3,
+  tools: {
+    inspect_image: tool({
+      description: "Read an image the caller is authorized to access",
+      parameters: z.object({ imageId: z.string() }),
+      execute: async ({ imageId }) => loadAuthorizedImage(imageId),
+      toModelOutput: (image) => ({
+        type: "content",
+        content: [
+          { type: "text", text: image.caption },
+          { type: "image", data: image.bytes, mediaType: "image/png" },
+        ],
+      }),
+    }),
+  },
+});
+// result.toolResults keeps the raw handler result for your application.
+// result.response.messages retains the model-facing content for the next turn.
+```
+
+`toModelOutput` is a synchronous mapper, called once when a tool completes. It is also available on Runtime and Copilot tool definitions. For existing Runtime/Copilot handlers, returning `{ success: true, _aiContent: [...] }` uses the same native path. Explicit `toModelOutput` takes precedence. MCP image results keep their accompanying text in order.
+
+Supported image parts:
+
+| Part                                            | OpenAI Responses                    | Anthropic |
+| ----------------------------------------------- | ----------------------------------- | --------- |
+| `{ type: 'image', data, mediaType }`            | Yes                                 | Yes       |
+| `{ type: 'image', url: 'https://…' }`           | Yes                                 | Yes       |
+| `{ type: 'image', fileId, provider: 'openai' }` | Yes, with an accessible OpenAI file | Rejected  |
+
+`data` accepts `Uint8Array`, canonical base64, or a base64 data URL matching `mediaType`. Supported media types: PNG, JPEG, WebP, GIF. Images are limited to 20 MiB each; provider/model aggregate limits can be smaller. The SDK does not download URLs or upload files implicitly. URL fetching happens at the selected provider. File references remain scoped to that provider/account.
+
+OpenAI Chat Completions, Gemini, Ollama, Azure Chat and other compatible endpoints reject native image tool output clearly. Text-only mapped content still works. Custom OpenAI endpoints require explicit Responses selection and their own compatibility validation. Arbitrary array-shaped JSON results are never assumed to contain images.
+
+Native output is carried as `modelOutput` next to the tool message's text. Preserve it when storing/restoring messages, along with `tool_call_id` / `toolCallId` and assistant tool calls. The Runtime storage helper places it at `StorageMessage.metadata.modelOutput`; a custom loader must map it back to `modelOutput`. Copilot's serialized `UIMessage` history preserves it directly, including server results in streaming execution metadata. Do not truncate image base64 or substitute it with text. Context pruning can remove complete older tool exchanges.
+
+If an existing screenshot handler explicitly uses `addAsUserMessage`, it continues to add an attachment. When native model output is also supplied, the native output takes precedence and no extra attachment turn is created. General image generation is separate and is not implemented here.
+
+## Speech generation on the server
+
+```ts
+import { generateSpeech } from "@yourgpt/llm-sdk";
+import { openaiSpeech } from "@yourgpt/llm-sdk/openai";
+
+const speech = await generateSpeech({
+  model: openaiSpeech("gpt-4o-mini-tts"), // reads server OPENAI_API_KEY
+  text: "Hello from Copilot.",
+  voice: "alloy",
+  outputFormat: "wav",
+  instructions: "Speak clearly and warmly.",
+  speed: 1,
+  signal: request.signal,
+});
+return new Response(new Uint8Array(speech.audio.uint8Array), {
+  headers: {
+    "Content-Type": speech.audio.mediaType,
+    "Cache-Control": "no-store",
+  },
+});
+```
+
+Returns audio bytes, a lazy `audio.base64` getter, media type/format, warnings, and provider/model/request metadata. Usage is optional and is not invented when the endpoint does not return it. This helper buffers the audio; it is not a realtime voice session or streamed audio API.
+
+Formats: MP3, Opus/Ogg, AAC, FLAC, WAV, and raw PCM. OpenAI PCM is 24 kHz, signed 16-bit little-endian without a container header; use WAV/MP3 for ordinary browser playback. Text/instructions are bounded at 4096 characters, speed at 0.25–4. `tts-1` and `tts-1-hd` reject instructions. Unsupported options fail explicitly. Responses are bounded at 25 MB and checked for a matching audio header; the helper does not perform full codec decoding.
+
+Browser playback, from a user click:
+
+```ts
+const response = await fetch("/api/speech", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ text: "Hello from Copilot." }),
+});
+if (!response.ok) throw new Error("Speech generation failed");
+const url = URL.createObjectURL(await response.blob());
+const player = new Audio(url);
+const release = () => URL.revokeObjectURL(url);
+player.addEventListener("ended", release, { once: true });
+player.addEventListener("error", release, { once: true });
+try {
+  await player.play();
+} catch (error) {
+  release();
+  throw error;
+}
+// On component disposal: player.pause(); release();
+```
+
+Label generated speech as AI-generated. Keep provider keys and authentication/rate limiting in your server route.
+
+## File transcription on the server
+
+```ts
+import { transcribe } from "@yourgpt/llm-sdk";
+import { openaiTranscription } from "@yourgpt/llm-sdk/openai";
+
+// POST /api/transcribe, behind your application's authentication.
+const form = await request.formData();
+const file = form.get("file");
+if (!(file instanceof Blob))
+  return new Response("Audio file required", { status: 400 });
+const transcript = await transcribe({
+  model: openaiTranscription("gpt-4o-mini-transcribe"),
+  audio: file,
+  language: "en",
+  signal: request.signal,
+});
+return Response.json(transcript);
+```
+
+Accepts a Blob, bytes/ArrayBuffer, or base64; bytes/base64 require `mediaType`. A filename is generated from the type unless supplied. No remote URL fetch occurs. Encoded files are limited to 25 MB and require a matching container header and filename extension. Accepted containers: MP3/MPEG/MPGA, MP4/M4A, WAV, WebM, Ogg, and FLAC. Raw PCM belongs to a separately configured realtime transcription protocol.
+
+`text`, provider metadata and usage are returned. Segments, word timestamps, speakers, language and duration are preserved when supplied by the provider. An empty transcript is a valid outcome for silence; missing/non-string text is an invalid response.
+
+For timestamps use `openaiTranscription('whisper-1')` with `providerOptions: { openai: { timestampGranularities: ['word', 'segment'] } }`. For speaker labels use `openaiTranscription('gpt-4o-transcribe-diarize')`; it selects `diarized_json` and automatic chunking. Diarization does not accept prompts or timestamp granularity options. Compatible GPT-4o transcription models can request `includeLogprobs: true`. The initial slice does not expose all options of the newer `gpt-transcribe` model (for example keyword lists or multiple language hints).
+
+Both audio helpers accept `signal`, preserve cancellation, and expose `AudioAPIError` with a stable `code`, HTTP `status` and provider `requestId` when available. They do not log audio/text or retain provider error bodies. There are no automatic chargeable retries.
+
+## Copilot microphone recording and review
+
+`VoiceRecorder` is framework-independent and exported from `@yourgpt/copilot-sdk/core`. It makes no permission request until `start()` is called. Call it from a user gesture on HTTPS/localhost.
+
+```ts
+import { VoiceRecorder, transcribeRecording } from "@yourgpt/copilot-sdk/core";
+
+const recorder = new VoiceRecorder({
+  onStateChange: (state) => updateRecordingIndicator(state),
+  onError: (error) => showError(error.message),
+});
+let upload: AbortController | undefined;
+
+// Record button:
+await recorder.start();
+
+// Stop button:
+const recording = await recorder.stop();
+upload = new AbortController();
+const transcript = await transcribeRecording(recording, {
+  url: "/api/transcribe",
+  signal: upload.signal,
+});
+setChatDraft(transcript.text); // Review/edit, then submit through the usual chat flow.
+// transcript.provenance identifies recorded audio and the server provider/model.
+
+// Cancel button or component disposal:
+upload?.abort();
+recorder.dispose();
+```
+
+The recorder negotiates supported WebM/Opus, MP4, or Ogg/Opus containers. Stop, cancel, permission races, recorder errors and disposal release microphone tracks. Defaults: 20 MB and 60 seconds; exceeding either discards the recording and invokes `onError`. No automatic message submission, voice cloning, telephony, live transcription, or bidirectional voice call is included.
+
+## Verification sources
+
+Provider formats were checked against [OpenAI function outputs](https://developers.openai.com/api/docs/guides/function-calling), [Anthropic tool results](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls), [OpenAI speech](https://developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create), and [OpenAI transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create). Vercel comparisons use its [tool output guidance](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling), [speech](https://ai-sdk.dev/docs/ai-sdk-core/speech), [transcription](https://ai-sdk.dev/docs/ai-sdk-core/transcription), and source checkout `8a5233b15b1e69573d63faee6cd0014559252ee4` (2026-10-15).