specrails-desktop 2.16.0 → 2.18.0

package/server/dist/mcp/mcp-token.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadOrGenerateMcpToken = loadOrGenerateMcpToken;
+exports.getMcpToken = getMcpToken;
+exports.regenerateMcpToken = regenerateMcpToken;
+exports.requireMcpAuth = requireMcpAuth;
+exports._resetMcpTokenForTest = _resetMcpTokenForTest;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const crypto_1 = require("crypto");
+const auth_1 = require("../auth");
+// ─── MCP-scoped token (design D3) ─────────────────────────────────────────────
+//
+// The MCP surface is authenticated by a token SEPARATE from the all-powerful
+// master token (`~/.specrails/desktop.token`). The master token grants shell
+// (terminals), arbitrary AI-CLI spawns and project admin; handing it to a
+// third-party MCP client would be a security smell. Instead the MCP server
+// mints its own scoped token at `~/.specrails/mcp.token` (0600). The stdio
+// bridge reads it locally so it never appears in client config; the direct
+// streamable-HTTP path requires it as `Authorization: Bearer <token>`.
+//
+// This module mirrors the shape of `server/auth.ts` (loadOrGenerateToken /
+// safeEqual / requireAuth) for the scoped token. There is intentionally NO
+// legacy-file migration — this is a greenfield credential.
+// Honour the shared test-home override (SPECRAILS_REGISTRY_HOME) so tests never
+// touch the real ~/.specrails/mcp.token; falls back to os.homedir() in prod.
+function homeDir() {
+    return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+}
+function tokenDir() {
+    return path_1.default.join(homeDir(), '.specrails');
+}
+function tokenPath() {
+    return path_1.default.join(tokenDir(), 'mcp.token');
+}
+let _mcpToken = null;
+function generateToken() {
+    return (0, crypto_1.randomUUID)().replace(/-/g, '') + (0, crypto_1.randomUUID)().replace(/-/g, '');
+}
+/**
+ * Loads the persisted MCP token, or generates and persists a fresh one.
+ * Cached for the lifetime of the process.
+ */
+function loadOrGenerateMcpToken() {
+    if (_mcpToken)
+        return _mcpToken;
+    try {
+        if (fs_1.default.existsSync(tokenPath())) {
+            const t = fs_1.default.readFileSync(tokenPath(), 'utf-8').trim();
+            if (t && t.length >= 32) {
+                _mcpToken = t;
+                return _mcpToken;
+            }
+        }
+    }
+    catch {
+        // Fall through to generate a new token.
+    }
+    _mcpToken = generateToken();
+    persist(_mcpToken);
+    return _mcpToken;
+}
+function persist(token) {
+    try {
+        fs_1.default.mkdirSync(tokenDir(), { recursive: true });
+        fs_1.default.writeFileSync(tokenPath(), token, { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch (err) {
+        console.warn('[mcp] could not persist mcp token to disk:', err);
+    }
+}
+/** Returns the current MCP token (generating + persisting one if needed). */
+function getMcpToken() {
+    return loadOrGenerateMcpToken();
+}
+/**
+ * Overwrites the MCP token with a fresh value (invalidating any previously
+ * issued token) and returns the new value. Used by the Settings "regenerate"
+ * action.
+ */
+function regenerateMcpToken() {
+    const next = generateToken();
+    _mcpToken = next;
+    persist(next);
+    return next;
+}
+/** Extracts a bearer token from `Authorization: Bearer <t>` or `X-Desktop-Token`. */
+function extractToken(req) {
+    const auth = req.headers['authorization'];
+    if (typeof auth === 'string' && auth.startsWith('Bearer ')) {
+        return auth.slice(7).trim();
+    }
+    const xToken = req.headers['x-desktop-token'];
+    if (typeof xToken === 'string' && xToken.trim())
+        return xToken.trim();
+    return null;
+}
+/**
+ * Express middleware gating the MCP transport: requires the MCP-scoped token
+ * (constant-time compared). Mirrors `requireAuth` from auth.ts but checks the
+ * MCP token, never the master token.
+ */
+function requireMcpAuth(req, res, next) {
+    const provided = extractToken(req);
+    if (provided && (0, auth_1.safeEqual)(provided, getMcpToken())) {
+        next();
+        return;
+    }
+    // JSON-RPC-shaped error so MCP clients can parse it.
+    res.status(401).json({ jsonrpc: '2.0', error: { code: -32001, message: 'Unauthorized: invalid MCP token' }, id: null });
+}
+/** Test seam: clears the cached token so a test can point HOME elsewhere. */
+function _resetMcpTokenForTest() {
+    _mcpToken = null;
+}

package/server/dist/mcp/resources.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerResources = registerResources;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const guide_1 = require("./guide");
+const projects_1 = require("./tools/projects");
+// Read-only state exposed as MCP resources. Read-tier only (resources are never
+// mutating). Per-project resource templates (tickets, rails, analytics) are
+// added in subsequent phases.
+function registerResources(server, ctx) {
+    server.registerResource('guide', 'specrails://guide', { title: 'Specrails platform guide', description: 'Concepts, workflow and invariants for operating Specrails.', mimeType: 'text/markdown' }, async (uri) => ({
+        contents: [{ uri: uri.href, text: guide_1.SPECRAILS_GUIDE }],
+    }));
+    server.registerResource('projects', 'specrails://projects', { title: 'Projects', description: 'All registered Specrails projects.', mimeType: 'application/json' }, async (uri) => ({
+        contents: [{ uri: uri.href, text: JSON.stringify(ctx.registry.listContexts().map((c) => (0, projects_1.serializeProject)(c.project)), null, 2) }],
+    }));
+    server.registerResource('project', new mcp_js_1.ResourceTemplate('specrails://projects/{projectId}', { list: undefined }), { title: 'Project', description: 'A single project by id.', mimeType: 'application/json' }, async (uri, variables) => {
+        const projectId = String(variables.projectId);
+        const pc = ctx.registry.getContext(projectId);
+        if (!pc)
+            throw new Error(`Unknown projectId "${projectId}".`);
+        return { contents: [{ uri: uri.href, text: JSON.stringify((0, projects_1.serializeProject)(pc.project), null, 2) }] };
+    });
+}

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

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsTools = agentsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Agents domain — agent PROFILES (declarative per-project routing config) and
+ * the agents CATALOG (the `.claude/agents/*.md` definitions: read-only `sr-*`
+ * upstream agents + user-authored `custom-*` agents, with AI generate/test/
+ * iterative-refine on the custom ones).
+ *
+ * CLAUDE-ONLY: agent profiles are a Claude concept. On a project whose primary
+ * provider (or any installed provider) is codex/gemini, rails force-null the
+ * profile and the whole section is hidden client-side — creating profiles for a
+ * non-Claude project is mostly inert. The server still validates against that
+ * provider's adapter catalog. Prefer using this tool on Claude projects.
+ *
+ * Every operation is per-project (mounted at /api/projects/:projectId/profiles)
+ * and is gated by SPECRAILS_AGENTS_SECTION — a disabled server 404s every route.
+ *
+ * The catalog `generate`, `test`, `refine_start`, and `refine_turn` actions
+ * SPAWN the claude CLI and incur real cost (refine records ai_invocations and
+ * streams agent_refine_* WS events). `refine_apply` / `update_custom` /
+ * `delete_custom` / `create_custom` mutate `custom-*.md` files on disk.
+ */
+function agentsTools() {
+    return [
+        {
+            name: 'specrails_agents',
+            title: 'Agents (Profiles & Catalog)',
+            description: 'Manage agent PROFILES and the agents CATALOG for a project (Claude-only — profiles are inert on codex/gemini projects). ' +
+                'PROFILE actions: list, get, resolve (preview which profile a rail would resolve to), create, update, delete (destructive — protected default/project-default cannot be deleted), ' +
+                'duplicate, rename, migrate (seed a default profile from installed sr-*.md frontmatter), analytics (per-profile metrics), core_version (specrails-core version + 4.1.0 profile-aware check). ' +
+                'CATALOG actions: catalog_list, catalog_get (full agent .md body), versions (custom agent edit history), create_custom (custom-*.md), update_custom, delete_custom (destructive), ' +
+                'generate (AI-generate a draft custom agent — spawns claude, costs), test (AI smoke-test a draft body — spawns claude, costs), ' +
+                'refine_start / refine_turn (AI iterative refine of a custom agent — spawn claude, cost, stream over WS), refine_list, refine_get, refine_patch (toggle autoTest), refine_cancel (kill the spawn), refine_apply (write the refined draft to disk).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (['delete', 'delete_custom'].includes(action))
+                    return 'destructive';
+                if (['generate', 'test', 'refine_start', 'refine_turn'].includes(action))
+                    return 'ai-spawn';
+                if ([
+                    'create',
+                    'update',
+                    'duplicate',
+                    'rename',
+                    'migrate',
+                    'create_custom',
+                    'update_custom',
+                    'refine_patch',
+                    'refine_cancel',
+                    'refine_apply',
+                ].includes(action)) {
+                    return 'write';
+                }
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    // PROFILES
+                    'list',
+                    'get',
+                    'resolve',
+                    'create',
+                    'update',
+                    'delete',
+                    'duplicate',
+                    'rename',
+                    'migrate',
+                    'analytics',
+                    'core_version',
+                    // CATALOG (definitions)
+                    'catalog_list',
+                    'catalog_get',
+                    'versions',
+                    'create_custom',
+                    'update_custom',
+                    'delete_custom',
+                    'generate',
+                    'test',
+                    // CATALOG (AI refine)
+                    'refine_start',
+                    'refine_turn',
+                    'refine_list',
+                    'refine_get',
+                    'refine_patch',
+                    'refine_cancel',
+                    'refine_apply',
+                ])
+                    .describe('Operation to perform (profile or catalog action)'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // Profile params
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Profile name (get/update/delete/duplicate/rename source). For duplicate/rename, the NEW name goes in `newName`.'),
+                newName: zod_1.z.string().optional().describe('New profile name (for duplicate / rename)'),
+                profileName: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Explicit profile name to preview in `resolve` (omit to resolve the project default)'),
+                profile: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('Full Profile body for create/update: { schemaVersion:1, name, description?, provider?, orchestrator:{model}, agents:[], routing:[] }'),
+                windowDays: zod_1.z.number().int().optional().describe('analytics time window in days (1-365, default 30)'),
+                // Catalog params
+                agentId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Agent id for catalog_get/versions/update_custom/delete_custom and all refine actions (custom-* for mutations, sr-*|custom-* for reads)'),
+                body: zod_1.z.string().optional().describe('Agent .md body (for create_custom / update_custom)'),
+                agentName: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('New custom agent id for create_custom — must match ^custom-[a-z0-9][a-z0-9-]*$'),
+                description: zod_1.z.string().optional().describe('Plain-language description for `generate` (AI draft a custom agent)'),
+                draftBody: zod_1.z.string().optional().describe('Draft agent body to smoke-test in `test`'),
+                sampleTask: zod_1.z.string().optional().describe('Sample task the `test` action runs the draft against'),
+                instruction: zod_1.z.string().optional().describe('Refine instruction (for refine_start / refine_turn)'),
+                autoTest: zod_1.z.boolean().optional().describe('Auto-test the refined draft (refine_start default true; refine_patch toggles it)'),
+                refineId: zod_1.z.string().optional().describe('Refine session id (for refine_get/refine_turn/refine_patch/refine_cancel/refine_apply)'),
+                force: zod_1.z.boolean().optional().describe('Bypass the disk-hash guard when applying a refine draft (refine_apply)'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/profiles`;
+                const action = args.action;
+                const agentId = args.agentId;
+                const refineId = args.refineId;
+                const profileName = args.name;
+                switch (action) {
+                    // ── PROFILES ────────────────────────────────────────────────────
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'get': {
+                        if (!profileName)
+                            throw new Error('get requires a profile "name".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${encodeURIComponent(profileName)}`);
+                    }
+                    case 'resolve': {
+                        const p = args.profileName;
+                        const qs = p ? `?profile=${encodeURIComponent(p)}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/resolve${qs}`);
+                    }
+                    case 'create': {
+                        if (!args.profile)
+                            throw new Error('create requires a "profile" body.');
+                        return (0, types_1.apiCall)(ctx, 'POST', base, args.profile);
+                    }
+                    case 'update': {
+                        if (!profileName)
+                            throw new Error('update requires a profile "name".');
+                        if (!args.profile)
+                            throw new Error('update requires a "profile" body (its name must equal "name").');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/${encodeURIComponent(profileName)}`, args.profile);
+                    }
+                    case 'delete': {
+                        if (!profileName)
+                            throw new Error('delete requires a profile "name".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/${encodeURIComponent(profileName)}`);
+                    }
+                    case 'duplicate': {
+                        if (!profileName)
+                            throw new Error('duplicate requires a source profile "name".');
+                        const newName = args.newName;
+                        if (!newName)
+                            throw new Error('duplicate requires a "newName".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${encodeURIComponent(profileName)}/duplicate`, { name: newName });
+                    }
+                    case 'rename': {
+                        if (!profileName)
+                            throw new Error('rename requires a source profile "name".');
+                        const newName = args.newName;
+                        if (!newName)
+                            throw new Error('rename requires a "newName".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${encodeURIComponent(profileName)}/rename`, { name: newName });
+                    }
+                    case 'migrate':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/migrate-from-settings`);
+                    case 'analytics': {
+                        const wd = args.windowDays;
+                        const qs = typeof wd === 'number' ? `?windowDays=${wd}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/analytics${qs}`);
+                    }
+                    case 'core_version':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/core-version`);
+                    // ── CATALOG: definitions ────────────────────────────────────────
+                    case 'catalog_list':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog`);
+                    case 'catalog_get': {
+                        if (!agentId)
+                            throw new Error('catalog_get requires an "agentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}`);
+                    }
+                    case 'versions': {
+                        if (!agentId)
+                            throw new Error('versions requires an "agentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}/versions`);
+                    }
+                    case 'create_custom': {
+                        const id = args.agentName;
+                        const body = args.body;
+                        if (!id)
+                            throw new Error('create_custom requires an "agentName" (custom-* id).');
+                        if (!body)
+                            throw new Error('create_custom requires a "body".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog`, { id, body });
+                    }
+                    case 'update_custom': {
+                        if (!agentId)
+                            throw new Error('update_custom requires an "agentId" (custom-* only).');
+                        const body = args.body;
+                        if (!body)
+                            throw new Error('update_custom requires a "body".');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/catalog/${encodeURIComponent(agentId)}`, { body });
+                    }
+                    case 'delete_custom': {
+                        if (!agentId)
+                            throw new Error('delete_custom requires an "agentId" (custom-* only).');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/catalog/${encodeURIComponent(agentId)}`);
+                    }
+                    // ── CATALOG: AI spawns (cost) ───────────────────────────────────
+                    case 'generate': {
+                        const name = args.agentName;
+                        const description = args.description;
+                        if (!name)
+                            throw new Error('generate requires an "agentName" (custom-* id).');
+                        if (!description)
+                            throw new Error('generate requires a "description".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/generate`, { name, description });
+                    }
+                    case 'test': {
+                        const draftBody = args.draftBody;
+                        const sampleTask = args.sampleTask;
+                        if (!draftBody)
+                            throw new Error('test requires a "draftBody".');
+                        if (!sampleTask)
+                            throw new Error('test requires a "sampleTask".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/test`, {
+                            ...(agentId ? { agentId } : {}),
+                            draftBody,
+                            sampleTask,
+                        });
+                    }
+                    // ── CATALOG: AI refine sessions ─────────────────────────────────
+                    case 'refine_start': {
+                        if (!agentId)
+                            throw new Error('refine_start requires an "agentId" (custom-* only).');
+                        const instruction = args.instruction;
+                        if (!instruction)
+                            throw new Error('refine_start requires an "instruction".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/${encodeURIComponent(agentId)}/refine`, {
+                            instruction,
+                            ...(typeof args.autoTest === 'boolean' ? { autoTest: args.autoTest } : {}),
+                        });
+                        return {
+                            ...r,
+                            hint: 'Refine streams over WS (agent_refine_* events). Use refine_get with the returned refineId to poll the session, then refine_apply to write the draft to disk.',
+                        };
+                    }
+                    case 'refine_turn': {
+                        if (!agentId)
+                            throw new Error('refine_turn requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_turn requires a "refineId".');
+                        const instruction = args.instruction;
+                        if (!instruction)
+                            throw new Error('refine_turn requires an "instruction".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}/turn`, { instruction });
+                        return {
+                            ...r,
+                            hint: 'The turn streams over WS (agent_refine_* events). Use refine_get with the refineId to read the updated draft.',
+                        };
+                    }
+                    case 'refine_list': {
+                        if (!agentId)
+                            throw new Error('refine_list requires an "agentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}/refine`);
+                    }
+                    case 'refine_get': {
+                        if (!agentId)
+                            throw new Error('refine_get requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_get requires a "refineId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}`);
+                    }
+                    case 'refine_patch': {
+                        if (!agentId)
+                            throw new Error('refine_patch requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_patch requires a "refineId".');
+                        if (typeof args.autoTest !== 'boolean')
+                            throw new Error('refine_patch requires a boolean "autoTest".');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}`, { autoTest: args.autoTest });
+                    }
+                    case 'refine_cancel': {
+                        if (!agentId)
+                            throw new Error('refine_cancel requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_cancel requires a "refineId".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}`);
+                    }
+                    case 'refine_apply': {
+                        if (!agentId)
+                            throw new Error('refine_apply requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_apply requires a "refineId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}/apply`, { ...(typeof args.force === 'boolean' ? { force: args.force } : {}) });
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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