@wrenai/genbi 0.0.4 → 0.0.5

package/dist-server/server/runtime-host/codex-terminal-protocol.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import { CODEX_BASELINE_VERSION } from "./codex-compatibility.js";
+const request = z.object({ id: z.union([z.string().max(256), z.number().int()]).optional(), method: z.string().max(128), params: z.record(z.string(), z.unknown()).optional() }).strict();
+const input = z.array(z.object({ type: z.literal("text"), text: z.string().min(1).max(262_144), text_elements: z.array(z.unknown()).max(0).optional() }).strict()).min(1).max(16);
+const record = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/**
+ * 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 class CodexTerminalProtocol {
+    conversation;
+    scope;
+    send;
+    assertActive;
+    onReady;
+    initialized = false;
+    acknowledged = false;
+    started = false;
+    submitted = false;
+    attachment;
+    pendingTurn;
+    activeTurn;
+    closed = false;
+    createdAt = Math.floor(Date.now() / 1000);
+    ids = new Set();
+    constructor(conversation, scope, send, assertActive, onReady = () => { }) {
+        this.conversation = conversation;
+        this.scope = scope;
+        this.send = send;
+        this.assertActive = assertActive;
+        this.onReady = onReady;
+    }
+    close() { this.closed = true; this.attachment?.detach(); this.attachment = undefined; }
+    thread() {
+        const id = this.conversation.terminalThreadId();
+        return { id, sessionId: id, forkedFromId: null, parentThreadId: null, preview: "", ephemeral: true,
+            section: null, sectionEnteredAt: null, projectId: null, historyMode: "legacy", modelProvider: "openai", model: this.scope.model,
+            reasoningEffort: null, createdAt: this.createdAt, updatedAt: this.createdAt, recencyAt: this.createdAt,
+            status: { type: this.activeTurn ? "active" : "idle", ...(this.activeTurn ? { activeFlags: [] } : {}) }, path: null,
+            cwd: this.scope.cwd, cliVersion: CODEX_BASELINE_VERSION, originator: "genbi", source: "appServer", threadSource: "user",
+            agentNickname: null, agentRole: null, gitInfo: null, name: null, turns: [] };
+    }
+    result(id, result) { if (!this.closed)
+        this.send({ id, result }); }
+    error(id, message = "This operation is unavailable in the pinned GenBI session.") {
+        if (!this.closed)
+            this.send({ id, error: { code: -32600, message } });
+    }
+    event(frame) {
+        if (this.closed || frame.type !== "event")
+            return;
+        const event = structuredClone(frame.event);
+        if (event.method === "turn/started" && record(event.params.turn)) {
+            this.activeTurn = String(event.params.turn.id);
+            if (this.pendingTurn !== undefined) {
+                this.result(this.pendingTurn, { turn: terminalTurn(event.params.turn) });
+                this.pendingTurn = undefined;
+            }
+        }
+        if (record(event.params.turn))
+            event.params.turn = terminalTurn(event.params.turn);
+        if (record(event.params.item))
+            event.params.item = terminalItem(event.params.item);
+        this.send(event);
+        if (event.method === "turn/completed")
+            this.activeTurn = undefined;
+    }
+    async receive(value) {
+        const parsed = request.safeParse(value);
+        if (!parsed.success || this.closed)
+            throw new Error("Invalid terminal protocol message");
+        const { id, method, params = {} } = parsed.data;
+        if (method === "initialized" && id === undefined && this.initialized && !this.acknowledged) {
+            this.acknowledged = true;
+            return;
+        }
+        if (id === undefined)
+            throw new Error("Invalid terminal protocol notification");
+        if (this.ids.has(id) || this.ids.size >= 4096)
+            throw new Error("Duplicate or excessive terminal request");
+        this.ids.add(id);
+        try {
+            this.assertActive();
+            if (method === "initialize") {
+                if (this.initialized || !record(params.clientInfo) || params.clientInfo.name !== "codex-tui" || params.clientInfo.version !== CODEX_BASELINE_VERSION)
+                    throw new Error();
+                this.initialized = true;
+                this.result(id, { userAgent: `genbi/${CODEX_BASELINE_VERSION}`, codexHome: this.scope.clientHome, platformFamily: "unix", platformOs: "macos" });
+                return;
+            }
+            if (!this.acknowledged)
+                throw new Error();
+            // Every scoped request is confined to this process-owned thread/workspace.
+            if (params.threadId != null && params.threadId !== this.conversation.terminalThreadId())
+                throw new Error();
+            if (params.cwd != null && params.cwd !== this.scope.cwd)
+                throw new Error();
+            if (params.model != null && params.model !== this.scope.model)
+                throw new Error();
+            switch (method) {
+                case "account/read":
+                    this.result(id, { account: null, requiresOpenaiAuth: false });
+                    return; // login is owned by the host
+                case "config/read":
+                    this.result(id, { config: { model: this.scope.model, model_provider: "openai", approval_policy: "never", sandbox_mode: "read-only",
+                            web_search: "disabled", check_for_update_on_startup: false, project_doc_max_bytes: 0, project_root_markers: [],
+                            projects: { [this.scope.cwd]: { trust_level: "trusted" } }, features: { remote_control: false, hooks: false, plugins: false, apps: false, multi_agent: false },
+                            history: { persistence: "none" } }, origins: {}, layers: [] });
+                    return;
+                case "configRequirements/read":
+                    this.result(id, { requirements: { allowedApprovalPolicies: ["never"], allowedSandboxModes: ["read-only"], allowedWebSearchModes: ["disabled"] } });
+                    return;
+                case "model/list":
+                    this.result(id, { data: [{ id: this.scope.model, model: this.scope.model, displayName: this.scope.model,
+                                description: "GenBI session model", hidden: false, isDefault: true, upgrade: null, upgradeInfo: null,
+                                supportedReasoningEfforts: [], defaultReasoningEffort: "medium", inputModalities: ["text"], supportsPersonality: false }], nextCursor: null });
+                    return;
+                case "hooks/list":
+                    this.result(id, { data: [{ cwd: this.scope.cwd, hooks: [], warnings: [], errors: [] }] });
+                    return;
+                case "skills/list":
+                    this.result(id, { data: [{ cwd: this.scope.cwd, skills: [], errors: [] }] });
+                    return;
+                case "plugin/list":
+                    this.result(id, { marketplaces: [], marketplaceLoadErrors: [], featuredPluginIds: [] });
+                    return;
+                case "app/installed":
+                    this.result(id, { apps: [] });
+                    return;
+                case "mcpServerStatus/list":
+                    this.result(id, { data: [], nextCursor: null });
+                    return;
+                case "collaborationMode/list":
+                    this.result(id, { data: [] });
+                    return;
+                case "thread/loaded/list":
+                    this.result(id, { data: this.started ? [this.conversation.terminalThreadId()] : [], nextCursor: null });
+                    return;
+                case "thread/list":
+                    this.result(id, { data: [], nextCursor: null, backwardsCursor: null });
+                    return;
+                case "thread/read":
+                    if (!this.started || params.includeTurns === true)
+                        throw new Error();
+                    this.result(id, { thread: this.thread() });
+                    return;
+                case "thread/turns/list":
+                    if (!this.started || this.submitted)
+                        throw new Error();
+                    this.result(id, { data: [], nextCursor: null, backwardsCursor: null });
+                    return;
+                case "thread/start": {
+                    if (this.started)
+                        throw new Error();
+                    // Client-supplied policy, tools and instructions are never forwarded.
+                    // The already-created host thread owns all execution authority.
+                    this.started = true;
+                    this.attachment = this.conversation.attach(this.conversation.capability, (f) => this.event(f), this.conversation.snapshot().sequence);
+                    const thread = this.thread();
+                    this.result(id, { thread, model: this.scope.model, modelProvider: "openai", serviceTier: null, disabledPluginIds: [], cwd: this.scope.cwd,
+                        runtimeWorkspaceRoots: [], instructionSources: [], approvalPolicy: "never", approvalsReviewer: "user",
+                        sandbox: { type: "readOnly", networkAccess: false }, activePermissionProfile: null, reasoningEffort: null });
+                    this.send({ method: "thread/started", params: { thread } });
+                    this.onReady();
+                    return;
+                }
+                case "turn/start": {
+                    if (!this.started || !this.attachment || this.pendingTurn !== undefined || this.activeTurn)
+                        throw new Error();
+                    const text = input.parse(params.input).map((part) => part.text).join("\n");
+                    if (Buffer.byteLength(text) > 262_144)
+                        throw new Error();
+                    // Only plain text enters the driver. Policy/model/config overrides,
+                    // injected tool outputs and collaboration instructions are rejected.
+                    for (const [key, val] of Object.entries(params)) {
+                        if (["threadId", "input", "cwd", "model", "clientUserMessageId"].includes(key) || val == null)
+                            continue;
+                        if (key === "approvalPolicy" && val === "never")
+                            continue;
+                        if (key === "approvalsReviewer" && val === "user")
+                            continue;
+                        if (key === "turnTrigger" && val === "user")
+                            continue;
+                        if (key === "serviceTier" && val === "default")
+                            continue;
+                        if (key === "runtimeWorkspaceRoots" && Array.isArray(val) && val.length === 0)
+                            continue;
+                        if (key === "sandboxPolicy" && record(val) && val.type === "readOnly" && val.networkAccess !== true)
+                            continue;
+                        throw new Error();
+                    }
+                    this.pendingTurn = id;
+                    this.submitted = true;
+                    void Promise.resolve().then(() => this.attachment.submit(text)).catch(() => { if (this.pendingTurn !== undefined)
+                        this.error(this.pendingTurn, "GenBI could not complete the turn."); this.pendingTurn = undefined; });
+                    return;
+                }
+                case "turn/steer": {
+                    if (!this.activeTurn || params.expectedTurnId !== this.activeTurn || !this.attachment?.steer)
+                        throw new Error();
+                    const text = input.parse(params.input).map((part) => part.text).join("\n");
+                    if (Buffer.byteLength(text) > 262_144)
+                        throw new Error();
+                    for (const [key, value] of Object.entries(params)) {
+                        if (["threadId", "expectedTurnId", "input", "clientUserMessageId"].includes(key) || value == null)
+                            continue;
+                        throw new Error();
+                    }
+                    this.result(id, await this.attachment.steer(text, this.activeTurn));
+                    return;
+                }
+                case "turn/interrupt":
+                    if (!this.activeTurn || params.turnId !== this.activeTurn || !this.attachment)
+                        throw new Error();
+                    await this.attachment.interrupt();
+                    this.result(id, {});
+                    return;
+                default:
+                    this.error(id);
+                    return;
+            }
+        }
+        catch {
+            this.error(id);
+        }
+    }
+}
+function terminalTurn(turn) {
+    return { ...turn, items: Array.isArray(turn.items) ? turn.items.map((i) => record(i) ? terminalItem(i) : i) : [], itemsView: turn.itemsView ?? "full",
+        error: turn.status === "failed" ? { message: "GenBI execution failed.", codexErrorInfo: null, additionalDetails: null } : null,
+        startedAt: null, completedAt: null, durationMs: null };
+}
+function terminalItem(item) {
+    if (item.type === "userMessage" && Array.isArray(item.content))
+        return { ...item, content: item.content.map((p) => record(p) ? { ...p, text_elements: [] } : p) };
+    if (item.type === "agentMessage")
+        return { ...item, phase: null };
+    if (item.type === "dynamicToolCall")
+        return { ...item, arguments: {}, contentItems: null, durationMs: null };
+    return item;
+}

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

@@ -0,0 +1,16 @@
+import { type InteractiveTerminalManager, type InteractiveTerminalSession } from "../interactive-terminal.js";
+import { type NativeExecutableIdentity } from "../native-runtime-spec.js";
+import type { CodexConversation } from "./codex-conversation.js";
+/** Official CLI renderer with a credential-free home and a private Unix socket. */
+export declare function startCodexTerminal(input: {
+    id: string;
+    conversation: CodexConversation;
+    manager: InteractiveTerminalManager;
+    vendor: NativeExecutableIdentity;
+    cwd: string;
+    model: string;
+    assertActive(): void;
+}): Promise<{
+    terminal: InteractiveTerminalSession;
+    close(): Promise<void>;
+}>;

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

@@ -0,0 +1,120 @@
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import path from "node:path";
+import { WebSocketServer } from "ws";
+import { NO_INTERACTIVE_TERMINAL_LEASES } from "../interactive-terminal.js";
+import { assertNativeExecutableIdentity } from "../native-runtime-spec.js";
+import { CodexTerminalProtocol } from "./codex-terminal-protocol.js";
+/** Official CLI renderer with a credential-free home and a private Unix socket. */
+export async function startCodexTerminal(input) {
+    input.assertActive();
+    assertNativeExecutableIdentity(input.vendor);
+    // Short path for macOS sockaddr_un; mkdtemp creates an owner-only directory.
+    const root = realpathSync(mkdtempSync("/private/tmp/genbi-terminal-"));
+    const home = path.join(root, "home");
+    mkdirSync(home, { mode: 0o700 });
+    const socket = path.join(root, "rpc.sock");
+    const server = createServer((_req, res) => { res.writeHead(404); res.end(); });
+    const wss = new WebSocketServer({ noServer: true, maxPayload: 1_048_576, perMessageDeflate: false });
+    let claimed = false;
+    let protocol;
+    let terminal;
+    let closing;
+    let exited = false;
+    let resolveExit;
+    const exit = new Promise((resolve) => { resolveExit = resolve; });
+    let ready;
+    let failed;
+    const handshake = new Promise((resolve, reject) => { ready = resolve; failed = reject; });
+    void handshake.catch(() => { });
+    server.on("upgrade", (req, connection, head) => {
+        if (claimed || closing || req.headers.origin || req.url !== "/rpc") {
+            connection.destroy();
+            return;
+        }
+        claimed = true;
+        wss.handleUpgrade(req, connection, head, (ws) => {
+            protocol = new CodexTerminalProtocol(input.conversation, { cwd: input.cwd, clientHome: home, model: input.model }, (message) => {
+                if (ws.readyState !== ws.OPEN || ws.bufferedAmount > 1_048_576)
+                    throw new Error("Terminal connection unavailable");
+                ws.send(JSON.stringify(message));
+            }, input.assertActive, ready);
+            ws.on("message", (bytes, binary) => {
+                if (binary) {
+                    ws.terminate();
+                    return;
+                }
+                try {
+                    void protocol.receive(JSON.parse(bytes.toString())).catch(() => ws.terminate());
+                }
+                catch {
+                    ws.terminate();
+                }
+            });
+            ws.on("error", () => ws.terminate());
+            ws.on("close", () => { protocol?.close(); failed(new Error("Terminal connection closed")); terminal?.close(); });
+        });
+    });
+    const close = () => closing ??= (async () => {
+        protocol?.close();
+        terminal?.close();
+        for (const ws of wss.clients)
+            ws.terminate();
+        await new Promise((resolve) => wss.close(() => resolve()));
+        if (server.listening)
+            await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+        if (terminal && !exited) {
+            let timer;
+            try {
+                await Promise.race([exit, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Terminal cleanup failed")), 2_000); })]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        rmSync(root, { recursive: true });
+    })();
+    try {
+        await new Promise((resolve, reject) => { server.once("error", reject); server.listen(socket, () => { server.removeListener("error", reject); resolve(); }); });
+        chmodSync(socket, 0o600);
+        input.assertActive();
+        assertNativeExecutableIdentity(input.vendor);
+        const filesystem = { ":minimal": "read", "/private/tmp": "deny", "/private/var/tmp": "deny",
+            [path.dirname(input.vendor.executable)]: "read", [input.cwd]: "read", [root]: "write" };
+        const filesystemToml = `{${Object.entries(filesystem).map(([key, value]) => `${JSON.stringify(key)}=${JSON.stringify(value)}`).join(",")}}`;
+        terminal = input.manager.start({ version: "5", target: "codex:interactive", executable: "codex", hostExecutable: input.vendor.executable,
+            argv: ["sandbox", "-C", root, "-P", "genbi-terminal", "-c", `permissions.genbi-terminal.filesystem=${filesystemToml}`,
+                "-c", "permissions.genbi-terminal.network.enabled=false", "--allow-unix-socket", socket, "--", input.vendor.executable,
+                "--remote", `unix://${socket}`, "--no-alt-screen", "-C", input.cwd, "-c", "check_for_update_on_startup=false"],
+            cwd: root, artifact_root: root, handoff_path: "" }, { id: input.id, capability: input.conversation.capability }, { HOME: home, CODEX_HOME: home, PATH: "/usr/bin:/bin" }, NO_INTERACTIVE_TERMINAL_LEASES);
+        // This credential-free renderer starts before the browser attaches. Answer
+        // its initial terminal capability probes; xterm owns replies after startup.
+        let probeTail = "";
+        const stopProbe = terminal.onData((data) => {
+            probeTail = (probeTail + data).slice(-1024);
+            if (probeTail.includes("\x1b[6n")) {
+                terminal.write("\x1b[1;1R");
+                probeTail = probeTail.replaceAll("\x1b[6n", "");
+            }
+            if (probeTail.includes("\x1b]11;?")) {
+                terminal.write("\x1b]11;rgb:0000/0000/0000\x1b\\");
+                probeTail = probeTail.replaceAll("\x1b]11;?", "");
+            }
+        });
+        terminal.onExit(() => { exited = true; resolveExit(); failed(new Error("Terminal exited before startup")); });
+        let timeout;
+        try {
+            await Promise.race([handshake, new Promise((_, reject) => { timeout = setTimeout(() => reject(new Error("Terminal startup timed out")), 15_000); })]);
+        }
+        finally {
+            clearTimeout(timeout);
+            stopProbe();
+        }
+        input.assertActive();
+        return { terminal, close };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}

package/dist-server/server/runtime-host/index.d.ts

@@ -0,0 +1,5 @@
+export { RuntimeHost } from "./local.js";
+export { runtimeNotReady, runtimeReady, sanitizeRuntimeDiagnostic, sanitizeRuntimeReadiness } from "./policy.js";
+export { RUNTIME_BACKEND_IDS, RUNTIME_BACKEND_REASON_CODES, RUNTIME_CAPABILITIES } from "./types.js";
+export type { RuntimeDeployment, RuntimeHostOptions, VendorRuntimeProbes } from "./local.js";
+export type { RuntimeBackendDiagnostic, RuntimeBackendId, RuntimeBackendNotReady, RuntimeBackendProbeResult, RuntimeBackendReadiness, RuntimeBackendReasonCode, RuntimeBackendReady, RuntimeCapability, RuntimeDiagnostics, RuntimeReadiness, } from "./types.js";

package/dist-server/server/runtime-host/index.js

@@ -0,0 +1,3 @@
+export { RuntimeHost } from "./local.js";
+export { runtimeNotReady, runtimeReady, sanitizeRuntimeDiagnostic, sanitizeRuntimeReadiness } from "./policy.js";
+export { RUNTIME_BACKEND_IDS, RUNTIME_BACKEND_REASON_CODES, RUNTIME_CAPABILITIES } from "./types.js";

package/dist-server/server/runtime-host/local.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeBackendId, RuntimeBackendProbeResult, RuntimeDiagnostics, RuntimeReadiness } from "./types.js";
+export type RuntimeDeployment = "development" | "production";
+export interface VendorRuntimeProbes {
+    readonly "codex-app-server"?: () => Promise<RuntimeBackendProbeResult<"codex-app-server">>;
+    readonly "claude-sandbox-runtime"?: () => Promise<RuntimeBackendProbeResult<"claude-sandbox-runtime">>;
+}
+export interface RuntimeHostOptions {
+    /** Server-owned selection. Browser input is deliberately absent from this type. */
+    readonly selected: RuntimeBackendId;
+    readonly deployment: RuntimeDeployment;
+    readonly localAvailable: () => boolean | Promise<boolean>;
+    /** Internal test/adaptor seam. Future vendor adapters must supply this server-side. */
+    readonly vendorProbes?: VendorRuntimeProbes;
+}
+/**
+ * Phase 1 read-only runtime boundary. It does not launch vendor processes;
+ * production adapters will replace only their own probe seam in later phases.
+ */
+export declare class RuntimeHost {
+    private readonly options;
+    private diagnostics?;
+    constructor(options: RuntimeHostOptions);
+    private probeLocal;
+    private probeCodex;
+    private probeClaude;
+    probe(): Promise<RuntimeReadiness>;
+    /** Host-only support evidence; never include this object in an API response. */
+    serverDiagnostics(): RuntimeDiagnostics | undefined;
+}

package/dist-server/server/runtime-host/local.js

@@ -0,0 +1,90 @@
+import { runtimeNotReady, runtimeReady, sanitizeRuntimeDiagnostic, sanitizeRuntimeReadiness, } from "./policy.js";
+const fixedCodexProbe = () => ({
+    // Phase 2A has no managed-runtime record/provisioner yet. This is the first
+    // blocking link for every Codex launch, even while the development-local
+    // PTY host itself is healthy.
+    readiness: runtimeNotReady("codex-app-server", "unprovisioned", "codex_wren_runtime_unprovisioned"),
+    diagnostic: { phase: "provisioning" },
+});
+const fixedClaudeProbe = () => ({
+    readiness: runtimeNotReady("claude-sandbox-runtime", "unprovisioned", "claude_sandbox_runtime_unprovisioned"),
+    diagnostic: { phase: "provisioning" },
+});
+/**
+ * Phase 1 read-only runtime boundary. It does not launch vendor processes;
+ * production adapters will replace only their own probe seam in later phases.
+ */
+export class RuntimeHost {
+    options;
+    diagnostics;
+    constructor(options) {
+        this.options = options;
+    }
+    async probeLocal() {
+        if (this.options.deployment === "production") {
+            return {
+                readiness: runtimeNotReady("local", "unavailable", "local_runtime_production_forbidden"),
+                diagnostic: { phase: "policy" },
+            };
+        }
+        try {
+            if (await this.options.localAvailable()) {
+                return {
+                    readiness: runtimeReady("development-local", ["pty", "terminal_replay", "terminal_resize", "terminal_terminate"]),
+                    diagnostic: { phase: "capability", requiredCapability: "pty" },
+                };
+            }
+        }
+        catch {
+            // The browser gets the same fixed result as a false host probe.
+        }
+        return {
+            readiness: runtimeNotReady("local", "unavailable", "local_runtime_host_unavailable"),
+            diagnostic: { phase: "capability", requiredCapability: "pty" },
+        };
+    }
+    async probeCodex() {
+        try {
+            return await (this.options.vendorProbes?.["codex-app-server"]?.() ?? Promise.resolve(fixedCodexProbe()));
+        }
+        catch {
+            return {
+                readiness: runtimeNotReady("codex-app-server", "unavailable", "runtime_probe_failed"),
+                diagnostic: { phase: "probe" },
+            };
+        }
+    }
+    async probeClaude() {
+        try {
+            return await (this.options.vendorProbes?.["claude-sandbox-runtime"]?.() ?? Promise.resolve(fixedClaudeProbe()));
+        }
+        catch {
+            return {
+                readiness: runtimeNotReady("claude-sandbox-runtime", "unavailable", "runtime_probe_failed"),
+                diagnostic: { phase: "probe" },
+            };
+        }
+    }
+    async probe() {
+        const [local, codex, claude] = await Promise.all([
+            this.probeLocal(),
+            this.probeCodex(),
+            this.probeClaude(),
+        ]);
+        const backends = {
+            local: sanitizeRuntimeReadiness("local", local.readiness),
+            "codex-app-server": sanitizeRuntimeReadiness("codex-app-server", codex.readiness),
+            "claude-sandbox-runtime": sanitizeRuntimeReadiness("claude-sandbox-runtime", claude.readiness),
+        };
+        this.diagnostics = {
+            local: sanitizeRuntimeDiagnostic(local.diagnostic),
+            "codex-app-server": sanitizeRuntimeDiagnostic(codex.diagnostic),
+            "claude-sandbox-runtime": sanitizeRuntimeDiagnostic(claude.diagnostic),
+        };
+        return { selected: this.options.selected, selectedReadiness: backends[this.options.selected], backends };
+    }
+    /** Host-only support evidence; never include this object in an API response. */
+    serverDiagnostics() {
+        return this.diagnostics;
+    }
+}

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

@@ -0,0 +1,8 @@
+import { type RuntimeBackendDiagnostic, type RuntimeBackendId, type RuntimeBackendNotReady, type RuntimeBackendReadiness, type RuntimeBackendReasonCode, type RuntimeBackendReady, type RuntimeCapability, type RuntimeReadinessState } from "./types.js";
+export declare function isRuntimeReasonCode<B extends RuntimeBackendId>(backend: B, code: string): code is RuntimeBackendReasonCode<B>;
+export declare function runtimeNotReady<B extends RuntimeBackendId>(backend: B, state: Exclude<RuntimeReadinessState, "ready">, code: RuntimeBackendReasonCode<B>): RuntimeBackendNotReady<B>;
+export declare function runtimeReady(version: string, capabilities: readonly RuntimeCapability[]): RuntimeBackendReady;
+/** Rebuild a probe result so server-only probe seams cannot leak custom text. */
+export declare function sanitizeRuntimeReadiness<B extends RuntimeBackendId>(backend: B, readiness: RuntimeBackendReadiness<B>): RuntimeBackendReadiness<B>;
+/** Keep only parsed support evidence. This return value is never an API DTO. */
+export declare function sanitizeRuntimeDiagnostic(diagnostic: RuntimeBackendDiagnostic): RuntimeBackendDiagnostic;

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

@@ -0,0 +1,78 @@
+import { RUNTIME_BACKEND_REASON_CODES, RUNTIME_CAPABILITIES, } from "./types.js";
+const MESSAGES = {
+    local_runtime_disabled: "The local development runtime is disabled by server policy.",
+    local_runtime_host_unavailable: "The local development runtime cannot start a terminal host on this machine.",
+    local_runtime_production_forbidden: "The local development runtime is not available in production.",
+    runtime_probe_failed: "The runtime readiness probe could not complete.",
+    codex_app_server_unprovisioned: "The Codex app-server runtime has not been provisioned by this GenBI release.",
+    codex_cli_missing: "The required Codex CLI is not available.",
+    codex_cli_version_malformed: "The installed Codex CLI version is invalid.",
+    codex_cli_version_unsupported: "The installed Codex CLI version is not supported by this GenBI release.",
+    codex_identity_uncertified: "This Codex version has test evidence, but this installed identity is not certified.",
+    codex_dependencies_drifted: "Codex native is certified for other Warble, IR or context-loader versions than this install uses; re-certify Codex on the installed versions to enable it.",
+    codex_app_server_unreachable: "The Codex app-server runtime is unavailable.",
+    codex_app_server_cleanup_failed: "Codex runtime cleanup could not be confirmed. The runtime generation has been retained.",
+    codex_app_server_protocol_incompatible: "The Codex app-server protocol is incompatible with this GenBI release.",
+    codex_sandbox_policy_unavailable: "The required Codex sandbox policy is unavailable.",
+    codex_permission_profile_unavailable: "The required Codex permission profile is unavailable.",
+    codex_wren_manifest_missing: "The managed Wren runtime manifest is unavailable.",
+    codex_wren_manifest_invalid: "The managed Wren runtime manifest is invalid.",
+    codex_wren_platform_unsupported: "The managed Wren runtime does not support this platform.",
+    codex_wren_runtime_unprovisioned: "The managed Wren runtime has not been provisioned.",
+    codex_wren_provision_failed: "The managed Wren runtime could not be provisioned.",
+    codex_wren_interpreter_mismatch: "The managed Wren interpreter identity does not match this GenBI release.",
+    codex_wren_launcher_mismatch: "The managed Wren launcher identity does not match this GenBI release.",
+    codex_wren_package_mismatch: "The managed Wren package identity does not match this GenBI release.",
+    codex_wren_closure_mismatch: "The managed Wren runtime closure does not match this GenBI release.",
+    codex_wren_profile_unavailable: "The bound Wren profile is unavailable to this session.",
+    codex_wren_secret_unavailable: "A secret required by the bound Wren profile is unavailable.",
+    codex_wren_session_home_unavailable: "The private Wren session home is unavailable.",
+    codex_wren_child_env_invalid: "The managed Wren child environment is invalid.",
+    claude_sandbox_runtime_unprovisioned: "The Claude sandbox runtime has not been provisioned by this GenBI release.",
+    claude_cli_missing: "The required Claude CLI is not available.",
+    claude_cli_version_malformed: "The installed Claude CLI version is invalid.",
+    claude_cli_version_unsupported: "The installed Claude CLI version is not supported by this GenBI release.",
+    claude_identity_uncertified: "This Claude runtime version has test evidence, but this installed identity is not certified.",
+    claude_sandbox_runtime_missing: "The required Claude sandbox runtime is unavailable.",
+    claude_sandbox_runtime_version_malformed: "The installed Claude sandbox runtime version is invalid.",
+    claude_sandbox_runtime_version_unsupported: "The installed Claude sandbox runtime version is not supported by this GenBI release.",
+    claude_sandbox_capability_missing: "The required Claude sandbox capability is unavailable.",
+    runtime_platform_unsupported: "This runtime backend is not supported on this platform.",
+    runtime_policy_unavailable: "The runtime policy required by this backend is unavailable.",
+};
+const SAFE_VERSION = /^(?:[0-9]+(?:\.[0-9]+){1,3}(?:[-+._][A-Za-z0-9]+)?|development-local)$/;
+const SAFE_IDENTITY = /^sha256:[a-f0-9]{64}$/;
+export function isRuntimeReasonCode(backend, code) {
+    return RUNTIME_BACKEND_REASON_CODES[backend].includes(code);
+}
+export function runtimeNotReady(backend, state, code) {
+    return { state, code, message: MESSAGES[code] };
+}
+export function runtimeReady(version, capabilities) {
+    return {
+        state: "ready",
+        version: SAFE_VERSION.test(version) ? version : "development-local",
+        capabilities: capabilities.filter((capability) => RUNTIME_CAPABILITIES.includes(capability)),
+    };
+}
+/** Rebuild a probe result so server-only probe seams cannot leak custom text. */
+export function sanitizeRuntimeReadiness(backend, readiness) {
+    if (readiness.state === "ready")
+        return runtimeReady(readiness.version, readiness.capabilities);
+    return isRuntimeReasonCode(backend, readiness.code)
+        ? runtimeNotReady(backend, readiness.state, readiness.code)
+        : runtimeNotReady(backend, "unavailable", "runtime_probe_failed");
+}
+/** Keep only parsed support evidence. This return value is never an API DTO. */
+export function sanitizeRuntimeDiagnostic(diagnostic) {
+    return {
+        phase: diagnostic.phase,
+        ...(diagnostic.observedVersion && SAFE_VERSION.test(diagnostic.observedVersion) ? { observedVersion: diagnostic.observedVersion } : {}),
+        ...(diagnostic.requiredCapability && RUNTIME_CAPABILITIES.includes(diagnostic.requiredCapability)
+            ? { requiredCapability: diagnostic.requiredCapability }
+            : {}),
+        ...(diagnostic.attestedIdentity && SAFE_IDENTITY.test(diagnostic.attestedIdentity)
+            ? { attestedIdentity: diagnostic.attestedIdentity }
+            : {}),
+    };
+}