@nonbot/mcp 0.0.0-stage → 0.1.0

package/dist/core/toolsets/run.js

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+import { api, expectJson } from '../http.js';
+const GATE = 'The Run feature is gated behind NONBOT_RUN_FEATURE_ENABLED on the server. Ask the non.bot operator to enable it.';
+const rid = (id) => encodeURIComponent(id);
+async function runReq(ctx, method, path, body) {
+    const init = { method };
+    if (body !== undefined)
+        init.body = JSON.stringify(body);
+    const res = await api(ctx, path, init);
+    if (res.status === 503)
+        throw new Error(GATE);
+    return expectJson(res, `${method} ${path}`);
+}
+function textResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+const WRITE = { readOnlyHint: false, openWorldHint: true };
+const READ = { readOnlyHint: true, openWorldHint: true };
+export function registerRunTools(server, ctx) {
+    server.registerTool('run_get_state', {
+        title: 'Get run state',
+        description: 'Ground-truth run state: active_plan, ghost_plan, stickies, pending_violations, pending_reflections, trust_dial, last_user_intervention_at. Call before every non-trivial action. Read-only.',
+        inputSchema: { run_id: z.string() },
+        annotations: READ,
+    }, async (a) => textResult(await runReq(ctx, 'GET', `/api/portfolio/runs/${rid(a.run_id)}`)));
+    if (ctx.readonly)
+        return;
+    server.registerTool('run_load_activation', {
+        title: 'Load run activation context',
+        description: 'Load the full context for a run: the story brief, acceptance criteria, applicable WhyGraph rules, and ensemble defaults. Call once at the start of a run.',
+        inputSchema: { activation_id: z.string().describe('The activation id to load.') },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => textResult(await runReq(ctx, 'POST', '/api/portfolio/runs/load', { activationId: a.activation_id })));
+    server.registerTool('run_register_agent', {
+        title: 'Register an ensemble agent',
+        description: 'Register an ensemble member for this activation (creates the run on the first agent). Returns the run_id you pass to every other run_* tool. role ∈ researcher|architect|lead|verifier|capsule_writer.',
+        inputSchema: {
+            activation_id: z.string(),
+            role: z.enum(['researcher', 'architect', 'lead', 'verifier', 'capsule_writer']),
+            model_hint: z.string().optional(),
+            title: z.string().optional(),
+        },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', '/api/portfolio/runs', {
+        activationId: a.activation_id,
+        role: a.role,
+        modelHint: a.model_hint,
+        title: a.title,
+    })));
+    server.registerTool('run_declare_scope', {
+        title: 'Declare run scope',
+        description: 'Lead declares the file allowlist + intent. Out-of-scope writes are advisory-blocked.',
+        inputSchema: {
+            run_id: z.string(),
+            allowlist: z.array(z.string()).describe('Repo-relative paths/globs the run may touch.'),
+            intent: z.string(),
+        },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/declare-scope`, { allowlist: a.allowlist, intent: a.intent })));
+    server.registerTool('run_request_scope_change', {
+        title: 'Request a scope change',
+        description: 'Request expansion of the file allowlist. Surfaces as a yellow flare on the canvas for the human to accept/reject.',
+        inputSchema: { run_id: z.string(), reason: z.string(), additions: z.array(z.string()) },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/request-scope-change`, { reason: a.reason, additions: a.additions })));
+    server.registerTool('run_emit_diff', {
+        title: 'Emit a code diff',
+        description: 'Report a code diff. Triggers a WhyGraph rule-check + scope guard; returns { violations, reinforcements, blocked_paths }.',
+        inputSchema: {
+            run_id: z.string(),
+            files: z.array(z.string()).min(1),
+            lines_added: z.number().int().optional(),
+            lines_removed: z.number().int().optional(),
+            snippets: z.array(z.string()).optional(),
+            step_node_id: z.string().optional(),
+        },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/diff`, {
+        files: a.files,
+        linesAdded: a.lines_added ?? 0,
+        linesRemoved: a.lines_removed ?? 0,
+        snippets: a.snippets,
+        stepNodeId: a.step_node_id,
+    })));
+    server.registerTool('run_emit_test_run', {
+        title: 'Emit test results',
+        description: 'Report a test run; updates the dashboard sparkline.',
+        inputSchema: {
+            run_id: z.string(),
+            results: z.object({
+                passed: z.number().int(),
+                failed: z.number().int(),
+                total: z.number().int(),
+                failures: z.array(z.any()).optional(),
+            }),
+        },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/test-run`, { results: a.results })));
+    server.registerTool('run_emit_lint', {
+        title: 'Emit lint results',
+        description: 'Report lint hits; updates the dashboard.',
+        inputSchema: { run_id: z.string(), hits: z.array(z.any()) },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/lint`, { hits: a.hits })));
+    server.registerTool('run_emit_typecheck', {
+        title: 'Emit typecheck results',
+        description: 'Report type-check errors; updates the dashboard.',
+        inputSchema: { run_id: z.string(), errors: z.array(z.any()) },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/typecheck`, { errors: a.errors })));
+    server.registerTool('run_emit_build', {
+        title: 'Emit build status',
+        description: 'Report build status; updates the dashboard.',
+        inputSchema: { run_id: z.string(), status: z.enum(['pass', 'fail', 'warn']), log: z.string().optional() },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/build`, { status: a.status, log: a.log })));
+    server.registerTool('run_emit_file_touch', {
+        title: 'Emit a file touch',
+        description: 'Report a file access (read|write|create); glows the living codebase map.',
+        inputSchema: { run_id: z.string(), path: z.string(), op: z.enum(['read', 'write', 'create']) },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/file-touch`, { path: a.path, op: a.op })));
+    server.registerTool('run_emit_usage', {
+        title: 'Emit a turn\'s token usage',
+        description: 'Report ONE turn\'s raw token counts so the command center\'s Metered Spend tile and per-run cost cap become truthful (instead of showing $0.00). The SERVER computes the cost from the model — never send a dollar amount (an agent can\'t under-report its way past the cap). Returns cumulative spend + percent-of-cap + status; a 409 means this turn busted the run\'s hard cap and you must escalate to the operator before continuing. Call once per model turn with the provider-reported input/output token counts.',
+        inputSchema: {
+            run_id: z.string(),
+            turn_index: z.number().int().min(0).describe('0-based turn number within the run.'),
+            model: z.string().describe('Model id — must be one the server prices (e.g. a claude-* id).'),
+            input_tokens: z.number().int().min(0),
+            output_tokens: z.number().int().min(0),
+            phase: z.string().optional().describe('Optional phase tag for per-phase cost rollup.'),
+        },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/cost-event`, {
+        turnIndex: a.turn_index,
+        model: a.model,
+        inputTokens: a.input_tokens,
+        outputTokens: a.output_tokens,
+        ...(a.phase ? { phase: a.phase } : {}),
+    })));
+    server.registerTool('run_request_reconsider', {
+        title: 'Request a reconsideration',
+        description: 'Verifier nudges the Lead to reflect; inserts a pending reflection row.',
+        inputSchema: { run_id: z.string(), reason: z.string(), last_step_id: z.string().optional() },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/reflections`, { kind: 'request', reason: a.reason, lastStepId: a.last_step_id })));
+    server.registerTool('run_post_reflection', {
+        title: 'Post a reflection',
+        description: 'Lead posts a reflection (response to a reconsider, or self-initiated). decision ∈ continue|revise_plan|escalate.',
+        inputSchema: {
+            run_id: z.string(),
+            reflection_md: z.string(),
+            decision: z.enum(['continue', 'revise_plan', 'escalate']),
+            last_step_id: z.string().optional(),
+            plan_diff: z.any().optional(),
+        },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/reflections`, {
+        kind: 'post',
+        reflectionMd: a.reflection_md,
+        decision: a.decision,
+        lastStepId: a.last_step_id,
+        planDiff: a.plan_diff,
+    })));
+    server.registerTool('run_resolve_violation', {
+        title: 'Resolve a WhyGraph violation',
+        description: 'Resolve a rule violation. action ∈ enforce (rollback) | accept (weight decay) | override (log).',
+        inputSchema: { run_id: z.string(), violation_id: z.string(), action: z.enum(['enforce', 'accept', 'override']) },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/violations/${rid(a.violation_id)}/resolve`, { action: a.action })));
+    server.registerTool('run_set_trust_dial', {
+        title: 'Set the trust dial',
+        description: 'Adjust the trust dial mid-run (0–10). Lower = more escalation; higher = more autonomy.',
+        inputSchema: { run_id: z.string(), value: z.number().int().min(0).max(10) },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => textResult(await runReq(ctx, 'PATCH', `/api/portfolio/runs/${rid(a.run_id)}`, { trustDial: a.value })));
+    server.registerTool('run_pause_agent', {
+        title: 'Pause an ensemble agent',
+        description: 'Pause one ensemble member by role. (Newly surfaced — was defined but unregistered in the old server.)',
+        inputSchema: { run_id: z.string(), role: z.string() },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/agents/${rid(a.role)}/pause`, {})));
+    server.registerTool('run_resume_agent', {
+        title: 'Resume an ensemble agent',
+        description: 'Resume one paused ensemble member by role. (Newly surfaced — was defined but unregistered in the old server.)',
+        inputSchema: { run_id: z.string(), role: z.string() },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/agents/${rid(a.role)}/resume`, {})));
+    server.registerTool('run_emit_pr', {
+        title: 'Announce a PR',
+        description: 'Announce that a PR is open; triggers the Act-5 closing sequence.',
+        inputSchema: { run_id: z.string(), pr_url: z.string() },
+        annotations: WRITE,
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/pr`, { prUrl: a.pr_url })));
+    server.registerTool('run_finish', {
+        title: 'Finish the run',
+        description: 'Final close-out: triggers reinforcement + candidate-rule extraction, sets the story to shipped. Provide the capsule markdown and an optional PR URL.',
+        inputSchema: { run_id: z.string(), capsule_md: z.string(), pr_url: z.string().optional(), summary: z.any().optional() },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (a) => textResult(await runReq(ctx, 'POST', `/api/portfolio/runs/${rid(a.run_id)}/finish`, { capsuleMd: a.capsule_md, prUrl: a.pr_url, summary: a.summary })));
+}

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

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

package/dist/core/toolsets/whygraph.js

@@ -0,0 +1,346 @@
+import { z } from 'zod';
+import { api, expectJson } from '../http.js';
+async function fetchGraph(ctx) {
+    const res = await api(ctx, '/api/whygraph/decisions');
+    const data = await expectJson(res, 'whygraph');
+    if (data.error) {
+        throw new Error(`WhyGraph is temporarily unavailable (${data.hint ?? 'unknown'}). The decision graph backend is not reachable right now.`);
+    }
+    return { decisions: data.decisions ?? [], relationships: data.relationships ?? [] };
+}
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1);
+}
+function isLaw(d) {
+    return d.status === 'locked' || (typeof d.weight === 'number' && d.weight >= 5);
+}
+function scoreDecision(queryTokens, d) {
+    if (queryTokens.length === 0)
+        return 0;
+    const hay = new Set(tokenize(`${d.title ?? ''} ${d.description ?? ''} ${d.category ?? ''}`));
+    let score = 0;
+    for (const t of queryTokens)
+        if (hay.has(t))
+            score += 1;
+    return score;
+}
+export function registerWhygraphTools(server, ctx) {
+    server.registerTool('whygraph_search', {
+        title: 'Search decisions',
+        description: 'Search the PM decision graph by keyword, ranked by weight (how reinforced a decision is) then relevance. Use this to find prior decisions before proposing something new. Read-only.',
+        inputSchema: {
+            query: z.string().describe('Keywords to match against decision title, description, and category.'),
+            category: z.string().optional().describe('Restrict to one category.'),
+            limit: z.number().int().min(1).max(50).optional().describe('Max results (default 10).'),
+        },
+        outputSchema: {
+            count: z.number(),
+            decisions: z.array(z.object({
+                id: z.string(),
+                title: z.string(),
+                category: z.string().optional(),
+                weight: z.number(),
+                status: z.string().optional(),
+                isLaw: z.boolean(),
+                score: z.number(),
+            })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const { decisions } = await fetchGraph(ctx);
+        const qTokens = tokenize(args.query);
+        const scored = decisions
+            .filter((d) => (args.category ? d.category === args.category : true))
+            .map((d) => ({
+            id: d.id,
+            title: d.title ?? d.id,
+            category: d.category,
+            weight: typeof d.weight === 'number' ? d.weight : 0,
+            status: d.status,
+            isLaw: isLaw(d),
+            score: scoreDecision(qTokens, d),
+        }))
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.weight - a.weight || b.score - a.score);
+        const page = scored.slice(0, args.limit ?? 10);
+        const structured = { count: page.length, decisions: page };
+        const text = page.length
+            ? JSON.stringify(structured, null, 2)
+            : JSON.stringify({ ...structured, note: `No decisions matched "${args.query}". Try whygraph_stats for an overview, or whygraph_context to see which LAWs apply to a task.` }, null, 2);
+        return { content: [{ type: 'text', text }], structuredContent: structured };
+    });
+    server.registerTool('whygraph_context', {
+        title: 'Get decision context for a task',
+        description: 'Given a task you are about to do, return the decisions that apply: the best keyword matches PLUS every LAW (locked, weight ≥ 5) — because LAWs always apply. Call this BEFORE acting so you answer to the rules the team already wrote down. Read-only.',
+        inputSchema: {
+            task: z.string().describe('A short description of what you are about to do.'),
+        },
+        outputSchema: {
+            task: z.string(),
+            matchedCount: z.number(),
+            lawCount: z.number(),
+            matched: z.array(z.object({ id: z.string(), title: z.string(), category: z.string().optional(), weight: z.number(), status: z.string().optional() })),
+            laws: z.array(z.object({ id: z.string(), title: z.string(), category: z.string().optional(), weight: z.number() })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const { decisions } = await fetchGraph(ctx);
+        const qTokens = tokenize(args.task);
+        const matched = decisions
+            .map((d) => ({ d, score: scoreDecision(qTokens, d) }))
+            .filter((x) => x.score > 0)
+            .sort((a, b) => (b.d.weight ?? 0) - (a.d.weight ?? 0) || b.score - a.score)
+            .slice(0, 10)
+            .map(({ d }) => ({ id: d.id, title: d.title ?? d.id, category: d.category, weight: d.weight ?? 0, status: d.status }));
+        const matchedIds = new Set(matched.map((m) => m.id));
+        const laws = decisions
+            .filter(isLaw)
+            .filter((d) => !matchedIds.has(d.id))
+            .sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0))
+            .map((d) => ({ id: d.id, title: d.title ?? d.id, category: d.category, weight: d.weight ?? 0 }));
+        const structured = { task: args.task, matchedCount: matched.length, lawCount: laws.length, matched, laws };
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+    });
+    server.registerTool('whygraph_neighbors', {
+        title: 'Trace a decision’s impact radius',
+        description: 'Graph reasoning the flat decision list cannot give you: starting from one decision, traverse RELATED_TO relationships breadth-first to surface every connected decision within N hops — the "impact radius" of changing or violating it. Returns connected decisions grouped by distance. Read-only.',
+        inputSchema: {
+            id: z.string().describe('The decision id to start from (slug, e.g. from whygraph_search).'),
+            depth: z.number().int().min(1).max(4).optional().describe('How many hops to traverse (default 2, max 4).'),
+        },
+        outputSchema: {
+            root: z.string(),
+            found: z.number(),
+            maxDepth: z.number(),
+            neighbors: z.array(z.object({
+                id: z.string(),
+                title: z.string(),
+                category: z.string().optional(),
+                distance: z.number(),
+                isLaw: z.boolean(),
+            })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const { decisions, relationships } = await fetchGraph(ctx);
+        const byId = new Map(decisions.map((d) => [d.id, d]));
+        if (!byId.has(args.id)) {
+            throw new Error(`No decision with id "${args.id}". Use whygraph_search to find the right id first.`);
+        }
+        const adj = new Map();
+        const link = (a, b) => {
+            if (!adj.has(a))
+                adj.set(a, new Set());
+            adj.get(a).add(b);
+        };
+        for (const r of relationships) {
+            link(r.fromId, r.toId);
+            link(r.toId, r.fromId);
+        }
+        const maxDepth = args.depth ?? 2;
+        const dist = new Map([[args.id, 0]]);
+        let frontier = [args.id];
+        for (let d = 1; d <= maxDepth && frontier.length > 0; d++) {
+            const next = [];
+            for (const node of frontier) {
+                for (const nb of adj.get(node) ?? []) {
+                    if (!dist.has(nb)) {
+                        dist.set(nb, d);
+                        next.push(nb);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        const neighbors = [...dist.entries()]
+            .filter(([id]) => id !== args.id)
+            .map(([id, distance]) => {
+            const d = byId.get(id);
+            return { id, title: d?.title ?? id, category: d?.category, distance, isLaw: d ? isLaw(d) : false };
+        })
+            .sort((a, b) => a.distance - b.distance || a.title.localeCompare(b.title))
+            .slice(0, 100);
+        const structured = { root: args.id, found: neighbors.length, maxDepth, neighbors };
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+    });
+    server.registerTool('whygraph_stats', {
+        title: 'Decision graph overview',
+        description: 'A dashboard view of the decision graph: total decisions, a per-category breakdown, the LAWs (locked, weight ≥ 5), and the most-violated decisions. Read-only.',
+        inputSchema: {},
+        outputSchema: {
+            total: z.number(),
+            byCategory: z.record(z.string(), z.number()),
+            laws: z.array(z.object({ id: z.string(), title: z.string(), weight: z.number() })),
+            mostViolated: z.array(z.object({ id: z.string(), title: z.string(), violationCount: z.number() })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async () => {
+        const { decisions } = await fetchGraph(ctx);
+        const byCategory = {};
+        for (const d of decisions) {
+            const c = d.category ?? 'uncategorized';
+            byCategory[c] = (byCategory[c] ?? 0) + 1;
+        }
+        const laws = decisions
+            .filter(isLaw)
+            .sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0))
+            .map((d) => ({ id: d.id, title: d.title ?? d.id, weight: d.weight ?? 0 }));
+        const mostViolated = decisions
+            .filter((d) => (d.violationCount ?? 0) > 0)
+            .sort((a, b) => (b.violationCount ?? 0) - (a.violationCount ?? 0))
+            .slice(0, 5)
+            .map((d) => ({ id: d.id, title: d.title ?? d.id, violationCount: d.violationCount ?? 0 }));
+        const structured = { total: decisions.length, byCategory, laws, mostViolated };
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+    });
+    server.registerTool('whygraph_path', {
+        title: 'Find the path between two decisions',
+        description: 'Find the shortest chain of RELATED_TO links connecting one decision to another — how a decision reaches another through the graph. Returns the ordered path (or connected:false if there is none). Read-only.',
+        inputSchema: {
+            from_id: z.string().describe('Start decision id (from whygraph_search).'),
+            to_id: z.string().describe('Target decision id.'),
+            maxDepth: z.number().int().min(1).max(8).optional().describe('Max hops to search (default 8).'),
+        },
+        outputSchema: {
+            from: z.string(),
+            to: z.string(),
+            connected: z.boolean(),
+            hops: z.number(),
+            path: z.array(z.object({ id: z.string(), title: z.string() })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const { decisions, relationships } = await fetchGraph(ctx);
+        const byId = new Map(decisions.map((d) => [d.id, d]));
+        if (!byId.has(args.from_id))
+            throw new Error(`No decision "${args.from_id}". Use whygraph_search to find the id.`);
+        if (!byId.has(args.to_id))
+            throw new Error(`No decision "${args.to_id}". Use whygraph_search to find the id.`);
+        const adj = new Map();
+        const link = (a, b) => {
+            if (!adj.has(a))
+                adj.set(a, new Set());
+            adj.get(a).add(b);
+        };
+        for (const r of relationships) {
+            link(r.fromId, r.toId);
+            link(r.toId, r.fromId);
+        }
+        const maxDepth = args.maxDepth ?? 8;
+        const prev = new Map([[args.from_id, null]]);
+        let frontier = [args.from_id];
+        let found = args.from_id === args.to_id;
+        for (let d = 1; d <= maxDepth && frontier.length > 0 && !found; d++) {
+            const next = [];
+            for (const node of frontier) {
+                for (const nb of adj.get(node) ?? []) {
+                    if (!prev.has(nb)) {
+                        prev.set(nb, node);
+                        if (nb === args.to_id)
+                            found = true;
+                        next.push(nb);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        const path = [];
+        if (prev.has(args.to_id)) {
+            const chain = [];
+            let cur = args.to_id;
+            while (cur !== null) {
+                chain.unshift(cur);
+                cur = prev.get(cur) ?? null;
+            }
+            for (const id of chain)
+                path.push({ id, title: byId.get(id)?.title ?? id });
+        }
+        const structured = { from: args.from_id, to: args.to_id, connected: path.length > 0, hops: path.length > 0 ? path.length - 1 : 0, path };
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+    });
+    server.registerTool('whygraph_conflicts', {
+        title: 'Surface potential decision conflicts',
+        description: 'Surface pairs of decisions that govern the SAME field but are NOT linked to each other — potential unreconciled overlap or contradiction to review. A heuristic for human review (it flags candidates, it does not judge). Read-only.',
+        inputSchema: {
+            field: z.string().optional().describe('Restrict to decisions tagged with this field.'),
+            limit: z.number().int().min(1).max(50).optional().describe('Max pairs to return (default 20).'),
+        },
+        outputSchema: {
+            count: z.number(),
+            note: z.string().optional(),
+            pairs: z.array(z.object({
+                sharedField: z.string(),
+                a: z.object({ id: z.string(), title: z.string(), weight: z.number() }),
+                b: z.object({ id: z.string(), title: z.string(), weight: z.number() }),
+            })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const { decisions, relationships } = await fetchGraph(ctx);
+        const linked = new Set();
+        for (const r of relationships) {
+            linked.add(`${r.fromId}|${r.toId}`);
+            linked.add(`${r.toId}|${r.fromId}`);
+        }
+        const ds = decisions.filter((d) => Array.isArray(d.fields) && d.fields.length > 0);
+        const pairs = [];
+        for (let i = 0; i < ds.length; i++) {
+            for (let j = i + 1; j < ds.length; j++) {
+                const A = ds[i];
+                const B = ds[j];
+                if (linked.has(`${A.id}|${B.id}`))
+                    continue;
+                const fa = new Set(A.fields ?? []);
+                const shared = (B.fields ?? []).find((f) => fa.has(f) && (args.field ? f === args.field : true));
+                if (!shared)
+                    continue;
+                pairs.push({
+                    sharedField: shared,
+                    a: { id: A.id, title: A.title ?? A.id, weight: A.weight ?? 0 },
+                    b: { id: B.id, title: B.title ?? B.id, weight: B.weight ?? 0 },
+                });
+            }
+        }
+        pairs.sort((x, y) => (y.a.weight + y.b.weight) - (x.a.weight + x.b.weight));
+        const page = pairs.slice(0, args.limit ?? 20);
+        const structured = { count: page.length, pairs: page };
+        if (page.length === 0) {
+            structured.note = 'No field-level overlaps without a link were found (decisions may not be tagged with fields). This flags candidates only.';
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+    });
+    server.registerTool('whygraph_recent_violations', {
+        title: 'Recent rule violations',
+        description: 'The most recent times decisions were violated — what broke, when, and which decision. The temporal signal the stats overview can’t give you. Read-only.',
+        inputSchema: { limit: z.number().int().min(1).max(50).optional().describe('How many recent violations (default 20).') },
+        outputSchema: {
+            count: z.number(),
+            violations: z.array(z.object({
+                id: z.string().optional(),
+                decisionId: z.string().optional(),
+                decisionTitle: z.string().optional(),
+                what: z.string().optional(),
+                result: z.string().optional(),
+                timestamp: z.string().optional(),
+            })),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => {
+        const limit = args.limit ?? 20;
+        const res = await api(ctx, `/api/whygraph/violations?limit=${limit}`);
+        const data = await expectJson(res, 'whygraph_recent_violations');
+        const violations = (data.violations ?? []).map((v) => ({
+            ...(v.id != null ? { id: String(v.id) } : {}),
+            ...(v.decisionId != null ? { decisionId: String(v.decisionId) } : {}),
+            ...(v.decisionTitle != null ? { decisionTitle: String(v.decisionTitle) } : {}),
+            ...(v.what != null ? { what: String(v.what) } : {}),
+            ...(v.result != null ? { result: String(v.result) } : {}),
+            ...(v.timestamp != null ? { timestamp: String(v.timestamp) } : {}),
+        }));
+        const structured = { count: violations.length, violations };
+        return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
+    });
+}

package/dist/core/validate.d.ts

@@ -0,0 +1,21 @@
+export interface PortfolioNode {
+    id: string;
+    type?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    data?: {
+        parentItemId?: string;
+        linkedEpicIds?: string[];
+        hierarchyLevel?: string;
+        [k: string]: unknown;
+    };
+}
+export interface PortfolioEdge {
+    id: string;
+    source: string;
+    target: string;
+    [k: string]: unknown;
+}
+export declare function validateGraph(nodes: PortfolioNode[], edges: PortfolioEdge[]): string[];

package/dist/core/validate.js

@@ -0,0 +1,45 @@
+export function validateGraph(nodes, edges) {
+    const errors = [];
+    if (!Array.isArray(nodes))
+        return ['nodes must be an array'];
+    if (!Array.isArray(edges))
+        return ['edges must be an array'];
+    const ids = new Set();
+    for (const n of nodes) {
+        if (!n.id)
+            errors.push(`node missing id: ${JSON.stringify(n).slice(0, 80)}`);
+        else if (ids.has(n.id))
+            errors.push(`duplicate node id: ${n.id}`);
+        else
+            ids.add(n.id);
+    }
+    const epicIds = new Set(nodes.filter((n) => n.data?.hierarchyLevel === 'epic').map((n) => n.id));
+    for (const n of nodes) {
+        const parent = n.data?.parentItemId;
+        if (parent && !ids.has(parent)) {
+            errors.push(`node ${n.id} has parentItemId ${parent} that does not exist`);
+        }
+        const linked = n.data?.linkedEpicIds;
+        if (Array.isArray(linked)) {
+            for (const epicId of linked) {
+                if (!epicIds.has(epicId)) {
+                    errors.push(`node ${n.id} linkedEpicIds points to non-epic ${epicId}`);
+                }
+            }
+        }
+    }
+    const edgeIds = new Set();
+    for (const e of edges) {
+        if (!e.id)
+            errors.push('edge missing id');
+        else if (edgeIds.has(e.id))
+            errors.push(`duplicate edge id: ${e.id}`);
+        else
+            edgeIds.add(e.id);
+        if (!ids.has(e.source))
+            errors.push(`edge ${e.id} source ${e.source} not in nodes`);
+        if (!ids.has(e.target))
+            errors.push(`edge ${e.id} target ${e.target} not in nodes`);
+    }
+    return errors;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};