specrails-desktop 2.47.0 → 2.48.0

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");
@@ -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

@@ -1426,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();
@@ -1436,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

@@ -92,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

package/server/dist/providers/index.js

@@ -7,7 +7,7 @@
 //
 // Spec: openspec/specs/multi-provider-architecture/spec.md
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnknownProviderError = exports.CUSTOM_MODEL_ALIAS_MAX_LENGTH = exports.isSafeCustomModelAlias = exports.isModelAvailableForAdapter = exports.isReasoningEffortValidForModel = exports.defaultReasoningEffortForModel = exports.reasoningEffortsForModel = exports.requireToolPolicy = exports.pureOutputToolPolicy = exports.supportsToolPolicy = exports.parseStreamEvents = exports.buildProviderRepoAccessArgs = exports.formatProviderCommand = exports.buildProviderEnv = exports.kimiAdapter = exports.geminiAdapter = exports.codexAdapter = exports.claudeAdapter = exports.listAdapters = exports.hasAdapter = exports.getAdapter = void 0;
+exports.UnknownProviderError = exports.CUSTOM_MODEL_ALIAS_MAX_LENGTH = exports.isSafeCustomModelAlias = exports.isModelAvailableForAdapter = exports.isReasoningEffortValidForModel = exports.defaultReasoningEffortForModel = exports.reasoningEffortsForModel = exports.requireToolPolicy = exports.pureOutputToolPolicy = exports.supportsToolPolicy = exports.parseStreamEvents = exports.buildProviderRepoAccessArgs = exports.formatProviderCommand = exports.buildProviderEnv = exports.kimiAdapter = exports.geminiAdapter = exports.codexAdapter = exports.claudeAdapter = exports.adapterKind = exports.isLocalAdapterId = exports.unregisterAdapter = exports.listAdapters = exports.hasAdapter = exports.getAdapter = void 0;
 const registry_1 = require("./registry");
 const claude_adapter_1 = require("./claude-adapter");
 Object.defineProperty(exports, "claudeAdapter", { enumerable: true, get: function () { return claude_adapter_1.claudeAdapter; } });
@@ -25,6 +25,9 @@ var registry_2 = require("./registry");
 Object.defineProperty(exports, "getAdapter", { enumerable: true, get: function () { return registry_2.getAdapter; } });
 Object.defineProperty(exports, "hasAdapter", { enumerable: true, get: function () { return registry_2.hasAdapter; } });
 Object.defineProperty(exports, "listAdapters", { enumerable: true, get: function () { return registry_2.listAdapters; } });
+Object.defineProperty(exports, "unregisterAdapter", { enumerable: true, get: function () { return registry_2.unregisterAdapter; } });
+Object.defineProperty(exports, "isLocalAdapterId", { enumerable: true, get: function () { return registry_2.isLocalAdapterId; } });
+Object.defineProperty(exports, "adapterKind", { enumerable: true, get: function () { return registry_2.adapterKind; } });
 var runtime_1 = require("./runtime");
 Object.defineProperty(exports, "buildProviderEnv", { enumerable: true, get: function () { return runtime_1.buildProviderEnv; } });
 Object.defineProperty(exports, "formatProviderCommand", { enumerable: true, get: function () { return runtime_1.formatProviderCommand; } });

package/server/dist/providers/local-adapter-registry.js

@@ -0,0 +1,56 @@
+"use strict";
+// Dynamic registration of local (OpenAI-compatible) adapters — one per
+// connection in `~/.specrails/runtime-providers.json`. Called at boot (after
+// the connections load) and after every successful `PUT /api/runtime-providers`.
+//
+// Kill switch: SPECRAILS_LOCAL_ENGINES=0|false|off ⇒ no registration, and any
+// previously registered local adapter is removed (byte-identical legacy).
+//
+// Spec: openspec/changes/local-ai-engines/specs/local-ai-engines/spec.md
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalEnginesEnabled = isLocalEnginesEnabled;
+exports.listLocalAdapters = listLocalAdapters;
+exports.listLocalConnections = listLocalConnections;
+exports.syncLocalAdapters = syncLocalAdapters;
+const registry_1 = require("./registry");
+const local_adapter_1 = require("./local-adapter");
+function isLocalEnginesEnabled() {
+    const raw = (process.env.SPECRAILS_LOCAL_ENGINES ?? '').trim().toLowerCase();
+    return !(raw === '0' || raw === 'false' || raw === 'off');
+}
+/** Every currently registered local adapter, in registry order. */
+function listLocalAdapters() {
+    return (0, registry_1.listAdapters)().filter(local_adapter_1.isLocalAdapter);
+}
+/** The connections behind the registered local adapters. */
+function listLocalConnections() {
+    return listLocalAdapters().map((a) => a.localConnection);
+}
+function syncLocalAdapters(connections) {
+    const result = { registered: [], unregistered: [], skipped: [] };
+    const wanted = new Map();
+    if (isLocalEnginesEnabled()) {
+        for (const conn of connections) {
+            if (conn.kind !== 'openai-compatible' || typeof conn.baseUrl !== 'string')
+                continue;
+            if ((0, registry_1.hasAdapter)(conn.id) && (0, registry_1.adapterKind)(conn.id) !== 'local') {
+                result.skipped.push(conn.id);
+                continue;
+            }
+            wanted.set(conn.id, conn);
+        }
+    }
+    for (const existing of listLocalAdapters()) {
+        if (!wanted.has(existing.id)) {
+            if ((0, registry_1.unregisterAdapter)(existing.id))
+                result.unregistered.push(existing.id);
+        }
+    }
+    for (const [id, conn] of wanted) {
+        // Re-register on every sync so a changed baseUrl/rates/label takes effect;
+        // in-flight jobs keep the adapter instance they resolved earlier.
+        (0, registry_1.register)((0, local_adapter_1.createLocalAdapter)({ ...conn }), 'local');
+        result.registered.push(id);
+    }
+    return result;
+}