@heuresis/mcp 1.0.0-rc.1

package/dist/cloudOperators.js

@@ -0,0 +1,530 @@
+// Heuresis MCP — operator-running tools (Phase 19.5).
+//
+// Turns the MCP from a "data layer" into a "thinking partner": the user / a
+// host agent can fire a Branch / Matrix / ASIT / TRIZ / Free / Combine /
+// Contradiction operator directly from the MCP, against the same cloud
+// workspace the webapp sees. The MCP loads the user's BYO key via the
+// `get_my_provider_key` SECURITY DEFINER RPC, calls the provider directly,
+// parses the JSON envelope through the same schema the webapp uses, and
+// returns structured candidates.
+//
+// Two surfaces:
+//
+//   * run_operator(family, key, anchor_id, args?)  — generates candidates
+//     and (by default) does NOT commit. The caller decides whether to use
+//     `bulk_add_concepts` (Agent B's tool) to commit, or to call the sibling
+//     `run_operator_and_commit` to do it in one tool round-trip.
+//
+//   * expand_concept(id, depth, breadth, angle?)  — recursive Branch. Walks
+//     breadth-first and commits each level immediately so the user sees
+//     partial results in the webapp as the run progresses (rather than
+//     waiting 30s for a full tree). Hard-capped at depth * breadth ≤ 60 per
+//     PLAN.md Phase 10.3 safety guardrail.
+//
+// Provenance — every committed concept gets a row in `public.provenance`
+// stamped origin='mcp', operator='<family>:<key>', sourceRefs=[anchor_id].
+// The migration that lands the table is 0015 (Agent B's half).
+//
+// Cost preview — every run_operator response carries an `estimated_cost:
+// { credits, dollars }` chip from the rate card in `docs/credits.md` §2.
+// Informational only; BYO-key runs don't bill against managed credits.
+import { z } from 'zod';
+import { unwrap } from './cloudClient.js';
+import { ASIT_OPERATORS } from './operators/asit.js';
+import { TRIZ_OPERATORS } from './operators/triz.js';
+import { CONTRADICTION_OPERATOR } from './operators/contradiction.js';
+import { COMBINE_OPERATOR } from './operators/combine.js';
+import { EXPLORE_OPERATOR } from './operators/explore.js';
+import { TRIZ_PARAMETERS, TRIZ_PRINCIPLES, lookupPrinciples, } from './operators/triz-matrix.js';
+import { composePrompt } from './prompt/compose.js';
+import { parseLlmResponse } from './prompt/parse.js';
+import { defaultModelFor, runLlm, } from './llm/client.js';
+import { estimateCost } from './llm/cost.js';
+// ---------------------------------------------------------------------------
+// FREEFORM operator — referenced by run_operator(family='free') and reused
+// internally by expand_concept. Defined inline rather than in
+// `operators/free.ts` because it's a single value and the webapp lives it in
+// `operators/catalog.ts`; folding it here keeps the operator file count low.
+// ---------------------------------------------------------------------------
+const FREEFORM_OPERATOR = {
+    family: 'FREEFORM',
+    key: 'freeform',
+    name: 'Free expansion',
+    glyph: '✎',
+    oneLiner: 'Expand the concept along a user-supplied angle.',
+    doctrine: 'No fixed heuristic. The user supplies an angle or question and the LLM proposes partitions consistent with that angle.',
+    promptFragment: 'Apply the FREEFORM operator: propose 3–5 partitions that expand the current concept along the angle stated by the user (see <angle> tag below).',
+};
+const ALL_OPERATORS = [
+    ...ASIT_OPERATORS,
+    ...TRIZ_OPERATORS,
+    CONTRADICTION_OPERATOR,
+    FREEFORM_OPERATOR,
+    COMBINE_OPERATOR,
+    EXPLORE_OPERATOR,
+];
+// ---------------------------------------------------------------------------
+// Family-key resolution
+// ---------------------------------------------------------------------------
+// `run_operator` accepts `family` as a low-case string ('asit' | 'triz' |
+// 'contradiction' | 'free' | 'combine') for caller convenience; the webapp
+// uses UPPER (OperatorDefinition.family). Normalize once.
+const FAMILY_ALIASES = {
+    asit: 'ASIT',
+    triz: 'TRIZ',
+    contradiction: 'CONTRADICTION',
+    free: 'FREEFORM',
+    freeform: 'FREEFORM',
+    combine: 'COMBINE',
+    explore: 'EXPLORE',
+    branch: 'EXPLORE',
+};
+function normalizeFamily(raw) {
+    const lower = raw.toLowerCase();
+    return FAMILY_ALIASES[lower] ?? null;
+}
+function resolveOperator(family, key) {
+    // EXPLORE / FREEFORM / COMBINE / CONTRADICTION ignore `key` — there's
+    // exactly one operator per family. Default to that.
+    if (family === 'EXPLORE')
+        return EXPLORE_OPERATOR;
+    if (family === 'FREEFORM')
+        return FREEFORM_OPERATOR;
+    if (family === 'COMBINE')
+        return COMBINE_OPERATOR;
+    if (family === 'CONTRADICTION')
+        return CONTRADICTION_OPERATOR;
+    // ASIT + TRIZ need a key. Match exactly.
+    return (ALL_OPERATORS.find((o) => o.family === family && o.key === key) ?? null);
+}
+// ---------------------------------------------------------------------------
+// Anchor + project + ancestry loaders
+// ---------------------------------------------------------------------------
+async function loadAnchor(client, id) {
+    const res = await client.from('nodes').select('*').eq('id', id).maybeSingle();
+    if (res.error)
+        throw new Error(res.error.message);
+    if (!res.data)
+        throw new Error(`No concept with id ${id}`);
+    return res.data;
+}
+async function loadProjectForNode(client, node) {
+    // Prefer the denormalized project_id on the node; fall back to a join
+    // through project_nodes (legacy rows pre-migration 0012 lacked the column).
+    let projectId = node.project_id;
+    if (!projectId) {
+        const rows = unwrap(await client
+            .from('project_nodes')
+            .select('project_id')
+            .eq('node_id', node.id)
+            .limit(1));
+        projectId = rows[0]?.project_id ?? null;
+    }
+    if (!projectId) {
+        throw new Error(`Concept ${node.id} is not in any project — operators need a project context to compose prompts.`);
+    }
+    const proj = unwrap(await client.from('projects').select('*').eq('id', projectId).single());
+    return proj;
+}
+async function loadAncestry(client, node) {
+    // Walk parent_id up to the root. Cheap because depth is small.
+    const chain = [node];
+    const seen = new Set([node.id]);
+    let cur = node.parent_id;
+    while (cur && !seen.has(cur)) {
+        seen.add(cur);
+        const res = await client.from('nodes').select('*').eq('id', cur).maybeSingle();
+        if (res.error)
+            break;
+        const p = res.data;
+        if (!p)
+            break;
+        chain.unshift(p);
+        cur = p.parent_id;
+    }
+    return chain;
+}
+async function loadKnowledgePool(client, project) {
+    const memberRows = unwrap(await client
+        .from('project_nodes')
+        .select('node_id')
+        .eq('project_id', project.id));
+    const memberIds = memberRows.map((r) => r.node_id);
+    if (memberIds.length === 0)
+        return [];
+    const rows = unwrap(await client
+        .from('nodes')
+        .select('*')
+        .in('id', memberIds)
+        .eq('status', 'validated'));
+    // Cap at 20 to keep prompt bloat bounded; same heuristic the webapp uses.
+    return rows.slice(0, 20);
+}
+async function loadDirectChildren(client, node) {
+    const rows = unwrap(await client
+        .from('nodes')
+        .select('*')
+        .eq('parent_id', node.id)
+        .neq('status', 'archived'));
+    return rows;
+}
+// ---------------------------------------------------------------------------
+// LLM config resolution — reads localStorage-style provider/model selection
+// from credentials.json (added in a tiny extension) OR defaults to anthropic
+// + sonnet. The key itself comes from the RPC.
+// ---------------------------------------------------------------------------
+async function resolveLlmConfig(client, preferProvider) {
+    const provider = preferProvider ?? 'anthropic';
+    const rpcRes = await client.rpc('get_my_provider_key', {
+        p_provider: provider,
+    });
+    if (rpcRes.error) {
+        throw new Error(`Failed to load BYO key via get_my_provider_key: ${rpcRes.error.message}`);
+    }
+    const apiKey = rpcRes.data ?? '';
+    if (!apiKey) {
+        throw new Error(`No provider key configured for "${provider}". Add one in Settings ▸ AI service (in the webapp) or pass a different provider via args.provider.`);
+    }
+    return { provider, apiKey, model: defaultModelFor(provider) };
+}
+// ---------------------------------------------------------------------------
+// run_operator
+// ---------------------------------------------------------------------------
+const ProviderEnum = z.enum(['anthropic', 'openai', 'openrouter', 'google']);
+export const runOperatorInput = z
+    .object({
+    family: z
+        .string()
+        .describe("Operator family. One of 'asit' | 'triz' | 'contradiction' | 'free' | 'combine' | 'explore'."),
+    key: z
+        .string()
+        .describe("Operator key within the family. Ignored for single-operator families (free, combine, contradiction, explore). For ASIT use one of: unification, multiplication, division, object_removal, breaking_symmetry. For TRIZ use 'principle_NN_<snake_name>' (e.g. principle_01_segmentation)."),
+    anchor_id: z.string().describe('The concept the operator runs against.'),
+    args: z
+        .record(z.unknown())
+        .optional()
+        .describe("Family-specific extras: { angle?: string } for free/explore/combine, { improving: number, worsening: number } for contradiction, { combineWithIds: string[] } for combine. Optional { provider: 'anthropic' | 'openai' | 'openrouter' | 'google' } overrides the default provider."),
+})
+    .strict();
+export async function runOperator(client, args) {
+    const family = normalizeFamily(args.family);
+    if (!family) {
+        throw new Error(`Unknown operator family "${args.family}". Use one of: asit, triz, contradiction, free, combine, explore.`);
+    }
+    const operator = resolveOperator(family, args.key);
+    if (!operator) {
+        throw new Error(`Unknown operator key "${args.key}" for family ${family}.`);
+    }
+    const anchor = await loadAnchor(client, args.anchor_id);
+    const project = await loadProjectForNode(client, anchor);
+    const [ancestry, knowledge] = await Promise.all([
+        loadAncestry(client, anchor),
+        loadKnowledgePool(client, project),
+    ]);
+    // Family-specific extras.
+    const extras = args.args ?? {};
+    const angle = typeof extras.angle === 'string' ? extras.angle : undefined;
+    let branch;
+    if (family === 'EXPLORE') {
+        const kids = await loadDirectChildren(client, anchor);
+        branch = {
+            parentLabel: anchor.label,
+            existingChildren: kids.map((k) => ({
+                label: k.label,
+                description: k.description,
+            })),
+        };
+    }
+    let contradiction;
+    if (family === 'CONTRADICTION') {
+        const improving = Number(extras.improving);
+        const worsening = Number(extras.worsening);
+        if (!Number.isInteger(improving) || improving < 1 || improving > 39) {
+            throw new Error("CONTRADICTION requires args.improving (1..39 — TRIZ parameter number).");
+        }
+        if (!Number.isInteger(worsening) || worsening < 1 || worsening > 39) {
+            throw new Error("CONTRADICTION requires args.worsening (1..39 — TRIZ parameter number).");
+        }
+        const improvingParam = TRIZ_PARAMETERS.find((p) => p.num === improving);
+        const worseningParam = TRIZ_PARAMETERS.find((p) => p.num === worsening);
+        const principleNums = lookupPrinciples(improving, worsening).slice(0, 5);
+        const principles = principleNums
+            .map((n) => TRIZ_PRINCIPLES.find((p) => p.num === n))
+            .filter((p) => !!p)
+            .map((p) => ({ num: p.num, name: p.name, doctrine: p.doctrine }));
+        contradiction = {
+            improvingName: improvingParam.name,
+            worseningName: worseningParam.name,
+            principles,
+        };
+    }
+    let combineInputs;
+    if (family === 'COMBINE') {
+        const ids = Array.isArray(extras.combineWithIds)
+            ? extras.combineWithIds.filter((x) => typeof x === 'string')
+            : [];
+        if (ids.length === 0) {
+            throw new Error('COMBINE requires args.combineWithIds: a non-empty array of concept ids to fuse with the anchor.');
+        }
+        const rows = unwrap(await client
+            .from('nodes')
+            .select('id, label, description')
+            .in('id', [anchor.id, ...ids]));
+        combineInputs = rows;
+    }
+    // Compose + resolve the BYO key.
+    const prompt = composePrompt({
+        project,
+        ancestry,
+        target: anchor,
+        operator,
+        knowledge,
+        freeformAngle: angle,
+        combineInputs,
+        branch,
+        contradiction,
+    });
+    const preferProvider = ProviderEnum.safeParse(extras.provider).success
+        ? extras.provider
+        : undefined;
+    const config = await resolveLlmConfig(client, preferProvider);
+    const cost = estimateCost({
+        provider: config.provider,
+        model: config.model,
+        promptChars: prompt.length,
+    });
+    const llmResult = await runLlm(config, { prompt });
+    const parsed = parseLlmResponse(llmResult.text);
+    if (!parsed.ok) {
+        throw new Error(`Operator run produced output the parser rejected: ${parsed.error}`);
+    }
+    const candidates = parsed.data.partitions.map((p) => ({
+        label: p.label,
+        description: p.description,
+        partitionAttribute: p.partitionAttribute,
+        rationale: p.rationale,
+        kReferences: p.kReferences,
+        selfCritique: p.selfCritique,
+        children: p.children,
+    }));
+    return {
+        family,
+        key: operator.key,
+        anchorId: anchor.id,
+        candidates,
+        newKnowledgeProposed: parsed.data.newKnowledgeProposed,
+        operatorNotes: parsed.data.operatorNotes,
+        estimatedCost: {
+            credits: cost.credits,
+            dollars: cost.dollars,
+            modelClass: cost.modelClass,
+        },
+        rawTextPreview: llmResult.text.slice(0, 5000),
+        usage: llmResult.usage,
+    };
+}
+// ---------------------------------------------------------------------------
+// run_operator_and_commit — convenience wrapper that fires run_operator,
+// then writes every top-level candidate as a child of the anchor, with a
+// partition edge + provenance row. Children-of-children are NOT committed
+// here (the depth-2 leaves are kept in the response for the caller to act on
+// separately) because mixing depth-2 commits with the depth-1 set has
+// surprised users in webapp testing.
+// ---------------------------------------------------------------------------
+export const runOperatorAndCommitInput = runOperatorInput;
+export async function runOperatorAndCommit(client, args) {
+    const run = await runOperator(client, args);
+    const anchor = await loadAnchor(client, args.anchor_id);
+    const project = await loadProjectForNode(client, anchor);
+    const ids = [];
+    for (const cand of run.candidates) {
+        const id = await commitCandidate(client, {
+            anchor,
+            project,
+            label: cand.label,
+            description: cand.description,
+            operator: `${run.family}:${run.key}`,
+        });
+        ids.push(id);
+    }
+    return {
+        family: run.family,
+        key: run.key,
+        anchorId: run.anchorId,
+        committedIds: ids,
+        estimatedCost: run.estimatedCost,
+        operatorNotes: run.operatorNotes,
+        usage: run.usage,
+    };
+}
+async function commitCandidate(client, args) {
+    const inserted = unwrap(await client
+        .from('nodes')
+        .insert({
+        workspace_id: args.anchor.workspace_id,
+        parent_id: args.anchor.id,
+        label: args.label,
+        description: args.description,
+        project_id: args.project.id,
+        tags: [],
+    })
+        .select('id')
+        .single());
+    // Partition edge so the canvas draws the parent → child line.
+    await client
+        .from('edges')
+        .insert({
+        workspace_id: args.anchor.workspace_id,
+        from_id: args.anchor.id,
+        to_id: inserted.id,
+        kind: 'partition',
+    })
+        .select('id')
+        .maybeSingle();
+    // project_nodes link (the project's member list).
+    await client
+        .from('project_nodes')
+        .insert({ project_id: args.project.id, node_id: inserted.id, position: 0 })
+        .select('id')
+        .maybeSingle();
+    // Provenance row — origin='mcp', operator='<family>:<key>', anchor as
+    // source_ref. Best-effort: if the table is absent on a not-yet-migrated
+    // database (0015 not applied), swallow the error rather than fail the
+    // whole commit — the concept itself is still useful.
+    try {
+        await client.from('provenance').insert({
+            workspace_id: args.anchor.workspace_id,
+            node_id: inserted.id,
+            origin: 'mcp',
+            operator_key: args.operator,
+            source_refs: [args.anchor.id],
+            created_by: 'agent',
+            timestamp_ms: Date.now(),
+        });
+    }
+    catch {
+        // ignore — provenance is metadata, not blocking.
+    }
+    return inserted.id;
+}
+// ---------------------------------------------------------------------------
+// expand_concept — recursive Branch with depth + breadth.
+// ---------------------------------------------------------------------------
+export const expandConceptInput = z
+    .object({
+    id: z.string().describe('The concept to expand.'),
+    depth: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .describe('How many levels deep to expand (1..3).'),
+    breadth: z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .describe('Approximate children per node (1..5).'),
+    angle: z
+        .string()
+        .optional()
+        .describe('Optional creative-direction hint passed to the underlying free / explore operator.'),
+})
+    .strict()
+    .refine((v) => v.depth * v.breadth <= 60, 'Safety guardrail: depth × breadth must be ≤ 60. See PLAN.md Phase 10.3.');
+export async function expandConcept(client, args) {
+    const root = await loadAnchor(client, args.id);
+    const rootTree = { id: root.id, label: root.label, children: [] };
+    let totalCommitted = 0;
+    let totalCredits = 0;
+    // Breadth-first: at each level, expand every just-committed node by one
+    // level of EXPLORE. We commit each level immediately so the user sees
+    // partial results in the webapp as the run progresses.
+    let frontier = [
+        { node: root, tree: rootTree },
+    ];
+    for (let lvl = 0; lvl < args.depth; lvl++) {
+        const nextFrontier = [];
+        for (const cur of frontier) {
+            const runArgs = {
+                family: 'explore',
+                key: 'branch',
+                anchor_id: cur.node.id,
+                args: args.angle ? { angle: args.angle } : undefined,
+            };
+            const run = await runOperator(client, runArgs);
+            totalCredits += run.estimatedCost.credits;
+            // Take up to `breadth` candidates per node.
+            const chosen = run.candidates.slice(0, args.breadth);
+            const project = await loadProjectForNode(client, cur.node);
+            for (const cand of chosen) {
+                const newId = await commitCandidate(client, {
+                    anchor: cur.node,
+                    project,
+                    label: cand.label,
+                    description: cand.description,
+                    operator: 'expand',
+                });
+                totalCommitted++;
+                const childTree = {
+                    id: newId,
+                    label: cand.label,
+                    children: [],
+                };
+                cur.tree.children.push(childTree);
+                if (lvl + 1 < args.depth) {
+                    // Re-load the freshly-inserted node so subsequent EXPLORE calls
+                    // have a real NodeRow to anchor against.
+                    const fresh = await loadAnchor(client, newId);
+                    nextFrontier.push({ node: fresh, tree: childTree });
+                }
+            }
+        }
+        frontier = nextFrontier;
+        if (frontier.length === 0)
+            break;
+    }
+    return {
+        rootId: root.id,
+        totalCommitted,
+        tree: rootTree,
+        estimatedCostTotal: {
+            credits: totalCredits,
+            dollars: Math.round(totalCredits) / 100,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// OPERATOR_TOOLS export — index.ts splices this onto CLOUD_TOOLS and wires
+// each entry's `handler(client, args)` to the lazy auth handshake.
+// ---------------------------------------------------------------------------
+export const OPERATOR_TOOLS = [
+    {
+        name: 'run_operator',
+        description: "Run an ASIT / TRIZ / Contradiction / Free / Combine / Explore operator against one concept (the anchor). Returns CANDIDATE concepts WITHOUT committing them — call `bulk_add_concepts` (or `run_operator_and_commit`) to persist. Use this when you want the agent to vet the candidates before writing. The anchor must already live in a project; the operator pulls in ancestry + validated knowledge in the same project to ground the prompt.",
+        inputSchema: runOperatorInput,
+        handler: async (client, raw) => runOperator(client, runOperatorInput.parse(raw)),
+    },
+    {
+        name: 'run_operator_and_commit',
+        description: "Same as `run_operator`, but immediately writes every top-level candidate as a child of the anchor with a partition edge and a provenance row stamped origin='mcp'. Use when the agent is confident the candidates should land directly on the canvas (e.g. inside an autonomous expand loop). Children-of-children proposed in `partitions[].children` are NOT auto-committed — request them via a separate run.",
+        inputSchema: runOperatorAndCommitInput,
+        handler: async (client, raw) => runOperatorAndCommit(client, runOperatorAndCommitInput.parse(raw)),
+    },
+    {
+        name: 'expand_concept',
+        description: 'Recursive Branch — expand a concept by `breadth` children at each of `depth` levels (depth*breadth ≤ 60). Commits each level immediately so the webapp shows partial results as the run progresses. Optionally takes an `angle` hint that biases the underlying EXPLORE operator. Best when the anchor has few or no children yet; on a dense subtree consider `run_operator(family="explore")` so the operator can read existing children and propose complementary partitions.',
+        inputSchema: expandConceptInput,
+        handler: async (client, raw) => expandConcept(client, expandConceptInput.parse(raw)),
+    },
+];
+// Re-exports kept narrow on purpose: index.ts only needs `makeOperatorTools`,
+// but the inputs / shapes are exported above for unit tests when they land.
+export const OPERATOR_FAMILIES = [
+    'asit',
+    'triz',
+    'contradiction',
+    'free',
+    'combine',
+    'explore',
+];