@chances-ai/wire 24.0.0

package/dist/rpc/rpc-server.js

@@ -0,0 +1,305 @@
+// The bespoke RPC server: a thin orchestrator over the `EngineHost` seam
+// (codex C1). It subscribes the engine bus → outbound frames, dispatches
+// inbound commands via a method table (C8), owns the permission round-trip
+// (deny-on-abort/close + dedup — C7, Round-1 M2), and runs the shutdown order
+// (cancel → deny → dispose → flush — Round-1 S4). No transport I/O lives here:
+// `run()` consumes an async-iterable of input lines and writes through the
+// injected `BoundedNdjsonWriter`, so the whole thing is unit-testable
+// in-process against a MockAdapter-backed engine.
+import { CancellationTokenSource, createId } from "@chances-ai/runtime";
+import { mapEvent } from "./event-map.js";
+import { CommandSchema, PROTOCOL_NAME, PROTOCOL_VERSION, } from "./protocol.js";
+import { BoundedNdjsonWriter } from "./writer.js";
+const KNOWN_TYPES = new Set([
+    "prompt",
+    "abort",
+    "set_model",
+    "get_state",
+    "get_models",
+    "permission_response",
+    "set_options",
+    "ping",
+]);
+const MAX_RESOLVED_IDS = 1024;
+/** Bound on awaiting an in-flight turn during shutdown (Round-2 M1). Matches
+ * the CLI's other 2 s teardown deadlines. */
+const SHUTDOWN_TURN_DEADLINE_MS = 2_000;
+export class RpcServer {
+    host;
+    writer;
+    agent;
+    autoApprove;
+    toolChunks;
+    logSink;
+    built = null;
+    unsub = null;
+    activeTurn = null;
+    /** The in-flight `handlePrompt` promise (fire-and-forget from the read
+     * loop). Tracked so shutdown can await its terminal `result` before
+     * closing the writer (Round-2 M1). */
+    activePrompt = null;
+    pending = new Map();
+    resolvedIds = [];
+    resolvedSet = new Set();
+    shuttingDown = false;
+    constructor(opts) {
+        this.host = opts.host;
+        this.writer = opts.writer;
+        this.agent = opts.agent;
+        this.autoApprove = opts.autoApprove ?? false;
+        this.toolChunks = opts.toolChunks ?? true;
+        this.logSink = opts.logSink ?? ((line) => process.stderr.write(line));
+    }
+    /** Drive the server until `lines` ends, then shut down. Returns an exit code. */
+    async run(lines) {
+        const built = this.host.build(this.makeResolver());
+        this.built = built;
+        // Subscribe BEFORE ready so no frame is missed. `log` is routed to stderr
+        // (stdout purity); everything else maps to a wire frame or is suppressed.
+        this.unsub = built.bus.onAny((e) => {
+            if (e.type === "log") {
+                this.logSink(`[${e.level}] ${e.message}\n`);
+                return;
+            }
+            const frame = mapEvent(e, { toolChunks: this.toolChunks });
+            if (!frame)
+                return;
+            if (frame.type === "turn_start")
+                frame.commandId = this.activeTurn?.commandId;
+            this.writer.enqueue(frame);
+        });
+        this.writer.enqueue({
+            type: "ready",
+            protocol: PROTOCOL_NAME,
+            version: PROTOCOL_VERSION,
+            agent: this.agent,
+            sessionId: built.sessionId,
+            models: this.host.listModels(),
+            capabilities: { permissionPrompt: true, toolChunks: this.toolChunks, steering: false },
+        });
+        try {
+            for await (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed === "")
+                    continue;
+                await this.handleLine(trimmed);
+            }
+        }
+        finally {
+            await this.shutdown();
+        }
+        return 0;
+    }
+    /** Idempotent shutdown. Order (Round-1 S4): cancel the turn → deny pending
+     * permissions (so a turn blocked in the resolver unwinds — M2) → dispose
+     * (disposers may emit their LAST bus frames, still subscribed) → flush →
+     * close. */
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.activeTurn?.cts.cancel();
+        this.denyAllPending();
+        // (Round-2 M1) Await the in-flight prompt so its terminal `result` frame
+        // is enqueued before we flush + close — otherwise EOF/SIGINT could ack a
+        // prompt and then drop its completion. Cancellation above makes runTurn
+        // settle promptly; the bounded race guards a turn that ignores the token.
+        if (this.activePrompt) {
+            await Promise.race([this.activePrompt, delay(SHUTDOWN_TURN_DEADLINE_MS)]);
+        }
+        try {
+            await this.host.dispose();
+        }
+        catch {
+            // dispose is best-effort; never let it block the flush.
+        }
+        await this.writer.flush();
+        this.unsub?.();
+        this.writer.close();
+    }
+    // -- command handling ------------------------------------------------------
+    async handleLine(line) {
+        let json;
+        try {
+            json = JSON.parse(line);
+        }
+        catch {
+            this.respondError(null, "parse", { code: "PARSE_ERROR", message: "invalid JSON line" });
+            return;
+        }
+        const parsed = CommandSchema.safeParse(json);
+        if (!parsed.success) {
+            const id = idOf(json);
+            const type = json?.type;
+            const unknown = typeof type !== "string" || !KNOWN_TYPES.has(type);
+            this.respondError(id, "parse", {
+                code: unknown ? "UNKNOWN_COMMAND" : "BAD_REQUEST",
+                message: parsed.error.issues[0]?.message ?? "invalid command",
+            });
+            return;
+        }
+        const cmd = parsed.data;
+        // `prompt` is long-running — fire-and-forget so the loop keeps reading
+        // `abort` / `permission_response` mid-turn. It emits its own `result`.
+        if (cmd.type === "prompt") {
+            // Fire-and-forget so the loop keeps reading abort/permission mid-turn,
+            // but track the promise so shutdown can await the terminal `result`
+            // (Round-2 M1). handlePrompt never rejects (it catches internally).
+            this.activePrompt = this.handlePrompt(cmd).finally(() => {
+                this.activePrompt = null;
+            });
+            return;
+        }
+        await this.dispatch(cmd);
+    }
+    async dispatch(cmd) {
+        switch (cmd.type) {
+            case "abort":
+                // Deny pending permissions FIRST so a turn parked in the resolver
+                // unwinds, then cancel the token (Round-1 M2).
+                this.denyAllPending();
+                this.activeTurn?.cts.cancel();
+                this.respondOk(cmd.id, "abort");
+                return;
+            case "set_model":
+                if (this.activeTurn) {
+                    this.respondError(cmd.id ?? null, "set_model", {
+                        code: "AGENT_BUSY",
+                        message: "cannot switch model while a turn is running",
+                    });
+                    return;
+                }
+                this.built?.selection.set({ provider: cmd.provider, model: cmd.model });
+                this.respondOk(cmd.id, "set_model", this.built?.selection.get() ?? {});
+                return;
+            case "get_state":
+                this.respondOk(cmd.id, "get_state", {
+                    model: this.built?.selection.get() ?? {},
+                    busy: this.activeTurn !== null,
+                    sessionId: this.built?.sessionId ?? "",
+                    toolChunks: this.toolChunks,
+                });
+                return;
+            case "get_models":
+                this.respondOk(cmd.id, "get_models", { models: this.host.listModels() });
+                return;
+            case "permission_response":
+                this.resolvePermission(cmd.id, cmd.allow, cmd.remember);
+                return; // no response frame — it's a reply, not a request
+            case "set_options":
+                if (cmd.toolChunks !== undefined)
+                    this.toolChunks = cmd.toolChunks;
+                this.respondOk(cmd.id, "set_options", { toolChunks: this.toolChunks });
+                return;
+            case "ping":
+                this.respondOk(cmd.id, "ping");
+                return;
+        }
+    }
+    async handlePrompt(cmd) {
+        if (this.activeTurn) {
+            this.respondError(cmd.id ?? null, "prompt", {
+                code: "AGENT_BUSY",
+                message: "a turn is already running",
+            });
+            return;
+        }
+        const cts = new CancellationTokenSource();
+        this.activeTurn = { cts, commandId: cmd.id };
+        this.respondOk(cmd.id, "prompt"); // ack now; completion is the `result` frame (C6)
+        let result = { text: "", inputTokens: 0, outputTokens: 0, costUsd: 0 };
+        let stopReason = "end";
+        try {
+            result = await this.built.runTurn(cmd.text, cts.token);
+        }
+        catch {
+            // Non-cancel engine errors already emitted an `error` bus frame before
+            // throwing; cancellation is user-initiated, not an error to re-surface.
+            stopReason = cts.token.isCancelled ? "cancelled" : "error";
+        }
+        finally {
+            this.activeTurn = null;
+        }
+        this.writer.enqueue({
+            type: "result",
+            commandId: cmd.id,
+            text: result.text,
+            usage: {
+                inputTokens: result.inputTokens,
+                outputTokens: result.outputTokens,
+                costUsd: result.costUsd,
+            },
+            stopReason,
+        });
+    }
+    // -- permission round-trip -------------------------------------------------
+    makeResolver() {
+        return (req) => {
+            // (5.10b) Narrow the union before reading authorization-only fields
+            // (`summary`/`args`/`cacheKey`). No remote question UI yet — the channel
+            // is ready, the host frame is a follow-up; a question declines for now.
+            if (req.kind === "question") {
+                const declined = { kind: "question", answers: {}, declined: true };
+                return Promise.resolve(declined);
+            }
+            if (this.autoApprove)
+                return Promise.resolve({ allow: true, remember: true });
+            const id = createId("perm");
+            return new Promise((resolve) => {
+                this.pending.set(id, resolve);
+                this.writer.enqueue({
+                    type: "request_permission",
+                    id,
+                    callId: req.callId,
+                    tool: req.name,
+                    category: req.category,
+                    summary: req.summary,
+                    args: req.args,
+                    cacheKey: req.cacheKey,
+                });
+            });
+        };
+    }
+    resolvePermission(id, allow, remember) {
+        if (this.resolvedSet.has(id))
+            return; // dedup orphan/duplicate (C7)
+        const resolve = this.pending.get(id);
+        if (!resolve)
+            return; // unknown id — ignore
+        this.pending.delete(id);
+        this.markResolved(id);
+        resolve({ allow, remember });
+    }
+    /** Resolve every outstanding permission with deny — unblocks a turn parked
+     * in the resolver on `abort` / shutdown (Round-1 M2). */
+    denyAllPending() {
+        for (const [id, resolve] of this.pending) {
+            this.markResolved(id);
+            resolve({ allow: false });
+        }
+        this.pending.clear();
+    }
+    markResolved(id) {
+        this.resolvedSet.add(id);
+        this.resolvedIds.push(id);
+        if (this.resolvedIds.length > MAX_RESOLVED_IDS) {
+            const evicted = this.resolvedIds.shift();
+            this.resolvedSet.delete(evicted);
+        }
+    }
+    // -- response helpers ------------------------------------------------------
+    respondOk(id, command, data) {
+        this.writer.enqueue({ type: "response", id: id ?? null, command, ok: true, data: data });
+    }
+    respondError(id, command, error) {
+        this.writer.enqueue({ type: "response", id, command, ok: false, error });
+    }
+}
+function idOf(json) {
+    const id = json?.id;
+    return typeof id === "string" ? id : null;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=rpc-server.js.map

package/dist/rpc/rpc-server.js.map

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

package/dist/rpc/stdout-guard.d.ts

@@ -0,0 +1,5 @@
+export interface StdoutGuard {
+    restore(): void;
+}
+export declare function installStdoutGuard(): StdoutGuard;
+//# sourceMappingURL=stdout-guard.d.ts.map

package/dist/rpc/stdout-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout-guard.d.ts","sourceRoot":"","sources":["../../src/rpc/stdout-guard.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,kBAAkB,IAAI,WAAW,CAuBhD"}

package/dist/rpc/stdout-guard.js

@@ -0,0 +1,31 @@
+// stdout purity guard (codex C5 + Round-1 S2). stdout carries ONLY protocol
+// frames; a single stray `console.log` from a dependency would corrupt the
+// client's NDJSON parser. Redirect the stdout-writing console methods to
+// stderr for the server's lifetime. `restore()` is idempotent and must run in
+// a `finally` so a thrown server (or an embedding test) can't leak the
+// override. The bus `log` event is routed to stderr by the server, not here.
+export function installStdoutGuard() {
+    // Save the ORIGINAL references (not `.bind` copies) so `restore()` puts the
+    // exact same functions back — identity matters for embedders/tests.
+    const saved = {
+        log: console.log,
+        info: console.info,
+        debug: console.debug,
+    };
+    const toErr = (...args) => console.error(...args);
+    console.log = toErr;
+    console.info = toErr;
+    console.debug = toErr;
+    let restored = false;
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            console.log = saved.log;
+            console.info = saved.info;
+            console.debug = saved.debug;
+        },
+    };
+}
+//# sourceMappingURL=stdout-guard.js.map

package/dist/rpc/stdout-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout-guard.js","sourceRoot":"","sources":["../../src/rpc/stdout-guard.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,8EAA8E;AAC9E,uEAAuE;AACvE,6EAA6E;AAQ7E,MAAM,UAAU,kBAAkB;IAChC,4EAA4E;IAC5E,oEAAoE;IACpE,MAAM,KAAK,GAAsE;QAC/E,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;IACF,MAAM,KAAK,GAAkB,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC;IACpB,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC;IACrB,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IAEtB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO;QACL,OAAO;YACL,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;YACxB,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YAC1B,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/rpc/writer.d.ts

@@ -0,0 +1,34 @@
+import type { ServerFrame } from "./protocol.js";
+/** The subset of a Node Writable the writer needs. `process.stdout` satisfies
+ * it; tests inject an in-memory sink. */
+export interface ByteSink {
+    write(chunk: string): boolean;
+    once(event: "drain", listener: () => void): void;
+}
+export interface WriterOptions {
+    /** Frames; past this the writer warns (once per stall episode) to stderr. */
+    highWaterMark?: number;
+    /** Sink for the high-water warning (defaults to a `process.stderr` write). */
+    warn?: (message: string) => void;
+}
+export declare class BoundedNdjsonWriter<T = ServerFrame> {
+    private readonly sink;
+    private readonly opts;
+    private readonly queue;
+    private draining;
+    private closed;
+    private warnedHighWater;
+    private readonly flushWaiters;
+    constructor(sink: ByteSink, opts?: WriterOptions);
+    /** Serialise + enqueue a frame. Synchronous (callable from a sync bus
+     * handler); the async drain loop does the actual writing. The type param
+     * lets the bespoke transport keep `ServerFrame` (the default) while the M3
+     * ACP transport enqueues JSON-RPC messages through the SAME bounded queue. */
+    enqueue(frame: T): void;
+    private drain;
+    /** Resolves once the queue has fully drained (or the writer is closed). */
+    flush(): Promise<void>;
+    /** Stop accepting + draining frames (transport closing). */
+    close(): void;
+}
+//# sourceMappingURL=writer.d.ts.map

package/dist/rpc/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/rpc/writer.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;yCACyC;AACzC,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAID,qBAAa,mBAAmB,CAAC,CAAC,GAAG,WAAW;IAQ5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;gBAGnC,IAAI,EAAE,QAAQ,EACd,IAAI,GAAE,aAAkB;IAG3C;;;kFAG8E;IAC9E,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;YAaT,KAAK;IA2BnB,2EAA2E;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,4DAA4D;IAC5D,KAAK,IAAI,IAAI;CAMd"}

package/dist/rpc/writer.js

@@ -0,0 +1,85 @@
+// Single bounded FIFO writer (codex C4 + Round-1 S1). Every outbound frame
+// goes through one ordered queue, so a `response` / `request_permission` can
+// never overtake a queued `assistant_delta`, and the drain loop respects the
+// sink's backpressure (`write()` → false → await "drain"). Fixes the
+// sync-unawaited-write flaw in pi/oh-my-pi. Never drops a frame; a stalled
+// client grows the in-memory queue and trips a re-armable stderr warning past
+// a high-water mark (no silent cap).
+const DEFAULT_HIGH_WATER = 10_000;
+export class BoundedNdjsonWriter {
+    sink;
+    opts;
+    queue = [];
+    draining = false;
+    closed = false;
+    warnedHighWater = false;
+    flushWaiters = [];
+    constructor(sink, opts = {}) {
+        this.sink = sink;
+        this.opts = opts;
+    }
+    /** Serialise + enqueue a frame. Synchronous (callable from a sync bus
+     * handler); the async drain loop does the actual writing. The type param
+     * lets the bespoke transport keep `ServerFrame` (the default) while the M3
+     * ACP transport enqueues JSON-RPC messages through the SAME bounded queue. */
+    enqueue(frame) {
+        if (this.closed)
+            return;
+        this.queue.push(JSON.stringify(frame) + "\n");
+        const hwm = this.opts.highWaterMark ?? DEFAULT_HIGH_WATER;
+        if (this.queue.length > hwm && !this.warnedHighWater) {
+            this.warnedHighWater = true;
+            (this.opts.warn ?? defaultWarn)(`rpc: outbound queue exceeded ${hwm} frames — client may be stalled; not dropping`);
+        }
+        void this.drain();
+    }
+    async drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            while (this.queue.length > 0 && !this.closed) {
+                const line = this.queue.shift();
+                let ok;
+                try {
+                    ok = this.sink.write(line);
+                }
+                catch {
+                    // EPIPE / sink gone — stop writing, drop the rest cleanly.
+                    this.closed = true;
+                    this.queue.length = 0;
+                    break;
+                }
+                if (!ok && !this.closed) {
+                    await new Promise((resolve) => this.sink.once("drain", resolve));
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+            if (this.queue.length === 0)
+                this.warnedHighWater = false; // re-arm
+            const waiters = this.flushWaiters.splice(0);
+            for (const w of waiters)
+                w();
+        }
+    }
+    /** Resolves once the queue has fully drained (or the writer is closed). */
+    async flush() {
+        if (this.closed || (this.queue.length === 0 && !this.draining))
+            return;
+        await new Promise((resolve) => this.flushWaiters.push(resolve));
+    }
+    /** Stop accepting + draining frames (transport closing). */
+    close() {
+        this.closed = true;
+        this.queue.length = 0;
+        const waiters = this.flushWaiters.splice(0);
+        for (const w of waiters)
+            w();
+    }
+}
+function defaultWarn(message) {
+    process.stderr.write(message + "\n");
+}
+//# sourceMappingURL=writer.js.map

package/dist/rpc/writer.js.map

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

package/dist/serve/acp-session-host.d.ts

@@ -0,0 +1,120 @@
+/**
+ * (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 { type EngineHost } from "../rpc/index.js";
+import { type ReplayHubOptions } from "./replay-hub.js";
+import { type ServerSocket } from "./ws-transport.js";
+export interface AcpSessionHostOptions {
+    host: EngineHost;
+    agent: {
+        name: string;
+        version: string;
+    };
+    /** Auto-approve every tool permission (trusted automation). Default false. */
+    autoApprove?: boolean;
+    /** stderr-style sink for routed `log` events + writer diagnostics. */
+    logSink?: (line: string) => void;
+    /** Replay ring depth (frames). Default {@link ReplayHub}'s. */
+    ring?: ReplayHubOptions;
+    /** (v21 M4 §5) Enable the single-controller lease. Default false ⇒ fan-out
+     *  (any paired device drives; the engine serializes turns via AGENT_BUSY). */
+    controllerLease?: boolean;
+}
+export interface AcpAttachment {
+    /** Per-attach fencing token (forward-compat; not enforced on the M3 WS — the
+     *  fan-out has no exclusive lock to fence). */
+    epoch: number;
+    /** Remove this socket from the fan-out. Idempotent; does NOT end the session. */
+    detach(): void;
+}
+export declare class AcpSessionHost {
+    private readonly hub;
+    private readonly queue;
+    private readonly driver;
+    private readonly host;
+    private readonly done;
+    private epochCounter;
+    private shuttingDown;
+    private readonly leaseEnabled;
+    private holder;
+    private controlEpoch;
+    /** clientId → socket, for TARGETED lease replies (not_controller / ack). */
+    private readonly socketsByClient;
+    constructor(opts: AcpSessionHostOptions);
+    /**
+     * 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: ServerSocket, lastSeq: number, clientId?: string): AcpAttachment;
+    /**
+     * 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: string, fromClientId?: string): void;
+    /** 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). */
+    private handleQuery;
+    /**
+     * 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.
+     */
+    private gate;
+    /** Broadcast the current lease state to every socket (stamped + fanned out). */
+    private broadcastControlState;
+    /** Send a single frame to ONE client (targeted; not fanned out, not stamped). */
+    private replyTo;
+    get headSeq(): number;
+    get socketCount(): number;
+    get busy(): boolean;
+    /** Current lease holder (clientId) or null. Exposed for tests/diagnostics. */
+    get controllerHolder(): string | null;
+    /** End the persistent queue → `run` returns → graceful driver shutdown. */
+    shutdown(): Promise<number>;
+}
+//# sourceMappingURL=acp-session-host.d.ts.map

package/dist/serve/acp-session-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-session-host.d.ts","sourceRoot":"","sources":["../../src/serve/acp-session-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAWpE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;kFAC8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B;mDAC+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAS;IAG7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAAK;IACzB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;gBAEvD,IAAI,EAAE,qBAAqB;IAoBvC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa;IAwC/E;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IAkBpD;;;mDAG+C;YACjC,WAAW;IASzB;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAuCZ,gFAAgF;IAChF,OAAO,CAAC,qBAAqB;IAK7B,iFAAiF;IACjF,OAAO,CAAC,OAAO;IAKf,IAAI,OAAO,IAAI,MAAM,CAEpB;IACD,IAAI,WAAW,IAAI,MAAM,CAExB;IACD,IAAI,IAAI,IAAI,OAAO,CAElB;IACD,8EAA8E;IAC9E,IAAI,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEpC;IAED,2EAA2E;IACrE,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;CAOlC"}