@cozibud/harness 0.1.0 → 0.2.1

package/dist/process-driver.js

@@ -1,12 +1,40 @@
 import { spawn } from "node:child_process";
 import { mkdtemp, rm } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { delimiter, isAbsolute, join } from "node:path";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
+import { ensureCursorWorkspace } from "./cursor-workspace.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TEMP_DIRECTORY_CLEANUP_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 };
+let cursorRunTail = Promise.resolve();
+async function acquireCursorRun(signal, label) {
+    const predecessor = cursorRunTail.catch(() => undefined);
+    let release;
+    const held = new Promise((resolve) => { release = resolve; });
+    cursorRunTail = predecessor.then(() => held);
+    if (signal.aborted) {
+        void predecessor.then(release);
+        throw new Error(`${label} was cancelled.`);
+    }
+    let cancelWait;
+    const cancelled = new Promise((_, reject) => {
+        cancelWait = () => reject(new Error(`${label} was cancelled.`));
+        signal.addEventListener("abort", cancelWait, { once: true });
+    });
+    try {
+        await Promise.race([predecessor, cancelled]);
+    }
+    catch (error) {
+        void predecessor.then(release);
+        throw error;
+    }
+    finally {
+        signal.removeEventListener("abort", cancelWait);
+    }
+    return release;
+}
 function stopProcess(child) {
     if (!child.pid || child.exitCode !== null)
         return;
@@ -24,6 +52,8 @@ function stopProcess(child) {
     }
 }
 function carePrompt(input) {
+    if (input.interpretation)
+        return `${input.interpretation}\n<caregiver_request>\n${input.prompt}\n</caregiver_request>`;
     const origin = `${input.client} ${input.source}`;
     return [
         "You are handling a Cozibud family-care request.",
@@ -31,6 +61,10 @@ function carePrompt(input) {
         "Do not inspect or modify local files and do not run shell commands.",
         "Ask a short follow-up only when ambiguity would make a care record incorrect.",
         "Otherwise return a concise, spoken-friendly answer and confirm writes only after the tool succeeds.",
+        ...(input.careRecordIdempotencyKey ? [
+            `For every Cozibud care-record write in this turn, pass clientEventId exactly ${input.careRecordIdempotencyKey}.`,
+            "Do not claim that a care record was saved unless the Cozibud tool succeeds with that identity.",
+        ] : []),
         `Input origin: ${origin}. Locale: ${input.locale ?? "unspecified"}.`,
         "<caregiver_request>",
         input.prompt,
@@ -88,8 +122,9 @@ export function createProcessHarnessDriver(definition, options = {}) {
         command: definition.command,
         authentication: "existing-login",
         async probe() {
+            const probeCwd = definition.id === "cursor" ? ensureCursorWorkspace(options.cwd) : options.cwd;
             return await new Promise((resolve) => {
-                const child = spawn(definition.command, definition.versionArgs ?? ["--version"], { ...spawnOptions, stdio: ["ignore", "pipe", "pipe"] });
+                const child = spawn(definition.command, definition.versionArgs ?? ["--version"], { ...spawnOptions, cwd: probeCwd, stdio: ["ignore", "pipe", "pipe"] });
                 let output = "";
                 let bytes = 0;
                 let overflow = false;
@@ -124,130 +159,139 @@ export function createProcessHarnessDriver(definition, options = {}) {
         async run(input, context) {
             if (context.signal.aborted)
                 throw new Error(`${definition.label} was cancelled.`);
-            const ephemeralCwd = options.cwd ? null : await mkdtemp(join(tmpdir(), "cozibud-harness-"));
-            let turnError;
+            const releaseCursor = definition.id === "cursor" ? await acquireCursorRun(context.signal, definition.label) : undefined;
             try {
-                if (context.signal.aborted)
-                    throw new Error(`${definition.label} was cancelled.`);
-                return await new Promise((resolve, reject) => {
-                    const args = [...definition.args(), ...(ephemeralCwd ? definition.emptyDirectoryArgs ?? [] : [])];
-                    const child = spawn(definition.command, args, { ...spawnOptions, cwd: options.cwd ?? ephemeralCwd, stdio: ["pipe", "pipe", "pipe"] });
-                    child.stdin.on("error", () => { });
-                    child.stdin.end(carePrompt(input));
-                    const decoder = new StringDecoder("utf8");
-                    let pending = "";
-                    let response = "";
-                    let outputBytes = 0;
-                    let settled = false;
-                    let timedOut = false;
-                    let failure;
-                    let stopping = false;
-                    const stop = () => { if (!stopping) {
-                        stopping = true;
-                        stopProcess(child);
-                    } };
-                    const finish = (error) => {
-                        if (settled)
-                            return;
-                        settled = true;
-                        clearTimeout(timer);
-                        context.signal.removeEventListener("abort", abort);
-                        if (error)
-                            reject(error);
-                        else
-                            resolve({ text: response.trim() });
-                    };
-                    const abort = () => stop();
-                    context.signal.addEventListener("abort", abort, { once: true });
-                    const timer = setTimeout(() => { timedOut = true; stop(); }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-                    const lineReceived = (line) => {
-                        if (failure || context.signal.aborted || timedOut)
-                            return;
-                        try {
-                            const event = JSON.parse(line);
-                            if (event?.type === "error" && event.severity === "warning")
+                const stableCwd = definition.id === "cursor" ? ensureCursorWorkspace(options.cwd) : options.cwd;
+                const ephemeralCwd = stableCwd ? null : await mkdtemp(join(tmpdir(), "cozibud-harness-"));
+                let turnError;
+                try {
+                    if (context.signal.aborted)
+                        throw new Error(`${definition.label} was cancelled.`);
+                    return await new Promise((resolve, reject) => {
+                        const args = [...definition.args(input), ...(ephemeralCwd ? definition.emptyDirectoryArgs ?? [] : [])];
+                        const child = spawn(definition.command, args, { ...spawnOptions, cwd: stableCwd ?? ephemeralCwd, stdio: ["pipe", "pipe", "pipe"] });
+                        child.stdin.on("error", () => { });
+                        child.stdin.end(carePrompt(input));
+                        const decoder = new StringDecoder("utf8");
+                        let pending = "";
+                        let response = "";
+                        let outputBytes = 0;
+                        let settled = false;
+                        let timedOut = false;
+                        let failure;
+                        let stopping = false;
+                        const stop = () => { if (!stopping) {
+                            stopping = true;
+                            stopProcess(child);
+                        } };
+                        const finish = (error) => {
+                            if (settled)
                                 return;
-                            if (event && (event.is_error === true || event.type === "error" || event.type === "turn.failed" || event.error)) {
-                                failure = new Error(`${definition.label} reported a failed turn. Check the client's sign-in, subscription, and Cozibud MCP authorization, then retry.`);
-                                stop();
+                            settled = true;
+                            clearTimeout(timer);
+                            context.signal.removeEventListener("abort", abort);
+                            if (error)
+                                reject(error);
+                            else
+                                resolve({ text: response.trim() });
+                        };
+                        const abort = () => stop();
+                        context.signal.addEventListener("abort", abort, { once: true });
+                        const timer = setTimeout(() => { timedOut = true; stop(); }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+                        const lineReceived = (line) => {
+                            if (failure || context.signal.aborted || timedOut)
                                 return;
+                            try {
+                                const event = JSON.parse(line);
+                                if (event?.type === "error" && event.severity === "warning")
+                                    return;
+                                if (event && (event.is_error === true || event.type === "error" || event.type === "turn.failed" || event.error)) {
+                                    failure = new Error(`${definition.label} reported a failed turn. Check the client's sign-in, subscription, and Cozibud MCP authorization, then retry.`);
+                                    stop();
+                                    return;
+                                }
+                                const candidate = messageText(event);
+                                if (!candidate)
+                                    return;
+                                const next = event.type === "message" && event.delta === true
+                                    ? { value: response + candidate, delta: candidate }
+                                    : appendNovelText(response, candidate);
+                                response = next.value;
+                                if (next.delta)
+                                    context.emit({ type: "assistant.delta", text: next.delta });
+                            }
+                            catch {
+                                // Never return provider diagnostics as household answers.
                             }
-                            const candidate = messageText(event);
-                            if (!candidate)
+                        };
+                        const count = (chunk) => {
+                            outputBytes += chunk.length;
+                            if (outputBytes <= MAX_OUTPUT_BYTES && !failure)
+                                return true;
+                            if (!failure) {
+                                failure = new Error("Harness output exceeded the 1 MiB safety limit.");
+                                pending = "";
+                                stop();
+                            }
+                            return false;
+                        };
+                        child.stderr.on("data", (chunk) => { count(chunk); });
+                        child.stdout.on("data", (chunk) => {
+                            if (!count(chunk))
                                 return;
-                            const next = event.type === "message" && event.delta === true
-                                ? { value: response + candidate, delta: candidate }
-                                : appendNovelText(response, candidate);
-                            response = next.value;
-                            if (next.delta)
-                                context.emit({ type: "assistant.delta", text: next.delta });
+                            pending += decoder.write(chunk);
+                            let newline;
+                            while ((newline = pending.indexOf("\n")) >= 0) {
+                                const line = pending.slice(0, newline);
+                                pending = pending.slice(newline + 1);
+                                lineReceived(line);
+                            }
+                        });
+                        child.once("error", (error) => {
+                            finish(new Error(error.code === "ENOENT" ? `${definition.command} is not installed or is not on PATH.` : `${definition.label} failed to start.`));
+                        });
+                        child.once("close", (code) => {
+                            if (failure)
+                                return finish(failure);
+                            if (timedOut)
+                                return finish(new Error(`${definition.label} timed out.`));
+                            if (context.signal.aborted)
+                                return finish(new Error(`${definition.label} was cancelled.`));
+                            if (code !== 0)
+                                return finish(new Error(`${definition.label} exited with code ${code ?? "unknown"}. Check the client's sign-in, subscription, and Cozibud MCP authorization.`));
+                            lineReceived(pending + decoder.end());
+                            if (failure)
+                                return finish(failure);
+                            if (!response.trim())
+                                return finish(new Error(`${definition.label} returned no assistant response.`));
+                            finish();
+                        });
+                    });
+                }
+                catch (error) {
+                    turnError = error;
+                    throw error;
+                }
+                finally {
+                    if (definition.id === "cursor" && stableCwd)
+                        ensureCursorWorkspace(stableCwd);
+                    if (ephemeralCwd) {
+                        try {
+                            await (options.removeDirectory ?? rm)(ephemeralCwd, TEMP_DIRECTORY_CLEANUP_OPTIONS);
                         }
                         catch {
-                            // Never return provider diagnostics as household answers.
-                        }
-                    };
-                    const count = (chunk) => {
-                        outputBytes += chunk.length;
-                        if (outputBytes <= MAX_OUTPUT_BYTES && !failure)
-                            return true;
-                        if (!failure) {
-                            failure = new Error("Harness output exceeded the 1 MiB safety limit.");
-                            pending = "";
-                            stop();
-                        }
-                        return false;
-                    };
-                    child.stderr.on("data", (chunk) => { count(chunk); });
-                    child.stdout.on("data", (chunk) => {
-                        if (!count(chunk))
-                            return;
-                        pending += decoder.write(chunk);
-                        let newline;
-                        while ((newline = pending.indexOf("\n")) >= 0) {
-                            const line = pending.slice(0, newline);
-                            pending = pending.slice(newline + 1);
-                            lineReceived(line);
+                            const cleanupWarning = "Temporary working-directory cleanup did not complete.";
+                            if (turnError instanceof Error)
+                                turnError.message = `${turnError.message} ${cleanupWarning}`;
+                            else
+                                throw new Error(`${definition.label} completed, but temporary working-directory cleanup did not complete.`);
                         }
-                    });
-                    child.once("error", (error) => {
-                        finish(new Error(error.code === "ENOENT" ? `${definition.command} is not installed or is not on PATH.` : `${definition.label} failed to start.`));
-                    });
-                    child.once("close", (code) => {
-                        if (failure)
-                            return finish(failure);
-                        if (timedOut)
-                            return finish(new Error(`${definition.label} timed out.`));
-                        if (context.signal.aborted)
-                            return finish(new Error(`${definition.label} was cancelled.`));
-                        if (code !== 0)
-                            return finish(new Error(`${definition.label} exited with code ${code ?? "unknown"}. Check the client's sign-in, subscription, and Cozibud MCP authorization.`));
-                        lineReceived(pending + decoder.end());
-                        if (failure)
-                            return finish(failure);
-                        if (!response.trim())
-                            return finish(new Error(`${definition.label} returned no assistant response.`));
-                        finish();
-                    });
-                });
-            }
-            catch (error) {
-                turnError = error;
-                throw error;
-            }
-            finally {
-                if (ephemeralCwd) {
-                    try {
-                        await (options.removeDirectory ?? rm)(ephemeralCwd, TEMP_DIRECTORY_CLEANUP_OPTIONS);
-                    }
-                    catch {
-                        const cleanupWarning = "Temporary working-directory cleanup did not complete.";
-                        if (turnError instanceof Error)
-                            turnError.message = `${turnError.message} ${cleanupWarning}`;
-                        else
-                            throw new Error(`${definition.label} completed, but temporary working-directory cleanup did not complete.`);
                     }
                 }
             }
+            finally {
+                releaseCursor?.();
+            }
         },
     };
 }
@@ -263,17 +307,46 @@ export function executable(configured) {
         for (const directory of directories) {
             const base = directory ? join(directory, configured) : configured;
             const script = /\.ps1$/i.test(base) ? base : `${base}.ps1`;
-            if (existsSync(script))
-                return {
-                    command: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
-                    prefixArgs: ["-NoLogo", "-NoProfile", "-File", script],
-                };
+            if (!existsSync(script))
+                continue;
+            const shimmed = nodeShimTarget(script);
+            if (shimmed)
+                return shimmed;
+            return {
+                command: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+                prefixArgs: ["-NoLogo", "-NoProfile", "-File", script],
+            };
         }
     }
     return /\.(?:c|m)?js$/i.test(configured)
         ? { command: process.execPath, prefixArgs: [configured] }
         : { command: configured, prefixArgs: [] };
 }
+/**
+ * npm, pnpm and Yarn install a CLI on Windows as a PowerShell shim that runs a JavaScript entry point
+ * with Node. Running that entry point directly keeps arguments intact: `powershell -File` treats a bare
+ * `-` (read the prompt from stdin) as an unnamed parameter and fails before the CLI starts.
+ */
+function nodeShimTarget(script) {
+    let source;
+    try {
+        source = readFileSync(script, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (source.length > 16_384)
+        return null;
+    const target = /"\$basedir[\\/]([^"$`]+\.[cm]?js)"/i.exec(source)?.[1];
+    if (!target)
+        return null;
+    const basedir = dirname(script);
+    const entry = resolve(basedir, target);
+    if (!existsSync(entry))
+        return null;
+    const bundledNode = join(basedir, "node.exe");
+    return { command: existsSync(bundledNode) ? bundledNode : process.execPath, prefixArgs: [entry] };
+}
 const codexExecutable = executable(process.env.COZIBUD_CODEX_PATH || "codex");
 const claudeExecutable = executable(process.env.COZIBUD_CLAUDE_PATH || "claude");
 const geminiExecutable = executable(process.env.COZIBUD_GEMINI_PATH || "gemini");
@@ -284,7 +357,8 @@ export const builtInProcessHarnesses = [
         label: "Codex CLI",
         command: codexExecutable.command,
         versionArgs: [...codexExecutable.prefixArgs, "--version"],
-        args: () => [...codexExecutable.prefixArgs, "exec", "--json", "--ephemeral", "--skip-git-repo-check", "--sandbox", "read-only", "-c", "mcp_servers.cozibud.required=true", "-"],
+        args: (input) => [...codexExecutable.prefixArgs, "exec", "--json", "--ephemeral", "--skip-git-repo-check", "--sandbox", "read-only",
+            ...(input?.interpretation ? ["--ignore-user-config", "--ignore-rules", "-c", "features.shell_tool=false", "-c", "features.apps=false", "-c", "features.multi_agent=false", "-c", "features.hooks=false", "-c", "web_search=\"disabled\""] : ["-c", "mcp_servers.cozibud.required=true"]), "-"],
     },
     {
         id: "claude",
@@ -305,9 +379,13 @@ export const builtInProcessHarnesses = [
         id: "cursor",
         label: "Cursor Agent",
         command: cursorExecutable.command,
-        emptyDirectoryArgs: ["--trust"],
         versionArgs: [...cursorExecutable.prefixArgs, "--version"],
-        args: () => [...cursorExecutable.prefixArgs, "-p", "--output-format", "stream-json"],
+        args: () => [
+            ...cursorExecutable.prefixArgs,
+            "-p", "--output-format", "stream-json", "--mode", "ask",
+            ...(process.platform === "win32" ? [] : ["--sandbox", "enabled"]),
+            "--trust",
+        ],
     },
 ];
 export function createBuiltInDrivers() {

package/dist/relay-client.d.ts

@@ -0,0 +1,69 @@
+import type { HarnessDriver } from "./contracts.js";
+export type StoredExecution = {
+    state: "started";
+    updatedAt: string;
+} | {
+    state: "completed";
+    modelOutput: string;
+    updatedAt: string;
+} | {
+    state: "failed" | "cancelled";
+    code: string;
+    message: string;
+    updatedAt: string;
+};
+export interface RelayExecutionStore {
+    get(requestId: string): Promise<StoredExecution | null>;
+    set(requestId: string, value: StoredExecution): Promise<void>;
+}
+export declare class MemoryRelayExecutionStore implements RelayExecutionStore {
+    private readonly values;
+    get(id: string): Promise<StoredExecution | null>;
+    set(id: string, value: StoredExecution): Promise<void>;
+}
+/** Privacy-bounded local journal: request ids and terminal results only, never prompts or credentials. */
+export declare class FileRelayExecutionStore implements RelayExecutionStore {
+    private readonly path;
+    private readonly maxEntries;
+    private readonly retentionMs;
+    private writeQueue;
+    constructor(path: string, maxEntries?: number, retentionMs?: number);
+    private read;
+    get(id: string): Promise<StoredExecution | null>;
+    set(id: string, value: StoredExecution): Promise<void>;
+    private write;
+}
+type Fetch = typeof fetch;
+export declare class RelayTransportError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+export declare class OutboundRelayBridge {
+    private readonly options;
+    readonly connectionId: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly active;
+    private readonly tasks;
+    private readonly scheduled;
+    private readonly cancelled;
+    constructor(options: {
+        baseUrl: string;
+        credential: string;
+        driver: HarnessDriver;
+        store: RelayExecutionStore;
+        fetchImpl?: Fetch;
+        maxActive?: number;
+    });
+    private get fetcher();
+    private headers;
+    private json;
+    connect(): Promise<unknown>;
+    step(): Promise<"idle" | "command" | "cancel">;
+    idle(): Promise<void>;
+    close(): Promise<void>;
+    private acknowledge;
+    private result;
+    private fromStored;
+    private handle;
+}
+export {};

package/dist/relay-client.js

@@ -0,0 +1,166 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { WATCH_RELAY_PROTOCOL_VERSION } from "./relay-protocol.js";
+export class MemoryRelayExecutionStore {
+    values = new Map();
+    async get(id) { return this.values.get(id) ?? null; }
+    async set(id, value) { this.values.set(id, value); }
+}
+/** Privacy-bounded local journal: request ids and terminal results only, never prompts or credentials. */
+export class FileRelayExecutionStore {
+    path;
+    maxEntries;
+    retentionMs;
+    writeQueue = Promise.resolve();
+    constructor(path, maxEntries = 100, retentionMs = 24 * 60 * 60_000) {
+        this.path = path;
+        this.maxEntries = maxEntries;
+        this.retentionMs = retentionMs;
+    }
+    async read() {
+        try {
+            return JSON.parse(await readFile(this.path, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    }
+    async get(id) { await this.writeQueue; return (await this.read())[id] ?? null; }
+    async set(id, value) {
+        const write = this.writeQueue.then(() => this.write(id, value));
+        this.writeQueue = write.catch(() => { });
+        await write;
+    }
+    async write(id, value) {
+        const values = await this.read();
+        values[id] = value;
+        const cutoff = Date.now() - this.retentionMs;
+        const retained = Object.entries(values).filter(([, row]) => Date.parse(row.updatedAt) >= cutoff)
+            .sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt)).slice(0, this.maxEntries);
+        await mkdir(dirname(this.path), { recursive: true });
+        const temporary = `${this.path}.${process.pid}.tmp`;
+        await writeFile(temporary, JSON.stringify(Object.fromEntries(retained)), { encoding: "utf8", mode: 0o600 });
+        await rename(temporary, this.path);
+    }
+}
+export class RelayTransportError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super("Cozibud relay request failed.");
+        this.status = status;
+        this.code = code;
+    }
+}
+export class OutboundRelayBridge {
+    options;
+    connectionId = randomUUID();
+    active = new Map();
+    tasks = new Set();
+    scheduled = new Set();
+    cancelled = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get fetcher() { return this.options.fetchImpl ?? fetch; }
+    headers(extra) { return { authorization: `Bearer ${this.options.credential}`, ...extra }; }
+    async json(path, init) {
+        const response = await this.fetcher(new URL(path, this.options.baseUrl), { ...init, redirect: "error", signal: AbortSignal.timeout(20_000) });
+        if (!response.ok) {
+            const code = await response.json().then(value => value.error?.code).catch(() => undefined);
+            throw new RelayTransportError(response.status, code ?? `relay_http_${response.status}`);
+        }
+        return response.status === 204 ? null : response.json();
+    }
+    async connect() {
+        return this.json("/api/watch-relay/v1/connect", { method: "POST", headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ connectionId: this.connectionId, protocolVersion: WATCH_RELAY_PROTOCOL_VERSION }) });
+    }
+    async step() {
+        const full = this.scheduled.size >= (this.options.maxActive ?? 2);
+        const delivery = await this.json(`/api/watch-relay/v1/deliveries/next${full ? "?cancelOnly=1" : ""}`, { method: "GET",
+            headers: this.headers({ "x-cozibud-connection": this.connectionId }) });
+        if (!delivery)
+            return "idle";
+        if (delivery.type === "cancel") {
+            this.cancelled.add(delivery.requestId);
+            this.active.get(delivery.requestId)?.abort();
+            return "cancel";
+        }
+        if (this.scheduled.has(delivery.command.requestId)) {
+            await this.acknowledge(delivery.command);
+            return "command";
+        }
+        this.scheduled.add(delivery.command.requestId);
+        // A transport loss after the local terminal result is journaled is
+        // recovered by stable-id redelivery; do not turn it into an unhandled
+        // rejection or execute the provider again.
+        const task = this.handle(delivery.command).catch(() => { }).finally(() => { this.scheduled.delete(delivery.command.requestId); this.tasks.delete(task); });
+        this.tasks.add(task);
+        return "command";
+    }
+    async idle() { await Promise.all(this.tasks); }
+    async close() { for (const controller of this.active.values())
+        controller.abort(); await this.idle(); }
+    async acknowledge(command) {
+        await this.json(`/api/watch-relay/v1/deliveries/${command.deliveryId}/ack`, { method: "POST", headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ requestId: command.requestId, connectionId: this.connectionId }) });
+    }
+    async result(command, result) {
+        await this.json(`/api/watch-relay/v1/deliveries/${command.deliveryId}/result`, { method: "POST", headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ requestId: command.requestId, connectionId: this.connectionId, ...result }) });
+    }
+    fromStored(value) {
+        if (value.state === "completed")
+            return { state: "completed", modelOutput: value.modelOutput };
+        if (value.state === "started")
+            return { state: "failed", error: { code: "execution_interrupted", message: "The prior local execution ended without a durable result; it was not repeated." } };
+        return { state: value.state, error: { code: value.code, message: value.message } };
+    }
+    async handle(command) {
+        if (this.active.has(command.requestId)) {
+            await this.acknowledge(command);
+            return;
+        }
+        const stored = await this.options.store.get(command.requestId);
+        if (stored) {
+            await this.acknowledge(command);
+            await this.result(command, this.fromStored(stored));
+            return;
+        }
+        await this.acknowledge(command);
+        await this.options.store.set(command.requestId, { state: "started", updatedAt: new Date().toISOString() });
+        const controller = new AbortController();
+        this.active.set(command.requestId, controller);
+        if (this.cancelled.delete(command.requestId))
+            controller.abort();
+        let terminal;
+        if (controller.signal.aborted) {
+            terminal = { state: "cancelled", code: "cancelled", message: "The request was cancelled.", updatedAt: new Date().toISOString() };
+        }
+        else
+            try {
+                const prompt = command.transcript ?? JSON.stringify(command.action);
+                const source = command.source === "structured-action" ? "quick-action" : command.source;
+                const output = await this.options.driver.run({ prompt, source, client: command.client,
+                    interpretation: command.interpretation,
+                    careRecordIdempotencyKey: `relay:${command.requestId}` }, {
+                    turnId: command.requestId, signal: controller.signal,
+                    // Progress remains local in v1; bounded server progress is reserved by the protocol.
+                    emit: () => { },
+                });
+                terminal = { state: "completed", modelOutput: output.text, updatedAt: new Date().toISOString() };
+            }
+            catch (error) {
+                const cancelled = controller.signal.aborted;
+                terminal = { state: cancelled ? "cancelled" : "failed", code: cancelled ? "cancelled" : "provider_failed",
+                    message: cancelled ? "The request was cancelled." : (error instanceof Error ? error.message.slice(0, 512) : "The local provider failed."), updatedAt: new Date().toISOString() };
+            }
+        this.active.delete(command.requestId);
+        await this.options.store.set(command.requestId, terminal);
+        await this.result(command, this.fromStored(terminal));
+    }
+}

package/dist/relay-protocol.d.ts

@@ -0,0 +1,18 @@
+/** Versioned wire values consumed by the outbound Cozibud relay client. */
+export declare const WATCH_RELAY_PROTOCOL: "cozibud.watch-relay.v2";
+export declare const WATCH_RELAY_PROTOCOL_VERSION: 2;
+export type WatchRelayCommand = Readonly<{
+    protocol: typeof WATCH_RELAY_PROTOCOL;
+    requestId: string;
+    deliveryId: string;
+    attempt: number;
+    source: "typed" | "voice-transcript" | "structured-action";
+    client: "web" | "phone" | "watch";
+    transcript?: string;
+    action?: Readonly<{
+        id: string;
+        arguments: Readonly<Record<string, unknown>>;
+    }>;
+    expiresAt: string;
+    interpretation?: string;
+}>;

package/dist/relay-protocol.js

@@ -0,0 +1,3 @@
+/** Versioned wire values consumed by the outbound Cozibud relay client. */
+export const WATCH_RELAY_PROTOCOL = "cozibud.watch-relay.v2";
+export const WATCH_RELAY_PROTOCOL_VERSION = 2;