specrails-desktop 2.16.0 → 2.18.0

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

@@ -0,0 +1,327 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specsTools = specsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+// Per-action danger classification for the specs (tickets) facade.
+const DESTRUCTIVE_ACTIONS = new Set(['delete', 'smash_undo', 'delete_epic_children']);
+// `create` routes through Quick Add Spec (generate-spec) so MCP-created specs
+// match the app's "Add Spec → Quick" flow — hence ai-spawn, not write.
+const AI_SPAWN_ACTIONS = new Set(['create', 'generate', 'ai_edit', 'contract_refine', 'smash']);
+// `commit_draft` (POST /tickets/from-draft) may fire-and-forget a Contract
+// Refine spawn as a side-effect, but the call itself is a synchronous store
+// mutation (a write), so it is classified as `write`.
+const WRITE_ACTIONS = new Set([
+    'update', 'from_prompt', 'save_draft', 'commit_draft', 'cancel_ai_edit',
+]);
+function resolveSpecsTier(action) {
+    if (DESTRUCTIVE_ACTIONS.has(action))
+        return 'destructive';
+    if (AI_SPAWN_ACTIONS.has(action))
+        return 'ai-spawn';
+    if (WRITE_ACTIONS.has(action))
+        return 'write';
+    return 'read';
+}
+const WATCH_HINT = 'Returns 202 immediately; the actual result streams over the WebSocket. ' +
+    'Use specrails_watch with the returned requestId/scheduled ref to await completion ' +
+    '(WS events: spec_gen_*, ticket_ai_edit_*, explore.contract_refine_*, smash.*).';
+function specsTools() {
+    return [
+        {
+            name: 'specrails_specs',
+            title: 'Specs (Tickets)',
+            description: 'Manage the spec/ticket backlog for a project (the local-tickets.json store). ' +
+                'Actions: list, get, ' +
+                'create (ai-spawn — THE way to add a spec: routes through Quick Add Spec, so the specrails agent generates a structured spec with AI from the user request, exactly matching the app\'s "Add Spec → Quick" flow; pass the request as title/description, it becomes the idea; async), ' +
+                'update, delete (destructive), ' +
+                'from_prompt (verbatim insert, no AI — use ONLY when you already have a complete finished spec to store as-is), ' +
+                'save_draft (persist an Explore conversation as a draft), commit_draft (flip a draft to a real spec), ' +
+                'generate (alias of create — Quick AI spec generation), ai_edit (ai-spawn, AI-edit a ticket title+description), ' +
+                'cancel_ai_edit (abort an in-flight ai-edit), contract_refine (ai-spawn, append a Contract Layer — Claude-only), ' +
+                'smash (ai-spawn, decompose a spec into N child sub-specs under an epic — Claude-only), ' +
+                'smash_undo (destructive, reverse a prior SMASH), delete_epic_children (destructive, delete all children of an epic), ' +
+                'spending_summary (per-ticket AI spend), files_touched (provenance of files an AI job touched for this ticket), ' +
+                'list_attachments, get_attachment. The generate/ai_edit/contract_refine/smash actions are async (HTTP 202) — ' +
+                'results arrive over the WebSocket, not the HTTP response.',
+            hintTier: 'read',
+            tier: (args) => resolveSpecsTier(args.action),
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'list',
+                    'get',
+                    'create',
+                    'update',
+                    'delete',
+                    'from_prompt',
+                    'save_draft',
+                    'commit_draft',
+                    'generate',
+                    'ai_edit',
+                    'cancel_ai_edit',
+                    'contract_refine',
+                    'smash',
+                    'smash_undo',
+                    'delete_epic_children',
+                    'spending_summary',
+                    'files_touched',
+                    'list_attachments',
+                    'get_attachment',
+                ])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // ── Ticket identity ──────────────────────────────────────────────
+                id: zod_1.z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Numeric ticket id (get/update/delete/contract_refine/smash/smash_undo/delete_epic_children/spending_summary/files_touched/ai_edit)'),
+                // ── list filters ─────────────────────────────────────────────────
+                status: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('list: filter by status (CSV: draft|todo|in_progress|done|cancelled). create/update: set ticket status'),
+                label: zod_1.z.string().optional().describe('list: filter by label (CSV)'),
+                q: zod_1.z.string().optional().describe('list: free-text search over title + description'),
+                // ── create / update / from_prompt / commit_draft fields ──────────
+                title: zod_1.z.string().optional().describe('Ticket title (required for create / commit_draft)'),
+                description: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Ticket description. For ai_edit this is the REQUIRED current baseline description'),
+                priority: zod_1.z
+                    .enum(['critical', 'high', 'medium', 'low'])
+                    .optional()
+                    .describe('Ticket priority (defaults to medium; may be null only for drafts)'),
+                labels: zod_1.z.array(zod_1.z.string()).optional().describe('Labels array'),
+                assignee: zod_1.z.string().optional().describe('create/update: assignee'),
+                prerequisites: zod_1.z.array(zod_1.z.number().int()).optional().describe('create/update: prerequisite ticket ids'),
+                metadata: zod_1.z.record(zod_1.z.unknown()).optional().describe('create/update: free-form metadata object'),
+                source: zod_1.z.string().optional().describe('create: source tag'),
+                acceptanceCriteria: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('update/commit_draft: acceptance-criteria bullets folded into the description'),
+                shortSummary: zod_1.z.string().optional().describe('commit_draft: explicit short summary (camelCase key)'),
+                short_summary: zod_1.z.string().optional().describe('update: explicit short summary (snake_case key; null clears)'),
+                structured: zod_1.z.boolean().optional().describe('from_prompt: lightly structure the verbatim prompt'),
+                createLocal: zod_1.z.boolean().optional().describe('commit_draft/generate: keep the spec local (skip Jira promote)'),
+                // ── draft linkage ────────────────────────────────────────────────
+                conversationId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('save_draft (required) / commit_draft: origin Explore conversation id'),
+                draftTicketId: zod_1.z.number().int().optional().describe('commit_draft: explicit draft ticket id to flip in place'),
+                editTicketId: zod_1.z.number().int().optional().describe('save_draft: existing ticket id to demote to a draft in place'),
+                pendingSpecId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('generate/from_prompt/commit_draft: pending-spec UUID owning pre-creation attachments'),
+                // ── generate (Quick AI spec) ─────────────────────────────────────
+                idea: zod_1.z.string().optional().describe('generate: the idea/prompt to turn into a spec (required)'),
+                model: zod_1.z.string().optional().describe('generate/smash: model override (validated against the provider catalog)'),
+                aiEngine: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('generate: provider/engine override (must be an installed provider; defaults to primary)'),
+                contextScope: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('generate: context-awareness flags {specrails,openspec,full,mcp,userMcp,contractRefine}'),
+                contractRefine: zod_1.z.boolean().optional().describe('generate: enrich the spec with a Contract Layer (Claude-only)'),
+                attachmentIds: zod_1.z.array(zod_1.z.string()).optional().describe('generate: attachment ids (requires pendingSpecId)'),
+                // ── ai_edit ──────────────────────────────────────────────────────
+                instructions: zod_1.z.string().optional().describe('ai_edit: natural-language editing instructions (required)'),
+                priorInstructions: zod_1.z.array(zod_1.z.string()).optional().describe('ai_edit: prior refinement turns for an iterative edit'),
+                priorProposal: zod_1.z.string().optional().describe('ai_edit: the previous turn proposal to refine'),
+                requestId: zod_1.z.string().optional().describe('cancel_ai_edit: requestId of the in-flight ai-edit to abort (required)'),
+                // ── smash ────────────────────────────────────────────────────────
+                mode: zod_1.z.enum(['simple', 'full']).optional().describe('smash: decomposition mode (default simple)'),
+                smashedAt: zod_1.z.string().optional().describe('smash_undo: the smashedAt timestamp of the SMASH to reverse (required)'),
+                // ── attachments ──────────────────────────────────────────────────
+                ticketId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('list_attachments/get_attachment: ticket numeric id or pending-spec UUID'),
+                attachmentId: zod_1.z.string().optional().describe('get_attachment: attachment id (required)'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                const requireId = () => {
+                    const id = args.id;
+                    if (typeof id !== 'number' || !Number.isInteger(id)) {
+                        throw new Error(`Action "${action}" requires a numeric "id".`);
+                    }
+                    return id;
+                };
+                switch (action) {
+                    // ── reads ──────────────────────────────────────────────────────
+                    case 'list': {
+                        const qs = new URLSearchParams();
+                        if (typeof args.status === 'string')
+                            qs.set('status', args.status);
+                        if (typeof args.label === 'string')
+                            qs.set('label', args.label);
+                        if (typeof args.q === 'string')
+                            qs.set('q', args.q);
+                        const suffix = qs.toString() ? `?${qs.toString()}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets${suffix}`);
+                    }
+                    case 'get':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${requireId()}`);
+                    case 'spending_summary':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${requireId()}/spending-summary`);
+                    case 'files_touched':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/provenance?ticketId=${requireId()}`);
+                    case 'list_attachments': {
+                        const ticketId = args.ticketId;
+                        if (!ticketId)
+                            throw new Error('list_attachments requires a "ticketId" (numeric id or UUID).');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${encodeURIComponent(ticketId)}/attachments`);
+                    }
+                    case 'get_attachment': {
+                        const ticketId = args.ticketId;
+                        const attachmentId = args.attachmentId;
+                        if (!ticketId)
+                            throw new Error('get_attachment requires a "ticketId".');
+                        if (!attachmentId)
+                            throw new Error('get_attachment requires an "attachmentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${encodeURIComponent(ticketId)}/attachments/${encodeURIComponent(attachmentId)}`);
+                    }
+                    // ── writes (synchronous store mutations) ────────────────────────
+                    case 'create': {
+                        // Route through Quick Add Spec (POST /tickets/generate-spec) so an
+                        // MCP-created spec matches the app's "Add Spec → Quick" flow: the
+                        // specrails agent generates a structured spec (source 'propose-spec')
+                        // following the project's conventions, instead of a raw insert of
+                        // whatever the external LLM wrote. The user's request becomes the
+                        // `idea`. For a verbatim insert with no AI, use `from_prompt`.
+                        const idea = [args.title, args.description]
+                            .filter((v) => typeof v === 'string' && v.trim().length > 0)
+                            .join('\n\n')
+                            .trim();
+                        if (!idea)
+                            throw new Error('create requires a "title" and/or "description" to use as the spec idea.');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/generate-spec`, {
+                            idea,
+                            model: args.model,
+                            aiEngine: args.aiEngine,
+                            provider: args.provider,
+                            contractRefine: args.contractRefine,
+                        });
+                        return { ...r, hint: WATCH_HINT };
+                    }
+                    case 'update':
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/tickets/${requireId()}`, {
+                            title: args.title,
+                            description: args.description,
+                            status: args.status,
+                            priority: args.priority,
+                            labels: args.labels,
+                            assignee: args.assignee,
+                            prerequisites: args.prerequisites,
+                            metadata: args.metadata,
+                            acceptanceCriteria: args.acceptanceCriteria,
+                            short_summary: args.short_summary,
+                        });
+                    case 'from_prompt':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/from-prompt`, {
+                            description: args.description,
+                            title: args.title,
+                            labels: args.labels,
+                            priority: args.priority,
+                            structured: args.structured,
+                            pendingSpecId: args.pendingSpecId,
+                        });
+                    case 'save_draft': {
+                        if (!args.conversationId)
+                            throw new Error('save_draft requires a "conversationId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/save-as-draft`, {
+                            conversationId: args.conversationId,
+                            title: args.title,
+                            description: args.description,
+                            labels: args.labels,
+                            editTicketId: args.editTicketId,
+                        });
+                    }
+                    case 'commit_draft':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/from-draft`, {
+                            title: args.title,
+                            description: args.description,
+                            draftTicketId: args.draftTicketId,
+                            conversationId: args.conversationId,
+                            pendingSpecId: args.pendingSpecId,
+                            labels: args.labels,
+                            acceptanceCriteria: args.acceptanceCriteria,
+                            priority: args.priority,
+                            shortSummary: args.shortSummary,
+                            createLocal: args.createLocal,
+                        });
+                    case 'cancel_ai_edit': {
+                        if (!args.requestId)
+                            throw new Error('cancel_ai_edit requires a "requestId".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/tickets/${requireId()}/ai-edit?requestId=${encodeURIComponent(args.requestId)}`);
+                    }
+                    // ── destructive ────────────────────────────────────────────────
+                    case 'delete':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/tickets/${requireId()}`);
+                    case 'smash_undo': {
+                        if (!args.smashedAt)
+                            throw new Error('smash_undo requires the "smashedAt" timestamp.');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/smash/undo`, {
+                            smashedAt: args.smashedAt,
+                        });
+                    }
+                    case 'delete_epic_children':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/tickets/${requireId()}/children`);
+                    // ── ai-spawn (async 202 → WS) ──────────────────────────────────
+                    case 'generate': {
+                        if (!args.idea)
+                            throw new Error('generate requires an "idea".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/generate-spec`, {
+                            idea: args.idea,
+                            model: args.model,
+                            aiEngine: args.aiEngine,
+                            contextScope: args.contextScope,
+                            contractRefine: args.contractRefine,
+                            attachmentIds: args.attachmentIds,
+                            pendingSpecId: args.pendingSpecId,
+                            createLocal: args.createLocal,
+                        });
+                        return { ...r, hint: WATCH_HINT };
+                    }
+                    case 'ai_edit': {
+                        if (!args.instructions)
+                            throw new Error('ai_edit requires "instructions".');
+                        if (!args.description)
+                            throw new Error('ai_edit requires the current "description" baseline.');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/ai-edit`, {
+                            instructions: args.instructions,
+                            description: args.description,
+                            title: args.title,
+                            attachmentIds: args.attachmentIds,
+                            priorInstructions: args.priorInstructions,
+                            priorProposal: args.priorProposal,
+                        });
+                        return { ...r, hint: WATCH_HINT };
+                    }
+                    case 'contract_refine': {
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/contract-refine`);
+                        return { ...r, hint: WATCH_HINT };
+                    }
+                    case 'smash': {
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/smash`, {
+                            mode: args.mode,
+                            model: args.model,
+                        });
+                        return { ...r, hint: WATCH_HINT };
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiCall = apiCall;
+exports.projectPath = projectPath;
+exports.requireProject = requireProject;
+exports.setActiveProject = setActiveProject;
+exports.getActiveProject = getActiveProject;
+exports.registerTieredTool = registerTieredTool;
+const mcp_tiers_1 = require("../mcp-tiers");
+const auth_1 = require("../../auth");
+const agent_tier_1 = require("../../agent-tier");
+/**
+ * Calls the app's own REST API over loopback using the MASTER token (held
+ * server-side, never exposed to the MCP client). This reuses every router's
+ * existing logic/validation rather than re-implementing it in tools — the same
+ * loopback-forward pattern the Mobile Gateway uses for REST. `path` is appended
+ * after `/api` (e.g. `/projects/<id>/tickets`).
+ */
+async function apiCall(ctx, method, path, body) {
+    const url = `http://127.0.0.1:${ctx.desktopPort}/api${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${(0, auth_1.loadOrGenerateToken)()}`,
+            ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        data = text;
+    }
+    if (!res.ok) {
+        const detail = typeof data === 'object' && data !== null ? JSON.stringify(data) : String(data);
+        throw new Error(`API ${method} ${path} → ${res.status}: ${detail}`);
+    }
+    return data;
+}
+/** Convenience: build the `/projects/<id>` path prefix for a resolved project. */
+function projectPath(ctx, projectId) {
+    return `/projects/${requireProject(ctx, projectId).project.id}`;
+}
+/** Resolve a per-project context or throw a clear, LLM-readable error. */
+function requireProject(ctx, projectId) {
+    const id = projectId ?? getActiveProject(ctx);
+    if (!id) {
+        throw new Error('No project specified and no active project selected. Call specrails_select_project or pass projectId.');
+    }
+    const pc = ctx.registry.getContext(id);
+    if (!pc)
+        throw new Error(`Unknown projectId "${id}". Use specrails_projects(list) to see valid ids.`);
+    return pc;
+}
+// ── Active-project stickiness (per server process) ────────────────────────────
+// The active project is a soft default; an explicit projectId always wins.
+let _activeProjectId = null;
+function setActiveProject(id) {
+    _activeProjectId = id;
+}
+function getActiveProject(_ctx) {
+    return _activeProjectId;
+}
+function tierAnnotations(tier) {
+    switch (tier) {
+        case 'read':
+            return { readOnlyHint: true, openWorldHint: false };
+        case 'write':
+            return { readOnlyHint: false, openWorldHint: false };
+        case 'ai-spawn':
+            return { readOnlyHint: false, openWorldHint: true };
+        case 'destructive':
+            return { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+    }
+}
+function toResult(data) {
+    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    return { content: [{ type: 'text', text }] };
+}
+function errorResult(message) {
+    return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+}
+/**
+ * Broadcasts an app-level `mcp.activity` event after a successful mutating tool
+ * call so the UI can surface what an external LLM did — regardless of which
+ * project is currently active. Deliberately carries NO top-level `projectId`
+ * (so the client's per-project WS filter does not drop it); the affected project
+ * is in `affectedProjectId` for cache invalidation. Read-tier calls don't emit.
+ * A notify failure must never break the tool, so it's wrapped.
+ */
+function emitMcpActivity(ctx, spec, args, tier) {
+    try {
+        const affectedProjectId = (typeof args.projectId === 'string' ? args.projectId : null) ?? getActiveProject(ctx);
+        ctx.broadcast({
+            type: 'mcp.activity',
+            tool: spec.name,
+            action: typeof args.action === 'string' ? args.action : null,
+            tier,
+            affectedProjectId,
+            title: spec.title,
+            at: new Date().toISOString(),
+        });
+    }
+    catch {
+        /* a notification failure must never fail the tool */
+    }
+}
+/**
+ * Registers a tool on the McpServer, wrapping the handler with (1) tier
+ * enforcement and (2) uniform success/error result shaping. No tool can forget
+ * the tier check because it lives here, not in the handler.
+ */
+function registerTieredTool(server, ctx, spec) {
+    const hintTier = spec.hintTier ?? (typeof spec.tier === 'string' ? spec.tier : 'write');
+    server.registerTool(spec.name, {
+        title: spec.title,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+        annotations: tierAnnotations(hintTier),
+    }, async (args, extra) => {
+        // In-app agent: a per-request active-project header (loopback-only, set by
+        // the agent's bridge from the Cursor-style selector) pins the project for
+        // this call so project-scoped tools resolve without specrails_select_project.
+        const projectHeader = extra?.requestInfo?.headers?.[agent_tier_1.AGENT_PROJECT_HEADER];
+        if (projectHeader != null) {
+            const pid = Array.isArray(projectHeader) ? projectHeader[0] : projectHeader;
+            if (typeof pid === 'string' && pid.trim())
+                setActiveProject(pid.trim());
+        }
+        const tier = typeof spec.tier === 'function' ? spec.tier(args ?? {}) : spec.tier;
+        // In-app agent: when the request carries the loopback-only agent-tier header,
+        // enforce the cumulative ladder instead of the external Settings checkboxes
+        // (design D4). Absent header → external client → unchanged Settings gate.
+        const agentLevel = (0, agent_tier_1.levelFromHeader)(extra?.requestInfo?.headers?.[agent_tier_1.AGENT_TIER_HEADER]);
+        if (agentLevel !== null) {
+            if (!(0, agent_tier_1.levelAllowsTier)(agentLevel, tier)) {
+                return errorResult((0, mcp_tiers_1.tierRefusalMessage)(tier));
+            }
+        }
+        else if (!(0, mcp_tiers_1.isTierEnabled)(ctx.desktopDb, tier)) {
+            return errorResult((0, mcp_tiers_1.tierRefusalMessage)(tier));
+        }
+        try {
+            const data = await spec.handler(ctx, args ?? {});
+            if (tier !== 'read')
+                emitMcpActivity(ctx, spec, args ?? {}, tier);
+            return toResult(data);
+        }
+        catch (err) {
+            return errorResult(err instanceof Error ? err.message : String(err));
+        }
+    });
+}

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchTool = watchTool;
+const zod_1 = require("zod");
+// Event `type` suffixes/strings that mean an async operation has settled.
+const TERMINAL_PATTERNS = [
+    'job.finalized',
+    'rail.job_completed',
+    'rail.job_stopped',
+    'chat_done',
+    'chat_error',
+    'spec_gen_done',
+    'spec_gen_error',
+    'ticket_ai_edit_done',
+    'ticket_ai_edit_error',
+    'agent_refine_ready',
+    'agent_refine_error',
+    'smash.completed',
+    'smash.failed',
+    'loop.run_completed',
+    'loop.run_stopped',
+    'explore.contract_refine_failed',
+    'file.summary_updated',
+    'file.summary_failed',
+];
+function isTerminal(type) {
+    return TERMINAL_PATTERNS.some((p) => type === p || type.endsWith(p));
+}
+function mentionsRef(msg, ref) {
+    // Heuristic: the reference (jobId / requestId / loopRunId) appears somewhere
+    // in the message payload. Cheap and robust across the heterogeneous WS union.
+    try {
+        return JSON.stringify(msg).includes(ref);
+    }
+    catch {
+        return false;
+    }
+}
+function watchTool() {
+    return {
+        name: 'specrails_watch',
+        title: 'Watch async result',
+        description: 'Wait for an asynchronous operation (rail launch, spec generation, chat turn, agent refine, SMASH, loop run) to settle ' +
+            'and return its events. Pass the projectId and the reference (jobId / requestId) returned by the action. ' +
+            'Resolves when a terminal event for that reference is seen, or after untilMs.',
+        tier: 'read',
+        inputSchema: {
+            projectId: zod_1.z.string().describe('Project id the operation runs in'),
+            ref: zod_1.z.string().describe('jobId / requestId / loopRunId returned by the async action'),
+            untilMs: zod_1.z.number().int().min(1000).max(600000).default(120000).describe('Max time to wait (ms)'),
+        },
+        handler: (ctx, args) => {
+            const projectId = args.projectId;
+            const ref = args.ref;
+            const untilMs = args.untilMs ?? 120000;
+            return new Promise((resolve) => {
+                const events = [];
+                let done = false;
+                const finish = (settled, reason) => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    unsub();
+                    resolve({
+                        settled,
+                        reason,
+                        ref,
+                        projectId,
+                        eventCount: events.length,
+                        terminalEvent: settled ? events[events.length - 1] : null,
+                        events: events.slice(-50),
+                    });
+                };
+                const unsub = ctx.eventBus.onMessage((msg) => {
+                    const msgProjectId = msg.projectId;
+                    if (msgProjectId && msgProjectId !== projectId)
+                        return;
+                    if (!mentionsRef(msg, ref))
+                        return;
+                    events.push(msg);
+                    const type = msg.type ?? '';
+                    if (isTerminal(type))
+                        finish(true, `terminal:${type}`);
+                });
+                const timer = setTimeout(() => finish(false, 'timeout'), untilMs);
+                // Do not keep the event loop alive solely for this watch.
+                if (typeof timer.unref === 'function')
+                    timer.unref();
+            });
+        },
+    };
+}

package/server/dist/mobile/mobile-event-bus.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobileEventBus = void 0;
 exports.getMobileEventBus = getMobileEventBus;
 const events_1 = require("events");
 // In-process fan-out of every WS broadcast to the Mobile Gateway.
@@ -28,6 +29,7 @@ class MobileEventBus extends events_1.EventEmitter {
         return () => this.off('message', cb);
     }
 }
+exports.MobileEventBus = MobileEventBus;
 // EventEmitter defaults to 10 listeners; the gateway attaches one shared listener
 // that fans out to many sockets, so the default is plenty — but lift it anyway
 // to be safe against future multi-listener designs.

package/server/dist/project-router-setup.js

@@ -67,7 +67,21 @@ function registerSetupRoutes(deps) {
         const requested = (req.body ?? {});
         const provider = typeof requested.provider === 'string' ? requested.provider : undefined;
         res.status(202).json({ ok: true });
-        setupManager.startInstall(project.id, project.path, project.slug, provider);
+        // One-shot multi-provider install: an explicit `providers` list, or `all:true`
+        // to install every provider the project is registered with (used by the MCP/
+        // agent so a single `install` provisions them all). Else single-provider.
+        const explicit = Array.isArray(requested.providers)
+            ? requested.providers.filter((p) => typeof p === 'string')
+            : undefined;
+        if (explicit && explicit.length > 0) {
+            setupManager.startInstallProviders(project.id, project.path, project.slug, explicit);
+        }
+        else if (requested.all === true) {
+            setupManager.startInstallProviders(project.id, project.path, project.slug, project.providers);
+        }
+        else {
+            setupManager.startInstall(project.id, project.path, project.slug, provider);
+        }
     });
     router.post('/:projectId/enrich/start', (req, res) => {
         const { project, setupManager } = ctx(req);

package/server/dist/project-router-tickets.js

@@ -1322,8 +1322,8 @@ function registerTicketsRoutes(deps) {
                     short_summary: null,
                     created_at: now,
                     updated_at: now,
-                    created_by: 'hub', // legacy on-disk wire value (tickets.json, shared with specrails-core) — do not rename
-                    source: source === 'product-backlog' || source === 'propose-spec' || source === 'manual' ? source : 'hub', // legacy on-disk wire value — do not rename
+                    created_by: source === 'mcp' ? 'mcp' : 'hub', // 'hub' = legacy on-disk wire value (tickets.json, shared with specrails-core) — do not rename
+                    source: source === 'product-backlog' || source === 'propose-spec' || source === 'manual' || source === 'mcp' ? source : 'hub', // 'hub' legacy wire value — do not rename
                 };
                 s.tickets[String(id)] = ticket;
                 created = ticket;