xo-harness 0.1.0

package/dist/internal/protocol/parts.d.ts

@@ -0,0 +1,219 @@
+import { z } from "zod";
+/**
+ * Tool call + result as one part's lifecycle — no separate tool_result. `running`
+ * starts at `tool.requested` (arguments are complete by then); `settled` embeds the
+ * canonical ToolOutcome verbatim, so nothing is lost re-encoding it — including task
+ * handoffs, which later settle to their real result when `task.completed` arrives.
+ */
+export declare const ToolPartStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"running">;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    startedAtMs: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"settled">;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"completed">;
+        value: z.ZodJSONSchema;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"accepted_task">;
+        taskId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"failed">;
+        error: z.ZodString;
+    }, z.core.$strip>], "type">;
+    startedAtMs: z.ZodNumber;
+    endedAtMs: z.ZodNumber;
+}, z.core.$strip>], "status">;
+export type ToolPartState = z.infer<typeof ToolPartStateSchema>;
+/** Assistant/model output parts. */
+export declare const OutputPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+    state: z.ZodEnum<{
+        done: "done";
+        streaming: "streaming";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"reasoning">;
+    text: z.ZodString;
+    state: z.ZodEnum<{
+        done: "done";
+        streaming: "streaming";
+    }>;
+    providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"tool">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"running">;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        startedAtMs: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        status: z.ZodLiteral<"settled">;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"completed">;
+            value: z.ZodJSONSchema;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"accepted_task">;
+            taskId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"failed">;
+            error: z.ZodString;
+        }, z.core.$strip>], "type">;
+        startedAtMs: z.ZodNumber;
+        endedAtMs: z.ZodNumber;
+    }, z.core.$strip>], "status">;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"file">;
+    mediaType: z.ZodString;
+    url: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    messageId: z.ZodString;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"audio">;
+    streamId: z.ZodString;
+    sampleRate: z.ZodNumber;
+    state: z.ZodEnum<{
+        done: "done";
+        streaming: "streaming";
+    }>;
+}, z.core.$strip>], "type">;
+export type OutputPart = z.infer<typeof OutputPartSchema>;
+/** User input parts — multimodal in. A bare string stays first-class via AgentInput. */
+export declare const InputPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    mediaType: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    mediaType: z.ZodString;
+    url: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type InputPart = z.infer<typeof InputPartSchema>;
+/** A turn's input: a plain string, or an ordered list of typed parts. */
+export declare const AgentInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    mediaType: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    mediaType: z.ZodString;
+    url: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">>]>;
+export type AgentInput = z.infer<typeof AgentInputSchema>;
+/** Collapse any AgentInput to its text (for providers/logging that only want a string). */
+export declare function agentInputToText(input: AgentInput): string;
+/** A rendered conversation message: role + ordered parts, folded from the event log. */
+export declare const MessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    createdAtMs: z.ZodNumber;
+    parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        messageId: z.ZodString;
+        parentToolUseId: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+        state: z.ZodEnum<{
+            done: "done";
+            streaming: "streaming";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        messageId: z.ZodString;
+        parentToolUseId: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"reasoning">;
+        text: z.ZodString;
+        state: z.ZodEnum<{
+            done: "done";
+            streaming: "streaming";
+        }>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        messageId: z.ZodString;
+        parentToolUseId: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"tool">;
+        toolCallId: z.ZodString;
+        toolName: z.ZodString;
+        state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"running">;
+            input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            startedAtMs: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            status: z.ZodLiteral<"settled">;
+            input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"completed">;
+                value: z.ZodJSONSchema;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"accepted_task">;
+                taskId: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"failed">;
+                error: z.ZodString;
+            }, z.core.$strip>], "type">;
+            startedAtMs: z.ZodNumber;
+            endedAtMs: z.ZodNumber;
+        }, z.core.$strip>], "status">;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        messageId: z.ZodString;
+        parentToolUseId: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"file">;
+        mediaType: z.ZodString;
+        url: z.ZodString;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        messageId: z.ZodString;
+        parentToolUseId: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"audio">;
+        streamId: z.ZodString;
+        sampleRate: z.ZodNumber;
+        state: z.ZodEnum<{
+            done: "done";
+            streaming: "streaming";
+        }>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export type Message = z.infer<typeof MessageSchema>;

package/dist/internal/protocol/parts.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { ToolOutcomeSchema } from "./tools.js";
+/**
+ * The content-part model — the shape every mature agent harness converged on (opencode,
+ * Vercel AI SDK v5, Claude Code, Codex, agent-server, echo-backend, ACP vocabulary): a
+ * message is an ordered array of typed parts with stable identity, and a tool call folds
+ * its result into one part's nested state rather than a separate result event.
+ *
+ * XO's addition to the family is the `audio` part — the addressable handle for a duplex
+ * speech stream, linked to its transcript by streamId. Ordering rules and the event
+ * catalog these fold from live in docs/protocol.md.
+ *
+ * These are the projection/persistence types; the durable transport stays the flat,
+ * sequence-ordered HarnessEvent log. `projectMessages` (in the harness) folds the log
+ * into these deterministically: the same log always yields the same ids.
+ */
+/** Identity + sub-agent threading shared by every part. */
+const PartBaseSchema = z.object({
+    id: z.string().min(1),
+    sessionId: z.string().min(1),
+    messageId: z.string().min(1),
+    /** Set when a part was produced inside a nested tool/sub-agent, linking it to that call. */
+    parentToolUseId: z.string().min(1).optional(),
+});
+const PartStateSchema = z.enum(["streaming", "done"]);
+/**
+ * Tool call + result as one part's lifecycle — no separate tool_result. `running`
+ * starts at `tool.requested` (arguments are complete by then); `settled` embeds the
+ * canonical ToolOutcome verbatim, so nothing is lost re-encoding it — including task
+ * handoffs, which later settle to their real result when `task.completed` arrives.
+ */
+export const ToolPartStateSchema = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("running"),
+        input: z.record(z.string(), z.unknown()),
+        startedAtMs: z.number(),
+    }),
+    z.object({
+        status: z.literal("settled"),
+        input: z.record(z.string(), z.unknown()),
+        outcome: ToolOutcomeSchema,
+        startedAtMs: z.number(),
+        endedAtMs: z.number(),
+    }),
+]);
+/** Assistant/model output parts. */
+export const OutputPartSchema = z.discriminatedUnion("type", [
+    PartBaseSchema.extend({ type: z.literal("text"), text: z.string(), state: PartStateSchema }),
+    PartBaseSchema.extend({
+        type: z.literal("reasoning"),
+        text: z.string(),
+        state: PartStateSchema,
+        providerMetadata: z.record(z.string(), z.unknown()).optional(),
+    }),
+    PartBaseSchema.extend({
+        type: z.literal("tool"),
+        toolCallId: z.string().min(1),
+        toolName: z.string().min(1),
+        state: ToolPartStateSchema,
+    }),
+    PartBaseSchema.extend({
+        type: z.literal("file"),
+        mediaType: z.string().min(1),
+        url: z.string().min(1),
+        filename: z.string().optional(),
+    }),
+    // XO addition: a duplex speech stream. PCM rides audio.output frames keyed by streamId;
+    // the paired text transcript is a sibling text part linked by the same streamId.
+    PartBaseSchema.extend({
+        type: z.literal("audio"),
+        streamId: z.string().min(1),
+        sampleRate: z.number().positive(),
+        state: PartStateSchema,
+    }),
+]);
+/** User input parts — multimodal in. A bare string stays first-class via AgentInput. */
+export const InputPartSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("text"), text: z.string().min(1) }),
+    z.object({ type: z.literal("image"), mediaType: z.string().min(1), url: z.string().min(1) }),
+    z.object({
+        type: z.literal("file"),
+        mediaType: z.string().min(1),
+        url: z.string().min(1),
+        filename: z.string().optional(),
+    }),
+]);
+/** A turn's input: a plain string, or an ordered list of typed parts. */
+export const AgentInputSchema = z.union([z.string().min(1), z.array(InputPartSchema).min(1)]);
+/** Collapse any AgentInput to its text (for providers/logging that only want a string). */
+export function agentInputToText(input) {
+    if (typeof input === "string")
+        return input;
+    return input
+        .map((part) => (part.type === "text" ? part.text : ""))
+        .filter((text) => text !== "")
+        .join("\n");
+}
+/** A rendered conversation message: role + ordered parts, folded from the event log. */
+export const MessageSchema = z.object({
+    id: z.string().min(1),
+    sessionId: z.string().min(1),
+    role: z.enum(["user", "assistant"]),
+    createdAtMs: z.number().nonnegative(),
+    parts: z.array(OutputPartSchema),
+});

package/dist/internal/protocol/provider.d.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+/**
+ * What a provider can actually do, declared at session start and recorded in
+ * `session.started` so consumers adapt instead of probing.
+ */
+export declare const ProviderCapabilitiesSchema: z.ZodObject<{
+    continuousInputDuringOutput: z.ZodBoolean;
+    modelManagedFloor: z.ZodBoolean;
+    supportsToolCalls: z.ZodBoolean;
+    supportsAsyncContext: z.ZodBoolean;
+    supportsPlayoutAcknowledgements: z.ZodBoolean;
+}, z.core.$strip>;
+export type ProviderCapabilities = z.infer<typeof ProviderCapabilitiesSchema>;
+export declare const PlayoutProgressSchema: z.ZodObject<{
+    streamId: z.ZodString;
+    playedThroughSample: z.ZodInt;
+}, z.core.$strip>;
+export type PlayoutProgress = z.infer<typeof PlayoutProgressSchema>;
+/** What the model may produce; ["text"] runs a session without audio output. */
+export declare const OutputModalitySchema: z.ZodEnum<{
+    audio: "audio";
+    text: "text";
+}>;
+export type OutputModality = z.infer<typeof OutputModalitySchema>;
+/**
+ * Token accounting for one completed model response, as reported by the provider.
+ * cachedInputTokens is the slice of input served from the provider's prompt cache —
+ * the number that proves (and prices) cache effectiveness.
+ */
+export declare const UsagePayloadSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    audioInputTokens: z.ZodOptional<z.ZodNumber>;
+    audioOutputTokens: z.ZodOptional<z.ZodNumber>;
+    cachedAudioInputTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type UsagePayload = z.infer<typeof UsagePayloadSchema>;
+/** The one transcript payload shape, shared by provider events and harness events. */
+export declare const TranscriptPayloadSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    text: z.ZodString;
+    streamId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TranscriptPayload = z.infer<typeof TranscriptPayloadSchema>;
+/** Incremental assistant text as the model streams it; finalized by a `transcript`. */
+export declare const TranscriptDeltaPayloadSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    delta: z.ZodString;
+    streamId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TranscriptDeltaPayload = z.infer<typeof TranscriptDeltaPayloadSchema>;
+/**
+ * What a provider adapter yields to the harness. Deliberately minimal: adapters
+ * translate vendor wire dialects into these eight shapes, and the harness turns them
+ * into HarnessEvents. Anything not expressible here does not exist to the harness.
+ */
+export declare const ProviderEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"audio.output">;
+    chunk: z.ZodObject<{
+        streamId: z.ZodString;
+        sequence: z.ZodInt;
+        encoding: z.ZodLiteral<"pcm_s16le">;
+        sampleRate: z.ZodInt;
+        channels: z.ZodInt;
+        startSample: z.ZodInt;
+        data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    text: z.ZodString;
+    streamId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"transcript">;
+}, z.core.$strip>, z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    delta: z.ZodString;
+    streamId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"transcript.delta">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool.call">;
+    call: z.ZodObject<{
+        callId: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    audioInputTokens: z.ZodOptional<z.ZodNumber>;
+    audioOutputTokens: z.ZodOptional<z.ZodNumber>;
+    cachedAudioInputTokens: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"usage">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+    recoverable: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"closed">;
+    reason: z.ZodString;
+}, z.core.$strip>], "type">;
+export type ProviderEvent = z.infer<typeof ProviderEventSchema>;

package/dist/internal/protocol/provider.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { AudioChunkSchema } from "./audio.js";
+import { ToolCallSchema } from "./tools.js";
+/**
+ * What a provider can actually do, declared at session start and recorded in
+ * `session.started` so consumers adapt instead of probing.
+ */
+export const ProviderCapabilitiesSchema = z.object({
+    /** Microphone audio may keep flowing while the model is speaking (full duplex). */
+    continuousInputDuringOutput: z.boolean(),
+    /** The model decides when to speak (server VAD); the harness never gates turns. */
+    modelManagedFloor: z.boolean(),
+    supportsToolCalls: z.boolean(),
+    /** Accepts out-of-band context injections such as task settlement announcements. */
+    supportsAsyncContext: z.boolean(),
+    /** Honors playout acknowledgements for truncation-accurate barge-in. */
+    supportsPlayoutAcknowledgements: z.boolean(),
+});
+export const PlayoutProgressSchema = z.object({
+    streamId: z.string().min(1),
+    playedThroughSample: z.int().nonnegative(),
+});
+/** What the model may produce; ["text"] runs a session without audio output. */
+export const OutputModalitySchema = z.enum(["audio", "text"]);
+/**
+ * Token accounting for one completed model response, as reported by the provider.
+ * cachedInputTokens is the slice of input served from the provider's prompt cache —
+ * the number that proves (and prices) cache effectiveness.
+ */
+export const UsagePayloadSchema = z.object({
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    totalTokens: z.number().int().nonnegative(),
+    cachedInputTokens: z.number().int().nonnegative().optional(),
+    audioInputTokens: z.number().int().nonnegative().optional(),
+    audioOutputTokens: z.number().int().nonnegative().optional(),
+    cachedAudioInputTokens: z.number().int().nonnegative().optional(),
+});
+/** The one transcript payload shape, shared by provider events and harness events. */
+export const TranscriptPayloadSchema = z.object({
+    role: z.enum(["user", "assistant"]),
+    text: z.string().min(1),
+    streamId: z.string().min(1).optional(),
+});
+/** Incremental assistant text as the model streams it; finalized by a `transcript`. */
+export const TranscriptDeltaPayloadSchema = z.object({
+    role: z.enum(["user", "assistant"]),
+    delta: z.string().min(1),
+    streamId: z.string().min(1).optional(),
+});
+/**
+ * What a provider adapter yields to the harness. Deliberately minimal: adapters
+ * translate vendor wire dialects into these eight shapes, and the harness turns them
+ * into HarnessEvents. Anything not expressible here does not exist to the harness.
+ */
+export const ProviderEventSchema = z.discriminatedUnion("type", [
+    /** Session configuration acknowledged; the model is listening. */
+    z.object({ type: z.literal("ready") }),
+    /** Model speech as sample-addressed PCM. */
+    z.object({ type: z.literal("audio.output"), chunk: AudioChunkSchema }),
+    /** Final transcript text for either role. */
+    TranscriptPayloadSchema.extend({ type: z.literal("transcript") }),
+    /** Incremental assistant text; assembled into a streaming text part. */
+    TranscriptDeltaPayloadSchema.extend({ type: z.literal("transcript.delta") }),
+    /** The model requested a tool invocation. */
+    z.object({ type: z.literal("tool.call"), call: ToolCallSchema }),
+    /** Token accounting for one completed response. */
+    UsagePayloadSchema.extend({ type: z.literal("usage") }),
+    /** Provider fault; unrecoverable errors are followed by `closed`. */
+    z.object({
+        type: z.literal("error"),
+        message: z.string().min(1),
+        recoverable: z.boolean(),
+    }),
+    /** Terminal: the provider connection is gone. Always the last event. */
+    z.object({ type: z.literal("closed"), reason: z.string().min(1) }),
+]);

package/dist/internal/protocol/tools.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export declare const JsonValueSchema: z.ZodJSONSchema;
+export type JsonValue = z.infer<typeof JsonValueSchema>;
+export declare const ToolCallSchema: z.ZodObject<{
+    callId: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type ToolCall = z.infer<typeof ToolCallSchema>;
+export declare const ToolOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"completed">;
+    value: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"accepted_task">;
+    taskId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"failed">;
+    error: z.ZodString;
+}, z.core.$strip>], "type">;
+export type ToolOutcome = z.infer<typeof ToolOutcomeSchema>;
+export declare const ProviderToolDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strip>;
+export type ProviderToolDefinition = z.infer<typeof ProviderToolDefinitionSchema>;
+export declare const ProviderToolResultSchema: z.ZodObject<{
+    callId: z.ZodString;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"completed">;
+        value: z.ZodJSONSchema;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"accepted_task">;
+        taskId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"failed">;
+        error: z.ZodString;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>;
+export type ProviderToolResult = z.infer<typeof ProviderToolResultSchema>;
+export declare const ProviderContextEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"task.progress">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    update: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"task.completed">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    result: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"task.failed">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"task.cancelled">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>], "type">;
+export type ProviderContextEvent = z.infer<typeof ProviderContextEventSchema>;

package/dist/internal/protocol/tools.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+export const JsonValueSchema = z.json();
+export const ToolCallSchema = z.object({
+    callId: z.string().min(1),
+    name: z.string().min(1),
+    arguments: z.record(z.string(), z.unknown()),
+});
+export const ToolOutcomeSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("completed"), value: JsonValueSchema }),
+    z.object({ type: z.literal("accepted_task"), taskId: z.string().min(1) }),
+    z.object({ type: z.literal("failed"), error: z.string().min(1) }),
+]);
+export const ProviderToolDefinitionSchema = z.object({
+    name: z.string().regex(/^[A-Za-z0-9_.-]{1,128}$/),
+    description: z.string().min(1),
+    inputSchema: z.record(z.string(), JsonValueSchema),
+});
+export const ProviderToolResultSchema = z.object({
+    callId: z.string().min(1),
+    outcome: ToolOutcomeSchema,
+});
+export const ProviderContextEventSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("task.progress"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        update: JsonValueSchema,
+    }),
+    z.object({
+        type: z.literal("task.completed"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        result: JsonValueSchema,
+    }),
+    z.object({
+        type: z.literal("task.failed"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        error: z.string().min(1),
+    }),
+    z.object({
+        type: z.literal("task.cancelled"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        reason: z.string().min(1),
+    }),
+]);

package/dist/internal/provider/contract.d.ts

@@ -0,0 +1,24 @@
+import type { AudioChunk, OutputModality, PlayoutProgress, ProviderCapabilities, ProviderContextEvent, ProviderEvent, ProviderToolDefinition, ProviderToolResult } from "../protocol/index.js";
+export interface CreateProviderSessionOptions {
+    sessionId: string;
+    signal: AbortSignal;
+    instructions?: string;
+    /** What the model may produce this session; ["text"] disables audio output. Default: audio. */
+    outputModalities?: readonly OutputModality[];
+    tools: readonly ProviderToolDefinition[];
+}
+export interface VoiceProviderSession {
+    readonly events: AsyncIterable<ProviderEvent>;
+    sendAudio(chunk: AudioChunk): Promise<void>;
+    /** Injects a typed user message into the conversation; the model responds as usual. */
+    sendText(text: string): Promise<void>;
+    reportPlayout(progress: PlayoutProgress): Promise<void>;
+    sendToolResult(result: ProviderToolResult): Promise<void>;
+    sendContext(event: ProviderContextEvent): Promise<void>;
+    close(reason?: string): Promise<void>;
+}
+export interface VoiceProvider {
+    readonly id: string;
+    readonly capabilities: ProviderCapabilities;
+    createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;
+}

package/dist/internal/provider/contract.js

@@ -0,0 +1 @@
+export {};