@cozibud/harness 0.1.0 → 0.2.1

package/README.md

@@ -1,24 +1,54 @@
-# `@cozibud/harness`
-
-Internal infrastructure for the Cozibud Watch local-client bridge. It invokes a
-supported local AI client and exposes the provider-neutral runtime used by the
-bridge engineering tools.
-
-This package is not a released Watch feature. The authenticated server relay,
-device pairing, and production delivery path are not included, and the local
-HTTP adapter must not be exposed to a LAN or the internet.
-
-## Maintainer smoke check
-
-After building or installing an explicitly reviewed version:
-
-```text
-cozibud-harness --help
-```
-
-Provider setup and request commands are internal acceptance tools. They use the
-provider's own installed client and sign-in state; the harness does not accept
-or store provider passwords.
-
-Release and bootstrap procedures live in the private repository's
-`docs/NPM-HARNESS-PUBLISHING.md` operator runbook.
+# `@cozibud/harness`
+
+Connect a signed-in Codex CLI to your Cozibud household for watch voice.
+Keep the computer awake and the outbound relay running while using voice.
+Watch voice requires Codex CLI 0.159.0 or newer and a server supporting relay
+protocol 2. This source version still needs its package and server release.
+
+## Watch voice
+
+After installing the released harness, sign in to Codex with `codex login`.
+Run this single command:
+
+```text
+cozibud-harness relay --provider codex
+```
+
+On the first run, open the displayed Cozibud link and approve your computer
+in the household you use on your watch. The command then connects automatically.
+Later runs reuse the saved pairing. Keep this command running and the computer awake.
+If the watch finds no connected computer, **Open guide on phone** shows the setup steps.
+
+On the watch, select the child, speak, and check the transcript. **Send & save**
+authorizes the server to validate and save one record. Ambiguous requests ask
+for clarification. A saved-record receipt appears only after server readback.
+No microphone audio is sent to the bridge; the confirmed transcript and selected
+child context go to your signed-in Codex client and its model service.
+
+Your Codex login stays local. Pairing credentials are protected with your
+Windows account's DPAPI on Windows, or a user-only file on other systems.
+Disconnect the computer in Cozibud's Watch settings to revoke its access.
+Each Cozibud account can pair two computers. The one connected longest answers
+requests from the web app, the phone app and the watch; the other is a backup
+that takes over when the first stops reporting in. Run `pair` again on a computer
+to replace its pairing, or choose the household and account by signing in to the
+one you want when you approve the link. Codex uses whichever account `codex login`
+signed in (set `CODEX_HOME` to keep a separate Codex profile).
+Use `COZIBUD_RELAY_URL` to choose another HTTPS server before pairing; pairings
+are scoped to that origin. The relay requires no inbound computer port.
+The separate local HTTP adapter must remain on loopback.
+
+## Maintainer smoke check
+
+After building or installing an explicitly reviewed version:
+
+```text
+cozibud-harness --help
+```
+
+Provider setup and request commands are internal acceptance tools. They use the
+provider's own installed client and sign-in state; the harness does not accept
+or store provider passwords.
+
+Release and bootstrap procedures live in the private repository's
+`docs/NPM-HARNESS-PUBLISHING.md` operator runbook.

package/dist/cli.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { ensureRelayPairing, pairRelay, relayOrigin } from "./pairing.js";
 import { createBuiltInDrivers } from "./process-driver.js";
+import { FileRelayExecutionStore, OutboundRelayBridge, RelayTransportError } from "./relay-client.js";
 import { HarnessRuntime } from "./runtime.js";
 import { createHarnessHttpServer } from "./server.js";
 import { DEFAULT_COZIBUD_MCP_URL, setupProvider } from "./setup.js";
@@ -20,26 +25,96 @@ function promptFrom(args) {
     return parts.join(" ").trim();
 }
 function printHelp() {
-    console.log(`Cozibud local LLM harness
-
-Usage:
-  cozibud-harness setup [--provider codex|claude|gemini|cursor] [--mcp-url https://cozibud.com/api/mcp]
-  cozibud-harness ask [--provider codex|claude|gemini|cursor] [--locale en-US] "When was the last bottle?"
-  cozibud-harness serve [--host 127.0.0.1] [--port 8798]
-
-Quick start:
-  setup   prepares a signed-in local client and the MCP access its bridge turns need
-  ask     sends one typed request through an already signed-in provider
-
-Environment:
-  COZIBUD_HARNESS_TOKEN     bearer token (generated for this run when omitted)
-  COZIBUD_HARNESS_ORIGINS   comma-separated browser origins allowed by CORS
-  COZIBUD_CODEX_PATH        optional Codex executable path
-  COZIBUD_CLAUDE_PATH       optional Claude executable path
-  COZIBUD_GEMINI_PATH       optional Gemini executable path
-  COZIBUD_CURSOR_PATH       optional Cursor Agent executable path
+    console.log(`Cozibud local LLM harness
+
+Usage:
+  cozibud-harness setup [--provider codex|claude|gemini|cursor] [--mcp-url https://cozibud.com/api/mcp]
+  cozibud-harness ask [--provider codex|claude|gemini|cursor] [--locale en-US] "When was the last bottle?"
+  cozibud-harness relay [--provider codex]
+  cozibud-harness pair [--name "My computer"]
+  cozibud-harness serve [--host 127.0.0.1] [--port 8798]
+
+Quick start:
+  setup   prepares a signed-in local client and the MCP access its bridge turns need
+  ask     sends one typed request through an already signed-in provider
+  relay   pairs this computer if needed, then keeps watch voice connected
+
+Environment:
+  COZIBUD_HARNESS_TOKEN     bearer token (generated for this run when omitted)
+  COZIBUD_HARNESS_ORIGINS   comma-separated browser origins allowed by CORS
+  COZIBUD_RELAY_URL          canonical Cozibud origin (defaults to https://cozibud.com)
+  COZIBUD_RELAY_CREDENTIAL   optional paired credential override (never printed)
+  COZIBUD_RELAY_PAIRING      protected pairing file path
+  COZIBUD_RELAY_STATE        local idempotency journal path
+  COZIBUD_CODEX_PATH        optional Codex executable path
+  COZIBUD_CLAUDE_PATH       optional Claude executable path
+  COZIBUD_GEMINI_PATH       optional Gemini executable path
+  COZIBUD_CURSOR_PATH       optional Cursor Agent executable path
+  COZIBUD_CURSOR_WORKSPACE  stable dedicated empty Cursor bridge workspace
   COZIBUD_CURSOR_MCP_CONFIG optional Cursor user MCP config path (test/development override)`);
 }
+async function relay(args) {
+    const provider = value(args, "--provider", "codex");
+    const driver = createBuiltInDrivers().find((candidate) => candidate.id === provider);
+    if (!driver)
+        throw new Error(`Unknown provider: ${provider}. Choose codex, claude, gemini, or cursor.`);
+    if (provider !== "codex")
+        throw new Error("Watch voice currently requires Codex CLI.");
+    const baseUrl = relayOrigin(process.env.COZIBUD_RELAY_URL?.trim() || "https://cozibud.com");
+    const available = await driver.probe();
+    if (available.state === "unavailable")
+        throw new Error(available.message);
+    const version = available.version?.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!version || (Number(version[1]) === 0 && Number(version[2]) < 159))
+        throw new Error("Watch voice requires Codex CLI 0.159.0 or newer. Update Codex, sign in, and retry.");
+    const controller = new AbortController();
+    process.once("SIGINT", () => controller.abort());
+    process.once("SIGTERM", () => controller.abort());
+    let credential = process.env.COZIBUD_RELAY_CREDENTIAL?.trim() || await ensureRelayPairing({ origin: baseUrl,
+        name: value(args, "--name", hostname()), path: pairingPath(), write: console.log, signal: controller.signal });
+    const createBridge = () => {
+        const namespace = createHash("sha256").update(`${baseUrl}\n${credential}`).digest("hex").slice(0, 20);
+        const statePath = process.env.COZIBUD_RELAY_STATE?.trim() || join(homedir(), ".cozibud", `relay-state-${namespace}.json`);
+        return new OutboundRelayBridge({ baseUrl, credential, driver, store: new FileRelayExecutionStore(statePath) });
+    };
+    let bridge = createBridge();
+    let repaired = false;
+    let connected = false;
+    let backoffMs = 1_000;
+    while (!controller.signal.aborted) {
+        try {
+            if (!connected) {
+                await bridge.connect();
+                connected = true;
+                backoffMs = 1_000;
+                console.log(`Cozibud relay connected with ${driver.label}. No local or LAN listener is open.`);
+            }
+            const state = await bridge.step();
+            if (state === "idle")
+                await pause(1_000, controller.signal);
+        }
+        catch (error) {
+            if (error instanceof RelayTransportError && [401, 403, 404].includes(error.status)) {
+                await bridge.close();
+                if ([401, 403].includes(error.status) && !process.env.COZIBUD_RELAY_CREDENTIAL?.trim() && !repaired && !controller.signal.aborted) {
+                    repaired = true;
+                    console.log("This computer's pairing is no longer valid. Approve it again to reconnect.");
+                    credential = await pairRelay({ origin: baseUrl, name: value(args, "--name", hostname()), path: pairingPath(), write: console.log, signal: controller.signal });
+                    bridge = createBridge();
+                    connected = false;
+                    continue;
+                }
+                throw new Error("Desktop pairing is expired, revoked, or disabled. Run pair again on the selected server.");
+            }
+            connected = false;
+            console.error("Cozibud relay disconnected; retrying the outbound connection.");
+            await pause(backoffMs, controller.signal);
+            backoffMs = Math.min(15_000, backoffMs * 2);
+        }
+    }
+    await bridge.close();
+}
+function pairingPath() { return process.env.COZIBUD_RELAY_PAIRING?.trim() || join(homedir(), ".cozibud", "relay-pairing.json"); }
 async function ask(args) {
     const provider = value(args, "--provider", "codex");
     const locale = value(args, "--locale", "en-US");
@@ -118,6 +193,11 @@ try {
     }
     else if (command === "ask")
         await ask(args);
+    else if (command === "relay")
+        await relay(args);
+    else if (command === "pair")
+        await pairRelay({ origin: process.env.COZIBUD_RELAY_URL || "https://cozibud.com",
+            name: value(args, "--name", hostname()), path: pairingPath(), write: console.log });
     else if (command === "serve")
         await serve(args);
     else
@@ -127,3 +207,12 @@ catch (error) {
     console.error(error instanceof Error ? error.message : "The local harness failed.");
     process.exitCode = 1;
 }
+function pause(ms, signal) {
+    return new Promise(resolve => {
+        const done = () => { clearTimeout(timer); signal.removeEventListener("abort", done); resolve(); };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+        if (signal.aborted)
+            done();
+    });
+}

package/dist/contracts.d.ts

@@ -7,6 +7,10 @@ export interface HarnessTurnInput {
     source: HarnessInputSource;
     client: HarnessClient;
     locale?: string;
+    /** Server request-bound identity that every care-record write must use. */
+    careRecordIdempotencyKey?: string;
+    /** Server-supplied interpretation instructions; no MCP writes in this mode. */
+    interpretation?: string;
 }
 export interface HarnessTurnRequest extends HarnessTurnInput {
     harness: string;

package/dist/cursor-workspace.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_CURSOR_WORKSPACE: string;
+export declare function cursorWorkspacePath(configured?: string | undefined): string;
+export declare function ensureCursorWorkspace(configured?: string): string;

package/dist/cursor-workspace.js

@@ -0,0 +1,39 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+export const DEFAULT_CURSOR_WORKSPACE = join(homedir(), ".cozibud", "cursor-workspace");
+export function cursorWorkspacePath(configured = process.env.COZIBUD_CURSOR_WORKSPACE) {
+    const override = configured?.trim();
+    if (override && !isAbsolute(override))
+        throw new Error("COZIBUD_CURSOR_WORKSPACE must be an absolute path.");
+    const candidate = override || DEFAULT_CURSOR_WORKSPACE;
+    return resolve(candidate);
+}
+export function ensureCursorWorkspace(configured) {
+    const workspace = cursorWorkspacePath(configured);
+    const root = parse(workspace).root;
+    const current = resolve(process.cwd());
+    const isWithin = (parent, candidate) => {
+        const path = relative(parent, candidate);
+        return path !== "" && !isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`);
+    };
+    if (workspace === root || workspace === current || isWithin(current, workspace) || isWithin(workspace, current)) {
+        throw new Error("Cursor bridge workspace must be dedicated and outside the current repository or worktree.");
+    }
+    try {
+        const state = lstatSync(workspace);
+        if (state.isSymbolicLink() || !state.isDirectory()) {
+            throw new Error("Cursor bridge workspace must be a real directory, not a file or symbolic link.");
+        }
+        if (readdirSync(workspace).length !== 0) {
+            throw new Error("Cursor bridge workspace must be empty and dedicated to Cozibud.");
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        mkdirSync(workspace, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(workspace, 0o700);
+    return workspace;
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from "./process-driver.js";
 export * from "./runtime.js";
 export * from "./server.js";
 export * from "./setup.js";
+export * from "./relay-client.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export * from "./process-driver.js";
 export * from "./runtime.js";
 export * from "./server.js";
 export * from "./setup.js";
+export * from "./relay-client.js";

package/dist/pairing-secret.d.ts

@@ -0,0 +1,8 @@
+export declare function protectPairing(value: string): Promise<{
+    protection: string;
+    value: string;
+}>;
+export declare function unprotectPairing(row: {
+    protection: string;
+    value: string;
+}): Promise<string>;

package/dist/pairing-secret.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+/** Windows DPAPI binds the pairing secret to the signed-in OS user. */
+async function dpapi(value, decrypt) {
+    const script = [
+        "Add-Type -AssemblyName System.Security;",
+        "$inputValue = [Console]::In.ReadToEnd();",
+        decrypt
+            ? "$bytes = [Convert]::FromBase64String($inputValue); $plain = [Security.Cryptography.ProtectedData]::Unprotect($bytes,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser); [Console]::Out.Write([Text.Encoding]::UTF8.GetString($plain));"
+            : "$bytes = [Text.Encoding]::UTF8.GetBytes($inputValue); $protected = [Security.Cryptography.ProtectedData]::Protect($bytes,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser); [Console]::Out.Write([Convert]::ToBase64String($protected));",
+    ].join("\n");
+    return new Promise((resolve, reject) => {
+        const child = spawn(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { windowsHide: true, stdio: ["pipe", "pipe", "ignore"] });
+        let output = "";
+        const timer = setTimeout(() => child.kill(), 10_000);
+        child.stdout.on("data", chunk => { output += chunk.toString(); });
+        child.stdin.on("error", () => { });
+        child.once("error", () => { clearTimeout(timer); reject(new Error("Could not access the protected desktop pairing.")); });
+        child.once("close", code => { clearTimeout(timer); code === 0 ? resolve(output) : reject(new Error("Could not access the protected desktop pairing. Pair again on this computer.")); });
+        // Plaintext never appears in argv, environment values or diagnostics.
+        child.stdin.end(value);
+    });
+}
+export async function protectPairing(value) {
+    return process.platform === "win32" ? { protection: "dpapi", value: await dpapi(value, false) }
+        : { protection: "user-file", value };
+}
+export async function unprotectPairing(row) {
+    if (row.protection === "dpapi" && process.platform === "win32")
+        return dpapi(row.value, true);
+    if (row.protection === "user-file" && process.platform !== "win32")
+        return row.value;
+    throw new Error("This pairing cannot be used on this computer. Run pair again.");
+}

package/dist/pairing.d.ts

@@ -0,0 +1,14 @@
+export declare function relayOrigin(value: string): string;
+export declare function readPairing(path: string, origin: string): Promise<string | null>;
+export declare function pairRelay(options: {
+    origin: string;
+    name: string;
+    path: string;
+    write: (message: string) => void;
+    fetchImpl?: typeof fetch;
+    wait?: (ms: number) => Promise<void>;
+    now?: () => number;
+    signal?: AbortSignal;
+}): Promise<string>;
+/** Relay is also the first-run setup command; approval remains in the browser. */
+export declare function ensureRelayPairing(options: Parameters<typeof pairRelay>[0]): Promise<string>;

package/dist/pairing.js

@@ -0,0 +1,89 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { protectPairing, unprotectPairing } from "./pairing-secret.js";
+export function relayOrigin(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.pathname !== "/" || url.search || url.hash ||
+        (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) {
+        throw new Error("Use an HTTPS server origin, or HTTP on loopback for local testing.");
+    }
+    return url.origin;
+}
+export async function readPairing(path, origin) {
+    try {
+        const row = JSON.parse(await unprotectPairing(JSON.parse(await readFile(path, "utf8"))));
+        if (row.origin !== relayOrigin(origin) || !Number.isFinite(Date.parse(row.expiresAt)) || Date.parse(row.expiresAt) <= Date.now())
+            return null;
+        if (typeof row.credential !== "string" || !row.credential.startsWith("cbr_"))
+            throw new Error("Invalid local pairing. Run pair again.");
+        return row.credential;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function pairRelay(options) {
+    const origin = relayOrigin(options.origin), fetcher = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const wait = options.wait ?? (ms => new Promise((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); options.signal?.removeEventListener("abort", abort); };
+        const done = () => { cleanup(); resolve(); };
+        const abort = () => { cleanup(); reject(options.signal?.reason); };
+        const timer = setTimeout(done, ms);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+    }));
+    const post = (path, body) => fetcher(`${origin}${path}`, { method: "POST", redirect: "error",
+        headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000) });
+    const response = await post("/api/watch-relay/v1/bridge-authorizations", { bridgeName: options.name });
+    if (!response.ok)
+        throw new Error(response.status === 404 ? "Watch voice is not enabled on this server yet." : "Could not start desktop pairing. Try again later.");
+    const authorization = await response.json();
+    if (!authorization.device_code || !authorization.user_code || !Number.isFinite(authorization.expires_in) || !Number.isFinite(authorization.interval))
+        throw new Error("Invalid pairing response.");
+    const activation = new URL("/watch/activate", origin);
+    activation.searchParams.set("bridge", "1");
+    activation.searchParams.set("code", authorization.user_code);
+    options.write(`Open ${activation.href}\nSign in to your Cozibud household and approve ${options.name}.`);
+    const deadline = now() + authorization.expires_in * 1000;
+    let interval = Math.max(5, authorization.interval);
+    while (now() < deadline) {
+        await wait(interval * 1000);
+        options.signal?.throwIfAborted();
+        if (now() >= deadline)
+            break;
+        const exchange = await post("/api/watch-relay/v1/token", { deviceCode: authorization.device_code });
+        const result = await exchange.json();
+        if (exchange.ok && result.credential?.startsWith("cbr_") && Number.isFinite(result.expiresIn)) {
+            await mkdir(dirname(options.path), { recursive: true, mode: 0o700 });
+            const protectedPairing = await protectPairing(JSON.stringify({ origin, credential: result.credential, bridgeId: result.bridgeId,
+                expiresAt: new Date(now() + result.expiresIn * 1000).toISOString() }));
+            await writeFile(options.path, JSON.stringify(protectedPairing), { mode: 0o600 });
+            if (process.platform !== "win32")
+                await chmod(options.path, 0o600);
+            options.write("Desktop paired.");
+            return result.credential;
+        }
+        if (result.error?.code === "authorization_pending")
+            continue;
+        if (result.error?.code === "slow_down" || exchange.status === 429) {
+            interval += 5;
+            continue;
+        }
+        if (result.error?.code === "bridge_limit")
+            throw new Error("Your account already has two computers paired. Disconnect one in Cozibud under Settings → Assistants & API → Voice with a local agent, then run pair again.");
+        throw new Error("Pairing was denied or expired. Run pair again.");
+    }
+    throw new Error("Pairing expired. Run pair again.");
+}
+/** Relay is also the first-run setup command; approval remains in the browser. */
+export async function ensureRelayPairing(options) {
+    const saved = await readPairing(options.path, options.origin);
+    if (saved)
+        return saved;
+    options.write("This computer needs pairing. Approve it in Cozibud; the relay will start automatically.");
+    return pairRelay(options);
+}

package/dist/process-driver.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessDriver } from "./contracts.js";
+import type { HarnessDriver, HarnessTurnInput } from "./contracts.js";
 declare const TEMP_DIRECTORY_CLEANUP_OPTIONS: {
     readonly recursive: true;
     readonly force: true;
@@ -13,7 +13,7 @@ export interface ProcessHarnessDefinition {
     versionArgs?: string[];
     /** Applied only to a fresh empty directory created by this driver. */
     emptyDirectoryArgs?: string[];
-    args(): string[];
+    args(input?: HarnessTurnInput): string[];
 }
 declare function messageText(value: unknown): string | null;
 declare function appendNovelText(current: string, candidate: string): {