specrails-desktop 2.16.0 → 2.18.0

package/server/dist/agent-chat-manager.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentChatManager = void 0;
+const providers_1 = require("./providers");
+const spawn_lifecycle_1 = require("./spawn-lifecycle");
+const agent_cwd_manager_1 = require("./agent-cwd-manager");
+const agent_mcp_config_1 = require("./agent-mcp-config");
+const agent_tier_1 = require("./agent-tier");
+const agent_store_1 = require("./agent-store");
+const types_1 = require("./mcp/tools/types");
+// ─── AgentChatManager (design D1) ─────────────────────────────────────────────
+//
+// App-level sibling of ChatManager: spawns an AI CLI from the app-owned agent cwd
+// with the Specrails MCP bridge as its tool source, streams the turn over the
+// app-global `agent_*` WS events (no projectId — fans to all subscribers), and
+// persists to the app registry DB. It reuses the shared spawn→stream→settle core
+// (runAiCliInvocation) rather than re-implementing ChatManager's loop.
+const OPERATOR_SYSTEM_PROMPT = 'You are the Specrails operator agent. Drive the Specrails Desktop app on the ' +
+    "user's behalf using the specrails_* MCP tools. Target a project with " +
+    'specrails_select_project (or the projectId argument); if none is selected and ' +
+    'the request is project-specific, ask whether to create a project or search all. ' +
+    'Follow HTTP-202 actions to completion with specrails_watch. Respect the ' +
+    'permission ladder: if a tool is refused for the current level, tell the user ' +
+    'which level it needs rather than working around it. Be concise; report tool ' +
+    'outputs faithfully, including failures. Format replies for easy reading: ' +
+    'separate distinct ideas into short paragraphs with a blank line between them ' +
+    '(not one dense block), and use bullet lists for enumerations. ' +
+    'When the user has no projects yet, or wants to add one, first explain the UI ' +
+    'steps (click "Add Project" / the + in the left sidebar, enter the repo\'s ' +
+    'folder path, pick an AI provider, then run setup), THEN offer to do it for ' +
+    'them from here: ask for the repo folder path and which AI providers to set up, ' +
+    'then with their go-ahead call specrails_setup add_project (Edit level) and a ' +
+    'single specrails_setup install (Operate level) — one install provisions ALL the ' +
+    'chosen providers in one shot (no need to install them one by one). Setup is ' +
+    'QUICK-only (offline); do NOT offer or mention a "full" or "enrich" install. Use ' +
+    'specrails_setup prerequisites / available_providers first to check the machine.';
+class AgentChatManager {
+    _broadcast;
+    _db;
+    _port;
+    _active = new Map();
+    constructor(broadcast, db, port) {
+        this._broadcast = broadcast;
+        this._db = db;
+        this._port = port;
+    }
+    /** True while a turn is streaming for this conversation. */
+    isStreaming(conversationId) {
+        return this._active.has(conversationId);
+    }
+    /**
+     * Runs one agent turn: persists the user message, spawns the AI CLI pointed at
+     * the Specrails MCP, streams deltas + tool-use as `agent_*` events, then
+     * persists the assistant reply and the session id. Settles once.
+     */
+    async sendMessage(conversationId, userText, options = {}) {
+        const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+        if (!conversation) {
+            this._emitError(conversationId, 'Unknown conversation');
+            return;
+        }
+        if (this._active.has(conversationId)) {
+            this._emitError(conversationId, 'The agent is busy. Try again in a moment.');
+            return;
+        }
+        const tierLevel = (0, agent_tier_1.normalizeLevel)(options.tierLevel ?? conversation.tier_level);
+        const adapter = (0, providers_1.getAdapter)(conversation.provider);
+        // Resolve a model that is VALID for this provider. A stale model from another
+        // provider (e.g. claude's "sonnet" after switching to codex) is rejected by
+        // the provider — fall back to the provider's default instead of failing.
+        const catalog = new Set(adapter.modelCatalog().map((m) => m.value));
+        const requested = options.model || conversation.model;
+        const model = requested && catalog.has(requested) ? requested : adapter.defaultModel();
+        // Make the pinned project (Cursor-style selector) the MCP active project for
+        // this turn, so project-scoped tools resolve without the agent having to call
+        // specrails_select_project. Home (null) clears it → app-global mode.
+        (0, types_1.setActiveProject)(conversation.pinned_project_id ?? null);
+        (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'user', content: userText });
+        // Tell the agent which project is pinned (so it phrases + passes projectId).
+        const prompt = conversation.pinned_project_id
+            ? `[Active project: projectId="${conversation.pinned_project_id}". Use it for project-scoped tools unless told otherwise.]\n\n${userText}`
+            : userText;
+        const cwd = (0, agent_cwd_manager_1.ensureAgentCwd)();
+        let mcpArgs = [];
+        let mcpEnv = {};
+        try {
+            const wiring = (0, agent_mcp_config_1.prepareAgentMcp)({
+                adapterId: adapter.id,
+                conversationId,
+                cwd,
+                port: this._port,
+                tierLevel,
+                activeProjectId: conversation.pinned_project_id,
+            });
+            mcpArgs = wiring.extraArgs;
+            mcpEnv = wiring.env;
+        }
+        catch (err) {
+            // A bad conversation id or fs failure shouldn't poison the chat — run tool-less.
+            console.error('[agent-chat] failed to prepare mcp:', err);
+        }
+        const timestamp = () => new Date().toISOString();
+        const invoke = async (useResume) => {
+            const action = useResume ? 'chat-resume' : 'chat-turn';
+            let streamed = '';
+            let capturedSessionId = useResume ? conversation.session_id ?? null : null;
+            let capturedError = null;
+            console.log(`[agent-chat] turn start conv=${conversationId} provider=${adapter.id} binary=${adapter.binary} ` +
+                `action=${action} model=${model} cwd=${cwd} mcp=${mcpArgs.length ? 'mcp-config' : Object.keys(mcpEnv).join(',') || 'none'}`);
+            const result = await (0, spawn_lifecycle_1.runAiCliInvocation)({
+                adapter,
+                action,
+                cwd,
+                env: { ...process.env, ...mcpEnv },
+                buildOpts: {
+                    prompt,
+                    systemPrompt: adapter.capabilities.systemPromptArg ? OPERATOR_SYSTEM_PROMPT : undefined,
+                    model,
+                    sessionId: useResume ? conversation.session_id ?? undefined : undefined,
+                    extraArgs: mcpArgs,
+                },
+                onSpawn: (child) => {
+                    this._active.set(conversationId, child);
+                },
+                onEvent: (ev) => {
+                    switch (ev.kind) {
+                        case 'text-delta':
+                            streamed += ev.text;
+                            this._broadcast({ type: 'agent_stream', conversationId, delta: ev.text, timestamp: timestamp() });
+                            break;
+                        case 'tool-use':
+                            this._broadcast({ type: 'agent_tool', conversationId, tool: ev.name, timestamp: timestamp() });
+                            break;
+                        case 'session-started':
+                            if (ev.sessionId)
+                                capturedSessionId = ev.sessionId;
+                            break;
+                        case 'result': {
+                            const sid = ev.payload.session_id;
+                            if (sid)
+                                capturedSessionId = sid;
+                            break;
+                        }
+                        case 'error':
+                            capturedError = ev.message;
+                            break;
+                        case 'other':
+                            break;
+                    }
+                },
+            });
+            this._active.delete(conversationId);
+            const text = streamed.trim();
+            console.log(`[agent-chat] turn end conv=${conversationId} provider=${adapter.id} code=${result.code} ` +
+                `spawnFailed=${result.spawnFailed} chars=${text.length} err=${capturedError ?? ''}`);
+            if (result.stderrTail && (result.spawnFailed || (result.code ?? 0) !== 0 || !text)) {
+                console.error(`[agent-chat] ${adapter.id} stderr:\n${result.stderrTail}`);
+            }
+            return { text, sessionId: capturedSessionId, error: capturedError, code: result.code, spawnFailed: result.spawnFailed, stderrTail: result.stderrTail };
+        };
+        const canResume = !!conversation.session_id && adapter.capabilities.nativeResume;
+        let r = await invoke(canResume);
+        // Auto-heal a stale/foreign session: a resume that produced no text (e.g. a
+        // provider switch leaving another provider's session id, or codex
+        // "no rollout found for thread id") retries once as a fresh turn.
+        if (canResume && !r.spawnFailed && !r.text) {
+            console.log(`[agent-chat] resume produced no text — retrying fresh conv=${conversationId}`);
+            (0, agent_store_1.updateAgentConversation)(this._db, conversationId, { session_id: null });
+            r = await invoke(false);
+        }
+        if (r.spawnFailed) {
+            this._emitError(conversationId, `Failed to launch ${adapter.binary}. Is it installed and on PATH?`);
+            return;
+        }
+        if (r.text) {
+            (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'assistant', content: r.text });
+            (0, agent_store_1.updateAgentConversation)(this._db, conversationId, {
+                session_id: r.sessionId,
+                provider: conversation.provider,
+                model,
+                tier_level: tierLevel,
+            });
+            this._broadcast({ type: 'agent_done', conversationId, fullText: r.text, timestamp: timestamp() });
+            return;
+        }
+        // Failure: reset the session so the NEXT turn starts fresh, and surface the
+        // real reason instead of silently doing nothing.
+        (0, agent_store_1.updateAgentConversation)(this._db, conversationId, { session_id: null, provider: conversation.provider, model, tier_level: tierLevel });
+        const reason = r.error ||
+            (r.stderrTail ? r.stderrTail.split('\n').filter(Boolean).slice(-3).join(' ').slice(0, 300) : '') ||
+            (r.code !== 0 ? `${adapter.binary} exited with code ${r.code}` : 'The agent returned no output.');
+        this._emitError(conversationId, reason);
+    }
+    /** Aborts the active turn for a conversation, if any. */
+    abort(conversationId) {
+        const child = this._active.get(conversationId);
+        if (!child)
+            return false;
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            /* ignore */
+        }
+        this._active.delete(conversationId);
+        return true;
+    }
+    /** Kills all active turns (graceful shutdown). */
+    async shutdown() {
+        for (const [, child] of this._active) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this._active.clear();
+    }
+    _emitError(conversationId, error) {
+        this._broadcast({ type: 'agent_error', conversationId, error, timestamp: new Date().toISOString() });
+    }
+}
+exports.AgentChatManager = AgentChatManager;

package/server/dist/agent-chat-router.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAgentChatEnabled = isAgentChatEnabled;
+exports.createAgentChatRouter = createAgentChatRouter;
+const express_1 = require("express");
+const providers_1 = require("./providers");
+const agent_tier_1 = require("./agent-tier");
+const agent_store_1 = require("./agent-store");
+function isAgentChatEnabled() {
+    return process.env.SPECRAILS_AGENT_CHAT !== 'false';
+}
+function validProvider(provider) {
+    if (typeof provider !== 'string' || !provider)
+        return null;
+    try {
+        (0, providers_1.getAdapter)(provider);
+        return provider;
+    }
+    catch {
+        return null;
+    }
+}
+function createAgentChatRouter(deps) {
+    const { manager, desktopDb } = deps;
+    const router = (0, express_1.Router)();
+    // Feature gate: 404 the whole surface when disabled.
+    router.use((_req, res, next) => {
+        if (!isAgentChatEnabled()) {
+            res.status(404).json({ error: 'Agent chat is disabled' });
+            return;
+        }
+        next();
+    });
+    // Per-provider model catalog for the header model selector.
+    router.get('/models', (req, res) => {
+        const provider = validProvider(req.query.provider) ?? 'claude';
+        res.json({ provider, models: (0, providers_1.getAdapter)(provider).modelCatalog() });
+    });
+    router.get('/conversations', (_req, res) => {
+        res.json({ conversations: (0, agent_store_1.listAgentConversations)(desktopDb) });
+    });
+    router.post('/conversations', (req, res) => {
+        const body = (req.body ?? {});
+        let provider = 'claude';
+        if (body.provider !== undefined) {
+            const v = validProvider(body.provider);
+            if (!v) {
+                res.status(400).json({ error: 'Unknown or unavailable provider' });
+                return;
+            }
+            provider = v;
+        }
+        const conversation = (0, agent_store_1.createAgentConversation)(desktopDb, {
+            provider,
+            model: typeof body.model === 'string' ? body.model : null,
+            pinnedProjectId: typeof body.pinnedProjectId === 'string' ? body.pinnedProjectId : null,
+            tierLevel: body.tierLevel !== undefined ? (0, agent_tier_1.normalizeLevel)(body.tierLevel) : 0,
+        });
+        res.status(201).json({ conversation });
+    });
+    router.get('/conversations/:id', (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        res.json({ conversation, messages: (0, agent_store_1.listAgentMessages)(desktopDb, conversation.id) });
+    });
+    router.patch('/conversations/:id', (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const patch = {};
+        if (body.title !== undefined)
+            patch.title = typeof body.title === 'string' ? body.title : null;
+        if (body.pinnedProjectId !== undefined) {
+            patch.pinned_project_id = typeof body.pinnedProjectId === 'string' ? body.pinnedProjectId : null;
+        }
+        if (body.tierLevel !== undefined)
+            patch.tier_level = (0, agent_tier_1.normalizeLevel)(body.tierLevel);
+        if (body.provider !== undefined) {
+            const v = validProvider(body.provider);
+            if (!v) {
+                res.status(400).json({ error: 'Unknown or unavailable provider' });
+                return;
+            }
+            patch.provider = v;
+            // Switching provider invalidates the stored session id AND model (both
+            // belong to the previous provider) — clear them so the next turn starts a
+            // fresh session with the new provider's default model (codex rejects
+            // claude's "sonnet"; resume of a foreign thread → "no rollout found").
+            if (v !== conversation.provider) {
+                patch.session_id = null;
+                patch.model = null;
+            }
+        }
+        // Explicit model pick — validated against the (new or current) provider's catalog.
+        if (body.model !== undefined && patch.model === undefined) {
+            if (body.model === null) {
+                patch.model = null;
+            }
+            else if (typeof body.model === 'string') {
+                const effectiveProvider = patch.provider ?? conversation.provider;
+                const valid = new Set((0, providers_1.getAdapter)(effectiveProvider).modelCatalog().map((m) => m.value));
+                if (!valid.has(body.model)) {
+                    res.status(400).json({ error: 'Model not available for this provider' });
+                    return;
+                }
+                patch.model = body.model;
+            }
+        }
+        res.json({ conversation: (0, agent_store_1.updateAgentConversation)(desktopDb, conversation.id, patch) });
+    });
+    router.delete('/conversations/:id', (req, res) => {
+        manager.abort(String(req.params.id));
+        (0, agent_store_1.deleteAgentConversation)(desktopDb, String(req.params.id));
+        res.json({ ok: true });
+    });
+    router.post('/conversations/:id/send', (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const text = typeof body.text === 'string' ? body.text.trim() : '';
+        if (!text) {
+            res.status(400).json({ error: 'text is required' });
+            return;
+        }
+        const tierLevel = body.tierLevel !== undefined ? (0, agent_tier_1.normalizeLevel)(body.tierLevel) : undefined;
+        const model = typeof body.model === 'string' ? body.model : undefined;
+        // Fire-and-forget: the turn streams over WS. Persist the chosen tier first so
+        // a refresh mid-turn restores the right level.
+        if (tierLevel !== undefined)
+            (0, agent_store_1.updateAgentConversation)(desktopDb, conversation.id, { tier_level: tierLevel });
+        void manager.sendMessage(conversation.id, text, { tierLevel, model });
+        res.status(202).json({ accepted: true });
+    });
+    router.post('/conversations/:id/abort', (req, res) => {
+        const aborted = manager.abort(String(req.params.id));
+        res.json({ aborted });
+    });
+    return router;
+}

package/server/dist/agent-cwd-manager.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentCwdPath = agentCwdPath;
+exports.ensureAgentCwd = ensureAgentCwd;
+exports.removeAgentCwd = removeAgentCwd;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+// ─── App-level agent working directory (design D1) ────────────────────────────
+//
+// The agent chat spawns the AI CLI from an app-owned cwd (NOT a project path), so
+// no project's CLAUDE.md is auto-loaded and the agent starts with a focused
+// "operator" stance. Mirrors explore-cwd-manager but is app-global (one dir, no
+// project symlink). The operator instructions are written for every provider
+// (CLAUDE.md / AGENTS.md / GEMINI.md) so the chosen CLI picks them up.
+function homeDir() {
+    return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+}
+function agentCwdPath() {
+    return path_1.default.join(homeDir(), '.specrails', 'agent-cwd');
+}
+const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
+const OPERATOR_INSTRUCTIONS = `# Specrails Operator Agent
+
+You are the in-app Specrails operator. You drive the Specrails Desktop app on the
+user's behalf through the \`specrails_*\` MCP tools (projects, specs, rails, jobs,
+chat, agents, plugins, jira, loops, code, analytics, setup, settings).
+
+## How to work
+- Use \`specrails_select_project\` (or the projectId argument) to target a project.
+  If no project is selected ("Home") and the request is project-specific, ASK the
+  user whether to create a new project or search across all projects — do not guess.
+- For long-running actions that return HTTP 202, use \`specrails_watch\` to follow
+  them to completion instead of assuming they finished.
+- Prefer the meta tools \`specrails_guide\` / \`specrails_search\` / \`specrails_describe\`
+  to discover the exact action/arguments before calling a domain tool.
+
+## Permission ladder
+Your actions are gated by a cumulative level the user sets live:
+observe (read) ▸ edit (write) ▸ operate (launch AI, costs money) ▸ autonomous
+(delete/kill). If a tool is refused for the current level, tell the user which
+level it needs — do not try to work around the refusal.
+
+## Stance
+Be concise and action-oriented. Confirm what you did with concrete references
+(ids, names). Never fabricate results — report tool outputs faithfully, including
+failures.
+
+## Formatting
+Make replies easy to read: separate distinct ideas into short paragraphs with a
+blank line between them (avoid one dense block of text), and use bullet lists for
+enumerations. Give the conversation some breathing room.
+
+## Adding a project
+When the user has no projects yet, or asks to add one:
+1. Explain the UI path: click "Add Project" (the + in the left sidebar), enter the
+   repo's folder path, pick an AI provider, then run setup.
+2. Then OFFER to do it for them from here: ask for the repo folder path and which
+   AI providers to set up, then with their go-ahead call
+   \`specrails_setup(add_project, path, providers)\` (Edit level) and a SINGLE
+   \`specrails_setup(install, projectId)\` (Operate level) — one install provisions
+   ALL the chosen providers in one shot (do not install them one at a time).
+   Use \`specrails_setup(prerequisites)\` / \`available_providers\` first to confirm
+   the machine is ready.
+
+Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full" or
+"enrich" install — that flow is deprecated and not available through you.
+`;
+/**
+ * Ensures the app-level agent cwd exists with operator instruction files.
+ * Idempotent; safe to call on every turn. Returns the cwd path.
+ */
+function ensureAgentCwd() {
+    const dir = agentCwdPath();
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    for (const name of INSTRUCTION_FILES) {
+        // App-owned files (not user-edited) — always (re)write so operator-prompt
+        // updates take effect instead of being pinned to the first materialization.
+        fs_1.default.writeFileSync(path_1.default.join(dir, name), OPERATOR_INSTRUCTIONS, 'utf-8');
+    }
+    return dir;
+}
+/** Removes the agent cwd (used on full teardown / reset). Best-effort. */
+function removeAgentCwd() {
+    try {
+        fs_1.default.rmSync(agentCwdPath(), { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}

package/server/dist/agent-mcp-config.js

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBridgeScript = resolveBridgeScript;
+exports.resolveNodeCommand = resolveNodeCommand;
+exports.buildSpecrailsMcpEntry = buildSpecrailsMcpEntry;
+exports.mergeSpecrailsIntoWorkspaceMcp = mergeSpecrailsIntoWorkspaceMcp;
+exports.buildAgentMcpArgs = buildAgentMcpArgs;
+exports.prepareAgentMcp = prepareAgentMcp;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const path_resolver_1 = require("./path-resolver");
+const agent_tier_1 = require("./agent-tier");
+// ─── Agent MCP wiring (design D8 / D1) ────────────────────────────────────────
+//
+// The in-app agent drives the app by talking to its OWN embedded MCP server. We
+// spawn the AI CLI with `--mcp-config` pointing at a generated config whose sole
+// server is the bundled `specrails-mcp` stdio bridge, which relays to
+// `127.0.0.1:<port>/api/mcp` and reads the scoped token from disk (no token is
+// ever written into the config file). The current Shift+Tab ladder level is
+// forwarded via env → the bridge sets it as a loopback-only header so the tool
+// guard enforces the agent ladder independently of the external Settings tiers.
+function homeDir() {
+    return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+}
+function fileExists(p) {
+    try {
+        return fs_1.default.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Absolute path to the `specrails-mcp` bridge JS. Resolution order:
+ *   1. SPECRAILS_BUNDLED_MCP_BRIDGE_PATH (set by the Tauri host in the packaged app)
+ *   2. the staged copy under src-tauri/binaries/ (dev + bundled layouts)
+ *   3. the mcp-bridge build output (mcp-bridge/dist/)
+ * Climbs from this module so it works whether running from server/ or server/dist/.
+ */
+function resolveBridgeScript() {
+    const fromEnv = process.env.SPECRAILS_BUNDLED_MCP_BRIDGE_PATH;
+    if (fromEnv && fileExists(fromEnv))
+        return fromEnv;
+    const roots = [
+        path_1.default.resolve(__dirname, '..'),
+        path_1.default.resolve(__dirname, '..', '..'),
+        process.cwd(),
+    ];
+    const rels = [
+        path_1.default.join('src-tauri', 'binaries', 'specrails-mcp.js'),
+        path_1.default.join('mcp-bridge', 'dist', 'specrails-mcp.js'),
+    ];
+    for (const root of roots) {
+        for (const rel of rels) {
+            const candidate = path_1.default.join(root, rel);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** The node executable that should run the bridge (bundled in the packaged app, else PATH `node`). */
+function resolveNodeCommand() {
+    return (0, path_resolver_1.resolveBundledNodeExe)() ?? 'node';
+}
+/** Build the `mcpServers.specrails` entry the agent (or a project workspace) uses. */
+function buildSpecrailsMcpEntry(opts) {
+    const bridge = resolveBridgeScript();
+    if (!bridge)
+        return null;
+    const env = {
+        SPECRAILS_MCP_PORT: String(opts.port),
+    };
+    // Preserve the test-home override so the bridge reads the right token file.
+    if (process.env.SPECRAILS_REGISTRY_HOME)
+        env.SPECRAILS_REGISTRY_HOME = process.env.SPECRAILS_REGISTRY_HOME;
+    if (opts.tierLevel != null)
+        env[agent_tier_1.AGENT_TIER_ENV] = (0, agent_tier_1.tierNameForLevel)(opts.tierLevel);
+    if (opts.activeProjectId)
+        env[agent_tier_1.AGENT_PROJECT_ENV] = opts.activeProjectId;
+    return { command: resolveNodeCommand(), args: [bridge], env };
+}
+/**
+ * Part A (design D8): surgically merge the `specrails` MCP server into a
+ * project's app-managed WORKSPACE `.mcp.json` so the project's own rails/explore/
+ * chat spawns can also call the Specrails MCP. NEVER touches the pristine repo.
+ * Additive + idempotent: preserves any existing (e.g. plugin) mcpServers entries,
+ * writes atomically (temp + rename), inlines NO token. Returns true when written.
+ */
+function mergeSpecrailsIntoWorkspaceMcp(workspaceDir, port) {
+    const entry = buildSpecrailsMcpEntry({ port });
+    if (!entry)
+        return false;
+    const file = path_1.default.join(workspaceDir, '.mcp.json');
+    let current = {};
+    try {
+        if (fs_1.default.existsSync(file)) {
+            const parsed = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+            if (parsed && typeof parsed === 'object')
+                current = parsed;
+        }
+    }
+    catch {
+        // Corrupt file → start fresh rather than crash assembly.
+        current = {};
+    }
+    const mcpServers = { ...(current.mcpServers ?? {}), specrails: entry };
+    const next = { ...current, mcpServers };
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs_1.default.mkdirSync(workspaceDir, { recursive: true });
+    fs_1.default.writeFileSync(tmp, JSON.stringify(next, null, 2));
+    fs_1.default.renameSync(tmp, file);
+    return true;
+}
+/**
+ * Writes a per-conversation `--mcp-config` file for the agent and returns the
+ * `['--mcp-config', <file>]` argv to inject into SpawnOptions.extraArgs. Uses the
+ * bundled `specrails-mcp` stdio bridge (shipped inside the app — the user installs
+ * nothing; 100% unattended) which relays to this process's `/api/mcp`. Returns
+ * `[]` when the bridge can't be located (agent then runs tool-less / degraded).
+ */
+function buildAgentMcpArgs(opts) {
+    const entry = buildSpecrailsMcpEntry({ port: opts.port, tierLevel: opts.tierLevel, activeProjectId: opts.activeProjectId });
+    if (!entry)
+        return [];
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(opts.conversationId)) {
+        throw new Error(`unsafe agent conversation id: ${opts.conversationId}`);
+    }
+    const dir = path_1.default.join(homeDir(), '.specrails', 'agent', opts.conversationId);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const file = path_1.default.join(dir, 'mcp.json');
+    fs_1.default.writeFileSync(file, JSON.stringify({ mcpServers: { specrails: entry } }, null, 2), { mode: 0o600 });
+    try {
+        fs_1.default.chmodSync(file, 0o600);
+    }
+    catch {
+        /* best-effort on platforms without chmod */
+    }
+    return ['--mcp-config', file];
+}
+function agentDir(conversationId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(conversationId)) {
+        throw new Error(`unsafe agent conversation id: ${conversationId}`);
+    }
+    const dir = path_1.default.join(homeDir(), '.specrails', 'agent', conversationId);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Codex registers the specrails MCP via inline `-c mcp_servers.specrails.*`
+ * config overrides. This keeps codex on the USER's real CODEX_HOME (auth + model
+ * settings intact — no all-or-nothing 401 from a CODEX_HOME override) and cannot
+ * break codex startup the way an unknown `--mcp-config` flag does: `-c` is a known
+ * flag and unknown config keys are simply set. TOML scalar values reuse JSON
+ * escaping (compatible for our command/path/env inputs).
+ */
+function codexMcpOverrides(entry) {
+    const c = (kv) => ['-c', kv];
+    const args = [
+        ...c(`mcp_servers.specrails.command=${JSON.stringify(entry.command)}`),
+        ...c(`mcp_servers.specrails.args=[${entry.args.map((a) => JSON.stringify(a)).join(', ')}]`),
+    ];
+    for (const [k, v] of Object.entries(entry.env)) {
+        args.push(...c(`mcp_servers.specrails.env.${k}=${JSON.stringify(v)}`));
+    }
+    return args;
+}
+/**
+ * Prepares the specrails MCP for the given provider and returns the spawn
+ * extraArgs + env to merge. Returns empty wiring when the bridge is unavailable
+ * (agent then runs tool-less / degraded).
+ */
+function prepareAgentMcp(opts) {
+    const entry = buildSpecrailsMcpEntry({
+        port: opts.port,
+        tierLevel: opts.tierLevel,
+        activeProjectId: opts.activeProjectId,
+    });
+    if (!entry)
+        return { extraArgs: [], env: {} };
+    if (opts.adapterId === 'codex') {
+        // Inline -c overrides — no CODEX_HOME override, no file mutation; auth intact.
+        return { extraArgs: codexMcpOverrides(entry), env: {} };
+    }
+    if (opts.adapterId === 'claude') {
+        return { extraArgs: buildAgentMcpArgs(opts), env: {} };
+    }
+    // gemini + any other project-json provider: write .mcp.json in the spawn cwd.
+    const file = path_1.default.join(opts.cwd, '.mcp.json');
+    let current = {};
+    try {
+        if (fs_1.default.existsSync(file)) {
+            const parsed = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+            if (parsed && typeof parsed === 'object')
+                current = parsed;
+        }
+    }
+    catch {
+        current = {};
+    }
+    const next = { ...current, mcpServers: { ...(current.mcpServers ?? {}), specrails: entry } };
+    fs_1.default.writeFileSync(file, JSON.stringify(next, null, 2), { mode: 0o600 });
+    return { extraArgs: [], env: {} };
+}