specrails-core 6.3.0 → 6.5.0

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

@@ -0,0 +1,267 @@
+const TOOL_ITEMS = new Set(['commandExecution', 'mcpToolCall', 'fileChange', 'dynamicToolCall', 'collabAgentToolCall', 'webSearch']);
+const str = (value) => (typeof value === 'string' ? value : undefined);
+const obj = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
+function preview(value, limit = 16_384) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');
+    return text.length > limit ? `${text.slice(0, limit)}…` : text;
+}
+function toolName(item) {
+    const type = str(item.type) ?? 'tool';
+    if (type === 'mcpToolCall')
+        return `${str(item.server) ?? 'mcp'}.${str(item.tool) ?? 'tool'}`;
+    if (type === 'collabAgentToolCall')
+        return `agent.${str(item.tool) ?? 'call'}`;
+    return type;
+}
+function toolFailed(item) {
+    return ['failed', 'declined'].includes(str(item.status) ?? '') || item.success === false || (typeof item.exitCode === 'number' && item.exitCode !== 0) || !!item.error;
+}
+/** `/root/run_tests` → `run tests` (0.160 sub-agents are named, not described). */
+function describeAgentPath(agentPath) {
+    const name = agentPath?.split('/').filter(Boolean).pop() ?? '';
+    return name.replace(/[_-]+/g, ' ').trim().slice(0, 200);
+}
+function tokens(usage) {
+    return {
+        inputTokens: num(usage.inputTokens),
+        outputTokens: num(usage.outputTokens),
+        cacheReadTokens: num(usage.cachedInputTokens),
+        cacheWriteTokens: num(usage.cacheWriteInputTokens),
+        totalTokens: num(usage.totalTokens),
+    };
+}
+export class CodexTranslator {
+    rootThread = null;
+    rootTurn = null;
+    /** Inputs whose `turn/start` was acknowledged, waiting for the turn notification. */
+    pendingInputs = [];
+    rootText = '';
+    rootFinal = null;
+    streamed = new Map();
+    startedTools = new Set();
+    completedItems = new Set();
+    /** child thread → owner (null = root agent, else the owning child thread). */
+    children = new Map();
+    childTurn = new Map();
+    childPhase = new Map();
+    childLastText = new Map();
+    rootUsage = null;
+    model = null;
+    interruptRequested = false;
+    setRoot(threadId, model) { this.rootThread = threadId; this.model = model; }
+    get activeTurnId() { return this.rootTurn; }
+    noteTurnRequested(inputId) { this.pendingInputs.push(inputId); }
+    noteInterrupt() { if (this.rootTurn)
+        this.interruptRequested = true; }
+    /** Child threads with a turn in progress. */
+    liveChildren() {
+        return [...this.childTurn.entries()].filter((entry) => entry[1] !== null).map(([threadId, turnId]) => ({ threadId, turnId }));
+    }
+    /** A registered child thread (live or not). */
+    isChild(threadId) { return this.children.has(threadId); }
+    /** The turn a child is running, if any. */
+    childTurnOf(threadId) { return this.childTurn.get(threadId) ?? null; }
+    notification(method, params) {
+        const threadId = str(params.threadId);
+        if (method === 'error') {
+            const message = str(obj(params.error).message) ?? 'Codex reported an error';
+            return [{ kind: 'diagnostic', level: 'warning', code: params.willRetry === true ? 'provider.retrying' : 'provider.error', message: message.slice(0, 2_000) }];
+        }
+        if (!threadId)
+            return [];
+        if (threadId === this.rootThread)
+            return this.root(method, params);
+        if (this.children.has(threadId))
+            return this.child(threadId, method, params);
+        return [];
+    }
+    // ── root thread ───────────────────────────────────────────────────────────
+    root(method, params) {
+        switch (method) {
+            case 'turn/started': {
+                const turnId = str(obj(params.turn).id);
+                if (!turnId || this.rootTurn === turnId)
+                    return [];
+                this.rootTurn = turnId;
+                this.rootText = '';
+                this.rootFinal = null;
+                const inputIds = this.pendingInputs;
+                this.pendingInputs = [];
+                return [{ kind: 'turn.started', trigger: inputIds.length > 0 ? 'input' : 'continuation', inputIds }];
+            }
+            case 'item/agentMessage/delta': {
+                const delta = str(params.delta);
+                const itemId = str(params.itemId);
+                if (!delta || !itemId || this.completedItems.has(itemId))
+                    return [];
+                this.streamed.set(itemId, (this.streamed.get(itemId) ?? '') + delta);
+                return [{ kind: 'turn.output', channel: 'text', delta }];
+            }
+            case 'item/started':
+            case 'item/completed':
+                return this.item(null, obj(params.item), method === 'item/completed');
+            case 'thread/tokenUsage/updated':
+                this.rootUsage = obj(obj(params.tokenUsage).total);
+                return [];
+            case 'turn/completed': {
+                const turn = obj(params.turn);
+                if (!this.rootTurn || str(turn.id) !== this.rootTurn)
+                    return [];
+                const events = [];
+                for (const item of Array.isArray(turn.items) ? turn.items : [])
+                    events.push(...this.item(null, item, true));
+                const status = str(turn.status);
+                const interrupted = this.interruptRequested || status === 'interrupted';
+                this.interruptRequested = false;
+                this.rootTurn = null;
+                const error = str(obj(turn.error).message);
+                events.push({
+                    kind: 'turn.completed',
+                    status: interrupted ? 'stopped' : status === 'failed' ? 'failed' : 'completed',
+                    text: this.rootFinal ?? this.rootText,
+                    ...(status === 'failed' && !interrupted ? { error: error ?? 'Codex turn failed' } : {}),
+                    usage: { ...(this.rootUsage ? tokens(this.rootUsage) : {}), model: this.model },
+                });
+                return events;
+            }
+            default:
+                return [];
+        }
+    }
+    // ── child threads (sub-agents) ────────────────────────────────────────────
+    child(threadId, method, params) {
+        switch (method) {
+            case 'turn/started': {
+                const turnId = str(obj(params.turn).id) ?? null;
+                this.childTurn.set(threadId, turnId);
+                const events = [];
+                if (this.childPhase.get(threadId) !== 'running') {
+                    // Re-entry (the parent sent it more work): restart under the same id.
+                    if (this.childPhase.has(threadId))
+                        events.push({ kind: 'subagent.started', subagentId: threadId, parentId: this.children.get(threadId) ?? null, agentKind: 'background', agentType: 'codex-agent', description: 'Sub-agent' });
+                    this.childPhase.set(threadId, 'running');
+                }
+                events.push(this.roster());
+                return events;
+            }
+            case 'item/agentMessage/delta': {
+                const delta = str(params.delta);
+                const itemId = str(params.itemId);
+                if (!delta || !itemId || this.completedItems.has(itemId))
+                    return [];
+                this.streamed.set(itemId, (this.streamed.get(itemId) ?? '') + delta);
+                return [{ kind: 'subagent.output', subagentId: threadId, channel: 'text', delta }];
+            }
+            case 'item/started':
+            case 'item/completed':
+                return this.item(threadId, obj(params.item), method === 'item/completed');
+            case 'thread/tokenUsage/updated':
+                return [{ kind: 'subagent.usage', subagentId: threadId, usage: tokens(obj(obj(params.tokenUsage).total)) }];
+            case 'turn/completed': {
+                const turn = obj(params.turn);
+                this.childTurn.set(threadId, null);
+                const status = str(turn.status);
+                const phase = status === 'failed' ? 'failed' : status === 'interrupted' ? 'stopped' : 'idle';
+                const events = [];
+                for (const item of Array.isArray(turn.items) ? turn.items : [])
+                    events.push(...this.item(threadId, item, true));
+                const summary = this.childLastText.get(threadId);
+                if (phase === 'idle' && summary)
+                    events.push({ kind: 'subagent.result', subagentId: threadId, summary });
+                if (this.childPhase.get(threadId) !== phase) {
+                    this.childPhase.set(threadId, phase);
+                    events.push({ kind: 'subagent.phase', subagentId: threadId, phase });
+                }
+                events.push(this.roster());
+                return events;
+            }
+            default:
+                return [];
+        }
+    }
+    // ── items ─────────────────────────────────────────────────────────────────
+    item(owner, item, completed) {
+        const id = str(item.id);
+        const type = str(item.type);
+        if (!id || !type || this.completedItems.has(id))
+            return [];
+        const events = [];
+        if (type === 'agentMessage') {
+            if (!completed)
+                return [];
+            const text = str(item.text) ?? '';
+            const already = this.streamed.get(id) ?? '';
+            const rest = text.startsWith(already) ? text.slice(already.length) : '';
+            if (rest)
+                events.push(owner === null ? { kind: 'turn.output', channel: 'text', delta: rest } : { kind: 'subagent.output', subagentId: owner, channel: 'text', delta: rest });
+            if (owner === null) {
+                this.rootText = this.rootText ? `${this.rootText}\n\n${text}` : text;
+                if (item.phase === 'final_answer')
+                    this.rootFinal = text;
+            }
+            else if (text)
+                this.childLastText.set(owner, text);
+        }
+        else if (type === 'subAgentActivity') {
+            // Child turns carry progress, results and phase; only the start registers.
+            if (str(item.kind) === 'started')
+                events.push(...this.registerChild(owner, str(item.agentThreadId), describeAgentPath(str(item.agentPath))));
+        }
+        else if (TOOL_ITEMS.has(type)) {
+            const name = toolName(item);
+            if (!this.startedTools.has(id)) {
+                this.startedTools.add(id);
+                const tool = { toolUseId: id, name, phase: 'started', input: item.command ?? item.arguments ?? item.changes ?? item.prompt ?? item.query ?? null };
+                events.push(owner === null ? { kind: 'turn.tool', ...tool } : { kind: 'subagent.output', subagentId: owner, channel: 'tool', tool });
+            }
+            if (completed) {
+                if (type === 'collabAgentToolCall')
+                    events.push(...this.collab(owner, item));
+                const tool = { toolUseId: id, name, phase: 'completed', output: preview(item.aggregatedOutput ?? item.result ?? item.error ?? item.agentsStates ?? { status: item.status }), ...(toolFailed(item) ? { isError: true } : {}) };
+                events.push(owner === null ? { kind: 'turn.tool', ...tool } : { kind: 'subagent.output', subagentId: owner, channel: 'tool', tool });
+            }
+        }
+        if (completed)
+            this.completedItems.add(id);
+        return events;
+    }
+    collab(owner, item) {
+        const events = [];
+        if (str(item.tool) === 'spawnAgent') {
+            const prompt = str(item.prompt) ?? '';
+            for (const childId of Array.isArray(item.receiverThreadIds) ? item.receiverThreadIds : []) {
+                if (typeof childId === 'string')
+                    events.push(...this.registerChild(owner, childId, (prompt.split('\n')[0] ?? '').slice(0, 200), prompt));
+            }
+        }
+        // `wait` reports the final message of finished children.
+        for (const [childId, state] of Object.entries(obj(item.agentsStates))) {
+            const message = str(obj(state).message);
+            if (this.children.has(childId) && obj(state).status === 'completed' && message && message !== this.childLastText.get(childId)) {
+                this.childLastText.set(childId, message);
+                events.push({ kind: 'subagent.result', subagentId: childId, summary: message });
+            }
+        }
+        return events;
+    }
+    registerChild(owner, childId, description, prompt = '') {
+        if (!childId || this.children.has(childId))
+            return [];
+        this.children.set(childId, owner);
+        this.childPhase.set(childId, 'running');
+        this.childTurn.set(childId, this.childTurn.get(childId) ?? null);
+        return [{
+                kind: 'subagent.started',
+                subagentId: childId,
+                parentId: owner,
+                agentKind: 'background',
+                agentType: 'codex-agent',
+                description: description || 'Sub-agent',
+                ...(prompt ? { prompt } : {}),
+            }];
+    }
+    roster() {
+        return { kind: 'roster', liveSubagentIds: this.liveChildren().map((child) => child.threadId) };
+    }
+}

package/dist/agent-runtime/session/drivers/common/process.d.ts

@@ -0,0 +1,37 @@
+export interface ProcessSpec {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export interface ProcessHandlers {
+    /** One complete stdout line (without the trailing newline). */
+    onLine(line: string): void;
+    /** Bounded stderr tail updates, for diagnostics only. */
+    onStderr?(chunk: string): void;
+}
+export interface ProcessExit {
+    exitCode: number | null;
+    signal: string | null;
+}
+/**
+ * A long-lived provider process with line-oriented stdout. Unlike the one-shot
+ * `runCliProcess`, nothing accumulates: lines are handed over as they arrive.
+ */
+export interface ProviderProcess {
+    readonly pid: number | undefined;
+    /** Write one line to stdin; false when input is already closed. */
+    write(line: string): boolean;
+    endInput(): void;
+    /**
+     * Ask the whole process tree to stop (SIGTERM / taskkill), then force it
+     * (SIGKILL / taskkill /F) after `graceMs`. Resolves once the process exited.
+     */
+    terminate(graceMs: number): Promise<ProcessExit>;
+    readonly exited: Promise<ProcessExit>;
+}
+export type ProcessSpawner = (spec: ProcessSpec, handlers: ProcessHandlers) => ProviderProcess;
+/** Longest stdout line accepted; longer lines are dropped and reported. */
+export declare const MAX_LINE_BYTES: number;
+/** Production spawner: cross-spawn, own process group on POSIX, tree-kill on every platform. */
+export declare const spawnResidentProcess: ProcessSpawner;

package/dist/agent-runtime/session/drivers/common/process.js

@@ -0,0 +1,116 @@
+import crossSpawn from 'cross-spawn';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { cliProcessEnvironment } from '../../../cli-process.js';
+/** Longest stdout line accepted; longer lines are dropped and reported. */
+export const MAX_LINE_BYTES = 16 * 1024 * 1024;
+/** Production spawner: cross-spawn, own process group on POSIX, tree-kill on every platform. */
+export const spawnResidentProcess = (spec, handlers) => {
+    const env = cliProcessEnvironment(spec.env);
+    const child = crossSpawn(spec.command, spec.args, {
+        cwd: spec.cwd,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: false,
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+    });
+    const decoder = new StringDecoder('utf8');
+    let pending = '';
+    let inputOpen = true;
+    let exit = null;
+    const exited = new Promise((resolve) => {
+        child.once('error', (error) => {
+            handlers.onStderr?.(`spawn error: ${error.message}`);
+            if (!exit) {
+                exit = { exitCode: null, signal: 'spawn-error' };
+                resolve(exit);
+            }
+        });
+        child.once('close', (code, signal) => {
+            const rest = pending + decoder.end();
+            pending = '';
+            if (rest.trim())
+                handlers.onLine(rest.replace(/\r$/, ''));
+            if (!exit) {
+                exit = { exitCode: code, signal };
+                resolve(exit);
+            }
+        });
+    });
+    child.stdout?.on('data', (chunk) => {
+        pending += decoder.write(chunk);
+        for (;;) {
+            const newline = pending.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = pending.slice(0, newline).replace(/\r$/, '');
+            pending = pending.slice(newline + 1);
+            if (line.length > 0)
+                handlers.onLine(line);
+        }
+        if (Buffer.byteLength(pending) > MAX_LINE_BYTES) {
+            handlers.onStderr?.(`dropped an stdout line larger than ${MAX_LINE_BYTES} bytes`);
+            pending = '';
+        }
+    });
+    child.stderr?.on('data', (chunk) => handlers.onStderr?.(chunk.toString('utf8').slice(-8_192)));
+    child.stdin?.on('error', () => { inputOpen = false; });
+    const signalTree = (force) => {
+        const pid = child.pid;
+        if (!pid || exit)
+            return;
+        if (process.platform === 'win32') {
+            const taskkill = path.win32.join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'taskkill.exe');
+            execFile(taskkill, ['/PID', String(pid), '/T', ...(force ? ['/F'] : [])], { windowsHide: true, env, timeout: 10_000 }, () => {
+                if (force) {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch { /* already exited */ }
+                }
+            });
+            return;
+        }
+        try {
+            process.kill(-pid, force ? 'SIGKILL' : 'SIGTERM');
+        }
+        catch {
+            try {
+                child.kill(force ? 'SIGKILL' : 'SIGTERM');
+            }
+            catch { /* already exited */ }
+        }
+    };
+    let termination = null;
+    return {
+        get pid() { return child.pid; },
+        exited,
+        write(line) {
+            if (!inputOpen || exit || !child.stdin || child.stdin.destroyed)
+                return false;
+            child.stdin.write(`${line}\n`, 'utf8');
+            return true;
+        },
+        endInput() {
+            if (!inputOpen)
+                return;
+            inputOpen = false;
+            child.stdin?.end();
+        },
+        terminate(graceMs) {
+            if (exit)
+                return Promise.resolve(exit);
+            termination ??= (async () => {
+                signalTree(false);
+                let timer;
+                const forced = new Promise((resolve) => { timer = setTimeout(() => { signalTree(true); resolve(); }, Math.max(0, graceMs)); });
+                const result = await Promise.race([exited, forced.then(() => exited)]);
+                clearTimeout(timer);
+                return result;
+            })();
+            return termination;
+        },
+    };
+};

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

@@ -0,0 +1,22 @@
+import { type AgentExecutor } from '../../../executor-types.js';
+import type { DriverDescriptor } from '../../domain/types.js';
+import type { DriverEventSink, DriverFactory, DriverOpenSpec, DriverSession } from '../../ports.js';
+/**
+ * Adapter from the batch `AgentExecutor` contract (one request, one result) to
+ * the session driver contract. Each input runs as one executor invocation that
+ * resumes the provider session when the executor supports continuation.
+ * Declares exactly what it cannot do; the application adapts to it.
+ */
+export declare function executorDescriptor(id: string, displayName: string): DriverDescriptor;
+export interface ExecutorDriverOptions {
+    /** Per-invocation limits forwarded to the executor. */
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+}
+export declare class ExecutorDriverFactory implements DriverFactory {
+    readonly descriptor: DriverDescriptor;
+    private readonly executor;
+    private readonly options;
+    constructor(descriptor: DriverDescriptor, executor: AgentExecutor, options?: ExecutorDriverOptions);
+    open(spec: DriverOpenSpec, sink: DriverEventSink): Promise<DriverSession>;
+}

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

@@ -0,0 +1,163 @@
+import { AgentExecutionError } from '../../../executor-types.js';
+/**
+ * Adapter from the batch `AgentExecutor` contract (one request, one result) to
+ * the session driver contract. Each input runs as one executor invocation that
+ * resumes the provider session when the executor supports continuation.
+ * Declares exactly what it cannot do; the application adapts to it.
+ */
+export function executorDescriptor(id, displayName) {
+    return Object.freeze({
+        id,
+        displayName,
+        capabilities: Object.freeze({
+            resident: false,
+            nativeInputQueue: false,
+            subagents: 'unsupported',
+            subagentDisable: false,
+            subagentModel: false,
+            subagentEffort: false,
+            autonomousContinuation: false,
+            steer: false,
+            toolFiltering: false,
+            usage: Object.freeze({ costUsd: 'per-turn', tokens: 'per-turn' }),
+        }),
+    });
+}
+function reported(usage) {
+    return {
+        inputTokens: usage?.inputTokens ?? null,
+        outputTokens: usage?.outputTokens ?? null,
+        cacheReadTokens: usage?.cacheReadInputTokens ?? null,
+        cacheWriteTokens: usage?.cacheWriteInputTokens ?? null,
+        costUsd: usage?.costUsd ?? null,
+    };
+}
+class ExecutorDriverSession {
+    executor;
+    spec;
+    sink;
+    options;
+    running = null;
+    closed = false;
+    sessionRef;
+    toolSeq = 0;
+    firstTurn;
+    constructor(executor, spec, sink, options) {
+        this.executor = executor;
+        this.spec = spec;
+        this.sink = sink;
+        this.options = options;
+        this.sessionRef = spec.providerSessionRef;
+        this.firstTurn = spec.providerSessionRef === null;
+    }
+    async send(input) {
+        if (this.closed)
+            throw new Error('Session driver is closed');
+        if (this.running)
+            throw new Error('This provider runs one turn at a time');
+        const controller = new AbortController();
+        this.running = controller;
+        this.sink({ kind: 'input.receipt', inputId: input.inputId, state: 'started' });
+        this.sink({ kind: 'turn.started', trigger: 'input', inputIds: [input.inputId] });
+        // Run in the background: receipts and output arrive as events, like resident drivers.
+        void this.run(input, controller);
+    }
+    async run(input, controller) {
+        const openTools = [];
+        let text = '';
+        const files = (input.attachments ?? []).map((item) => `- ${item.path}`);
+        const prompt = [
+            this.firstTurn && this.spec.systemPrompt ? `${this.spec.systemPrompt}\n\n` : '',
+            input.text,
+            files.length ? `\n\nAttached files:\n${files.join('\n')}` : '',
+        ].join('');
+        try {
+            const result = await this.executor.execute({
+                role: 'session',
+                access: this.spec.policy.permissions === 'read-only' ? 'read' : 'write',
+                artifacts: 'none',
+                instructions: 'none',
+                prompt,
+                cwd: this.spec.cwd,
+                allowedRoots: [this.spec.cwd],
+                model: this.spec.model,
+                ...(this.spec.effort ? { effort: this.spec.effort } : {}),
+                ...(this.sessionRef ? { resumeSessionId: this.sessionRef } : {}),
+                ...(this.options.timeoutMs !== undefined ? { timeoutMs: this.options.timeoutMs } : {}),
+                ...(this.options.idleTimeoutMs !== undefined ? { idleTimeoutMs: this.options.idleTimeoutMs } : {}),
+                signal: controller.signal,
+                onEvent: (event) => {
+                    if (this.closed)
+                        return;
+                    if (event.kind === 'session' && event.sessionId && event.sessionId !== this.sessionRef) {
+                        this.sessionRef = event.sessionId;
+                        this.sink({ kind: 'provider.ref', providerSessionRef: event.sessionId });
+                    }
+                    else if (event.kind === 'text' && event.text) {
+                        text += event.text;
+                        this.sink({ kind: 'turn.output', channel: 'text', delta: event.text });
+                    }
+                    else if (event.kind === 'tool-start') {
+                        const id = `tool-${++this.toolSeq}`;
+                        openTools.push(id);
+                        this.sink({ kind: 'turn.tool', toolUseId: id, name: event.tool ?? 'tool', phase: 'started', ...(event.detail ? { input: event.detail } : {}) });
+                    }
+                    else if (event.kind === 'tool-end') {
+                        const id = openTools.shift();
+                        if (id)
+                            this.sink({ kind: 'turn.tool', toolUseId: id, name: event.tool ?? 'tool', phase: 'completed', ...(event.detail ? { output: event.detail } : {}) });
+                    }
+                },
+            });
+            this.firstTurn = false;
+            if (result.sessionId && result.sessionId !== this.sessionRef) {
+                this.sessionRef = result.sessionId;
+                this.sink({ kind: 'provider.ref', providerSessionRef: result.sessionId });
+            }
+            if (result.text && !text)
+                this.sink({ kind: 'turn.output', channel: 'text', delta: result.text });
+            this.sink({ kind: 'turn.completed', status: 'completed', text: result.text, usage: reported(result.usage) });
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            const failure = error instanceof AgentExecutionError ? error : null;
+            const stopped = failure?.code === 'aborted';
+            this.sink({
+                kind: 'turn.completed',
+                status: stopped ? 'stopped' : 'failed',
+                text,
+                ...(stopped ? {} : { error: error.message }),
+                usage: reported(failure?.usage),
+            });
+        }
+        finally {
+            if (this.running === controller)
+                this.running = null;
+        }
+    }
+    async interrupt() {
+        this.running?.abort();
+    }
+    async stopSubagents() {
+        return [];
+    }
+    async close(_reason) {
+        this.closed = true;
+        this.running?.abort();
+    }
+}
+export class ExecutorDriverFactory {
+    descriptor;
+    executor;
+    options;
+    constructor(descriptor, executor, options = {}) {
+        this.descriptor = descriptor;
+        this.executor = executor;
+        this.options = options;
+    }
+    async open(spec, sink) {
+        sink({ kind: 'process.started' });
+        return new ExecutorDriverSession(this.executor, spec, sink, this.options);
+    }
+}

package/dist/agent-runtime/session/drivers/registry.d.ts

@@ -0,0 +1,32 @@
+import type { AgentExecutor } from '../../executor-types.js';
+import type { DriverDescriptor } from '../domain/types.js';
+import type { DriverCatalog, DriverFactory } from '../ports.js';
+import { type ClaudeDriverOptions } from './claude/driver.js';
+import { type CodexDriverOptions } from './codex/driver.js';
+import { type ExecutorDriverOptions } from './executor/driver.js';
+/**
+ * Closed, frozen registry of session drivers (like the engine PieceRegistry).
+ * Adding a provider is a reviewed change: a drivers/<id>/ folder, an entry
+ * here, and a passing conformance run. Duplicate ids and invalid descriptors
+ * are rejected at construction.
+ */
+export declare class DriverRegistry implements DriverCatalog {
+    private readonly factories;
+    constructor(factories: readonly DriverFactory[]);
+    get(driverId: string): DriverFactory | undefined;
+    descriptors(): DriverDescriptor[];
+}
+export interface DriverRegistryOptions {
+    claude?: ClaudeDriverOptions | false;
+    codex?: CodexDriverOptions | false;
+    /** Non-resident providers backed by existing batch executors (Gemini, Kimi, OpenAI-compatible connections). */
+    executors?: Array<{
+        id: string;
+        displayName: string;
+        executor: AgentExecutor;
+        options?: ExecutorDriverOptions;
+    }>;
+    /** Extra factories (tests, embedding hosts). */
+    extra?: DriverFactory[];
+}
+export declare function createDriverRegistry(options?: DriverRegistryOptions): DriverRegistry;

package/dist/agent-runtime/session/drivers/registry.js

@@ -0,0 +1,38 @@
+import { validateDescriptor } from '../domain/descriptor.js';
+import { ClaudeDriverFactory } from './claude/driver.js';
+import { CodexDriverFactory } from './codex/driver.js';
+import { ExecutorDriverFactory, executorDescriptor } from './executor/driver.js';
+/**
+ * Closed, frozen registry of session drivers (like the engine PieceRegistry).
+ * Adding a provider is a reviewed change: a drivers/<id>/ folder, an entry
+ * here, and a passing conformance run. Duplicate ids and invalid descriptors
+ * are rejected at construction.
+ */
+export class DriverRegistry {
+    factories;
+    constructor(factories) {
+        const map = new Map();
+        for (const factory of factories) {
+            validateDescriptor(factory.descriptor);
+            if (map.has(factory.descriptor.id))
+                throw new Error(`Duplicate session driver "${factory.descriptor.id}"`);
+            map.set(factory.descriptor.id, factory);
+        }
+        this.factories = map;
+        Object.freeze(this);
+    }
+    get(driverId) {
+        return this.factories.get(driverId);
+    }
+    descriptors() {
+        return [...this.factories.values()].map((factory) => factory.descriptor);
+    }
+}
+export function createDriverRegistry(options = {}) {
+    return new DriverRegistry([
+        ...(options.claude === false ? [] : [new ClaudeDriverFactory(options.claude ?? {})]),
+        ...(options.codex === false ? [] : [new CodexDriverFactory(options.codex ?? {})]),
+        ...(options.executors ?? []).map((entry) => new ExecutorDriverFactory(executorDescriptor(entry.id, entry.displayName), entry.executor, entry.options ?? {})),
+        ...(options.extra ?? []),
+    ]);
+}