specrails-desktop 2.16.0 → 2.17.0

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

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupTools = setupTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * The setup-wizard domain facade. Mixes APP-LEVEL operations (prerequisites,
+ * available_providers, add_project — mounted at `/api` with NO `:projectId`)
+ * with PER-PROJECT operations (install-config, install, checkpoints, abort,
+ * integration-contract, enrich — under `/api/projects/:projectId/*`).
+ *
+ * LIFECYCLE the caller must respect:
+ *   1. prerequisites → must be ok before adding a project
+ *   2. add_project   → creates the ProjectContext + slug + registry mirror + workspace
+ *   3. install_config (one POST per provider for multi-provider projects)
+ *   4. install        → 202 async; the real result arrives only via WS / checkpoints
+ *   5. poll checkpoints (or stream WS) until isInstalling === false
+ *   6. optional enrich / enrich_message for the legacy full AI flow
+ *
+ * The async actions (install, enrich, enrich_message) return immediately (HTTP
+ * 202) and do the real, long-running work in a detached child whose only output
+ * channel is WebSocket — so they return a hint to poll `checkpoints` (which also
+ * exposes isInstalling/isEnriching/logLines/summary) for true completion.
+ */
+function setupTools() {
+    return [
+        {
+            name: 'specrails_setup',
+            title: 'Setup & Project Provisioning',
+            description: 'Add and provision Specrails projects via the setup wizard, and inspect setup prerequisites/providers. ' +
+                'App-level actions ignore projectId: prerequisites (probe node/npm/npx/git + provider CLIs), ' +
+                'available_providers (which AI CLIs are detected + install tiers), add_project (register a repo path). ' +
+                'Per-project actions: install_config (persist install-config.yaml), install (spawn offline framework scaffold — async/202), ' +
+                'checkpoints (poll live setup/install/enrich state — the canonical completion signal when not streaming WS), ' +
+                'abort (SIGTERM/SIGKILL the in-progress install+enrich child), integration_contract (read the ticket-provider contract), ' +
+                'enrich (spawn the legacy full AI flow — async/202, COST-INCURRING), enrich_message (resume an enrich session with a reply — async, COST-INCURRING).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'abort')
+                    return 'destructive';
+                if (action === 'install' || action === 'enrich' || action === 'enrich_message')
+                    return 'ai-spawn';
+                if (action === 'add_project' || action === 'install_config')
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'prerequisites',
+                    'available_providers',
+                    'add_project',
+                    'install_config',
+                    'install',
+                    'checkpoints',
+                    'abort',
+                    'integration_contract',
+                    'enrich',
+                    'enrich_message',
+                ])
+                    .describe('Setup operation to perform'),
+                projectId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Project id for per-project actions (install_config/install/checkpoints/abort/integration_contract/enrich/enrich_message). Ignored by app-level actions.'),
+                // prerequisites
+                diagnostic: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('prerequisites: when true, include the resolved PATH segments/sources + per-tool which results'),
+                // add_project
+                path: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('add_project: filesystem path of the repo to register (required for add_project)'),
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('add_project: display name (defaults to the directory basename)'),
+                provider: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('add_project: legacy single primary provider; install/enrich: which per-provider install-config to read'),
+                providers: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('add_project: providers to install (first = primary/default); de-duped server-side'),
+                // install_config
+                config: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('install_config: the install-config object to serialize (e.g. { tier:"quick", provider, agents }); required for install_config'),
+                // enrich_message
+                sessionId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('enrich_message: the enrich session id to resume (required for enrich_message)'),
+                message: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('enrich_message: the user reply to send into the enrich session (required for enrich_message)'),
+            },
+            async handler(ctx, args) {
+                const action = args.action;
+                switch (action) {
+                    // ─── App-level (no projectId) ───────────────────────────────────────
+                    case 'prerequisites': {
+                        const qs = args.diagnostic === true ? '?diagnostic=1' : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `/setup-prerequisites${qs}`);
+                    }
+                    case 'available_providers':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/available-providers');
+                    case 'add_project': {
+                        const path = args.path;
+                        if (!path)
+                            throw new Error('add_project requires a "path".');
+                        const body = { path };
+                        if (typeof args.name === 'string')
+                            body.name = args.name;
+                        if (typeof args.provider === 'string')
+                            body.provider = args.provider;
+                        if (Array.isArray(args.providers))
+                            body.providers = args.providers;
+                        return (0, types_1.apiCall)(ctx, 'POST', '/projects', body);
+                    }
+                    // ─── Per-project ────────────────────────────────────────────────────
+                    case 'install_config': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        const config = args.config;
+                        if (config === undefined || typeof config !== 'object' || Array.isArray(config)) {
+                            throw new Error('install_config requires a "config" object.');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/setup/install-config`, config);
+                    }
+                    case 'install': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        const body = {};
+                        if (typeof args.provider === 'string')
+                            body.provider = args.provider;
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/setup/install`, body);
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Install is async (HTTP 202). Poll specrails_setup(checkpoints) until isInstalling === false (and watch summary for the result), or stream the setup_install_done / setup_error WS events.',
+                        };
+                    }
+                    case 'checkpoints': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/setup/checkpoints`);
+                    }
+                    case 'abort': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/setup/abort`, {});
+                    }
+                    case 'integration_contract': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/integration-contract`);
+                    }
+                    case 'enrich': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/enrich/start`, {});
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Enrich is async (HTTP 202) and COST-INCURRING. Poll specrails_setup(checkpoints) until isEnriching === false, or stream the setup_complete / setup_turn_done / setup_error WS events. Use enrich_message to answer clarifying questions.',
+                        };
+                    }
+                    case 'enrich_message': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        const sessionId = args.sessionId;
+                        const message = args.message;
+                        if (!sessionId)
+                            throw new Error('enrich_message requires a "sessionId".');
+                        if (!message || !message.trim())
+                            throw new Error('enrich_message requires a non-empty "message".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/enrich/message`, { sessionId, message });
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Enrich-message is async (HTTP 202) and COST-INCURRING. Poll specrails_setup(checkpoints) until isEnriching === false, or stream the setup_turn_done / setup_error WS events.',
+                        };
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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,137 @@
+"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");
+/**
+ * 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) => {
+        const tier = typeof spec.tier === 'function' ? spec.tier(args ?? {}) : spec.tier;
+        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));
+        }
+    });
+}