specrails-desktop 2.46.0 → 2.48.0

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

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRuntimeHistory = writeRuntimeHistory;
+exports.readRuntimeHistory = readRuntimeHistory;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const agent_runtime_metrics_1 = require("./agent-runtime-metrics");
+const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+/** A replaceable projection, not an authority to resume, accept or deliver code. */
+function writeRuntimeHistory(contextPath, input) {
+    const contextText = node_fs_1.default.readFileSync(contextPath, 'utf8'), context = JSON.parse(contextText);
+    let selection;
+    try {
+        selection = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-selection.json'), 'utf8'));
+    }
+    catch { /* Old hosts have no explicit provenance. */ }
+    const result = { runId: context.runId, status: typeof input.status === 'string' ? input.status : 'failed', nextStep: typeof input.nextStep === 'string' ? input.nextStep : null,
+        updatedAt: new Date().toISOString(), ...(typeof input.error === 'string' ? { error: input.error.slice(0, 4000) } : {}),
+        metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(input.metrics), efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(input.efficiencySummary), selection, context.runId), steps: {} };
+    const payload = JSON.stringify({ schemaVersion: 1, contextHash: hash(contextText), result });
+    const file = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-history.json'), temporary = file + '.' + (0, node_crypto_1.randomUUID)() + '.tmp';
+    try {
+        node_fs_1.default.writeFileSync(temporary, JSON.stringify({ payload, integrity: hash(payload) }), { mode: 0o600, flag: 'wx' });
+        node_fs_1.default.renameSync(temporary, file);
+    }
+    finally {
+        node_fs_1.default.rmSync(temporary, { force: true });
+    }
+}
+function readRuntimeHistory(contextPath) {
+    const file = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-history.json');
+    if (!node_fs_1.default.existsSync(file))
+        return null;
+    if (node_fs_1.default.lstatSync(file).isSymbolicLink() || node_fs_1.default.statSync(file).size > 128 * 1024)
+        throw new Error('Historical runtime projection is invalid');
+    const envelope = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+    if (typeof envelope.payload !== 'string' || hash(envelope.payload) !== envelope.integrity)
+        throw new Error('Historical runtime projection integrity failed');
+    const value = JSON.parse(envelope.payload), contextText = node_fs_1.default.readFileSync(contextPath, 'utf8');
+    if (value.schemaVersion !== 1 || value.contextHash !== hash(contextText) || value.result?.runId !== JSON.parse(contextText).runId || !['running', 'succeeded', 'paused', 'failed', 'blocked', 'cancelled'].includes(value.result.status))
+        throw new Error('Historical runtime projection scope changed');
+    return { ...value.result, metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(value.result.metrics), efficiencySummary: (0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(value.result.efficiencySummary), steps: {} };
+}

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

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.findCoreAgentRuntimeEntry = findCoreAgentRuntimeEntry;
 exports.resetCoreAgentRuntimeApiCache = resetCoreAgentRuntimeApiCache;
 exports.loadCoreAgentRuntime = loadCoreAgentRuntime;
+exports.requireRuntimeCapabilities = requireRuntimeCapabilities;
+exports.validateRoleCapabilities = validateRoleCapabilities;
+exports.validateRequestedRoleEfforts = validateRequestedRoleEfforts;
 exports.findCoreAgentRuntimeCli = findCoreAgentRuntimeCli;
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
@@ -11,6 +14,7 @@ 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");
+const agent_runtime_package_1 = require("./agent-runtime-package");
 /** An explicit or bundled installation is authoritative: never silently replace
  * a broken production bundle with a developer's checkout. */
 function findCoreAgentRuntimeEntry() {
@@ -42,7 +46,7 @@ function findCoreAgentRuntimeEntry() {
     }
     return null;
 }
-/** The api probe is stable for a given CLI file; repeated settings saves need not respawn it.
+/** The api probe is stable for executable package content; 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(); }
@@ -57,17 +61,34 @@ async function loadCoreAgentRuntime() {
         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 fingerprint = (0, agent_runtime_package_1.runtimeEntryFingerprint)(cli);
     const cached = apiProbeCache.get(cli);
-    if (!cached || cached.mtimeMs !== stat.mtimeMs || cached.size !== stat.size) {
-        const api = JSON.parse(invoke(['api']));
+    let api = cached?.fingerprint === fingerprint ? cached.api : undefined;
+    if (!api) {
+        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 });
+        if (api.capabilities !== undefined && (!api.capabilities || typeof api.capabilities !== 'object' || Array.isArray(api.capabilities) || Object.values(api.capabilities).some(value => !Number.isSafeInteger(value) || value < 1)))
+            throw new Error('Core returned malformed runtime capabilities');
+        if (api.workflowVersions !== undefined && (!Array.isArray(api.workflowVersions) || !api.workflowVersions.every(value => typeof value === 'string' && /^\d+$/.test(value))))
+            throw new Error('Core returned malformed workflow versions');
+        if (api.runtimeIdentity !== undefined) {
+            const identity = api.runtimeIdentity;
+            if (!identity || identity.apiVersion !== 1 || !['packageVersion', 'workflowVersion', 'instructionsVersion', 'packageIntegrity'].every(key => typeof identity[key] === 'string') || !/^sha256:[a-f0-9]{64}$/.test(identity.packageIntegrity))
+                throw new Error('Core returned malformed runtime identity');
+        }
+        apiProbeCache.set(cli, { fingerprint, api });
     }
     return {
         RUNTIME_API_VERSION: 1,
+        api,
+        capabilities(input) {
+            if (api.capabilities?.efficientRoleExecution !== 1)
+                throw new Error('Installed Core does not support role capability introspection. Update the paired Core package.');
+            const result = JSON.parse(invoke(['capabilities', '--stdin'], JSON.stringify(input)));
+            return { ...validateRoleCapabilities(result, input), runtimeIdentity: api.runtimeIdentity };
+        },
         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()))
@@ -75,6 +96,7 @@ async function loadCoreAgentRuntime() {
             return result.defaults;
         },
         validateRuntimeConfig(input) {
+            requireRuntimeCapabilities(api, 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');
@@ -82,6 +104,63 @@ async function loadCoreAgentRuntime() {
         },
     };
 }
+function requireRuntimeCapabilities(api, input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return;
+    const config = input;
+    if ((config.efficiency !== undefined || Object.values(config.agents ?? {}).some(role => role?.effort !== undefined || role?.escalation !== undefined)) && api.capabilities?.efficientRoleExecution !== 1)
+        throw new Error('Requested role efficiency policy is unsupported by this Core runtime. Update the paired Core package.');
+    if (Array.isArray(config.verification) && config.verification.some(check => check?.policy !== undefined || check?.key !== undefined || check?.label !== undefined) && api.capabilities?.reproducibleVerification !== 1)
+        throw new Error('Requested verification policy is unsupported by this Core runtime. Update the paired Core package.');
+}
+/** Validate transport evidence against the exact submitted role selections. */
+function validateRoleCapabilities(value, input) {
+    const invalid = () => { throw new Error('Core returned malformed role capabilities'); };
+    const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : invalid();
+    const result = object(value), config = object(input);
+    const choices = Object.entries(object(config.agents));
+    if (result.type !== 'runtime-capabilities' || result.schemaVersion !== 1 || !Array.isArray(result.roles) || result.roles.length > 6)
+        return invalid();
+    const expected = choices.flatMap(([role, value]) => {
+        const selected = object(value);
+        return [['base', selected], ...(selected.escalation ? [['escalation', object(selected.escalation)]] : [])].map(([tier, choice]) => {
+            const model = choice;
+            return { role, tier: String(tier), provider: selected.provider, model: model.model ?? null, requestedEffort: model.effort ?? null };
+        });
+    });
+    if (expected.length !== result.roles.length || expected.length < 3)
+        return invalid();
+    const seen = new Set();
+    const roles = result.roles.map(value => {
+        const row = object(value);
+        const selected = expected.find(item => Object.entries(item).every(([key, value]) => row[key] === value));
+        if (!selected)
+            return invalid();
+        const key = String(row.role) + ':' + String(row.tier);
+        if (seen.has(key))
+            return invalid();
+        seen.add(key);
+        if (typeof row.transport !== 'string' || !row.transport || row.transport.length > 128 || !['supported', 'unsupported', 'unknown'].includes(String(row.continuation)) || !['supported', 'unsupported', 'unknown'].includes(String(row.effortSupport)) || typeof row.observedModel !== 'boolean' || typeof row.observedEffort !== 'boolean')
+            return invalid();
+        if (row.supportedEfforts !== null && (!Array.isArray(row.supportedEfforts) || row.supportedEfforts.length > 32 || !row.supportedEfforts.every((level) => typeof level === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(level))))
+            return invalid();
+        const levels = row.supportedEfforts;
+        if (row.effortSupport === 'supported' && !levels?.length || row.effortSupport === 'unknown' && levels !== null || row.effortSupport === 'unsupported' && levels?.length !== 0)
+            return invalid();
+        return { ...selected, transport: row.transport, continuation: row.continuation, effortSupport: row.effortSupport, supportedEfforts: levels, observedModel: row.observedModel, observedEffort: row.observedEffort };
+    });
+    return { type: 'runtime-capabilities', schemaVersion: 1, roles };
+}
+function validateRequestedRoleEfforts(runtime, config) {
+    if (!Object.values(config.agents).some(role => role.effort !== undefined || role.escalation?.effort !== undefined))
+        return;
+    if (!runtime.capabilities)
+        throw new Error('Installed Core cannot validate requested role effort');
+    const result = validateRoleCapabilities(runtime.capabilities(config), config);
+    for (const row of result.roles)
+        if (row.requestedEffort !== null && (row.effortSupport !== 'supported' || !row.supportedEfforts?.includes(String(row.requestedEffort))))
+            throw new Error(`${row.role} (${row.tier}): effort '${row.requestedEffort}' is not confirmed for ${row.transport}. Select provider default or a supported effort.`);
+}
 function findCoreAgentRuntimeCli() {
     const entry = findCoreAgentRuntimeEntry();
     if (!entry)

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

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readRuntimeEfficiency = readRuntimeEfficiency;
+exports.readRuntimeEfficiencySummary = readRuntimeEfficiencySummary;
+exports.applyRuntimeSelectionOrigins = applyRuntimeSelectionOrigins;
 const COUNTS = ['attempts', 'measuredAttempts', 'providerCalls', 'toolCalls', 'inputTokens', 'outputTokens', 'uncachedInputTokens', 'cacheReadInputTokens', 'cacheWriteInputTokens'];
 const KEYS = [...COUNTS, 'durationMs', 'agentDurationMs', 'costUsd'];
-const PHASES = ['architect', 'developer', 'verify', 'reviewer', 'archive'];
+const PHASES = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
 function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null; }
 function counters(value) {
     const input = object(value);
@@ -44,3 +46,77 @@ function readRuntimeEfficiency(value) {
     }
     return { schemaVersion: 1, total, phases };
 }
+function readRuntimeEfficiencySummary(value) {
+    const input = object(value), invocations = object(input?.invocations), checks = object(input?.checks);
+    if (!input || input.schemaVersion !== 1 || typeof input.runId !== 'string' || input.runId.length > 128 || typeof input.workflowVersion !== 'string' || input.workflowVersion.length > 16 || !['pending', 'validated', 'with-exceptions', 'blocked'].includes(String(input.technicalAcceptance)) || !invocations || !checks || !Array.isArray(input.roles) || input.roles.length > 3)
+        return undefined;
+    if (typeof input.archive !== 'string' || input.archive.length > 32 || typeof input.delivery !== 'string' || input.delivery.length > 32 || typeof invocations.complete !== 'boolean' || typeof checks.available !== 'boolean')
+        return undefined;
+    const count = (value, nullable = true) => (nullable && value === null) || typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+    for (const key of ['total', 'fullContexts', 'incrementalContexts'])
+        if (!count(invocations[key], false))
+            return undefined;
+    for (const key of ['promptBytes', 'contextBytes', 'handoffBytes'])
+        if (!count(invocations[key]))
+            return undefined;
+    if (checks.complete !== undefined && typeof checks.complete !== 'boolean' || checks.invalidated !== undefined && !count(checks.invalidated))
+        return undefined;
+    for (const key of ['executed', 'reused', 'notRun'])
+        if (!count(checks[key]))
+            return undefined;
+    if (checks.durationMs !== null && (typeof checks.durationMs !== 'number' || !Number.isFinite(checks.durationMs) || checks.durationMs < 0))
+        return undefined;
+    for (const key of ['planHash', 'candidateHash'])
+        if (input[key] !== null && (typeof input[key] !== 'string' || !/^[a-f0-9]{64}$/.test(input[key])))
+            return undefined;
+    if (!Array.isArray(input.currentEvidenceIds) || input.currentEvidenceIds.length > 100 || !input.currentEvidenceIds.every(id => typeof id === 'string' && /^[a-f0-9]{64}$/.test(id)))
+        return undefined;
+    const kinds = object(invocations.byKind);
+    if (!kinds || Object.keys(kinds).length !== 5 || !['initial', 'correction', 'repair', 'deepen', 'session-fallback'].every(key => count(kinds[key], false)))
+        return undefined;
+    const roles = [];
+    for (const raw of input.roles) {
+        const role = object(raw);
+        if (!role || !['architect', 'developer', 'reviewer'].includes(String(role.role)) || roles.some(item => item.role === role.role))
+            return undefined;
+        const row = { role: String(role.role) };
+        for (const key of ['provider', 'model', 'effort', 'observedModel', 'observedEffort', 'origin', 'tier']) {
+            if (role[key] !== null && (typeof role[key] !== 'string' || role[key].length > 256))
+                return undefined;
+            row[key] = role[key];
+        }
+        if (!['base', 'escalation'].includes(String(row.tier)) || typeof row.origin !== 'string')
+            return undefined;
+        roles.push(row);
+    }
+    let escalations;
+    if (input.escalations !== undefined) {
+        if (!Array.isArray(input.escalations) || input.escalations.length > 16 || typeof input.escalationsTruncated !== 'boolean')
+            return undefined;
+        escalations = [];
+        for (const item of input.escalations) {
+            const raw = object(item);
+            if (!raw || !['architect', 'developer', 'reviewer'].includes(String(raw.role)))
+                return undefined;
+            const row = { role: String(raw.role) };
+            for (const key of ['attemptId', 'provider', 'model', 'effort', 'reason']) {
+                if (raw[key] !== null && (typeof raw[key] !== 'string' || raw[key].length > 256) || ['attemptId', 'provider'].includes(key) && typeof raw[key] !== 'string')
+                    return undefined;
+                row[key] = raw[key];
+            }
+            escalations.push(row);
+        }
+    }
+    return { ...(escalations ? { escalations, escalationsTruncated: input.escalationsTruncated } : {}), schemaVersion: 1, currentEvidenceIds: [...input.currentEvidenceIds], planHash: input.planHash, candidateHash: input.candidateHash, runId: input.runId, workflowVersion: input.workflowVersion, technicalAcceptance: input.technicalAcceptance, archive: input.archive, delivery: input.delivery, roles,
+        invocations: { total: invocations.total, complete: invocations.complete, byKind: { ...kinds }, promptBytes: invocations.promptBytes, contextBytes: invocations.contextBytes, handoffBytes: invocations.handoffBytes, fullContexts: invocations.fullContexts, incrementalContexts: invocations.incrementalContexts },
+        checks: { ...(checks.complete === undefined ? {} : { complete: checks.complete }), ...(checks.invalidated === undefined ? {} : { invalidated: checks.invalidated }), available: checks.available, executed: checks.executed, reused: checks.reused, notRun: checks.notRun, durationMs: checks.durationMs } };
+}
+/** Provenance is host-owned; it never changes Core's frozen provider selection. */
+function applyRuntimeSelectionOrigins(summary, selection, runId) {
+    const record = object(selection), origins = object(record?.origins);
+    if (!summary || record?.schemaVersion !== 1 || record.runId !== runId || !origins)
+        return summary;
+    if (!['architect', 'developer', 'reviewer'].every(role => ['project-role', 'default', ...(role === 'developer' ? ['explicit-launch-override'] : [])].includes(String(origins[role]))))
+        return summary;
+    return { ...summary, roles: summary.roles.map(role => ({ ...role, origin: String(origins[role.role]) })) };
+}

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

@@ -0,0 +1,205 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeEntryFingerprint = runtimeEntryFingerprint;
+exports.retainAgentRuntime = retainAgentRuntime;
+exports.resolveRetainedAgentRuntime = resolveRetainedAgentRuntime;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const SHIPPED = ['package.json', 'dist', 'bin', 'templates', 'schemas', 'commands', 'integration-contract.json', 'pinned-versions.json'];
+const SAFE_PACKAGE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i;
+function packageRoot(file, name) {
+    let directory = node_path_1.default.dirname(node_fs_1.default.realpathSync(file));
+    for (;;) {
+        const manifest = node_path_1.default.join(directory, 'package.json');
+        if (node_fs_1.default.existsSync(manifest)) {
+            const pkg = JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf8'));
+            if (pkg.name === (name ?? 'specrails-core'))
+                return directory;
+        }
+        const parent = node_path_1.default.dirname(directory);
+        if (directory === parent)
+            throw new Error('Core runtime does not resolve to an identifiable package');
+        directory = parent;
+    }
+}
+/** Content identity also detects same-size edits with preserved timestamps. */
+function runtimeEntryFingerprint(cli) {
+    let root;
+    try {
+        root = packageRoot(cli);
+    }
+    catch {
+        return (0, node_crypto_1.createHash)('sha256').update(node_fs_1.default.readFileSync(cli)).digest('hex');
+    }
+    return treeDigest(root, SHIPPED);
+}
+function treeDigest(root, entries = node_fs_1.default.readdirSync(root).sort()) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    let files = 0, bytes = 0;
+    const visit = (relative) => {
+        const file = node_path_1.default.join(root, relative), stat = node_fs_1.default.lstatSync(file);
+        if (stat.isSymbolicLink())
+            throw new Error('Retained Core package contains a symbolic link');
+        if (stat.isDirectory())
+            for (const name of node_fs_1.default.readdirSync(file).sort())
+                visit(node_path_1.default.posix.join(relative, name));
+        else if (stat.isFile()) {
+            if (++files > 100_000 || (bytes += stat.size) > 1024 * 1024 * 1024)
+                throw new Error('Core runtime package exceeds retention limits');
+            hash.update(JSON.stringify([relative, stat.size])).update('\0').update(node_fs_1.default.readFileSync(file)).update('\0');
+        }
+        else
+            throw new Error('Core runtime package contains a nonregular file');
+    };
+    for (const entry of entries)
+        if (node_fs_1.default.existsSync(node_path_1.default.join(root, entry)))
+            visit(entry);
+    return hash.digest('hex');
+}
+/** Copy only the selected package and its installed production dependency
+ * closure. Resolution follows npm's actual nested versions, without downloads. */
+function copyInstalledPackage(source, destination) {
+    const installed = new Map();
+    const copying = new Set();
+    let files = 0, bytes = 0, packages = 0;
+    const copy = (from, to, boundary) => {
+        const stat = node_fs_1.default.lstatSync(from);
+        if (stat.isSymbolicLink()) {
+            const resolved = node_fs_1.default.realpathSync(from), relative = node_path_1.default.relative(boundary, resolved);
+            if (relative.startsWith('..') || node_path_1.default.isAbsolute(relative))
+                throw new Error('Core package symlink escapes its package');
+            copy(resolved, to, boundary);
+        }
+        else if (stat.isDirectory()) {
+            const real = node_fs_1.default.realpathSync(from);
+            if (copying.has(real))
+                throw new Error('Core package contains a cyclic symbolic link');
+            copying.add(real);
+            node_fs_1.default.mkdirSync(to, { recursive: true });
+            try {
+                for (const name of node_fs_1.default.readdirSync(from).sort())
+                    if (!['node_modules', '.git', '.bin'].includes(name))
+                        copy(node_path_1.default.join(from, name), node_path_1.default.join(to, name), boundary);
+            }
+            finally {
+                copying.delete(real);
+            }
+        }
+        else if (stat.isFile()) {
+            if (++files > 100_000 || (bytes += stat.size) > 1024 * 1024 * 1024)
+                throw new Error('Core runtime package exceeds retention limits');
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(to), { recursive: true });
+            node_fs_1.default.copyFileSync(from, to);
+            node_fs_1.default.chmodSync(to, stat.mode & 0o777);
+        }
+        else
+            throw new Error('Core package contains a nonregular file');
+    };
+    const resolveDependency = (name, from) => {
+        const require = (0, node_module_1.createRequire)(node_path_1.default.join(from, 'package.json'));
+        try {
+            return packageRoot(require.resolve(name + '/package.json'), name);
+        }
+        catch {
+            return packageRoot(require.resolve(name), name);
+        }
+    };
+    const install = (from, to, root = false) => {
+        if (++packages > 2000)
+            throw new Error('Core dependency closure exceeds retention limits');
+        if (root)
+            for (const entry of SHIPPED) {
+                if (node_fs_1.default.existsSync(node_path_1.default.join(from, entry)))
+                    copy(node_path_1.default.join(from, entry), node_path_1.default.join(to, entry), from);
+            }
+        else
+            copy(from, to, from);
+        installed.set(node_fs_1.default.realpathSync(to), from);
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(from, 'package.json'), 'utf8'));
+        for (const name of Object.keys({ ...pkg.dependencies, ...pkg.optionalDependencies }).sort()) {
+            if (!SAFE_PACKAGE.test(name))
+                throw new Error('Invalid Core package dependency');
+            let dependency;
+            try {
+                dependency = resolveDependency(name, from);
+            }
+            catch (error) {
+                if (pkg.optionalDependencies?.[name])
+                    continue;
+                throw error;
+            }
+            try {
+                const present = resolveDependency(name, to);
+                if (installed.get(present) === dependency)
+                    continue;
+            }
+            catch { /* Not copied into this resolution scope yet. */ }
+            install(dependency, node_path_1.default.join(to, 'node_modules', name));
+        }
+    };
+    install(source, destination, true);
+}
+function retainAgentRuntime(cli, contextPath) {
+    const pinFile = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-package.json');
+    if (node_fs_1.default.existsSync(pinFile))
+        return resolveRetainedAgentRuntime(contextPath);
+    const realCli = node_fs_1.default.realpathSync(cli);
+    const root = packageRoot(realCli);
+    const relativeCli = node_path_1.default.relative(root, realCli);
+    if (relativeCli.startsWith('..') || node_path_1.default.isAbsolute(relativeCli))
+        throw new Error('Core CLI escapes its package');
+    const cache = node_path_1.default.join(node_path_1.default.dirname(node_path_1.default.dirname(contextPath)), 'runtime-packages');
+    node_fs_1.default.mkdirSync(cache, { recursive: true, mode: 0o700 });
+    const staged = node_path_1.default.join(cache, '.staged-' + (0, node_crypto_1.randomUUID)());
+    try {
+        copyInstalledPackage(root, staged);
+        const integrity = treeDigest(staged);
+        const retained = node_path_1.default.join(cache, integrity);
+        if (node_fs_1.default.existsSync(retained)) {
+            if (treeDigest(retained) !== integrity)
+                throw new Error('Retained Core runtime integrity changed');
+        }
+        else {
+            try {
+                node_fs_1.default.renameSync(staged, retained);
+            }
+            catch (error) {
+                if (!node_fs_1.default.existsSync(retained) || treeDigest(retained) !== integrity)
+                    throw error;
+            }
+        }
+        const pin = { schemaVersion: 1, packageVersion: JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'package.json'), 'utf8')).version, integrity, root: retained, cli: relativeCli };
+        try {
+            node_fs_1.default.writeFileSync(pinFile, JSON.stringify(pin) + '\n', { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || resolveRetainedAgentRuntime(contextPath) !== node_path_1.default.join(retained, relativeCli))
+                throw error;
+        }
+        return node_path_1.default.join(retained, relativeCli);
+    }
+    finally {
+        node_fs_1.default.rmSync(staged, { recursive: true, force: true });
+    }
+}
+function resolveRetainedAgentRuntime(contextPath) {
+    const pinFile = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-package.json');
+    if (!node_fs_1.default.existsSync(pinFile))
+        throw new Error('Original runtime identity is unrecorded. Restore a proven original Core package before continuing this saved execution.');
+    const pin = JSON.parse(node_fs_1.default.readFileSync(pinFile, 'utf8'));
+    const expected = node_path_1.default.join(node_path_1.default.dirname(node_path_1.default.dirname(contextPath)), 'runtime-packages', pin.integrity);
+    if (pin.schemaVersion !== 1 || !/^[a-f0-9]{64}$/.test(pin.integrity) || pin.root !== expected || !node_fs_1.default.existsSync(expected) || node_fs_1.default.realpathSync(expected) !== node_path_1.default.resolve(expected)
+        || typeof pin.cli !== 'string' || node_path_1.default.isAbsolute(pin.cli) || pin.cli.split(/[\\/]/).includes('..'))
+        throw new Error('The original retained Core package is unavailable or invalid. Restore it before continuing.');
+    if (treeDigest(expected) !== pin.integrity)
+        throw new Error('The original retained Core package failed its integrity check. Restore it before continuing.');
+    const cli = node_path_1.default.join(expected, pin.cli);
+    if (!node_fs_1.default.statSync(cli).isFile())
+        throw new Error('The original Core executable is unavailable');
+    return cli;
+}

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

@@ -4,15 +4,70 @@ 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_settings_2 = require("./agent-runtime-settings");
 const agent_runtime_verification_suggestions_1 = require("./agent-runtime-verification-suggestions");
 const project_repositories_1 = require("./project-repositories");
+const agent_runtime_effective_config_1 = require("./agent-runtime-effective-config");
+/** Raw request body → same body with every local role's missing model filled (validation then passes). */
+function withDefaultRoleModels(body) {
+    const agents = body.agents;
+    const providers = body.providers;
+    if (!agents || typeof agents !== 'object' || !Array.isArray(providers))
+        return body;
+    // Only LOCAL roles: a CLI role saved without a model keeps meaning "provider default" (never frozen into the file).
+    const fixer = body.fixer && typeof body.fixer === 'object' ? structuredClone(body.fixer) : undefined;
+    const filled = (0, agent_runtime_effective_config_1.fillDefaultRoleModels)({ agents: structuredClone(agents), providers: providers, ...(fixer ? { fixer: fixer } : {}) }, { localOnly: true });
+    return { ...body, agents: filled.agents, ...(filled.fixer ? { fixer: filled.fixer } : {}) };
+}
+const loop_role_engines_1 = require("./loop-role-engines");
 function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
-    router.get('/:projectId/agent-runtime/config', (_req, res) => {
+    /** Guardrail catalog of the loaded Core (configurable-guardrails): ids + phase; the UI owns labels. `supported:false` on older cores. */
+    router.get('/:projectId/agent-runtime/guardrails', async (_req, res) => {
+        try {
+            const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+            const supported = runtime.api?.capabilities?.configurableGuardrails === 1;
+            const catalog = supported && Array.isArray(runtime.api?.guardrails) ? runtime.api.guardrails.filter((item) => item && typeof item.id === 'string' && typeof item.phase === 'string') : [];
+            res.json({ supported, catalog });
+        }
+        catch {
+            res.json({ supported: false, catalog: [] });
+        }
+    });
+    /** Loop-side role engines (verifier / decider) for `roles` rail launches — hybrid-role-engines. */
+    router.get('/:projectId/agent-runtime/loop-roles', (req, res) => {
+        try {
+            res.json({ roles: (0, loop_role_engines_1.loadLoopRoleEngines)(ctx(req).project) });
+        }
+        catch {
+            res.status(500).json({ error: 'loop_roles_read_failed' });
+        }
+    });
+    router.put('/:projectId/agent-runtime/loop-roles', (req, res) => {
+        try {
+            const project = ctx(req).project;
+            const roles = (0, loop_role_engines_1.validateLoopRoleEngines)(req.body?.roles ?? req.body ?? {}, project);
+            (0, loop_role_engines_1.saveLoopRoleEngines)(project, roles);
+            res.json({ roles });
+        }
+        catch (error) {
+            if (error instanceof loop_role_engines_1.LoopRoleEnginesError) {
+                res.status(400).json({ error: 'invalid_loop_roles', message: error.message });
+                return;
+            }
+            res.status(500).json({ error: 'loop_roles_write_failed' });
+        }
+    });
+    router.get('/:projectId/agent-runtime/config', async (_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 });
+            let efficiencyAvailable = false;
+            try {
+                efficiencyAvailable = (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).api?.capabilities?.efficientRoleExecution === 1;
+            }
+            catch { /* Ordinary settings remain readable without capability support. */ }
+            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;
@@ -32,18 +87,54 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
             res.status(500).json({ error: 'verification_suggestions_failed', message: 'Could not inspect the project repositories' });
         }
     });
+    router.post('/:projectId/agent-runtime/capabilities', async (req, res) => {
+        try {
+            const config = (0, agent_runtime_settings_1.validateAgentRuntimeConfig)(withDefaultRoleModels({ ...req.body, providers: (0, agent_runtime_settings_1.loadRuntimeProviders)(), enabled: true }));
+            const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+            if (!runtime.capabilities)
+                throw new Error('Installed Core does not support capability introspection');
+            // Core's schema is additionalProperties:false — strip the desktop-only
+            // connection fields (label/defaultModel/rates/supportsReasoningEffort) first.
+            res.json(await runtime.capabilities({ ...(0, agent_runtime_settings_2.forCoreRuntime)(config, runtime.api?.capabilities), providers: (0, agent_runtime_settings_2.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities)) }));
+        }
+        catch (error) {
+            // Core prints its verdict (`{"type":"runtime-result","status":"failed","error":…}`) before exiting non-zero: show that, not the generic "update Core" line.
+            const coreMessage = (() => { const out = error.stdout; if (typeof out !== 'string')
+                return undefined; try {
+                const parsed = JSON.parse(out.trim().split('\n').pop() ?? '');
+                return typeof parsed.error === 'string' ? parsed.error : undefined;
+            }
+            catch {
+                return undefined;
+            } })();
+            res.status(error instanceof agent_runtime_settings_1.AgentRuntimeConfigError || coreMessage ? 400 : 503).json({ error: 'runtime_capabilities_unavailable', message: error instanceof agent_runtime_settings_1.AgentRuntimeConfigError ? error.message : coreMessage ?? 'Update the paired Core runtime to inspect model capabilities' });
+        }
+    });
     router.put('/:projectId/agent-runtime/config', async (req, res) => {
         try {
-            (0, agent_runtime_settings_1.validateAgentRuntimeConfig)(req.body);
+            // A local role saved as "provider default" carries no model; fill the
+            // connection default (the launch rule) before the model-required check.
+            // The raw body is validated first (its own providers included — a
+            // credential in a submitted URL must be refused), then the stored
+            // connections replace them and the missing local-role models are filled
+            // from each connection's default before the model-required check.
+            // Saved WITHOUT filling local-role models: "provider default" stays a
+            // live reference to the connection's default (resolved at launch).
+            (0, agent_runtime_settings_1.validateAgentRuntimeConfig)({ ...req.body, providers: Array.isArray(req.body?.providers) ? req.body.providers : (0, agent_runtime_settings_1.loadRuntimeProviders)() });
             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;
             }
+            let efficiencyAvailable = false;
             if (config.enabled && runtimeAvailable) {
                 try {
-                    (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).validateRuntimeConfig(config);
+                    const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+                    const coreConfig = { ...(0, agent_runtime_settings_2.forCoreRuntime)((0, agent_runtime_effective_config_1.fillDefaultRoleModels)(structuredClone(config), { localOnly: true }), runtime.api?.capabilities), providers: (0, agent_runtime_settings_2.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities)) };
+                    runtime.validateRuntimeConfig(coreConfig);
+                    (0, agent_runtime_loader_1.validateRequestedRoleEfforts)(runtime, coreConfig);
+                    efficiencyAvailable = runtime.api?.capabilities?.efficientRoleExecution === 1;
                 }
                 catch {
                     res.status(503).json({ error: 'runtime_incompatible', message: 'The installed Core runtime could not validate this configuration; update Core and retry' });
@@ -51,7 +142,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 }
             }
             const saved = (0, agent_runtime_settings_1.saveAgentRuntimeConfig)(ctx(req).project, config);
-            res.json({ configured: true, config: saved, runtimeAvailable });
+            res.json({ configured: true, config: saved, runtimeAvailable, efficiencyAvailable });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;