@deepseek-harness-tui/dsh-tui 0.13.0 → 0.14.0

package/lib/types/backends/codex/rpc/binary.js

@@ -0,0 +1,174 @@
+/**
+ * The `codex` executable and the environment its app-server runs in
+ * (docs/codex-backend-design.md §5.1, §5.4).
+ *
+ * - Executable: `CODEX_EXECUTABLE` (taken as given, so a typo fails loudly)
+ *   → the first `codex` on PATH whose `--version` answers → not installed.
+ *   On Windows npm shims resolve to the native codex.exe so cmd.exe never
+ *   reparses app-server arguments.
+ * - Environment: `process.env` minus what a parent Codex session exports
+ *   to its shells (C0 V2: dsh-tui may itself run inside one, and the child
+ *   must not believe it is that thread's tool process) and minus the npm
+ *   launcher's own markers (the binary we spawn sets its own). The user's
+ *   own Codex settings (`CODEX_HOME`, `CODEX_API_KEY`, `CODEX_SQLITE_HOME`,
+ *   certificates, `OPENAI_*`) pass through untouched.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+import { parseCodexVersion } from '../contract.js';
+/** Variables a parent Codex thread exports to its tool processes (V2). */
+const SCRUBBED_EXACT = [
+    'CODEX_THREAD_ID',
+    'CODEX_SESSION_ID',
+    'CODEX_VERSION',
+    'CODEX_CI',
+    'CODEX_SANDBOX',
+    'CODEX_SANDBOX_NETWORK_DISABLED',
+    'CODEX_PERMISSION_PROFILE',
+    'CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS',
+    'CODEX_INTERNAL_ORIGINATOR_OVERRIDE',
+    'CODEX_MANAGED_PACKAGE_ROOT',
+];
+const SCRUBBED_PREFIXES = ['CODEX_MANAGED_BY_', 'CODEX_NETWORK_PROXY_'];
+/** Whether a variable is one the child must not inherit. */
+export function scrubbedCodexVariable(name) {
+    const upper = name.toUpperCase();
+    return SCRUBBED_EXACT.includes(upper) || SCRUBBED_PREFIXES.some(prefix => upper.startsWith(prefix));
+}
+/** The app-server child environment. */
+export function buildCodexEnv(base = process.env, extra = {}) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || scrubbedCodexVariable(key))
+            continue;
+        env[key] = value;
+    }
+    return { ...env, ...extra };
+}
+/** Run `<executable> --version` (bounded); the parsed version or undefined. */
+export function readCodexVersion(executable, env = process.env) {
+    const shim = process.platform === 'win32' && /\.(?:cmd|bat)$/iu.test(executable);
+    return new Promise(resolve => {
+        try {
+            execFile(shim ? (process.env.ComSpec ?? 'cmd.exe') : executable, shim ? ['/d', '/s', '/c', `"${executable}" --version`] : ['--version'], {
+                timeout: 10_000,
+                windowsHide: true,
+                env: buildCodexEnv(env),
+            }, (error, stdout) => {
+                if (error !== null) {
+                    resolve(undefined);
+                    return;
+                }
+                resolve(parseCodexVersion(String(stdout)));
+            });
+        }
+        catch {
+            resolve(undefined);
+        }
+    });
+}
+/** The npm launcher's platform packages and target triples (its
+ *  `bin/codex.js` maps the same way). */
+const NPM_TARGETS = {
+    'linux-x64': { triple: 'x86_64-unknown-linux-musl', pkg: 'codex-linux-x64' },
+    'linux-arm64': { triple: 'aarch64-unknown-linux-musl', pkg: 'codex-linux-arm64' },
+    'darwin-x64': { triple: 'x86_64-apple-darwin', pkg: 'codex-darwin-x64' },
+    'darwin-arm64': { triple: 'aarch64-apple-darwin', pkg: 'codex-darwin-arm64' },
+    'win32-x64': { triple: 'x86_64-pc-windows-msvc', pkg: 'codex-win32-x64' },
+    'win32-arm64': { triple: 'aarch64-pc-windows-msvc', pkg: 'codex-win32-arm64' },
+};
+/**
+ * The native binary behind an npm `codex` shim (`codex.cmd`, `codex.ps1`,
+ * the extensionless script), or undefined. A shim runs `node …/@openai/codex/
+ * bin/codex.js`, which locates `vendor/<triple>/bin/codex[.exe]` (older
+ * packages use `codex/` instead of `bin/`) of the
+ * platform package and spawns it; spawning that binary directly avoids
+ * `cmd.exe` re-parsing the `-c key="value"` arguments. Pure over its I/O
+ * seams (unit-tested with a fake tree).
+ */
+export function resolveNpmShim(shim, io) {
+    const target = NPM_TARGETS[`${io.platform}-${io.arch}`];
+    if (target === undefined)
+        return undefined;
+    const text = io.read(shim);
+    if (text === undefined || !/@openai[\\/]codex[\\/]bin[\\/]codex\.js/iu.test(text))
+        return undefined;
+    const paths = io.platform === 'win32' ? win32 : posix;
+    const shimDir = paths.dirname(shim);
+    const match = /["']([^"'\r\n]*@openai[\\/]codex[\\/]bin[\\/]codex\.js)["']|(\S*@openai[\\/]codex[\\/]bin[\\/]codex\.js)/iu.exec(text);
+    const launcher = (match?.[1] ?? match?.[2])?.replace(/%~?dp0%?|\$\{?basedir\}?|\$PSScriptRoot/giu, shimDir);
+    const roots = [
+        ...(launcher === undefined ? [] : [paths.dirname(paths.dirname(paths.resolve(shimDir, launcher)))]),
+        paths.join(shimDir, 'node_modules', '@openai', 'codex'),
+    ];
+    const binary = io.platform === 'win32' ? 'codex.exe' : 'codex';
+    for (const root of roots) {
+        const scope = paths.dirname(root);
+        for (const vendor of [paths.join(root, 'node_modules', '@openai', target.pkg, 'vendor'), paths.join(scope, target.pkg, 'vendor'), paths.join(root, 'vendor')]) {
+            for (const subdir of ['bin', 'codex']) {
+                const candidate = paths.join(vendor, target.triple, subdir, binary);
+                if (io.exists(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+/** The binary to spawn for a resolved path: an npm shim's native binary
+ *  when one is found, else the path itself. */
+export function spawnablePath(path) {
+    if (process.platform !== 'win32' && !/\.(?:cmd|bat|ps1)$/iu.test(path))
+        return path;
+    const native = resolveNpmShim(path, {
+        platform: process.platform,
+        arch: process.arch,
+        exists: existsSync,
+        read: file => { try {
+            return readFileSync(file, 'utf8').slice(0, 64 * 1024);
+        }
+        catch {
+            return undefined;
+        } },
+    });
+    return native ?? path;
+}
+/** Every existing `codex` on PATH, in the platform tool's order. */
+function whichAll(name) {
+    const win = process.platform === 'win32';
+    return new Promise(resolve => {
+        try {
+            execFile(win ? 'where' : 'which', win ? [name] : ['-a', name], { timeout: 5000, windowsHide: true }, (error, stdout) => {
+                if (error !== null && String(stdout).trim() === '') {
+                    resolve([]);
+                    return;
+                }
+                resolve(String(stdout).split(/\r?\n/u).map(line => line.trim()).filter(line => line !== '' && existsSync(line)));
+            });
+        }
+        catch {
+            resolve([]);
+        }
+    });
+}
+/** Resolve the executable and its version; undefined when none is usable. */
+export async function resolveCodexExecutable(env = process.env) {
+    const configured = env.CODEX_EXECUTABLE;
+    if (configured !== undefined && configured !== '') {
+        const path = spawnablePath(configured);
+        return { path, source: 'env', version: await readCodexVersion(path, env) };
+    }
+    // A candidate that cannot report its version cannot be spawned either
+    // (a dead npm shim, an extensionless script on Windows).
+    const candidates = await whichAll('codex');
+    const ordered = process.platform === 'win32'
+        ? [...candidates.filter(path => /\.(?:exe|cmd)$/iu.test(path)), ...candidates.filter(path => !/\.(?:exe|cmd)$/iu.test(path))]
+        : candidates;
+    for (const listed of ordered) {
+        const candidate = spawnablePath(listed);
+        const version = await readCodexVersion(candidate, env);
+        if (version !== undefined)
+            return { path: candidate, source: 'path', version };
+    }
+    return undefined;
+}

package/lib/types/backends/codex/rpc/client.d.ts

@@ -0,0 +1,72 @@
+/**
+ * JSON-RPC 2.0 over the app-server's newline-delimited stdio
+ * (docs/codex-backend-design.md §5.2). Transport-agnostic: the hub feeds
+ * every received line to `receive` and writes through `write`.
+ *
+ * - Requests get increasing integer ids and a per-method timeout (a timeout
+ *   rejects with `CodexRpcError(-32000)` and never kills the process: the
+ *   server may still answer, and a late answer is dropped).
+ * - Server requests (a message with both `id` and `method`) go to the one
+ *   registered handler; it returns the result (or a promise of it), or
+ *   `undefined` to answer later through `respond` (a parked approval).
+ * - A line that does not parse, an unknown notification and a response to
+ *   an id nobody waits for are debug-logged and dropped, never thrown.
+ * - `close(reason)` rejects every pending request with `reason`.
+ *
+ * Diagnostics never carry request parameters: the credential-bearing
+ * methods (`account/login/start`) would otherwise leak token material into
+ * the debug log.
+ */
+import { type Rec } from '../narrow.js';
+export type RequestId = number | string;
+/** JSON-RPC error codes the backend distinguishes. */
+export declare const RPC_ERROR: {
+    readonly timeout: -32000;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+};
+/** A JSON-RPC error answer (or a local timeout / closed connection). */
+export declare class CodexRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(message: string, code: number, data?: unknown | undefined);
+}
+/** The JSON-RPC code of an error, when it is one. */
+export declare const rpcCode: (error: unknown) => number | undefined;
+/** Timer seam (tests inject a manual clock). */
+export interface RpcClock {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare const REAL_CLOCK: RpcClock;
+/** Default request timeout (ms). */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface CallOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** A server → client request handler (see the module comment). */
+export type ServerRequestHandler = (id: RequestId, method: string, params: Rec) => Promise<unknown> | unknown;
+export interface RpcClient {
+    call<R = unknown>(method: string, params?: unknown, options?: CallOptions): Promise<R>;
+    notify(method: string, params?: unknown): void;
+    onNotification(listener: (method: string, params: Rec) => void): () => void;
+    onServerRequest(handler: ServerRequestHandler): void;
+    respond(id: RequestId, result: unknown): void;
+    respondError(id: RequestId, code: number, message: string): void;
+    /** Feed one received line. */
+    receive(line: string): void;
+    /** Reject every pending request; later calls reject at once. */
+    close(reason: Error): void;
+    readonly closed: boolean;
+    /** Requests still waiting for an answer. */
+    readonly pending: number;
+}
+export declare function createRpcClient(options: {
+    readonly write: (line: string) => void;
+    readonly debug: (message: string) => void;
+    readonly clock?: RpcClock;
+}): RpcClient;
+//# sourceMappingURL=client.d.ts.map

package/lib/types/backends/codex/rpc/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/rpc/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAuB,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AAE5D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAA;AAEvC,sDAAsD;AACtD,eAAO,MAAM,SAAS;;;;;;CAMZ,CAAA;AAEV,wEAAwE;AACxE,qBAAa,aAAc,SAAQ,KAAK;IACT,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO;gBAA/D,OAAO,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM,EAAW,IAAI,CAAC,EAAE,OAAO,YAAA;CAI5E;AAED,qDAAqD;AACrD,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAAoE,CAAA;AAEtH,gDAAgD;AAChD,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IACrD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;CACpC;AAED,eAAO,MAAM,UAAU,EAAE,QAOxB,CAAA;AAED,oCAAoC;AACpC,eAAO,MAAM,kBAAkB,QAAS,CAAA;AAUxC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;AAE7G,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACtF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAC9C,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3E,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAA;IACpD,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7C,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAChE,8BAA8B;IAC9B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,gEAAgE;IAChE,KAAK,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;CAC1B,GAAG,SAAS,CAyJZ"}

package/lib/types/backends/codex/rpc/client.js

@@ -0,0 +1,214 @@
+/**
+ * JSON-RPC 2.0 over the app-server's newline-delimited stdio
+ * (docs/codex-backend-design.md §5.2). Transport-agnostic: the hub feeds
+ * every received line to `receive` and writes through `write`.
+ *
+ * - Requests get increasing integer ids and a per-method timeout (a timeout
+ *   rejects with `CodexRpcError(-32000)` and never kills the process: the
+ *   server may still answer, and a late answer is dropped).
+ * - Server requests (a message with both `id` and `method`) go to the one
+ *   registered handler; it returns the result (or a promise of it), or
+ *   `undefined` to answer later through `respond` (a parked approval).
+ * - A line that does not parse, an unknown notification and a response to
+ *   an id nobody waits for are debug-logged and dropped, never thrown.
+ * - `close(reason)` rejects every pending request with `reason`.
+ *
+ * Diagnostics never carry request parameters: the credential-bearing
+ * methods (`account/login/start`) would otherwise leak token material into
+ * the debug log.
+ */
+import { errorText, rec, str } from '../narrow.js';
+/** JSON-RPC error codes the backend distinguishes. */
+export const RPC_ERROR = {
+    timeout: -32000,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internal: -32603,
+};
+/** A JSON-RPC error answer (or a local timeout / closed connection). */
+export class CodexRpcError extends Error {
+    code;
+    data;
+    constructor(message, code, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'CodexRpcError';
+    }
+}
+/** The JSON-RPC code of an error, when it is one. */
+export const rpcCode = (error) => error instanceof CodexRpcError ? error.code : undefined;
+export const REAL_CLOCK = {
+    setTimeout: (callback, ms) => {
+        const handle = setTimeout(callback, ms);
+        handle.unref();
+        return handle;
+    },
+    clearTimeout: handle => { clearTimeout(handle); },
+};
+/** Default request timeout (ms). */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** Methods that wait for the model or the disk longer than the default. */
+const METHOD_TIMEOUTS = {
+    'turn/start': 60_000,
+    'turn/steer': 60_000,
+    'thread/resume': 60_000,
+    'thread/compact/start': 120_000,
+};
+export function createRpcClient(options) {
+    const clock = options.clock ?? REAL_CLOCK;
+    const pending = new Map();
+    const listeners = new Set();
+    let handler;
+    let nextId = 1;
+    let closedWith;
+    const send = (message) => {
+        if (closedWith !== undefined)
+            return;
+        try {
+            options.write(JSON.stringify(message));
+        }
+        catch (error) {
+            options.debug(`codex rpc: write failed (${errorText(error)})`);
+        }
+    };
+    const settle = (id) => {
+        const entry = pending.get(id);
+        if (entry === undefined)
+            return undefined;
+        pending.delete(id);
+        clock.clearTimeout(entry.timer);
+        entry.detach?.();
+        return entry;
+    };
+    const answerServerRequest = (id, method, params) => {
+        if (handler === undefined) {
+            send({ id, error: { code: RPC_ERROR.methodNotFound, message: `dsh-tui does not handle ${method}` } });
+            return;
+        }
+        let outcome;
+        try {
+            outcome = handler(id, method, params);
+        }
+        catch (error) {
+            options.debug(`codex rpc: server request ${method} handler threw (${errorText(error)})`);
+            send({ id, error: { code: RPC_ERROR.internal, message: 'dsh-tui failed to handle the request' } });
+            return;
+        }
+        if (outcome === undefined)
+            return;
+        void Promise.resolve(outcome).then(result => {
+            if (result !== undefined)
+                send({ id, result });
+        }, (error) => {
+            const code = error instanceof CodexRpcError ? error.code : RPC_ERROR.internal;
+            send({ id, error: { code, message: error instanceof Error ? error.message : 'dsh-tui failed to handle the request' } });
+        });
+    };
+    return {
+        get closed() { return closedWith !== undefined; },
+        get pending() { return pending.size; },
+        call(method, params, callOptions = {}) {
+            if (closedWith !== undefined)
+                return Promise.reject(closedWith);
+            if (callOptions.signal?.aborted === true)
+                return Promise.reject(new CodexRpcError(`${method} aborted`, RPC_ERROR.timeout));
+            const id = nextId++;
+            return new Promise((resolve, reject) => {
+                const timeoutMs = callOptions.timeoutMs ?? METHOD_TIMEOUTS[method] ?? DEFAULT_TIMEOUT_MS;
+                const timer = clock.setTimeout(() => {
+                    if (settle(id) === undefined)
+                        return;
+                    options.debug(`codex rpc: ${method} #${id} timed out after ${timeoutMs} ms`);
+                    reject(new CodexRpcError(`${method} timed out`, RPC_ERROR.timeout));
+                }, timeoutMs);
+                let detach;
+                if (callOptions.signal !== undefined) {
+                    const signal = callOptions.signal;
+                    const onAbort = () => {
+                        if (settle(id) === undefined)
+                            return;
+                        reject(new CodexRpcError(`${method} aborted`, RPC_ERROR.timeout));
+                    };
+                    signal.addEventListener('abort', onAbort, { once: true });
+                    detach = () => { signal.removeEventListener('abort', onAbort); };
+                }
+                pending.set(id, { method, resolve: value => resolve(value), reject, timer, ...(detach === undefined ? {} : { detach }) });
+                send(params === undefined ? { id, method } : { id, method, params });
+            });
+        },
+        notify(method, params) {
+            send(params === undefined ? { method } : { method, params });
+        },
+        onNotification(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        onServerRequest(next) {
+            handler = next;
+        },
+        respond(id, result) {
+            send({ id, result });
+        },
+        respondError(id, code, message) {
+            send({ id, error: { code, message } });
+        },
+        receive(line) {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                options.debug(`codex rpc: dropped a line that is not JSON (${line.length} chars)`);
+                return;
+            }
+            const message = rec(parsed);
+            if (message === undefined) {
+                options.debug('codex rpc: dropped a non-object message');
+                return;
+            }
+            const method = str(message.method);
+            const id = typeof message.id === 'number' || typeof message.id === 'string' ? message.id : undefined;
+            if (method !== undefined && id !== undefined) {
+                answerServerRequest(id, method, rec(message.params) ?? {});
+                return;
+            }
+            if (method !== undefined) {
+                const params = rec(message.params) ?? {};
+                for (const listener of [...listeners]) {
+                    try {
+                        listener(method, params);
+                    }
+                    catch (error) {
+                        options.debug(`codex rpc: ${method} listener threw (${errorText(error)})`);
+                    }
+                }
+                return;
+            }
+            if (id === undefined) {
+                options.debug('codex rpc: dropped a message with neither id nor method');
+                return;
+            }
+            const entry = settle(id);
+            if (entry === undefined) {
+                options.debug(`codex rpc: dropped an answer to unknown request #${String(id)}`);
+                return;
+            }
+            const error = rec(message.error);
+            if (error !== undefined) {
+                const code = typeof error.code === 'number' ? error.code : RPC_ERROR.internal;
+                entry.reject(new CodexRpcError(str(error.message) ?? `${entry.method} failed`, code, error.data));
+                return;
+            }
+            entry.resolve(message.result);
+        },
+        close(reason) {
+            if (closedWith !== undefined)
+                return;
+            closedWith = reason;
+            for (const id of [...pending.keys()])
+                settle(id)?.reject(reason);
+        },
+    };
+}

package/lib/types/backends/codex/rpc/hub.d.ts

@@ -0,0 +1,105 @@
+import { type Rec } from '../narrow.js';
+import { type CallOptions, type RequestId, type RpcClock } from './client.js';
+import { type TransportFactory } from './transport.js';
+/** The server's handshake answer. */
+export interface InitializeInfo {
+    readonly userAgent: string;
+    readonly codexHome: string;
+    readonly platformFamily: string;
+    readonly platformOs: string;
+    /** Which connection generation answered (1 = the first child). */
+    readonly generation: number;
+}
+/** One server request as a session sees it. */
+export interface HubServerRequest {
+    /** `codex:<generation>:<id>`: unique across restarts. */
+    readonly key: string;
+    readonly id: RequestId;
+    readonly generation: number;
+    readonly method: string;
+    readonly params: Rec;
+    /** The same request arrived again (a rejoin redelivered it). */
+    readonly redelivered: boolean;
+    respond(result: unknown): void;
+    respondError(code: number, message: string): void;
+    /** Whether the connection it came on is still the live one. */
+    live(): boolean;
+}
+/** A bounded hub diagnostic, broadcast and replayed to every attached sink. */
+export interface HubDiagnostic {
+    readonly kind: 'debug' | 'stderr';
+    readonly message: string;
+}
+/** What a session attaches for its thread. */
+export interface ThreadSink {
+    notification(method: string, params: Rec): void;
+    serverRequest(request: HubServerRequest): void;
+    /** The child went away; `permanent` = no restart will follow. */
+    connectionLost(error: Error, permanent: boolean): void;
+    /** A restarted child finished its handshake: resubscribe. */
+    connectionRestored(): void;
+    /** Startup diagnostics are replayed on attach; subsequent ones fan out. */
+    diagnostic?(entry: HubDiagnostic): void;
+}
+export interface HubSettings {
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly cwd: string;
+    /** Credential mode and channel-private env participate in hub identity. */
+    readonly credentialMode?: 'codex' | 'external' | 'channel' | 'native-fallback';
+    readonly injectedEnvKeys?: readonly string[];
+}
+export interface CodexHubDeps {
+    readonly transportFactory?: TransportFactory;
+    readonly clock?: RpcClock;
+    readonly debug?: (message: string) => void;
+    /** One child stderr line (never the terminal). */
+    readonly stderr?: (line: string) => void;
+    /** Idle time before an unused hub closes (default 30 s). */
+    readonly idleMs?: number;
+    /** Restart backoff; its length is the attempt budget. */
+    readonly restartDelaysMs?: readonly number[];
+    /** `clientInfo.version` (the dsh-tui version). */
+    readonly clientVersion?: string;
+    /** Bound on the `initialize` answer. */
+    readonly handshakeTimeoutMs?: number;
+}
+export type HubState = 'starting' | 'ready' | 'restarting' | 'failed' | 'closed';
+export interface CodexHub {
+    /** The current connection's handshake. */
+    readonly ready: Promise<InitializeInfo>;
+    readonly info: InitializeInfo | undefined;
+    readonly generation: number;
+    readonly state: HubState;
+    readonly fingerprint: string;
+    /** Last 200 diagnostics, including stderr emitted before a session attached. */
+    readonly diagnostics: readonly HubDiagnostic[];
+    /** One-time startup finding survives diagnostic-history eviction. */
+    readonly bubblewrapMissing: boolean;
+    /** A request on the live connection (waits for its handshake). */
+    call<R = unknown>(method: string, params?: unknown, options?: CallOptions): Promise<R>;
+    attach(threadId: string, sink: ThreadSink): () => void;
+    /** Deliver another thread's traffic to the sink of `toThreadId` (a
+     *  subagent's thread to its parent session). */
+    route(threadId: string, toThreadId: string): () => void;
+    onGlobal(listener: (method: string, params: Rec) => void): () => void;
+    /** A handler for thread-less server requests (`account/…`). */
+    onGlobalRequest(method: string, handler: (request: HubServerRequest) => void): () => void;
+    retain(): () => void;
+    close(): Promise<void>;
+}
+/** A stable digest of what makes two hubs interchangeable (values hashed,
+ *  never kept). */
+export declare function hubFingerprint(settings: HubSettings): string;
+/** The thread a message concerns, when it names one. */
+export declare function threadOf(params: Rec): string | undefined;
+/** Create a hub (no registry: tests and the registry below). */
+export declare function createCodexHub(settings: HubSettings, deps?: CodexHubDeps): CodexHub;
+/** The process-wide hub for these settings (created on first use). */
+export declare function acquireCodexHub(settings: HubSettings, deps?: CodexHubDeps): CodexHub;
+/** Close every hub (the process exit path; tests). */
+export declare function closeAllCodexHubs(): Promise<void>;
+/** Parse a JSON-RPC answer's error message for a user (no params). */
+export declare const rpcErrorText: (error: unknown) => string;
+//# sourceMappingURL=hub.d.ts.map

package/lib/types/backends/codex/rpc/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/rpc/hub.ts"],"names":[],"mappings":"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"}