@cozibud/harness 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# `@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.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+import { createBuiltInDrivers } from "./process-driver.js";
+import { HarnessRuntime } from "./runtime.js";
+import { createHarnessHttpServer } from "./server.js";
+import { DEFAULT_COZIBUD_MCP_URL, setupProvider } from "./setup.js";
+function value(args, name, fallback) {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+}
+function promptFrom(args) {
+    const parts = [];
+    for (let index = 1; index < args.length; index += 1) {
+        if (["--provider", "--locale"].includes(args[index])) {
+            index += 1;
+            continue;
+        }
+        parts.push(args[index]);
+    }
+    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
+  COZIBUD_CURSOR_MCP_CONFIG optional Cursor user MCP config path (test/development override)`);
+}
+async function ask(args) {
+    const provider = value(args, "--provider", "codex");
+    const locale = value(args, "--locale", "en-US");
+    const prompt = promptFrom(args);
+    if (!prompt)
+        throw new Error('Add a request, for example: cozibud-harness ask "When was the last bottle?"');
+    if (prompt.length > 8_000)
+        throw new Error("Requests are limited to 8,000 characters.");
+    const driver = createBuiltInDrivers().find((candidate) => candidate.id === provider);
+    if (!driver)
+        throw new Error(`Unknown provider: ${provider}. Choose codex, claude, gemini, or cursor.`);
+    const availability = await driver.probe();
+    if (availability.state === "unavailable")
+        throw new Error(availability.message);
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once("SIGINT", cancel);
+    let streamed = false;
+    try {
+        const result = await driver.run({ prompt, source: "typed", client: "web", locale }, {
+            turnId: "cli",
+            signal: controller.signal,
+            emit: (event) => {
+                if (event.type !== "assistant.delta")
+                    return;
+                streamed = true;
+                process.stdout.write(event.text);
+            },
+        });
+        if (streamed)
+            process.stdout.write("\n");
+        else
+            console.log(result.text);
+    }
+    finally {
+        process.removeListener("SIGINT", cancel);
+    }
+}
+async function serve(args) {
+    const host = value(args, "--host", "127.0.0.1");
+    const port = Number(value(args, "--port", "8798"));
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Error("--port must be an integer from 1 to 65535.");
+    if (!["127.0.0.1", "::1", "localhost"].includes(host) && !args.includes("--allow-insecure-lan")) {
+        throw new Error("Refusing a non-loopback bind without --allow-insecure-lan. Use a TLS private-network proxy for a phone or watch.");
+    }
+    const configuredToken = process.env.COZIBUD_HARNESS_TOKEN?.trim();
+    const token = configuredToken || randomBytes(32).toString("base64url");
+    const origins = (process.env.COZIBUD_HARNESS_ORIGINS ?? "").split(",").map((origin) => origin.trim()).filter(Boolean);
+    const service = createHarnessHttpServer({ runtime: new HarnessRuntime(createBuiltInDrivers()), token, host, port, allowedOrigins: origins });
+    const address = await service.listen();
+    console.log(`Cozibud harness listening on ${address.url}`);
+    if (!configuredToken)
+        console.log(`One-time bearer token: ${token}`);
+    console.log("Prompts and transcripts stay on this bridge and the selected provider; Cozibud never receives provider credentials.");
+    let stopping = false;
+    const stop = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        await service.close();
+    };
+    process.once("SIGINT", () => void stop());
+    process.once("SIGTERM", () => void stop());
+}
+const args = process.argv.slice(2);
+const command = args[0] ?? "serve";
+try {
+    if (args.includes("--help") || args.includes("-h"))
+        printHelp();
+    else if (command === "setup") {
+        const provider = value(args, "--provider", "codex");
+        if (!["codex", "claude", "gemini", "cursor"].includes(provider))
+            throw new Error(`Unknown setup provider: ${provider}. Choose codex, claude, gemini, or cursor.`);
+        await setupProvider({ provider: provider, mcpUrl: value(args, "--mcp-url", DEFAULT_COZIBUD_MCP_URL) });
+    }
+    else if (command === "ask")
+        await ask(args);
+    else if (command === "serve")
+        await serve(args);
+    else
+        throw new Error(`Unknown command: ${command}. Run cozibud-harness --help.`);
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : "The local harness failed.");
+    process.exitCode = 1;
+}

package/dist/contracts.d.ts

@@ -0,0 +1,79 @@
+export declare const HARNESS_IDS: readonly ["codex", "claude", "gemini", "cursor"];
+export type BuiltInHarnessId = (typeof HARNESS_IDS)[number];
+export type HarnessInputSource = "typed" | "voice-transcript" | "quick-action";
+export type HarnessClient = "web" | "phone" | "watch";
+export interface HarnessTurnInput {
+    prompt: string;
+    source: HarnessInputSource;
+    client: HarnessClient;
+    locale?: string;
+}
+export interface HarnessTurnRequest extends HarnessTurnInput {
+    harness: string;
+}
+export type HarnessAvailability = {
+    state: "available";
+    version?: string;
+} | {
+    state: "unavailable";
+    reason: "missing-cli" | "probe-failed";
+    message: string;
+};
+export interface HarnessDescriptor {
+    id: string;
+    label: string;
+    command: string;
+    authentication: "existing-login" | "api-key";
+    availability: HarnessAvailability;
+}
+export type HarnessEvent = {
+    sequence: number;
+    turnId: string;
+    harness: string;
+    createdAt: string;
+} & ({
+    type: "turn.started";
+    source: HarnessInputSource;
+    client: HarnessClient;
+} | {
+    type: "assistant.delta";
+    text: string;
+} | {
+    type: "assistant.completed";
+    text: string;
+} | {
+    type: "turn.completed";
+} | {
+    type: "turn.failed";
+    code: "unavailable" | "cancelled" | "timeout" | "upstream-error";
+    message: string;
+});
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type HarnessEventPayload = DistributiveOmit<HarnessEvent, "sequence" | "turnId" | "harness" | "createdAt">;
+export interface HarnessRunContext {
+    turnId: string;
+    signal: AbortSignal;
+    emit: (event: HarnessEventPayload) => void;
+}
+export interface HarnessDriver {
+    readonly id: string;
+    readonly label: string;
+    readonly command: string;
+    readonly authentication: "existing-login" | "api-key";
+    probe(): Promise<HarnessAvailability>;
+    run(input: HarnessTurnInput, context: HarnessRunContext): Promise<{
+        text: string;
+    }>;
+}
+export interface TurnSnapshot {
+    id: string;
+    harness: string;
+    state: "running" | "completed" | "failed" | "cancelled";
+    source: HarnessInputSource;
+    client: HarnessClient;
+    createdAt: string;
+    updatedAt: string;
+    response?: string;
+    events: HarnessEvent[];
+}
+export {};

package/dist/contracts.js

@@ -0,0 +1 @@
+export const HARNESS_IDS = ["codex", "claude", "gemini", "cursor"];

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./contracts.js";
+export * from "./process-driver.js";
+export * from "./runtime.js";
+export * from "./server.js";
+export * from "./setup.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./contracts.js";
+export * from "./process-driver.js";
+export * from "./runtime.js";
+export * from "./server.js";
+export * from "./setup.js";

package/dist/process-driver.d.ts

@@ -0,0 +1,39 @@
+import type { HarnessDriver } from "./contracts.js";
+declare const TEMP_DIRECTORY_CLEANUP_OPTIONS: {
+    readonly recursive: true;
+    readonly force: true;
+    readonly maxRetries: 5;
+    readonly retryDelay: 100;
+};
+type RemoveDirectory = (path: string, options: typeof TEMP_DIRECTORY_CLEANUP_OPTIONS) => Promise<void>;
+export interface ProcessHarnessDefinition {
+    id: string;
+    label: string;
+    command: string;
+    versionArgs?: string[];
+    /** Applied only to a fresh empty directory created by this driver. */
+    emptyDirectoryArgs?: string[];
+    args(): string[];
+}
+declare function messageText(value: unknown): string | null;
+declare function appendNovelText(current: string, candidate: string): {
+    value: string;
+    delta: string;
+};
+export declare function createProcessHarnessDriver(definition: ProcessHarnessDefinition, options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    removeDirectory?: RemoveDirectory;
+}): HarnessDriver;
+export declare function executable(configured: string): {
+    command: string;
+    prefixArgs: string[];
+};
+export declare const builtInProcessHarnesses: ProcessHarnessDefinition[];
+export declare function createBuiltInDrivers(): HarnessDriver[];
+export declare const processOutput: {
+    messageText: typeof messageText;
+    appendNovelText: typeof appendNovelText;
+};
+export {};

package/dist/process-driver.js

@@ -0,0 +1,316 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+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 };
+function stopProcess(child) {
+    if (!child.pid || child.exitCode !== null)
+        return;
+    if (process.platform === "win32") {
+        const killer = spawn(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe"), ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+        killer.on("error", () => child.kill());
+    }
+    else {
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch {
+            child.kill("SIGKILL");
+        }
+    }
+}
+function carePrompt(input) {
+    const origin = `${input.client} ${input.source}`;
+    return [
+        "You are handling a Cozibud family-care request.",
+        "Use the already configured Cozibud MCP server for any household read or write.",
+        "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 origin: ${origin}. Locale: ${input.locale ?? "unspecified"}.`,
+        "<caregiver_request>",
+        input.prompt,
+        "</caregiver_request>",
+    ].join("\n");
+}
+function messageText(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const event = value;
+    if (event.is_error === true || event.type === "error" || event.error)
+        return null;
+    if (event.type === "result" && typeof event.result === "string")
+        return event.result;
+    if (event.type === "assistant" && event.message && typeof event.message === "object") {
+        const content = event.message.content;
+        if (Array.isArray(content)) {
+            const text = content
+                .filter((block) => Boolean(block) && typeof block === "object")
+                .filter((block) => block.type === "text" && typeof block.text === "string")
+                .map((block) => block.text)
+                .join("");
+            if (text)
+                return text;
+        }
+    }
+    if (event.type === "item.completed" && event.item && typeof event.item === "object") {
+        const item = event.item;
+        if ((item.type === "agent_message" || item.type === "assistant_message") && typeof item.text === "string")
+            return item.text;
+    }
+    if ((event.type === "assistant" || event.type === "assistant_message") && typeof event.text === "string")
+        return event.text;
+    if (event.type === "message" && event.role === "assistant" && typeof event.content === "string")
+        return event.content;
+    return null;
+}
+function appendNovelText(current, candidate) {
+    if (!candidate || candidate === current || current.endsWith(candidate))
+        return { value: current, delta: "" };
+    if (candidate.startsWith(current))
+        return { value: candidate, delta: candidate.slice(current.length) };
+    return { value: current + candidate, delta: candidate };
+}
+export function createProcessHarnessDriver(definition, options = {}) {
+    const spawnOptions = {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        windowsHide: true,
+        detached: process.platform !== "win32",
+    };
+    return {
+        id: definition.id,
+        label: definition.label,
+        command: definition.command,
+        authentication: "existing-login",
+        async probe() {
+            return await new Promise((resolve) => {
+                const child = spawn(definition.command, definition.versionArgs ?? ["--version"], { ...spawnOptions, stdio: ["ignore", "pipe", "pipe"] });
+                let output = "";
+                let bytes = 0;
+                let overflow = false;
+                const timer = setTimeout(() => stopProcess(child), 5_000);
+                const collect = (chunk, stdout) => {
+                    bytes += chunk.length;
+                    if (bytes > MAX_OUTPUT_BYTES) {
+                        if (!overflow)
+                            stopProcess(child);
+                        overflow = true;
+                        return;
+                    }
+                    if (stdout)
+                        output += chunk.toString("utf8");
+                };
+                child.stdout.on("data", (chunk) => collect(chunk, true));
+                child.stderr.on("data", (chunk) => collect(chunk, false));
+                child.once("error", (error) => {
+                    clearTimeout(timer);
+                    resolve(error.code === "ENOENT"
+                        ? { state: "unavailable", reason: "missing-cli", message: `${definition.command} is not installed or is not on PATH.` }
+                        : { state: "unavailable", reason: "probe-failed", message: `${definition.label} could not be checked.` });
+                });
+                child.once("close", (code) => {
+                    clearTimeout(timer);
+                    resolve(code === 0 && !overflow
+                        ? { state: "available", version: output.trim().split(/\r?\n/, 1)[0] || undefined }
+                        : { state: "unavailable", reason: "probe-failed", message: `${definition.label} returned exit code ${code ?? "unknown"}.` });
+                });
+            });
+        },
+        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;
+            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")
+                                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 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);
+                        }
+                    });
+                    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.`);
+                    }
+                }
+            }
+        },
+    };
+}
+export function executable(configured) {
+    if (process.platform === "win32" && !/\.(?:exe|[cm]?js)$/i.test(configured)) {
+        const directories = isAbsolute(configured) ? [""] : (process.env.PATH ?? process.env.Path ?? "").split(delimiter);
+        // Preserve native executable discovery before falling back to script shims.
+        for (const directory of directories) {
+            const base = directory ? join(directory, configured) : configured;
+            if (existsSync(`${base}.exe`))
+                return { command: `${base}.exe`, prefixArgs: [] };
+        }
+        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],
+                };
+        }
+    }
+    return /\.(?:c|m)?js$/i.test(configured)
+        ? { command: process.execPath, prefixArgs: [configured] }
+        : { command: configured, prefixArgs: [] };
+}
+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");
+const cursorExecutable = executable(process.env.COZIBUD_CURSOR_PATH || "cursor-agent");
+export const builtInProcessHarnesses = [
+    {
+        id: "codex",
+        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", "-"],
+    },
+    {
+        id: "claude",
+        label: "Claude Code",
+        command: claudeExecutable.command,
+        versionArgs: [...claudeExecutable.prefixArgs, "--version"],
+        args: () => [...claudeExecutable.prefixArgs, "-p", "--output-format", "stream-json", "--verbose", "--allowedTools", "mcp__cozibud__list_children"],
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        command: geminiExecutable.command,
+        emptyDirectoryArgs: ["--skip-trust"],
+        versionArgs: [...geminiExecutable.prefixArgs, "--version"],
+        args: () => [...geminiExecutable.prefixArgs, "--output-format", "stream-json"],
+    },
+    {
+        id: "cursor",
+        label: "Cursor Agent",
+        command: cursorExecutable.command,
+        emptyDirectoryArgs: ["--trust"],
+        versionArgs: [...cursorExecutable.prefixArgs, "--version"],
+        args: () => [...cursorExecutable.prefixArgs, "-p", "--output-format", "stream-json"],
+    },
+];
+export function createBuiltInDrivers() {
+    return builtInProcessHarnesses.map((definition) => createProcessHarnessDriver(definition));
+}
+export const processOutput = { messageText, appendNovelText };

package/dist/runtime.d.ts

@@ -0,0 +1,17 @@
+import type { HarnessDriver, HarnessEvent, HarnessTurnRequest, TurnSnapshot } from "./contracts.js";
+type Listener = (event: HarnessEvent) => void;
+export declare class HarnessRuntime {
+    private readonly maxTurns;
+    private readonly maxActiveTurns;
+    private readonly drivers;
+    private readonly turns;
+    constructor(drivers: HarnessDriver[], maxTurns?: number, maxActiveTurns?: number);
+    listDrivers(): HarnessDriver[];
+    getTurn(id: string): TurnSnapshot | null;
+    subscribe(id: string, listener: Listener): (() => void) | null;
+    start(request: HarnessTurnRequest): TurnSnapshot;
+    cancel(id: string): boolean;
+    private emit;
+    private execute;
+}
+export {};

package/dist/runtime.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+export class HarnessRuntime {
+    maxTurns;
+    maxActiveTurns;
+    drivers = new Map();
+    turns = new Map();
+    constructor(drivers, maxTurns = 100, maxActiveTurns = 2) {
+        this.maxTurns = maxTurns;
+        this.maxActiveTurns = maxActiveTurns;
+        for (const driver of drivers) {
+            if (this.drivers.has(driver.id))
+                throw new Error(`Duplicate harness driver: ${driver.id}`);
+            this.drivers.set(driver.id, driver);
+        }
+    }
+    listDrivers() { return [...this.drivers.values()]; }
+    getTurn(id) {
+        const turn = this.turns.get(id);
+        if (!turn)
+            return null;
+        const { controller: _controller, listeners: _listeners, ...snapshot } = turn;
+        return structuredClone(snapshot);
+    }
+    subscribe(id, listener) {
+        const turn = this.turns.get(id);
+        if (!turn)
+            return null;
+        turn.listeners.add(listener);
+        return () => turn.listeners.delete(listener);
+    }
+    start(request) {
+        const driver = this.drivers.get(request.harness);
+        if (!driver)
+            throw new Error(`Unknown harness: ${request.harness}`);
+        const active = [...this.turns.values()].filter((turn) => turn.state === "running").length;
+        if (active >= this.maxActiveTurns)
+            throw new Error("The local harness is busy. Wait for a turn to finish.");
+        while (this.turns.size >= this.maxTurns) {
+            let removed = false;
+            for (const [id, turn] of this.turns) {
+                if (turn.state === "running")
+                    continue;
+                this.turns.delete(id);
+                removed = true;
+                break;
+            }
+            if (!removed)
+                throw new Error("The local harness is at capacity. Wait for a turn to finish.");
+        }
+        const now = new Date().toISOString();
+        const turn = {
+            id: randomUUID(), harness: driver.id, state: "running", source: request.source, client: request.client,
+            createdAt: now, updatedAt: now, events: [], controller: new AbortController(), listeners: new Set(),
+        };
+        this.turns.set(turn.id, turn);
+        this.emit(turn, { type: "turn.started", source: request.source, client: request.client });
+        void this.execute(turn, driver, request);
+        return this.getTurn(turn.id);
+    }
+    cancel(id) {
+        const turn = this.turns.get(id);
+        if (!turn || turn.state !== "running")
+            return false;
+        turn.state = "cancelled";
+        turn.controller.abort();
+        this.emit(turn, { type: "turn.failed", code: "cancelled", message: "The turn was cancelled." });
+        return true;
+    }
+    emit(turn, event) {
+        const full = { ...event, sequence: turn.events.length + 1, turnId: turn.id, harness: turn.harness, createdAt: new Date().toISOString() };
+        turn.events.push(full);
+        turn.updatedAt = full.createdAt;
+        for (const listener of turn.listeners)
+            listener(full);
+    }
+    async execute(turn, driver, request) {
+        try {
+            const availability = await driver.probe();
+            if (turn.state !== "running")
+                return;
+            if (availability.state === "unavailable") {
+                turn.state = "failed";
+                this.emit(turn, { type: "turn.failed", code: "unavailable", message: availability.message });
+                return;
+            }
+            const result = await driver.run(request, {
+                turnId: turn.id,
+                signal: turn.controller.signal,
+                emit: (event) => { if (turn.state === "running")
+                    this.emit(turn, event); },
+            });
+            if (turn.state !== "running")
+                return;
+            turn.response = result.text;
+            this.emit(turn, { type: "assistant.completed", text: result.text });
+            turn.state = "completed";
+            this.emit(turn, { type: "turn.completed" });
+        }
+        catch (error) {
+            if (turn.state !== "running")
+                return;
+            const message = error instanceof Error ? error.message : "The harness failed.";
+            turn.state = "failed";
+            this.emit(turn, {
+                type: "turn.failed",
+                code: /timed out/i.test(message) ? "timeout" : "upstream-error",
+                message,
+            });
+        }
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { HarnessRuntime } from "./runtime.js";
+export interface HarnessServerOptions {
+    runtime: HarnessRuntime;
+    token: string;
+    host?: string;
+    port?: number;
+    allowedOrigins?: string[];
+}
+export declare function createHarnessHttpServer(options: HarnessServerOptions): {
+    server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    listen(): Promise<{
+        host: string;
+        port: number;
+        url: string;
+    }>;
+    close(): Promise<void>;
+};

package/dist/server.js

@@ -0,0 +1,140 @@
+import { timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+const MAX_BODY_BYTES = 16 * 1024;
+const ID_PATTERN = /^[0-9a-f-]{36}$/i;
+function json(response, status, body) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    response.end(JSON.stringify(body));
+}
+function validTurnRequest(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const row = value;
+    return typeof row.harness === "string" && row.harness.length <= 64
+        && typeof row.prompt === "string" && row.prompt.trim().length > 0 && row.prompt.length <= 8_000
+        && ["typed", "voice-transcript", "quick-action"].includes(String(row.source))
+        && ["web", "phone", "watch"].includes(String(row.client))
+        && (row.locale === undefined || (typeof row.locale === "string" && row.locale.length <= 35));
+}
+async function body(request) {
+    let raw = "";
+    for await (const chunk of request) {
+        raw += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+        if (Buffer.byteLength(raw) > MAX_BODY_BYTES)
+            throw new Error("too-large");
+    }
+    return JSON.parse(raw);
+}
+function sse(response, event) {
+    response.write(`id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+}
+function authorized(header, token) {
+    const expected = Buffer.from(`Bearer ${token}`);
+    const actual = Buffer.from(header ?? "");
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+export function createHarnessHttpServer(options) {
+    if (options.token.length < 32)
+        throw new Error("The local harness token must contain at least 32 characters.");
+    const allowedOrigins = new Set(options.allowedOrigins ?? []);
+    const runtime = options.runtime;
+    const server = createServer(async (request, response) => {
+        response.setHeader("x-content-type-options", "nosniff");
+        response.setHeader("referrer-policy", "no-referrer");
+        const origin = request.headers.origin;
+        if (origin && allowedOrigins.has(origin)) {
+            response.setHeader("access-control-allow-origin", origin);
+            response.setHeader("vary", "Origin");
+            response.setHeader("access-control-allow-headers", "authorization, content-type");
+            response.setHeader("access-control-allow-methods", "GET, POST, DELETE, OPTIONS");
+        }
+        if (request.method === "OPTIONS") {
+            if (!origin || !allowedOrigins.has(origin))
+                return json(response, 403, { error: "Origin is not allowed." });
+            response.writeHead(204);
+            response.end();
+            return;
+        }
+        if (request.url === "/health" && request.method === "GET")
+            return json(response, 200, { status: "ok" });
+        if (!authorized(request.headers.authorization, options.token)) {
+            response.setHeader("www-authenticate", 'Bearer realm="cozibud-local-harness"');
+            return json(response, 401, { error: "A valid local harness token is required." });
+        }
+        const url = new URL(request.url ?? "/", "http://localhost");
+        if (url.pathname === "/v1/harnesses" && request.method === "GET") {
+            const harnesses = await Promise.all(runtime.listDrivers().map(async (driver) => ({
+                id: driver.id, label: driver.label, command: driver.command, authentication: driver.authentication,
+                availability: await driver.probe(),
+            })));
+            return json(response, 200, { harnesses });
+        }
+        if (url.pathname === "/v1/turns" && request.method === "POST") {
+            try {
+                const parsed = await body(request);
+                if (!validTurnRequest(parsed))
+                    return json(response, 400, { error: "Provide a harness, prompt, input source, and client." });
+                const turn = runtime.start(parsed);
+                response.setHeader("location", `/v1/turns/${turn.id}`);
+                return json(response, 202, { turn });
+            }
+            catch (error) {
+                if (error instanceof SyntaxError)
+                    return json(response, 400, { error: "Request body must be valid JSON." });
+                if (error instanceof Error && error.message === "too-large")
+                    return json(response, 413, { error: "Request body is too large." });
+                return json(response, 409, { error: error instanceof Error ? error.message : "The turn could not be started." });
+            }
+        }
+        const match = url.pathname.match(/^\/v1\/turns\/([^/]+)(\/events)?$/);
+        if (match && ID_PATTERN.test(match[1] ?? "")) {
+            const id = match[1];
+            if (!match[2] && request.method === "GET") {
+                const turn = runtime.getTurn(id);
+                return turn ? json(response, 200, { turn }) : json(response, 404, { error: "Turn not found." });
+            }
+            if (!match[2] && request.method === "DELETE") {
+                return runtime.cancel(id) ? json(response, 200, { cancelled: true }) : json(response, 409, { error: "Turn is not running." });
+            }
+            if (match[2] && request.method === "GET") {
+                const turn = runtime.getTurn(id);
+                if (!turn)
+                    return json(response, 404, { error: "Turn not found." });
+                response.writeHead(200, {
+                    "content-type": "text/event-stream; charset=utf-8",
+                    "cache-control": "no-store",
+                    connection: "keep-alive",
+                });
+                for (const event of turn.events)
+                    sse(response, event);
+                if (turn.state !== "running")
+                    return response.end();
+                const unsubscribe = runtime.subscribe(id, (event) => {
+                    sse(response, event);
+                    if (event.type === "turn.completed" || event.type === "turn.failed") {
+                        unsubscribe?.();
+                        response.end();
+                    }
+                });
+                request.once("close", () => unsubscribe?.());
+                return;
+            }
+        }
+        return json(response, 404, { error: "Not found." });
+    });
+    return {
+        server,
+        async listen() {
+            const host = options.host ?? "127.0.0.1";
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(options.port ?? 0, host, () => { server.off("error", reject); resolve(); });
+            });
+            const address = server.address();
+            return { host, port: address.port, url: `http://${host}:${address.port}` };
+        },
+        async close() {
+            await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+        },
+    };
+}

package/dist/setup.d.ts

@@ -0,0 +1,32 @@
+export declare const DEFAULT_COZIBUD_MCP_URL = "https://cozibud.com/api/mcp";
+export type SetupProviderId = "codex" | "claude" | "gemini" | "cursor";
+export type SetupCommandResult = {
+    status: "completed" | "missing" | "failed";
+    exitCode: number | null;
+    output: string;
+};
+export type SetupCommandRunner = (command: string, args: string[], options: {
+    interactive: boolean;
+}) => Promise<SetupCommandResult>;
+export type SetupWriter = (message: string) => void;
+export declare const runSetupCommand: SetupCommandRunner;
+export interface CursorMcpConfigStore {
+    read(): Promise<string | null>;
+    write(contents: string): Promise<void>;
+}
+export declare function mergeCursorMcpConfig(contents: string | null, mcpUrl: string): string;
+export declare function validateMcpUrl(input: string): string;
+export declare function setupProvider(options?: {
+    provider?: SetupProviderId;
+    command?: string;
+    mcpUrl?: string;
+    run?: SetupCommandRunner;
+    write?: SetupWriter;
+    cursorConfig?: CursorMcpConfigStore;
+}): Promise<void>;
+export declare function setupCodex(options?: {
+    command?: string;
+    mcpUrl?: string;
+    run?: SetupCommandRunner;
+    write?: SetupWriter;
+}): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,286 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { executable } from "./process-driver.js";
+export const DEFAULT_COZIBUD_MCP_URL = "https://cozibud.com/api/mcp";
+const MAX_SETUP_OUTPUT_BYTES = 64 * 1024;
+export const runSetupCommand = async (command, args, options) => await new Promise((resolve) => {
+    const resolved = executable(command);
+    const child = spawn(resolved.command, [...resolved.prefixArgs, ...args], {
+        windowsHide: true,
+        stdio: options.interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    let settled = false;
+    const append = (chunk) => {
+        const remaining = MAX_SETUP_OUTPUT_BYTES - Buffer.byteLength(output);
+        if (remaining > 0)
+            output += chunk.toString("utf8").slice(0, remaining);
+    };
+    if (!options.interactive) {
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+    }
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve({ ...result, output });
+    };
+    child.once("error", (error) => finish({
+        status: error.code === "ENOENT" ? "missing" : "failed",
+        exitCode: null,
+    }));
+    child.once("close", (code) => finish({ status: "completed", exitCode: code }));
+});
+function succeeded(result) {
+    return result.status === "completed" && result.exitCode === 0;
+}
+function requireSuccess(result, missingMessage, failureMessage) {
+    if (result.status === "missing")
+        throw new Error(missingMessage);
+    if (!succeeded(result))
+        throw new Error(failureMessage);
+}
+function configuredUrl(output, requireNamedLine = false) {
+    const namedLine = output.split(/\r?\n/).find((line) => /\bcozibud\b/i.test(line) && /https?:\/\//i.test(line));
+    const namedUrl = namedLine?.match(/https?:\/\/[^\s)]+/i)?.[0];
+    if (namedUrl || requireNamedLine)
+        return namedUrl ?? null;
+    return output.match(/^\s*url:\s*(\S+)\s*$/im)?.[1] ?? null;
+}
+function reportsConnected(provider, output, expectedUrl) {
+    if (provider === "claude")
+        return /^\s*Status:\s*(?:[✓✔√]\s*)?Connected\s*$/im.test(output);
+    const namedLine = output.split(/\r?\n/).find((line) => /^\s*[^\w\s]?\s*cozibud\s*:/i.test(line));
+    const namedUrl = namedLine?.match(/https?:\/\/[^\s)]+/i)?.[0];
+    return namedUrl === expectedUrl && /-\s*Connected\s*$/i.test(namedLine ?? "");
+}
+function cursorReportsConnected(output) {
+    return output.split(/\r?\n/).some((line) => /^\s*cozibud\s*:\s*(?:ready|connected)\s*$/i.test(line));
+}
+function commandFor(configuredCommand) {
+    return /\.(?:c|m)?js$/i.test(configuredCommand)
+        ? { command: process.execPath, prefixArgs: [configuredCommand] }
+        : { command: configuredCommand, prefixArgs: [] };
+}
+function providerCommand(provider, override) {
+    const configured = override ?? ({
+        codex: process.env.COZIBUD_CODEX_PATH,
+        claude: process.env.COZIBUD_CLAUDE_PATH,
+        gemini: process.env.COZIBUD_GEMINI_PATH,
+        cursor: process.env.COZIBUD_CURSOR_PATH,
+    }[provider]) ?? (provider === "cursor" ? "cursor-agent" : provider);
+    return commandFor(configured);
+}
+function providerLabel(provider) {
+    return { codex: "Codex CLI", claude: "Claude Code", gemini: "Gemini CLI", cursor: "Cursor Agent" }[provider];
+}
+function installUrl(provider) {
+    return {
+        codex: "https://developers.openai.com/codex/cli",
+        claude: "https://docs.anthropic.com/en/docs/claude-code/getting-started",
+        gemini: "https://google-gemini.github.io/gemini-cli/",
+        cursor: "https://docs.cursor.com/en/cli/installation",
+    }[provider];
+}
+function cursorConfigStore() {
+    const path = process.env.COZIBUD_CURSOR_MCP_CONFIG?.trim() || join(homedir(), ".cursor", "mcp.json");
+    return {
+        async read() {
+            try {
+                return await readFile(path, "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            }
+        },
+        async write(contents) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, contents, { encoding: "utf8", mode: 0o600 });
+        },
+    };
+}
+function parsedCursorConfig(contents) {
+    if (!contents?.trim())
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new Error("Cursor MCP configuration is not valid JSON; fix it before running setup again.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Cursor MCP configuration must contain a JSON object.");
+    }
+    return parsed;
+}
+export function mergeCursorMcpConfig(contents, mcpUrl) {
+    const root = parsedCursorConfig(contents);
+    const currentServers = root.mcpServers;
+    if (currentServers !== undefined && (!currentServers || typeof currentServers !== "object" || Array.isArray(currentServers))) {
+        throw new Error("Cursor MCP configuration has an invalid mcpServers value.");
+    }
+    return `${JSON.stringify({
+        ...root,
+        mcpServers: {
+            ...currentServers,
+            cozibud: { url: mcpUrl },
+        },
+    }, null, 2)}\n`;
+}
+function cursorConfiguredUrl(contents) {
+    const servers = parsedCursorConfig(contents).mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return null;
+    const cozibud = servers.cozibud;
+    if (!cozibud || typeof cozibud !== "object" || Array.isArray(cozibud))
+        return null;
+    const url = cozibud.url;
+    return typeof url === "string" ? url : null;
+}
+export function validateMcpUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error("--mcp-url must be a valid HTTPS URL.");
+    }
+    const loopback = ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+    if (url.protocol !== "https:" && !(loopback && url.protocol === "http:")) {
+        throw new Error("--mcp-url must use HTTPS (HTTP is allowed only for loopback development).");
+    }
+    if (url.username || url.password || url.hash)
+        throw new Error("--mcp-url must not contain credentials or a fragment.");
+    return url.href;
+}
+async function setupCodexProvider(options) {
+    const executable = providerCommand("codex", options.command);
+    const args = (...values) => [...executable.prefixArgs, ...values];
+    const missing = `Codex CLI is not installed or is not on PATH. Install it from ${installUrl("codex")} and run setup again.`;
+    options.write("Checking Codex CLI…");
+    requireSuccess(await options.run(executable.command, args("--version"), { interactive: false }), missing, "Codex CLI was found but could not be started.");
+    const login = await options.run(executable.command, args("login", "status"), { interactive: false });
+    if (!succeeded(login)) {
+        options.write("Opening Codex sign-in in your browser…");
+        requireSuccess(await options.run(executable.command, args("login"), { interactive: true }), missing, "Codex sign-in did not complete. Run setup again when you are ready to sign in.");
+    }
+    else
+        options.write("Codex sign-in is ready.");
+    requireSuccess(await options.run(executable.command, args("login", "status"), { interactive: false }), missing, "Codex still reports that you are signed out.");
+    const existingMcp = await options.run(executable.command, args("mcp", "get", "cozibud"), { interactive: false });
+    const existingUrl = succeeded(existingMcp) ? configuredUrl(existingMcp.output) : null;
+    if (succeeded(existingMcp) && existingUrl !== options.mcpUrl) {
+        options.write("Replacing the existing cozibud connection because it points at a different endpoint…");
+        requireSuccess(await options.run(executable.command, args("mcp", "remove", "cozibud"), { interactive: true }), missing, "Codex could not remove the existing cozibud MCP connection.");
+    }
+    if (existingUrl !== options.mcpUrl) {
+        options.write(`Adding the Cozibud connection at ${options.mcpUrl}…`);
+        requireSuccess(await options.run(executable.command, args("mcp", "add", "cozibud", "--url", options.mcpUrl), { interactive: true }), missing, "Codex could not add the Cozibud MCP connection.");
+    }
+    else
+        options.write("The Cozibud connection is configured with the expected endpoint.");
+    options.write("Opening Cozibud sign-in and permission approval in your browser…");
+    requireSuccess(await options.run(executable.command, args("mcp", "login", "cozibud"), { interactive: true }), missing, "Cozibud sign-in or permission approval did not complete.");
+    const verified = await options.run(executable.command, args("mcp", "get", "cozibud"), { interactive: false });
+    requireSuccess(verified, missing, "Codex could not verify the Cozibud MCP connection after sign-in.");
+    if (configuredUrl(verified.output) !== options.mcpUrl)
+        throw new Error("The verified cozibud connection does not use the expected endpoint.");
+    options.write("Ready. Codex is signed in and connected to Cozibud.");
+}
+async function setupInteractiveProvider(provider, options) {
+    const executable = providerCommand(provider, options.command);
+    const args = (...values) => [...executable.prefixArgs, ...values];
+    const label = providerLabel(provider);
+    const missing = `${label} is not installed or is not on PATH. Install it from ${installUrl(provider)} and run setup again.`;
+    options.write(`Checking ${label}…`);
+    requireSuccess(await options.run(executable.command, args("--version"), { interactive: false }), missing, `${label} was found but could not be started.`);
+    if (provider === "claude") {
+        const login = await options.run(executable.command, args("auth", "status"), { interactive: false });
+        if (!succeeded(login)) {
+            options.write("Opening Claude sign-in in your browser…");
+            requireSuccess(await options.run(executable.command, args("auth", "login"), { interactive: true }), missing, "Claude sign-in did not complete.");
+        }
+        else
+            options.write("Claude sign-in is ready.");
+        requireSuccess(await options.run(executable.command, args("auth", "status"), { interactive: false }), missing, "Claude still reports that you are signed out.");
+    }
+    const inspectArgs = provider === "claude" ? args("mcp", "get", "cozibud") : args("mcp", "list");
+    const existing = await options.run(executable.command, inspectArgs, { interactive: false });
+    const existingUrl = succeeded(existing) ? configuredUrl(existing.output, provider === "gemini") : null;
+    if (succeeded(existing) && existingUrl && existingUrl !== options.mcpUrl) {
+        options.write("Replacing the existing cozibud connection because it points at a different endpoint…");
+        const removeArgs = provider === "claude"
+            ? args("mcp", "remove", "cozibud", "--scope", "user")
+            : args("mcp", "remove", "cozibud");
+        requireSuccess(await options.run(executable.command, removeArgs, { interactive: true }), missing, `${label} could not remove the existing cozibud MCP connection.`);
+    }
+    if (existingUrl !== options.mcpUrl) {
+        options.write(`Adding the Cozibud connection at ${options.mcpUrl}…`);
+        requireSuccess(await options.run(executable.command, args("mcp", "add", "--scope", "user", "--transport", "http", "cozibud", options.mcpUrl), { interactive: true }), missing, `${label} could not add the Cozibud MCP connection.`);
+    }
+    else
+        options.write("The Cozibud connection is configured with the expected endpoint.");
+    const authInstruction = provider === "claude" ? "Choose cozibud from /mcp" : "Run /mcp auth cozibud";
+    options.write(`${authInstruction}, complete Cozibud browser approval, then exit the provider to finish setup.`);
+    requireSuccess(await options.run(executable.command, args(), { interactive: true }), missing, `${label} closed before setup could finish.`);
+    const verified = await options.run(executable.command, inspectArgs, { interactive: false });
+    requireSuccess(verified, missing, `${label} could not verify the Cozibud MCP configuration.`);
+    if (configuredUrl(verified.output, provider === "gemini") !== options.mcpUrl)
+        throw new Error("The verified cozibud connection does not use the expected endpoint.");
+    if (!reportsConnected(provider, verified.output, options.mcpUrl)) {
+        throw new Error(`${label} did not report a connected Cozibud MCP session. Check any disabled or untrusted-client status, then run setup again and complete Cozibud browser approval before exiting the provider.`);
+    }
+    options.write(`Ready. ${label} is configured for Cozibud. The provider stores its own login and OAuth credentials.`);
+}
+async function setupCursorProvider(options) {
+    const executable = providerCommand("cursor", options.command);
+    const args = (...values) => [...executable.prefixArgs, ...values];
+    const missing = `Cursor Agent is not installed or is not on PATH. Install it from ${installUrl("cursor")} and run setup again.`;
+    options.write("Checking Cursor Agent…");
+    requireSuccess(await options.run(executable.command, args("--version"), { interactive: false }), missing, "Cursor Agent was found but could not be started.");
+    const login = await options.run(executable.command, args("status"), { interactive: false });
+    if (!succeeded(login)) {
+        options.write("Opening Cursor sign-in in your browser…");
+        requireSuccess(await options.run(executable.command, args("login"), { interactive: true }), missing, "Cursor sign-in did not complete.");
+    }
+    else
+        options.write("Cursor sign-in is ready.");
+    requireSuccess(await options.run(executable.command, args("status"), { interactive: false }), missing, "Cursor still reports that you are signed out.");
+    const currentConfig = await options.config.read();
+    if (cursorConfiguredUrl(currentConfig) !== options.mcpUrl) {
+        options.write("Adding the Cozibud connection to Cursor's user MCP configuration…");
+        await options.config.write(mergeCursorMcpConfig(currentConfig, options.mcpUrl));
+    }
+    else
+        options.write("The Cozibud connection is configured with the expected endpoint.");
+    options.write("Opening Cozibud sign-in and permission approval in your browser…");
+    requireSuccess(await options.run(executable.command, args("mcp", "login", "cozibud"), { interactive: true }), missing, "Cozibud sign-in or permission approval did not complete.");
+    const verified = await options.run(executable.command, args("mcp", "list"), { interactive: false });
+    requireSuccess(verified, missing, "Cursor could not verify the Cozibud MCP connection after sign-in.");
+    if (!cursorReportsConnected(verified.output))
+        throw new Error("Cursor did not report a ready Cozibud MCP connection after sign-in.");
+    if (cursorConfiguredUrl(await options.config.read()) !== options.mcpUrl)
+        throw new Error("Cursor's cozibud connection does not use the expected endpoint.");
+    options.write("Ready. Cursor is signed in and available to the local Cozibud bridge.");
+}
+export async function setupProvider(options = {}) {
+    const provider = options.provider ?? "codex";
+    const mcpUrl = validateMcpUrl(options.mcpUrl ?? DEFAULT_COZIBUD_MCP_URL);
+    const run = options.run ?? runSetupCommand;
+    const write = options.write ?? ((message) => console.log(message));
+    if (provider === "codex")
+        await setupCodexProvider({ command: options.command, mcpUrl, run, write });
+    else if (provider === "cursor")
+        await setupCursorProvider({ command: options.command, mcpUrl, run, write, config: options.cursorConfig ?? cursorConfigStore() });
+    else
+        await setupInteractiveProvider(provider, { command: options.command, mcpUrl, run, write });
+}
+export async function setupCodex(options = {}) {
+    await setupProvider({ ...options, provider: "codex" });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cozibud/harness",
+  "version": "0.1.0",
+  "description": "Cozibud local-client bridge and CLI.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rongduan-zhu/cozibud.git",
+    "directory": "packages/harness"
+  },
+  "homepage": "https://github.com/rongduan-zhu/cozibud/tree/main/packages/harness#readme",
+  "bugs": {
+    "url": "https://github.com/rongduan-zhu/cozibud/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "cozibud-harness": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --root ../.. packages/harness/src"
+  }
+}