antechamber 0.1.0 → 0.2.0

package/dist/pi-rpc.js

@@ -11,11 +11,52 @@ import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
 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;
+/**
+ * `compact` answers only when the summary is written. OmO bounds one compaction by
+ * its SUMMARIZATION_MAX_DURATION_CAP_MS (30 min); the generic 60 s budget gave up
+ * long before a large session finished, leaving the run orphaned.
+ */
+export const COMPACT_RPC_TIMEOUT_MS = 31 * 60_000;
+const MAX_JSONL_FRAME_BYTES = 64 * 1024 * 1024;
+export class UpstreamProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UpstreamProtocolError";
+    }
+}
 const PROCESS_KILL_GRACE_MS = 5_000;
+// Linux /proc. Any read failure (gone, no permission, no /proc) means the identity cannot be
+// verified, and an unverifiable process is never signalled: fail closed.
+const procTable = {
+    identity(pid) {
+        let stat;
+        try {
+            stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+        return { pid, group: Number(fields[2]), start: fields[19] ?? "" };
+    },
+    groupMembers(group) {
+        let names;
+        try {
+            names = readdirSync("/proc");
+        }
+        catch {
+            return [];
+        }
+        return names
+            .filter((name) => /^\d+$/.test(name))
+            .flatMap((name) => procTable.identity(Number(name)) ?? [])
+            .filter((member) => member.group === group);
+    },
+};
 export class PiRpcClient extends EventEmitter {
     options;
     proc;
@@ -69,6 +110,9 @@ export class PiRpcClient extends EventEmitter {
         this.proc.stderr.on("data", (chunk) => {
             this.stderrTail = (this.stderrTail + chunk.toString()).slice(-8192);
         });
+        this.proc.stdin?.on("error", (error) => {
+            this.closeForTransportFailure(error);
+        });
         this.proc.stdout.on("data", (chunk) => {
             const text = typeof chunk === "string" ? chunk : this.decoder.write(chunk);
             this.buffer += text;
@@ -80,11 +124,10 @@ export class PiRpcClient extends EventEmitter {
             this.buffer += text;
             this.bufferBytes += Buffer.byteLength(text);
             this.drain();
-            this.failAll(new Error("pi process closed stdout"));
+            this.closeForTransportFailure(new Error("pi process closed stdout"));
         });
         this.proc.on("error", (err) => {
-            this.closed = true;
-            this.failAll(err);
+            this.closeForTransportFailure(err);
         });
         this.proc.on("exit", (code, signal) => {
             this.closed = true;
@@ -126,9 +169,23 @@ export class PiRpcClient extends EventEmitter {
         this.proc.stdout?.destroy();
         if (this.proc.pid === undefined)
             this.proc.kill("SIGKILL");
-        else
+        else if (!this.reaped())
             process.kill(-this.proc.pid, "SIGKILL");
     }
+    /** Node has reaped the leader, so its PID (and group ID) may already belong to another process. */
+    reaped() {
+        return this.proc.exitCode !== null || this.proc.signalCode !== null;
+    }
+    closeForTransportFailure(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.failAll(error);
+        void this.dispose().catch((disposeError) => {
+            const message = disposeError instanceof Error ? disposeError.message : String(disposeError);
+            console.error(`[pi-rpc] failed to dispose after transport failure: ${message}`);
+        });
+    }
     handleLine(line) {
         let value;
         try {
@@ -152,6 +209,12 @@ export class PiRpcClient extends EventEmitter {
                 pending?.reject(error);
                 return;
             }
+            if (pending !== undefined && pending.command !== msg.command) {
+                const error = new Error(`pi returned mismatched RPC response command "${msg.command}" for pending command "${pending.command}"`);
+                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 }
                 : {
@@ -200,30 +263,31 @@ export class PiRpcClient extends EventEmitter {
         if (signal?.aborted)
             return Promise.reject(signal.reason);
         const id = randomUUID();
+        const expectedCommand = String(cmd.type);
         return new Promise((resolve, reject) => {
             const cleanup = () => {
                 clearTimeout(timer);
                 signal?.removeEventListener("abort", onAbort);
                 this.pending.delete(id);
             };
-            const onAbort = () => {
+            const rejectCommand = (reason) => {
                 cleanup();
-                reject(signal?.reason);
+                reject(reason);
+            };
+            const onAbort = () => {
+                rejectCommand(signal?.reason);
             };
             const timer = setTimeout(() => {
-                cleanup();
-                reject(new Error(`pi command "${cmd.type}" timed out after ${timeoutMs}ms`));
+                this.closeForTransportFailure(new Error(`pi command "${expectedCommand}" timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             this.pending.set(id, {
+                command: expectedCommand,
                 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);
-                },
+                reject: rejectCommand,
             });
             signal?.addEventListener("abort", onAbort, { once: true });
             this.write({ ...cmd, id });
@@ -240,45 +304,54 @@ export class PiRpcClient extends EventEmitter {
         this.closed = true;
         this.failAll(new Error("pi process disposed"));
         const pid = this.proc.pid;
-        if (pid === undefined)
+        if (pid === undefined || this.reaped())
             return;
         const clock = this.options.clock ?? systemClock;
-        const signalGroup = (signal) => {
+        const table = this.options.processTable ?? procTable;
+        const signal = (target, sig) => {
             try {
-                process.kill(-pid, signal);
-                return true;
+                process.kill(target, sig);
             }
             catch (error) {
                 if (error instanceof Error && "code" in error && error.code === "ESRCH")
-                    return false;
+                    return;
                 throw error;
             }
         };
+        // Until Node reaps the leader its PID, and therefore the group ID, cannot be reused, so group
+        // signals are safe only before "exit". Record the members now; after the leader exits, a
+        // grandchild is killed only when its PID still has the same group and start time.
+        const owned = table.groupMembers(pid).filter((member) => member.pid !== pid);
+        const survivors = () => owned
+            .filter((member) => {
+            const now = table.identity(member.pid);
+            return now !== undefined && now.group === member.group && now.start === member.start;
+        })
+            .map((member) => member.pid);
         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))
+                if (survivors().length === 0)
                     finish();
             };
             this.proc.once("exit", onExit);
             const timer = clock.setTimeout(() => {
-                signalGroup("SIGKILL");
-                if (exited)
-                    finish();
-                else
+                if (!this.reaped()) {
+                    signal(-pid, "SIGKILL");
+                    this.proc.off("exit", onExit);
                     this.proc.once("exit", finish);
+                    return;
+                }
+                for (const member of survivors())
+                    signal(member, "SIGKILL");
+                finish();
             }, PROCESS_KILL_GRACE_MS);
-            const alive = signalGroup("SIGTERM");
+            signal(-pid, "SIGTERM");
             this.proc.stdin?.end();
-            if (!alive && exited)
-                finish();
         });
         return this.disposing;
     }

package/dist/prompt-parts.d.ts

@@ -0,0 +1,40 @@
+import type { OCPromptPart } from "./types.js";
+export declare function isPromptPart(value: unknown): value is OCPromptPart;
+export declare function parsePromptParts(value: unknown): OCPromptPart[];
+/** OpenChamber 2.x attachments (`files: [{uri, name?}]`, `agents: [{name, mention?}]`) as prompt parts. */
+export declare function v2PromptParts(text: string, files: unknown, agents: unknown): OCPromptPart[];
+/** The v2 wire form of a prompt's attachments, as OpenChamber 2.x projects them back into parts. */
+export declare function v2PromptAttachments(parts: readonly OCPromptPart[]): {
+    files?: {
+        mime: string;
+        name?: string;
+        source: {
+            type: string;
+            uri: string;
+        };
+    }[];
+    agents?: {
+        name: string;
+        mention?: {
+            start: number;
+            end: number;
+            text: string;
+        };
+    }[];
+};
+/** Native custom-message type for no-reply context (v2 synthetic, v1 noReply) admitted without a turn. */
+export declare const CONTEXT_MESSAGE_TYPE = "antechamber.context";
+/** The OpenChamber message id of a native context entry, if the entry is one. */
+export declare function contextMessageID(entry: {
+    type?: string;
+    customType?: string;
+    details?: unknown;
+}): string | undefined;
+export declare function nativePromptInput(text: string, parts: readonly OCPromptPart[]): {
+    message: string;
+    images?: {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }[];
+};

package/dist/prompt-parts.js

@@ -0,0 +1,157 @@
+/** Lossless user parts on the wire, adapted to the native text/images RPC. */
+import { RequestBodyError } from "./http.js";
+export function isPromptPart(value) {
+    if (typeof value !== "object" || value === null || !("type" in value))
+        return false;
+    if ("id" in value && typeof value.id !== "string")
+        return false;
+    switch (value.type) {
+        case "text":
+            return ("text" in value &&
+                typeof value.text === "string" &&
+                (!("synthetic" in value) || typeof value.synthetic === "boolean"));
+        case "file":
+            return ("mime" in value &&
+                typeof value.mime === "string" &&
+                "url" in value &&
+                typeof value.url === "string" &&
+                (!("filename" in value) || typeof value.filename === "string"));
+        case "agent":
+            return ("name" in value &&
+                typeof value.name === "string" &&
+                (!("source" in value) ||
+                    (typeof value.source === "object" &&
+                        value.source !== null &&
+                        "value" in value.source &&
+                        typeof value.source.value === "string" &&
+                        "start" in value.source &&
+                        typeof value.source.start === "number" &&
+                        "end" in value.source &&
+                        typeof value.source.end === "number")));
+        default:
+            return false;
+    }
+}
+export function parsePromptParts(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || !value.every(isPromptPart))
+        throw new RequestBodyError(400, "parts must contain supported text, file, or agent inputs");
+    return value;
+}
+function plainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** OpenChamber 2.x attachments (`files: [{uri, name?}]`, `agents: [{name, mention?}]`) as prompt parts. */
+export function v2PromptParts(text, files, agents) {
+    const parts = text === "" ? [] : [{ type: "text", text }];
+    if (files !== undefined) {
+        if (!Array.isArray(files))
+            throw new RequestBodyError(400, "files must be an array");
+        for (const file of files) {
+            if (!plainRecord(file) ||
+                typeof file.uri !== "string" ||
+                (file.name !== undefined && typeof file.name !== "string"))
+                throw new RequestBodyError(400, "files must contain {uri, name?} attachments");
+            // v2 carries no MIME type; an inline data URI still names its own.
+            const mime = /^data:([^;,]+)/.exec(file.uri)?.[1] ?? "application/octet-stream";
+            parts.push({
+                type: "file",
+                mime,
+                url: file.uri,
+                ...(typeof file.name === "string" ? { filename: file.name } : {}),
+            });
+        }
+    }
+    if (agents !== undefined) {
+        if (!Array.isArray(agents))
+            throw new RequestBodyError(400, "agents must be an array");
+        for (const agent of agents) {
+            const mention = plainRecord(agent) ? agent.mention : undefined;
+            if (!plainRecord(agent) ||
+                typeof agent.name !== "string" ||
+                (mention !== undefined &&
+                    (!plainRecord(mention) ||
+                        typeof mention.start !== "number" ||
+                        typeof mention.end !== "number" ||
+                        typeof mention.text !== "string")))
+                throw new RequestBodyError(400, "agents must contain {name, mention?} references");
+            parts.push({
+                type: "agent",
+                name: agent.name,
+                ...(plainRecord(mention) &&
+                    typeof mention.text === "string" &&
+                    typeof mention.start === "number" &&
+                    typeof mention.end === "number"
+                    ? { source: { value: mention.text, start: mention.start, end: mention.end } }
+                    : {}),
+            });
+        }
+    }
+    return parts;
+}
+/** The v2 wire form of a prompt's attachments, as OpenChamber 2.x projects them back into parts. */
+export function v2PromptAttachments(parts) {
+    const files = parts.flatMap((part) => part.type === "file"
+        ? [
+            {
+                mime: part.mime,
+                ...(part.filename !== undefined ? { name: part.filename } : {}),
+                source: { type: "uri", uri: part.url },
+            },
+        ]
+        : []);
+    const agents = parts.flatMap((part) => part.type === "agent"
+        ? [
+            {
+                name: part.name,
+                ...(part.source !== undefined
+                    ? { mention: { start: part.source.start, end: part.source.end, text: part.source.value } }
+                    : {}),
+            },
+        ]
+        : []);
+    return { ...(files.length > 0 ? { files } : {}), ...(agents.length > 0 ? { agents } : {}) };
+}
+/** Native custom-message type for no-reply context (v2 synthetic, v1 noReply) admitted without a turn. */
+export const CONTEXT_MESSAGE_TYPE = "antechamber.context";
+/** The OpenChamber message id of a native context entry, if the entry is one. */
+export function contextMessageID(entry) {
+    if (entry.type !== "custom_message" || entry.customType !== CONTEXT_MESSAGE_TYPE || !plainRecord(entry.details))
+        return undefined;
+    return typeof entry.details.messageID === "string" ? entry.details.messageID : undefined;
+}
+export function nativePromptInput(text, parts) {
+    const chunks = [text];
+    const images = [];
+    for (const part of parts) {
+        switch (part.type) {
+            case "text":
+                break;
+            case "agent":
+                chunks.push(`@${part.name}`);
+                break;
+            case "file": {
+                const data = /^data:([^;,]*)(;base64)?,([\s\S]*)$/.exec(part.url);
+                if (data !== null) {
+                    const content = data[2]
+                        ? Buffer.from(data[3] ?? "", "base64")
+                        : Buffer.from(decodeURIComponent(data[3] ?? ""));
+                    if (part.mime.startsWith("image/"))
+                        images.push({ type: "image", data: content.toString("base64"), mimeType: part.mime });
+                    else if (part.mime.startsWith("text/"))
+                        chunks.push(`${part.filename ?? "attachment"} (${part.mime}):\n${content.toString("utf8")}`);
+                    else
+                        throw new RequestBodyError(400, `Unsupported inline attachment MIME type: ${part.mime}`);
+                }
+                else {
+                    // Native RPC has no generic FilePart; retain the reference in model
+                    // context so the agent can read the selected workspace file.
+                    chunks.push(JSON.stringify({ filename: part.filename, mime: part.mime, url: part.url }));
+                }
+                break;
+            }
+        }
+    }
+    return { message: chunks.join("\n\n"), ...(images.length > 0 ? { images } : {}) };
+}

package/dist/route-services.d.ts

@@ -3,7 +3,7 @@ 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 { OCEvent, OCMessageWithParts, OCPromptPart } from "./types.js";
 import type { TodoUpdated } from "./todo-bridge.js";
 export interface RouteServices {
     readonly sessions: SessionManager;
@@ -15,6 +15,8 @@ export interface RouteServices {
 }
 export declare const OPENCODE_COMPAT_VERSION: string | null;
 export declare function numberParam(value: string | null): number | undefined;
+export declare function sessionDirectory(value: unknown): string;
+export declare function sessionMetadata(value: unknown): Record<string, unknown> | undefined;
 /** v2 prompt bodies carry `model:{providerID, id|modelID}`; adapt to OCModelRef. */
 export declare function modelRefFromBody(model: {
     providerID?: string;
@@ -23,4 +25,45 @@ export declare function modelRefFromBody(model: {
     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;
+export declare function promptAsync(services: RouteServices, session: ManagedSession, text: string, model?: ModelSelection, noReply?: boolean, messageID?: string, delivery?: "steer" | "queue", parts?: readonly OCPromptPart[], metadata?: Record<string, unknown>): void;
+export type ShellRouteResult = {
+    kind: "input";
+} | {
+    kind: "busy";
+} | {
+    kind: "error";
+    message: string;
+} | {
+    kind: "success";
+    message: OCMessageWithParts;
+};
+/** Run a shell command consistently while leaving each API version to shape its response envelope. */
+export declare function runSessionShell(services: RouteServices, session: ManagedSession, body: unknown): Promise<ShellRouteResult>;
+export type SlashRouteResult = {
+    kind: "input";
+} | {
+    kind: "success";
+    message: OCMessageWithParts | undefined;
+};
+/** Parse and dispatch slash commands once for both protocol versions. */
+export declare function runSessionSlash(services: RouteServices, sessionID: string, body: unknown): Promise<SlashRouteResult>;
+export declare function agentDescriptors(services: RouteServices): Promise<{
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+    variant?: string;
+    name: string;
+    description: string;
+    mode: string;
+    hidden: boolean;
+    options: {};
+    native: boolean;
+    permission: {
+        permission: string;
+        pattern: string;
+        action: string;
+    }[];
+    prompt: string;
+    temperature: number;
+}[]>;

package/dist/route-services.js

@@ -1,5 +1,9 @@
 /** Shared services and prompt/model adaptation for both API versions. */
-import { announceSessionError } from "./session-commands.js";
+import { statSync } from "node:fs";
+import { RequestBodyError } from "./http.js";
+import { getAgentName, getExposedAgentNames } from "./agent-name.js";
+import { agentDefaults } from "./catalog.js";
+import { announceSessionError, parseShellCommand, parseSlashCommand, runShellCommand, runSlashCommand, } 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
@@ -15,6 +19,27 @@ export function numberParam(value) {
     const n = Number(value);
     return Number.isFinite(n) && n >= 0 ? n : undefined;
 }
+export function sessionDirectory(value) {
+    if (typeof value !== "string" || value.trim() === "" || value.includes("\0"))
+        throw new RequestBodyError(400, "directory must be a nonempty path");
+    try {
+        if (!statSync(value).isDirectory())
+            throw new RequestBodyError(400, "directory does not exist or is not a directory");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+            throw new RequestBodyError(400, "directory does not exist or is not a directory");
+        throw error;
+    }
+    return value;
+}
+export function sessionMetadata(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new RequestBodyError(400, "metadata must be an object");
+    return Object.fromEntries(Object.entries(value));
+}
 /** v2 prompt bodies carry `model:{providerID, id|modelID}`; adapt to OCModelRef. */
 export function modelRefFromBody(model, variant) {
     if (!model || typeof model.providerID !== "string")
@@ -26,8 +51,50 @@ export function modelRefFromBody(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) => {
+export function promptAsync(services, session, text, model, noReply = false, messageID, delivery = "steer", parts, metadata) {
+    void services.sessions
+        .prompt(session.info.id, text, model, noReply, messageID, delivery, parts, metadata)
+        .catch((error) => {
         announceSessionError({ sessions: services.sessions, session, emit: services.broadcast }, error instanceof Error ? error.name : "UnknownError", error instanceof Error ? error.message : String(error));
     });
 }
+/** Run a shell command consistently while leaving each API version to shape its response envelope. */
+export async function runSessionShell(services, session, body) {
+    const command = parseShellCommand(body);
+    if (command === undefined)
+        return { kind: "input" };
+    if (session.status.type !== "idle")
+        return { kind: "busy" };
+    const result = await runShellCommand({
+        sessions: services.sessions,
+        session,
+        command,
+        emit: services.broadcast,
+    });
+    return result.kind === "error" ? result : { kind: "success", message: result.message };
+}
+/** Parse and dispatch slash commands once for both protocol versions. */
+export async function runSessionSlash(services, sessionID, body) {
+    const input = parseSlashCommand(body);
+    if (input === undefined)
+        return { kind: "input" };
+    return { kind: "success", message: await runSlashCommand(services.sessions, sessionID, input) };
+}
+export async function agentDescriptors(services) {
+    const piName = getAgentName();
+    const defaults = agentDefaults(await services.catalog());
+    return getExposedAgentNames().map((name) => ({
+        name,
+        description: name === piName
+            ? `${piName} (pi coding agent via antechamber)`
+            : `${name} — ${piName} (pi coding agent via antechamber)`,
+        mode: "primary",
+        hidden: name === "build" && piName !== "build",
+        options: {},
+        native: true,
+        permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        prompt: "",
+        temperature: 0,
+        ...defaults,
+    }));
+}