specrails-desktop 2.16.0 → 2.17.0

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

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyticsTools = analyticsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Build a `?a=b&c=d` query string from a flat record, skipping undefined/null/''
+ * values. Arrays are joined with commas (the spending router parses CSV for
+ * surface/model/modelProvider/provider). Used by the read actions below.
+ */
+function buildQuery(params) {
+    const parts = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        const value = Array.isArray(v) ? v.join(',') : String(v);
+        if (value === '')
+            continue;
+        parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(value)}`);
+    }
+    return parts.length ? `?${parts.join('&')}` : '';
+}
+function analyticsTools() {
+    return [
+        {
+            name: 'specrails_analytics',
+            title: 'Analytics & Spending',
+            description: 'Per-project cost analytics over billable AI-CLI invocations (jobs, quick-spec, explore-spec, ai-edit, smash, file-summary, loop). ' +
+                'All read-only except set_budget. Actions: ' +
+                'spending (full dashboard: cost summary with prev-period delta, by-surface/model/mode/provider breakdowns, daily timeline, cost-vs-turns scatter, top tickets), ' +
+                'invocations (paginated raw invocation table), ' +
+                'ticket_summary (per-ticket cost aggregate across all surfaces), ' +
+                'export (download summary/raw analytics as CSV or JSON — file download, returns a note + headers), ' +
+                'budget_get (daily budget, per-job threshold, cost-today, utilization %), ' +
+                'budget_set (write — set/clear daily budget cap + per-job cost threshold; a too-low budget pauses the job queue). ' +
+                'Prefer spending over invocations/export-raw for token economy. ' +
+                'Filters: period(7d|30d|90d|all|custom), from/to (ISO, required for custom), surface[], model[], modelProvider[] (index-aligned to model), provider[], status(success|failed|aborted), minCostUsd, ticketId, tzOffsetMinutes(±840 — pass the user local offset so "today" lines up), sortBy.',
+            hintTier: 'read',
+            tier: (a) => (a.action === 'budget_set' ? 'write' : 'read'),
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['spending', 'invocations', 'ticket_summary', 'export', 'budget_get', 'budget_set'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // ─── Filters shared by spending / invocations / export ────────────────
+                period: zod_1.z
+                    .enum(['7d', '30d', '90d', 'all', 'custom'])
+                    .optional()
+                    .describe('Time window (default 30d). "custom" requires from + to.'),
+                from: zod_1.z.string().optional().describe('ISO start date (required when period=custom)'),
+                to: zod_1.z.string().optional().describe('ISO end date (required when period=custom)'),
+                surface: zod_1.z
+                    .array(zod_1.z.enum(['job', 'quick-spec', 'explore-spec', 'ai-edit', 'smash', 'file-summary', 'loop']))
+                    .optional()
+                    .describe('Filter to these surfaces (CSV)'),
+                model: zod_1.z.array(zod_1.z.string()).optional().describe('Filter to these model ids (CSV)'),
+                modelProvider: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Providers index-aligned to model[] (scopes each model id to its provider so codex/gemini estimated cost does not merge into a claude bar)'),
+                provider: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Filter to these providers (e.g. claude, codex, gemini) (CSV)'),
+                status: zod_1.z.enum(['success', 'failed', 'aborted']).optional().describe('Filter by invocation status'),
+                minCostUsd: zod_1.z.number().optional().describe('Only invocations costing at least this many USD'),
+                ticketId: zod_1.z.number().int().optional().describe('Scope to a single ticket id'),
+                tzOffsetMinutes: zod_1.z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Local UTC offset in minutes (±840) for daily-timeline calendar-day bucketing (default 0 = UTC)'),
+                sortBy: zod_1.z.enum(['recency', 'cost']).optional().describe('Sort order'),
+                // ─── invocations pagination ───────────────────────────────────────────
+                limit: zod_1.z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('invocations: max rows (clamped server-side to [1, 10000])'),
+                offset: zod_1.z.number().int().optional().describe('invocations: row offset for pagination'),
+                // ─── ticket_summary ───────────────────────────────────────────────────
+                id: zod_1.z.number().int().optional().describe('ticket_summary: the ticket id to aggregate'),
+                // ─── export ───────────────────────────────────────────────────────────
+                format: zod_1.z.enum(['csv', 'json']).optional().describe('export: output format (default json)'),
+                mode: zod_1.z
+                    .enum(['summary', 'raw'])
+                    .optional()
+                    .describe('export: summary (aggregated dashboard) or raw (up to 10000 invocation rows). Default summary.'),
+                // ─── budget_set ───────────────────────────────────────────────────────
+                dailyBudgetUsd: zod_1.z
+                    .number()
+                    .nullable()
+                    .optional()
+                    .describe('budget_set: daily budget cap USD (>0); null clears it'),
+                jobCostThresholdUsd: zod_1.z
+                    .number()
+                    .nullable()
+                    .optional()
+                    .describe('budget_set: per-job cost alert threshold USD (>0); null clears it'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                const filters = {
+                    period: args.period,
+                    from: args.from,
+                    to: args.to,
+                    surface: args.surface,
+                    model: args.model,
+                    modelProvider: args.modelProvider,
+                    provider: args.provider,
+                    status: args.status,
+                    minCostUsd: args.minCostUsd,
+                    ticketId: args.ticketId,
+                    tzOffsetMinutes: args.tzOffsetMinutes,
+                    sortBy: args.sortBy,
+                };
+                switch (action) {
+                    case 'spending':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/spending${buildQuery(filters)}`);
+                    case 'invocations':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/invocations${buildQuery({
+                            ...filters,
+                            limit: args.limit,
+                            offset: args.offset,
+                        })}`);
+                    case 'ticket_summary': {
+                        const id = args.id;
+                        if (id === undefined || id === null) {
+                            throw new Error('ticket_summary requires an "id" (ticket id).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${id}/spending-summary`);
+                    }
+                    case 'export': {
+                        // GET /analytics/export streams a file download (Content-Disposition).
+                        // apiCall returns the body text/JSON; for CSV it is the raw CSV string,
+                        // for JSON the parsed dashboard/invocations object. We surface it
+                        // inline with a note since there is no file sink over MCP.
+                        const format = args.format ?? 'json';
+                        const mode = args.mode ?? 'summary';
+                        const data = await (0, types_1.apiCall)(ctx, 'GET', `${base}/analytics/export${buildQuery({ ...filters, format, mode })}`);
+                        return {
+                            note: `Analytics export (mode=${mode}, format=${format}). This endpoint is normally a file download; the content is returned inline below. Raw mode caps at 10000 rows. Prefer the "spending" action for already-aggregated, bounded data.`,
+                            format,
+                            mode,
+                            data,
+                        };
+                    }
+                    case 'budget_get':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/budget`);
+                    case 'budget_set': {
+                        const body = {};
+                        if ('dailyBudgetUsd' in args)
+                            body.dailyBudgetUsd = args.dailyBudgetUsd;
+                        if ('jobCostThresholdUsd' in args)
+                            body.jobCostThresholdUsd = args.jobCostThresholdUsd;
+                        if (Object.keys(body).length === 0) {
+                            throw new Error('budget_set requires dailyBudgetUsd and/or jobCostThresholdUsd (number>0 to set, null to clear).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/budget`, body);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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}".`);
+                }
+            },
+        },
+    ];
+}