specrails-desktop 2.46.0 → 2.48.0

package/server/dist/local-engine-detection.js

@@ -0,0 +1,118 @@
+"use strict";
+// Local (OpenAI-compatible) engine detection.
+//
+// A local connection has no binary to probe: reachability is decided by a
+// bounded `GET <baseUrl>/models`. The result feeds the app-level provider
+// detection singleton (provider-detection.ts) AND the local adapter's dynamic
+// model catalog (modelCatalog() reads `getCachedModels(id)`).
+//
+// Mapping (design D4):
+//   2xx + `data[]`         → installed + executable, authenticated, models
+//   401 / 403              → installed + executable, unauthenticated, []
+//   anything else / error  → installed: false (unreachable)
+//
+// Spec: openspec/changes/local-ai-engines/specs/provider-auto-detection/spec.md
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_PROBE_TIMEOUT_MS = void 0;
+exports.probeConnection = probeConnection;
+exports.setCachedProbe = setCachedProbe;
+exports.getCachedProbe = getCachedProbe;
+exports.getCachedModels = getCachedModels;
+exports.clearCachedProbe = clearCachedProbe;
+exports._resetForTests = _resetForTests;
+exports.LOCAL_PROBE_TIMEOUT_MS = 3000;
+function modelsUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, '')}/models`;
+}
+function extractModelIds(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const data = body.data;
+    if (!Array.isArray(data))
+        return null;
+    const ids = [];
+    for (const entry of data) {
+        if (entry && typeof entry === 'object' && typeof entry.id === 'string') {
+            ids.push(entry.id);
+        }
+    }
+    return ids;
+}
+/** Bounded, never-throwing reachability + models probe of one connection. */
+async function probeConnection(conn, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? exports.LOCAL_PROBE_TIMEOUT_MS;
+    const doFetch = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const startedAt = Date.now();
+    const latency = () => Date.now() - startedAt;
+    const headers = { accept: 'application/json' };
+    let apiKeyEnvMissing = false;
+    if (conn.apiKeyEnv) {
+        const key = env[conn.apiKeyEnv];
+        if (key && key.length > 0)
+            headers.authorization = `Bearer ${key}`;
+        else
+            apiKeyEnvMissing = true;
+    }
+    const extra = apiKeyEnvMissing ? { apiKeyEnvMissing: true } : {};
+    const unreachable = (error) => ({
+        reachable: false, installed: false, executable: false, authState: 'unknown',
+        models: [], latencyMs: latency(), error, ...extra,
+    });
+    let res;
+    try {
+        res = await doFetch(modelsUrl(conn.baseUrl), {
+            method: 'GET',
+            headers,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const timedOut = err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError');
+        return unreachable(timedOut ? `timed out after ${timeoutMs} ms` : message);
+    }
+    if (res.status === 401 || res.status === 403) {
+        return {
+            reachable: true, installed: true, executable: true, authState: 'unauthenticated',
+            models: [], latencyMs: latency(), error: `endpoint answered HTTP ${res.status} (not authorized)`, ...extra,
+        };
+    }
+    if (res.status < 200 || res.status >= 300) {
+        return unreachable(`endpoint answered HTTP ${res.status}`);
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return unreachable('endpoint did not return JSON');
+    }
+    const models = extractModelIds(body);
+    if (models === null)
+        return unreachable('endpoint response has no `data` array');
+    return {
+        reachable: true, installed: true, executable: true, authState: 'authenticated',
+        models, latencyMs: latency(), ...extra,
+    };
+}
+// ─── Module cache (per connection id) ────────────────────────────────────────
+const _cache = new Map();
+function setCachedProbe(id, result) {
+    _cache.set(id, result);
+}
+function getCachedProbe(id) {
+    return _cache.get(id) ?? null;
+}
+/** Models discovered by the most recent SUCCESSFUL probe of `id` (else []). */
+function getCachedModels(id) {
+    const cached = _cache.get(id);
+    return cached && cached.authState === 'authenticated' ? [...cached.models] : [];
+}
+function clearCachedProbe(id) {
+    _cache.delete(id);
+}
+function _resetForTests() {
+    _cache.clear();
+}

package/server/dist/loop-executors.js

@@ -19,6 +19,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const win_spawn_1 = require("./util/win-spawn");
 const providers_1 = require("./providers");
+const registry_1 = require("./providers/registry");
 const workspace_manager_1 = require("./workspace-manager");
 const claude_trust_1 = require("./claude-trust");
 const spawn_lifecycle_1 = require("./spawn-lifecycle");
@@ -222,7 +223,7 @@ function createLoopExecutors(opts = {}) {
                 return null;
             }
         },
-        async runAiStep({ coreRun, prompt, sessionId, provider, model, effort, profileName, cwd, repoDir, executionManifest, onLine, onRawLine, onSpawn, aiStepTimeoutMs, idleTimeoutMs }) {
+        async runAiStep({ runtimeProviderOverride, coreRun, prompt, sessionId, provider, model, effort, profileName, cwd, repoDir, executionManifest, onLine, onRawLine, onSpawn, aiStepTimeoutMs, idleTimeoutMs }) {
             const adapter = (0, providers_1.getAdapter)(provider);
             // First iteration spawns headless (rail-job); subsequent iterations resume
             // the session so the agent keeps prior context across iterations.
@@ -246,7 +247,7 @@ function createLoopExecutors(opts = {}) {
                 return (0, agent_runtime_bridge_1.runAgentRuntimeInvocation)({
                     contextPath: core.contextPath, cwd, env: { ...programmaticStepEnv(resolveEnv(), repoDir, executionManifest), SPECRAILS_EXECUTION_CONTEXT: core.contextPath }, configPath: runtimeConfigPath(cwd),
                     change: (0, agent_runtime_bridge_1.runtimeChangeName)(coreRun.runId), resume: admitted,
-                    defaultProvider: provider, selectedModel: model,
+                    defaultProvider: provider, providerOverride: runtimeProviderOverride,
                     onLine, onRawLine, onSpawn, timeoutMs: aiStepTimeoutMs,
                 });
             }
@@ -262,7 +263,7 @@ function createLoopExecutors(opts = {}) {
             const effectivePrompt = (0, runtime_1.formatProviderCommand)(adapter, [core?.promptPrefix, prompt].filter(Boolean).join('\n\n'), cwd, sessionId ?? undefined);
             const buildOpts = {
                 prompt: effectivePrompt,
-                ...(adapter.id === 'claude' ? { systemPrompt: loop_constants_1.FOREGROUND_RULE } : {}),
+                ...(adapter.id === 'claude' || (0, registry_1.isLocalAdapterId)(adapter.id) ? { systemPrompt: loop_constants_1.FOREGROUND_RULE } : {}),
                 model,
                 sessionId: sessionId ?? undefined,
                 reasoning_effort: effort,

package/server/dist/loop-role-engines.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopRoleEnginesError = exports.LOOP_ROLES = exports.ROLES_ENGINE = void 0;
+exports.loopRoleEnginesPath = loopRoleEnginesPath;
+exports.loadLoopRoleEngines = loadLoopRoleEngines;
+exports.validateLoopRoleEngines = validateLoopRoleEngines;
+exports.saveLoopRoleEngines = saveLoopRoleEngines;
+exports.resolveLoopRoleEngine = resolveLoopRoleEngine;
+// Per-project engines for the loop-side AI roles (hybrid-role-engines).
+//
+// The pipeline roles architect/developer/reviewer already live in the project's
+// `agent-runtime.json` (Settings ▸ Specrails Agents ▸ runtime) and Core runs
+// them on whatever provider each role names — cloud or local, mixed freely.
+// What kept a hybrid setup from working was the rail: a selected engine became
+// a `runtimeProviderOverride` that flattened all three roles, and the loop's
+// own AI steps (verify/fix, the Loop Decider) always inherited that engine.
+//
+// This module owns the two LOOP roles and the `roles` engine sentinel:
+//   - `verifier` — every non-core ai-step of the factory loop (verify, fix,
+//     freestyle-less prose steps) and the provider a custom loop's ai-steps run on.
+//   - `decider`  — the Loop Decider (a cheap/fast model is the natural pick).
+// A rail whose engine is `roles` launches WITHOUT a provider override (Core
+// keeps the per-role settings) and resolves the loop steps from this file.
+//
+// Storage: `<workspace>/.specrails/loop-role-engines.json`, next to
+// `agent-runtime.json`; absent ⇒ every loop role inherits the project's primary.
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const providers_1 = require("./providers");
+const spec_models_1 = require("./spec-models");
+const workspace_resolution_1 = require("./workspace-resolution");
+const provider_selection_1 = require("./provider-selection");
+/** The rail engine value meaning "per-role engines, no flattening override". */
+exports.ROLES_ENGINE = 'roles';
+exports.LOOP_ROLES = ['verifier', 'decider'];
+class LoopRoleEnginesError extends Error {
+}
+exports.LoopRoleEnginesError = LoopRoleEnginesError;
+function loopRoleEnginesPath(project) {
+    return node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(project).specrailsDir, 'loop-role-engines.json');
+}
+function loadLoopRoleEngines(project) {
+    const file = loopRoleEnginesPath(project);
+    if (!(0, node_fs_1.existsSync)(file))
+        return {};
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        const out = {};
+        for (const role of exports.LOOP_ROLES) {
+            const entry = raw[role];
+            if (entry && typeof entry === 'object' && typeof entry.provider === 'string') {
+                const { provider, model, effort } = entry;
+                out[role] = { provider, ...(typeof model === 'string' && model ? { model } : {}), ...(typeof effort === 'string' && effort ? { effort } : {}) };
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Validates against the project's DETECTED providers; an unknown role or provider is rejected, a stale model is rejected. */
+function validateLoopRoleEngines(value, project) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new LoopRoleEnginesError('Loop role engines must be an object');
+    const raw = value;
+    for (const key of Object.keys(raw))
+        if (!exports.LOOP_ROLES.includes(key))
+            throw new LoopRoleEnginesError(`Unknown loop role "${key}"`);
+    const out = {};
+    for (const role of exports.LOOP_ROLES) {
+        const entry = raw[role];
+        if (entry === undefined || entry === null)
+            continue;
+        if (typeof entry !== 'object' || Array.isArray(entry))
+            throw new LoopRoleEnginesError(`Loop role "${role}" must be an object`);
+        const { provider, model, effort, ...rest } = entry;
+        if (Object.keys(rest).length)
+            throw new LoopRoleEnginesError(`Loop role "${role}" has unknown fields: ${Object.keys(rest).join(', ')}`);
+        if (typeof provider !== 'string' || !provider.trim())
+            throw new LoopRoleEnginesError(`Loop role "${role}" needs a provider`);
+        const check = (0, provider_selection_1.validateRequestedProvider)(project, provider);
+        if (!check.ok)
+            throw new LoopRoleEnginesError(`Loop role "${role}": ${check.error}`);
+        const engine = { provider: check.provider };
+        if (model !== undefined && model !== null && model !== '') {
+            if (typeof model !== 'string' || model.length > 256 || /[\r\n\0]/.test(model))
+                throw new LoopRoleEnginesError(`Loop role "${role}" has an invalid model`);
+            if (!(0, spec_models_1.isValidModelForProvider)(model, check.provider))
+                throw new LoopRoleEnginesError(`Loop role "${role}": model "${model}" is not valid for provider "${check.provider}"`);
+            engine.model = model;
+        }
+        if (effort !== undefined && effort !== null && effort !== '') {
+            if (typeof effort !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(effort))
+                throw new LoopRoleEnginesError(`Loop role "${role}" has an invalid effort`);
+            engine.effort = effort;
+        }
+        out[role] = engine;
+    }
+    return out;
+}
+function saveLoopRoleEngines(project, value) {
+    const file = loopRoleEnginesPath(project);
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(file), { recursive: true });
+    (0, node_fs_1.writeFileSync)(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+}
+/**
+ * The engine a loop role runs on for THIS launch: the stored role engine when
+ * its provider is still detected, else the fallback (the rail's primary path).
+ * Model falls back to the adapter default; effort is dropped when the adapter
+ * cannot honour it (local engines without the opt-in) or the model rejects it.
+ */
+function resolveLoopRoleEngine(project, role, fallback, stored = loadLoopRoleEngines(project)) {
+    const entry = stored[role];
+    if (!entry)
+        return fallback;
+    const check = (0, provider_selection_1.validateRequestedProvider)(project, entry.provider);
+    if (!check.ok || !(0, providers_1.hasAdapter)(check.provider))
+        return fallback;
+    const adapter = (0, providers_1.getAdapter)(check.provider);
+    const model = entry.model && (0, spec_models_1.isValidModelForProvider)(entry.model, check.provider) ? entry.model : adapter.defaultModel();
+    const effortAllowed = !((0, providers_1.isLocalAdapterId)(check.provider) && !adapter.capabilities.supportsReasoningEffort);
+    const allowed = effortAllowed ? (0, providers_1.reasoningEffortsForModel)(adapter, model) : [];
+    const effort = entry.effort && allowed.includes(entry.effort) ? entry.effort : undefined;
+    return { provider: check.provider, model, ...(effort ? { effort } : {}) };
+}

package/server/dist/loop-run-manager.js

@@ -5,6 +5,8 @@ exports.truncate = truncate;
 exports.resolveRunVars = resolveRunVars;
 exports.extractChangeId = extractChangeId;
 exports.recoverOrphanLoopStepAccounting = recoverOrphanLoopStepAccounting;
+const agent_runtime_events_1 = require("./agent-runtime-events");
+const agent_runtime_settings_1 = require("./agent-runtime-settings");
 const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
 const win_spawn_1 = require("./util/win-spawn");
 const db_1 = require("./db");
@@ -561,7 +563,7 @@ class LoopRunManager {
     async run(req) {
         // Later fresh steps must verify the admitted spec, even if its caller or
         // backlog changes while the implementation is running.
-        req = { ...req, graph: structuredClone(req.graph) };
+        req = { ...req, runtimeProviderOverride: (0, agent_runtime_settings_1.validateRuntimeProviderOverride)(req.runtimeProviderOverride), graph: structuredClone(req.graph) };
         if (req.spec)
             req = { ...req, spec: structuredClone(req.spec) };
         if (req.executionManifest)
@@ -752,6 +754,12 @@ class LoopRunManager {
                 logLine(line);
                 return;
             }
+            if (eventType === 'runtime-efficiency-event') {
+                const validated = (0, agent_runtime_events_1.runtimeEfficiencyEventLine)(line, runId);
+                if (!validated || (0, agent_runtime_events_1.isRecordedRuntimeEfficiencyEvent)(this.db, runId, validated))
+                    return;
+                line = validated;
+            }
             const s = takeSeq();
             try {
                 (0, db_1.appendEvent)(this.db, runId, s, { event_type: eventType, source: 'stdout', payload: line });
@@ -1145,7 +1153,7 @@ class LoopRunManager {
                                     nextEventSeq: takeSeq,
                                     recoveryStepKey: aiRecoveryKey,
                                 })
-                                : this.executors.runAiStep({ coreRun, prompt, sessionId, provider: nodeProvider, model: nodeModel, effort: nodeEffort, profileName: req.profileName, cwd: req.cwd, repoDir: req.repoDir, executionManifest: req.executionManifest, onLine: logLine, onRawLine, onSpawn: (c) => this._activeChild.set(runId, c), aiStepTimeoutMs: effectiveTimeoutMs, idleTimeoutMs });
+                                : this.executors.runAiStep({ runtimeProviderOverride: req.runtimeProviderOverride, coreRun, prompt, sessionId, provider: nodeProvider, model: nodeModel, effort: nodeEffort, profileName: req.profileName, cwd: req.cwd, repoDir: req.repoDir, executionManifest: req.executionManifest, onLine: logLine, onRawLine, onSpawn: (c) => this._activeChild.set(runId, c), aiStepTimeoutMs: effectiveTimeoutMs, idleTimeoutMs });
                         };
                         let res = await runAttempt(aiSessionId);
                         if (this._disposed)
@@ -1418,7 +1426,7 @@ class LoopRunManager {
                         iteration += 1;
                         const goal = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)(String(node.data?.goal ?? 'The loop goal is met.'), req.spec), constMap);
                         // `iteration` was just incremented — it IS this pass's 1-based number.
-                        emitStep('decider', `🔍 ${nodeLabel || 'Loop Decider'} (iteration ${iteration})`, node.id, iteration);
+                        emitStep('decider', `🔍 ${nodeLabel || 'Loop Decider'} (iteration ${iteration}${req.deciderEngine ? `, ${req.deciderEngine.provider}/${req.deciderEngine.model}` : ''})`, node.id, iteration);
                         logLine(`Goal: ${goal}`);
                         // BUG-32: capture the real Decider start BEFORE the await (see AI step).
                         const deciderStart = new Date(this.now()).toISOString();
@@ -1428,9 +1436,9 @@ class LoopRunManager {
                             // Give the Decider the spec so it can verify completeness against the
                             // FULL scope instead of trusting a step's self-reported success.
                             userPrompt: [(0, multi_repo_execution_store_1.executionManifestPrompt)(req.executionManifest), (0, loop_decider_1.buildDeciderUserPrompt)({ goal, history, spec: req.spec })].filter(Boolean).join('\n\n'),
-                            provider: nodeProvider,
-                            model: nodeModel,
-                            effort: nodeEffort,
+                            provider: req.deciderEngine?.provider ?? nodeProvider,
+                            model: req.deciderEngine?.model ?? nodeModel,
+                            effort: req.deciderEngine ? req.deciderEngine.effort : nodeEffort,
                             cwd: req.cwd,
                             repoDir: req.repoDir, executionManifest: req.executionManifest,
                             onLine: logLine,

package/server/dist/mcp/tools/app-settings.js

@@ -4,6 +4,7 @@ exports.appTools = appTools;
 const zod_1 = require("zod");
 const desktop_db_1 = require("../../desktop-db");
 const mcp_tiers_1 = require("../mcp-tiers");
+const types_1 = require("./types");
 // App-level settings the MCP may read/write. NOTE: the MCP enable flag and the
 // permission-tier toggles are intentionally NOT writable here — an external LLM
 // must never be able to escalate its own permissions. Those are user-only,
@@ -20,12 +21,19 @@ function appTools() {
             name: 'specrails_settings',
             title: 'App settings',
             description: 'Read or update app-level Specrails settings (theme, language, daily budget, cost-alert threshold, Code Explorer summary language + monthly summary budget). ' +
-                'Actions: get, set. The MCP enable flag and permission tiers are read-only here (user-controlled in the app). ' +
+                'Actions: get, set, runtime_providers.list (connections + live status), runtime_providers.test (probe an OpenAI-compatible baseUrl without saving), runtime_providers.save (replace the connections list — local AI engines re-register live). ' +
+                'The MCP enable flag and permission tiers are read-only here (user-controlled in the app). ' +
                 'dailyBudgetUsd here is APP-WIDE (all projects combined); per-project caps live in specrails_analytics(budget_set).',
             hintTier: 'read',
-            tier: (args) => (args.action === 'set' ? 'write' : 'read'),
+            tier: (args) => (args.action === 'set' || args.action === 'runtime_providers.save' ? 'write' : 'read'),
             inputSchema: {
-                action: zod_1.z.enum(['get', 'set']).describe('Operation'),
+                action: zod_1.z.enum(['get', 'set', 'runtime_providers.list', 'runtime_providers.test', 'runtime_providers.save']).describe('Operation'),
+                baseUrl: zod_1.z.string().optional().describe('runtime_providers.test: OpenAI-compatible base URL (e.g. http://127.0.0.1:11434/v1)'),
+                apiKeyEnv: zod_1.z.string().optional().describe('runtime_providers.test: env var NAME holding the API key (never the key itself)'),
+                providers: zod_1.z
+                    .array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()))
+                    .optional()
+                    .describe('runtime_providers.save: the FULL connections list ({ id, kind: "cli", cli } | { id, kind: "openai-compatible", baseUrl, apiKeyEnv?, label?, defaultModel?, rates?, supportsReasoningEffort? })'),
                 theme: zod_1.z.enum(WRITABLE_THEMES).optional(),
                 language: zod_1.z.enum(WRITABLE_LANGS).optional(),
                 dailyBudgetUsd: zod_1.z
@@ -45,8 +53,26 @@ function appTools() {
                     .optional()
                     .describe('Code Explorer monthly AI file-summary budget in USD (app-wide, default 5)'),
             },
-            handler: (ctx, args) => {
+            handler: async (ctx, args) => {
                 const db = ctx.desktopDb;
+                // Provider connections (local AI engines) — mirror the REST routes over
+                // loopback so validation, adapter re-sync and broadcasts stay identical.
+                if (args.action === 'runtime_providers.list') {
+                    return (0, types_1.apiCall)(ctx, 'GET', '/runtime-providers');
+                }
+                if (args.action === 'runtime_providers.test') {
+                    if (typeof args.baseUrl !== 'string' || !args.baseUrl)
+                        throw new Error('runtime_providers.test requires baseUrl.');
+                    return (0, types_1.apiCall)(ctx, 'POST', '/runtime-providers/test', {
+                        baseUrl: args.baseUrl,
+                        ...(typeof args.apiKeyEnv === 'string' && args.apiKeyEnv ? { apiKeyEnv: args.apiKeyEnv } : {}),
+                    });
+                }
+                if (args.action === 'runtime_providers.save') {
+                    if (!Array.isArray(args.providers) || !args.providers.length)
+                        throw new Error('runtime_providers.save requires a non-empty providers list.');
+                    return (0, types_1.apiCall)(ctx, 'PUT', '/runtime-providers', { providers: args.providers });
+                }
                 if (args.action === 'get') {
                     const theme = normalizeStoredTheme(db);
                     return {

package/server/dist/mcp/tools/rails.js

@@ -47,6 +47,7 @@ function railsTools() {
                 'stop (destructive — kills all active jobs and loop runs for the rail). ' +
                 'For on_review tickets with an already-open GitHub PR (including a published pr_ready delivery), launch automatically tries to continue that PR head branch; Jira-linked in_progress tickets can do the same when the PR match is explicit; fresh tickets still start from the project integration branch. ' +
                 'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider. On that same provider, an omitted model inherits the conversation model; an explicit model wins (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
+                'For Implement and Batch Implement, the selected launch provider applies to ALL runtime roles (architect, developer, reviewer); an explicit launch model/effort also applies to each role. Resuming an existing execution keeps its original frozen role configuration; start a new launch to change providers. ' +
                 'User-facing naming: call the free-form autonomous mode "Freestyle"; use "freestyle" as the canonical API enum value for that same capability. ' +
                 'For small OpenSpec-governed work, recommend "SDD Quick (OpenSpec)" and launch with mode "loop" plus loopId "factory:sdd-quick-openspec"; keep Freestyle for ticket-local implementation-only work. ' +
                 'NAMING: railIndex is the 0-BASED internal identity; the dashboard shows rails 1-based ("Rail N" = railIndex N-1). When talking to the user, ALWAYS say "Rail <railIndex + 1>" (or the rail\'s custom name) — results include railLabel with the correct user-facing label.',
@@ -91,7 +92,7 @@ function railsTools() {
                     .string()
                     .nullable()
                     .optional()
-                    .describe('AI engine/provider override; null = project primary (set_engine; also optional override for launch). Must be an installed provider. For launch from the in-app agent chat, omitting it defaults to the launching conversation\'s provider (overriding any stored rail engine) — pass a string or null explicitly to control it.'),
+                    .describe('AI engine/provider override; null = project primary (set_engine; also optional override for launch). Must be an installed provider, or "roles" to run each role on its own configured engine (Settings ▸ Specrails Agents: architect/developer/reviewer from the runtime config, verifier/decider from the loop roles; requires the agent runtime). For launch from the in-app agent chat, omitting it defaults to the launching conversation\'s provider (overriding any stored rail engine) — pass a string or null explicitly to control it.'),
                 // set_name / create_rail
                 name: zod_1.z
                     .string()

package/server/dist/pr-body.js

@@ -188,7 +188,7 @@ function extractSpecNarrative(description) {
     if (solutionSections.length > 0) {
         for (const s of solutionSections) {
             if (s.content.trim())
-                solutionParts.push(`**${s.title.trim()}** — ${s.content.trim()}`);
+                solutionParts.push(sectionDigest(s));
         }
     }
     else {
@@ -197,7 +197,7 @@ function extractSpecNarrative(description) {
         const rest = headed.filter((s) => s !== problemSection && s.content.trim());
         if (rest.length > 0) {
             for (const s of rest)
-                solutionParts.push(`**${s.title.trim()}** — ${s.content.trim()}`);
+                solutionParts.push(sectionDigest(s));
         }
         else if (!problemSection && preamble && problem === preamble) {
             // Heading-less description: first paragraph = problem, remainder = solution.
@@ -219,6 +219,15 @@ function extractSpecNarrative(description) {
         overflow: solutionFull,
     };
 }
+/**
+ * A headed section as markdown that still renders as markdown: the bold
+ * label on its own line, then the content as a BLOCK. The old inline
+ * `**Title** — content` join put a numbered list's first item on the label
+ * line, so every renderer (GitHub PR body, the review packet) lost the list.
+ */
+function sectionDigest(s) {
+    return `**${s.title.trim()}**\n\n${s.content.trim()}`;
+}
 /** Split markdown into sections at `#`-headings and standalone `**Bold**` label lines. */
 function splitSections(text) {
     const lines = text.split('\n');

package/server/dist/pricing.js

@@ -23,6 +23,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PRICING = void 0;
 exports.resolvePriceEntry = resolvePriceEntry;
 exports.estimateCostUsd = estimateCostUsd;
+exports.estimateLocalCostUsd = estimateLocalCostUsd;
 exports.lastReviewedAt = lastReviewedAt;
 exports.providerNeedsCostEstimation = providerNeedsCostEstimation;
 const registry_1 = require("./providers/registry");
@@ -159,6 +160,20 @@ function estimateCostUsd(providerId, model, usage) {
         : 0;
     return inputCost + outputCost + cacheReadCost + cacheWriteCost;
 }
+/**
+ * Cost of a LOCAL (OpenAI-compatible) invocation from the connection's
+ * user-supplied per-1M rates. `null` when the connection has no rates or the
+ * usage is empty — never a rate-card guess for a local model.
+ */
+function estimateLocalCostUsd(rates, usage) {
+    if (!rates)
+        return null;
+    const tokensIn = usage.tokens_in ?? 0;
+    const tokensOut = usage.tokens_out ?? 0;
+    if (tokensIn <= 0 && tokensOut <= 0)
+        return null;
+    return tokensIn / 1_000_000 * rates.inputPer1M + tokensOut / 1_000_000 * rates.outputPer1M;
+}
 /**
  * Returns the oldest `lastReviewedAt` date across the table. Surfaced by an
  * optional diagnostic endpoint so the maintainer can spot staleness quickly.

package/server/dist/provider-detection.js

@@ -48,6 +48,7 @@ exports.isGeminiBetaDisabled = isGeminiBetaDisabled;
 exports.getDetectionSnapshot = getDetectionSnapshot;
 exports.getDetectedIdsSync = getDetectedIdsSync;
 exports.getSnapshotSync = getSnapshotSync;
+exports.refreshLocalDetection = refreshLocalDetection;
 exports.refreshDetection = refreshDetection;
 exports._resetDetectionForTests = _resetDetectionForTests;
 const fs = __importStar(require("fs"));
@@ -55,6 +56,9 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const providers_1 = require("./providers");
 const core_compat_1 = require("./core-compat");
+const local_adapter_1 = require("./providers/local-adapter");
+const local_adapter_registry_1 = require("./providers/local-adapter-registry");
+const local_engine_detection_1 = require("./local-engine-detection");
 const CACHE_TTL_MS = 60_000;
 /** Auth probes are offline file checks today, but keep the contract bounded. */
 exports.AUTH_PROBE_TIMEOUT_MS = 1500;
@@ -135,7 +139,34 @@ function usabilityError(adapter, d) {
     }
     return undefined;
 }
+/** Local (OpenAI-compatible) adapter: the bounded HTTP models probe, cached for
+ *  the adapter's dynamic `modelCatalog()`. */
+async function probeLocalAdapter(adapter) {
+    let probe;
+    try {
+        probe = await (0, local_engine_detection_1.probeConnection)({ baseUrl: adapter.localConnection.baseUrl, apiKeyEnv: adapter.localConnection.apiKeyEnv });
+    }
+    catch (err) {
+        probe = { reachable: false, installed: false, executable: false, authState: 'unknown', models: [], latencyMs: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+    (0, local_engine_detection_1.setCachedProbe)(adapter.id, probe);
+    return {
+        id: adapter.id,
+        displayName: adapter.displayName,
+        installed: probe.installed,
+        executable: probe.executable,
+        authState: probe.authState,
+        usable: probe.reachable,
+        error: probe.reachable ? undefined : (probe.error ?? `${adapter.displayName} endpoint is unreachable.`),
+        kind: 'local',
+        models: probe.models,
+        latencyMs: probe.latencyMs,
+        ...(probe.apiKeyEnvMissing ? { apiKeyEnvMissing: true } : {}),
+    };
+}
 async function probeAdapter(adapter, home) {
+    if ((0, local_adapter_1.isLocalAdapter)(adapter))
+        return probeLocalAdapter(adapter);
     const vetoed = isVetoed(adapter.id);
     let detection;
     try {
@@ -179,7 +210,10 @@ let _snapshot = null;
 let _inflight = null;
 async function runDetection() {
     const home = os.homedir();
-    const adapters = (0, providers_1.listAdapters)();
+    // Local adapters are probed in the SAME cycle as CLIs; under the kill
+    // switch they are skipped entirely (they should not be registered anyway).
+    const localEnabled = (0, local_adapter_registry_1.isLocalEnginesEnabled)();
+    const adapters = (0, providers_1.listAdapters)().filter((a) => localEnabled || !(0, local_adapter_1.isLocalAdapter)(a));
     const results = await Promise.all(adapters.map((a) => probeAdapter(a, home)));
     const providers = {};
     for (const r of results)
@@ -221,6 +255,34 @@ function getSnapshotSync() {
  * Refresh and report whether the usable set changed vs the previous snapshot.
  * Callers use the flag to decide whether to broadcast `providers.detected_changed`.
  */
+/**
+ * Re-probe ONLY the registered local adapters (after a connections save) and
+ * merge into the current snapshot without re-spawning CLI probes. Returns
+ * whether the usable set changed. Falls back to a full refresh when no
+ * snapshot exists yet.
+ */
+async function refreshLocalDetection() {
+    if (!_snapshot)
+        return refreshDetection();
+    const before = _snapshot.detected.join(',');
+    const localEnabled = (0, local_adapter_registry_1.isLocalEnginesEnabled)();
+    const locals = (0, providers_1.listAdapters)().filter(local_adapter_1.isLocalAdapter);
+    const providers = {};
+    for (const [id, row] of Object.entries(_snapshot.providers)) {
+        if (row.kind !== 'local')
+            providers[id] = row;
+    }
+    if (localEnabled) {
+        const results = await Promise.all(locals.map((a) => probeLocalAdapter(a)));
+        for (const r of results)
+            providers[r.id] = r;
+    }
+    const ordered = (0, providers_1.listAdapters)().map((a) => a.id);
+    const detected = ordered.filter((id) => providers[id]?.usable);
+    const snapshot = { providers, detected, at: _snapshot.at };
+    _snapshot = snapshot;
+    return { snapshot, changed: before !== detected.join(',') };
+}
 async function refreshDetection() {
     const before = _snapshot?.detected.join(',') ?? null;
     const snapshot = await getDetectionSnapshot({ refresh: true });

package/server/dist/provider-selection.js

@@ -21,8 +21,10 @@ exports.installedProviders = installedProviders;
 exports.isProviderEnabled = isProviderEnabled;
 exports.isMultiProvider = isMultiProvider;
 exports.derivePrimaryProvider = derivePrimaryProvider;
+exports.defaultMachineProvider = defaultMachineProvider;
 exports.resolveProvider = resolveProvider;
 exports.validateRequestedProvider = validateRequestedProvider;
+const registry_1 = require("./providers/registry");
 /** Fixed preference order for primary derivation when the stored primary is gone. */
 exports.PROVIDER_PREFERENCE_ORDER = ['claude', 'codex', 'gemini', 'kimi'];
 let _detectedSupplier = null;
@@ -72,14 +74,37 @@ function isMultiProvider(project) {
 function derivePrimaryProvider(project) {
     const available = installedProviders(project);
     const stored = project.provider;
-    if (stored && available.includes(stored))
+    // A stored primary that is a LOCAL engine never wins over a detected CLI:
+    // local ids are opt-in per invocation, the machine's primary stays a CLI
+    // whenever one is detected (a local-only machine may still pick the local id).
+    const cliAvailable = available.filter((p) => !(0, registry_1.isLocalAdapterId)(p));
+    if (stored && available.includes(stored) && (cliAvailable.length === 0 || !(0, registry_1.isLocalAdapterId)(stored)))
         return stored;
     for (const p of exports.PROVIDER_PREFERENCE_ORDER) {
         if (available.includes(p))
             return p;
     }
+    if (cliAvailable.length > 0)
+        return cliAvailable[0];
+    // Local-only machine: the first detected local engine is the primary.
+    if (available.some((p) => (0, registry_1.isLocalAdapterId)(p)))
+        return available[0];
     return stored ?? available[0];
 }
+/**
+ * The provider an APP-LEVEL surface (Agent Chat missions, the Project Builder)
+ * starts a fresh conversation on when the caller names none: the machine's
+ * primary per `derivePrimaryProvider` over the detected set — a local-only
+ * machine therefore lands on its local engine instead of a `claude` that is
+ * not installed. Falls back to `claude` while no detection snapshot exists
+ * (startup, unit tests), byte-identical to the old hardcoded default.
+ */
+function defaultMachineProvider() {
+    const detected = detectedProviders();
+    if (!detected)
+        return 'claude';
+    return derivePrimaryProvider({ provider: 'claude', providers: detected });
+}
 /**
  * Resolve the effective provider for a per-invocation request.
  * Returns the requested provider when it is available; otherwise falls back to