@wrenai/genbi 0.0.3 → 0.0.5

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

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { CodexRpcError } from "./codex-rpc.js";
+const id = z.string().min(1).max(256);
+const text = z.string().max(1_048_576);
+const itemBase = { id };
+const state = z.enum(["inProgress", "completed", "failed", "declined"]);
+// Explicit supported item projection: never forward opaque vendor objects or
+// error text. New tools/items require reviewed schema and policy support.
+export const codexItemSchema = z.discriminatedUnion("type", [
+    z.object({ ...itemBase, type: z.literal("userMessage"), content: z.array(z.object({ type: z.literal("text"), text })).max(128) }),
+    z.object({ ...itemBase, type: z.literal("agentMessage"), text }),
+    z.object({ ...itemBase, type: z.literal("plan"), text }),
+    z.object({ ...itemBase, type: z.literal("reasoning"), content: z.array(text).default([]), summary: z.array(text).default([]) }),
+    z.object({ ...itemBase, type: z.literal("commandExecution"), command: text, cwd: text, status: state, aggregatedOutput: text.nullish(), exitCode: z.number().int().nullish() }),
+    z.object({ ...itemBase, type: z.literal("fileChange"), status: state, changes: z.array(z.object({ path: text, diff: text, kind: z.discriminatedUnion("type", [z.object({ type: z.literal("add") }), z.object({ type: z.literal("delete") }), z.object({ type: z.literal("update"), move_path: text.nullish() })]) })) }),
+    z.object({ ...itemBase, type: z.literal("contextCompaction") }),
+    z.object({ ...itemBase, type: z.literal("dynamicToolCall"), tool: z.string().min(1).max(256), namespace: z.null().optional(), status: z.enum(["inProgress", "completed", "failed"]), success: z.boolean().nullable().optional() }),
+]);
+export const codexTurnSchema = z.object({ id, status: z.enum(["inProgress", "completed", "interrupted", "failed"]), items: z.array(codexItemSchema).max(512), itemsView: z.enum(["full", "summary", "notLoaded"]).optional() })
+    .refine((turn) => turn.itemsView !== "notLoaded" || turn.items.length === 0);
+export const codexThreadSchema = z.object({ id, cwd: text, cliVersion: z.string(), ephemeral: z.boolean() });
+const scope = { threadId: id, turnId: id };
+const scopedItem = { ...scope, itemId: id };
+const delta = z.object({ ...scopedItem, delta: text });
+const usage = z.object({ totalTokens: z.number().int().nonnegative(), inputTokens: z.number().int().nonnegative(), cachedInputTokens: z.number().int().nonnegative(), outputTokens: z.number().int().nonnegative(), reasoningOutputTokens: z.number().int().nonnegative() });
+export const codexAccountUpdatedSchema = z.object({ authMode: z.literal("chatgpt"), planType: z.string().min(1).max(128).nullable().optional() }).strict();
+const limitText = z.string().max(256).nullish();
+const limitWindow = z.object({ usedPercent: z.number().int(), windowDurationMins: z.number().int().nullish(), resetsAt: z.number().int().nullish() }).strict().nullish();
+export const codexRateLimitsUpdatedSchema = z.object({ rateLimits: z.object({
+        limitId: limitText, limitName: limitText, normalModelSlug: limitText, planType: limitText,
+        primary: limitWindow, secondary: limitWindow,
+        credits: z.object({ hasCredits: z.boolean(), unlimited: z.boolean(), balance: limitText }).strict().nullish(),
+        individualLimit: z.object({ limit: z.string().max(256), used: z.string().max(256), remainingPercent: z.number().int(), resetsAt: z.number().int() }).strict().nullish(),
+        spendControlReached: z.boolean().nullish(),
+        rateLimitReachedType: z.enum(["rate_limit_reached", "workspace_owner_credits_depleted", "workspace_member_credits_depleted", "workspace_owner_usage_limit_reached", "workspace_member_usage_limit_reached"]).nullish(),
+    }).strict() }).strict();
+export const codexDisabledCodeModeWarningSchema = z.object({ threadId: id, message: z.literal("Code Mode is unavailable because code-mode host is disabled. Code mode will fail closed; enable `features.code_mode_host` and install `codex-code-mode-host`.") }).strict();
+export const codexNotificationSchemas = {
+    "warning": codexDisabledCodeModeWarningSchema,
+    "remoteControl/status/changed": z.object({ status: z.literal("disabled"), installationId: text, serverName: text, environmentId: z.null().optional() }),
+    "thread/started": z.object({ thread: codexThreadSchema }),
+    "thread/status/changed": z.object({ threadId: id, status: z.discriminatedUnion("type", [z.object({ type: z.literal("idle") }), z.object({ type: z.literal("active"), activeFlags: z.array(z.enum(["waitingOnApproval", "waitingOnUserInput"])) })]) }),
+    "thread/tokenUsage/updated": z.object({ ...scope, tokenUsage: z.object({ total: usage, last: usage, modelContextWindow: z.number().int().nullish() }) }),
+    "turn/started": z.object({ threadId: id, turn: codexTurnSchema }),
+    "turn/completed": z.object({ threadId: id, turn: codexTurnSchema }),
+    "turn/diff/updated": z.object({ ...scope, diff: text }),
+    "turn/plan/updated": z.object({ ...scope, explanation: text.nullish(), plan: z.array(z.object({ step: text, status: z.enum(["pending", "inProgress", "completed"]) })) }),
+    "item/started": z.object({ ...scope, item: codexItemSchema }),
+    "item/completed": z.object({ ...scope, item: codexItemSchema }),
+    "item/agentMessage/delta": delta,
+    "item/commandExecution/outputDelta": delta,
+    "item/fileChange/outputDelta": delta,
+    "item/reasoning/summaryTextDelta": delta.extend({ summaryIndex: z.number().int().nonnegative() }),
+    "item/reasoning/textDelta": delta.extend({ contentIndex: z.number().int().nonnegative() }),
+    "item/reasoning/summaryPartAdded": z.object({ ...scopedItem, summaryIndex: z.number().int().nonnegative() }),
+    "command/exec/outputDelta": z.object({ processId: id, stream: z.enum(["stdout", "stderr"]), deltaBase64: text.refine((value) => Buffer.from(value, "base64").toString("base64") === value), capReached: z.boolean() }),
+};
+export function parseCodexEvent(method, params) {
+    if (!Object.hasOwn(codexNotificationSchemas, method))
+        throw new CodexRpcError("protocol");
+    const schema = codexNotificationSchemas[method];
+    const parsed = schema.safeParse(params);
+    if (!parsed.success)
+        throw new CodexRpcError("protocol");
+    return { method, params: parsed.data };
+}

package/dist-server/server/runtime-host/codex-policy.d.ts

@@ -0,0 +1,16 @@
+import { type NativeRuntimeSpec } from "../native-runtime-spec.js";
+import type { ManagedWrenRuntimeRecord } from "../managed-wren-runtime.js";
+import type { CodexWrenHome } from "../native-wren-home.js";
+export declare const CODEX_PERMISSION_PROFILE = "genbi-scoped";
+export interface CodexSessionPolicy {
+    readonly model?: string;
+    readonly cwd: string;
+    readonly codexHome: string;
+    readonly profile: typeof CODEX_PERMISSION_PROFILE;
+    readonly args: readonly string[];
+    readonly environment: Readonly<Record<string, string>>;
+    readonly commandEnvironment: Readonly<Record<string, string | null>>;
+    readonly configuration: Readonly<Record<string, unknown>>;
+}
+/** Pure, resolve-only policy construction from host-owned scope, never request JSON. */
+export declare function buildCodexSessionPolicy(spec: NativeRuntimeSpec, runtime: ManagedWrenRuntimeRecord, home: CodexWrenHome, directTools?: boolean, model?: string): CodexSessionPolicy;

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

@@ -0,0 +1,151 @@
+import { lstatSync, realpathSync, existsSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { assertNativeRuntimeSpec } from "../native-runtime-spec.js";
+import { CodexRpcError } from "./codex-rpc.js";
+import { codexComponentConfiguration } from "./codex-component-step.js";
+export const CODEX_PERMISSION_PROFILE = "genbi-scoped";
+const deny = () => { throw new CodexRpcError("protocol"); };
+const within = (root, target) => target === root || target.startsWith(root + path.sep);
+function canonical(value) {
+    if (!path.isAbsolute(value) || realpathSync(value) !== value || lstatSync(value).isSymbolicLink())
+        deny();
+    // Permission keys interpret globs and ~, so never treat these as literal paths.
+    if (/[\x00-\x1f*?\[\]{}~]/.test(value))
+        deny();
+    return value;
+}
+function privateDirectory(value) {
+    canonical(value);
+    const stat = lstatSync(value);
+    if (!stat.isDirectory() || (stat.mode & 0o777) !== 0o700)
+        deny();
+}
+function toml(value) {
+    if (typeof value === "string" || typeof value === "boolean" || typeof value === "number")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(toml).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)}=${toml(item)}`).join(",")}}`;
+    return deny();
+}
+/** Pure, resolve-only policy construction from host-owned scope, never request JSON. */
+export function buildCodexSessionPolicy(spec, runtime, home, directTools = false, model) {
+    assertNativeRuntimeSpec(spec);
+    if (spec.backend !== "codex-app-server" || spec.vendor !== "codex" || !spec.childEnvironment.CODEX_HOME || spec.mcp)
+        deny();
+    if (spec.executables.wren?.executable !== runtime.launcher || spec.executables.python?.executable !== runtime.venv_python)
+        deny();
+    if (spec.sessionWrenHome !== home.home || !home.assertActive || !home.active?.())
+        deny();
+    home.assertActive();
+    const codexHome = canonical(spec.childEnvironment.CODEX_HOME);
+    const cwd = canonical(spec.workspace);
+    const generation = canonical(runtime.generation_root);
+    privateDirectory(codexHome);
+    privateDirectory(spec.childEnvironment.HOME);
+    privateDirectory(home.home);
+    // Login belongs to the user. Never copy it or read its contents; require a
+    // dedicated externally authenticated home, outside every writable/read root.
+    if (codexHome === path.join(os.homedir(), ".codex") || spec.childEnvironment.HOME === os.homedir())
+        deny();
+    const auth = path.join(codexHome, "auth.json");
+    const authStat = lstatSync(auth);
+    if (!authStat.isFile() || authStat.isSymbolicLink() || (authStat.mode & 0o077) !== 0)
+        deny();
+    // No operator config, plugins, hooks, or project config may augment this
+    // backend. Auth and vendor-generated session state may remain in the home.
+    for (const name of ["config.toml", "requirements.toml", "AGENTS.md", "instructions.md", "hooks.json", "plugins"]) {
+        if (existsSync(path.join(codexHome, name)))
+            deny();
+    }
+    // Codex seeds its bundled .system skills during initialization. Permit only
+    // that namespace; user skills still cannot enter through the login home.
+    const skills = path.join(codexHome, "skills");
+    if (existsSync(skills)) {
+        canonical(skills);
+        if (!lstatSync(skills).isDirectory() || readdirSync(skills).some((name) => name !== ".system"))
+            deny();
+        if (existsSync(path.join(skills, ".system")))
+            canonical(path.join(skills, ".system"));
+    }
+    for (const root of [cwd, ...(spec.project ? [spec.project.path] : [])]) {
+        let current = root;
+        while (true) {
+            if (existsSync(path.join(current, ".codex")))
+                deny();
+            const parent = path.dirname(current);
+            if (current === parent)
+                break;
+            current = parent;
+        }
+    }
+    const readRoots = [...new Set([generation, ...spec.toolDirectories, ...(spec.project ? [spec.project.path] : []), ...home.dataRoots])].map(canonical);
+    if (within(cwd, generation) || within(generation, cwd) || within(cwd, codexHome) || within(codexHome, cwd))
+        deny();
+    for (const root of readRoots) {
+        if (root === path.parse(root).root || within(root, os.homedir()) || within(root, codexHome) || within(codexHome, root))
+            deny();
+    }
+    // Platform defaults include shared scratch directories. The certified vendor
+    // must enforce these exclusions even against those implicit grants; session
+    // workspace grants below remain explicit and more specific.
+    const filesystem = {
+        ":minimal": "read", "/private/tmp": "deny", "/private/var/tmp": "deny",
+    };
+    for (const root of readRoots)
+        filesystem[root] = "read";
+    filesystem[cwd] = "write";
+    // A selected Wren profile is readable, never editable by the agent. Narrow
+    // session secrets are deliberate; user/project .env remains protected.
+    filesystem[home.home] = "read";
+    filesystem[codexHome] = "deny";
+    filesystem[path.join(os.homedir(), ".ssh")] = "deny";
+    filesystem[path.join(os.homedir(), ".aws")] = "deny";
+    filesystem[path.join(os.homedir(), ".codex")] = "deny";
+    filesystem[path.join(os.homedir(), ".claude")] = "deny";
+    if (spec.project)
+        filesystem[path.join(spec.project.path, ".env")] = "deny";
+    filesystem[path.join(cwd, ".codex")] = "deny";
+    filesystem[path.join(cwd, ".git")] = "read";
+    const environment = {
+        PATH: spec.childEnvironment.PATH, HOME: spec.childEnvironment.HOME,
+        CODEX_HOME: codexHome, TERM: "xterm-256color", COLORTERM: "truecolor",
+        PYTHONNOUSERSITE: "1", PYTHONUTF8: "1", PYTHONDONTWRITEBYTECODE: "1",
+        WREN_HOME: home.home,
+        ...(spec.project ? { WREN_PROJECT_HOME: spec.project.path } : {}),
+    };
+    // App-server may read its login; commands receive neither its home variable
+    // nor any provider credentials. No ambient environment spread is used.
+    const { CODEX_HOME: _loginHome, ...shellEnvironment } = environment;
+    const config = directTools ? { ...codexComponentConfiguration(CODEX_PERMISSION_PROFILE) } : {
+        default_permissions: CODEX_PERMISSION_PROFILE,
+        permissions: { [CODEX_PERMISSION_PROFILE]: { filesystem, network: { enabled: false } } },
+        approval_policy: "never",
+        shell_environment_policy: { inherit: "none", set: shellEnvironment },
+        project_doc_max_bytes: 0,
+        project_root_markers: [], web_search: "disabled", mcp_servers: {},
+        features: Object.fromEntries([
+            "apps", "browser_use", "browser_use_external", "browser_use_full_cdp_access", "computer_use",
+            "code_mode_host", "code_mode", "code_mode_only", "hooks", "image_generation", "in_app_browser",
+            "multi_agent", "multi_agent_v2", "plugins", "remote_plugin", "plugin_sharing", "skill_mcp_dependency_install",
+            "skill_search", "tool_suggest", "workspace_dependencies", "request_permissions_tool", "exec_permission_approvals",
+            "guardian_approval", "guardianv2", "goals", "memories", "external_agent_memory_import", "realtime_conversation",
+            "shell_snapshot", "standalone_web_search",
+        ].map((name) => [name, false])),
+    };
+    if (model !== undefined) {
+        if (!model.trim() || model.length > 256)
+            deny();
+        config.model = model;
+    }
+    if (directTools) {
+        delete environment.WREN_HOME;
+        delete environment.WREN_PROJECT_HOME;
+    }
+    const args = Object.entries(config).flatMap(([key, value]) => ["-c", `${key}=${toml(value)}`]);
+    args.push("app-server", "--stdio", "--strict-config");
+    return Object.freeze({ ...(model ? { model } : {}), cwd, codexHome, profile: CODEX_PERMISSION_PROFILE, args: Object.freeze(args),
+        environment: Object.freeze(environment), commandEnvironment: Object.freeze(directTools ? {} : { ...shellEnvironment, CODEX_HOME: null }), configuration: Object.freeze(config) });
+}

package/dist-server/server/runtime-host/codex-process.d.ts

@@ -0,0 +1,8 @@
+import { type RpcTransport } from "./codex-rpc.js";
+/** Owned POSIX process group. Never accepts a PID from a vendor response. */
+export declare function spawnCodexTransport(input: {
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}): RpcTransport;

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

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { CodexRpcError } from "./codex-rpc.js";
+/** Owned POSIX process group. Never accepts a PID from a vendor response. */
+export function spawnCodexTransport(input) {
+    const child = spawn(input.executable, [...input.args], {
+        cwd: input.cwd, env: input.env, detached: true, stdio: ["pipe", "pipe", "pipe"],
+    });
+    let handlers;
+    let failed = false;
+    let ended = false;
+    let closing;
+    child.stderr.resume(); // drain without retaining secrets or model output
+    child.on("error", () => { failed = true; handlers?.error(); });
+    child.stdin.on("error", () => { failed = true; handlers?.error(); });
+    child.stdout.on("error", () => { failed = true; handlers?.error(); });
+    child.stdout.on("end", () => { ended = true; handlers?.end(); });
+    child.on("exit", () => { ended = true; handlers?.end(); });
+    const alive = () => {
+        if (!child.pid)
+            return false;
+        try {
+            process.kill(-child.pid, 0);
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ESRCH")
+                return false;
+            // macOS can briefly return EPERM while a terminated group is being
+            // reaped. It is NOT evidence of exit: keep polling to the deadline.
+            if (code === "EPERM")
+                return true;
+            throw error;
+        }
+    };
+    const signal = (value) => {
+        if (!child.pid)
+            return;
+        try {
+            process.kill(-child.pid, value);
+        }
+        catch (error) {
+            const code = error.code;
+            // A denied signal is never success; the bounded liveness check below
+            // still has to observe ESRCH or report incomplete cleanup.
+            if (code !== "ESRCH" && code !== "EPERM")
+                throw error;
+        }
+    };
+    const wait = async (milliseconds) => {
+        const deadline = performance.now() + milliseconds;
+        while (alive() && performance.now() < deadline)
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        return !alive();
+    };
+    return {
+        listen(value) {
+            if (handlers)
+                throw new CodexRpcError("transport");
+            handlers = value;
+            child.stdout.on("data", (chunk) => value.data(chunk));
+            if (failed)
+                value.error();
+            else if (ended)
+                value.end();
+        },
+        write(line) {
+            if (closing || failed || ended || child.stdin.destroyed || child.stdin.writableLength > 1_048_576)
+                throw new CodexRpcError("transport");
+            child.stdin.write(line);
+        },
+        close() {
+            closing ??= (async () => {
+                try {
+                    child.stdin.end();
+                    // Let the vendor's connection-close handler reap command/PTY groups
+                    // that are distinct from this group before escalating host signals.
+                    if (await wait(200))
+                        return;
+                    signal("SIGTERM");
+                    if (await wait(500))
+                        return;
+                    signal("SIGKILL");
+                    if (!(await wait(2_000)))
+                        throw new CodexRpcError("cleanup");
+                }
+                finally {
+                    child.stdin.destroy();
+                    child.stdout.destroy();
+                    child.stderr.destroy();
+                }
+            })();
+            return closing;
+        },
+    };
+}

package/dist-server/server/runtime-host/codex-rpc.d.ts

@@ -0,0 +1,47 @@
+/** Codex JSONL is JSON-RPC with the jsonrpc header omitted. No raw diagnostics. */
+export type RpcFailure = "protocol" | "closed" | "transport" | "timeout" | "cancelled" | "remote" | "cleanup" | "permission";
+export declare class CodexRpcError extends Error {
+    readonly reason: RpcFailure;
+    constructor(reason: RpcFailure);
+}
+export interface RpcTransport {
+    listen(handlers: {
+        data(chunk: Buffer): void;
+        end(): void;
+        error(): void;
+    }): void;
+    write(line: string): void;
+    /** Resolves only when owned processes are gone; rejects on incomplete cleanup. */
+    close(): Promise<void>;
+}
+export declare function object(value: unknown): value is Record<string, unknown>;
+export interface RpcNotification {
+    readonly method: string;
+    readonly params: unknown;
+}
+export declare class CodexRpcClient {
+    private readonly transport;
+    private readonly notification;
+    private readonly maxLineBytes;
+    /** Opt-in governed tools only. Existing session clients still reject all server requests. */
+    private readonly serverRequest?;
+    private buffer;
+    private nextId;
+    private pending;
+    private failure?;
+    private closing?;
+    private failureListeners;
+    private readonly serverIds;
+    private readonly serverTimers;
+    constructor(transport: RpcTransport, notification: (message: RpcNotification) => void, maxLineBytes?: number, 
+    /** Opt-in governed tools only. Existing session clients still reject all server requests. */
+    serverRequest?: ((request: RpcNotification) => Promise<unknown>) | undefined);
+    onFailure(listener: (error: CodexRpcError) => void): () => void;
+    request(method: string, params: unknown, timeoutMs?: number, signal?: AbortSignal, responseReceived?: () => void): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    private send;
+    private receive;
+    private handleLine;
+    fail(reason: RpcFailure): void;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,182 @@
+export class CodexRpcError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Codex RPC ${reason}`);
+        this.reason = reason;
+    }
+}
+export function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export class CodexRpcClient {
+    transport;
+    notification;
+    maxLineBytes;
+    serverRequest;
+    buffer = Buffer.alloc(0);
+    nextId = 1;
+    pending = new Map();
+    failure;
+    closing;
+    failureListeners = new Set();
+    serverIds = new Set();
+    serverTimers = new Set();
+    constructor(transport, notification, maxLineBytes = 1_048_576, 
+    /** Opt-in governed tools only. Existing session clients still reject all server requests. */
+    serverRequest) {
+        this.transport = transport;
+        this.notification = notification;
+        this.maxLineBytes = maxLineBytes;
+        this.serverRequest = serverRequest;
+        transport.listen({
+            data: (chunk) => this.receive(chunk),
+            end: () => this.fail("closed"),
+            error: () => this.fail("transport"),
+        });
+    }
+    onFailure(listener) {
+        if (this.failure)
+            listener(this.failure);
+        else
+            this.failureListeners.add(listener);
+        return () => this.failureListeners.delete(listener);
+    }
+    request(method, params, timeoutMs = 10_000, signal, responseReceived) {
+        if (this.failure)
+            return Promise.reject(this.failure);
+        if (this.pending.size >= 128) {
+            this.fail("protocol");
+            return Promise.reject(this.failure);
+        }
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 3_600_000)
+            return Promise.reject(new CodexRpcError("protocol"));
+        if (signal?.aborted) {
+            this.fail("cancelled");
+            return Promise.reject(this.failure);
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const abort = () => this.fail("cancelled");
+            const timer = setTimeout(() => this.fail("timeout"), timeoutMs);
+            // Registration must precede write, including an in-process synchronous peer.
+            this.pending.set(id, { resolve, reject, timer, ...(responseReceived ? { responseReceived } : {}), removeAbort: () => signal?.removeEventListener("abort", abort) });
+            signal?.addEventListener("abort", abort, { once: true });
+            this.send({ id, method, params });
+        });
+    }
+    notify(method, params) {
+        if (this.failure)
+            throw this.failure;
+        this.send({ method, params });
+        if (this.failure)
+            throw this.failure;
+    }
+    send(message) {
+        try {
+            const line = JSON.stringify(message) + "\n";
+            if (Buffer.byteLength(line) > this.maxLineBytes)
+                return this.fail("protocol");
+            this.transport.write(line);
+        }
+        catch {
+            this.fail("transport");
+        }
+    }
+    receive(chunk) {
+        if (this.failure)
+            return;
+        // Never retain more than one bounded frame; a chunk may contain many frames.
+        let offset = 0;
+        while (offset < chunk.length && !this.failure) {
+            const newline = chunk.indexOf(10, offset);
+            const end = newline < 0 ? chunk.length : newline;
+            if (this.buffer.length + end - offset > this.maxLineBytes)
+                return this.fail("protocol");
+            this.buffer = Buffer.concat([this.buffer, chunk.subarray(offset, end)]);
+            if (newline < 0)
+                return;
+            const line = this.buffer;
+            this.buffer = Buffer.alloc(0);
+            offset = newline + 1;
+            this.handleLine(line);
+        }
+    }
+    handleLine(line) {
+        try {
+            const message = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+            if (!object(message))
+                return this.fail("protocol");
+            if ("id" in message) {
+                if ("method" in message) {
+                    if (!this.serverRequest || typeof message.method !== "string" || !("params" in message) || "result" in message || "error" in message
+                        || !(Number.isSafeInteger(message.id) || (typeof message.id === "string" && message.id.length > 0 && message.id.length <= 256)))
+                        return this.fail("protocol");
+                    const key = JSON.stringify(message.id);
+                    if (this.serverIds.has(key) || this.serverIds.size >= 512)
+                        return this.fail("protocol");
+                    this.serverIds.add(key);
+                    const timer = setTimeout(() => this.fail("timeout"), 120_000);
+                    this.serverTimers.add(timer);
+                    void Promise.resolve().then(() => { if (this.failure)
+                        throw this.failure; return this.serverRequest({ method: message.method, params: message.params }); })
+                        .then((result) => { if (!this.failure)
+                        this.send({ id: message.id, result }); })
+                        .catch(() => this.fail("protocol")).finally(() => { clearTimeout(timer); this.serverTimers.delete(timer); });
+                    return;
+                }
+                if (!Number.isSafeInteger(message.id))
+                    return this.fail("protocol");
+                if (("result" in message) === ("error" in message))
+                    return this.fail("protocol");
+                const pending = this.pending.get(message.id);
+                if (!pending)
+                    return this.fail("protocol"); // duplicates and unknown/late ids
+                if ("error" in message) {
+                    if (!object(message.error) || !Number.isInteger(message.error.code) || typeof message.error.message !== "string")
+                        return this.fail("protocol");
+                    return this.fail("remote");
+                }
+                // Mark authority boundaries synchronously, before later frames in this buffer.
+                pending.responseReceived?.();
+                this.pending.delete(message.id);
+                clearTimeout(pending.timer);
+                pending.removeAbort();
+                pending.resolve(message.result);
+            }
+            else {
+                if (typeof message.method !== "string" || !("params" in message) || "result" in message || "error" in message)
+                    return this.fail("protocol");
+                this.notification({ method: message.method, params: message.params });
+            }
+        }
+        catch {
+            this.fail("protocol");
+        }
+    }
+    fail(reason) {
+        if (this.failure)
+            return;
+        this.failure = new CodexRpcError(reason);
+        this.buffer = Buffer.alloc(0);
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.removeAbort();
+            pending.reject(this.failure);
+        }
+        this.pending.clear();
+        for (const timer of this.serverTimers)
+            clearTimeout(timer);
+        this.serverTimers.clear();
+        this.closing = Promise.resolve().then(() => this.transport.close()).catch(() => { throw new CodexRpcError("cleanup"); });
+        // Failures remain observable through close(), without an unhandled rejection.
+        void this.closing.catch(() => { });
+        for (const listener of this.failureListeners) {
+            try {
+                listener(this.failure);
+            }
+            catch { /* no raw callback errors */ }
+        }
+        this.failureListeners.clear();
+    }
+    async close() { this.fail("closed"); await this.closing; }
+}

package/dist-server/server/runtime-host/codex-session.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { codexTurnSchema, type CodexEvent } from "./codex-events.js";
+import type { CodexSessionPolicy } from "./codex-policy.js";
+import { CodexRpcError, type RpcTransport } from "./codex-rpc.js";
+import type { CodexSessionTools } from "./codex-direct-tools.js";
+type Turn = z.infer<typeof codexTurnSchema>;
+declare const commandSchema: z.ZodObject<{
+    command: z.ZodArray<z.ZodString>;
+    tty: z.ZodDefault<z.ZodBoolean>;
+    size: z.ZodOptional<z.ZodObject<{
+        cols: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.core.$strict>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type CodexCommandInput = z.input<typeof commandSchema>;
+export interface CodexCommand {
+    readonly id: string;
+    readonly completed: Promise<{
+        exitCode: number;
+    }>;
+    write(bytes: Uint8Array, closeStdin?: boolean): Promise<void>;
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    terminate(): Promise<void>;
+}
+/**
+ * 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 declare class CodexSession {
+    private readonly policy;
+    private readonly revalidate;
+    private readonly emit;
+    private readonly rpc;
+    private readonly tools;
+    private toolsClosing?;
+    private threadId?;
+    private startingThread;
+    private threadEventId?;
+    private turn;
+    private commands;
+    private ready;
+    private accountResponseReceived;
+    private closed;
+    private closePromise?;
+    private constructor();
+    static connect(transport: RpcTransport, policy: CodexSessionPolicy, revalidate: () => void, emit: (event: CodexEvent) => void, created?: (session: CodexSession) => void, tools?: CodexSessionTools): Promise<CodexSession>;
+    private check;
+    private protocolFailure;
+    startThread(): Promise<string>;
+    private validateThread;
+    /** Completes on turn/completed, not the immediate turn/start acknowledgement. */
+    runTurn(text: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<Turn>;
+    steerTurn(text: string, expectedTurnId: string): Promise<{
+        turnId: string;
+    }>;
+    interruptTurn(): Promise<void>;
+    startCommand(input: CodexCommandInput, signal?: AbortSignal): CodexCommand;
+    private settleTurn;
+    private receive;
+    private callTool;
+    private closeTools;
+    /** Disconnect and BFF shutdown use the same bounded, connection-owned close. */
+    onFailure(listener: (error: CodexRpcError) => void): () => void;
+    close(): Promise<void>;
+}
+export {};