specrails-desktop 2.16.0 → 2.18.0

package/server/dist/mcp/tools/app-settings.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appTools = appTools;
+const zod_1 = require("zod");
+const desktop_db_1 = require("../../desktop-db");
+const mcp_tiers_1 = require("../mcp-tiers");
+// App-level settings the MCP may read/write. NOTE: the MCP enable flag and the
+// permission-tier toggles are intentionally NOT writable here — an external LLM
+// must never be able to escalate its own permissions. Those are user-only,
+// changed in the Settings ▸ MCP panel.
+const WRITABLE_THEMES = ['specrails', 'dracula', 'aurora-light', 'obsidian-dark', 'matrix'];
+const WRITABLE_LANGS = ['en', 'es', 'fr', 'de', 'pt', 'it', 'zh', 'ja'];
+function appTools() {
+    return [
+        {
+            name: 'specrails_settings',
+            title: 'App settings',
+            description: 'Read or update app-level Specrails settings (theme, language, daily budget, cost-alert threshold). ' +
+                'Actions: get, set. The MCP enable flag and permission tiers are read-only here (user-controlled in the app).',
+            hintTier: 'read',
+            tier: (args) => (args.action === 'set' ? 'write' : 'read'),
+            inputSchema: {
+                action: zod_1.z.enum(['get', 'set']).describe('Operation'),
+                theme: zod_1.z.enum(WRITABLE_THEMES).optional(),
+                language: zod_1.z.enum(WRITABLE_LANGS).optional(),
+                dailyBudgetUsd: zod_1.z.number().min(0).nullable().optional(),
+                costAlertThresholdUsd: zod_1.z.number().min(0).nullable().optional(),
+            },
+            handler: (ctx, args) => {
+                const db = ctx.desktopDb;
+                if (args.action === 'get') {
+                    return {
+                        theme: (0, desktop_db_1.getDesktopSetting)(db, 'ui_theme') ?? 'specrails',
+                        language: (0, desktop_db_1.getDesktopSetting)(db, 'ui_language') ?? null,
+                        dailyBudgetUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'desktop_daily_budget_usd')),
+                        costAlertThresholdUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'cost_alert_threshold_usd')),
+                        mcp: {
+                            enabled: (0, mcp_tiers_1.isMcpEnabled)(db),
+                            tierWrite: (0, mcp_tiers_1.isTierEnabled)(db, 'write'),
+                            tierAiSpawn: (0, mcp_tiers_1.isTierEnabled)(db, 'ai-spawn'),
+                            tierDestructive: (0, mcp_tiers_1.isTierEnabled)(db, 'destructive'),
+                        },
+                    };
+                }
+                // set
+                const changed = [];
+                if (args.theme !== undefined) {
+                    (0, desktop_db_1.setDesktopSetting)(db, 'ui_theme', String(args.theme));
+                    changed.push('theme');
+                }
+                if (args.language !== undefined) {
+                    (0, desktop_db_1.setDesktopSetting)(db, 'ui_language', String(args.language));
+                    changed.push('language');
+                }
+                if (args.dailyBudgetUsd !== undefined) {
+                    writeNumOrClear(db, 'desktop_daily_budget_usd', args.dailyBudgetUsd);
+                    changed.push('dailyBudgetUsd');
+                }
+                if (args.costAlertThresholdUsd !== undefined) {
+                    writeNumOrClear(db, 'cost_alert_threshold_usd', args.costAlertThresholdUsd);
+                    changed.push('costAlertThresholdUsd');
+                }
+                if (!changed.length)
+                    throw new Error('set requires at least one field (theme, language, dailyBudgetUsd, costAlertThresholdUsd).');
+                return { ok: true, changed };
+            },
+        },
+    ];
+}
+function num(v) {
+    if (v === undefined)
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+function writeNumOrClear(db, key, value) {
+    if (value === null)
+        (0, desktop_db_1.setDesktopSetting)(db, key, '');
+    else
+        (0, desktop_db_1.setDesktopSetting)(db, key, String(value));
+}

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolSpecs = buildToolSpecs;
+const projects_1 = require("./projects");
+const app_settings_1 = require("./app-settings");
+const watch_1 = require("./watch");
+const meta_1 = require("./meta");
+const specs_1 = require("./specs");
+const rails_1 = require("./rails");
+const jobs_1 = require("./jobs");
+const chat_1 = require("./chat");
+const agents_1 = require("./agents");
+const plugins_1 = require("./plugins");
+const jira_1 = require("./jira");
+const loops_1 = require("./loops");
+const code_1 = require("./code");
+const setup_1 = require("./setup");
+const analytics_1 = require("./analytics");
+/**
+ * The full MCP tool catalog. Domain-facade tools each expose an `action` enum
+ * and call the app's REST API over loopback (see apiCall). Meta tools receive a
+ * lazy getter so `search`/`describe` can see the whole list.
+ */
+function buildToolSpecs() {
+    const specs = [];
+    // App-level + meta + watch
+    specs.push(...(0, projects_1.projectsTools)());
+    specs.push(...(0, app_settings_1.appTools)());
+    specs.push((0, watch_1.watchTool)());
+    // Per-project domains
+    specs.push(...(0, specs_1.specsTools)());
+    specs.push(...(0, rails_1.railsTools)());
+    specs.push(...(0, jobs_1.jobsTools)());
+    specs.push(...(0, chat_1.chatTools)());
+    specs.push(...(0, agents_1.agentsTools)());
+    specs.push(...(0, plugins_1.pluginsTools)());
+    specs.push(...(0, jira_1.jiraTools)());
+    specs.push(...(0, loops_1.loopsTools)());
+    specs.push(...(0, code_1.codeTools)());
+    specs.push(...(0, setup_1.setupTools)());
+    specs.push(...(0, analytics_1.analyticsTools)());
+    // Meta last (needs the full list for search/describe)
+    specs.push(...(0, meta_1.metaTools)(() => specs));
+    return specs;
+}

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

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chatTools = chatTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Chat / Explore conversations for a project. A domain-facade tool over the
+ * per-project chat routes in `server/project-router-chat.ts`. The agent-refine
+ * (AI-edit) routes under `/profiles/catalog/:agentId/refine` are intentionally
+ * NOT here — they belong to the agents domain.
+ *
+ * `send` is the only cost-incurring action: it 202-accepts and streams the
+ * assistant reply over WebSocket, so it returns a watch hint keyed on the
+ * conversation id.
+ */
+function chatTools() {
+    return [
+        {
+            name: 'specrails_chat',
+            title: 'Chat / Explore',
+            description: 'Manage a project\'s chat & Explore-Spec conversations and drive their AI turns. ' +
+                'Actions: list_conversations, get (conversation + messages), create (kind sidebar|explore, optional provider/model/contextScope), ' +
+                'send (cost-incurring — spawns the AI CLI and streams the reply async over WS), abort (interrupt the in-flight turn), ' +
+                'delete (destructive — removes the conversation, its messages, and clears linked draft origin), minimize (arm Explore idle-kill timer), ' +
+                'restore (cancel the idle-kill timer), spec_draft (read the in-memory Explore spec-draft state), messages (persisted history only).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'delete')
+                    return 'destructive';
+                if (action === 'send')
+                    return 'ai-spawn';
+                if (action === 'create' || action === 'update' || action === 'abort' || action === 'minimize' || action === 'restore')
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'list_conversations',
+                    'get',
+                    'create',
+                    'update',
+                    'send',
+                    'abort',
+                    'delete',
+                    'minimize',
+                    'restore',
+                    'spec_draft',
+                    'messages',
+                ])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                conversationId: zod_1.z.string().optional().describe('Conversation id (required for get/update/send/abort/delete/minimize/restore/spec_draft/messages)'),
+                // create params
+                kind: zod_1.z.enum(['sidebar', 'explore']).optional().describe('Conversation kind for create (default sidebar)'),
+                provider: zod_1.z.string().optional().describe('AI engine for create — must be installed on the project (alias of aiEngine); defaults to the primary provider'),
+                model: zod_1.z.string().optional().describe('Model for create/update — must be valid for the conversation\'s provider'),
+                contextScope: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('Explore-only context scope flags for create (mcp/userMcp/full/specrails/openspec/contractRefine)'),
+                // update params
+                title: zod_1.z.string().optional().describe('New title for update'),
+                // send params
+                text: zod_1.z.string().optional().describe('User message text for send (required)'),
+                lightweight: zod_1.z.boolean().optional().describe('Use the lightweight system prompt for send'),
+                maxTurns: zod_1.z.number().optional().describe('Max agent turns for send'),
+                attachments: zod_1.z
+                    .object({
+                    ticketKey: zod_1.z.string().describe('Ticket key the attachments belong to'),
+                    ids: zod_1.z.array(zod_1.z.string()).describe('Uploaded attachment ids'),
+                })
+                    .optional()
+                    .describe('Attachment references for send'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                const convId = args.conversationId;
+                const requireConv = () => {
+                    if (!convId)
+                        throw new Error(`Action "${action}" requires a "conversationId".`);
+                    return convId;
+                };
+                switch (action) {
+                    case 'list_conversations':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/chat/conversations`);
+                    case 'get':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/chat/conversations/${requireConv()}`);
+                    case 'messages':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/chat/conversations/${requireConv()}/messages`);
+                    case 'spec_draft':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/chat/conversations/${requireConv()}/spec-draft`);
+                    case 'create': {
+                        const body = {};
+                        if (args.kind !== undefined)
+                            body.kind = args.kind;
+                        if (args.provider !== undefined)
+                            body.aiEngine = args.provider;
+                        if (args.model !== undefined)
+                            body.model = args.model;
+                        if (args.contextScope !== undefined)
+                            body.contextScope = args.contextScope;
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/chat/conversations`, body);
+                    }
+                    case 'update': {
+                        const body = {};
+                        if (args.title !== undefined)
+                            body.title = args.title;
+                        if (args.model !== undefined)
+                            body.model = args.model;
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/chat/conversations/${requireConv()}`, body);
+                    }
+                    case 'send': {
+                        const text = args.text;
+                        if (!text || !text.trim())
+                            throw new Error('send requires non-empty "text".');
+                        const body = { text: text.trim() };
+                        if (args.lightweight !== undefined)
+                            body.lightweight = args.lightweight;
+                        if (args.maxTurns !== undefined)
+                            body.maxTurns = args.maxTurns;
+                        if (args.attachments !== undefined)
+                            body.attachments = args.attachments;
+                        const r = (await (0, types_1.apiCall)(ctx, 'POST', `${base}/chat/conversations/${requireConv()}/messages`, body));
+                        return {
+                            ...r,
+                            conversationId: requireConv(),
+                            hint: `Turn accepted (202). The assistant reply streams over WebSocket — use specrails_watch with conversationId "${requireConv()}" to await completion (chat_done / chat_error).`,
+                        };
+                    }
+                    case 'abort':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/chat/conversations/${requireConv()}/messages/stream`);
+                    case 'delete':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/chat/conversations/${requireConv()}`);
+                    case 'minimize':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/chat/conversations/${requireConv()}/minimize`);
+                    case 'restore':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/chat/conversations/${requireConv()}/restore`);
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codeTools = codeTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Read-only Code Explorer surface for a project: the AI-touched file tree,
+ * file contents + plain-language AI summaries, "touched by AI" provenance, and
+ * stored per-file diffs — plus the one cost-incurring action, regenerating a
+ * file's AI summary (async, fire-and-forget over WS).
+ *
+ * Every op is per-project under `/api/projects/:projectId/code/*`. The v1 edit
+ * path (PUT /code/file) is intentionally NOT exposed — Code Explorer is
+ * read-only here. The app-level GET/PATCH /api/code-explorer-settings ops are
+ * app-scoped settings, surfaced by the settings domain, not here.
+ *
+ * Encode query strings explicitly so file paths with spaces/`#`/`?` survive.
+ */
+function codeTools() {
+    return [
+        {
+            name: 'specrails_code',
+            title: 'Code Explorer',
+            description: 'Read-only browse a project\'s source through the Code Explorer: list the file tree ' +
+                '(default scoped to AI-touched files, optional provenance rollup), read a file with its ' +
+                'AI summary + staleness + provenance, fetch a stored summary alone, regenerate a file\'s ' +
+                'AI summary (cost-incurring, async), list "touched by AI" provenance rows, and fetch the ' +
+                'stored unified-diff a job applied to a file. ' +
+                'Actions: tree, read_file, summary, regenerate_summary (ai-spawn — spawns an AI CLI, ' +
+                'incurs cost, returns 202 then completes over WS), provenance, diff. ' +
+                'Requires SPECRAILS_CODE_EXPLORER (default on); the /code prefix 404s when disabled.',
+            hintTier: 'read',
+            tier: (a) => (a.action === 'regenerate_summary' ? 'ai-spawn' : 'read'),
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['tree', 'read_file', 'summary', 'regenerate_summary', 'provenance', 'diff'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                path: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Project-relative file path. Required for read_file/summary/regenerate_summary/diff; ' +
+                    'optional narrowing filter for provenance.'),
+                filter: zod_1.z
+                    .enum(['touched-by-ai', 'all'])
+                    .optional()
+                    .describe('tree only: scope to AI-touched files (default) or the whole repo'),
+                withProvenance: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('tree only: include per-file/dir provenance rollup (created-by / modified-by chips)'),
+                cursor: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('tree only: opaque pagination cursor from a prior response\'s nextCursor'),
+                ticketId: zod_1.z
+                    .number()
+                    .int()
+                    .positive()
+                    .optional()
+                    .describe('tree/provenance: narrow to files touched by this ticket'),
+                jobId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('tree/provenance/diff: narrow to a job; required for diff'),
+                overrideBudget: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('regenerate_summary only: bypass the monthly summary budget cap. Privileged — ' +
+                    'incurs cost beyond the configured limit.'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                const requirePath = () => {
+                    const p = args.path;
+                    if (!p || p.trim() === '')
+                        throw new Error(`Action "${action}" requires a "path".`);
+                    return p;
+                };
+                switch (action) {
+                    case 'tree': {
+                        const qs = new URLSearchParams();
+                        if (args.filter)
+                            qs.set('filter', args.filter);
+                        if (args.withProvenance === true)
+                            qs.set('withProvenance', '1');
+                        if (args.cursor)
+                            qs.set('cursor', args.cursor);
+                        if (typeof args.ticketId === 'number')
+                            qs.set('ticketId', String(args.ticketId));
+                        if (args.jobId)
+                            qs.set('jobId', args.jobId);
+                        const suffix = qs.toString() ? `?${qs.toString()}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/tree${suffix}`);
+                    }
+                    case 'read_file': {
+                        const qs = new URLSearchParams({ path: requirePath() });
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/file?${qs.toString()}`);
+                    }
+                    case 'summary': {
+                        const qs = new URLSearchParams({ path: requirePath() });
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/summary?${qs.toString()}`);
+                    }
+                    case 'regenerate_summary': {
+                        const qs = new URLSearchParams({ path: requirePath() });
+                        const r = (await (0, types_1.apiCall)(ctx, 'POST', `${base}/code/file/regenerate-summary?${qs.toString()}`, { overrideBudget: args.overrideBudget === true }));
+                        // 202 → enqueued; 200 → { skipped: '...' }. Either way the real
+                        // outcome (summary ready / failed / skipped) arrives over WS, not in
+                        // this response, so always point the caller at the live channel.
+                        return {
+                            ...r,
+                            hint: 'Summary generation is async and cost-incurring. The outcome arrives over the ' +
+                                'WS channel as file.summary_updated / file.summary_failed / file.summary_skipped ' +
+                                "(reason: 'budget'|'per-job-cap'|'ttl'|'not-found'), NOT in this response. A 202 " +
+                                '{ enqueued: true } only means it was queued; a 200 { skipped } means it never ran.',
+                        };
+                    }
+                    case 'provenance': {
+                        const qs = new URLSearchParams();
+                        if (typeof args.ticketId === 'number')
+                            qs.set('ticketId', String(args.ticketId));
+                        if (args.jobId)
+                            qs.set('jobId', args.jobId);
+                        if (args.path)
+                            qs.set('path', args.path);
+                        if (![...qs.keys()].length) {
+                            throw new Error('Action "provenance" requires at least one of: ticketId, jobId, path.');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/provenance?${qs.toString()}`);
+                    }
+                    case 'diff': {
+                        const jobId = args.jobId;
+                        if (!jobId)
+                            throw new Error('Action "diff" requires a "jobId".');
+                        const qs = new URLSearchParams({ jobId, path: requirePath() });
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/code/diff?${qs.toString()}`);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jiraTools = jiraTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Per-project Jira integration facade. Maps each action to the corresponding
+ * `/api/projects/:projectId/jira/*` route (server/jira-router.ts). Every op is
+ * project-scoped and external-network-bound (live HTTPS to the customer's Jira
+ * Cloud / Data Center instance with their stored or supplied credentials).
+ *
+ * SECURITY: the Jira API token / PAT is a high-value SECRET. It is passed as a
+ * plaintext `token` field on test / discover_projects / discover_statuses /
+ * connect; never log or echo it, and it is never returned on reads (GET
+ * /connection redacts it to `hasToken`).
+ *
+ * ID SCOPING: spec_details / discard_spec take the LOCAL monotonic ticket id
+ * (NOT a Jira `PROJ-123` key); retry_outbox takes the LOCAL outbox row id. Map
+ * Jira keys → local ids via the `links` action first.
+ */
+function jiraTools() {
+    return [
+        {
+            name: 'specrails_jira',
+            title: 'Jira integration',
+            description: 'Manage a project\'s Jira-backed specs (each project syncs with its own Jira board). Read connection/links/outbox, run the connect wizard, sync, and create/discard Jira-backed specs. ' +
+                'Actions: connection (get current connection, token redacted), test (validate creds), discover_projects, discover_statuses (with throwaway creds), connect (persist connection — write), update_connection (enable/disable hot-swap + statusMap/discardStatus — write), disconnect (remove connection + restore local write access — destructive), statuses (connected project\'s real statuses), sync (full re-fetch of the board — write, long-running on big boards), resume (drain parked outbox after re-auth — write), outbox (list ops + counts), retry_outbox (re-queue a dead-lettered op — write), create_spec (create a real Jira issue — write), discard_spec (move linked issue to discard status — write), spec_details (read-only Jira fields + dev panel), links (spec↔issue link map). ' +
+                'The `token` param is a SECRET (Jira API token / PAT) — only required for test/discover_projects/discover_statuses/connect; it is never returned on reads.',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'disconnect')
+                    return 'destructive';
+                if ([
+                    'connect',
+                    'update_connection',
+                    'sync',
+                    'resume',
+                    'retry_outbox',
+                    'create_spec',
+                    'discard_spec',
+                ].includes(action)) {
+                    return 'write';
+                }
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'connection',
+                    'test',
+                    'discover_projects',
+                    'discover_statuses',
+                    'connect',
+                    'update_connection',
+                    'disconnect',
+                    'statuses',
+                    'sync',
+                    'resume',
+                    'outbox',
+                    'retry_outbox',
+                    'create_spec',
+                    'discard_spec',
+                    'spec_details',
+                    'links',
+                ])
+                    .describe('Jira operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // Credential / probe fields (test, discover_projects, discover_statuses, connect)
+                baseUrl: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira base URL, e.g. https://acme.atlassian.net (test / discover_* / connect)'),
+                accountEmail: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira account email — required for Cloud Basic auth (test / discover_* / connect)'),
+                token: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('SECRET: Jira API token (Cloud) or PAT (Data Center). Required for test / discover_projects / discover_statuses / connect. Never returned on reads.'),
+                query: zod_1.z.string().optional().describe('Optional name filter for discover_projects'),
+                projectKey: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira project key to inspect statuses for (discover_statuses)'),
+                jiraProjectKey: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira project key to connect this project to (connect)'),
+                statusMap: zod_1.z
+                    .record(zod_1.z.string(), zod_1.z.string())
+                    .optional()
+                    .describe('Optional map of logical states (todo / in_progress / done / cancelled) → Jira status name (connect / update_connection)'),
+                discardStatus: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira status name the discard action moves an issue to; empty string clears it (connect / update_connection)'),
+                // update_connection
+                enabled: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Hot-swap toggle: true re-arms Jira write-back (read-only local backlog), false restores local write access (update_connection)'),
+                // create_spec
+                title: zod_1.z.string().optional().describe('Issue summary/title (create_spec)'),
+                description: zod_1.z.string().optional().describe('Issue description (create_spec)'),
+                labels: zod_1.z.array(zod_1.z.string()).optional().describe('Issue labels (create_spec)'),
+                priority: zod_1.z.string().optional().describe('Jira priority name (create_spec)'),
+                issueType: zod_1.z.string().optional().describe('Jira issue type; defaults to Task (create_spec)'),
+                // discard_spec / spec_details
+                localId: zod_1.z
+                    .number()
+                    .optional()
+                    .describe('LOCAL monotonic ticket id (discard_spec / spec_details) — NOT a Jira key; map via the links action'),
+                comment: zod_1.z.string().optional().describe('Optional reason comment posted on discard (discard_spec)'),
+                // retry_outbox
+                opId: zod_1.z
+                    .number()
+                    .optional()
+                    .describe('LOCAL outbox row id of a dead-lettered op to re-queue (retry_outbox)'),
+                // outbox
+                state: zod_1.z
+                    .enum(['pending', 'inflight', 'done', 'dead'])
+                    .optional()
+                    .describe('Filter outbox ops by state (outbox); omit for all'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/jira`;
+                const action = args.action;
+                switch (action) {
+                    case 'connection':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/connection`);
+                    case 'test':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/test`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                        });
+                    case 'discover_projects':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/discover-projects`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                            query: args.query,
+                        });
+                    case 'discover_statuses':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/discover-statuses`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                            projectKey: args.projectKey,
+                        });
+                    case 'connect':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/connect`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                            jiraProjectKey: args.jiraProjectKey,
+                            statusMap: args.statusMap,
+                            discardStatus: args.discardStatus,
+                        });
+                    case 'update_connection':
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/connection`, {
+                            enabled: args.enabled,
+                            discardStatus: args.discardStatus,
+                            statusMap: args.statusMap,
+                        });
+                    case 'disconnect':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/connection`);
+                    case 'statuses':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/statuses`);
+                    case 'sync':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/sync`);
+                    case 'resume':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/resume`);
+                    case 'outbox': {
+                        const state = args.state;
+                        const qs = state ? `?state=${encodeURIComponent(state)}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/outbox${qs}`);
+                    }
+                    case 'retry_outbox': {
+                        const opId = args.opId;
+                        if (opId === undefined)
+                            throw new Error('retry_outbox requires an "opId" (local outbox row id).');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/outbox/${opId}/retry`);
+                    }
+                    case 'create_spec':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/specs`, {
+                            title: args.title,
+                            description: args.description,
+                            labels: args.labels,
+                            priority: args.priority,
+                            issueType: args.issueType,
+                        });
+                    case 'discard_spec': {
+                        const localId = args.localId;
+                        if (localId === undefined)
+                            throw new Error('discard_spec requires a "localId" (local ticket id).');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/specs/${localId}/discard`, {
+                            comment: args.comment,
+                        });
+                        // 202 accepted: the transition + optional comment drain asynchronously.
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Discard enqueued (202). Use action "outbox" to watch the transition/comment ops drain, or "connection" for live outbox counts.',
+                        };
+                    }
+                    case 'spec_details': {
+                        const localId = args.localId;
+                        if (localId === undefined)
+                            throw new Error('spec_details requires a "localId" (local ticket id).');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/specs/${localId}/details`);
+                    }
+                    case 'links':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/links`);
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}