specrails-core 5.2.3 → 5.4.0

package/README.md

@@ -8,6 +8,8 @@ Specrails Core installs specification-driven development workflows into a projec
 
 Use Core directly from Claude Code, Codex CLI, Gemini CLI or Kimi Code. For mission conversations, a shared project board, execution loops and delivery controls, use [Specrails Desktop](https://github.com/fjpulidop/specrails-desktop).
 
+The current source also includes an opt-in [programmatic agent runtime](docs/agent-runtime.md): a shared LangGraph workflow with per-role providers, durable recovery and local OpenAI-compatible models. Its TypeScript API and CLI keep phase control in Core while the caller owns delivery.
+
 This README describes the current source tree. `npx specrails-core@latest` installs the published package, not unmerged changes. Check the [release notes](https://github.com/fjpulidop/specrails-core/releases), or [build this checkout](#develop-from-source) when testing unreleased work.
 
 ## Quick start
@@ -158,6 +160,7 @@ Core's configuration, specs and run state are local files. Provider CLIs still s
 
 - [CLI reference](docs/user-docs/cli-reference.md)
 - [Provider pipeline contracts](docs/user-docs/provider-pipelines.md)
+- [Programmatic agent runtime](docs/agent-runtime.md)
 - [Core update consistency](docs/user-docs/core-updates.md)
 - [Local tickets](docs/local-tickets.md)
 - [Documentation index](docs/README.md)

package/bin/specrails-core.mjs

@@ -62,6 +62,7 @@ const KNOWN_SUBCOMMANDS = new Set([
   'update',
   'doctor',
   'pipeline',
+  'runtime',
   'install-framework',
   'swap-current',
   'assemble',
@@ -399,6 +400,10 @@ async function runNodeCli(argv) {
     process.exit(1)
   }
   const code = await mod.main(argv)
+  // Let pipe writes drain before exiting; runtime status can exceed a pipe buffer.
+  await Promise.all([process.stdout, process.stderr].map(stream =>
+    new Promise((resolve, reject) => stream.write('', error => error ? reject(error) : resolve()))
+  ))
   process.exit(code)
 }
 

package/dist/agent-runtime/capabilities.d.ts

@@ -0,0 +1,27 @@
+import { type CliProcessRunner } from './cli-process.js';
+import { type CliProvider, type ExecutorCapabilities, type RuntimeAgentConfig, type RuntimeConfig } from './executor-types.js';
+import type { ExecutorRegistry } from './executors.js';
+export declare function unknownCapabilities(transport: string): ExecutorCapabilities;
+/** Introspection never calls an inference endpoint. A flag is not proof that
+ * a transport restores history, so built-in continuation stays conservative. */
+export declare function cliCapabilities(provider: CliProvider, model: string | undefined, options?: {
+    runProcess?: CliProcessRunner;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ExecutorCapabilities>;
+export declare function assertEffortSupported(selection: Pick<RuntimeAgentConfig, 'effort'>, capability: ExecutorCapabilities): void;
+export declare function configuredCapabilities(config: RuntimeConfig, registry: ExecutorRegistry): Promise<{
+    schemaVersion: 1;
+    roles: {
+        transport: string;
+        continuation: "supported" | "unsupported" | "unknown";
+        effortSupport: "supported" | "unsupported" | "unknown";
+        supportedEfforts: string[] | null;
+        observedModel: boolean;
+        observedEffort: boolean;
+        role: string;
+        tier: string;
+        provider: string;
+        model: string | null;
+        requestedEffort: string | null;
+    }[];
+}>;

package/dist/agent-runtime/capabilities.js

@@ -0,0 +1,73 @@
+import { readFileSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { runCliProcess } from './cli-process.js';
+import { AgentExecutionError } from './executor-types.js';
+export function unknownCapabilities(transport) {
+    return { transport, continuation: 'unknown', effortSupport: 'unknown', supportedEfforts: null, observedModel: false, observedEffort: false };
+}
+/** Introspection never calls an inference endpoint. A flag is not proof that
+ * a transport restores history, so built-in continuation stays conservative. */
+export async function cliCapabilities(provider, model, options = {}) {
+    const result = unknownCapabilities(provider === 'kimi' ? 'kimi-acp' : `${provider}-cli`);
+    if (provider === 'kimi')
+        return { ...result, continuation: 'unsupported', effortSupport: 'unsupported', supportedEfforts: [] };
+    if (provider === 'gemini')
+        return result;
+    const env = options.env ?? process.env;
+    try {
+        const runner = options.runProcess ?? runCliProcess;
+        const help = await runner({ command: provider, args: ['--help'] }, { cwd: tmpdir(), env, timeoutMs: 10_000 });
+        if (help.exitCode !== 0)
+            return result;
+        if (provider === 'claude') {
+            const section = /--effort\s+<[^>]+>([\s\S]*?)(?=\n\s+--|$)/.exec(help.stdout)?.[1];
+            const levels = section?.match(/\(([^)]+)\)/)?.[1].split(',').map(value => value.trim());
+            if (levels?.length && levels.every(value => /^[a-z][a-z0-9_-]{0,31}$/.test(value)))
+                return { ...result, effortSupport: 'supported', supportedEfforts: levels };
+        }
+        else if (model && help.stdout.includes('--config')) {
+            // Use the installed client's own bounded, fresh model catalog. Do not
+            // infer reasoning support from a model prefix or another provider.
+            const file = path.join(env.CODEX_HOME ?? path.join(env.HOME ?? homedir(), '.codex'), 'models_cache.json');
+            if (statSync(file).size > 2 * 1024 * 1024)
+                return result;
+            const cache = JSON.parse(readFileSync(file, 'utf8'));
+            const age = Date.now() - Date.parse(cache.fetched_at);
+            if (!Number.isFinite(age) || age < -60_000 || age > 24 * 60 * 60_000)
+                return result;
+            const version = await runner({ command: provider, args: ['--version'] }, { cwd: tmpdir(), env, timeoutMs: 10_000 });
+            if (version.exitCode !== 0 || version.stdout.trim() !== `codex-cli ${cache.client_version}`)
+                return result;
+            const entry = Array.isArray(cache.models) ? cache.models.find((item) => item?.slug === model) : undefined;
+            const levels = entry?.supported_reasoning_levels?.map((item) => item?.effort);
+            if (Array.isArray(levels) && levels.length && levels.every(value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(value))) {
+                return { ...result, effortSupport: 'supported', supportedEfforts: [...new Set(levels)] };
+            }
+        }
+    }
+    catch { /* Missing/stale metadata is unknown, never optimistic support. */ }
+    return result;
+}
+export function assertEffortSupported(selection, capability) {
+    if (selection.effort !== undefined && (capability.effortSupport !== 'supported' || !capability.supportedEfforts?.includes(selection.effort))) {
+        throw new AgentExecutionError(`Requested effort '${selection.effort}' is not confirmed for ${capability.transport}. Select a supported effort or provider default.`, 'provider_capability_unsupported');
+    }
+}
+export async function configuredCapabilities(config, registry) {
+    const probes = new Map();
+    const probe = (provider, model) => {
+        const key = JSON.stringify([provider, model ?? null]);
+        if (!probes.has(key))
+            probes.set(key, registry.capabilities(provider, model));
+        return probes.get(key);
+    };
+    const roles = [];
+    for (const [role, selected] of Object.entries(config.agents)) {
+        for (const [tier, choice] of [['base', selected], ...(selected.escalation ? [['escalation', selected.escalation]] : [])]) {
+            roles.push({ role, tier, provider: selected.provider, model: choice.model ?? null, requestedEffort: choice.effort ?? null, ...await probe(selected.provider, choice.model) });
+        }
+    }
+    return { schemaVersion: 1, roles };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/agent-runtime/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/agent-runtime/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime/cli-executor.d.ts

@@ -0,0 +1,43 @@
+import { type AgentEvent, type AgentExecutor, type AgentLimits, type AgentRequest, type AgentResult, type CliProvider } from './executor-types.js';
+import { type CliInvocation, type CliProcessRunner } from './cli-process.js';
+export interface CliExecutorOptions {
+    runProcess?: CliProcessRunner;
+    env?: NodeJS.ProcessEnv;
+}
+export interface CliInvocationOptions {
+    kimiAgentFile?: string;
+    geminiPolicyFile?: string;
+    codexSchemaFile?: string;
+    openspecBridge?: {
+        command: string;
+        args: string[];
+    };
+    mcpConfigFile?: string;
+}
+/**
+ * Build the exact argv for one role. Read-only roles use each CLI's native
+ * read-only boundary. The developer role gets the same autonomy the legacy
+ * Implement step had (edits and shell inside the CLI's own sandbox), because a
+ * developer that cannot run tests iterates blind and fails verification.
+ */
+export declare function buildCliInvocation(provider: CliProvider, request: AgentRequest, options?: CliInvocationOptions): CliInvocation;
+interface ParsedCliResult extends AgentResult {
+    terminal: boolean;
+    failed: boolean;
+    turns: number;
+    failureKind?: 'max_turns' | 'cost_budget' | 'structured_output_retries';
+}
+export declare function parseCliOutput(provider: CliProvider, stdout: string): ParsedCliResult;
+/** Live tool activity for one streamed JSON line, or undefined when the line carries none. */
+export declare function cliToolEvents(provider: CliProvider, event: Record<string, unknown>): AgentEvent[];
+export declare class CliExecutor implements AgentExecutor {
+    private readonly provider;
+    private readonly options;
+    constructor(provider: CliProvider, options?: CliExecutorOptions);
+    capabilities(model?: string): Promise<import("./executor-types.js").ExecutorCapabilities>;
+    private readonly capabilityChecks;
+    validateOpenSpec(context: import('./openspec.js').OpenSpecRoleContext): Promise<void>;
+    validateLimits(limits: AgentLimits): void;
+    execute(request: AgentRequest): Promise<AgentResult>;
+}
+export {};

package/dist/agent-runtime/cli-executor.js

@@ -0,0 +1,405 @@
+import { codexOutputSchema, restoreOptionalFields } from './codex-schema.js';
+import { assertEffortSupported, cliCapabilities } from './capabilities.js';
+import { providerDiagnostic } from './provider-diagnostic.js';
+import { toolEvent } from './tool-event.js';
+import { openSpecPrompt, writeOpenSpecBridge } from './openspec.js';
+import { existsSync, readFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { sumCacheUsage } from './efficiency-types.js';
+import { normalizeKimiCliModel } from '../installer/runtime/kimi.js';
+import { AgentExecutionError, unknownUsage, validateAgentRequest } from './executor-types.js';
+import { runCliProcess } from './cli-process.js';
+import { canonicalWorkspace } from './workspace-tools.js';
+import { parseStructuredText } from './openai-executor.js';
+import { executeKimiReadonlyAcp } from './kimi-acp.js';
+import { assertGeminiAdminPolicyAvailable, GEMINI_READONLY_POLICY } from './gemini-policy.js';
+/** Tools a Claude developer may not use: nested agents and platform skills would start a second, unobserved workflow. */
+const CLAUDE_DEVELOPER_DISALLOWED = 'Agent,Task,Skill';
+/**
+ * Build the exact argv for one role. Read-only roles use each CLI's native
+ * read-only boundary. The developer role gets the same autonomy the legacy
+ * Implement step had (edits and shell inside the CLI's own sandbox), because a
+ * developer that cannot run tests iterates blind and fails verification.
+ */
+export function buildCliInvocation(provider, request, options = {}) {
+    const readOnly = request.role !== 'developer';
+    const model = request.model ? ['--model', request.model] : [];
+    const extraRoots = request.allowedRoots.filter(root => root !== request.cwd);
+    const resume = request.resumeSessionId;
+    switch (provider) {
+        case 'claude': return { command: 'claude', stdin: request.prompt, args: [
+                '-p', '--output-format', 'stream-json', '--verbose', '--max-turns', String(request.maxTurns ?? 100), ...model,
+                ...(request.effort === undefined ? [] : ['--effort', request.effort]),
+                // Project instructions and rules stay visible; the user's global config,
+                // memory and plugins never leak into an autonomous role.
+                '--setting-sources', 'project,local',
+                ...(readOnly
+                    ? ['--tools', options.mcpConfigFile ? 'Read,Grep,Glob,ToolSearch' : 'Read,Grep,Glob', '--permission-mode', options.mcpConfigFile ? 'dontAsk' : 'plan', '--strict-mcp-config', ...(options.mcpConfigFile ? ['--allowedTools', 'Read,Grep,Glob,ToolSearch,mcp__specrails_openspec__workflow,mcp__specrails_openspec__read_verification_evidence'] : [])]
+                    : ['--tools', 'default', '--disallowedTools', CLAUDE_DEVELOPER_DISALLOWED, '--dangerously-skip-permissions']),
+                ...(options.mcpConfigFile ? ['--mcp-config', options.mcpConfigFile] : []),
+                ...(request.outputSchema ? ['--json-schema', JSON.stringify(request.outputSchema)] : []),
+                ...(request.maxCostUsd === undefined ? [] : ['--max-budget-usd', String(request.maxCostUsd)]),
+                ...extraRoots.flatMap(root => ['--add-dir', root]),
+                ...(resume ? ['--resume', resume] : []),
+            ] };
+        case 'codex': {
+            const sandbox = readOnly ? 'read-only' : 'workspace-write';
+            const common = ['--json', '--skip-git-repo-check', '-c', 'approval_policy="never"', ...model,
+                ...(request.effort === undefined ? [] : ['-c', 'model_reasoning_effort=' + JSON.stringify(request.effort)]),
+                ...(options.openspecBridge ? ['-c', 'mcp_servers.specrails_openspec.command=' + JSON.stringify(options.openspecBridge.command), '-c', 'mcp_servers.specrails_openspec.args=' + JSON.stringify(options.openspecBridge.args), '-c', 'mcp_servers.specrails_openspec.default_tools_approval_mode="approve"', '-c', 'mcp_servers.specrails_openspec.required=true'] : []),
+            ];
+            // `codex exec resume` has no --sandbox flag; the same policy travels as a config override.
+            if (resume)
+                return { command: 'codex', stdin: request.prompt, args: ['exec', 'resume', ...common, '-c', `sandbox_mode="${sandbox}"`, '-c', 'sandbox_workspace_write.writable_roots=' + JSON.stringify(readOnly ? [] : request.allowedRoots), resume, '-'] };
+            return { command: 'codex', stdin: request.prompt, args: [
+                    'exec', ...common, '--sandbox', sandbox,
+                    ...(options.codexSchemaFile ? ['--output-schema', options.codexSchemaFile] : []),
+                    ...extraRoots.flatMap(root => ['--add-dir', root]), '-',
+                ] };
+        }
+        case 'gemini': {
+            if (readOnly && !options.geminiPolicyFile)
+                throw new AgentExecutionError('Gemini architect/reviewer roles require --admin-policy support for an enforced read-only tool allowlist. Upgrade Gemini CLI or select another provider for this role.', 'provider_capability_unsupported');
+            return { command: 'gemini', stdin: request.prompt, args: [
+                    '-p', 'Execute the task supplied on stdin.', '--output-format', 'stream-json', ...model,
+                    // Headless Gemini cannot answer shell approvals; the developer runs with
+                    // auto-approval exactly as the legacy Implement step did.
+                    ...(readOnly ? ['--approval-mode', 'plan'] : ['--yolo']),
+                    ...(options.geminiPolicyFile ? ['--admin-policy', options.geminiPolicyFile] : []),
+                    ...extraRoots.flatMap(root => ['--include-directories', root]),
+                    ...(resume ? ['--resume', resume] : []),
+                ] };
+        }
+        case 'kimi': {
+            if (readOnly && !options.kimiAgentFile)
+                throw new AgentExecutionError('Kimi read-only print mode requires --agent-file and enforced tool allowlists. Use CliExecutor to select the ACP read-only transport on older CLIs.', 'provider_capability_unsupported');
+            return { command: 'kimi', args: [
+                    ...(request.model ? ['-m', normalizeKimiCliModel(request.model)] : []),
+                    ...(resume ? [`--session=${resume}`] : []),
+                    '-p', request.prompt, '--output-format', 'stream-json',
+                    ...(options.kimiAgentFile ? ['--agent-file', options.kimiAgentFile] : []),
+                    ...extraRoots.flatMap(root => ['--add-dir', root]),
+                ] };
+        }
+    }
+}
+function object(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+function number(value) { return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null; }
+function textBlocks(value) {
+    return Array.isArray(value) ? value.map(raw => object(raw)).filter(block => block.type === 'text' && typeof block.text === 'string').map(block => block.text).join('') : '';
+}
+function claudeCacheUsage(reported) {
+    if (reported.cache_read_input_tokens === undefined && reported.cache_creation_input_tokens === undefined)
+        return {};
+    return { uncachedInputTokens: number(reported.input_tokens), cacheReadInputTokens: number(reported.cache_read_input_tokens), cacheWriteInputTokens: number(reported.cache_creation_input_tokens) };
+}
+function inclusiveCacheUsage(reported) {
+    const cached = number(reported.cached_input_tokens), input = number(reported.input_tokens);
+    if (reported.cached_input_tokens === undefined)
+        return {};
+    return { cacheReadInputTokens: cached !== null && input !== null && cached <= input ? cached : null, uncachedInputTokens: cached !== null && input !== null && cached <= input ? input - cached : null, cacheWriteInputTokens: null };
+}
+export function parseCliOutput(provider, stdout) {
+    let text = '', terminal = false, failed = false, sessionId, turns = 0;
+    let usage = unknownUsage();
+    let failureKind;
+    let structured;
+    const claudeMessages = new Map();
+    for (const line of stdout.split(/\r?\n/)) {
+        let event;
+        try {
+            event = object(JSON.parse(line));
+        }
+        catch {
+            continue;
+        }
+        if (typeof event.session_id === 'string')
+            sessionId = event.session_id;
+        if (typeof event.thread_id === 'string')
+            sessionId = event.thread_id;
+        if (['error', 'turn.failed', 'system.error'].includes(String(event.type)))
+            failed = true;
+        if (provider === 'claude') {
+            if (event.type === 'assistant') {
+                const message = object(event.message), reported = object(message.usage);
+                const messageText = textBlocks(message.content);
+                if (messageText)
+                    text = messageText;
+                const id = typeof message.id === 'string' ? message.id : `anonymous-${claudeMessages.size}`;
+                const input = number(reported.input_tokens);
+                claudeMessages.set(id, { inputTokens: input === null ? null : input + (number(reported.cache_read_input_tokens) ?? 0) + (number(reported.cache_creation_input_tokens) ?? 0), outputTokens: number(reported.output_tokens), costUsd: null, ...claudeCacheUsage(reported) });
+                turns = claudeMessages.size;
+            }
+            if (event.type === 'result' && object(event.origin).kind !== 'task-notification') {
+                terminal = true;
+                failed ||= event.is_error === true || (typeof event.subtype === 'string' && event.subtype !== 'success');
+                if (event.subtype === 'error_max_turns')
+                    failureKind = 'max_turns';
+                if (event.subtype === 'error_max_budget_usd')
+                    failureKind = 'cost_budget';
+                if (event.subtype === 'error_max_structured_output_retries')
+                    failureKind = 'structured_output_retries';
+                if (typeof event.result === 'string')
+                    text = event.result;
+                // --json-schema returns the validated object separately from the text.
+                if (event.structured_output && typeof event.structured_output === 'object' && !Array.isArray(event.structured_output))
+                    structured = event.structured_output;
+                const reported = object(event.usage), input = number(reported.input_tokens);
+                usage = { inputTokens: input === null ? null : input + (number(reported.cache_read_input_tokens) ?? 0) + (number(reported.cache_creation_input_tokens) ?? 0), outputTokens: number(reported.output_tokens), costUsd: number(event.total_cost_usd), ...claudeCacheUsage(reported) };
+            }
+        }
+        else if (provider === 'codex') {
+            if (event.type === 'turn.failed' || event.type === 'error')
+                failed = true;
+            if (event.type === 'item.completed') {
+                const item = object(event.item);
+                if (item.type === 'agent_message' && typeof item.text === 'string')
+                    text = item.text;
+                if (item.type === 'agent_message' || ['command_execution', 'mcp_tool_call', 'function_call', 'local_shell_call'].includes(String(item.type)))
+                    turns++;
+            }
+            if (event.type === 'turn.completed') {
+                terminal = true;
+                failed = false;
+                const reported = object(event.usage);
+                usage = { inputTokens: number(reported.input_tokens), outputTokens: number(reported.output_tokens), costUsd: null, ...inclusiveCacheUsage(reported) };
+            }
+        }
+        else if (provider === 'gemini') {
+            if (event.type === 'message' && event.role === 'assistant' && typeof event.content === 'string') {
+                text += event.content;
+                if (!event.delta)
+                    turns++;
+            }
+            // Assistant deltas before a tool belong to an intermediate turn. Keep
+            // streaming them to observers, but return only the final response.
+            if (event.type === 'tool_use') {
+                turns++;
+                text = '';
+            }
+            if (event.type === 'result') {
+                terminal = true;
+                failed ||= event.status !== 'success';
+                const reported = object(event.stats);
+                usage = { inputTokens: number(reported.input_tokens), outputTokens: number(reported.output_tokens), costUsd: null };
+            }
+        }
+        else {
+            if (event.role === 'assistant') {
+                turns++;
+                const content = typeof event.content === 'string' ? event.content : textBlocks(event.content);
+                if (content)
+                    text = content;
+            }
+            if (event.type === 'session.resume_hint')
+                terminal = true;
+        }
+    }
+    if (provider === 'claude' && !terminal && claudeMessages.size) {
+        const messages = [...claudeMessages.values()];
+        usage = { inputTokens: messages.some(message => message.inputTokens === null) ? null : messages.reduce((sum, message) => sum + (message.inputTokens ?? 0), 0), outputTokens: messages.some(message => message.outputTokens === null) ? null : messages.reduce((sum, message) => sum + (message.outputTokens ?? 0), 0), costUsd: null, ...sumCacheUsage(messages) };
+    }
+    if (structured && !text.trim())
+        text = JSON.stringify(structured);
+    return { text, terminal, failed, turns, usage, sessionId, structured: structured ?? parseStructuredText(text), ...(failureKind ? { failureKind } : {}) };
+}
+/** Live tool activity for one streamed JSON line, or undefined when the line carries none. */
+export function cliToolEvents(provider, event) {
+    if (provider === 'claude' && event.type === 'assistant') {
+        const content = object(event.message).content;
+        return Array.isArray(content) ? content.map(object).filter(block => block.type === 'tool_use' && typeof block.name === 'string').map(block => toolEvent(String(block.name), block.input)) : [];
+    }
+    if (provider === 'codex' && event.type === 'item.started') {
+        const item = object(event.item);
+        if (['command_execution', 'local_shell_call'].includes(String(item.type)))
+            return [toolEvent('shell', { command: item.command, cwd: item.cwd })];
+        if (['mcp_tool_call', 'function_call'].includes(String(item.type)))
+            return [toolEvent(typeof item.name === 'string' ? item.name : 'tool', item.arguments)];
+        if (item.type === 'file_change')
+            return [toolEvent('edit', { paths: Array.isArray(item.changes) ? item.changes.map(change => object(change).path) : [] })];
+        return [];
+    }
+    if (provider === 'gemini' && event.type === 'tool_use')
+        return [toolEvent(typeof event.tool_name === 'string' ? event.tool_name : 'tool', event.parameters)];
+    if (provider === 'kimi' && event.role === 'assistant' && Array.isArray(event.tool_calls)) {
+        return event.tool_calls.map(object).map(call => { const fn = object(call.function); let input; try {
+            input = typeof fn.arguments === 'string' ? JSON.parse(fn.arguments) : fn.arguments;
+        }
+        catch {
+            input = undefined;
+        } return toolEvent(typeof fn.name === 'string' ? fn.name : 'tool', input); });
+    }
+    return [];
+}
+export class CliExecutor {
+    provider;
+    options;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.options = options;
+    }
+    capabilities(model) { return cliCapabilities(this.provider, model, this.options); }
+    capabilityChecks = new Map();
+    async validateOpenSpec(context) {
+        const key = context.role === 'developer' ? 'write' : 'read';
+        let checked = this.capabilityChecks.get(key);
+        if (!checked) {
+            checked = (async () => {
+                if (this.provider === 'gemini' && key === 'read')
+                    assertGeminiAdminPolicyAvailable();
+                const help = await (this.options.runProcess ?? runCliProcess)({ command: this.provider, args: this.provider === 'kimi' ? ['acp', '--help'] : ['--help'] }, { cwd: context.root, timeoutMs: 10000, env: this.options.env });
+                const flags = this.provider === 'claude' ? ['--mcp-config', '--allowedTools'] : this.provider === 'codex' ? ['--config'] : this.provider === 'gemini' && key === 'read' ? ['--admin-policy'] : [];
+                if (help.exitCode !== 0 || flags.some(flag => !help.stdout.includes(flag)))
+                    throw new AgentExecutionError(`The installed ${this.provider} CLI lacks the required OpenSpec transport. Upgrade this CLI or select another provider.`, 'provider_capability_unsupported');
+            })();
+            this.capabilityChecks.set(key, checked);
+        }
+        await checked;
+    }
+    validateLimits(limits) {
+        if (limits.maxCostUsd !== undefined && this.provider !== 'claude')
+            throw new AgentExecutionError(`A strict USD cap is unsupported by the ${this.provider} CLI. Use Claude's native cap or remove the dollar cap.`, 'cost_limit_unsupported');
+        if (limits.maxTokens !== undefined && this.provider === 'kimi')
+            throw new AgentExecutionError('Kimi does not report authoritative token usage. Remove the token cap or select another provider for this role.', 'usage_unavailable');
+    }
+    async execute(request) {
+        validateAgentRequest(request);
+        if (request.effort !== undefined)
+            assertEffortSupported(request, await this.capabilities(request.model));
+        this.validateLimits(request);
+        const scope = canonicalWorkspace(request.cwd, request.allowedRoots);
+        const normalized = { ...request, prompt: (request.openspec ? openSpecPrompt(request.openspec) : '') + request.prompt, cwd: scope.cwd, allowedRoots: scope.roots };
+        const runner = this.options.runProcess ?? runCliProcess;
+        let temporary, kimiAgentFile, geminiPolicyFile, codexSchemaFile, stream = '', turns = 0;
+        const assistantIds = new Set();
+        const scratch = () => temporary ??= mkdtempSync(path.join(tmpdir(), 'specrails-' + this.provider + '-role-'));
+        try {
+            const openspecBridge = request.openspec ? writeOpenSpecBridge(request.openspec, scratch()) : undefined;
+            let mcpConfigFile;
+            let executionEnv = this.options.env;
+            if (openspecBridge) {
+                mcpConfigFile = path.join(scratch(), 'mcp.json');
+                writeFileSync(mcpConfigFile, JSON.stringify({ mcpServers: { specrails_openspec: openspecBridge } }), { mode: 0o600 });
+                if (this.provider === 'gemini') {
+                    const env = this.options.env ?? process.env;
+                    const systemPath = env.GEMINI_CLI_SYSTEM_SETTINGS_PATH ?? (process.platform === 'darwin' ? '/Library/Application Support/GeminiCli/settings.json' : process.platform === 'win32' ? 'C:\\ProgramData\\gemini-cli\\settings.json' : '/etc/gemini-cli/settings.json');
+                    const settings = existsSync(systemPath) ? JSON.parse(readFileSync(systemPath, 'utf8')) : {};
+                    if (settings.mcp?.allowed || settings.mcp?.excluded || settings.admin?.mcp?.enabled === false)
+                        throw new AgentExecutionError('Gemini administrator MCP restrictions require explicit OpenSpec server admission', 'provider_capability_unsupported');
+                    writeFileSync(mcpConfigFile, JSON.stringify({ ...settings, mcpServers: { ...settings.mcpServers, specrails_openspec: { ...openspecBridge, trust: true, includeTools: ['workflow', 'read_verification_evidence'] } } }), { mode: 0o600 });
+                    executionEnv = { ...env, GEMINI_CLI_SYSTEM_SETTINGS_PATH: mcpConfigFile };
+                }
+                if (this.provider === 'kimi')
+                    return await executeKimiReadonlyAcp(normalized, { ...this.options, openspecBridge });
+            }
+            if (this.provider === 'gemini' && request.role !== 'developer') {
+                assertGeminiAdminPolicyAvailable();
+                const help = await runner({ command: 'gemini', args: ['--help'] }, { cwd: scope.cwd, signal: request.signal, timeoutMs: 10_000, env: this.options.env });
+                if (help.exitCode !== 0 || !help.stdout.includes('--admin-policy'))
+                    throw new AgentExecutionError('Gemini architect/reviewer roles require --admin-policy support for an enforced read-only tool allowlist. Upgrade Gemini CLI or select another provider for this role.', 'provider_capability_unsupported');
+                geminiPolicyFile = path.join(scratch(), 'readonly.toml');
+                writeFileSync(geminiPolicyFile, (openspecBridge ? '[[rule]]\nmcpName = "specrails_openspec"\ntoolName = "workflow"\ndecision = "allow"\npriority = 1000\n\n[[rule]]\nmcpName = "specrails_openspec"\ntoolName = "read_verification_evidence"\ndecision = "allow"\npriority = 1000\n\n' : '') + GEMINI_READONLY_POLICY, { mode: 0o600 });
+            }
+            if (this.provider === 'kimi' && request.role !== 'developer') {
+                const help = await runner({ command: 'kimi', args: ['--help'] }, { cwd: scope.cwd, signal: request.signal, timeoutMs: 10_000, env: this.options.env });
+                if (help.exitCode !== 0)
+                    throw new AgentExecutionError('Cannot detect Kimi CLI capabilities', 'provider_capability_unsupported');
+                if (!help.stdout.includes('--agent-file'))
+                    return await executeKimiReadonlyAcp(request, this.options);
+                kimiAgentFile = path.join(scratch(), 'readonly.md');
+                writeFileSync(kimiAgentFile, '---\nname: specrails-readonly\ndescription: Execute one read-only Specrails role\ntools:\n  - Read\n  - Grep\n  - Glob\nsubagents: []\n---\nExecute the supplied task and return its complete result. All instructions are supplied in the task.\n', { mode: 0o600 });
+            }
+            if (this.provider === 'codex' && request.outputSchema && !request.resumeSessionId) {
+                codexSchemaFile = path.join(scratch(), 'output-schema.json');
+                writeFileSync(codexSchemaFile, JSON.stringify(codexOutputSchema(request.outputSchema)), { mode: 0o600 });
+            }
+            const result = await runner(buildCliInvocation(this.provider, normalized, { kimiAgentFile, geminiPolicyFile, codexSchemaFile, openspecBridge, mcpConfigFile }), {
+                cwd: scope.cwd, signal: request.signal, timeoutMs: request.timeoutMs ?? 15 * 60_000, env: executionEnv,
+                onLine: line => {
+                    stream += line + '\n';
+                    let event;
+                    try {
+                        event = object(JSON.parse(line));
+                    }
+                    catch {
+                        return;
+                    }
+                    let delta = '';
+                    if (this.provider === 'claude' && event.type === 'assistant') {
+                        const message = object(event.message);
+                        const id = typeof message.id === 'string' ? message.id : `anonymous-${turns}`;
+                        if (!assistantIds.has(id)) {
+                            assistantIds.add(id);
+                            turns++;
+                        }
+                        delta = textBlocks(message.content);
+                    }
+                    else if (this.provider === 'codex' && event.type === 'item.completed') {
+                        const item = object(event.item);
+                        if (item.type === 'agent_message' || ['command_execution', 'mcp_tool_call', 'function_call', 'local_shell_call'].includes(String(item.type)))
+                            turns++;
+                        if (item.type === 'agent_message' && typeof item.text === 'string')
+                            delta = item.text;
+                    }
+                    else if (this.provider === 'gemini') {
+                        if (event.type === 'tool_use')
+                            turns++;
+                        if (event.type === 'message' && event.role === 'assistant' && typeof event.content === 'string')
+                            delta = event.content;
+                    }
+                    else if (this.provider === 'kimi' && event.role === 'assistant') {
+                        turns++;
+                        delta = typeof event.content === 'string' ? event.content : textBlocks(event.content);
+                    }
+                    if (turns > (request.maxTurns ?? 100))
+                        throw new AgentExecutionError('CLI exceeded its configured turn/tool limit', 'max_turns', parseCliOutput(this.provider, stream).usage);
+                    for (const tool of cliToolEvents(this.provider, event))
+                        request.onEvent?.(tool);
+                    if (delta)
+                        request.onEvent?.({ kind: 'text', text: delta });
+                },
+            });
+            const parsed = parseCliOutput(this.provider, result.stdout);
+            request.onEvent?.({ kind: 'usage', usage: parsed.usage });
+            if (parsed.failureKind) {
+                const message = parsed.failureKind === 'max_turns'
+                    ? `${this.provider} reached the configured limit of ${request.maxTurns ?? 100} turns for ${request.role}. Inspect partial changes before recovery; a higher limit requires a new run configuration.`
+                    : parsed.failureKind === 'cost_budget' ? `${this.provider} reached its configured cost budget.` : `${this.provider} exhausted structured output retries.`;
+                throw new AgentExecutionError(message, parsed.failureKind, parsed.usage);
+            }
+            if (result.exitCode !== 0 || parsed.failed) {
+                const diagnostic = providerDiagnostic(result.stdout, result.stderr, { ...process.env, ...this.options.env });
+                throw new AgentExecutionError(`${this.provider} execution failed${result.exitCode !== 0 ? ` (exit ${result.exitCode})` : ''}.${diagnostic ? ' ' + diagnostic : ' The provider did not report a diagnostic.'}`, 'provider_execution_error', parsed.usage);
+            }
+            if (!parsed.terminal || !parsed.text.trim())
+                throw new AgentExecutionError(`${this.provider} exited without a successful final result`, 'incomplete_response', parsed.usage);
+            if (request.maxTokens !== undefined) {
+                if (parsed.usage.inputTokens === null || parsed.usage.outputTokens === null)
+                    throw new AgentExecutionError(`${this.provider} did not report usage needed for the token limit`, 'usage_unavailable', parsed.usage);
+                if (parsed.usage.inputTokens + parsed.usage.outputTokens > request.maxTokens)
+                    throw new AgentExecutionError('Agent token budget exceeded', 'token_budget', parsed.usage);
+            }
+            // The final text was already streamed as it arrived; re-emitting it would
+            // print every summary twice in host logs.
+            if (this.provider === 'codex' && request.outputSchema && parsed.structured) {
+                parsed.structured = restoreOptionalFields(parsed.structured, request.outputSchema);
+                parsed.text = JSON.stringify(parsed.structured);
+            }
+            return { text: parsed.text, usage: parsed.usage, sessionId: parsed.sessionId, structured: parsed.structured };
+        }
+        catch (error) {
+            if (error instanceof AgentExecutionError) {
+                const usage = parseCliOutput(this.provider, stream).usage;
+                if (error.usage.inputTokens === null && usage.inputTokens !== null)
+                    throw new AgentExecutionError(error.message, error.code, usage);
+            }
+            throw error;
+        }
+        finally {
+            if (temporary)
+                rmSync(temporary, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=cli-executor.js.map