specrails-core 6.4.0 → 6.5.0

package/dist/agent-runtime/session/drivers/codex/argv.d.ts

@@ -0,0 +1,12 @@
+import type { SessionPolicy } from '../../domain/types.js';
+/**
+ * Names of MCP servers declared in the user's Codex config. `-c mcp_servers={}`
+ * does not remove them (overrides merge), so isolation disables each one.
+ */
+export declare function declaredCodexMcpServers(env?: NodeJS.ProcessEnv): string[];
+/**
+ * `codex app-server` argv for a policy. Sandbox and approvals travel in the
+ * JSON-RPC thread request; config-level switches go through `-c`.
+ */
+export declare function codexArgs(policy: SessionPolicy, declaredServers: readonly string[]): string[];
+export declare function codexSandbox(permissions: SessionPolicy['permissions']): 'danger-full-access' | 'workspace-write' | 'read-only';

package/dist/agent-runtime/session/drivers/codex/argv.js

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { nativeSubagentsAllowed } from '../../domain/policy.js';
+/** TOML string literal (basic string) for a `-c key=value` override. */
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+/** TOML key segment: bare when possible, quoted otherwise. */
+function tomlKey(name) {
+    return /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
+}
+/**
+ * Names of MCP servers declared in the user's Codex config. `-c mcp_servers={}`
+ * does not remove them (overrides merge), so isolation disables each one.
+ */
+export function declaredCodexMcpServers(env = process.env) {
+    const home = env.CODEX_HOME ?? path.join(env.HOME ?? os.homedir(), '.codex');
+    const file = path.join(home, 'config.toml');
+    if (!existsSync(file))
+        return [];
+    const names = new Set();
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+        const match = /^\s*\[\s*mcp_servers\.(?:"((?:[^"\\]|\\.)+)"|([A-Za-z0-9_-]+))\s*\]\s*(?:#.*)?$/.exec(line);
+        if (match)
+            names.add(match[1] ? JSON.parse(`"${match[1]}"`) : match[2]);
+    }
+    return [...names];
+}
+function serverOverrides(server) {
+    const key = `mcp_servers.${tomlKey(server.name)}`;
+    const values = [`${key}.enabled=true`];
+    if (server.url) {
+        values.push(`${key}.url=${tomlString(server.url)}`);
+        for (const [header, value] of Object.entries(server.headers ?? {}))
+            values.push(`${key}.http_headers.${tomlKey(header)}=${tomlString(value)}`);
+    }
+    else if (server.command) {
+        values.push(`${key}.command=${tomlString(server.command)}`);
+        values.push(`${key}.args=[${(server.args ?? []).map(tomlString).join(',')}]`);
+        for (const [name, value] of Object.entries(server.env ?? {}))
+            values.push(`${key}.env.${tomlKey(name)}=${tomlString(value)}`);
+    }
+    // Codex gates MCP tools it cannot classify; under approvalPolicy=never it refuses them.
+    if (server.autoApprove)
+        values.push(`${key}.default_tools_approval_mode="approve"`);
+    return values;
+}
+/**
+ * `codex app-server` argv for a policy. Sandbox and approvals travel in the
+ * JSON-RPC thread request; config-level switches go through `-c`.
+ */
+export function codexArgs(policy, declaredServers) {
+    const overrides = [];
+    if (!nativeSubagentsAllowed(policy))
+        overrides.push('features.multi_agent=false');
+    else if (policy.subagentRuntime.mode === 'native') {
+        // Verified live (codex-cli 0.160.1): a luna parent ran a terra/low child.
+        if (policy.subagentRuntime.model)
+            overrides.push(`agents.default_subagent_model=${tomlString(policy.subagentRuntime.model)}`);
+        if (policy.subagentRuntime.effort)
+            overrides.push(`agents.default_subagent_reasoning_effort=${tomlString(policy.subagentRuntime.effort)}`);
+    }
+    const wanted = new Set(policy.mcp.servers.map((server) => server.name));
+    if (!policy.mcp.inheritUserScope) {
+        for (const name of declaredServers)
+            if (!wanted.has(name))
+                overrides.push(`mcp_servers.${tomlKey(name)}.enabled=false`);
+    }
+    for (const server of policy.mcp.servers)
+        overrides.push(...serverOverrides(server));
+    return [...overrides.flatMap((value) => ['-c', value]), 'app-server', '--listen', 'stdio://'];
+}
+export function codexSandbox(permissions) {
+    return permissions === 'bypass' ? 'danger-full-access' : permissions === 'read-only' ? 'read-only' : 'workspace-write';
+}

package/dist/agent-runtime/session/drivers/codex/driver.d.ts

@@ -0,0 +1,19 @@
+import type { DriverDescriptor } from '../../domain/types.js';
+import type { DriverEventSink, DriverFactory, DriverOpenSpec, DriverSession } from '../../ports.js';
+import { type ProcessSpawner } from '../common/process.js';
+export declare const CODEX_DESCRIPTOR: DriverDescriptor;
+export interface CodexDriverOptions {
+    binary?: string;
+    spawner?: ProcessSpawner;
+    env?: NodeJS.ProcessEnv;
+    terminateGraceMs?: number;
+    rpcTimeoutMs?: number;
+    /** Override discovery of the user's declared MCP servers (tests). */
+    declaredMcpServers?: string[];
+}
+export declare class CodexDriverFactory implements DriverFactory {
+    private readonly options;
+    readonly descriptor: DriverDescriptor;
+    constructor(options?: CodexDriverOptions);
+    open(spec: DriverOpenSpec, sink: DriverEventSink): Promise<DriverSession>;
+}

package/dist/agent-runtime/session/drivers/codex/driver.js

@@ -0,0 +1,193 @@
+import { spawnResidentProcess } from '../common/process.js';
+import { codexArgs, codexSandbox, declaredCodexMcpServers } from './argv.js';
+import { JsonRpcPeer, RpcError } from './rpc.js';
+import { CodexTranslator } from './translator.js';
+export const CODEX_DESCRIPTOR = Object.freeze({
+    id: 'codex',
+    displayName: 'Codex',
+    testedVersions: ['0.153.4', '0.160.1'],
+    capabilities: Object.freeze({
+        resident: true,
+        // Codex starts a turn per request; the application holds input while one runs.
+        nativeInputQueue: false,
+        subagents: 'supported',
+        subagentDisable: true,
+        subagentModel: true,
+        subagentEffort: true,
+        // The parent only reacts to finished sub-agents through `wait` or new input.
+        autonomousContinuation: false,
+        steer: true,
+        toolFiltering: false,
+        usage: Object.freeze({ costUsd: 'none', tokens: 'cumulative' }),
+    }),
+});
+function userInput(input) {
+    const images = (input.attachments ?? []).filter((item) => item.kind === 'image');
+    const files = (input.attachments ?? []).filter((item) => item.kind === 'file');
+    const text = files.length ? `${input.text}\n\nAttached files:\n${files.map((file) => `- ${file.path}`).join('\n')}` : input.text;
+    return [{ type: 'text', text, text_elements: [] }, ...images.map((image) => ({ type: 'localImage', path: image.path }))];
+}
+class CodexDriverSession {
+    child;
+    peer;
+    translator;
+    threadId;
+    spec;
+    sink;
+    graceMs;
+    markClosing;
+    pendingStops;
+    closing = null;
+    constructor(child, peer, translator, threadId, spec, sink, graceMs, markClosing, 
+    /** Children asked to stop before their first turn started (0.160 announces them first). */
+    pendingStops) {
+        this.child = child;
+        this.peer = peer;
+        this.translator = translator;
+        this.threadId = threadId;
+        this.spec = spec;
+        this.sink = sink;
+        this.graceMs = graceMs;
+        this.markClosing = markClosing;
+        this.pendingStops = pendingStops;
+    }
+    async send(input) {
+        const activeTurn = this.translator.activeTurnId;
+        if (activeTurn && input.delivery === 'steer') {
+            await this.peer.request('turn/steer', { threadId: this.threadId, expectedTurnId: activeTurn, clientUserMessageId: input.inputId, input: userInput(input) });
+            this.sink({ kind: 'input.receipt', inputId: input.inputId, state: 'started' });
+            return;
+        }
+        this.translator.noteTurnRequested(input.inputId);
+        await this.peer.request('turn/start', {
+            threadId: this.threadId,
+            clientUserMessageId: input.inputId,
+            input: userInput(input),
+            model: this.spec.model,
+            ...(this.spec.effort ? { effort: this.spec.effort } : {}),
+        });
+        this.sink({ kind: 'input.receipt', inputId: input.inputId, state: 'started' });
+    }
+    async interrupt() {
+        const turnId = this.translator.activeTurnId;
+        if (!turnId)
+            return;
+        this.translator.noteInterrupt();
+        await this.peer.request('turn/interrupt', { threadId: this.threadId, turnId });
+    }
+    /** Children are threads: each live one is interrupted on its own thread. */
+    async stopSubagents(ids) {
+        const targets = this.translator.liveChildren().filter((child) => !ids || ids.includes(child.threadId));
+        const stopped = [];
+        // A child announced but not yet running is interrupted as soon as its turn starts.
+        for (const id of ids ?? []) {
+            if (this.translator.isChild(id) && !this.translator.childTurnOf(id)) {
+                this.pendingStops.add(id);
+                stopped.push(id);
+            }
+        }
+        for (const target of targets) {
+            try {
+                await this.peer.request('turn/interrupt', { threadId: target.threadId, turnId: target.turnId });
+                stopped.push(target.threadId);
+            }
+            catch (error) {
+                this.sink({ kind: 'diagnostic', level: 'warning', code: 'provider.stop_failed', message: `${target.threadId}: ${error.message}` });
+            }
+        }
+        return stopped;
+    }
+    close(_reason) {
+        this.closing ??= (async () => {
+            this.markClosing();
+            this.peer.close('Codex session closed');
+            this.child.endInput();
+            await this.child.terminate(this.graceMs);
+        })();
+        return this.closing;
+    }
+}
+export class CodexDriverFactory {
+    options;
+    descriptor = CODEX_DESCRIPTOR;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async open(spec, sink) {
+        const env = { ...(this.options.env ?? process.env) };
+        const declared = this.options.declaredMcpServers ?? declaredCodexMcpServers(env);
+        const translator = new CodexTranslator();
+        const pendingStops = new Set();
+        let closeRequested = false;
+        let ended = false;
+        let peer = null;
+        const spawner = this.options.spawner ?? spawnResidentProcess;
+        const child = spawner({ command: this.options.binary ?? 'codex', args: codexArgs(spec.policy, declared), cwd: spec.cwd, env }, {
+            onLine: (line) => {
+                if (ended)
+                    return;
+                let frame;
+                try {
+                    frame = JSON.parse(line);
+                }
+                catch {
+                    sink({ kind: 'diagnostic', level: 'warning', code: 'provider.unparseable', message: line.slice(0, 500) });
+                    return;
+                }
+                peer?.receive(frame);
+            },
+        });
+        peer = new JsonRpcPeer((line) => child.write(line), {
+            onNotification: (method, params) => {
+                for (const event of translator.notification(method, params))
+                    sink(event);
+                const threadId = typeof params.threadId === 'string' ? params.threadId : null;
+                const turnId = threadId ? translator.childTurnOf(threadId) : null;
+                if (method === 'turn/started' && threadId && turnId && pendingStops.delete(threadId)) {
+                    void peer?.request('turn/interrupt', { threadId, turnId }).catch((error) => sink({ kind: 'diagnostic', level: 'warning', code: 'provider.stop_failed', message: `${threadId}: ${error.message}` }));
+                }
+            },
+            onRequest: (method) => {
+                // approvalPolicy is `never`; a request still arriving is declined (the sandbox is the boundary).
+                if (method === 'item/commandExecution/requestApproval' || method === 'item/fileChange/requestApproval')
+                    return { decision: 'decline' };
+                if (method === 'item/tool/requestUserInput')
+                    return { answers: {} };
+                throw new RpcError(`Unsupported client request ${method}`, -32601);
+            },
+        }, this.options.rpcTimeoutMs ?? 60_000);
+        void child.exited.then((exit) => {
+            peer?.close('Codex app-server exited');
+            if (!ended && !closeRequested)
+                sink({ kind: 'process.exited', exitCode: exit.exitCode, signal: exit.signal });
+            ended = true;
+        });
+        try {
+            await peer.request('initialize', { clientInfo: { name: 'specrails_core', title: 'Specrails Core', version: '1' }, capabilities: { experimentalApi: true } });
+            peer.notify('initialized');
+            const thread = await peer.request(spec.providerSessionRef ? 'thread/resume' : 'thread/start', {
+                ...(spec.providerSessionRef ? { threadId: spec.providerSessionRef } : {}),
+                model: spec.model,
+                cwd: spec.cwd,
+                approvalPolicy: 'never',
+                sandbox: codexSandbox(spec.policy.permissions),
+                ...(spec.systemPrompt ? { developerInstructions: spec.systemPrompt } : {}),
+            });
+            const threadId = typeof thread.thread?.id === 'string' ? thread.thread.id : null;
+            if (!threadId)
+                throw new Error('Codex did not return a thread id');
+            if (spec.providerSessionRef && threadId !== spec.providerSessionRef)
+                throw new Error('Codex resumed an unexpected thread');
+            translator.setRoot(threadId, spec.model);
+            sink({ kind: 'process.started', ...(child.pid !== undefined ? { pid: child.pid } : {}) });
+            sink({ kind: 'provider.ref', providerSessionRef: threadId });
+            return new CodexDriverSession(child, peer, translator, threadId, spec, sink, this.options.terminateGraceMs ?? 5_000, () => { closeRequested = true; }, pendingStops);
+        }
+        catch (error) {
+            closeRequested = true;
+            peer.close('Codex session failed to start');
+            await child.terminate(this.options.terminateGraceMs ?? 5_000);
+            throw error;
+        }
+    }
+}

package/dist/agent-runtime/session/drivers/codex/rpc.d.ts

@@ -0,0 +1,28 @@
+/** Minimal JSON-RPC 2.0 peer over newline-delimited frames (Codex app-server). */
+type Json = Record<string, unknown>;
+export declare class RpcError extends Error {
+    readonly code?: number | undefined;
+    constructor(message: string, code?: number | undefined);
+}
+export interface RpcHandlers {
+    /** Server notification. */
+    onNotification(method: string, params: Json): void;
+    /** Server request; return the result (or throw RpcError to answer with an error). */
+    onRequest(method: string, params: Json): Json;
+}
+export declare class JsonRpcPeer {
+    private readonly write;
+    private readonly handlers;
+    private readonly timeoutMs;
+    private nextId;
+    private readonly pending;
+    private closedError;
+    constructor(write: (line: string) => boolean, handlers: RpcHandlers, timeoutMs?: number);
+    request(method: string, params: Json): Promise<Json>;
+    notify(method: string, params?: Json): void;
+    /** Feed one stdout line. */
+    receive(frame: Json): void;
+    /** Reject everything in flight (process ended). */
+    close(reason: string): void;
+}
+export {};

package/dist/agent-runtime/session/drivers/codex/rpc.js

@@ -0,0 +1,81 @@
+export class RpcError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'RpcError';
+    }
+}
+export class JsonRpcPeer {
+    write;
+    handlers;
+    timeoutMs;
+    nextId = 1;
+    pending = new Map();
+    closedError = null;
+    constructor(write, handlers, timeoutMs = 60_000) {
+        this.write = write;
+        this.handlers = handlers;
+        this.timeoutMs = timeoutMs;
+    }
+    request(method, params) {
+        if (this.closedError)
+            return Promise.reject(this.closedError);
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new RpcError(`Codex app-server did not answer ${method} in time`));
+            }, this.timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { method, resolve, reject, timer });
+            if (!this.write(JSON.stringify({ id, method, params }))) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new RpcError('Codex app-server input is closed'));
+            }
+        });
+    }
+    notify(method, params) {
+        this.write(JSON.stringify(params ? { method, params } : { method }));
+    }
+    /** Feed one stdout line. */
+    receive(frame) {
+        const id = frame.id;
+        if (typeof frame.method === 'string') {
+            if (typeof id === 'number' || typeof id === 'string') {
+                try {
+                    this.write(JSON.stringify({ id, result: this.handlers.onRequest(frame.method, (frame.params ?? {})) }));
+                }
+                catch (error) {
+                    this.write(JSON.stringify({ id, error: { code: error instanceof RpcError ? error.code ?? -32603 : -32603, message: error.message } }));
+                }
+            }
+            else
+                this.handlers.onNotification(frame.method, (frame.params ?? {}));
+            return;
+        }
+        if (typeof id !== 'number')
+            return;
+        const request = this.pending.get(id);
+        if (!request)
+            return;
+        this.pending.delete(id);
+        clearTimeout(request.timer);
+        if (frame.error && typeof frame.error === 'object') {
+            const error = frame.error;
+            request.reject(new RpcError(typeof error.message === 'string' ? error.message : `Codex rejected ${request.method}`, typeof error.code === 'number' ? error.code : undefined));
+        }
+        else
+            request.resolve((frame.result ?? {}));
+    }
+    /** Reject everything in flight (process ended). */
+    close(reason) {
+        this.closedError = new RpcError(reason);
+        for (const [id, request] of this.pending) {
+            clearTimeout(request.timer);
+            request.reject(this.closedError);
+            this.pending.delete(id);
+        }
+    }
+}

package/dist/agent-runtime/session/drivers/codex/translator.d.ts

@@ -0,0 +1,53 @@
+import type { DriverEvent } from '../../ports.js';
+/**
+ * Anti-corruption layer for `codex app-server` notifications (codex-cli 0.153.4
+ * and 0.160.1). Deterministic and free of I/O. Pinned by the recorded transcripts:
+ * - the session is one root thread; sub-agents are child threads. 0.153 announces
+ *   them with a `collabAgentToolCall` (`spawnAgent`, `receiverThreadIds`); 0.160
+ *   with a `subAgentActivity` item (`kind: started`, `agentThreadId`, `agentPath`)
+ *   and no prompt, so the description comes from the agent's path name;
+ * - every thread streams its own turn/item/tokenUsage notifications, interleaved;
+ * - children keep running after the parent's turn completes; the parent never
+ *   continues on its own (it collects them with `wait`).
+ */
+type Json = Record<string, unknown>;
+export declare class CodexTranslator {
+    private rootThread;
+    private rootTurn;
+    /** Inputs whose `turn/start` was acknowledged, waiting for the turn notification. */
+    private pendingInputs;
+    private rootText;
+    private rootFinal;
+    private readonly streamed;
+    private readonly startedTools;
+    private readonly completedItems;
+    /** child thread → owner (null = root agent, else the owning child thread). */
+    private readonly children;
+    private readonly childTurn;
+    private readonly childPhase;
+    private readonly childLastText;
+    private rootUsage;
+    private model;
+    private interruptRequested;
+    setRoot(threadId: string, model: string | null): void;
+    get activeTurnId(): string | null;
+    noteTurnRequested(inputId: string): void;
+    noteInterrupt(): void;
+    /** Child threads with a turn in progress. */
+    liveChildren(): Array<{
+        threadId: string;
+        turnId: string;
+    }>;
+    /** A registered child thread (live or not). */
+    isChild(threadId: string): boolean;
+    /** The turn a child is running, if any. */
+    childTurnOf(threadId: string): string | null;
+    notification(method: string, params: Json): DriverEvent[];
+    private root;
+    private child;
+    private item;
+    private collab;
+    private registerChild;
+    private roster;
+}
+export {};