@rryando/arcs 3.9.2 → 3.11.0

package/dist/web-server/claude-runner.js

@@ -0,0 +1,320 @@
+/**
+ * Headless `claude -p` run lifecycle (T001 of the session-panel async-runs plan).
+ *
+ * Owns everything between "the web route decided to run a job" and a finished
+ * run record: spawn, output capture with caps, timeout escalation, `--output-
+ * format json` parsing, exit mapping, per-write-target concurrency serialization
+ * and ARCS_HOOK_* env scrubbing. The module is argv-agnostic — the calling route
+ * supplies argv/cwd; this module never decides what the child does. The route's
+ * post-run write-back (transcript mirror + metadata.run finalization) plugs in
+ * as the per-job `onSettled` callback, invoked after the child fully exits.
+ *
+ * Injectable `spawnImpl` + `binary` keep tests free of real children; the
+ * default impl is plain node child_process `spawn` with `stdio:
+ * ["ignore","pipe","pipe"]`. Every child-side failure resolves to an outcome
+ * record — this module never throws on spawn/exit/timeout paths.
+ */
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
+const DEFAULT_KILL_GRACE_MS = 5_000;
+export const STDOUT_CAP = 1024 * 1024; // 1 MB
+export const STDERR_CAP = 4 * 1024; // 4 KB
+/** Keys never forwarded to the child env — the hook handshake must not leak. */
+const ENV_SCRUB_KEYS = ["ARCS_HOOK_TOKEN", "ARCS_HOOK_SLUG", "ARCS_HOOK_URL"];
+/** writeTargetKey → live child. Module-level: shared across all web routes. */
+const liveRuns = new Map();
+/**
+ * Atomically claims the slot for a write-target key. Returns a typed refusal
+ * when a live run already holds it. Synchronous and called immediately after
+ * spawn (no await in between), so two overlapping requests cannot both win.
+ */
+export function beginRun(writeTargetKey, child) {
+    if (liveRuns.has(writeTargetKey)) {
+        return {
+            ok: false,
+            reason: "ALREADY_RUNNING",
+            message: `a claude run for "${writeTargetKey}" is already in progress`,
+        };
+    }
+    const startedAt = Date.now();
+    liveRuns.set(writeTargetKey, { child, startedAt });
+    return { ok: true, startedAt };
+}
+/** Releases the slot for a write-target key (idempotent). */
+export function endRun(writeTargetKey) {
+    liveRuns.delete(writeTargetKey);
+}
+/** Read-only liveness probe for the same slot (routes / UI status). */
+export function isRunLive(writeTargetKey) {
+    return liveRuns.has(writeTargetKey);
+}
+// ---------------------------------------------------------------------------
+// runClaudeJob
+// ---------------------------------------------------------------------------
+export async function runClaudeJob(input, options = {}) {
+    const { argv, cwd, writeTargetKey } = input;
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const binary = options.binary ?? "claude";
+    const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    const env = input.env ?? process.env;
+    const timeoutMs = resolveTimeoutMs(input.timeoutMs, env);
+    const startedAt = Date.now();
+    const fail = (outcome, error) => ({
+        pid: null,
+        startedAt,
+        endedAt: Date.now(),
+        outcome,
+        error,
+    });
+    let child;
+    try {
+        child = spawnImpl(binary, argv, { cwd, env: scrubEnv(env), stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (err) {
+        // Some spawn failures surface synchronously (fake impls, odd platforms).
+        return writeBack(input, fail("error", spawnErrorMessage(err, binary)));
+    }
+    const begin = beginRun(writeTargetKey, child);
+    if (!begin.ok) {
+        // A live run holds the slot — drop the freshly spawned child immediately.
+        // Attach a no-op error listener first: the refused child has no other
+        // listeners, so a spawn failure surfacing on it would otherwise crash.
+        child.on("error", () => { });
+        safeKill(child, "SIGKILL");
+        return writeBack(input, fail("error", begin.message));
+    }
+    const record = { pid: child.pid ?? null, startedAt, outcome: "success" };
+    try {
+        const settled = await settleRun(child, { timeoutMs, killGraceMs, binary });
+        record.endedAt = settled.endedAt;
+        record.outcome = settled.outcome;
+        if (settled.error !== undefined)
+            record.error = settled.error;
+        if (settled.replyText !== undefined) {
+            record.replyText = settled.replyText;
+            record.replyChars = settled.replyText.length;
+        }
+    }
+    catch (err) {
+        // Never throw on child-side failures — every path resolves to a record.
+        record.outcome = "error";
+        record.error = `runner failed: ${String(err)}`;
+    }
+    finally {
+        endRun(writeTargetKey);
+    }
+    return writeBack(input, record);
+}
+/**
+ * Fires the route-registered write-back (onSettled) against the settled record.
+ * Runs after endRun so the concurrency slot frees before the write-back's store
+ * work begins. Every record-producing path funnels through here — including
+ * sync spawn failures and refused overlaps — so the route can mirror the
+ * runtime transcript and finalize metadata.run regardless of outcome. Callback
+ * errors are swallowed: the write-back is best-effort and never changes the
+ * returned record.
+ */
+async function writeBack(input, record) {
+    if (input.onSettled === undefined)
+        return record;
+    try {
+        await input.onSettled(record);
+    }
+    catch {
+        // Write-back failure is a swallowed no-op — the run itself already settled.
+    }
+    return record;
+}
+function settleRun(child, ctx) {
+    return new Promise((resolve) => {
+        const stdout = makeTailBuffer(STDOUT_CAP);
+        const stderr = makeTailBuffer(STDERR_CAP);
+        let settled = false;
+        let timedOut = false;
+        let termTimer = null;
+        let killTimer = null;
+        const clearTimers = () => {
+            if (termTimer)
+                clearTimeout(termTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            termTimer = null;
+            killTimer = null;
+        };
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            child.removeAllListeners();
+            child.stdout?.removeAllListeners();
+            child.stderr?.removeAllListeners();
+            resolve(result);
+        };
+        termTimer = setTimeout(() => {
+            timedOut = true;
+            safeKill(child, "SIGTERM");
+            killTimer = setTimeout(() => {
+                safeKill(child, "SIGKILL");
+            }, ctx.killGraceMs);
+        }, ctx.timeoutMs);
+        child.stdout?.on("data", (chunk) => stdout.push(String(chunk)));
+        child.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
+        child.on("error", (err) => {
+            settle({
+                endedAt: Date.now(),
+                outcome: "error",
+                error: spawnErrorMessage(err, ctx.binary),
+            });
+        });
+        // Resolve on `close` (after stdio drained) rather than `exit` so the caps
+        // see the complete output. `close` also fires after a failed spawn.
+        child.on("close", (code, signal) => {
+            settle(mapExit({
+                code,
+                signal: signal ?? null,
+                timedOut,
+                stdout,
+                stderr,
+                timeoutMs: ctx.timeoutMs,
+            }));
+        });
+    });
+}
+function mapExit(input) {
+    const endedAt = Date.now();
+    if (input.timedOut) {
+        return {
+            endedAt,
+            outcome: "timeout",
+            error: `claude run timed out after ${input.timeoutMs}ms (SIGTERM, then SIGKILL)`,
+        };
+    }
+    if (input.code === 0) {
+        const parsed = parseClaudeJson(input.stdout.text());
+        if (parsed) {
+            if (parsed.is_error) {
+                return {
+                    endedAt,
+                    outcome: "error",
+                    error: parsed.result?.trim() || "claude reported an error (is_error)",
+                };
+            }
+            // `result` is optional — fall back to the trimmed raw stdout when absent.
+            const replyText = typeof parsed.result === "string" ? parsed.result : input.stdout.text().trim();
+            return { endedAt, outcome: "success", replyText };
+        }
+        // Unparsable stdout on exit 0 — treat the trimmed raw stdout as the reply.
+        return { endedAt, outcome: "success", replyText: input.stdout.text().trim() };
+    }
+    if (input.signal) {
+        return {
+            endedAt,
+            outcome: "error",
+            error: `claude run was terminated by signal ${input.signal}`,
+        };
+    }
+    const stderrTail = input.stderr.text().trim();
+    return {
+        endedAt,
+        outcome: "error",
+        error: stderrTail || `claude exited with status ${input.code}`,
+    };
+}
+/**
+ * Parses `claude --output-format json` stdout. Returns null when the output is
+ * not a JSON object carrying the is_error/result envelope, so the caller can
+ * fall back to raw stdout. Never throws.
+ */
+function parseClaudeJson(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const candidate = value;
+    if (typeof candidate.is_error !== "boolean" && typeof candidate.result !== "string") {
+        return null;
+    }
+    return candidate;
+}
+function resolveTimeoutMs(timeoutMs, env) {
+    if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        return timeoutMs;
+    }
+    const raw = env.ARCS_CLAUDE_RUN_TIMEOUT_MS;
+    if (raw) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isInteger(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_TIMEOUT_MS;
+}
+/** process.env minus the ARCS_HOOK_* handshake keys (the explicit 3-key
+ *  denylist above — not a prefix wildcard scrub). */
+function scrubEnv(env) {
+    const childEnv = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (ENV_SCRUB_KEYS.includes(key))
+            continue;
+        childEnv[key] = value;
+    }
+    return childEnv;
+}
+function spawnErrorMessage(err, binary) {
+    const code = err?.code;
+    if (code === "ENOENT")
+        return "claude not found on PATH";
+    return `failed to spawn ${binary}: ${String(err)}`;
+}
+function safeKill(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Child already exited — nothing to signal.
+    }
+}
+/**
+ * Accumulates output keeping only the most recent `limit` characters, dropping
+ * overflow from the head. Used so a runaway child cannot balloon memory while
+ * the important (tail) output survives.
+ *
+ * SHORTCUT: caps count UTF-16 code units, not bytes; upgrade to
+ * Buffer.byteLength accounting when non-ASCII payloads sit at the cap boundary.
+ */
+function makeTailBuffer(limit) {
+    const chunks = [];
+    let size = 0;
+    return {
+        push(chunk) {
+            if (chunk.length === 0)
+                return;
+            chunks.push(chunk);
+            size += chunk.length;
+            while (size > limit && chunks.length > 1) {
+                size -= chunks[0].length;
+                chunks.shift();
+            }
+            if (size > limit) {
+                // Single chunk larger than the cap — keep its tail.
+                const overflow = size - limit;
+                chunks[0] = chunks[0].slice(overflow);
+                size -= overflow;
+            }
+        },
+        text() {
+            return chunks.join("");
+        },
+    };
+}
+//# sourceMappingURL=claude-runner.js.map

package/dist/web-server/claude-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-runner.js","sourceRoot":"","sources":["../../src/web-server/claude-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAwC,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAsDjF,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AACpD,MAAM,qBAAqB,GAAG,KAAK,CAAC;AACpC,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO;AAC9C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO;AAE3C,gFAAgF;AAChF,MAAM,cAAc,GAAG,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,CAAC,CAAC;AAe9E,+EAA+E;AAC/E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,cAAsB,EAAE,KAAmB;IAClE,IAAI,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;QACjC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,iBAAiB;YACzB,OAAO,EAAE,qBAAqB,cAAc,0BAA0B;SACvE,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACnD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,MAAM,CAAC,cAAsB;IAC3C,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AAClC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,SAAS,CAAC,cAAsB;IAC9C,OAAO,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACtC,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAqB,EACrB,UAA+B,EAAE;IAEjC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC;IAC1C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,qBAAqB,CAAC;IACjE,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACrC,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,MAAM,IAAI,GAAG,CAAC,OAAmB,EAAE,KAAa,EAAmB,EAAE,CAAC,CAAC;QACrE,GAAG,EAAE,IAAI;QACT,SAAS;QACT,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;QACnB,OAAO;QACP,KAAK;KACN,CAAC,CAAC;IAEH,IAAI,KAAmB,CAAC;IACxB,IAAI,CAAC;QACH,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,0EAA0E;QAC1E,sEAAsE;QACtE,uEAAuE;QACvE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAC3B,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAoB,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAC1F,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3E,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACjC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACjC,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9D,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;YACrC,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC;QAC/C,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wEAAwE;QACxE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;QACzB,MAAM,CAAC,KAAK,GAAG,kBAAkB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,cAAc,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,SAAS,CAAC,KAAqB,EAAE,MAAuB;IACrE,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;IAC9E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAmBD,SAAS,SAAS,CAAC,KAAmB,EAAE,GAAkB;IACxD,OAAO,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,EAAE;QAC3C,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,SAAS,GAA0B,IAAI,CAAC;QAC5C,IAAI,SAAS,GAA0B,IAAI,CAAC;QAE5C,MAAM,WAAW,GAAG,GAAS,EAAE;YAC7B,IAAI,SAAS;gBAAE,YAAY,CAAC,SAAS,CAAC,CAAC;YACvC,IAAI,SAAS;gBAAE,YAAY,CAAC,SAAS,CAAC,CAAC;YACvC,SAAS,GAAG,IAAI,CAAC;YACjB,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;QAEF,MAAM,MAAM,GAAG,CAAC,MAAoB,EAAQ,EAAE;YAC5C,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,WAAW,EAAE,CAAC;YACd,KAAK,CAAC,kBAAkB,EAAE,CAAC;YAC3B,KAAK,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC;YACnC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC,CAAC;QAEF,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,QAAQ,GAAG,IAAI,CAAC;YAChB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC3B,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC7B,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QACtB,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QAElB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACjF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAEjF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAC/B,MAAM,CAAC;gBACL,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;gBACnB,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC;aAC1C,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,0EAA0E;QAC1E,oEAAoE;QACpE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACjC,MAAM,CACJ,OAAO,CAAC;gBACN,IAAI;gBACJ,MAAM,EAAE,MAAM,IAAI,IAAI;gBACtB,QAAQ;gBACR,MAAM;gBACN,MAAM;gBACN,SAAS,EAAE,GAAG,CAAC,SAAS;aACzB,CAAC,CACH,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,OAAO,CAAC,KAOhB;IACC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE3B,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO;YACL,OAAO;YACP,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,8BAA8B,KAAK,CAAC,SAAS,4BAA4B;SACjF,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,OAAO;oBACL,OAAO;oBACP,OAAO,EAAE,OAAO;oBAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,qCAAqC;iBACtE,CAAC;YACJ,CAAC;YACD,0EAA0E;YAC1E,MAAM,SAAS,GACb,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACjF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;QACpD,CAAC;QACD,2EAA2E;QAC3E,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;IAChF,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,OAAO;YACL,OAAO;YACP,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,uCAAuC,KAAK,CAAC,MAAM,EAAE;SAC7D,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO;QACL,OAAO;QACP,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,UAAU,IAAI,6BAA6B,KAAK,CAAC,IAAI,EAAE;KAC/D,CAAC;AACJ,CAAC;AAOD;;;;GAIG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,SAAS,GAAG,KAAyB,CAAC;IAC5C,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,SAA6B,EAAE,GAAsB;IAC7E,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QACjF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,0BAA0B,CAAC;IAC3C,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxC,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC;IAC5D,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED;qDACqD;AACrD,SAAS,QAAQ,CAAC,GAAsB;IACtC,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,SAAS;QAC3C,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAY,EAAE,MAAc;IACrD,MAAM,IAAI,GAAI,GAAoC,EAAE,IAAI,CAAC;IACzD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,0BAA0B,CAAC;IACzD,OAAO,mBAAmB,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAmB,EAAE,MAAsB;IAC3D,IAAI,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;AACH,CAAC;AAWD;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO;QACL,IAAI,CAAC,KAAa;YAChB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;YACrB,OAAO,IAAI,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzC,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;gBACzB,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,CAAC;YACD,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;gBACjB,oDAAoD;gBACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,KAAK,CAAC;gBAC9B,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACtC,IAAI,IAAI,QAAQ,CAAC;YACnB,CAAC;QACH,CAAC;QACD,IAAI;YACF,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/web-server/hook-auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bearer-token gate for `/api/hook/*`.
+ *
+ * Layered on top of (never instead of) the global loopback-only
+ * `secureLocalRequest`: loopback proves the caller is on this machine, the
+ * token proves it is this project's installed hook script. Browser-facing
+ * routes stay token-free — only the hook endpoint carries a shared secret,
+ * because only it is called by something that is not the ARCS web UI.
+ */
+import type { MiddlewareHandler } from "hono";
+export declare const requireHookToken: MiddlewareHandler;
+//# sourceMappingURL=hook-auth.d.ts.map

package/dist/web-server/hook-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-auth.d.ts","sourceRoot":"","sources":["../../src/web-server/hook-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAY9C,eAAO,MAAM,gBAAgB,EAAE,iBAmB9B,CAAC"}

package/dist/web-server/hook-auth.js

@@ -0,0 +1,36 @@
+/**
+ * Bearer-token gate for `/api/hook/*`.
+ *
+ * Layered on top of (never instead of) the global loopback-only
+ * `secureLocalRequest`: loopback proves the caller is on this machine, the
+ * token proves it is this project's installed hook script. Browser-facing
+ * routes stay token-free — only the hook endpoint carries a shared secret,
+ * because only it is called by something that is not the ARCS web UI.
+ */
+import { verifyHookToken } from "../utils/hook-token-store.js";
+import { fail, requireProjectDir } from "./respond.js";
+const BEARER = /^Bearer\s+(\S+)$/i;
+/** `/api/hook/:slug/...` → the slug segment, or "" when the shape is wrong. */
+function slugFromPath(url) {
+    const segments = new URL(url).pathname.split("/");
+    return segments[1] === "api" && segments[2] === "hook" ? (segments[3] ?? "") : "";
+}
+export const requireHookToken = async (c, next) => {
+    const unauthorized = () => c.json(fail("hook_unauthorized", "Missing or invalid ARCS hook token"), 401);
+    const match = BEARER.exec((c.req.header("authorization") ?? "").trim());
+    if (!match)
+        return unauthorized();
+    let projectDir;
+    try {
+        projectDir = requireProjectDir(slugFromPath(c.req.url));
+    }
+    catch {
+        // Deliberately 401, not 404: an unauthenticated caller must not be able to
+        // probe which project slugs exist on this machine.
+        return unauthorized();
+    }
+    if (!(await verifyHookToken(projectDir, match[1])))
+        return unauthorized();
+    await next();
+};
+//# sourceMappingURL=hook-auth.js.map

package/dist/web-server/hook-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-auth.js","sourceRoot":"","sources":["../../src/web-server/hook-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,MAAM,GAAG,mBAAmB,CAAC;AAEnC,+EAA+E;AAC/E,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACpF,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAsB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;IACnE,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,oCAAoC,CAAC,EAAE,GAAG,CAAC,CAAC;IAE/E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACxE,IAAI,CAAC,KAAK;QAAE,OAAO,YAAY,EAAE,CAAC;IAElC,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,mDAAmD;QACnD,OAAO,YAAY,EAAE,CAAC;IACxB,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,YAAY,EAAE,CAAC;IAE1E,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC"}

package/dist/web-server/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Web server entry — starts the HTTP server for the ARCS web UI.
+ */
+export interface StartWebServerOptions {
+    /** Port to listen on (default 4173). Pass 0 for an ephemeral port. */
+    port?: number;
+    /** Interface to bind (default 127.0.0.1). */
+    host?: string;
+    /** Auto-open the browser (default false here; the CLI command defaults true). */
+    open?: boolean;
+    /** Override the static client root. */
+    staticRoot?: string;
+    /** Disable the data-dir watcher (tests). */
+    watch?: boolean;
+}
+export interface WebServerHandle {
+    url: string;
+    port: number;
+    host: string;
+    close: () => Promise<void>;
+}
+export declare function startWebServer(options?: StartWebServerOptions): Promise<WebServerHandle>;
+//# sourceMappingURL=index.d.ts.map

package/dist/web-server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-server/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAeD,wBAAsB,cAAc,CAClC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC,CA8B1B"}

package/dist/web-server/index.js

@@ -0,0 +1,49 @@
+/**
+ * Web server entry — starts the HTTP server for the ARCS web UI.
+ */
+import { spawn } from "node:child_process";
+import { serve } from "@hono/node-server";
+import { createApp } from "./app.js";
+import { isLoopbackHost } from "./security.js";
+function openBrowser(url) {
+    try {
+        const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+        const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // No browser available — the URL is printed either way.
+    }
+}
+export async function startWebServer(options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const requestedPort = options.port ?? 4173;
+    if (!isLoopbackHost(host)) {
+        throw new Error(`ARCS web only binds to loopback addresses; refusing non-loopback host "${host}".`);
+    }
+    const app = createApp({ staticRoot: options.staticRoot, watch: options.watch });
+    return new Promise((resolvePromise, rejectPromise) => {
+        try {
+            const server = serve({ fetch: app.fetch, port: requestedPort, hostname: host }, (info) => {
+                const url = `http://${host}:${info.port}`;
+                if (options.open)
+                    openBrowser(url);
+                resolvePromise({
+                    url,
+                    port: info.port,
+                    host,
+                    close: () => new Promise((res) => {
+                        server.close(() => res());
+                    }),
+                });
+            });
+            server.on("error", rejectPromise);
+        }
+        catch (err) {
+            rejectPromise(err);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/web-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web-server/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAsB/C,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GACP,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7F,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5B,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAiC,EAAE;IAEnC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACzC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAC3C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,0EAA0E,IAAI,IAAI,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAEhF,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE;QACnD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;gBACvF,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC1C,IAAI,OAAO,CAAC,IAAI;oBAAE,WAAW,CAAC,GAAG,CAAC,CAAC;gBACnC,cAAc,CAAC;oBACb,GAAG;oBACH,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,IAAI;oBACJ,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE;wBACxB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;oBAC5B,CAAC,CAAC;iBACL,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,aAAa,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/web-server/opencode-client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * opencode session discovery bridge (Phase 1 — observability only).
+ *
+ * ARCS never spawns or manages an opencode server; it attaches to an already
+ * running `opencode serve` instance as a thin client, subscribes to the
+ * cross-instance `/global/event` SSE stream, and mirrors what it sees into the
+ * per-project session store. Everything here is best-effort: if opencode is
+ * not configured, not running, or speaks a different dialect, the ARCS web
+ * server keeps working and the sessions list is simply empty or stale.
+ *
+ * Verified against opencode 0.0.0-main-202607110203:
+ * - `opencode serve` defaults to port 0 (ephemeral), so a port/URL must be
+ *   supplied explicitly via env — there is no safe default to guess.
+ * - `OPENCODE_SERVER_PASSWORD` is enforced as HTTP Basic auth with the literal
+ *   username "opencode"; any other username is rejected with 401.
+ * - `/event` is scoped to one instance (`?directory=`); `/global/event` is the
+ *   cross-directory stream and wraps each event as `{ directory, project,
+ *   payload }`. Frames carry no `event:` field, only `data:`.
+ */
+import { type SessionStatus } from "../utils/session-store.js";
+export interface OpencodeConfig {
+    baseUrl: string;
+    password?: string;
+}
+/**
+ * Reads bridge configuration from the environment. Returns null (discovery
+ * disabled) when no opencode endpoint is configured.
+ */
+export declare function readOpencodeConfig(env?: NodeJS.ProcessEnv): OpencodeConfig | null;
+export interface OpencodeMessageTarget {
+    /** opencode-native session id ("ses_…") — never the ARCS normalized id. */
+    runtimeSessionId: string;
+    /** Worktree the session belongs to, when known — scopes opencode's lookup. */
+    directory?: string;
+}
+/**
+ * Injects a user message into a live opencode session.
+ *
+ * Unlike the rest of this module (best-effort observability) this is a user
+ * mutation, so failures throw a typed DagError the web routes can surface.
+ *
+ * Verified against opencode 1.0.0 (`GET /doc`) plus a live server:
+ * - `POST /session/:sessionID/prompt_async` acks with 204 and runs the turn in
+ *   the background. `POST /session/:sessionID/message` takes the same body but
+ *   only responds once the assistant has finished its whole turn — minutes, for
+ *   a browser request — so async delivery is the one that fits a web form.
+ * - the body requires `parts`; a text part is `{ type: "text", text }`.
+ * - `?directory=` is optional (an unscoped send still lands) but is passed when
+ *   known so the lookup is unambiguous across worktrees.
+ */
+export declare function sendOpencodeMessage(config: OpencodeConfig, target: OpencodeMessageTarget, text: string): Promise<void>;
+export interface CreateOpencodeSessionInput {
+    /** Worktree the session runs in — required, see the directory note below. */
+    directory: string;
+    title?: string;
+}
+/** Only what ARCS needs to mirror the session; the SSE stream fills in the rest. */
+export interface CreatedOpencodeSession {
+    runtimeSessionId: string;
+    title?: string;
+}
+/**
+ * Creates a live opencode session bound to a worktree.
+ *
+ * Verified against opencode 0.0.0-main-202607110203 (`GET /doc`, operationId
+ * `session.create`) plus a live server:
+ * - the route is `POST /session` — NOT `/api/session`. opencode serves its own
+ *   web UI from the same port and answers every unknown path with a 200
+ *   text/html SPA shell, so a wrong path looks like a success until the body is
+ *   read. That is why the id is checked below rather than trusting `res.ok`.
+ * - `directory` is a *query* parameter and never a body field. Omitting it does
+ *   not fail; opencode silently creates the session in its own working
+ *   directory, so the caller must always pass the worktree explicitly.
+ * - `title` is the only body field ARCS sets; the response is a full session
+ *   object (`{ id, slug, directory, title, time }`).
+ * - `DELETE /session/:sessionID` exists, so nothing created here is permanent.
+ */
+export declare function createOpencodeSession(config: OpencodeConfig, input: CreateOpencodeSessionInput): Promise<CreatedOpencodeSession>;
+interface OpencodeSessionInfo {
+    id?: string;
+    slug?: string;
+    title?: string;
+    directory?: string;
+    projectID?: string;
+    time?: {
+        created?: number;
+        updated?: number;
+    };
+    project?: {
+        worktree?: string;
+    };
+}
+interface OpencodeEvent {
+    type?: string;
+    properties?: {
+        sessionID?: string;
+        info?: OpencodeSessionInfo;
+        status?: {
+            type?: string;
+        };
+    };
+}
+/**
+ * Maps an opencode event type to the ARCS session status it implies.
+ * Returns null for events that carry no status transition (the record is
+ * refreshed but its status is left alone).
+ */
+export declare function statusForOpencodeEvent(event: OpencodeEvent): SessionStatus | null;
+export interface OpencodeDiscoveryState {
+    enabled: boolean;
+    connected: boolean;
+    baseUrl: string | null;
+}
+export declare function opencodeDiscoveryState(): OpencodeDiscoveryState;
+/**
+ * Starts the discovery loop if an opencode endpoint is configured. Idempotent;
+ * returns false when discovery is disabled (no configuration present).
+ */
+export declare function startOpencodeDiscovery(config?: OpencodeConfig | null): boolean;
+/** Stops the discovery loop (test cleanup / server shutdown). */
+export declare function stopOpencodeDiscovery(): Promise<void>;
+export {};
+//# sourceMappingURL=opencode-client.d.ts.map

package/dist/web-server/opencode-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-client.d.ts","sourceRoot":"","sources":["../../src/web-server/opencode-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,2BAA2B,CAAC;AAanC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,GAAG,IAAI,CAc9F;AAYD,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAiCf;AAMD,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAyCjC;AAeD,UAAU,mBAAmB;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,mBAAmB,CAAC;QAC3B,MAAM,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5B,CAAC;CACH;AAQD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAuBjF;AA2DD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,wBAAgB,sBAAsB,IAAI,sBAAsB,CAE/D;AAoQD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,wBAAuB,GAAG,OAAO,CAW7E;AAED,iEAAiE;AACjE,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3D"}