specrails-desktop 2.46.0 → 2.48.0

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

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = void 0;
+exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = void 0;
+exports.stripDesktopConnectionFields = stripDesktopConnectionFields;
+exports.coreConnectionFieldGates = coreConnectionFieldGates;
 exports.validateAgentRuntimeConfig = validateAgentRuntimeConfig;
 exports.defaultAgentRuntimeConfig = defaultAgentRuntimeConfig;
 exports.agentRuntimeConfigPath = agentRuntimeConfigPath;
@@ -17,6 +19,8 @@ exports.saveAgentRuntimeConfig = saveAgentRuntimeConfig;
 exports.validateRuntimeRolePrompts = validateRuntimeRolePrompts;
 exports.loadRuntimeRolePrompts = loadRuntimeRolePrompts;
 exports.saveRuntimeRolePrompts = saveRuntimeRolePrompts;
+exports.validateRuntimeProviderOverride = validateRuntimeProviderOverride;
+exports.forCoreRuntime = forCoreRuntime;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -24,6 +28,89 @@ const node_crypto_1 = require("node:crypto");
 const ajv_1 = __importDefault(require("ajv"));
 const agent_runtime_schema_json_1 = __importDefault(require("./schemas/agent-runtime.schema.json"));
 const workspace_resolution_1 = require("./workspace-resolution");
+const registry_1 = require("./providers/registry");
+const DESKTOP_CONNECTION_FIELDS = ['label', 'defaultModel', 'rates'];
+/** Core-owned small-model fields: known only to cores advertising `capabilities.compactAgentLoop`
+ *  (`supportsReasoningEffort` moved here: core forwards it as OpenAI `reasoning_effort`). */
+const CORE_COMPACT_FIELDS = ['agentLoop', 'contextWindowTokens', 'supportsReasoningEffort'];
+/** Known only to cores advertising `capabilities.compactOutputBudget`. */
+const CORE_OUTPUT_BUDGET_FIELDS = ['maxOutputTokens'];
+exports.CONTEXT_WINDOW_TOKENS_MIN = 4096;
+exports.CONTEXT_WINDOW_TOKENS_MAX = 4_000_000;
+exports.MAX_OUTPUT_TOKENS_MIN = 1024;
+exports.MAX_OUTPUT_TOKENS_MAX = 1_000_000;
+const MODEL_PATTERN = /^[^-\r\n\u0000][^\r\n\u0000]*$/;
+/** Core-shaped providers: desktop-only connection fields removed. */
+function stripDesktopConnectionFields(providers, opts) {
+    return providers.map((provider) => {
+        if (provider.kind !== 'openai-compatible')
+            return { ...provider };
+        const copy = { ...provider };
+        for (const field of DESKTOP_CONNECTION_FIELDS)
+            delete copy[field];
+        // Older cores reject unknown keys: only hand the compact-loop fields to a
+        // core that advertises them. Absent opts ⇒ conservative (strip).
+        if (opts?.coreCompactLoop !== true)
+            for (const field of CORE_COMPACT_FIELDS)
+                delete copy[field];
+        if (opts?.coreOutputBudget !== true)
+            for (const field of CORE_OUTPUT_BUDGET_FIELDS)
+                delete copy[field];
+        return copy;
+    });
+}
+function validateDesktopConnectionFields(provider, index) {
+    const at = `/providers/${index}`;
+    const extras = {};
+    if (provider.label !== undefined) {
+        if (typeof provider.label !== 'string' || !provider.label.trim() || provider.label.length > 64 || /[\r\n\u0000]/.test(provider.label))
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/label: must be 1–64 characters`);
+        extras.label = provider.label;
+    }
+    if (provider.defaultModel !== undefined) {
+        if (typeof provider.defaultModel !== 'string' || !provider.defaultModel.trim() || provider.defaultModel.length > 256 || !MODEL_PATTERN.test(provider.defaultModel))
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/defaultModel: must be a model id (no leading '-', no control characters)`);
+        extras.defaultModel = provider.defaultModel;
+    }
+    if (provider.rates !== undefined) {
+        const rates = provider.rates;
+        if (!rates || typeof rates !== 'object' || Array.isArray(rates) || Object.keys(rates).some((key) => key !== 'inputPer1M' && key !== 'outputPer1M'))
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/rates: expected { inputPer1M, outputPer1M }`);
+        for (const key of ['inputPer1M', 'outputPer1M']) {
+            const value = rates[key];
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+                throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/rates/${key}: must be a non-negative number`);
+        }
+        extras.rates = { inputPer1M: rates.inputPer1M, outputPer1M: rates.outputPer1M };
+    }
+    if (provider.supportsReasoningEffort !== undefined) {
+        if (typeof provider.supportsReasoningEffort !== 'boolean')
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/supportsReasoningEffort: must be a boolean`);
+        extras.supportsReasoningEffort = provider.supportsReasoningEffort;
+    }
+    if (provider.agentLoop !== undefined) {
+        if (provider.agentLoop !== 'compact' && provider.agentLoop !== 'free')
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/agentLoop: must be "compact" or "free"`);
+        extras.agentLoop = provider.agentLoop;
+    }
+    if (provider.contextWindowTokens !== undefined) {
+        const n = provider.contextWindowTokens;
+        if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < exports.CONTEXT_WINDOW_TOKENS_MIN || n > exports.CONTEXT_WINDOW_TOKENS_MAX)
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/contextWindowTokens: must be an integer between ${exports.CONTEXT_WINDOW_TOKENS_MIN} and ${exports.CONTEXT_WINDOW_TOKENS_MAX}`);
+        extras.contextWindowTokens = n;
+    }
+    if (provider.maxOutputTokens !== undefined) {
+        const n = provider.maxOutputTokens;
+        if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < exports.MAX_OUTPUT_TOKENS_MIN || n > exports.MAX_OUTPUT_TOKENS_MAX)
+            throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${at}/maxOutputTokens: must be an integer between ${exports.MAX_OUTPUT_TOKENS_MIN} and ${exports.MAX_OUTPUT_TOKENS_MAX}`);
+        extras.maxOutputTokens = n;
+    }
+    return extras;
+}
+/** The strip options for a loaded core: each core-owned field family travels only when the core advertises it. */
+function coreConnectionFieldGates(capabilities) {
+    return { coreCompactLoop: capabilities?.compactAgentLoop === 1, coreOutputBudget: capabilities?.compactOutputBudget === 1 };
+}
 /** Core's own review gate. Configured thresholds may only tighten it (mirrors Core's config.ts). */
 exports.REVIEW_THRESHOLD_FLOORS = {
     minScore: 70,
@@ -39,6 +126,19 @@ exports.AgentRuntimeConfigError = AgentRuntimeConfigError;
 /** Vendored from Core's schema; parity tests keep offline configuration aligned.
  *  Semantic checks mirror Core because JSON Schema cannot check provider refs. */
 function validateAgentRuntimeConfig(input) {
+    // Desktop-only connection fields ride the openai-compatible entries; the
+    // vendored (byte-identical to Core) schema forbids unknown keys, so they are
+    // validated here and re-attached after the schema pass.
+    const extrasByIndex = new Map();
+    if (input && typeof input === 'object' && !Array.isArray(input) && Array.isArray(input.providers)) {
+        const rawProviders = input.providers;
+        rawProviders.forEach((provider, index) => {
+            if (!provider || typeof provider !== 'object' || provider.kind !== 'openai-compatible')
+                return;
+            extrasByIndex.set(index, validateDesktopConnectionFields(provider, index));
+        });
+        input = { ...input, providers: stripDesktopConnectionFields(rawProviders) };
+    }
     if (!schemaValidator(input)) {
         const error = schemaValidator.errors?.[0];
         throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${error?.instancePath || '/'}: ${error?.message ?? 'invalid value'}`);
@@ -51,6 +151,10 @@ function validateAgentRuntimeConfig(input) {
     for (const provider of config.providers) {
         if (provider.kind !== 'openai-compatible')
             continue;
+        // A connection id may never shadow a registered CLI adapter (claude/codex/
+        // gemini/kimi): local adapters register under the connection id.
+        if ((0, registry_1.hasAdapter)(provider.id) && (0, registry_1.adapterKind)(provider.id) !== 'local')
+            throw new AgentRuntimeConfigError(`Provider id '${provider.id}' is reserved for the ${provider.id} CLI adapter`);
         let url;
         try {
             url = new URL(provider.baseUrl);
@@ -61,23 +165,43 @@ function validateAgentRuntimeConfig(input) {
         if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || provider.baseUrl.includes('\0'))
             throw new AgentRuntimeConfigError('Provider URLs must use HTTP(S) without credentials, query parameters or fragments');
     }
-    for (const role of ROLES) {
-        const agent = config.agents[role];
+    for (const role of [...ROLES, ...(config.fixer ? ['fixer'] : [])]) {
+        const agent = role === 'fixer' ? config.fixer : config.agents[role];
         const provider = config.providers.find(({ id }) => id === agent.provider);
         if (!provider)
             throw new AgentRuntimeConfigError(`Role ${role} references a provider that is not configured`);
-        if (provider.kind === 'openai-compatible' && !agent.model)
+        // Core requires a model on API providers, but a LOCAL engine (a registered
+        // connection with a discovered/stored default) may be saved as "provider
+        // default": the launch path fills the connection's CURRENT default
+        // (`fillDefaultRoleModels`), so changing the connection's default later
+        // applies to every role that did not pin one. Persisting the filled value
+        // used to freeze gpt-oss-fast into the architect after the user switched
+        // the connection to qwen3-coder.
+        if (provider.kind === 'openai-compatible' && !agent.model && !((0, registry_1.hasAdapter)(provider.id) && (0, registry_1.isLocalAdapterId)(provider.id)))
             throw new AgentRuntimeConfigError(`Role ${role} requires a model for its API provider`);
         if (agent.model !== undefined && !agent.model.trim())
             throw new AgentRuntimeConfigError(`Role ${role} requires a nonempty model identifier`);
+        for (const value of [agent.model, agent.effort, agent.escalation?.model, agent.escalation?.effort])
+            if (value !== undefined && (!value.trim() || value.includes('\0')))
+                throw new AgentRuntimeConfigError(`Role ${role} has an invalid model or effort`);
+        if (agent.escalation && (!agent.model || (agent.escalation.model === agent.model && agent.escalation.effort === agent.effort)))
+            throw new AgentRuntimeConfigError(`Role ${role} escalation requires an explicit base and a different model or effort`);
         if (agent.maxTurns !== undefined && !Number.isSafeInteger(agent.maxTurns))
             throw new AgentRuntimeConfigError(`Role ${role} maxTurns must be a safe integer`);
+        if (agent.thinking !== undefined && agent.thinking !== 'on' && agent.thinking !== 'off')
+            throw new AgentRuntimeConfigError(`Role ${role} thinking must be "on" or "off"`);
     }
     for (const [key, value] of Object.entries(config.limits ?? {})) {
         if (!Number.isFinite(value) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value)))
             throw new AgentRuntimeConfigError('Workflow limits must be finite, safe numbers');
     }
+    const keys = config.verification.flatMap(command => command.key ? [command.key] : []);
+    if (new Set(keys).size !== keys.length)
+        throw new AgentRuntimeConfigError('Verification check keys must be unique');
     for (const command of config.verification) {
+        for (const value of [command.label, ...(command.policy?.inputs ?? []), ...(command.policy?.toolchainInputs ?? []), ...(command.policy?.resources ?? [])])
+            if (value !== undefined && (!value.trim() || value.includes('\0')))
+                throw new AgentRuntimeConfigError('Invalid verification label or policy input');
         if (![command.command, ...command.args, ...(command.cwd === undefined ? [] : [command.cwd])].every((value) => !value.includes('\0')) || !command.command.trim() || (command.cwd !== undefined && !command.cwd.trim()))
             throw new AgentRuntimeConfigError('Verification command contains an empty or invalid value');
         if (command.timeoutMs !== undefined && !Number.isSafeInteger(command.timeoutMs))
@@ -95,7 +219,10 @@ function validateAgentRuntimeConfig(input) {
         if (value < exports.REVIEW_THRESHOLD_FLOORS.aspects[aspect])
             throw new AgentRuntimeConfigError(`Review threshold review.aspects.${aspect} must be at least ${exports.REVIEW_THRESHOLD_FLOORS.aspects[aspect]} (Core's own review gate)`);
     }
-    return structuredClone(config);
+    const cloned = structuredClone(config);
+    for (const [index, extras] of extrasByIndex)
+        cloned.providers[index] = { ...cloned.providers[index], ...extras };
+    return cloned;
 }
 function defaultAgentRuntimeConfig(project) {
     const provider = CLI_PROVIDERS.includes(project.provider) ? project.provider : 'claude';
@@ -211,13 +338,14 @@ function saveAgentRuntimeConfig(project, input) {
     atomicJson(file, settings);
     return config;
 }
+const PROMPT_ROLES = [...ROLES, 'fixer'];
 function validateRuntimeRolePrompts(input) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new AgentRuntimeConfigError('Role prompts must be an object');
     const prompts = {};
     for (const [role, text] of Object.entries(input)) {
-        if (!ROLES.includes(role) || typeof text !== 'string' || !text.trim() || text.length > 20000 || text.includes('\0'))
-            throw new AgentRuntimeConfigError('Role prompts must use architect, developer or reviewer with 1–20000 nonblank characters and no null bytes');
+        if (!PROMPT_ROLES.includes(role) || typeof text !== 'string' || !text.trim() || text.length > 20000 || text.includes('\0'))
+            throw new AgentRuntimeConfigError('Role prompts must use architect, developer, reviewer or fixer with 1–20000 nonblank characters and no null bytes');
         prompts[role] = text;
     }
     return prompts;
@@ -237,3 +365,31 @@ function saveRuntimeRolePrompts(input) {
     atomicJson(node_path_1.default.join(node_os_1.default.homedir(), '.specrails', 'runtime-role-prompts.json'), prompts);
     return prompts;
 }
+function validateRuntimeProviderOverride(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new AgentRuntimeConfigError('Invalid runtime provider override');
+    const raw = value;
+    if (Object.keys(raw).some(key => !['provider', 'model', 'effort'].includes(key)) || typeof raw.provider !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(raw.provider))
+        throw new AgentRuntimeConfigError('Invalid runtime provider override provider');
+    if (raw.model !== undefined && (typeof raw.model !== 'string' || !raw.model.trim() || raw.model.length > 256 || /^-|[\r\n\0]/.test(raw.model)))
+        throw new AgentRuntimeConfigError('Invalid runtime provider override model');
+    if (raw.effort !== undefined && (typeof raw.effort !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(raw.effort)))
+        throw new AgentRuntimeConfigError('Invalid runtime provider override effort');
+    return structuredClone(raw);
+}
+/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`. */
+function forCoreRuntime(config, capabilities) {
+    let out = config;
+    if (capabilities?.configurableGuardrails !== 1 && out.guardrails !== undefined) {
+        const { guardrails: _dropped, ...rest } = out;
+        out = rest;
+    }
+    // The per-role thinking switch is known only to cores advertising `roleThinkingControl`.
+    if (capabilities?.roleThinkingControl !== 1 && (Object.values(out.agents ?? {}).some(agent => agent?.thinking !== undefined) || out.fixer?.thinking !== undefined)) {
+        const strip = (agent) => { const { thinking: _t, ...rest } = agent; return rest; };
+        out = { ...out, ...(out.agents ? { agents: Object.fromEntries(Object.entries(out.agents).map(([role, agent]) => [role, strip(agent)])) } : {}), ...(out.fixer ? { fixer: strip(out.fixer) } : {}) };
+    }
+    return out;
+}

package/server/dist/agent-spec-framing.js

@@ -33,6 +33,8 @@ exports.framingRefusalMessage = framingRefusalMessage;
 exports.checkSpecFraming = checkSpecFraming;
 exports.recordSpecCommitted = recordSpecCommitted;
 const agent_store_1 = require("./agent-store");
+const agent_fence_promotion_1 = require("./agent-fence-promotion");
+const registry_1 = require("./providers/registry");
 /** User-typed command word that switches framing off for the conversation. */
 exports.FRAMING_WAIVER_TOKEN = '#noframe';
 /** User-typed command word that switches it back on. */
@@ -78,7 +80,10 @@ function payloadIsValidFrame(raw) {
     return true;
 }
 /** True when an assistant message carries at least one VALID frame block. */
-function hasValidProblemFrame(content) {
+function hasValidProblemFrame(rawContent, opts) {
+    // Local (OpenAI-compatible) engines only — mirrors the client: a ```json
+    // fence with a frame-shaped body counts. CLI providers stay strict.
+    const content = opts?.tolerantFences ? (0, agent_fence_promotion_1.promoteAgentProtocolFences)(rawContent) : rawContent;
     if (!content.includes(OPEN_FENCE))
         return false;
     FENCE_RE.lastIndex = 0;
@@ -125,7 +130,7 @@ function isFramingMarker(content) {
  * rather than a series. A waiver is sticky for the rest of the conversation and
  * is cleared only by the restore token.
  */
-function evaluateFramingState(messages) {
+function evaluateFramingState(messages, opts) {
     let waived = false;
     let pendingFrame = false; // emitted, awaiting the user's answer
     let answeredFrame = false; // answered and not yet spent on a spec
@@ -137,7 +142,7 @@ function evaluateFramingState(messages) {
             continue;
         }
         if (msg.role === 'assistant') {
-            if (hasValidProblemFrame(msg.content)) {
+            if (hasValidProblemFrame(msg.content, opts)) {
                 pendingFrame = true;
                 sawFrame = true;
             }
@@ -182,7 +187,8 @@ function framingRefusalMessage(reason) {
  * MCP client cannot render the card and holds no conversation here.
  */
 function checkSpecFraming(db, conversationId) {
-    const state = evaluateFramingState((0, agent_store_1.listAgentMessages)(db, conversationId));
+    const tolerantFences = (0, registry_1.isLocalAdapterId)((0, agent_store_1.getAgentConversation)(db, conversationId)?.provider);
+    const state = evaluateFramingState((0, agent_store_1.listAgentMessages)(db, conversationId), { tolerantFences });
     if (state.satisfied)
         return null;
     return framingRefusalMessage(state.reason ?? 'no_frame');

package/server/dist/binary-probe.js

@@ -1,7 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.binaryOnPath = binaryOnPath;
 exports.__resetBinaryProbeCacheForTest = __resetBinaryProbeCacheForTest;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const child_process_1 = require("child_process");
 const win_spawn_1 = require("./util/win-spawn");
 // Windows has no `which`; probe via `where` instead. Both exit non-zero
@@ -20,6 +25,13 @@ function binaryOnPath(binary) {
     if (hit && now - hit.at < PROBE_TTL_MS)
         return hit.onPath;
     let onPath;
+    // An absolute binary (the bundled Node that runs the local AI runner) is
+    // probed by existence: `where C:\\…\\node.exe` does not resolve a path.
+    if (node_path_1.default.isAbsolute(binary)) {
+        onPath = node_fs_1.default.existsSync(binary);
+        _cache.set(binary, { at: now, onPath });
+        return onPath;
+    }
     try {
         // `where` runs via cmd.exe; pass a SystemRoot-backfilled env so the probe
         // (a HARD gate before job/chat spawns) can't be falsely cached as missing

package/server/dist/blueprint-router.js

@@ -8,6 +8,7 @@ const providers_1 = require("./providers");
 const runtime_1 = require("./providers/runtime");
 const blueprint_store_1 = require("./blueprint-store");
 const blueprint_spec_quality_1 = require("./blueprint-spec-quality");
+const provider_selection_1 = require("./provider-selection");
 function isProjectBuilderEnabled() {
     return process.env.SPECRAILS_PROJECT_BUILDER !== 'false';
 }
@@ -33,7 +34,7 @@ function createBlueprintRouter(deps) {
         next();
     });
     router.get('/models', (req, res) => {
-        const provider = validProvider(req.query.provider) ?? 'claude';
+        const provider = validProvider(req.query.provider) ?? (0, provider_selection_1.defaultMachineProvider)();
         const adapter = (0, providers_1.getAdapter)(provider);
         const toolPolicy = (0, runtime_1.pureOutputToolPolicy)(adapter);
         const requestedModel = typeof req.query.model === 'string' && req.query.model
@@ -63,7 +64,7 @@ function createBlueprintRouter(deps) {
     });
     router.post('/conversations', (req, res) => {
         const body = (req.body ?? {});
-        const provider = validProvider(body.provider) ?? 'claude';
+        const provider = validProvider(body.provider) ?? (0, provider_selection_1.defaultMachineProvider)();
         if (!(0, runtime_1.pureOutputToolPolicy)((0, providers_1.getAdapter)(provider))) {
             res.status(409).json({ error: 'provider_tool_policy_unsupported', provider });
             return;

package/server/dist/chat-manager.js

@@ -21,6 +21,7 @@ const providers_1 = require("./providers");
 const runtime_1 = require("./providers/runtime");
 const context_scope_1 = require("./context-scope");
 const user_mcp_config_1 = require("./user-mcp-config");
+const registry_1 = require("./providers/registry");
 const binary_probe_1 = require("./binary-probe");
 const explore_stdin_session_1 = require("./explore-stdin-session");
 const workspace_resolution_1 = require("./workspace-resolution");
@@ -937,7 +938,10 @@ class ChatManager {
             // gating is therefore claude-only today — codex inherits its sandbox
             // and approval policy from the project's `.codex/config.toml` (or the
             // `-c sandbox_mode=` override the adapter already attaches on resume).
-            const scopeFlags = conversationScope && adapter.id === 'claude'
+            // Local (OpenAI-compatible) runners accept the SAME `--tools` /
+            // `--disallowedTools` shape (the adapter's extraArgs allowlist drops any
+            // claude-only flag), so the scope tiers apply to them too.
+            const scopeFlags = conversationScope && (adapter.id === 'claude' || (0, registry_1.isLocalAdapterId)(adapter.id))
                 ? (0, context_scope_1.toolFlagsForScope)(conversationScope).args
                 : [];
             if (this._cwd && conversation.kind !== 'milestone' && (!conversationScope || conversationScope.mcp)) {

package/server/dist/desktop-router.js

@@ -21,6 +21,9 @@ const specrails_tech_client_1 = require("./specrails-tech-client");
 const core_compat_1 = require("./core-compat");
 const providers_1 = require("./providers");
 const provider_detection_1 = require("./provider-detection");
+const local_engine_detection_1 = require("./local-engine-detection");
+const local_adapter_registry_1 = require("./providers/local-adapter-registry");
+const local_adapter_1 = require("./providers/local-adapter");
 const agent_defaults_1 = require("./agent-defaults");
 const external_mcp_1 = require("./external-mcp");
 const workspace_manager_1 = require("./workspace-manager");
@@ -397,6 +400,17 @@ function createDesktopRouter(registry, broadcast) {
         // provider surfaces here with no edit. Apply per-provider beta gates: codex
         // is forced unavailable when SPECRAILS_CODEX_BETA=0 (emergency rollback).
         const gated = { ...providers };
+        // Local (OpenAI-compatible) engines have no CLI to `which`: their binary is
+        // the bundled node, so the PATH probe above always says "installed" even
+        // when the endpoint is down. Their availability is the bounded HTTP probe
+        // from the detection cycle (refreshed here so a first call after boot is
+        // not blind); an id the snapshot does not know stays unavailable.
+        const localIds = (0, providers_1.listAdapters)().filter(local_adapter_1.isLocalAdapter).map((adapter) => adapter.id);
+        if (localIds.length > 0) {
+            const snapshot = await (0, provider_detection_1.getDetectionSnapshot)();
+            for (const id of localIds)
+                gated[id] = snapshot.providers[id]?.usable === true;
+        }
         if ((0, provider_detection_1.isCodexBetaDisabled)())
             gated.codex = false;
         // Gemini: enabled by default; forced unavailable only when
@@ -430,7 +444,10 @@ function createDesktopRouter(registry, broadcast) {
             adapter.id,
             { command: adapter.binary, args: [] },
         ]));
-        res.json({ ...gated, tiers, providerIssues, launchDescriptors });
+        // Display names so app-level selectors (Agent composer, Builder) can label
+        // a local engine with its connection label instead of its raw id.
+        const labels = Object.fromEntries((0, providers_1.listAdapters)().map((adapter) => [adapter.id, adapter.displayName]));
+        res.json({ ...gated, tiers, providerIssues, launchDescriptors, labels });
     });
     router.get('/setup-prerequisites', (req, res) => {
         const status = (0, setup_prerequisites_1.getSetupPrerequisitesStatus)();
@@ -1230,28 +1247,94 @@ function createDesktopRouter(registry, broadcast) {
         res.json({ language, monthlyBudgetUsd });
     });
     (0, runtime_role_prompts_router_1.registerRuntimeRolePromptRoutes)(router);
+    // ─── Runtime provider connections (local AI engines) ──────────────────────
+    // GET returns every connection plus a per-id status: local ids read the
+    // detection cache (reachable/authState/models), CLI ids the detection
+    // snapshot. PUT saves, re-syncs the local adapters, re-probes them (awaited)
+    // and broadcasts `providers.detected_changed` when the usable set changed so
+    // open engine selectors update live. POST /test probes an UNSAVED draft.
+    const runtimeProviderStatus = (providers) => {
+        const snapshot = (0, provider_detection_1.getSnapshotSync)();
+        const status = {};
+        for (const provider of providers) {
+            if (provider.kind === 'openai-compatible') {
+                const probe = (0, local_engine_detection_1.getCachedProbe)(provider.id);
+                status[provider.id] = probe
+                    ? {
+                        kind: 'local', reachable: probe.reachable, authState: probe.authState, models: probe.models,
+                        latencyMs: probe.latencyMs, ...(probe.error ? { error: probe.error } : {}),
+                        ...(probe.apiKeyEnvMissing ? { apiKeyEnvMissing: true } : {}),
+                    }
+                    : { kind: 'local', reachable: false, authState: 'unknown', models: [], probing: true };
+                continue;
+            }
+            const row = snapshot?.providers[provider.cli];
+            status[provider.id] = row
+                ? { kind: 'cli', reachable: row.usable, installed: row.installed, executable: row.executable, authState: row.authState, models: [], ...(row.version ? { version: row.version } : {}), ...(row.error ? { error: row.error } : {}) }
+                : { kind: 'cli', reachable: false, installed: false, executable: false, authState: 'unknown', models: [], probing: true };
+        }
+        return status;
+    };
     router.get('/runtime-providers', (_req, res) => {
         try {
             for (const project of (0, desktop_db_1.listProjects)(registry.desktopDb))
                 (0, agent_runtime_settings_1.loadAgentRuntimeConfig)(project);
-            res.json({ providers: (0, agent_runtime_settings_1.loadRuntimeProviders)() });
+            const providers = (0, agent_runtime_settings_1.loadRuntimeProviders)();
+            res.json({ providers, status: runtimeProviderStatus(providers), localEnginesEnabled: (0, local_adapter_registry_1.isLocalEnginesEnabled)() });
         }
         catch (error) {
             res.status(422).json({ message: error.message });
         }
     });
-    router.put('/runtime-providers', (req, res) => {
+    router.put('/runtime-providers', async (req, res) => {
+        let saved;
         try {
             const projects = (0, desktop_db_1.listProjects)(registry.desktopDb).map(project => (0, agent_runtime_settings_1.loadAgentRuntimeConfig)(project));
             const providers = (0, agent_runtime_settings_1.validateRuntimeProviders)(req.body.providers);
             for (const config of projects)
                 if (config)
                     (0, agent_runtime_settings_1.validateAgentRuntimeConfig)({ ...config, providers });
-            res.json({ providers: (0, agent_runtime_settings_1.saveRuntimeProviders)(providers) });
+            saved = (0, agent_runtime_settings_1.saveRuntimeProviders)(providers);
         }
         catch (error) {
             res.status(error instanceof agent_runtime_settings_1.AgentRuntimeConfigError ? 400 : 500).json({ message: error.message });
+            return;
+        }
+        try {
+            (0, local_adapter_registry_1.syncLocalAdapters)(saved);
+            const { snapshot, changed } = await (0, provider_detection_1.refreshLocalDetection)();
+            if (changed) {
+                broadcast({
+                    type: 'providers.detected_changed',
+                    detected: snapshot.detected,
+                    providers: snapshot.providers,
+                    timestamp: new Date().toISOString(),
+                });
+            }
         }
+        catch (error) {
+            console.warn('[runtime-providers] local engine re-sync failed (non-fatal):', error.message);
+        }
+        res.json({ providers: saved, status: runtimeProviderStatus(saved), localEnginesEnabled: (0, local_adapter_registry_1.isLocalEnginesEnabled)() });
+    });
+    router.post('/runtime-providers/test', async (req, res) => {
+        const body = (req.body ?? {});
+        // Same shape rules as the connections schema (absolute http(s), no
+        // credentials/query/fragment; env NAME only, never a key value).
+        if (typeof body.baseUrl !== 'string' || !/^https?:\/\/[^/?#@]+(?:\/[^?#]*)?$/.test(body.baseUrl)) {
+            res.status(400).json({ error: 'invalid_base_url', message: 'baseUrl must be an absolute HTTP(S) URL without credentials, query or fragment' });
+            return;
+        }
+        if (body.apiKeyEnv !== undefined && body.apiKeyEnv !== null && body.apiKeyEnv !== '' && (typeof body.apiKeyEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(body.apiKeyEnv))) {
+            res.status(400).json({ error: 'invalid_api_key_env', message: 'apiKeyEnv must be an environment variable name' });
+            return;
+        }
+        const apiKeyEnv = typeof body.apiKeyEnv === 'string' && body.apiKeyEnv ? body.apiKeyEnv : undefined;
+        const probe = await (0, local_engine_detection_1.probeConnection)({ baseUrl: body.baseUrl, apiKeyEnv });
+        res.json({
+            reachable: probe.reachable, authState: probe.authState, models: probe.models, latencyMs: probe.latencyMs,
+            ...(probe.error ? { error: probe.error } : {}), ...(probe.apiKeyEnvMissing ? { apiKeyEnvMissing: true } : {}),
+        });
     });
     // ─── Specrails Agents defaults (global per-provider agent model/effort) ───
     // App-level layer read AT SPAWN TIME by QueueManager / rails-router / loop

package/server/dist/index.js

@@ -53,6 +53,19 @@ const transient_children_1 = require("./transient-children");
 // before any manager constructs a project context. See
 // openspec/changes/add-multi-provider-support/specs/multi-provider-architecture/spec.md.
 require("./providers");
+const local_adapter_registry_1 = require("./providers/local-adapter-registry");
+const agent_runtime_settings_1 = require("./agent-runtime-settings");
+// Local AI engines: every OpenAI-compatible connection in
+// ~/.specrails/runtime-providers.json becomes a registered adapter BEFORE the
+// first detection cycle (kill switch SPECRAILS_LOCAL_ENGINES=false ⇒ no-op).
+try {
+    const sync = (0, local_adapter_registry_1.syncLocalAdapters)((0, agent_runtime_settings_1.loadRuntimeProviders)());
+    if (sync.registered.length)
+        console.log(`[local-engines] registered: ${sync.registered.join(', ')}`);
+}
+catch (err) {
+    console.warn('[local-engines] could not load runtime provider connections (non-fatal):', err.message);
+}
 const hostControlToken = (0, host_control_1.consumeHostControlToken)();
 const inheritedPathBeforeResolve = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean).length;
 // Backfill SystemRoot/ComSpec/etc into process.env BEFORE anything spawns, so a

package/server/dist/interactive-job-session.js

@@ -39,6 +39,7 @@ const explore_stdin_session_1 = require("./explore-stdin-session");
 const result_event_1 = require("./result-event");
 const db_1 = require("./db");
 const stream_display_1 = require("./util/stream-display");
+const registry_1 = require("./providers/registry");
 const runtime_1 = require("./providers/runtime");
 const terminal_result_1 = require("./providers/terminal-result");
 const claude_background_tasks_1 = require("./providers/claude-background-tasks");
@@ -227,7 +228,8 @@ class InteractiveJobSession {
         // system context, not in the command's argument string. Preserve any
         // existing appended system prompt supplied by the queue/loop owner.
         const args = [...spec.args];
-        if (this._adapter.id === 'claude' && this._settleMode === 'auto') {
+        // Local runners share claude's argv shape for the appended system prompt.
+        if ((this._adapter.id === 'claude' || (0, registry_1.isLocalAdapterId)(this._adapter.id)) && this._settleMode === 'auto') {
             const index = args.indexOf('--append-system-prompt');
             if (index >= 0)
                 args[index + 1] = `${args[index + 1] ?? ''}\n\n${loop_constants_1.FOREGROUND_RULE}`;