antechamber 0.0.0-stage → 0.1.0

package/dist/pi-rpc.js

@@ -0,0 +1,285 @@
+/**
+ * pi RPC subprocess client.
+ *
+ * Speaks pi's headless JSONL protocol (`pi --mode rpc`): commands go to stdin,
+ * responses and events come back on stdout. Framing is strict LF-only JSONL —
+ * pi's docs warn that generic line readers (Node `readline`) also split on
+ * U+2028/U+2029, which are legal inside JSON strings, so we split on "\n"
+ * ourselves and only strip a single trailing "\r".
+ */
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { systemClock } from "./lifecycle.js";
+import { agentBinary, envSetting } from "./config.js";
+export const RPC_COMMAND_TIMEOUT_MS = 60_000;
+export const MAX_JSONL_FRAME_BYTES = 64 * 1024 * 1024;
+const PROCESS_KILL_GRACE_MS = 5_000;
+export class PiRpcClient extends EventEmitter {
+    options;
+    proc;
+    buffer = "";
+    bufferBytes = 0;
+    decoder = new StringDecoder("utf8");
+    pending = new Map();
+    closed = false;
+    stderrTail = "";
+    disposing;
+    get pid() {
+        return this.proc.pid;
+    }
+    get isBusy() {
+        return this.pending.size > 0;
+    }
+    onEvent(listener) {
+        return super.on("event", listener);
+    }
+    onExit(listener) {
+        return super.on("exit", listener);
+    }
+    onExtensionUI(listener) {
+        return super.on("extension_ui_request", listener);
+    }
+    constructor(options) {
+        super();
+        this.options = options;
+        const extraArgs = envSetting("PI_ARGS")?.trim().split(/\s+/).filter(Boolean) ?? [];
+        const args = ["--mode", "rpc", ...(options.args ?? []), ...extraArgs];
+        const capabilities = [
+            ...new Set([
+                ...(process.env.OMO_RPC_CLIENT_CAPABILITIES ?? "").split(","),
+                ...(process.env.SENPI_RPC_CLIENT_CAPABILITIES ?? "").split(","),
+                "auto_title_sessions",
+                "question",
+            ]
+                .map((value) => value.trim())
+                .filter(Boolean)),
+        ].join(",");
+        this.proc = spawn(options.piBinary ?? agentBinary(), args, {
+            cwd: options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                OMO_RPC_CLIENT_CAPABILITIES: capabilities,
+                SENPI_RPC_CLIENT_CAPABILITIES: capabilities,
+            },
+            detached: true,
+        });
+        this.proc.stderr.on("data", (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk.toString()).slice(-8192);
+        });
+        this.proc.stdout.on("data", (chunk) => {
+            const text = typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+            this.buffer += text;
+            this.bufferBytes += Buffer.byteLength(text);
+            this.drain();
+        });
+        this.proc.stdout.on("end", () => {
+            const text = this.decoder.end();
+            this.buffer += text;
+            this.bufferBytes += Buffer.byteLength(text);
+            this.drain();
+            this.failAll(new Error("pi process closed stdout"));
+        });
+        this.proc.on("error", (err) => {
+            this.closed = true;
+            this.failAll(err);
+        });
+        this.proc.on("exit", (code, signal) => {
+            this.closed = true;
+            console.error(`[pi-rpc] process exited code=${code} signal=${signal}` +
+                (envSetting("DEBUG") && this.stderrTail ? `\n[pi-rpc] stderr tail:\n${this.stderrTail}` : ""));
+            this.failAll(new Error(`pi exited (code=${code} signal=${signal})`));
+            this.emit("exit", code, signal);
+        });
+    }
+    drain() {
+        for (;;) {
+            const idx = this.buffer.indexOf("\n");
+            if (idx === -1) {
+                if (this.bufferBytes > MAX_JSONL_FRAME_BYTES)
+                    this.frameOverflow();
+                return;
+            }
+            let line = this.buffer.slice(0, idx);
+            const frameBytes = Buffer.byteLength(line);
+            if (frameBytes > MAX_JSONL_FRAME_BYTES) {
+                this.frameOverflow();
+                return;
+            }
+            this.buffer = this.buffer.slice(idx + 1);
+            this.bufferBytes -= frameBytes + 1;
+            if (line.endsWith("\r"))
+                line = line.slice(0, -1);
+            if (line.length === 0)
+                continue;
+            this.handleLine(line);
+        }
+    }
+    frameOverflow() {
+        const error = new Error(`pi JSONL frame exceeded ${MAX_JSONL_FRAME_BYTES} bytes`);
+        this.closed = true;
+        this.buffer = "";
+        this.bufferBytes = 0;
+        this.failAll(error);
+        this.proc.stdout?.destroy();
+        if (this.proc.pid === undefined)
+            this.proc.kill("SIGKILL");
+        else
+            process.kill(-this.proc.pid, "SIGKILL");
+    }
+    handleLine(line) {
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            // Non-JSON noise on stdout; ignore but keep going.
+            return;
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return;
+        const msg = value;
+        if (msg.type === "response") {
+            const pending = typeof msg.id === "string" ? this.pending.get(msg.id) : undefined;
+            if (typeof msg.id !== "string" ||
+                typeof msg.success !== "boolean" ||
+                typeof msg.command !== "string" ||
+                (msg.error !== undefined && typeof msg.error !== "string")) {
+                const error = new Error("pi returned a malformed RPC response");
+                console.error(`[pi-rpc] ${error.message}`);
+                pending?.reject(error);
+                return;
+            }
+            const response = msg.success
+                ? { type: "response", id: msg.id, command: msg.command, success: true, data: msg.data }
+                : {
+                    type: "response",
+                    id: msg.id,
+                    command: msg.command,
+                    success: false,
+                    ...(msg.error !== undefined ? { error: msg.error } : {}),
+                };
+            pending?.resolve(response);
+            return;
+        }
+        if (msg.type === "extension_ui_request") {
+            this.handleExtensionUI(msg);
+            return;
+        }
+        this.emit("event", msg);
+    }
+    handleExtensionUI(msg) {
+        const method = msg.method;
+        const id = msg.id;
+        if (!id || !method)
+            return;
+        const blocking = new Set(["select", "confirm", "input", "editor"]);
+        if (!blocking.has(method) && method !== "notify" && method !== "question")
+            return;
+        this.emit("extension_ui_request", msg);
+    }
+    respondExtensionUI(response) {
+        this.write(response);
+    }
+    write(obj) {
+        if (this.closed)
+            return;
+        this.proc.stdin.write(JSON.stringify(obj) + "\n");
+    }
+    failAll(err) {
+        for (const p of this.pending.values())
+            p.reject(err);
+        this.pending.clear();
+    }
+    /** Send a command and wait for its correlated response. */
+    command(cmd, timeoutMs = RPC_COMMAND_TIMEOUT_MS, signal, onDispatch) {
+        if (this.closed)
+            return Promise.reject(new Error("pi process is not running"));
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                this.pending.delete(id);
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(signal?.reason);
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`pi command "${cmd.type}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (r) => {
+                    cleanup();
+                    // The envelope is checked at the transport boundary; callers own data schemas.
+                    resolve(r.success ? { ...r, data: r.data } : r);
+                },
+                reject: (e) => {
+                    cleanup();
+                    reject(e);
+                },
+            });
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.write({ ...cmd, id });
+            onDispatch?.();
+        });
+    }
+    /** Fire-and-forget command (no response correlation). */
+    notify(cmd) {
+        this.write(cmd);
+    }
+    async dispose() {
+        if (this.disposing !== undefined)
+            return this.disposing;
+        this.closed = true;
+        this.failAll(new Error("pi process disposed"));
+        const pid = this.proc.pid;
+        if (pid === undefined)
+            return;
+        const clock = this.options.clock ?? systemClock;
+        const signalGroup = (signal) => {
+            try {
+                process.kill(-pid, signal);
+                return true;
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ESRCH")
+                    return false;
+                throw error;
+            }
+        };
+        this.disposing = new Promise((resolve) => {
+            let exited = this.proc.exitCode !== null || this.proc.signalCode !== null;
+            const finish = () => {
+                clock.clearTimeout(timer);
+                this.proc.off("exit", onExit);
+                resolve();
+            };
+            const onExit = () => {
+                exited = true;
+                // A grandchild may outlive pi. Keep the escalation armed for its group.
+                if (!signalGroup(0))
+                    finish();
+            };
+            this.proc.once("exit", onExit);
+            const timer = clock.setTimeout(() => {
+                signalGroup("SIGKILL");
+                if (exited)
+                    finish();
+                else
+                    this.proc.once("exit", finish);
+            }, PROCESS_KILL_GRACE_MS);
+            const alive = signalGroup("SIGTERM");
+            this.proc.stdin?.end();
+            if (!alive && exited)
+                finish();
+        });
+        return this.disposing;
+    }
+}

package/dist/pidfd.d.ts

@@ -0,0 +1,2 @@
+/** Shared by private-host teardown and doctor; no probing at module import. */
+export declare function findPidfdPython(env?: NodeJS.ProcessEnv, probe?: (binary: string, args: readonly string[]) => boolean): string | undefined;

package/dist/pidfd.js

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+import { delimiter, resolve } from "node:path";
+const pidfdProbe = String.raw `
+import os, selectors, signal
+fd = os.pidfd_open(os.getpid())
+try:
+    signal.pidfd_send_signal(fd, 0)
+    with selectors.DefaultSelector() as selector:
+        selector.register(fd, selectors.EVENT_READ)
+finally:
+    os.close(fd)
+`;
+/** Shared by private-host teardown and doctor; no probing at module import. */
+export function findPidfdPython(env = process.env, probe = (binary, args) => {
+    const result = spawnSync(binary, args, { stdio: "ignore", timeout: 1_000, killSignal: "SIGKILL", env });
+    return !result.error && result.status === 0;
+}) {
+    const candidates = new Set([
+        ...(env.PATH ?? "").split(delimiter).map((directory) => resolve(directory, "python3")),
+        "/bin/python3",
+        "/usr/bin/python3",
+    ]);
+    for (const binary of candidates) {
+        if (probe(binary, ["-I", "-c", pidfdProbe]))
+            return binary;
+    }
+    return undefined;
+}

package/dist/question-forms.d.ts

@@ -0,0 +1,30 @@
+import { type PendingQuestion } from "./approvals.js";
+export declare function questionFormID(id: string): string;
+export declare function toQuestionForm(card: PendingQuestion): {
+    id: string;
+    sessionID: string;
+    title: string;
+    metadata: Record<string, unknown>;
+    fields: ({
+        key: string;
+        type: string;
+        title: string;
+        description: string;
+        required: boolean;
+        options?: {
+            label: string;
+            description: string;
+            value: string;
+        }[];
+        custom?: boolean;
+    } | {
+        key: string;
+        type: string;
+        title: string;
+        required: boolean;
+    })[];
+};
+export declare function formQuestionAnswer(card: PendingQuestion, value: unknown): {
+    answers: string[][];
+    comment?: string;
+};

package/dist/question-forms.js

@@ -0,0 +1,46 @@
+import { ApprovalInputError } from "./approvals.js";
+export function questionFormID(id) {
+    return `frm_${id}`;
+}
+export function toQuestionForm(card) {
+    return {
+        id: questionFormID(card.id),
+        sessionID: card.sessionID,
+        title: card.questions.map((q) => q.header).join(" / "),
+        metadata: card.metadata ?? {},
+        fields: [
+            ...card.questions.map((q, index) => ({
+                key: card.questionIDs?.[index] ?? `q${index + 1}`,
+                type: q.multiple ? "multiselect" : "string",
+                title: q.header,
+                description: q.question,
+                required: false,
+                ...(q.options.length
+                    ? { options: q.options.map((o) => ({ value: o.label, ...o })), custom: q.custom !== false }
+                    : {}),
+            })),
+            ...(card.questionIDs ? [{ key: "comment", type: "string", title: "Comment", required: false }] : []),
+        ],
+    };
+}
+export function formQuestionAnswer(card, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new ApprovalInputError("answer must be an object");
+    const answer = Object.fromEntries(Object.entries(value));
+    const keys = card.questions.map((_, i) => card.questionIDs?.[i] ?? `q${i + 1}`);
+    if (Object.keys(answer).some((key) => !keys.includes(key) && !(card.questionIDs && key === "comment")))
+        throw new ApprovalInputError("unknown form field");
+    const answers = keys.map((key, i) => {
+        const v = answer[key];
+        if (v === undefined)
+            return [];
+        if (typeof v === "string")
+            return v === "" ? [] : [v];
+        if (card.questions[i]?.multiple && Array.isArray(v) && v.every((item) => typeof item === "string"))
+            return v;
+        throw new ApprovalInputError("form field answer must match its type");
+    });
+    if (answer.comment !== undefined && typeof answer.comment !== "string")
+        throw new ApprovalInputError("comment must be a string");
+    return { answers, ...(typeof answer.comment === "string" ? { comment: answer.comment } : {}) };
+}

package/dist/route-services.d.ts

@@ -0,0 +1,26 @@
+/** Shared services and prompt/model adaptation for both API versions. */
+import type { IncomingMessage } from "node:http";
+import type { SessionManager, ManagedSession } from "./sessions.js";
+import type { Catalog } from "./catalog.js";
+import type { ModelSelection } from "./thinking-levels.js";
+import type { OCEvent } from "./types.js";
+import type { TodoUpdated } from "./todo-bridge.js";
+export interface RouteServices {
+    readonly sessions: SessionManager;
+    readonly defaultDirectory: string;
+    readonly url: string;
+    readonly body: (req: IncomingMessage) => Promise<unknown>;
+    readonly catalog: () => Promise<Catalog>;
+    readonly broadcast: (directory: string, event: OCEvent | TodoUpdated) => void;
+}
+export declare const OPENCODE_COMPAT_VERSION: string | null;
+export declare function numberParam(value: string | null): number | undefined;
+/** v2 prompt bodies carry `model:{providerID, id|modelID}`; adapt to OCModelRef. */
+export declare function modelRefFromBody(model: {
+    providerID?: string;
+    id?: string;
+    modelID?: string;
+    variant?: string;
+} | undefined, variant?: string): ModelSelection | undefined;
+/** Both async APIs acknowledge admission; failures must reach SSE and history. */
+export declare function promptAsync(services: RouteServices, session: ManagedSession, text: string, model?: ModelSelection, noReply?: boolean, messageID?: string, delivery?: "steer" | "queue"): void;

package/dist/route-services.js

@@ -0,0 +1,33 @@
+/** Shared services and prompt/model adaptation for both API versions. */
+import { announceSessionError } from "./session-commands.js";
+import { envSetting } from "./config.js";
+// This connector is not opencode — it only implements an OpenCode API subset.
+// OpenChamber reads /global/health's `version` as the installed opencode version
+// and offers an update when it trails the latest release. Advertising the SDK
+// contract version (1.18.31) made every adapter profile look permanently
+// outdated, and the resulting "update" then failed with "Unknown installation
+// method". Report no version so upgrade-status returns available:null and the UI
+// shows no prompt. Set ANTECHAMBER_OPENCODE_COMPAT_VERSION to advertise one on purpose.
+export const OPENCODE_COMPAT_VERSION = envSetting("OPENCODE_COMPAT_VERSION")?.trim() || null;
+export function numberParam(value) {
+    if (value === null || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/** v2 prompt bodies carry `model:{providerID, id|modelID}`; adapt to OCModelRef. */
+export function modelRefFromBody(model, variant) {
+    if (!model || typeof model.providerID !== "string")
+        return undefined;
+    const modelID = typeof model.id === "string" ? model.id : typeof model.modelID === "string" ? model.modelID : undefined;
+    if (modelID === undefined)
+        return undefined;
+    const level = variant ?? model.variant;
+    return { providerID: model.providerID, modelID, ...(typeof level === "string" ? { variant: level } : {}) };
+}
+/** Both async APIs acknowledge admission; failures must reach SSE and history. */
+export function promptAsync(services, session, text, model, noReply = false, messageID, delivery = "steer") {
+    void services.sessions.prompt(session.info.id, text, model, noReply, messageID, delivery).catch((error) => {
+        announceSessionError({ sessions: services.sessions, session, emit: services.broadcast }, error instanceof Error ? error.name : "UnknownError", error instanceof Error ? error.message : String(error));
+    });
+}

package/dist/routes-v1.d.ts

@@ -0,0 +1,4 @@
+/** OpenCode v1 routes, using the services composed by AdapterServer. */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type RouteServices } from "./route-services.js";
+export declare function handleV1(services: RouteServices, req: IncomingMessage, res: ServerResponse, url: URL, path: string, method: string, directory: string): Promise<void>;