xo-harness 0.1.2 → 0.2.0

package/dist/internal/provider/realtime-session.js

@@ -1,10 +1,9 @@
-import { Buffer } from "node:buffer";
-import { AssistantTurnRequestSchema, AsyncQueue, AudioChunkSchema, audioSampleCount, PlayoutProgressSchema, ProviderContextEventSchema, ProviderToolResultSchema, ToolCallSchema, } from "../protocol/index.js";
+import { AssistantTurnRequestSchema, AsyncQueue, AudioChunkSchema, audioSampleCount, PlayoutProgressSchema, PROVIDER_DIAGNOSTIC_MAX_CONTENT_TYPES, PROVIDER_DIAGNOSTIC_MAX_OUTPUTS, PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH, ProviderContextEventSchema, ProviderToolResultSchema, ToolCallSchema, } from "../protocol/index.js";
 import { z } from "zod";
 const FALLBACK_STREAM_ID = "assistant-output";
 const CLOSE_REASON_BYTE_LIMIT = 120;
-const INPUT_TRANSCRIPT_SETTLE_MS = 300;
 const EMITTED_USER_TRANSCRIPT_CACHE_LIMIT = 128;
+const VAD_RESPONSE_RECOVERY_MS = 1_500;
 const ServerEnvelopeSchema = z.looseObject({ type: z.string().min(1) });
 const OutputAudioDeltaSchema = z.looseObject({
     item_id: z.string().min(1).optional(),
@@ -34,6 +33,29 @@ const UsageDetailsSchema = z.looseObject({
     })
         .optional(),
 });
+const ResponseOutputContentSchema = z.looseObject({
+    type: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+});
+const ResponseOutputDiagnosticSchema = z.looseObject({
+    id: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+    type: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+    content: z.array(ResponseOutputContentSchema).max(PROVIDER_DIAGNOSTIC_MAX_CONTENT_TYPES).optional(),
+});
+const ResponseStatusDetailsSchema = z.looseObject({
+    reason: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).nullish(),
+    error: z
+        .looseObject({
+        code: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+    })
+        .nullish(),
+});
+const ResponseDiagnosticSchema = z.looseObject({
+    id: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+    status: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+    status_details: ResponseStatusDetailsSchema.nullish(),
+    output: z.array(ResponseOutputDiagnosticSchema).max(PROVIDER_DIAGNOSTIC_MAX_OUTPUTS).optional(),
+});
+/** Core response.done fields stay independent from optional diagnostic metadata. */
 const ResponseDoneSchema = z.looseObject({
     response: z.looseObject({
         output: z.array(z.looseObject({ type: z.string().optional() })).optional(),
@@ -48,6 +70,13 @@ const ResponseDoneSchema = z.looseObject({
             .optional(),
     }),
 });
+const ResponseEnvelopeSchema = z.looseObject({
+    response: z.looseObject({}),
+});
+/** Response identity is core bookkeeping, separate from optional diagnostic metadata. */
+const ResponseIdEnvelopeSchema = z.looseObject({
+    response: z.looseObject({ id: z.string().min(1).optional() }),
+});
 const TranscriptEventSchema = z.looseObject({
     transcript: z.string(),
     item_id: z.string().min(1).optional(),
@@ -66,6 +95,7 @@ const ServerErrorSchema = z.looseObject({
 const SessionUpdatedSchema = z.looseObject({
     session: z
         .looseObject({
+        model: z.string().min(1).optional(),
         audio: z
             .looseObject({
             output: z
@@ -78,21 +108,34 @@ const SessionUpdatedSchema = z.looseObject({
     })
         .optional(),
 });
+const SpeechBoundarySchema = z.looseObject({
+    item_id: z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH).optional(),
+    audio_start_ms: z.number().nonnegative().optional(),
+    audio_end_ms: z.number().nonnegative().optional(),
+});
 export class RealtimeVoiceSession {
     #socket;
     #wire;
     #queue = new AsyncQueue();
     #outputStreams = new Map();
     #playedThrough = new Map();
+    #interruptedStreams = new Set();
     #deliveredToolCalls = new Set();
+    #completedResponseIds = new Set();
+    #usageResponseIds = new Set();
     #pendingUserTranscripts = new Map();
     #emittedUserTranscripts = new Map();
     #settled;
     #resolveSettled;
     #outputSampleRate;
-    #activeOutputItemId;
+    #responseNumber = 0;
     #responseActive = false;
+    #activeResponseId;
     #responseWanted = false;
+    #inputSpeechActive = false;
+    #awaitingVadResponse = false;
+    #vadResponseRecoveryTimer;
+    #reportedResponseState;
     #wantedResponseInstructions;
     #ready = false;
     #closed = false;
@@ -197,14 +240,22 @@ export class RealtimeVoiceSession {
                 this.#handleSessionUpdated(parsed);
                 break;
             case "response.created":
+                this.#handleResponseCreated(parsed);
                 this.#responseActive = true;
+                this.#activeResponseId = responseIdFromEnvelope(parsed);
+                if (!this.#inputSpeechActive)
+                    this.#clearAwaitingVadResponse();
+                this.#reportResponseState();
                 break;
             case "response.output_audio.delta":
                 this.#handleAudioDelta(parsed);
                 break;
             case "response.output_audio_transcript.delta":
             case "response.output_text.delta":
-                this.#handleTranscriptDelta(parsed);
+                this.#handleTranscriptDelta(parsed, "assistant");
+                break;
+            case "conversation.item.input_audio_transcription.delta":
+                this.#handleTranscriptDelta(parsed, "user");
                 break;
             case "response.output_audio_transcript.done":
                 this.#handleTranscript(parsed, "assistant");
@@ -222,7 +273,20 @@ export class RealtimeVoiceSession {
                 this.#handleResponseDone(parsed);
                 break;
             case "input_audio_buffer.speech_started":
-                this.#handleSpeechStarted();
+                this.#handleSpeechStarted(parsed);
+                break;
+            case "input_audio_buffer.speech_stopped":
+                this.#emitSpeechDiagnostic(parsed, "stopped");
+                this.#inputSpeechActive = false;
+                if (this.#awaitingVadResponse && this.#responseActive && this.#wire.interruptOnSpeech === false) {
+                    // Non-interrupting VAD can skip automatic creation while an older response
+                    // is active. Request its continuation once that response finishes.
+                    this.#clearAwaitingVadResponse();
+                    this.#responseWanted = true;
+                }
+                else if (this.#awaitingVadResponse) {
+                    this.#armVadResponseRecovery();
+                }
                 break;
             case "error":
                 this.#handleServerError(parsed);
@@ -236,11 +300,19 @@ export class RealtimeVoiceSession {
         const rate = updated.success ? updated.data.session?.audio?.output?.format?.rate : undefined;
         if (rate !== undefined)
             this.#outputSampleRate = rate;
+        const model = updated.success ? updated.data.session?.model : undefined;
+        if (model !== undefined && model.length <= PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH) {
+            this.#emit({ type: "diagnostic", diagnostic: { kind: "session", model } });
+        }
         if (!this.#ready) {
             this.#ready = true;
             this.#emit({ type: "ready" });
+            this.#reportResponseState();
         }
     }
+    #handleResponseCreated(parsed) {
+        this.#emitResponseEnvelopeDiagnostic(parsed, "started");
+    }
     #handleAudioDelta(parsed) {
         const delta = OutputAudioDeltaSchema.safeParse(parsed);
         if (!delta.success) {
@@ -252,13 +324,29 @@ export class RealtimeVoiceSession {
             this.#emitError("Received an output audio delta without an audio payload", true);
             return;
         }
-        const bytes = Buffer.from(payload, "base64");
+        let bytes;
+        try {
+            bytes = Uint8Array.from(atob(payload), (character) => character.charCodeAt(0));
+        }
+        catch {
+            this.#emitError("Received an output audio delta with invalid base64", true);
+            return;
+        }
         if (bytes.byteLength === 0 || bytes.byteLength % 2 !== 0) {
             this.#emitError(`Received a PCM16 delta with invalid byte length ${bytes.byteLength}`, true);
             return;
         }
-        const streamId = delta.data.item_id ?? delta.data.response_id ?? FALLBACK_STREAM_ID;
-        const stream = this.#outputStreams.get(streamId) ?? { sequence: 0, startSample: 0 };
+        const streamId = delta.data.item_id ??
+            delta.data.response_id ??
+            (this.#responseNumber === 0 ? FALLBACK_STREAM_ID : `${FALLBACK_STREAM_ID}-${this.#responseNumber}`);
+        if (this.#interruptedStreams.has(streamId))
+            return;
+        const stream = this.#outputStreams.get(streamId) ?? {
+            sequence: 0,
+            startSample: 0,
+            complete: false,
+            itemId: delta.data.item_id,
+        };
         const chunk = AudioChunkSchema.parse({
             streamId,
             sequence: stream.sequence,
@@ -266,12 +354,11 @@ export class RealtimeVoiceSession {
             sampleRate: this.#outputSampleRate,
             channels: 1,
             startSample: stream.startSample,
-            data: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+            data: bytes,
         });
         stream.sequence += 1;
         stream.startSample += audioSampleCount(chunk);
         this.#outputStreams.set(streamId, stream);
-        this.#activeOutputItemId = streamId;
         this.#emit({ type: "audio.output", chunk });
     }
     #handleTranscript(parsed, role) {
@@ -292,8 +379,10 @@ export class RealtimeVoiceSession {
         const pending = this.#pendingUserTranscripts.get(streamId);
         if (pending)
             clearTimeout(pending.timer);
-        const timer = setTimeout(() => this.#flushUserTranscript(streamId), INPUT_TRANSCRIPT_SETTLE_MS);
+        const timer = setTimeout(() => this.#flushUserTranscript(streamId), this.#wire.inputTranscriptSettleMs ?? 0);
         this.#pendingUserTranscripts.set(streamId, { text, timer });
+        if (!this.#wire.inputTranscriptSettleMs)
+            this.#flushUserTranscript(streamId);
     }
     #flushUserTranscript(streamId) {
         const pending = this.#pendingUserTranscripts.get(streamId);
@@ -316,13 +405,13 @@ export class RealtimeVoiceSession {
         for (const streamId of [...this.#pendingUserTranscripts.keys()])
             this.#flushUserTranscript(streamId);
     }
-    #handleTranscriptDelta(parsed) {
+    #handleTranscriptDelta(parsed, role) {
         const delta = TranscriptDeltaWireSchema.safeParse(parsed);
         if (!delta.success || delta.data.delta === "")
             return;
         this.#emit({
             type: "transcript.delta",
-            role: "assistant",
+            role,
             delta: delta.data.delta,
             ...(delta.data.item_id === undefined ? {} : { streamId: delta.data.item_id }),
         });
@@ -346,13 +435,19 @@ export class RealtimeVoiceSession {
         this.#emitFunctionCall(done.data.call_id, done.data.name, done.data.arguments);
     }
     #handleResponseDone(parsed) {
-        this.#responseActive = false;
-        this.#activeOutputItemId = undefined;
+        this.#emitResponseEnvelopeDiagnostic(parsed, "completed");
+        const responseId = responseIdFromEnvelope(parsed);
+        const duplicate = responseId !== undefined && this.#completedResponseIds.has(responseId);
+        if (responseId !== undefined)
+            this.#completedResponseIds.add(responseId);
         const done = ResponseDoneSchema.safeParse(parsed);
         if (done.success) {
             const usage = done.data.response.usage;
-            if (usage)
+            if (usage && (responseId === undefined || !this.#usageResponseIds.has(responseId))) {
                 this.#emitUsage(usage);
+                if (responseId !== undefined)
+                    this.#usageResponseIds.add(responseId);
+            }
             for (const item of done.data.response.output ?? []) {
                 if (item.type !== "function_call")
                     continue;
@@ -364,11 +459,26 @@ export class RealtimeVoiceSession {
                 this.#emitFunctionCall(call.data.call_id, call.data.name, call.data.arguments);
             }
         }
+        // A duplicate or stale terminal update can refine diagnostics and carry omitted
+        // usage, but must never settle the response currently generating.
+        const settlesActiveResponse = !duplicate &&
+            (responseId === undefined ||
+                this.#activeResponseId === undefined ||
+                responseId === this.#activeResponseId);
+        if (!settlesActiveResponse)
+            return;
+        this.#responseActive = false;
+        this.#activeResponseId = undefined;
+        // Generation often ends well before the client finishes playing its queued PCM.
+        for (const stream of this.#outputStreams.values())
+            stream.complete = true;
+        this.#responseNumber += 1;
         if (this.#responseWanted) {
             const instructions = this.#wantedResponseInstructions;
             this.#wantedResponseInstructions = undefined;
             this.#requestResponse(instructions);
         }
+        this.#reportResponseState();
     }
     #emitUsage(usage) {
         const input = usage.input_token_details;
@@ -407,40 +517,151 @@ export class RealtimeVoiceSession {
             call: ToolCallSchema.parse({ callId, name, arguments: parsedArguments }),
         });
     }
-    #handleSpeechStarted() {
-        const itemId = this.#activeOutputItemId;
-        if (itemId === undefined)
+    #handleSpeechStarted(parsed) {
+        this.#emitSpeechDiagnostic(parsed, "started");
+        this.#clearVadResponseRecoveryTimer();
+        this.#inputSpeechActive = true;
+        this.#awaitingVadResponse = this.#wire.autoRespondToAudio;
+        this.#reportResponseState();
+        if (this.#wire.interruptOnSpeech === false)
             return;
-        this.#activeOutputItemId = undefined;
-        const playedThroughSample = this.#playedThrough.get(itemId);
-        if (playedThroughSample === undefined)
+        // A response can contain a preamble and an answer, both ahead of playback.
+        // Discard queued items first so stopping the audible item cannot start the next.
+        for (const [streamId, stream] of [...this.#outputStreams].reverse()) {
+            if (this.#interruptedStreams.has(streamId))
+                continue;
+            const playedThroughSample = this.#playedThrough.get(streamId) ?? 0;
+            if (stream.complete && playedThroughSample >= stream.startSample)
+                continue;
+            this.#interruptedStreams.add(streamId);
+            this.#emit({ type: "audio.interrupted", streamId });
+            // Only a real conversation item ID is valid in the vendor's truncate command.
+            if (stream.itemId === undefined)
+                continue;
+            this.#trySend({
+                type: "conversation.item.truncate",
+                item_id: stream.itemId,
+                content_index: 0,
+                audio_end_ms: Math.floor((Math.min(playedThroughSample, stream.startSample) / this.#outputSampleRate) * 1000),
+            });
+        }
+    }
+    #emitSpeechDiagnostic(parsed, phase) {
+        const boundary = SpeechBoundarySchema.safeParse(parsed);
+        if (!boundary.success)
             return;
-        this.#trySend({
-            type: "conversation.item.truncate",
-            item_id: itemId,
-            content_index: 0,
-            audio_end_ms: Math.floor((playedThroughSample / this.#outputSampleRate) * 1000),
+        const audioOffsetMs = phase === "started" ? boundary.data.audio_start_ms : boundary.data.audio_end_ms;
+        this.#emit({
+            type: "diagnostic",
+            diagnostic: {
+                kind: "speech",
+                phase,
+                ...(boundary.data.item_id === undefined ? {} : { streamId: boundary.data.item_id }),
+                ...(audioOffsetMs === undefined ? {} : { audioOffsetMs }),
+            },
         });
     }
+    #emitResponseDiagnostic(parsed, phase) {
+        const response = ResponseDiagnosticSchema.safeParse(parsed);
+        if (!response.success)
+            return;
+        const details = response.data.status_details;
+        const outputs = response.data.output
+            ?.filter((item) => item.type !== undefined)
+            .map((item) => ({
+            ...(item.id === undefined ? {} : { streamId: item.id }),
+            type: item.type,
+            contentTypes: item.content?.flatMap((content) => (content.type === undefined ? [] : [content.type])) ?? [],
+        }));
+        this.#emit({
+            type: "diagnostic",
+            diagnostic: {
+                kind: "response",
+                phase,
+                ...(response.data.id === undefined ? {} : { responseId: response.data.id }),
+                ...(response.data.status === undefined ? {} : { status: response.data.status }),
+                ...(details?.reason == null ? {} : { reason: details.reason }),
+                ...(details?.error?.code === undefined ? {} : { code: details.error.code }),
+                ...(outputs === undefined ? {} : { outputs }),
+            },
+        });
+    }
+    #emitResponseEnvelopeDiagnostic(parsed, phase) {
+        const envelope = ResponseEnvelopeSchema.safeParse(parsed);
+        if (envelope.success)
+            this.#emitResponseDiagnostic(envelope.data.response, phase);
+    }
     #handleServerError(parsed) {
         const error = ServerErrorSchema.safeParse(parsed);
         const message = error.success ? error.data.error?.message : undefined;
         this.#emitError(message ?? `${this.#wire.label} reported an error`, true);
+        if (this.#awaitingVadResponse && !this.#inputSpeechActive) {
+            this.#clearAwaitingVadResponse();
+            this.#resumeQueuedResponse();
+        }
     }
     #requestResponse(instructions) {
+        if (this.#awaitingVadResponse) {
+            // Tool/task context is already in the conversation. Let VAD answer after the
+            // user finishes, including the gap between speech_stopped and response.created.
+            if (instructions !== undefined)
+                this.#wantedResponseInstructions = instructions;
+            this.#responseWanted = this.#wantedResponseInstructions !== undefined;
+            this.#reportResponseState();
+            return;
+        }
         if (this.#responseActive) {
             this.#responseWanted = true;
             if (instructions !== undefined)
                 this.#wantedResponseInstructions = instructions;
+            this.#reportResponseState();
             return;
         }
         this.#responseWanted = false;
         this.#responseActive = true;
+        this.#reportResponseState();
         this.#trySend({
             type: "response.create",
             ...(instructions === undefined ? {} : { response: { instructions } }),
         });
     }
+    #armVadResponseRecovery() {
+        this.#clearVadResponseRecoveryTimer();
+        this.#vadResponseRecoveryTimer = setTimeout(() => {
+            this.#vadResponseRecoveryTimer = undefined;
+            if (this.#closed || !this.#awaitingVadResponse)
+                return;
+            this.#clearAwaitingVadResponse();
+            this.#emitError("Provider did not create the expected VAD response", true);
+            this.#resumeQueuedResponse();
+        }, VAD_RESPONSE_RECOVERY_MS);
+    }
+    #clearAwaitingVadResponse() {
+        this.#awaitingVadResponse = false;
+        this.#clearVadResponseRecoveryTimer();
+    }
+    #clearVadResponseRecoveryTimer() {
+        if (this.#vadResponseRecoveryTimer !== undefined)
+            clearTimeout(this.#vadResponseRecoveryTimer);
+        this.#vadResponseRecoveryTimer = undefined;
+    }
+    #resumeQueuedResponse() {
+        if (!this.#responseWanted) {
+            this.#reportResponseState();
+            return;
+        }
+        const instructions = this.#wantedResponseInstructions;
+        this.#responseWanted = false;
+        this.#wantedResponseInstructions = undefined;
+        this.#requestResponse(instructions);
+    }
+    #reportResponseState() {
+        const state = this.#responseActive || this.#responseWanted || this.#awaitingVadResponse ? "pending" : "idle";
+        if (state === this.#reportedResponseState)
+            return;
+        this.#reportedResponseState = state;
+        this.#emit({ type: "response.state", state });
+    }
     #send(payload) {
         if (this.#socket.state !== "open") {
             throw new Error(`${this.#wire.label} session socket is not open`);
@@ -464,6 +685,7 @@ export class RealtimeVoiceSession {
     #settle(reason) {
         if (this.#closed)
             return;
+        this.#clearVadResponseRecoveryTimer();
         this.#flushUserTranscripts();
         this.#closed = true;
         this.#queue.push({ type: "closed", reason });
@@ -506,10 +728,23 @@ function contextText(event) {
     }
 }
 function toBase64(data) {
-    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("base64");
+    let binary = "";
+    // Bound each argument list; microphone buffers need not fit the engine's call stack.
+    for (let offset = 0; offset < data.length; offset += 0x8000) {
+        binary += String.fromCharCode(...data.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
 }
 function truncateCloseReason(reason) {
-    return Buffer.byteLength(reason, "utf8") <= CLOSE_REASON_BYTE_LIMIT
-        ? reason
-        : Buffer.from(reason, "utf8").subarray(0, CLOSE_REASON_BYTE_LIMIT).toString("utf8");
+    const bytes = new TextEncoder().encode(reason);
+    if (bytes.byteLength <= CLOSE_REASON_BYTE_LIMIT)
+        return reason;
+    // Streaming decode leaves a partial final code point buffered instead of replacing it.
+    return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes.subarray(0, CLOSE_REASON_BYTE_LIMIT), {
+        stream: true,
+    });
+}
+function responseIdFromEnvelope(parsed) {
+    const envelope = ResponseIdEnvelopeSchema.safeParse(parsed);
+    return envelope.success ? envelope.data.response.id : undefined;
 }

package/dist/internal/provider-fake/replay-voice-provider.d.ts

@@ -12,8 +12,12 @@ export interface ReplayVoiceProviderOptions {
  * Replays the provider-visible half of a recorded session: model audio, tool requests,
  * and provider errors, in recorded order and (optionally) recorded pacing. Input audio,
  * playout acknowledgements, tool results, and context are accepted and captured but do
- * not influence playback. This is the shadow-test primitive: re-drive UIs, tools, and
- * stores from an authoritative log without a live model or an API key.
+ * not influence playback. This re-drives UIs and stores from a recorded log without a
+ * live model or an API key.
+ *
+ * Playback closes after the last recorded output, even if a replayed tool request is
+ * still awaiting admission or execution. Recorded tool outcomes are not replayed.
+ * Use ScriptedVoiceProvider when subsequent output must wait for and verify results.
  */
 export declare class ReplayVoiceProvider implements VoiceProvider {
     #private;

package/dist/internal/provider-fake/replay-voice-provider.js

@@ -3,8 +3,12 @@ import { AssistantTurnRequestSchema, AsyncQueue, AudioChunkSchema, PlayoutProgre
  * Replays the provider-visible half of a recorded session: model audio, tool requests,
  * and provider errors, in recorded order and (optionally) recorded pacing. Input audio,
  * playout acknowledgements, tool results, and context are accepted and captured but do
- * not influence playback. This is the shadow-test primitive: re-drive UIs, tools, and
- * stores from an authoritative log without a live model or an API key.
+ * not influence playback. This re-drives UIs and stores from a recorded log without a
+ * live model or an API key.
+ *
+ * Playback closes after the last recorded output, even if a replayed tool request is
+ * still awaiting admission or execution. Recorded tool outcomes are not replayed.
+ * Use ScriptedVoiceProvider when subsequent output must wait for and verify results.
  */
 export class ReplayVoiceProvider {
     id = "replay";
@@ -114,14 +118,18 @@ export class ReplayVoiceProviderSession {
 }
 function isReplayable(event) {
     return (event.type === "audio.output" ||
+        event.type === "audio.interrupted" ||
         event.type === "transcript" ||
         event.type === "tool.requested" ||
-        event.type === "provider.error");
+        event.type === "provider.error" ||
+        event.type === "provider.diagnostic");
 }
 function toProviderEvent(event) {
     switch (event.type) {
         case "audio.output":
             return { type: "audio.output", chunk: event.chunk };
+        case "audio.interrupted":
+            return { type: "audio.interrupted", streamId: event.streamId };
         case "transcript":
             return {
                 type: "transcript",
@@ -133,5 +141,7 @@ function toProviderEvent(event) {
             return { type: "tool.call", call: event.call };
         case "provider.error":
             return { type: "error", message: event.message, recoverable: event.recoverable };
+        case "provider.diagnostic":
+            return { type: "diagnostic", diagnostic: event.diagnostic };
     }
 }

package/dist/internal/skills/index.d.ts

@@ -0,0 +1,2 @@
+export { parseSkillMarkdown, type Skill, type SkillMetadata, skillFromMarkdown } from "./skill.js";
+export { createSkillTools } from "./tools.js";

package/dist/internal/skills/index.js

@@ -0,0 +1,2 @@
+export { parseSkillMarkdown, skillFromMarkdown } from "./skill.js";
+export { createSkillTools } from "./tools.js";

package/dist/internal/skills/node.d.ts

@@ -0,0 +1,7 @@
+import { type Skill } from "./skill.js";
+/**
+ * Discovers immediate skill directories in explicitly trusted roots. Missing roots
+ * are ignored; malformed skills and duplicates fail with a path for the host to fix.
+ * Nothing scans the user's home, executes scripts, or grants allowed-tools.
+ */
+export declare function loadSkillsFromDirectories(directories: readonly string[]): Promise<readonly Skill[]>;

package/dist/internal/skills/node.js

@@ -0,0 +1,99 @@
+import { constants } from "node:fs";
+import { open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { parseSkillMarkdown, validateSkillPath } from "./skill.js";
+// Skills are text guidance, not an unbounded file export API. Resource paging bounds
+// model context; this limit also bounds host memory during discovery and reads.
+const MAX_FILE_BYTES = 1024 * 1024;
+/**
+ * Discovers immediate skill directories in explicitly trusted roots. Missing roots
+ * are ignored; malformed skills and duplicates fail with a path for the host to fix.
+ * Nothing scans the user's home, executes scripts, or grants allowed-tools.
+ */
+export async function loadSkillsFromDirectories(directories) {
+    const skills = new Map();
+    for (const directory of directories) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            throw error;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if ((!entry.isDirectory() && !entry.isSymbolicLink()) || entry.name.startsWith("."))
+                continue;
+            const location = path.resolve(directory, entry.name);
+            let root;
+            let markdown;
+            try {
+                root = await realpath(location);
+                markdown = await readSkillFile(root, "SKILL.md");
+            }
+            catch (error) {
+                if (isMissing(error))
+                    continue;
+                throw new Error(`Cannot load skill at ${location}`, { cause: error });
+            }
+            let metadata;
+            try {
+                metadata = parseSkillMarkdown(markdown);
+                if (metadata.name !== entry.name)
+                    throw new Error("Skill name must match its directory name");
+                if (skills.has(metadata.name))
+                    throw new Error(`Duplicate skill name: ${metadata.name}`);
+            }
+            catch (error) {
+                throw new Error(`Invalid skill at ${location}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+            skills.set(metadata.name, {
+                ...metadata,
+                // Freeze the activated instructions to the catalog that was discovered.
+                read: (resource, signal) => {
+                    signal.throwIfAborted();
+                    return resource === "SKILL.md" ? markdown : readSkillFile(root, resource, signal);
+                },
+            });
+        }
+    }
+    return [...skills.values()];
+}
+async function readSkillFile(root, resource, signal) {
+    validateSkillPath(resource);
+    signal?.throwIfAborted();
+    const target = await realpath(path.join(root, resource));
+    const relative = path.relative(root, target);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error("Skill resource resolves outside its skill directory");
+    }
+    // Nonblocking open lets fstat reject FIFOs instead of waiting forever for a writer.
+    const file = await open(target, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile())
+            throw new Error("Skill resource must be a regular text file");
+        const bytes = new Uint8Array(MAX_FILE_BYTES + 1);
+        let size = 0;
+        while (size < bytes.length) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await file.read(bytes, size, bytes.length - size, null);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+        }
+        if (size > MAX_FILE_BYTES)
+            throw new Error("Skill resource exceeds the 1 MiB text limit");
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, size));
+        if (text.includes("\u0000"))
+            throw new Error("Skill resource must be UTF-8 text without NUL bytes");
+        return text;
+    }
+    finally {
+        await file.close();
+    }
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}