@wrenai/genbi 0.0.4 → 0.0.6

package/dist-server/server/runtime-host/codex-session.js

@@ -0,0 +1,492 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { CODEX_BASELINE_VERSION } from "./codex-compatibility.js";
+import { codexAccountUpdatedSchema, codexRateLimitsUpdatedSchema, codexThreadSchema, codexTurnSchema, parseCodexEvent } from "./codex-events.js";
+import { CodexRpcClient, CodexRpcError, object } from "./codex-rpc.js";
+import { isDeepStrictEqual } from "node:util";
+const sizeSchema = z.object({ cols: z.number().int().min(1).max(500), rows: z.number().int().min(1).max(500) }).strict();
+const commandSchema = z.object({
+    command: z.array(z.string().max(65_536).refine((v) => !v.includes("\0"))).min(1).max(256),
+    tty: z.boolean().default(false), size: sizeSchema.optional(),
+    timeoutMs: z.number().int().min(1).max(300_000).default(30_000),
+}).strict().refine((v) => !v.size || v.tty);
+const commandResultSchema = z.object({ exitCode: z.number().int(), stdout: z.literal(""), stderr: z.literal("") });
+function parse(schema, value) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new CodexRpcError("protocol");
+    return result.data;
+}
+// Config/read expands optional TOML fields into nulls. Null is absence, not
+// permission; every non-null profile/network/environment field must match.
+function configured(value) {
+    if (Array.isArray(value))
+        return value.map(configured);
+    if (object(value))
+        return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== null).map(([key, item]) => [key, configured(item)]));
+    return value;
+}
+/**
+ * Internal protocol driver. It has no spawn, readiness or certification grant;
+ * only CodexAppServerBackend may compose it with a real process. Tests can use
+ * an in-memory transport without creating an activation path.
+ */
+export class CodexSession {
+    policy;
+    revalidate;
+    emit;
+    rpc;
+    tools;
+    toolsClosing;
+    threadId;
+    startingThread = false;
+    threadEventId;
+    turn;
+    commands = new Map();
+    ready = false;
+    accountResponseReceived = false;
+    closed = false;
+    closePromise;
+    constructor(transport, policy, revalidate, emit, tools) {
+        this.policy = policy;
+        this.revalidate = revalidate;
+        this.emit = emit;
+        this.tools = tools ? Object.freeze({ accountEmail: tools.accountEmail, definitions: structuredClone(tools.definitions),
+            assertCurrent: tools.assertCurrent.bind(tools), call: tools.call.bind(tools), close: tools.close.bind(tools) }) : undefined;
+        this.rpc = new CodexRpcClient(transport, ({ method, params }) => {
+            if (method === "account/rateLimits/updated") {
+                parse(codexRateLimitsUpdatedSchema, params);
+                return;
+            } // host-only telemetry
+            if (method === "account/updated") {
+                if (this.accountResponseReceived || !this.tools)
+                    this.protocolFailure();
+                parse(codexAccountUpdatedSchema, params);
+                return; // account/read still pins identity before ready; never project auth to UI
+            }
+            this.receive(parseCodexEvent(method, params));
+        }, 1_048_576, this.tools ? (request) => this.callTool(request.method, request.params) : undefined);
+        this.rpc.onFailure((error) => {
+            this.closed = true;
+            if (this.turn)
+                this.settleTurn(undefined, error);
+            this.commands.clear();
+            void this.closeTools().catch(() => { });
+        });
+    }
+    static async connect(transport, policy, revalidate, emit, created, tools) {
+        const session = new CodexSession(transport, policy, revalidate, emit, tools);
+        try {
+            created?.(session);
+            session.tools?.assertCurrent();
+            const initialized = parse(z.object({ codexHome: z.literal(policy.codexHome), platformFamily: z.literal("unix"), platformOs: z.literal("macos"), userAgent: z.string().min(1) }), await session.rpc.request("initialize", {
+                clientInfo: { name: "genbi", version: "0.0.4" }, capabilities: { experimentalApi: true },
+            }));
+            if (!initialized.userAgent.includes(`/${CODEX_BASELINE_VERSION} `))
+                throw new CodexRpcError("protocol");
+            session.rpc.notify("initialized", {});
+            const effective = await session.rpc.request("config/read", { cwd: policy.cwd, includeLayers: false });
+            if (!object(effective) || !object(effective.config))
+                throw new CodexRpcError("protocol");
+            for (const [key, expected] of Object.entries(policy.configuration)) {
+                const actual = effective.config[key];
+                if (key === "features") {
+                    if (!object(actual) || !object(expected) || Object.entries(expected).some(([name, value]) => !isDeepStrictEqual(actual[name], value)))
+                        throw new CodexRpcError("protocol");
+                }
+                else if (!isDeepStrictEqual(configured(actual), configured(expected)))
+                    throw new CodexRpcError("protocol");
+            }
+            const profiles = parse(z.object({ data: z.array(z.object({ id: z.string(), allowed: z.boolean() })), nextCursor: z.null().optional() }), await session.rpc.request("permissionProfile/list", { cwd: policy.cwd }));
+            if (profiles.data.filter((p) => p.id === policy.profile && p.allowed).length !== 1)
+                throw new CodexRpcError("permission");
+            if (session.closed)
+                throw new CodexRpcError("closed");
+            if (session.tools) {
+                parse(z.object({ requiresOpenaiAuth: z.literal(true), account: z.object({ type: z.literal("chatgpt"), email: z.literal(session.tools.accountEmail) }) }), await session.rpc.request("account/read", { refreshToken: false }, 10_000, undefined, () => { session.accountResponseReceived = true; }));
+                if (session.closed)
+                    throw new CodexRpcError("protocol");
+                session.tools.assertCurrent();
+            }
+            session.ready = true;
+            return session;
+        }
+        catch (error) {
+            await session.close();
+            throw error;
+        }
+    }
+    check() {
+        if (this.closed || !this.ready)
+            throw new CodexRpcError("closed");
+        try {
+            this.revalidate();
+            this.tools?.assertCurrent();
+        }
+        catch {
+            this.rpc.fail("protocol");
+            throw new CodexRpcError("protocol");
+        }
+    }
+    protocolFailure() { this.rpc.fail("protocol"); throw new CodexRpcError("protocol"); }
+    async startThread() {
+        this.check();
+        if (this.threadId || this.startingThread)
+            throw new CodexRpcError("protocol");
+        this.startingThread = true;
+        try {
+            const result = parse(z.object({ thread: codexThreadSchema }), await this.rpc.request("thread/start", {
+                cwd: this.policy.cwd, permissions: this.policy.profile, approvalPolicy: "never", ephemeral: true,
+                ...(this.policy.model ? { model: this.policy.model } : {}),
+                runtimeWorkspaceRoots: this.tools ? [] : [this.policy.cwd], environments: [], dynamicTools: this.tools?.definitions ?? [],
+                ...(this.tools ? { baseInstructions: "Use the provided tool for the selected analytical request. Component steps, data access and persistence are owned by the host.", developerInstructions: "" } : {}),
+                allowProviderModelFallback: false,
+            }));
+            this.validateThread(result.thread);
+            if (this.threadEventId && result.thread.id !== this.threadEventId)
+                this.protocolFailure();
+            this.threadId = result.thread.id;
+            return result.thread.id;
+        }
+        catch (error) {
+            this.rpc.fail("protocol");
+            throw error;
+        }
+        finally {
+            this.startingThread = false;
+        }
+    }
+    validateThread(thread) {
+        if (thread.cwd !== this.policy.cwd || thread.cliVersion !== CODEX_BASELINE_VERSION || !thread.ephemeral)
+            this.protocolFailure();
+    }
+    /** Completes on turn/completed, not the immediate turn/start acknowledgement. */
+    async runTurn(text, options = {}) {
+        this.check();
+        if (!this.threadId || this.turn || typeof text !== "string" || text.length === 0 || Buffer.byteLength(text) > 262_144)
+            throw new CodexRpcError("protocol");
+        const timeoutMs = options.timeoutMs ?? 120_000;
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)
+            throw new CodexRpcError("protocol");
+        if (options.signal?.aborted) {
+            await this.close();
+            throw new CodexRpcError("cancelled");
+        }
+        const abort = () => this.rpc.fail("cancelled");
+        let active;
+        let releaseTools;
+        const ready = new Promise((resolve) => { releaseTools = resolve; });
+        const completion = new Promise((resolve, reject) => {
+            active = { resolve, reject, started: false, early: [], earlyBytes: 0, items: new Map(),
+                toolsAbort: new AbortController(), calls: new Set(), pendingTools: 0, ready, releaseTools,
+                timer: setTimeout(() => this.rpc.fail("timeout"), timeoutMs),
+                detach: () => options.signal?.removeEventListener("abort", abort),
+            };
+        });
+        this.turn = active;
+        // Install rejection handling before a synchronous transport can fail.
+        void completion.catch(() => { });
+        options.signal?.addEventListener("abort", abort, { once: true });
+        try {
+            const result = parse(z.object({ turn: codexTurnSchema }), await this.rpc.request("turn/start", {
+                threadId: this.threadId, input: [{ type: "text", text }], cwd: this.policy.cwd,
+                permissions: this.policy.profile, approvalPolicy: "never", runtimeWorkspaceRoots: this.tools ? [] : [this.policy.cwd], environments: [],
+            }, Math.min(timeoutMs, 10_000)));
+            if (this.turn !== active || result.turn.status !== "inProgress")
+                this.protocolFailure();
+            active.id = result.turn.id;
+            const queued = active.early;
+            active.early = [];
+            active.earlyBytes = 0;
+            for (const event of queued)
+                this.receive(event);
+            active.releaseTools();
+            return await completion;
+        }
+        catch (error) {
+            this.rpc.fail(error instanceof CodexRpcError ? error.reason : "protocol");
+            await this.close();
+            throw error instanceof CodexRpcError ? error : new CodexRpcError("protocol");
+        }
+    }
+    async steerTurn(text, expectedTurnId) {
+        this.check();
+        const active = this.turn;
+        if (!active?.id || active.id !== expectedTurnId || active.interruptRequested || !text.trim() || Buffer.byteLength(text) > 262_144)
+            throw new CodexRpcError("protocol");
+        const result = parse(z.object({ turnId: z.literal(active.id) }).strict(), await this.rpc.request("turn/steer", {
+            threadId: this.threadId, expectedTurnId, input: [{ type: "text", text }],
+        }));
+        if (this.turn !== active || active.interruptRequested)
+            throw new CodexRpcError("protocol");
+        return result;
+    }
+    async interruptTurn() {
+        this.check();
+        const active = this.turn;
+        if (!active?.id)
+            throw new CodexRpcError("protocol");
+        try {
+            active.interruptRequested = true;
+            active.toolsAbort.abort();
+            parse(z.object({}).strict(), await this.rpc.request("turn/interrupt", { threadId: this.threadId, turnId: active.id }, 10_000));
+            // An ack is not completion. Bound how long a silent peer may keep working.
+            if (this.turn === active) {
+                clearTimeout(active.timer);
+                active.timer = setTimeout(() => this.rpc.fail("timeout"), 10_000);
+            }
+        }
+        catch {
+            await this.close();
+            throw new CodexRpcError("protocol");
+        }
+    }
+    startCommand(input, signal) {
+        this.check();
+        if (this.tools)
+            throw new CodexRpcError("permission");
+        const command = parse(commandSchema, input);
+        if (this.commands.size >= 16 || !command.command[0])
+            throw new CodexRpcError("protocol");
+        const id = randomUUID();
+        const state = { tty: command.tty, stdinClosed: false, bytes: 0 };
+        this.commands.set(id, state);
+        const completed = this.rpc.request("command/exec", {
+            ...command, processId: id, cwd: this.policy.cwd, permissionProfile: this.policy.profile,
+            env: this.policy.commandEnvironment, streamStdin: true, streamStdoutStderr: true, outputBytesCap: 262_144,
+        }, command.timeoutMs + 3_000, signal).then((value) => {
+            const result = parse(commandResultSchema, value);
+            this.commands.delete(id);
+            return { exitCode: result.exitCode };
+        }).catch(async (error) => {
+            this.rpc.fail(error instanceof CodexRpcError ? error.reason : "protocol");
+            await this.close();
+            throw error instanceof CodexRpcError ? error : new CodexRpcError("protocol");
+        });
+        void completed.catch(() => { });
+        const control = async (method, params) => {
+            this.check();
+            if (!this.commands.has(id))
+                throw new CodexRpcError("closed");
+            try {
+                parse(z.object({}).strict(), await this.rpc.request(method, { processId: id, ...params }, 2_000));
+            }
+            catch (error) {
+                this.rpc.fail("protocol");
+                await this.close();
+                throw error;
+            }
+        };
+        return Object.freeze({ id, completed,
+            write: async (bytes, closeStdin = false) => {
+                if (!(bytes instanceof Uint8Array) || bytes.byteLength > 65_536 || state.stdinClosed || typeof closeStdin !== "boolean")
+                    throw new CodexRpcError("protocol");
+                if (closeStdin)
+                    state.stdinClosed = true;
+                await control("command/exec/write", { deltaBase64: Buffer.from(bytes).toString("base64"), closeStdin });
+            },
+            resize: async (size) => {
+                if (!state.tty)
+                    throw new CodexRpcError("protocol");
+                await control("command/exec/resize", { size: parse(sizeSchema, size) });
+            },
+            terminate: async () => {
+                await control("command/exec/terminate", {});
+                let timer;
+                try {
+                    await Promise.race([completed, new Promise((_, reject) => { timer = setTimeout(() => { this.rpc.fail("timeout"); reject(new CodexRpcError("timeout")); }, 2_000); })]);
+                }
+                catch (error) {
+                    await this.close();
+                    throw error;
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+        });
+    }
+    settleTurn(value, error) {
+        const active = this.turn;
+        if (!active)
+            return;
+        if (value?.status === "interrupted" && active.pendingTools) {
+            active.toolsAbort.abort();
+            void active.toolFinished.then(() => { if (this.turn === active)
+                this.settleTurn(value); });
+            return;
+        }
+        this.turn = undefined;
+        clearTimeout(active.timer);
+        active.detach();
+        active.toolsAbort.abort();
+        active.releaseTools();
+        if (value)
+            active.resolve(value);
+        else
+            active.reject(error);
+    }
+    receive(event) {
+        if (this.closed)
+            return;
+        if (event.method === "remoteControl/status/changed")
+            return; // validated disabled; never forward host identity
+        if (event.method === "command/exec/outputDelta") {
+            const command = this.commands.get(event.params.processId);
+            if (!command || (command.tty && event.params.stream !== "stdout"))
+                this.protocolFailure();
+            command.bytes += Buffer.from(event.params.deltaBase64, "base64").byteLength;
+            if (command.bytes > 524_288)
+                this.protocolFailure();
+            this.emit(event);
+            return;
+        }
+        if (event.method === "thread/started") {
+            this.validateThread(event.params.thread);
+            if (this.threadEventId || (!this.startingThread && this.threadId !== event.params.thread.id))
+                this.protocolFailure();
+            this.threadEventId = event.params.thread.id;
+            return;
+        }
+        if (!this.threadId || event.params.threadId !== this.threadId)
+            this.protocolFailure();
+        if (event.method === "warning") {
+            const features = this.policy.configuration.features;
+            if (!this.tools || !object(features) || features.code_mode_host !== false || features.code_mode !== false)
+                this.protocolFailure();
+            return; // validated disabled capability; never forward raw vendor warnings
+        }
+        if (event.method === "thread/status/changed") {
+            this.emit(event);
+            return;
+        }
+        const active = this.turn;
+        if (!active)
+            this.protocolFailure();
+        if (this.tools && "item" in event.params && !["userMessage", "agentMessage", "reasoning", "dynamicToolCall", "contextCompaction"].includes(event.params.item.type))
+            this.protocolFailure();
+        if (!active.id) {
+            active.earlyBytes += Buffer.byteLength(JSON.stringify(event));
+            if (active.early.length >= 128 || active.earlyBytes > 1_048_576)
+                this.protocolFailure();
+            active.early.push(event);
+            return;
+        }
+        const turnId = "turn" in event.params ? event.params.turn.id : event.params.turnId;
+        if (turnId !== active.id)
+            this.protocolFailure();
+        if (event.method === "turn/started") {
+            if (active.started || event.params.turn.status !== "inProgress")
+                this.protocolFailure();
+            active.started = true;
+        }
+        else if (event.method === "turn/completed") {
+            // Full integrity validation before terminal output is emitted or settled.
+            this.check();
+            if (event.params.turn.status === "inProgress" || (active.pendingTools && event.params.turn.status === "completed"))
+                this.protocolFailure();
+            if (this.tools && event.params.turn.status === "completed") {
+                const returned = new Set();
+                for (const item of event.params.turn.items) {
+                    const observed = active.items.get(item.id);
+                    if (!observed?.completed || observed.type !== item.type || !isDeepStrictEqual(observed.item, item) || returned.has(item.id))
+                        this.protocolFailure();
+                    returned.add(item.id);
+                }
+                if (!active.started || [...active.items.values()].some((item) => !item.completed)
+                    || ((event.params.turn.itemsView ?? "full") === "full" && returned.size !== active.items.size))
+                    this.protocolFailure();
+                if (event.params.turn.itemsView === "summary" || event.params.turn.itemsView === "notLoaded") {
+                    const complete = { ...event.params.turn, itemsView: "full", items: [...active.items.values()].map((item) => item.item) };
+                    this.emit({ ...event, params: { ...event.params, turn: complete } });
+                    this.settleTurn(complete);
+                    return;
+                }
+            }
+            this.emit(event);
+            this.settleTurn(event.params.turn);
+            return;
+        }
+        else if (event.method === "item/started") {
+            const received = event.params.item;
+            if (received.type === "dynamicToolCall" && (!this.tools || !this.tools.definitions.some((tool) => tool.name === received.tool)))
+                this.protocolFailure();
+            if (active.items.has(event.params.item.id) || active.items.size >= 512)
+                this.protocolFailure();
+            active.items.set(event.params.item.id, { type: event.params.item.type, completed: false });
+        }
+        else if (event.method === "item/completed") {
+            const item = active.items.get(event.params.item.id);
+            if (!item || item.completed || item.type !== event.params.item.type)
+                this.protocolFailure();
+            if (event.params.item.type === "dynamicToolCall" && (!active.calls.has(event.params.item.id) || active.pendingTools))
+                this.protocolFailure();
+            item.completed = true;
+            item.item = structuredClone(event.params.item);
+        }
+        else if ("itemId" in event.params) {
+            const item = active.items.get(event.params.itemId);
+            if (!item || item.completed)
+                this.protocolFailure();
+        }
+        this.emit(event);
+    }
+    async callTool(method, params) {
+        this.check();
+        const call = parse(z.object({ threadId: z.string().min(1), turnId: z.string().min(1), callId: z.string().min(1).max(256),
+            tool: z.string().min(1), arguments: z.unknown(), namespace: z.null().optional() }).strict(), params);
+        const active = this.turn;
+        if (method !== "item/tool/call" || !this.tools || !active || call.threadId !== this.threadId
+            || !this.tools.definitions.some((tool) => tool.name === call.tool) || active.calls.has(call.callId)
+            || active.calls.size >= 32 || active.pendingTools || Buffer.byteLength(JSON.stringify(call.arguments) ?? "") > 65_536)
+            this.protocolFailure();
+        active.calls.add(call.callId);
+        active.pendingTools++;
+        let finished;
+        active.toolFinished = new Promise((resolve) => { finished = resolve; });
+        try {
+            await active.ready;
+            this.check();
+            active.toolsAbort.signal.throwIfAborted();
+            const item = active.items.get(call.callId);
+            if (this.turn !== active || call.turnId !== active.id || !active.started || item?.type !== "dynamicToolCall" || item.completed)
+                this.protocolFailure();
+            const result = await this.tools.call(call.tool, call.arguments, `${active.id}:${call.callId}`, active.toolsAbort.signal);
+            this.check();
+            active.toolsAbort.signal.throwIfAborted();
+            if (this.turn !== active)
+                this.protocolFailure();
+            const text = JSON.stringify(result);
+            if (text === undefined || Buffer.byteLength(text) > 1_048_000)
+                this.protocolFailure();
+            return { contentItems: [{ type: "inputText", text }], success: true };
+        }
+        catch (error) {
+            // A requested cancellation is a failed tool result, not malformed RPC.
+            // Recheck the session scope and integrity before keeping it reusable.
+            if (!active.interruptRequested || !active.toolsAbort.signal.aborted || error !== active.toolsAbort.signal.reason)
+                throw error;
+            this.check();
+            return { contentItems: [{ type: "inputText", text: "Operation cancelled." }], success: false };
+        }
+        finally {
+            active.pendingTools--;
+            finished();
+        }
+    }
+    closeTools() {
+        return this.toolsClosing ??= Promise.resolve().then(() => this.tools?.close()).catch(() => { throw new CodexRpcError("cleanup"); });
+    }
+    /** Disconnect and BFF shutdown use the same bounded, connection-owned close. */
+    onFailure(listener) {
+        return this.rpc.onFailure(listener);
+    }
+    close() {
+        this.closed = true;
+        this.closePromise ??= Promise.allSettled([this.rpc.close(), this.closeTools()]).then((results) => {
+            if (results.some((result) => result.status === "rejected"))
+                throw new CodexRpcError("cleanup");
+        });
+        return this.closePromise;
+    }
+}

package/dist-server/server/runtime-host/codex-terminal-protocol.d.ts

@@ -0,0 +1,35 @@
+import type { CodexConversation } from "./codex-conversation.js";
+/**
+ * Protocol presented to the official remote TUI, not an app-server proxy.
+ * Only text submission and interruption reach the governed conversation.
+ * Config, filesystem, shell, auth, plugin and cross-thread mutations never do.
+ * Catalogs describe this host's restricted surface, not the operator's account.
+ */
+export declare class CodexTerminalProtocol {
+    private readonly conversation;
+    private readonly scope;
+    private readonly send;
+    private readonly assertActive;
+    private readonly onReady;
+    private initialized;
+    private acknowledged;
+    private started;
+    private submitted;
+    private attachment;
+    private pendingTurn;
+    private activeTurn;
+    private closed;
+    private readonly createdAt;
+    private readonly ids;
+    constructor(conversation: CodexConversation, scope: {
+        cwd: string;
+        clientHome: string;
+        model: string;
+    }, send: (message: unknown) => void, assertActive: () => void, onReady?: () => void);
+    close(): void;
+    private thread;
+    private result;
+    private error;
+    private event;
+    receive(value: unknown): Promise<void>;
+}