specrails-desktop 2.44.2 → 2.46.0

package/server/dist/agent-runtime-controls.js

@@ -0,0 +1,341 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRuntimeControls = exports.RuntimeControlError = void 0;
+exports.validateRuntimeResumeInput = validateRuntimeResumeInput;
+exports.readAgentRuntimeStatus = readAgentRuntimeStatus;
+const agent_runtime_settlement_1 = require("./agent-runtime-settlement");
+const agent_runtime_metrics_1 = require("./agent-runtime-metrics");
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const agent_runtime_loader_1 = require("./agent-runtime-loader");
+const agent_runtime_bridge_1 = require("./agent-runtime-bridge");
+const core_node_runtime_1 = require("./core-node-runtime");
+const win_spawn_1 = require("./util/win-spawn");
+const workspace_resolution_1 = require("./workspace-resolution");
+const loop_runs_store_1 = require("./loop-runs-store");
+const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
+const db_1 = require("./db");
+const loop_run_manager_1 = require("./loop-run-manager");
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const STEP_IDS = ['architect', 'developer', 'verify', 'reviewer', 'archive'];
+const ANSWER_LIMIT = 20_000;
+class RuntimeControlError extends Error {
+    statusCode;
+    code;
+    constructor(statusCode, code, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}
+exports.RuntimeControlError = RuntimeControlError;
+function validateRuntimeResumeInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new RuntimeControlError(400, 'invalid_resume_request', 'Resume request must be an object');
+    const body = input;
+    for (const [key, value] of Object.entries(body)) {
+        if (key === 'answer') {
+            if (typeof value !== 'string' || !value.trim() || value.length > ANSWER_LIMIT)
+                throw new RuntimeControlError(400, 'invalid_resume_request', `An answer must be a nonempty string of at most ${ANSWER_LIMIT} characters`);
+            continue;
+        }
+        if (!['approve', 'recover', 'invalidate'].includes(key) || !Array.isArray(value) || value.length > STEP_IDS.length || !value.every((id) => typeof id === 'string' && STEP_IDS.includes(id)) || new Set(value).size !== value.length)
+            throw new RuntimeControlError(400, 'invalid_resume_request', 'Only approve, recover and invalidate arrays of known phase IDs are allowed');
+    }
+    return body;
+}
+/** A question stays pending until Core records its answer. */
+function openQuestion(state) {
+    return state.pendingQuestion && state.pendingQuestion.answeredAt === undefined ? state.pendingQuestion : undefined;
+}
+/** Status is a read-only Core CLI operation. It never invokes a provider. */
+async function readAgentRuntimeStatus(contextPath, cwd, env) {
+    const cli = (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)();
+    if (!cli)
+        throw new RuntimeControlError(503, 'runtime_unavailable', 'Update Core to inspect or resume agent runtime executions');
+    const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, 'status', '--context', contextPath, '--compact'], {
+        cwd, env: (0, win_spawn_1.windowsSpawnEnv)(env), windowsHide: true, timeout: 15000, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8',
+    });
+    const result = JSON.parse(stdout);
+    if (result.type !== 'runtime-status' || result.state === undefined)
+        throw new Error('Core returned an invalid runtime status');
+    return result.state;
+}
+/** One controller per ProjectContext; Core's durable lease remains the final
+ * cross-process guard. Resume never constructs a new context or worktree. */
+class AgentRuntimeControls {
+    ctx;
+    dependencies;
+    isActive(runId) { return this.active.has(runId); }
+    activeRunIds() { return [...this.active.keys()]; }
+    active = new Map();
+    errors = new Map();
+    statusCache = new Map();
+    disposed = false;
+    constructor(ctx, dependencies = { status: readAgentRuntimeStatus, execute: agent_runtime_bridge_1.runAgentRuntimeInvocation, kill: win_spawn_1.treeKillSafe, settle: agent_runtime_settlement_1.settleRuntimeContinuation }) {
+        this.ctx = ctx;
+        this.dependencies = dependencies;
+    }
+    context(runId) {
+        if (!SAFE_ID.test(runId))
+            throw new RuntimeControlError(400, 'invalid_run_id', 'Invalid runtime run ID');
+        const execution = (0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project);
+        const backlogRoot = node_fs_1.default.realpathSync(node_path_1.default.dirname(execution.specrailsDir));
+        const directory = node_path_1.default.join(execution.specrailsDir, 'pipeline', runId);
+        const file = node_path_1.default.join(directory, 'desktop-context.json');
+        if (!node_fs_1.default.existsSync(file))
+            throw new RuntimeControlError(404, 'runtime_run_not_found', 'Runtime execution context is unavailable');
+        if (node_fs_1.default.realpathSync(file) !== node_path_1.default.join(node_fs_1.default.realpathSync(execution.specrailsDir), 'pipeline', runId, 'desktop-context.json'))
+            throw new RuntimeControlError(409, 'runtime_scope_changed', 'Runtime context path no longer matches its project');
+        const frozen = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        try {
+            if (frozen.runId !== runId || node_fs_1.default.realpathSync(frozen.backlogRoot) !== backlogRoot || !Array.isArray(frozen.repositories) || !frozen.repositories.length || !frozen.repositories.some((repository) => repository.path === frozen.artifactRoot))
+                throw new Error();
+            for (const root of [frozen.artifactRoot, ...frozen.repositories.map((repository) => repository.path)]) {
+                if (!node_path_1.default.isAbsolute(root) || node_fs_1.default.realpathSync(root) !== root || !node_fs_1.default.statSync(root).isDirectory())
+                    throw new Error();
+            }
+        }
+        catch {
+            throw new RuntimeControlError(409, 'runtime_scope_unavailable', 'The original runtime worktree or project scope is unavailable. Start a new implementation.');
+        }
+        const stored = this.ctx.db.prepare('SELECT execution_manifest FROM loop_runs WHERE id = ?').get(runId);
+        const manifest = (0, multi_repo_execution_store_1.readExecutionManifest)(stored?.execution_manifest);
+        if (manifest && (manifest.projectId !== this.ctx.project.id || manifest.repositories.length !== frozen.repositories.length || !manifest.repositories.every((repository) => frozen.repositories.some((item) => item.id === repository.repositoryId && item.path === repository.worktreePath))))
+            throw new RuntimeControlError(409, 'runtime_scope_changed', 'The saved worktree manifest differs from the frozen runtime scope');
+        const hostFile = node_path_1.default.join(directory, 'desktop-runtime-host.json');
+        if (!node_fs_1.default.existsSync(hostFile))
+            throw new RuntimeControlError(409, 'runtime_host_unavailable', 'The original runtime host settings are missing. Start a new implementation.');
+        const host = JSON.parse(node_fs_1.default.readFileSync(hostFile, 'utf8'));
+        if (host.schemaVersion !== 1 || typeof host.cwd !== 'string' || ![frozen.backlogRoot, ...frozen.repositories.map((repository) => repository.path)].includes(host.cwd) || !host.env || typeof host.env !== 'object' || Array.isArray(host.env) || Object.entries(host.env).some(([key, value]) => !agent_runtime_bridge_1.RUNTIME_HOST_ENV_KEYS.includes(key) || typeof value !== 'string'))
+            throw new RuntimeControlError(409, 'runtime_host_invalid', 'The saved runtime host settings are invalid');
+        const env = { ...(0, workspace_resolution_1.resolveLoopBaseEnv)(this.ctx.project) };
+        for (const key of agent_runtime_bridge_1.RUNTIME_HOST_ENV_KEYS)
+            delete env[key];
+        Object.assign(env, host.env, { SPECRAILS_EXECUTION_CONTEXT: file });
+        return { file, frozen, cwd: host.cwd, env };
+    }
+    async list() {
+        const directory = node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project).specrailsDir, 'pipeline');
+        if (!node_fs_1.default.existsSync(directory))
+            return [];
+        const entries = node_fs_1.default.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && SAFE_ID.test(entry.name) && node_fs_1.default.existsSync(node_path_1.default.join(directory, entry.name, 'agent-runtime-request.json')))
+            .sort((a, b) => node_fs_1.default.statSync(node_path_1.default.join(directory, b.name)).mtimeMs - node_fs_1.default.statSync(node_path_1.default.join(directory, a.name)).mtimeMs).slice(0, 20);
+        const runs = [];
+        // Bounded sequential reads avoid spawning one Node process per historical run at once.
+        for (const entry of entries)
+            runs.push(await this.summary(entry.name));
+        return runs;
+    }
+    async summary(runId) {
+        try {
+            const { file, cwd, env } = this.context(runId);
+            // Core owns checkpoint parsing. Its atomic file revision is only a cache
+            // key, keeping idle settings panes from spawning CLI processes repeatedly.
+            const checkpoint = node_path_1.default.join(node_path_1.default.dirname(file), 'agent-workflow', runId, 'checkpoint.json');
+            const stat = node_fs_1.default.existsSync(checkpoint) ? node_fs_1.default.statSync(checkpoint) : null;
+            const fingerprint = stat ? `${stat.mtimeMs}:${stat.size}` : null;
+            const cached = this.statusCache.get(runId);
+            const state = fingerprint && cached?.fingerprint === fingerprint ? cached.state : await this.dependencies.status(file, cwd, env);
+            if (!state || state.runId !== runId)
+                throw new Error('No saved workflow state is available');
+            if (fingerprint)
+                this.statusCache.set(runId, { fingerprint, state });
+            const parent = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
+            const active = this.active.has(runId) || parent?.status === 'running' || parent?.status === 'paused';
+            const recoverableSteps = Object.entries(state.steps).filter(([, step]) => ['running', 'interrupted'].includes(step.status)).map(([id]) => id);
+            return { runId, status: state.status === 'running' && !active ? 'interrupted' : state.status, nextStep: state.nextStep,
+                updatedAt: state.updatedAt, error: this.errors.get(runId) ?? state.error, pendingApproval: state.pendingApproval,
+                traceId: state.traceId, pendingQuestion: openQuestion(state),
+                metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(state.metrics),
+                canSettle: !active && state.status === 'succeeded' && this.ctx.db.prepare('SELECT status FROM jobs WHERE id = ?').get(runId)?.status !== 'completed',
+                recoverableSteps, active, canCancel: this.active.has(runId), canResume: !active && parent?.status === 'completed' && state.status !== 'succeeded' };
+        }
+        catch (error) {
+            return { runId, status: 'unavailable', nextStep: null, active: this.active.has(runId), canResume: false, canCancel: this.active.has(runId), recoverableSteps: [], error: error instanceof RuntimeControlError ? error.message : 'Could not inspect the saved runtime execution' };
+        }
+    }
+    async resume(runId, input) {
+        if (this.disposed)
+            throw new RuntimeControlError(503, 'runtime_shutting_down', 'Project runtime is shutting down');
+        const parent = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
+        if (!parent || parent.status !== 'completed' || this.active.has(runId))
+            throw new RuntimeControlError(409, 'runtime_run_active', 'Wait for the original Desktop execution to settle before resuming');
+        if (parent.rail_index != null && [...(this.ctx.railLoopRuns?.values() ?? []), ...(this.ctx.railJobs?.values() ?? [])].some(meta => meta.railIndex === parent.rail_index))
+            throw new RuntimeControlError(409, 'runtime_rail_active', 'Wait for the implementation card to finish its active job before resuming');
+        const context = this.context(runId);
+        // Reserve before awaiting status so concurrent resume requests cannot race.
+        const active = { cancelled: false };
+        this.active.set(runId, active);
+        try {
+            // Accounting from a prior continuation must settle even when Core now
+            // reports success and correctly refuses any further execution.
+            (0, loop_run_manager_1.recoverOrphanLoopStepAccounting)(this.ctx.db, new Date().toISOString(), runId);
+            const state = await this.dependencies.status(context.file, context.cwd, context.env);
+            if (!state || state.runId !== runId || state.status === 'succeeded')
+                throw new RuntimeControlError(409, 'runtime_not_resumable', 'This execution has no resumable workflow');
+            if (parent.rail_index != null && [...(this.ctx.railLoopRuns?.values() ?? []), ...(this.ctx.railJobs?.values() ?? [])].some(meta => meta.railIndex === parent.rail_index))
+                throw new RuntimeControlError(409, 'runtime_rail_active', 'The implementation card became active while checking the saved execution');
+            // A pending question resumes the architect only with the operator's answer.
+            if (openQuestion(state) && !input.answer)
+                throw new RuntimeControlError(400, 'answer_required', 'This execution is waiting for an answer to the architect\'s question');
+            this.errors.delete(runId);
+            this.statusCache.delete(runId);
+            const startedAt = new Date().toISOString();
+            const invocationId = (0, node_crypto_1.randomUUID)();
+            const stepKey = `runtime-resume:${invocationId}`;
+            // Both live settlement and restart use the existing loop ledger.
+            const previous = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
+            let sequence = this.ctx.db.prepare('SELECT COALESCE(MAX(seq), -1) AS seq FROM events WHERE job_id = ?').get(runId).seq;
+            const startedAtMs = Date.parse(startedAt);
+            let ticketIds = [];
+            try {
+                const ids = JSON.parse(previous.ticket_ids_json ?? '[]');
+                if (Array.isArray(ids))
+                    ticketIds = ids.filter((id) => typeof id === 'number' && Number.isSafeInteger(id));
+            }
+            catch { /* Older loop records can lack a ticket scope. */ }
+            (0, loop_runs_store_1.stageLoopStepRecovery)(this.ctx.db, {
+                version: 1, runId, stepKey, invocationId, projectId: this.ctx.project.id,
+                provider: 'agent-runtime', model: 'per-role', surfaceRefId: stepKey,
+                ticketIds, startedAt, baseline: (0, loop_runs_store_1.readLoopJobUsage)(this.ctx.db, runId),
+                completedEventSeq: sequence, providerCostBaseline: 0, providerTurnsBaseline: 0,
+                loopDurationBaseline: previous.total_duration_ms, completedDurationMs: 0,
+                iterationCount: previous.iteration_count, activeTurnStartedAtMs: startedAtMs, lastActivityAtMs: startedAtMs,
+            });
+            const logLine = (line, source = 'stdout') => {
+                if (this.disposed)
+                    return;
+                try {
+                    (0, db_1.appendEvent)(this.ctx.db, runId, ++sequence, { event_type: 'log', source, payload: JSON.stringify({ line: line.replace(/\n$/, '') }) });
+                }
+                catch { /* events table best-effort */ }
+                try {
+                    this.ctx.broadcast?.({ type: 'log', source, line, timestamp: new Date().toISOString(), processId: runId });
+                }
+                catch { /* persisted log remains authoritative */ }
+            };
+            if (parent.rail_index != null)
+                this.ctx.railLoopRuns?.set(runId, { railIndex: parent.rail_index, ticketIds, requiresTerminalIntent: true });
+            const publishActivity = (running) => {
+                try {
+                    this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: parent.rail_index, active: running });
+                }
+                catch { /* durable log remains available */ }
+            };
+            publishActivity(true);
+            const requested = [...(input.approve?.length ? ['approve ' + input.approve.join(',')] : []), ...(input.recover?.length ? ['recover ' + input.recover.join(',')] : []), ...(input.invalidate?.length ? ['invalidate ' + input.invalidate.join(',')] : []), ...(input.answer ? ['answered question'] : [])];
+            logLine(`[runtime] continuation started from phase ${state.nextStep ?? 'end'}${requested.length ? ' (' + requested.join('; ') + ')' : ''}; the original worktree and frozen scope are reused`);
+            void this.dependencies.execute({
+                contextPath: context.file, cwd: context.cwd, env: context.env, resume: true, ...input,
+                // Readable progress lands in the same job log as the original rail run.
+                onLine: logLine,
+                onRawLine: (line) => {
+                    if (this.disposed)
+                        return;
+                    let eventType = 'agent-runtime';
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (typeof parsed.type === 'string')
+                            eventType = parsed.type;
+                    }
+                    catch { /* Keep raw diagnostics available to recovery. */ }
+                    this.ctx.db.transaction(() => {
+                        (0, db_1.appendEvent)(this.ctx.db, runId, ++sequence, { event_type: eventType, source: 'stdout', payload: line });
+                        (0, loop_runs_store_1.updateLoopStepActivityCheckpoint)(this.ctx.db, runId, stepKey, undefined, Date.now());
+                    })();
+                    try {
+                        this.ctx.broadcast?.({ type: 'event', jobId: runId, event_type: eventType, source: 'stdout', payload: line, seq: sequence, timestamp: new Date().toISOString() });
+                    }
+                    catch { /* persisted event remains authoritative */ }
+                },
+                onSpawn: (child) => {
+                    active.child = child;
+                    if (this.disposed && child.pid)
+                        this.dependencies.kill(child.pid, 'SIGKILL');
+                    else if (active.cancelled)
+                        this.cancel(runId);
+                },
+            }).then(async (result) => {
+                if (this.disposed)
+                    return;
+                logLine(result.failed ? `[runtime] continuation ended: ${result.errorText ?? 'failed'}` : '[runtime] continuation completed', result.failed ? 'stderr' : 'stdout');
+                (0, loop_runs_store_1.setLoopStepSettledResult)(this.ctx.db, runId, stepKey, { ...result, provider: 'agent-runtime', model: 'per-role', failed: active.cancelled || result.failed });
+                (0, loop_run_manager_1.recoverOrphanLoopStepAccounting)(this.ctx.db, new Date().toISOString(), runId);
+                if (result.errorText)
+                    this.errors.set(runId, result.errorText);
+                if (!result.failed && !active.cancelled)
+                    await this.dependencies.settle?.({ db: this.ctx.db, projectId: this.ctx.project.id, runId, contextPath: context.file, cwd: context.cwd, env: context.env, broadcast: this.ctx.broadcast });
+            }).catch(() => {
+                if (this.disposed)
+                    return;
+                const message = 'Runtime continuation failed. Inspect the saved phase state before retrying.';
+                this.errors.set(runId, message);
+                logLine(`[runtime] ${message}`, 'stderr');
+            })
+                .finally(() => {
+                clearTimeout(active.forceKillTimer);
+                this.active.delete(runId);
+                this.ctx.railLoopRuns?.delete(runId);
+                this.statusCache.delete(runId);
+                publishActivity(false);
+            });
+        }
+        catch (error) {
+            this.active.delete(runId);
+            this.ctx.railLoopRuns?.delete(runId);
+            try {
+                this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: parent.rail_index, active: false });
+            }
+            catch { /* admission failed */ }
+            throw error;
+        }
+    }
+    async settle(runId) {
+        if (this.active.has(runId) || (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId)?.status !== 'completed')
+            throw new RuntimeControlError(409, 'runtime_run_active', 'Wait for the execution to settle');
+        const context = this.context(runId);
+        this.active.set(runId, { cancelled: false });
+        try {
+            await (this.dependencies.settle ?? agent_runtime_settlement_1.settleRuntimeContinuation)({ db: this.ctx.db, projectId: this.ctx.project.id, runId, contextPath: context.file, cwd: context.cwd, env: context.env, broadcast: this.ctx.broadcast });
+            this.errors.delete(runId);
+        }
+        catch (error) {
+            throw new RuntimeControlError(409, 'runtime_settlement_blocked', error instanceof Error ? error.message : 'Could not prepare the recovered delivery');
+        }
+        finally {
+            this.active.delete(runId);
+            this.statusCache.delete(runId);
+            this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId)?.rail_index ?? null, active: false });
+        }
+    }
+    cancel(runId) {
+        const active = this.active.get(runId);
+        if (!active)
+            throw new RuntimeControlError(409, 'runtime_not_active', 'Only a continuation started here can be cancelled here; stop active rail runs from their job controls');
+        active.cancelled = true;
+        if (active.child?.pid) {
+            this.dependencies.kill(active.child.pid, this.disposed ? 'SIGKILL' : 'SIGTERM');
+            if (!this.disposed && !active.forceKillTimer) {
+                const pid = active.child.pid;
+                active.forceKillTimer = setTimeout(() => {
+                    if (this.active.get(runId) === active)
+                        this.dependencies.kill(pid, 'SIGKILL');
+                }, 3000);
+                active.forceKillTimer.unref?.();
+            }
+        }
+    }
+    shutdown() {
+        this.disposed = true;
+        for (const runId of this.active.keys())
+            this.cancel(runId);
+    }
+}
+exports.AgentRuntimeControls = AgentRuntimeControls;

package/server/dist/agent-runtime-loader.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCoreAgentRuntimeEntry = findCoreAgentRuntimeEntry;
+exports.resetCoreAgentRuntimeApiCache = resetCoreAgentRuntimeApiCache;
+exports.loadCoreAgentRuntime = loadCoreAgentRuntime;
+exports.findCoreAgentRuntimeCli = findCoreAgentRuntimeCli;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const core_runtime_1 = require("./core-runtime");
+const core_node_runtime_1 = require("./core-node-runtime");
+const win_spawn_1 = require("./util/win-spawn");
+/** An explicit or bundled installation is authoritative: never silently replace
+ * a broken production bundle with a developer's checkout. */
+function findCoreAgentRuntimeEntry() {
+    const explicit = process.env.SPECRAILS_CORE_RUNTIME_PATH;
+    if (explicit) {
+        const entry = (0, node_path_1.resolve)(explicit);
+        return (0, node_fs_1.existsSync)(entry) ? entry : null;
+    }
+    const selected = (0, core_runtime_1.getCoreRuntimeStatus)();
+    if (selected.error)
+        return null;
+    if (selected.runtime) {
+        const entry = (0, node_path_1.join)(selected.runtime.root, 'dist', 'agent-runtime', 'index.js');
+        if ((0, node_fs_1.existsSync)(entry))
+            return entry;
+        // Match Desktop's activated Core package, including managed upgrades. A
+        // missing API must never load an older bundle behind an active framework.
+        if (process.env.NODE_ENV === 'production' || ['managed', 'override', 'bundled'].includes(selected.runtime.source))
+            return null;
+    }
+    try {
+        return (0, node_module_1.createRequire)((0, node_path_1.join)(process.cwd(), 'package.json')).resolve('specrails-core/agent-runtime');
+    }
+    catch { /* A source checkout can use the sibling Core build. */ }
+    if (process.env.NODE_ENV !== 'production') {
+        const entry = (0, node_path_1.resolve)(process.cwd(), '..', 'specrails-core', 'dist', 'agent-runtime', 'index.js');
+        if ((0, node_fs_1.existsSync)(entry))
+            return entry;
+    }
+    return null;
+}
+/** The api probe is stable for a given CLI file; repeated settings saves need not respawn it.
+ * Validation stays uncached because its answer depends on the submitted configuration. */
+const apiProbeCache = new Map();
+function resetCoreAgentRuntimeApiCache() { apiProbeCache.clear(); }
+async function loadCoreAgentRuntime() {
+    const cli = findCoreAgentRuntimeCli();
+    if (!cli)
+        throw new Error('Programmatic agent runtime is unavailable. Build or bundle a compatible specrails-core release.');
+    // Core is ESM. Desktop ships both CJS and a pkg sidecar; importing external
+    // ESM from either depends on host-loader details. The bundled ordinary Node
+    // process is the same portable boundary used for execution and inspection.
+    const invoke = (args, input) => (0, node_child_process_1.execFileSync)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, ...args], {
+        cwd: (0, node_path_1.dirname)(cli), env: (0, win_spawn_1.windowsSpawnEnv)(process.env), input, encoding: 'utf8',
+        timeout: 15_000, maxBuffer: 2 * 1024 * 1024, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const stat = (0, node_fs_1.statSync)(cli);
+    const cached = apiProbeCache.get(cli);
+    if (!cached || cached.mtimeMs !== stat.mtimeMs || cached.size !== stat.size) {
+        const api = JSON.parse(invoke(['api']));
+        if (api.type !== 'runtime-api' || api.apiVersion !== 1) {
+            throw new Error('Incompatible Core agent runtime API; expected version 1. Update the paired Core bundle.');
+        }
+        apiProbeCache.set(cli, { mtimeMs: stat.mtimeMs, size: stat.size });
+    }
+    return {
+        RUNTIME_API_VERSION: 1,
+        rolePromptDefaults() {
+            const result = JSON.parse(invoke(['prompts']));
+            if (result.type !== 'runtime-role-prompts' || !['architect', 'developer', 'reviewer'].every(role => typeof result.defaults?.[role] === 'string' && result.defaults[role].trim()))
+                throw new Error('Core role prompt catalog is unavailable. Update the paired Core bundle.');
+            return result.defaults;
+        },
+        validateRuntimeConfig(input) {
+            const result = JSON.parse(invoke(['validate', '--stdin'], JSON.stringify(input)));
+            if (result.type !== 'runtime-config-valid')
+                throw new Error('Core did not validate the runtime configuration');
+            return input;
+        },
+    };
+}
+function findCoreAgentRuntimeCli() {
+    const entry = findCoreAgentRuntimeEntry();
+    if (!entry)
+        return null;
+    const cli = (0, node_path_1.join)((0, node_path_1.dirname)(entry), 'cli.js');
+    return (0, node_fs_1.existsSync)(cli) ? cli : null;
+}

package/server/dist/agent-runtime-metrics.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRuntimeEfficiency = readRuntimeEfficiency;
+const COUNTS = ['attempts', 'measuredAttempts', 'providerCalls', 'toolCalls', 'inputTokens', 'outputTokens', 'uncachedInputTokens', 'cacheReadInputTokens', 'cacheWriteInputTokens'];
+const KEYS = [...COUNTS, 'durationMs', 'agentDurationMs', 'costUsd'];
+const PHASES = ['architect', 'developer', 'verify', 'reviewer', 'archive'];
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null; }
+function counters(value) {
+    const input = object(value);
+    if (!input)
+        return null;
+    const output = {};
+    for (const key of KEYS) {
+        const number = input[key];
+        if (number === null && key !== 'attempts' && key !== 'measuredAttempts') {
+            output[key] = null;
+            continue;
+        }
+        if (typeof number !== 'number' || !Number.isFinite(number) || number < 0 || (COUNTS.includes(key) && !Number.isSafeInteger(number)))
+            return null;
+        output[key] = number;
+    }
+    if (output.measuredAttempts > output.attempts)
+        return null;
+    return output;
+}
+/** Older Core versions omit metrics; malformed/unknown versions do not break run controls. */
+function readRuntimeEfficiency(value) {
+    const input = object(value);
+    if (input?.schemaVersion !== 1 || !Array.isArray(input.phases) || input.phases.length > PHASES.length)
+        return undefined;
+    const total = counters(input.total);
+    if (!total)
+        return undefined;
+    const phases = [];
+    for (const raw of input.phases) {
+        const phase = object(raw), count = counters(phase);
+        if (!phase || !count || typeof phase.stepId !== 'string' || !PHASES.includes(phase.stepId) || phases.some(item => item.stepId === phase.stepId))
+            return undefined;
+        for (const key of ['providers', 'models'])
+            if (!Array.isArray(phase[key]) || phase[key].length > 50 || !phase[key].every((item) => typeof item === 'string' && item.length > 0 && item.length <= 256))
+                return undefined;
+        phases.push({ ...count, stepId: phase.stepId, providers: [...phase.providers], models: [...phase.models] });
+    }
+    return { schemaVersion: 1, total, phases };
+}

package/server/dist/agent-runtime-paths.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAgentRuntimeRequest = hasAgentRuntimeRequest;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const workspace_resolution_1 = require("./workspace-resolution");
+function hasAgentRuntimeRequest(project, runId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(runId))
+        return false;
+    const file = (0, node_path_1.join)((0, workspace_resolution_1.resolveProjectExecution)(project).specrailsDir, 'pipeline', runId, 'agent-runtime-request.json');
+    return (0, node_fs_1.existsSync)(file);
+}

package/server/dist/agent-runtime-repositories.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolRepositories = toolRepositories;
+const node_path_1 = require("node:path");
+/** Attribute only explicit paths or repository roots present in a tool action.
+ * Never carry a previous action's repository into an unrelated tool call. */
+function toolRepositories(event, repositories, defaultCwd) {
+    const found = new Set();
+    const cwd = typeof event.cwd === 'string' && (0, node_path_1.isAbsolute)(event.cwd) ? event.cwd : defaultCwd;
+    const paths = Array.isArray(event.targetPaths) ? event.targetPaths.filter((p) => typeof p === 'string') : [];
+    if (!paths.length && typeof event.detail === 'string' && (0, node_path_1.isAbsolute)(event.detail) && !event.detail.endsWith('…'))
+        paths.push(event.detail);
+    for (const target of paths) {
+        const absolute = (0, node_path_1.resolve)(cwd, target);
+        const matches = repositories.filter(repo => {
+            if (!repo.path)
+                return false;
+            const suffix = (0, node_path_1.relative)(repo.path, absolute);
+            return suffix === '' || (!(0, node_path_1.isAbsolute)(suffix) && suffix !== '..' && !suffix.startsWith('..' + node_path_1.sep));
+        }).sort((a, b) => b.path.length - a.path.length);
+        if (matches[0])
+            found.add(matches[0].id);
+    }
+    // Shell activity may contain `cd /repo && ...` or address several repositories.
+    if (!paths.length && typeof event.detail === 'string') {
+        for (const repo of repositories) {
+            if (!repo.path)
+                continue;
+            const escaped = repo.path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            if (new RegExp('(?:^|[\\s\\x22\\x27=])' + escaped + '(?=$|[\\s/\\\\\\x22\\x27;&])').test(event.detail))
+                found.add(repo.id);
+        }
+    }
+    if (!found.size && !paths.length && typeof event.cwd === 'string' && (0, node_path_1.isAbsolute)(event.cwd))
+        return toolRepositories({ targetPaths: [event.cwd] }, repositories, defaultCwd);
+    return repositories.filter(repo => found.has(repo.id));
+}

package/server/dist/agent-runtime-settings-router.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgentRuntimeSettingsRoutes = registerAgentRuntimeSettingsRoutes;
+const node_fs_1 = require("node:fs");
+const agent_runtime_loader_1 = require("./agent-runtime-loader");
+const agent_runtime_settings_1 = require("./agent-runtime-settings");
+const agent_runtime_verification_suggestions_1 = require("./agent-runtime-verification-suggestions");
+const project_repositories_1 = require("./project-repositories");
+function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
+    router.get('/:projectId/agent-runtime/config', (_req, res) => {
+        try {
+            const project = ctx(_req).project;
+            const configured = (0, node_fs_1.existsSync)((0, agent_runtime_settings_1.agentRuntimeConfigPath)(project));
+            const config = (0, agent_runtime_settings_1.loadAgentRuntimeConfig)(project);
+            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null });
+        }
+        catch (err) {
+            const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;
+            res.status(validation ? 422 : 500).json({ error: validation ? 'invalid_runtime_config' : 'runtime_config_read_failed', message: validation ? err.message : 'Could not read runtime configuration' });
+        }
+    });
+    /** Offline detection of each repository's own checks; never invokes a model.
+     *  Verification stays optional: the architect proposes commands for uncovered
+     *  repositories at run time, and Core admits repositories without any check. */
+    router.get('/:projectId/agent-runtime/verification-suggestions', (req, res) => {
+        try {
+            const project = ctx(req).project;
+            const repositories = (0, project_repositories_1.getProjectRepositories)(project).map((repository) => ({ id: repository.id, name: repository.name, path: repository.path }));
+            res.json({ repositories: repositories.map(({ id, name }) => ({ id, name })), suggestions: (0, agent_runtime_verification_suggestions_1.suggestVerificationCommands)(repositories) });
+        }
+        catch {
+            res.status(500).json({ error: 'verification_suggestions_failed', message: 'Could not inspect the project repositories' });
+        }
+    });
+    router.put('/:projectId/agent-runtime/config', async (req, res) => {
+        try {
+            (0, agent_runtime_settings_1.validateAgentRuntimeConfig)(req.body);
+            const config = (0, agent_runtime_settings_1.validateAgentRuntimeConfig)({ ...req.body, enabled: true, providers: (0, agent_runtime_settings_1.loadRuntimeProviders)() });
+            const runtimeAvailable = (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null;
+            if (config.enabled && !runtimeAvailable) {
+                res.status(503).json({ error: 'runtime_unavailable', message: 'Update Core to an installation with the agent runtime before enabling it' });
+                return;
+            }
+            if (config.enabled && runtimeAvailable) {
+                try {
+                    (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).validateRuntimeConfig(config);
+                }
+                catch {
+                    res.status(503).json({ error: 'runtime_incompatible', message: 'The installed Core runtime could not validate this configuration; update Core and retry' });
+                    return;
+                }
+            }
+            const saved = (0, agent_runtime_settings_1.saveAgentRuntimeConfig)(ctx(req).project, config);
+            res.json({ configured: true, config: saved, runtimeAvailable });
+        }
+        catch (err) {
+            const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;
+            res.status(validation ? 400 : 500).json({ error: validation ? 'invalid_runtime_config' : 'runtime_config_write_failed', message: validation ? err.message : 'Could not save runtime configuration' });
+        }
+    });
+}