@nonbot/mcp 0.0.0-stage → 0.2.0

package/dist/core/toolsets/portfolio.js

@@ -0,0 +1,521 @@
+import { z } from 'zod';
+import { api, expectJson } from '../http.js';
+import { validateGraph } from '../validate.js';
+const DEFAULT_PAGE_SIZE = 25;
+const MAX_PAGE_SIZE = 100;
+function text(obj) {
+    return { type: 'text', text: JSON.stringify(obj, null, 2) };
+}
+export function registerPortfolioTools(server, ctx) {
+    server.registerTool('portfolio_list', {
+        title: 'List portfolios',
+        description: 'List the portfolios the caller can access (owned, team, and shared). Supports filtering by status/team and a case-insensitive substring match on the name, plus cursor pagination so large workspaces stay within the token budget. Read-only — safe to call freely.',
+        inputSchema: {
+            status: z.string().optional().describe('Only return portfolios with this status (e.g. "active", "draft").'),
+            teamId: z.string().optional().describe('Only return portfolios owned by this team id.'),
+            nameContains: z.string().optional().describe('Case-insensitive substring match on the portfolio name.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_PAGE_SIZE)
+                .optional()
+                .describe(`Max results to return (default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}).`),
+            cursor: z.string().optional().describe('Opaque pagination cursor — pass the nextCursor returned by a previous call.'),
+        },
+        outputSchema: {
+            count: z.number().describe('Number of portfolios in this page.'),
+            total: z.number().describe('Total matching portfolios across all pages.'),
+            nextCursor: z.string().optional().describe('Pass to the next call to fetch the following page. Absent when there are no more.'),
+            portfolios: z.array(z.object({
+                id: z.string(),
+                name: z.string(),
+                description: z.string().optional(),
+                status: z.string(),
+                updatedAt: z.string().optional(),
+                teamId: z.string().optional(),
+            })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const res = await api(ctx, '/api/portfolio/list');
+        const data = await expectJson(res, 'portfolio_list');
+        let rows = (data.portfolios ?? []).map((p) => ({
+            id: String(p.id),
+            name: String(p.name ?? ''),
+            description: p.description != null ? String(p.description) : undefined,
+            status: String(p.status ?? 'unknown'),
+            updatedAt: p.updatedAt != null ? String(p.updatedAt) : p.updated_at != null ? String(p.updated_at) : undefined,
+            teamId: p.teamId != null ? String(p.teamId) : p.team_id != null ? String(p.team_id) : undefined,
+        }));
+        if (args.status)
+            rows = rows.filter((r) => r.status === args.status);
+        if (args.teamId)
+            rows = rows.filter((r) => r.teamId === args.teamId);
+        if (args.nameContains) {
+            const q = args.nameContains.toLowerCase();
+            rows = rows.filter((r) => r.name.toLowerCase().includes(q));
+        }
+        rows.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
+        const total = rows.length;
+        const limit = args.limit ?? DEFAULT_PAGE_SIZE;
+        let offset = 0;
+        if (args.cursor !== undefined) {
+            const parsed = Number(args.cursor);
+            if (!Number.isInteger(parsed) || parsed < 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Invalid cursor "${args.cursor}". Pass a nextCursor returned by a previous portfolio_list call, or omit it to start from the beginning.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            offset = parsed;
+        }
+        const page = rows.slice(offset, offset + limit);
+        const nextOffset = offset + page.length;
+        const structured = {
+            count: page.length,
+            total,
+            ...(nextOffset < total ? { nextCursor: String(nextOffset) } : {}),
+            portfolios: page,
+        };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_get', {
+        title: 'Get a portfolio graph',
+        description: 'Fetch the full node/edge graph (plus viewport and version) for one portfolio. ALWAYS call this before portfolio_update so you hold the current version for optimistic-concurrency safety. The text content carries the full graph; structuredContent carries a quick summary (counts + version). Read-only.',
+        inputSchema: {
+            id: z.string().describe('Portfolio id (from portfolio_list).'),
+        },
+        outputSchema: {
+            id: z.string(),
+            name: z.string().optional(),
+            version: z.number().optional(),
+            nodeCount: z.number(),
+            edgeCount: z.number(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        if (!args.id) {
+            return { content: [{ type: 'text', text: 'id is required (get it from portfolio_list).' }], isError: true };
+        }
+        const res = await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(args.id)}`);
+        const data = await expectJson(res, 'portfolio_get');
+        const graph = (data.graph ?? data);
+        const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+        const edges = Array.isArray(graph.edges) ? graph.edges : [];
+        const structured = {
+            id: args.id,
+            ...(typeof data.name === 'string' ? { name: data.name } : {}),
+            ...(typeof graph.version === 'number' ? { version: graph.version } : {}),
+            nodeCount: nodes.length,
+            edgeCount: edges.length,
+        };
+        return { content: [text(data)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_get_activation', {
+        title: 'Get an activation',
+        description: 'Fetch the launch payload + story-brief snapshot for one activation (Act-3 ▶ Run). Read-only.',
+        inputSchema: { activation_id: z.string().describe('The activation id.') },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const res = await api(ctx, `/api/portfolio/activations/${encodeURIComponent(a.activation_id)}`);
+        return { content: [text(await expectJson(res, 'portfolio_get_activation'))] };
+    });
+    server.registerTool('portfolio_subscribe_to_activations', {
+        title: 'List pending activations',
+        description: 'Poll the caller’s currently-pending activations (the Act-3 ▶ Run fallback). Read-only.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async () => {
+        const res = await api(ctx, '/api/portfolio/activations');
+        return { content: [text(await expectJson(res, 'portfolio_subscribe_to_activations'))] };
+    });
+    server.registerTool('portfolio_versions', {
+        title: 'List portfolio snapshots',
+        description: 'List the saved version snapshots (time-travel restore points) for a portfolio — id, label, node count, created time. Read-only.',
+        inputSchema: { portfolio_id: z.string() },
+        outputSchema: {
+            count: z.number(),
+            versions: z.array(z.object({ id: z.string(), label: z.string(), nodeCount: z.number().optional(), versionNumber: z.number().optional(), createdAt: z.string().optional() })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const res = await api(ctx, `/api/portfolio/versions?portfolioId=${encodeURIComponent(a.portfolio_id)}`);
+        const data = await expectJson(res, 'portfolio_versions');
+        const versions = (data.versions ?? []).map((v) => ({
+            id: String(v.id),
+            label: String(v.label ?? ''),
+            ...(typeof v.nodeCount === 'number' ? { nodeCount: v.nodeCount } : {}),
+            ...(typeof v.versionNumber === 'number' ? { versionNumber: v.versionNumber } : {}),
+            ...(v.createdAt != null ? { createdAt: String(v.createdAt) } : {}),
+        }));
+        const structured = { count: versions.length, versions };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_version_get', {
+        title: 'Load a portfolio snapshot',
+        description: 'Load one snapshot’s full graph (nodes + edges + viewport) — the restore source. To restore: load it here, then write it back with portfolio_update (which keeps OCC + a pre-write backup + the confirm gate). Read-only.',
+        inputSchema: { version_id: z.string() },
+        outputSchema: { id: z.string(), label: z.string().optional(), nodeCount: z.number(), edgeCount: z.number() },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const res = await api(ctx, `/api/portfolio/versions?versionId=${encodeURIComponent(a.version_id)}`);
+        const data = await expectJson(res, 'portfolio_version_get');
+        const v = (data.version ?? data);
+        const parse = (x) => {
+            if (typeof x !== 'string')
+                return x;
+            try {
+                return JSON.parse(x);
+            }
+            catch {
+                return x;
+            }
+        };
+        const pn = parse(v.nodes);
+        const pe = parse(v.edges);
+        const nodes = Array.isArray(pn) ? pn : [];
+        const edges = Array.isArray(pe) ? pe : [];
+        const full = { id: a.version_id, label: v.label, viewport: parse(v.viewport), nodes, edges };
+        const structured = { id: a.version_id, ...(typeof v.label === 'string' ? { label: v.label } : {}), nodeCount: nodes.length, edgeCount: edges.length };
+        return { content: [text(full)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_characters', {
+        title: 'List characters (personas)',
+        description: 'List the Character personas the caller can see (their own + team), optionally scoped to a portfolio. Read-only.',
+        inputSchema: { portfolio_id: z.string().optional() },
+        outputSchema: {
+            count: z.number(),
+            characters: z.array(z.object({ id: z.string(), name: z.string(), visibility: z.string().optional(), originPortfolioId: z.string().optional() })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const q = a.portfolio_id ? `?portfolioId=${encodeURIComponent(a.portfolio_id)}` : '';
+        const res = await api(ctx, `/api/portfolio/characters${q}`);
+        const raw = (await expectJson(res, 'portfolio_characters'));
+        const list = (Array.isArray(raw?.characters) ? raw.characters : Array.isArray(raw) ? raw : []);
+        const characters = list.map((c) => ({
+            id: String(c.id),
+            name: String(c.name ?? ''),
+            ...(c.visibility != null ? { visibility: String(c.visibility) } : {}),
+            ...(c.origin_portfolio_id != null ? { originPortfolioId: String(c.origin_portfolio_id) } : {}),
+        }));
+        const structured = { count: characters.length, characters };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    if (ctx.readonly)
+        return;
+    async function gatedReq(method, path, body, label) {
+        const init = { method };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const res = await api(ctx, path, init);
+        if (res.status === 503) {
+            return { content: [{ type: 'text', text: `${label}: this endpoint is gated behind NONBOT_RUN_FEATURE_ENABLED on the server.` }], isError: true };
+        }
+        return { content: [text(await expectJson(res, label))] };
+    }
+    server.registerTool('portfolio_update', {
+        title: 'Replace a portfolio graph',
+        description: 'Whole-graph replace: write the complete nodes + edges for a portfolio. Use it for restructures and deletes; to ADD items use portfolio_add_items, to change one item portfolio_patch_item, to re-position portfolio_layout. Pre-flight validation rejects orphan parents, duplicate ids, and unresolvable epic links. The current server state is snapshotted (backed up) before the write. Pass expectedVersion from portfolio_get; if it no longer matches, the write is refused with a 409 instead of clobbering a concurrent edit.',
+        inputSchema: {
+            id: z.string().describe('Portfolio id.'),
+            nodes: z.array(z.any()).describe('The COMPLETE set of nodes (whole-graph replace).'),
+            edges: z.array(z.any()).describe('The COMPLETE set of edges (whole-graph replace).'),
+            name: z.string().optional().describe('Optional new portfolio name.'),
+            description: z.string().optional().describe('Optional new portfolio description.'),
+            viewport: z.any().optional().describe('Optional Vue Flow viewport { x, y, zoom }.'),
+            expectedVersion: z
+                .number()
+                .int()
+                .optional()
+                .describe('The version from your most recent portfolio_get. Optimistic-concurrency guard — the write is refused (409) if the portfolio changed since. Omit to use the version at write time.'),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            nodeCount: z.number(),
+            edgeCount: z.number(),
+            version: z.number().optional(),
+            backedUp: z.boolean().describe('Whether the prior server state was snapshotted before the write.'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const nodes = (args.nodes ?? []);
+        const edges = (args.edges ?? []);
+        const problems = validateGraph(nodes, edges);
+        if (problems.length > 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Refusing to write — the graph has ${problems.length} problem(s):\n` + problems.map((e) => `  - ${e}`).join('\n'),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const currentRes = await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(args.id)}`);
+        const current = await expectJson(currentRes, 'portfolio_update (pre-fetch)');
+        let backedUp = false;
+        if (ctx.backup) {
+            try {
+                await ctx.backup(args.id, current);
+                backedUp = true;
+            }
+            catch {
+                backedUp = false;
+            }
+        }
+        const currentGraph = (current.graph ?? current);
+        const curNodeCount = Array.isArray(currentGraph.nodes) ? currentGraph.nodes.length : 0;
+        const removed = curNodeCount - nodes.length;
+        if (curNodeCount > 0 && (removed >= 5 || nodes.length < curNodeCount / 2)) {
+            try {
+                const el = await server.server.elicitInput({
+                    message: `This overwrites the portfolio graph: ${curNodeCount} → ${nodes.length} nodes (removing ${Math.max(removed, 0)}). Proceed?`,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: { confirm: { type: 'boolean', description: 'true to proceed with the overwrite' } },
+                        required: ['confirm'],
+                    },
+                });
+                if (el.action !== 'accept' || el.content?.confirm !== true) {
+                    return { content: [{ type: 'text', text: 'Update cancelled — the overwrite was not confirmed. The prior state is unchanged.' }], isError: true };
+                }
+            }
+            catch {
+            }
+        }
+        const baselineVersion = typeof args.expectedVersion === 'number' ? args.expectedVersion : currentGraph.version;
+        const putRes = await api(ctx, '/api/portfolio/graph', {
+            method: 'PUT',
+            body: JSON.stringify({
+                id: args.id,
+                nodes,
+                edges,
+                ...(baselineVersion !== undefined ? { expectedVersion: baselineVersion } : {}),
+                name: args.name ?? String(current.name ?? current.graph?.name ?? ''),
+                description: args.description ?? String(current.description ?? current.graph?.description ?? ''),
+                ...(args.viewport !== undefined ? { viewport: args.viewport } : currentGraph.viewport !== undefined ? { viewport: currentGraph.viewport } : {}),
+            }),
+        });
+        if (putRes.status === 409) {
+            const conflict = (await putRes.json().catch(() => ({})));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Update refused (409) — the portfolio changed since you read it ` +
+                            `(current version ${conflict.currentVersion ?? '?'}). ` +
+                            `Call portfolio_get again, re-apply your edits onto the latest, then retry.` +
+                            (backedUp ? ' The prior state was backed up before this attempt.' : ''),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const result = await expectJson(putRes, 'portfolio_update');
+        const resultGraph = (result.server ?? result.graph ?? result);
+        const structured = {
+            ok: true,
+            nodeCount: nodes.length,
+            edgeCount: edges.length,
+            ...(typeof resultGraph.version === 'number' ? { version: resultGraph.version } : {}),
+            backedUp,
+        };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    const planItem = z.object({
+        title: z.string(),
+        description: z.string().optional(),
+        acceptanceCriteria: z.string().optional(),
+    });
+    server.registerTool('portfolio_create_from_plan', {
+        title: 'Create a portfolio from a plan',
+        description: 'Create a DRAFT portfolio from an LLM-structured plan (epic + optional features/stories). Status stays "draft" until portfolio_publish_draft.',
+        inputSchema: {
+            suggested_name: z.string().optional(),
+            description: z.string().optional(),
+            epic: planItem,
+            features: z.array(planItem.extend({ stories: z.array(planItem).optional() })).optional(),
+            stories: z.array(planItem.extend({ parentFeatureIndex: z.number().int().optional() })).optional(),
+            inception_summary: z.string().optional(),
+            claude_session_id: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => {
+        if (!a.epic?.title?.trim()) {
+            return { content: [{ type: 'text', text: 'epic.title is required.' }], isError: true };
+        }
+        return gatedReq('POST', '/api/portfolio/create-from-plan', a, 'portfolio_create_from_plan');
+    });
+    server.registerTool('portfolio_decompose', {
+        title: 'Decompose an item into children',
+        description: 'Ask the server AI to decompose an item (epic→features or feature→stories) into SUGGESTED children for review. Reads the parent (level/title/description) from the portfolio by item_id. Returns { items, reasoning } — it does NOT write them; apply via portfolio_update if you accept them.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            item_id: z.string(),
+            count: z.number().int().min(1).max(10).optional().describe('How many children to suggest.'),
+            guidance: z.string().optional().describe('Extra guidance for the decomposition.'),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => {
+        const gRes = await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(a.portfolio_id)}`);
+        const gData = await expectJson(gRes, 'portfolio_decompose (fetch)');
+        const graph = (gData.graph ?? gData);
+        const nodes = Array.isArray(graph.nodes)
+            ? graph.nodes
+            : [];
+        const node = nodes.find((n) => n?.id === a.item_id);
+        if (!node) {
+            return { content: [{ type: 'text', text: `No item "${a.item_id}" in portfolio "${a.portfolio_id}". Use portfolio_get to find the id.` }], isError: true };
+        }
+        const d = node.data ?? {};
+        return gatedReq('POST', '/api/portfolio/decompose', {
+            portfolioId: a.portfolio_id,
+            parentLevel: String(d.hierarchyLevel ?? 'epic'),
+            parentTitle: String(d.title ?? d.label ?? d.name ?? ''),
+            parentDescription: String(d.description ?? ''),
+            ...(a.count !== undefined ? { count: a.count } : {}),
+            ...(a.guidance !== undefined ? { guidance: a.guidance } : {}),
+        }, 'portfolio_decompose');
+    });
+    server.registerTool('portfolio_attach_brief', {
+        title: 'Attach a brief to an item',
+        description: 'Attach metadata to one node: a markdown brief, acceptance criteria, description, and/or hypothesis. At least one is required.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            item_id: z.string(),
+            brief_md: z.string().optional(),
+            acceptance_criteria: z.string().optional(),
+            description: z.string().optional(),
+            hypothesis: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => {
+        if (!a.brief_md && !a.acceptance_criteria && !a.description && !a.hypothesis) {
+            return { content: [{ type: 'text', text: 'Provide at least one of brief_md, acceptance_criteria, description, hypothesis.' }], isError: true };
+        }
+        return gatedReq('POST', `/api/portfolio/${encodeURIComponent(a.portfolio_id)}/attach-brief`, {
+            itemId: a.item_id,
+            briefMd: a.brief_md,
+            acceptanceCriteria: a.acceptance_criteria,
+            description: a.description,
+            hypothesis: a.hypothesis,
+        }, 'portfolio_attach_brief');
+    });
+    server.registerTool('portfolio_link_chat_session', {
+        title: 'Link a chat session to a portfolio',
+        description: 'Backlink a portfolio to the chat that birthed it. Provide a claude_session_id and/or an inception_summary.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            claude_session_id: z.string().optional(),
+            inception_summary: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => {
+        if (!a.claude_session_id && !a.inception_summary) {
+            return { content: [{ type: 'text', text: 'Provide at least one of claude_session_id, inception_summary.' }], isError: true };
+        }
+        return gatedReq('POST', `/api/portfolio/${encodeURIComponent(a.portfolio_id)}/link-chat-session`, {
+            claude_session_id: a.claude_session_id,
+            inception_summary: a.inception_summary,
+        }, 'portfolio_link_chat_session');
+    });
+    server.registerTool('portfolio_publish_draft', {
+        title: 'Publish a draft portfolio',
+        description: 'Flip a portfolio from "draft" → "active". Idempotent.',
+        inputSchema: { portfolio_id: z.string() },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => gatedReq('POST', `/api/portfolio/${encodeURIComponent(a.portfolio_id)}/publish-draft`, undefined, 'portfolio_publish_draft'));
+    server.registerTool('portfolio_mark_run_ready', {
+        title: 'Mark a story run-ready',
+        description: 'Tag a story as ready for CLI pickup (or clear it with run_ready=false).',
+        inputSchema: { portfolio_id: z.string(), item_id: z.string(), run_ready: z.boolean().optional() },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => gatedReq('POST', `/api/portfolio/${encodeURIComponent(a.portfolio_id)}/mark-run-ready`, {
+        itemId: a.item_id,
+        ...(a.run_ready === undefined ? {} : { runReady: a.run_ready }),
+    }, 'portfolio_mark_run_ready'));
+    server.registerTool('portfolio_repo_path', {
+        title: 'Get or set the portfolio repo path',
+        description: 'Your per-user local repo path for a portfolio — where ▶ Run activations cd before launching. Without repo_path: returns the current value. With repo_path: sets it (absolute POSIX path; pass empty string to clear). portfolio_create_activation fails with no_repo_path until this is set. (Added after a live dogfood hit exactly that wall.)',
+        inputSchema: {
+            portfolio_id: z.string(),
+            repo_path: z.string().optional().describe('Absolute local path to set, "" to clear; omit to read.'),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const path = `/api/portfolio/${encodeURIComponent(a.portfolio_id)}/repo-path`;
+        if (a.repo_path === undefined)
+            return gatedReq('GET', path, undefined, 'portfolio_repo_path');
+        return gatedReq('PUT', path, { repoPath: a.repo_path === '' ? null : a.repo_path }, 'portfolio_repo_path');
+    });
+    server.registerTool('portfolio_create_activation', {
+        title: 'Create an activation',
+        description: 'Create an activation (a ▶ Run launch request) for a story. Targets the assignee or the caller.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            item_id: z.string(),
+            target_operator_user_id: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => gatedReq('POST', '/api/portfolio/activations', {
+        portfolioId: a.portfolio_id,
+        itemId: a.item_id,
+        ...(a.target_operator_user_id !== undefined ? { targetOperatorUserId: a.target_operator_user_id } : {}),
+    }, 'portfolio_create_activation'));
+    server.registerTool('portfolio_update_activation_status', {
+        title: 'Update activation status',
+        description: 'Transition an activation: pending → running | failed | cancelled. The caller must be the target operator.',
+        inputSchema: {
+            activation_id: z.string(),
+            status: z.string(),
+            terminal_app_used: z.string().optional(),
+            run_id: z.string().optional(),
+            failure_reason: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => gatedReq('PATCH', `/api/portfolio/activations/${encodeURIComponent(a.activation_id)}`, {
+        status: a.status,
+        ...(a.terminal_app_used ? { terminalAppUsed: a.terminal_app_used } : {}),
+        ...(a.run_id ? { runId: a.run_id } : {}),
+        ...(a.failure_reason ? { failureReason: a.failure_reason } : {}),
+    }, 'portfolio_update_activation_status'));
+    server.registerTool('portfolio_snapshot', {
+        title: 'Snapshot a portfolio',
+        description: 'Save a labeled version snapshot of a portfolio’s CURRENT graph — a time-travel restore point. Reads the live graph and stores it. The server rate-limits snapshots (20/day).',
+        inputSchema: { portfolio_id: z.string(), label: z.string().optional().describe('Optional human label for the snapshot.') },
+        outputSchema: { ok: z.boolean(), versionId: z.string().optional(), label: z.string().optional() },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (a) => {
+        const gRes = await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(a.portfolio_id)}`);
+        const g = await expectJson(gRes, 'portfolio_snapshot (fetch)');
+        const graph = (g.graph ?? g);
+        const res = await api(ctx, '/api/portfolio/versions', {
+            method: 'POST',
+            body: JSON.stringify({
+                portfolioId: a.portfolio_id,
+                label: a.label,
+                nodes: graph.nodes ?? [],
+                edges: graph.edges ?? [],
+                viewport: graph.viewport,
+            }),
+        });
+        const data = await expectJson(res, 'portfolio_snapshot');
+        const ver = (data.version ?? data);
+        const versionId = ver.id != null ? String(ver.id) : data.versionId != null ? String(data.versionId) : undefined;
+        const structured = { ok: true, ...(versionId ? { versionId } : {}), ...(a.label ? { label: a.label } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+}

package/dist/core/toolsets/run.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from '../config.js';
+export declare function registerRunTools(server: McpServer, ctx: ApiContext): void;