@chances-ai/wire 24.0.0

package/dist/serve/acp-session-host.js

@@ -0,0 +1,276 @@
+/**
+ * (v20 M3 / docs/6.4a §3; v21 M4 lease / docs/6.5 §5) `AcpSessionHost` — the ACP
+ * twin of the bespoke session host. ONE persistent engine session per process,
+ * sockets attach/detach over a seq-stamping `ReplayHub` fan-out; the inner engine
+ * is the `AcpEngineDriver` (ACP JSON-RPC wire).
+ *
+ * Two deliberate differences from the M2 design:
+ *  1. **State source.** The reconnect snapshot (`busy` / `pendingPermissionIds`)
+ *     is read straight off the driver (authoritative). The `ReplayHub` stays a
+ *     pure payload-agnostic seq/replay/fan-out layer — it does NOT parse the
+ *     outbound bytes for session state (a byte-snoop lived there in the
+ *     chances-rpc era; removed with the M3 hard cutover, since ACP frames' first
+ *     key is `jsonrpc`/`rseq`, never `type`).
+ *  2. **No `ready` re-send.** ACP is client-initiated: a fresh client sends
+ *     `initialize`/`session/new` and the driver replies; a cold-reloaded client
+ *     re-initializes (client-core, c4).
+ *
+ * **Controller lease (v21 M4 §5).** Disabled by default ⇒ fan-out: any paired
+ * device drives, the engine serializes turns via `AGENT_BUSY` (the M2 model).
+ * When enabled, this host gates every inbound command by its source clientId —
+ * only the lease HOLDER may drive (`session/prompt`/`cancel`), answer a
+ * permission, or change the model; everyone else is a read-only VIEWER and gets a
+ * typed `not_controller`. `_chances/unstable/take_control` hands control over
+ * (any authed client may claim it — single-user multi-device) and bumps
+ * `controlEpoch`; the new holder + epoch are broadcast as a
+ * `_chances/unstable/control` notification. The gate lives HERE (it needs the
+ * socket→clientId map) so the driver stays a protocol-pure turn runner.
+ *
+ * **Threat model (codex M4-review).** The lease is COORDINATION among one user's
+ * equally-authed devices, NOT an authorization boundary. The security boundary is
+ * the pairing token (every connection is already token-authed); `clientId` is a
+ * self-reported coordination tag, not a trusted identity. A device could spoof
+ * another's clientId to "impersonate" the holder — but it gains nothing
+ * `take_control` doesn't already grant (any authed client may claim control), so
+ * there is no privilege escalation among your own devices. A truly-restricted
+ * viewer (read-only access shared with a THIRD party) needs server-issued identity
+ * and belongs to the multi-tenant Team era — out of scope here.
+ *
+ * The seq/replay layer (`ReplayHub`) is reused UNCHANGED — it stamps `rseq` on
+ * the serialized ACP JSON-RPC bytes (payload-agnostic, docs/6.2 §3.2).
+ */
+import { AcpEngineDriver, dispatchWorkspaceQuery, hostSupportsWorkspaceQueries, isWorkspaceQueryMethod, } from "../rpc/index.js";
+import { ReplayHub } from "./replay-hub.js";
+import { MessageQueue } from "./ws-transport.js";
+/** Lease wire methods (chances extensions; a plain ACP client never sends them). */
+const METHOD_TAKE_CONTROL = "_chances/unstable/take_control";
+const METHOD_CONTROL_STATE = "_chances/unstable/control";
+/** JSON-RPC error for a viewer's privileged command while a lease is held. */
+const NOT_CONTROLLER = -32010;
+/** (v23 M5) Bound a read-only workspace query so a hung git/fs can't park a
+ *  fire-and-forget handler forever. */
+const QUERY_TIMEOUT_MS = 10_000;
+export class AcpSessionHost {
+    hub;
+    queue = new MessageQueue();
+    driver;
+    host;
+    done;
+    epochCounter = 0;
+    shuttingDown = false;
+    // -- controller lease (§5) --
+    leaseEnabled;
+    holder = null;
+    controlEpoch = 0;
+    /** clientId → socket, for TARGETED lease replies (not_controller / ack). */
+    socketsByClient = new Map();
+    constructor(opts) {
+        this.hub = new ReplayHub(opts.ring);
+        this.host = opts.host;
+        this.leaseEnabled = opts.controllerLease ?? false;
+        this.driver = new AcpEngineDriver({
+            host: opts.host,
+            sink: this.hub,
+            agent: opts.agent,
+            autoApprove: opts.autoApprove ?? false,
+            logSink: opts.logSink,
+            // (v23 M5) Advertise read-only workspace queries when the host supports
+            // them — this host intercepts + answers them off-ring (the driver itself
+            // never handles them), so the capability is honest only under the relay.
+            workspaceQueries: hostSupportsWorkspaceQueries(opts.host),
+        });
+        // Build + drive the one session immediately; `run` reads the persistent
+        // queue until it ends (process shutdown). Fire-and-forget; run catches.
+        this.done = this.driver.run(this.queue).catch(() => 1);
+    }
+    /**
+     * Attach a socket, synchronously replaying everything since `lastSeq` then
+     * going live (same disjoint-and-ordered guarantee as the M2 host). `clientId`
+     * (from the `?client_id=` connect query) attributes this socket for the lease.
+     * Wire order: `relay_welcome` → replayed gap → re-sent open permissions → [live].
+     */
+    attach(socket, lastSeq, clientId) {
+        const epoch = ++this.epochCounter;
+        const slice = this.hub.replaySince(lastSeq);
+        const welcome = {
+            type: "relay_welcome",
+            epoch,
+            headSeq: this.hub.headSeq,
+            reset: slice.reset,
+            busy: this.driver.busy,
+            pendingPermissionIds: this.driver.pendingPermissionIds(),
+            lease: this.leaseEnabled,
+            holder: this.holder,
+            controlEpoch: this.controlEpoch,
+        };
+        if (!this.hub.sendTo(socket, frameLine(welcome)))
+            return deadAttachment(epoch);
+        for (const line of slice.frames) {
+            if (!this.hub.sendTo(socket, line))
+                return deadAttachment(epoch);
+        }
+        // Re-send still-open permission asks (the ring may have evicted them); the
+        // client de-dups by permission id, so one also present in the replay is a no-op.
+        for (const open of this.driver.openPermissionFrames()) {
+            if (!this.hub.sendTo(socket, open))
+                return deadAttachment(epoch);
+        }
+        this.hub.addSocket(socket);
+        if (clientId)
+            this.socketsByClient.set(clientId, socket);
+        return {
+            epoch,
+            detach: () => {
+                this.hub.removeSocket(socket);
+                // Only drop the mapping if it still points at THIS socket — a reconnect
+                // with the same clientId installs a new socket we must not evict. The
+                // holder is intentionally retained: the same client reconnecting resumes
+                // control; another device can always `take_control` if it left for good.
+                if (clientId && this.socketsByClient.get(clientId) === socket)
+                    this.socketsByClient.delete(clientId);
+            },
+        };
+    }
+    /**
+     * One inbound text message (ACP JSON-RPC). Split LF-batched lines; each line
+     * passes the lease {@link gate} (a no-op when the lease is disabled) before
+     * reaching the ONE persistent queue. `fromClientId` (the attach's clientId)
+     * attributes the command to a client for the lease.
+     */
+    onMessage(text, fromClientId) {
+        for (const part of text.split("\n")) {
+            const line = part.trim();
+            if (!line)
+                continue;
+            // (v23 M5) Read-only workspace queries (file tree / read / git) are
+            // intercepted BEFORE the lease gate — they are non-privileged, so a viewer
+            // may browse — and answered targeted + off-ring (never enqueued, never
+            // stamped into the replay ring; a big `read_file` must not fan out to every
+            // device or get replayed on reconnect).
+            const msg = tryParseMessage(line);
+            if (msg && typeof msg.method === "string" && isWorkspaceQueryMethod(msg.method)) {
+                void this.handleQuery(msg, fromClientId);
+                continue;
+            }
+            if (this.gate(line, fromClientId))
+                this.queue.push(line);
+        }
+    }
+    /** Answer one read-only workspace query: dispatch to the host's query
+     *  primitives and `replyTo` the originating socket only (off-ring). Needs an id
+     *  (to respond) and a clientId (to target); a query missing either is dropped
+     *  (a conformant client always sends both). */
+    async handleQuery(msg, fromClientId) {
+        if (msg.id === undefined || fromClientId === undefined)
+            return;
+        const outcome = await dispatchWorkspaceQuery(this.host, msg.method, msg.params, AbortSignal.timeout(QUERY_TIMEOUT_MS));
+        this.replyTo(fromClientId, outcome.error ? { jsonrpc: "2.0", id: msg.id, error: outcome.error } : { jsonrpc: "2.0", id: msg.id, result: outcome.result });
+    }
+    /**
+     * Controller-lease gate. Returns true ⇒ the line may proceed to the driver;
+     * false ⇒ the host handled it (a handoff) or rejected it (a viewer's privileged
+     * command — a `not_controller` reply was sent to the source). A no-op (always
+     * true) when the lease is disabled.
+     */
+    gate(line, fromClientId) {
+        if (!this.leaseEnabled)
+            return true; // default: fan-out, anyone drives
+        const msg = tryParseMessage(line);
+        if (!msg)
+            return true; // unparseable → let the driver reject it
+        // Handoff: any authed client may take control (single-user multi-device).
+        if (msg.method === METHOD_TAKE_CONTROL) {
+            if (fromClientId) {
+                this.holder = fromClientId;
+                this.controlEpoch++;
+                this.broadcastControlState();
+                if (msg.id !== undefined) {
+                    this.replyTo(fromClientId, { jsonrpc: "2.0", id: msg.id, result: { holder: this.holder, controlEpoch: this.controlEpoch } });
+                }
+            }
+            return false; // host-handled; never a driver command
+        }
+        if (!isPrivileged(msg))
+            return true; // read-only (initialize/get_state/ping) → viewers allowed
+        // Privileged (drive a turn / answer a permission / change model). Auto-claim
+        // an unheld lease for the first driver, then enforce the holder.
+        if (this.holder === null && fromClientId) {
+            this.holder = fromClientId;
+            this.broadcastControlState();
+        }
+        if (fromClientId === undefined || fromClientId !== this.holder) {
+            if (fromClientId !== undefined && msg.id !== undefined) {
+                this.replyTo(fromClientId, {
+                    jsonrpc: "2.0",
+                    id: msg.id,
+                    error: { code: NOT_CONTROLLER, message: "not the controller — a lease is active; take control first" },
+                });
+            }
+            return false; // a stale command from a former holder lands here too (id ≠ holder)
+        }
+        return true;
+    }
+    /** Broadcast the current lease state to every socket (stamped + fanned out). */
+    broadcastControlState() {
+        const frame = JSON.stringify({ jsonrpc: "2.0", method: METHOD_CONTROL_STATE, params: { lease: this.leaseEnabled, holder: this.holder, controlEpoch: this.controlEpoch } }) + "\n";
+        this.hub.write(frame);
+    }
+    /** Send a single frame to ONE client (targeted; not fanned out, not stamped). */
+    replyTo(clientId, obj) {
+        const socket = this.socketsByClient.get(clientId);
+        if (socket)
+            this.hub.sendTo(socket, JSON.stringify(obj) + "\n");
+    }
+    get headSeq() {
+        return this.hub.headSeq;
+    }
+    get socketCount() {
+        return this.hub.socketCount;
+    }
+    get busy() {
+        return this.driver.busy;
+    }
+    /** Current lease holder (clientId) or null. Exposed for tests/diagnostics. */
+    get controllerHolder() {
+        return this.holder;
+    }
+    /** End the persistent queue → `run` returns → graceful driver shutdown. */
+    async shutdown() {
+        if (!this.shuttingDown) {
+            this.shuttingDown = true;
+            this.queue.end();
+        }
+        return this.done;
+    }
+}
+function frameLine(frame) {
+    return JSON.stringify(frame) + "\n";
+}
+function deadAttachment(epoch) {
+    return { epoch, detach: () => { } };
+}
+function tryParseMessage(line) {
+    try {
+        const m = JSON.parse(line);
+        return typeof m === "object" && m !== null ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A command that DRIVES the session (only the lease holder may send it): drive a
+ *  turn, change the model/options, or ANSWER a permission (a JSON-RPC response —
+ *  no method, an id, and a result/error). Read-only methods
+ *  (initialize/session.new/get_state/get_models/ping) are NOT privileged so a
+ *  viewer can still connect + observe. */
+function isPrivileged(msg) {
+    const m = msg.method;
+    if (m === "session/prompt" || m === "session/cancel")
+        return true;
+    if (m === "_chances/unstable/set_model" || m === "_chances/unstable/set_options")
+        return true;
+    if (m === undefined && msg.id !== undefined && ("result" in msg || "error" in msg))
+        return true;
+    return false;
+}
+//# sourceMappingURL=acp-session-host.js.map

package/dist/serve/acp-session-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-session-host.js","sourceRoot":"","sources":["../../src/serve/acp-session-host.ts"],"names":[],"mappings":"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"}

package/dist/serve/auth.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingHttpHeaders } from "node:http";
+/** Header carrying the pairing token (non-browser clients). Lowercased — Node
+ *  normalizes incoming header names to lowercase. */
+export declare const PAIRING_HEADER = "x-chances-pair";
+/** Mint a fresh 256-bit pairing token (64 lowercase hex chars). */
+export declare function mintPairingToken(): string;
+/**
+ * Pull a pairing token off a WS upgrade request: the `X-Chances-Pair` header
+ * first (non-browser), else the `?token=` query param (browser fallback).
+ * `baseUrl` is the relay's OWN bound base (the `Host` header is not trusted —
+ * consistent with `requestUrl`). Returns undefined when neither carries one.
+ */
+export declare function extractToken(reqUrl: string | undefined, headers: IncomingHttpHeaders, baseUrl: string): string | undefined;
+/**
+ * Constant-time token check. Fail-closed: an absent/empty/length-mismatched/
+ * wrong token all return false. (`timingSafeEqual` THROWS on unequal-length
+ * buffers, so the length guard is required; the token length is fixed and public,
+ * not a secret, so an early length return leaks nothing useful.)
+ */
+export declare function checkToken(provided: string | undefined, expected: string): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/serve/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/serve/auth.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD;qDACqD;AACrD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,mEAAmE;AACnE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAS1H;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMlF"}

package/dist/serve/auth.js

@@ -0,0 +1,58 @@
+/**
+ * (v21 M4 / docs/6.5 §2) Pairing-token auth primitives for the relay edge.
+ *
+ * Pure + stateless: minting/storage live in the CLI (they need the vault +
+ * runtime); the relay only CHECKS a token at the WS `upgrade` edge — fail-closed,
+ * BEFORE a socket ever reaches `AcpSessionHost`. Loopback needs no token (the
+ * trust boundary is "any local process is you"); a non-loopback bind REQUIRES one
+ * (enforced in Stage 2 together with TLS, so a token never crosses the wire in
+ * cleartext).
+ *
+ * Token shape mirrors goose's `X-Secret-Key` (`crates/goose-server/src/auth.rs`):
+ * a 256-bit random hex, accepted from the `X-Chances-Pair` header OR the `?token=`
+ * connect-URL query (a browser WebSocket can't set headers — the same reason M2
+ * put the replay cursor in the query). Compared constant-time (`timingSafeEqual`)
+ * to blunt token-probing timing attacks.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+/** Header carrying the pairing token (non-browser clients). Lowercased — Node
+ *  normalizes incoming header names to lowercase. */
+export const PAIRING_HEADER = "x-chances-pair";
+/** Mint a fresh 256-bit pairing token (64 lowercase hex chars). */
+export function mintPairingToken() {
+    return randomBytes(32).toString("hex");
+}
+/**
+ * Pull a pairing token off a WS upgrade request: the `X-Chances-Pair` header
+ * first (non-browser), else the `?token=` query param (browser fallback).
+ * `baseUrl` is the relay's OWN bound base (the `Host` header is not trusted —
+ * consistent with `requestUrl`). Returns undefined when neither carries one.
+ */
+export function extractToken(reqUrl, headers, baseUrl) {
+    const h = headers[PAIRING_HEADER];
+    const headerVal = Array.isArray(h) ? h[0] : h;
+    if (headerVal)
+        return headerVal;
+    try {
+        return new URL(reqUrl ?? "/", baseUrl).searchParams.get("token") ?? undefined;
+    }
+    catch {
+        return undefined; // malformed URL → no token
+    }
+}
+/**
+ * Constant-time token check. Fail-closed: an absent/empty/length-mismatched/
+ * wrong token all return false. (`timingSafeEqual` THROWS on unequal-length
+ * buffers, so the length guard is required; the token length is fixed and public,
+ * not a secret, so an early length return leaks nothing useful.)
+ */
+export function checkToken(provided, expected) {
+    if (!provided || !expected)
+        return false;
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+//# sourceMappingURL=auth.js.map

package/dist/serve/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/serve/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG3D;qDACqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAE/C,mEAAmE;AACnE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B,EAAE,OAA4B,EAAE,OAAe;IACpG,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,2BAA2B;IAC/C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,QAA4B,EAAE,QAAgB;IACvE,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACzC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/serve/highlight.d.ts

@@ -0,0 +1,25 @@
+/**
+ * (v17 M0 / docs/6.1 §1.4 res #2) Server-side syntax highlighting. The relay
+ * reuses ui-core's PURE `highlightToSegments`, so the wire can carry themed
+ * `Segment[]` and NO client ships a highlighter (shiki is dropped): the TUI,
+ * web, desktop, and mobile all render byte-identical segments produced by the
+ * same function. This is the load-bearing reuse that makes res #2 work.
+ *
+ * M0 wires the SEAM (a server-callable highlighter + golden parity test); the
+ * full frame-emit path — attaching segments to code/markdown frames on the
+ * `chances-rpc` wire — lands with the web renderer in M1.
+ */
+import { type Segment } from "@chances-ai/ui-core";
+export type { Segment };
+/**
+ * Highlight `code` as `lang` into themed segments for the wire. Thin pass-through
+ * to ui-core's `highlightToSegments` (kept as a named server entry so M1 can wrap
+ * it with frame envelopes without callers reaching into ui-core directly).
+ * Unknown/absent language or any highlighter error degrades to a single `plain`
+ * segment — never throws.
+ */
+export declare function highlightForWire(code: string, lang: string | undefined): Segment[];
+/** Whether a language label resolves to a registered grammar (so the relay can
+ *  decide to highlight vs. ship plain). Mirrors the TUI's gate. */
+export declare function canHighlight(lang: string | undefined): boolean;
+//# sourceMappingURL=highlight.d.ts.map

package/dist/serve/highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../../src/serve/highlight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAwC,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEzF,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,EAAE,CAElF;AAED;mEACmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE9D"}

package/dist/serve/highlight.js

@@ -0,0 +1,28 @@
+/**
+ * (v17 M0 / docs/6.1 §1.4 res #2) Server-side syntax highlighting. The relay
+ * reuses ui-core's PURE `highlightToSegments`, so the wire can carry themed
+ * `Segment[]` and NO client ships a highlighter (shiki is dropped): the TUI,
+ * web, desktop, and mobile all render byte-identical segments produced by the
+ * same function. This is the load-bearing reuse that makes res #2 work.
+ *
+ * M0 wires the SEAM (a server-callable highlighter + golden parity test); the
+ * full frame-emit path — attaching segments to code/markdown frames on the
+ * `chances-rpc` wire — lands with the web renderer in M1.
+ */
+import { highlightToSegments, resolveLanguage } from "@chances-ai/ui-core";
+/**
+ * Highlight `code` as `lang` into themed segments for the wire. Thin pass-through
+ * to ui-core's `highlightToSegments` (kept as a named server entry so M1 can wrap
+ * it with frame envelopes without callers reaching into ui-core directly).
+ * Unknown/absent language or any highlighter error degrades to a single `plain`
+ * segment — never throws.
+ */
+export function highlightForWire(code, lang) {
+    return highlightToSegments(code, lang);
+}
+/** Whether a language label resolves to a registered grammar (so the relay can
+ *  decide to highlight vs. ship plain). Mirrors the TUI's gate. */
+export function canHighlight(lang) {
+    return resolveLanguage(lang) !== null;
+}
+//# sourceMappingURL=highlight.js.map

package/dist/serve/highlight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.js","sourceRoot":"","sources":["../../src/serve/highlight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAgB,MAAM,qBAAqB,CAAC;AAIzF;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAwB;IACrE,OAAO,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,YAAY,CAAC,IAAwB;IACnD,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AACxC,CAAC"}

package/dist/serve/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@chances-ai/serve` — the thin local relay exposing the engine to web +
+ * mobile clients (docs/6.1 §3.1 / 6.4a M3). A default-loopback HTTP server with
+ * `/health` + a persistent WS `/acp` ACP control channel (replay/reconnect) +
+ * static SPA serving. No agent logic lives here — the engine is reached through
+ * the `@chances-ai/rpc` `EngineHost` seam (the `AcpEngineDriver` projection).
+ */
+export { LOOPBACK, DEFAULT_PORT, type BindOptions, type BindAddress, resolveBindAddress, isLoopbackHost, type RelayDeps, type RpcRelayDeps, handleRequest, type RelayHandle, startRelay, parsePortFlag, parseHostFlag, serveStatic, } from "./relay.js";
+export { generateSelfSignedCert, fingerprintOf, type SelfSignedCert } from "./tls.js";
+export { buildPairingDeepLink, type PairingPayload } from "./pairing.js";
+export { MessageQueue, perConnectionHost, type ServerSocket } from "./ws-transport.js";
+export { highlightForWire, canHighlight, type Segment } from "./highlight.js";
+export { PAIRING_HEADER, mintPairingToken, extractToken, checkToken } from "./auth.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/serve/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/serve/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,kBAAkB,EAClB,cAAc,EACd,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,aAAa,EACb,KAAK,WAAW,EAChB,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIvF,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAI9E,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/serve/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@chances-ai/serve` — the thin local relay exposing the engine to web +
+ * mobile clients (docs/6.1 §3.1 / 6.4a M3). A default-loopback HTTP server with
+ * `/health` + a persistent WS `/acp` ACP control channel (replay/reconnect) +
+ * static SPA serving. No agent logic lives here — the engine is reached through
+ * the `@chances-ai/rpc` `EngineHost` seam (the `AcpEngineDriver` projection).
+ */
+export { LOOPBACK, DEFAULT_PORT, resolveBindAddress, isLoopbackHost, handleRequest, startRelay, parsePortFlag, parseHostFlag, serveStatic, } from "./relay.js";
+// (v21 M4 / docs/6.5 §3) Self-signed TLS cert generation + SHA-256 fingerprint
+// for a non-loopback bind. Pure; the CLI caches the PEM in the vault.
+export { generateSelfSignedCert, fingerprintOf } from "./tls.js";
+// (v21 M4 / docs/6.5 §4) QR pairing deep link (carries token + fingerprint + url).
+export { buildPairingDeepLink } from "./pairing.js";
+// (M3) Relay transport primitives reused by the persistent ACP `/acp` control
+// channel (M1's per-socket `RpcServer` binding was retired in the hard cutover).
+export { MessageQueue, perConnectionHost } from "./ws-transport.js";
+// (res #2) Server-side highlight seam — the relay emits themed segments so no
+// client ships a highlighter; the same ui-core function the TUI uses.
+export { highlightForWire, canHighlight } from "./highlight.js";
+// (v21 M4 / docs/6.5 §2) Pairing-token auth primitives for the relay edge. Pure
+// + stateless; minting/storage live in the CLI (they need the vault).
+export { PAIRING_HEADER, mintPairingToken, extractToken, checkToken } from "./auth.js";
+//# sourceMappingURL=index.js.map

package/dist/serve/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/serve/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,QAAQ,EACR,YAAY,EAGZ,kBAAkB,EAClB,cAAc,EAGd,aAAa,EAEb,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,sEAAsE;AACtE,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAuB,MAAM,UAAU,CAAC;AAEtF,mFAAmF;AACnF,OAAO,EAAE,oBAAoB,EAAuB,MAAM,cAAc,CAAC;AAEzE,8EAA8E;AAC9E,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAqB,MAAM,mBAAmB,CAAC;AAEvF,8EAA8E;AAC9E,sEAAsE;AACtE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAgB,MAAM,gBAAgB,CAAC;AAE9E,gFAAgF;AAChF,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/serve/pairing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * (v21 M4 / docs/6.5 §4) Pairing payload + deep link for QR-based pairing.
+ *
+ * A single scan conveys BOTH who-to-trust (the cert SHA-256 fingerprint, pinned
+ * TOFU) and proof-of-authorization (the pairing token), plus where (the wss URL)
+ * and a human label — so a phone (M6) or a second device pairs in one step. This
+ * is pure string building; rendering the QR to the terminal is the CLI's job.
+ */
+export interface PairingPayload {
+    /** The relay's wss URL, e.g. `wss://192.168.1.5:4517/acp`. */
+    url: string;
+    /** The pairing token (proof of authorization). */
+    token: string;
+    /** The cert SHA-256 fingerprint to pin (TOFU). */
+    fingerprint: string;
+    /** A human label for the host, e.g. the machine name. */
+    name: string;
+}
+/**
+ * Encode a pairing payload as a `chances://pair?…` deep link (a mobile custom
+ * scheme / universal link). All fields are URL-encoded; a client parses it back
+ * with `new URL(link).searchParams` (`url`/`token`/`fp`/`name`).
+ */
+export declare function buildPairingDeepLink(p: PairingPayload): string;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/serve/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/serve/pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAG9D"}

package/dist/serve/pairing.js

@@ -0,0 +1,10 @@
+/**
+ * Encode a pairing payload as a `chances://pair?…` deep link (a mobile custom
+ * scheme / universal link). All fields are URL-encoded; a client parses it back
+ * with `new URL(link).searchParams` (`url`/`token`/`fp`/`name`).
+ */
+export function buildPairingDeepLink(p) {
+    const q = new URLSearchParams({ url: p.url, token: p.token, fp: p.fingerprint, name: p.name });
+    return `chances://pair?${q.toString()}`;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/serve/pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.js","sourceRoot":"","sources":["../../src/serve/pairing.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAiB;IACpD,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/F,OAAO,kBAAkB,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC1C,CAAC"}

package/dist/serve/relay-frames.d.ts

@@ -0,0 +1,29 @@
+/**
+ * (v19 M2 / docs/6.2 §3.3) Relay-side reconnect helpers. The `RelayFrame` types
+ * + `stampSeq` live in `@chances-ai/rpc` (browser-safe, shared with client-core);
+ * this module holds the serve-only transport-parsing piece.
+ */
+/**
+ * Read the reconnect cursor a client carries on its `/acp` WebSocket upgrade.
+ *
+ * The cursor rides a **query parameter** `?last_event_id=N`, NOT an HTTP header
+ * — a browser `WebSocket` constructor cannot set request headers, so the header
+ * form is unreachable from the web client (claude-code makes the same choice
+ * with its `from_sequence_num` query param). The `Last-Event-ID` **header** is
+ * still honoured as a fallback for non-browser clients (and aligns the future
+ * M5 SSE leg with native `EventSource` reconnect). Query param wins if both are
+ * present.
+ *
+ * Returns `0` (a fresh client ⇒ full ring replay) when absent, empty, or
+ * malformed — never throws, never a negative or fractional cursor.
+ */
+export declare function parseLastEventId(urlPathAndQuery: string, headers: {
+    readonly [key: string]: string | string[] | undefined;
+}): number;
+/**
+ * (v21 M4 / docs/6.5 §5) Read the client id a client carries on its `/acp`
+ * upgrade (`?client_id=`), so the relay can attribute commands to a client for
+ * the controller lease. Returns undefined when absent/empty/malformed.
+ */
+export declare function parseClientId(urlPathAndQuery: string): string | undefined;
+//# sourceMappingURL=relay-frames.d.ts.map

package/dist/serve/relay-frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-frames.d.ts","sourceRoot":"","sources":["../../src/serve/relay-frames.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;CAAE,GACjE,MAAM,CAYR;AAQD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOzE"}

package/dist/serve/relay-frames.js

@@ -0,0 +1,54 @@
+/**
+ * (v19 M2 / docs/6.2 §3.3) Relay-side reconnect helpers. The `RelayFrame` types
+ * + `stampSeq` live in `@chances-ai/rpc` (browser-safe, shared with client-core);
+ * this module holds the serve-only transport-parsing piece.
+ */
+/**
+ * Read the reconnect cursor a client carries on its `/acp` WebSocket upgrade.
+ *
+ * The cursor rides a **query parameter** `?last_event_id=N`, NOT an HTTP header
+ * — a browser `WebSocket` constructor cannot set request headers, so the header
+ * form is unreachable from the web client (claude-code makes the same choice
+ * with its `from_sequence_num` query param). The `Last-Event-ID` **header** is
+ * still honoured as a fallback for non-browser clients (and aligns the future
+ * M5 SSE leg with native `EventSource` reconnect). Query param wins if both are
+ * present.
+ *
+ * Returns `0` (a fresh client ⇒ full ring replay) when absent, empty, or
+ * malformed — never throws, never a negative or fractional cursor.
+ */
+export function parseLastEventId(urlPathAndQuery, headers) {
+    // `urlPathAndQuery` is `req.url` ("/acp?last_event_id=42"); resolve against a
+    // dummy base so only the query matters (the host is irrelevant here).
+    let fromQuery = null;
+    try {
+        fromQuery = new URL(urlPathAndQuery, "http://relay.invalid").searchParams.get("last_event_id");
+    }
+    catch {
+        fromQuery = null;
+    }
+    const headerRaw = headers["last-event-id"];
+    const fromHeader = Array.isArray(headerRaw) ? headerRaw[0] : headerRaw;
+    return toCursor(fromQuery) ?? toCursor(fromHeader) ?? 0;
+}
+function toCursor(raw) {
+    if (raw === null || raw === undefined || raw === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+/**
+ * (v21 M4 / docs/6.5 §5) Read the client id a client carries on its `/acp`
+ * upgrade (`?client_id=`), so the relay can attribute commands to a client for
+ * the controller lease. Returns undefined when absent/empty/malformed.
+ */
+export function parseClientId(urlPathAndQuery) {
+    try {
+        const id = new URL(urlPathAndQuery, "http://relay.invalid").searchParams.get("client_id");
+        return id && id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=relay-frames.js.map

package/dist/serve/relay-frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-frames.js","sourceRoot":"","sources":["../../src/serve/relay-frames.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,eAAuB,EACvB,OAAkE;IAElE,8EAA8E;IAC9E,sEAAsE;IACtE,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,GAAG,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjG,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,OAAO,QAAQ,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,QAAQ,CAAC,GAA8B;IAC9C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,eAAuB;IACnD,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1F,OAAO,EAAE,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}