taskflow-mcp-core 0.1.8 → 0.2.1

package/dist/mcp/server.js

@@ -21,13 +21,93 @@
  *   - taskflow_verify  : statically verify a flow (no execution)
  *   - taskflow_compile : render a flow as a DAG diagram (SVG image) + status line
  *   - taskflow_peek    : inspect a stored run's intermediate phase output
+ *   - taskflow_trace   : read a run's append-only event trace
+ *   - taskflow_replay  : re-evaluate a recorded trace under alternate knobs (zero tokens)
+ *   - taskflow_why_stale / taskflow_recompute / taskflow_reconcile_workspace
+ *   - taskflow_save / taskflow_search
  */
 import { RpcError, RPC, serveStdio } from "./jsonrpc.js";
 import { renderFlowSvg, renderFlowOutline, svgToBase64 } from "./svg.js";
-import { discoverAgents, executeTaskflow, getFlowDiagnosed, listFlows, newRunId, peekRun, saveRun, DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS, readDefineFile, describeLoadFailure, compileTaskflow, verifyTaskflow, desugar, isShorthand, validateTaskflow, readSubagentSettings, readMeta, saveFlowWithMeta, bumpReuseInSidecar, deriveMeta, searchLibrary, } from "taskflow-core";
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, relative, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { discoverAgents, executeTaskflow, getFlowDiagnosed, listFlows, newRunId, peekRun, saveRun, DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS, readDefineFile, describeLoadFailure, compileTaskflow, verifyTaskflow, desugar, isShorthand, validateTaskflow, resolveArgs, cwdBridgeModeFromEnv, directoryIdentity, readSubagentSettings, readMeta, saveFlowWithMeta, bumpReuseInSidecar, deriveMeta, searchLibrary, replayRun, upgradeTraceEvent, reconcileResolveOnlyWorkspace, WORKSPACE_RECONCILE_ACKNOWLEDGEMENT, workspaceReconcileAllowedFromEnv, } from "taskflow-core";
 import { runsDir, traceFilePath, FileTraceSink, readTrace, loadRunDiagnosed, readMapOf, declaredReadMapOfDef, formatWhyStale, recomputeTaskflow, } from "taskflow-core";
 const PROTOCOL_VERSION = "2025-06-18";
-const SERVER_INFO = { name: "taskflow", title: "Taskflow", version: "0.1.5" };
+const SERVER_VERSION = readServerVersion();
+const SERVER_INFO = { name: "taskflow", title: "Taskflow", version: SERVER_VERSION };
+function readServerVersion() {
+    try {
+        const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (typeof pkg === "object" && pkg !== null && "version" in pkg) {
+            const version = pkg.version;
+            if (typeof version === "string" && version)
+                return version;
+        }
+    }
+    catch {
+        // Keep the handshake available even in unusual embedded/bundled layouts.
+    }
+    return "0.2.1";
+}
+function validateToolValue(value, schema, path) {
+    const errors = [];
+    const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+    if (enumValues && !enumValues.some((candidate) => Object.is(candidate, value))) {
+        errors.push(`${path} must be one of ${enumValues.map(String).join(", ")}`);
+        return errors;
+    }
+    const type = schema.type;
+    if (type === "object") {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return [`${path} must be an object`];
+        }
+        const object = value;
+        const properties = (schema.properties ?? {});
+        for (const required of Array.isArray(schema.required) ? schema.required : []) {
+            if (typeof required === "string" && !(required in object))
+                errors.push(`${path}.${required} is required`);
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(object)) {
+                if (!(key in properties))
+                    errors.push(`${path}.${key} is not allowed`);
+            }
+        }
+        for (const [key, childSchema] of Object.entries(properties)) {
+            if (key in object)
+                errors.push(...validateToolValue(object[key], childSchema, `${path}.${key}`));
+        }
+        return errors;
+    }
+    if (type === "array") {
+        if (!Array.isArray(value))
+            return [`${path} must be an array`];
+        const itemSchema = schema.items;
+        if (typeof itemSchema === "object" && itemSchema !== null) {
+            value.forEach((item, index) => errors.push(...validateToolValue(item, itemSchema, `${path}[${index}]`)));
+        }
+        return errors;
+    }
+    if (type === "string" && typeof value !== "string")
+        errors.push(`${path} must be a string`);
+    if (type === "number" && (typeof value !== "number" || !Number.isFinite(value)))
+        errors.push(`${path} must be a finite number`);
+    if (type === "integer" && (typeof value !== "number" || !Number.isSafeInteger(value)))
+        errors.push(`${path} must be an integer`);
+    if (type === "boolean" && typeof value !== "boolean")
+        errors.push(`${path} must be a boolean`);
+    return errors;
+}
+function validateToolArguments(tool, value) {
+    const args = value ?? {};
+    const errors = validateToolValue(args, tool.inputSchema, "arguments");
+    if (errors.length > 0)
+        throw new RpcError(RPC.INVALID_PARAMS, `Invalid ${tool.name} arguments: ${errors.join("; ")}`);
+    return args;
+}
 /**
  * MCP tools/call result with a single text block.
  *
@@ -116,8 +196,43 @@ function count(n, noun) {
  *  Output text is truncated so a fan-out's full transcripts don't flood the
  *  host context — pass json:true for the complete record. Mirrors the pi
  *  adapter's formatTrace. */
-function formatTraceMcp(events, runId, flowName) {
+const TRACE_DEFAULT_LIMIT = 200;
+const TRACE_MAX_LIMIT = 1000;
+const TRACE_MAX_RESPONSE_CHARS = 120_000;
+const TRACE_JSON_STRING_LIMIT = 4_000;
+function traceLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return TRACE_DEFAULT_LIMIT;
+    return Math.max(1, Math.min(TRACE_MAX_LIMIT, Math.floor(value)));
+}
+function boundedTraceEvents(events, requested) {
+    const limit = traceLimit(requested);
+    const bounded = events.slice(-limit).map((event) => JSON.parse(JSON.stringify(event, (_key, value) => typeof value === "string" && value.length > TRACE_JSON_STRING_LIMIT
+        ? `${value.slice(0, TRACE_JSON_STRING_LIMIT)}… (+${value.length - TRACE_JSON_STRING_LIMIT} chars)`
+        : value)));
+    while (bounded.length > 1) {
+        const candidate = JSON.stringify({ total: events.length, returned: bounded.length, truncated: bounded.length < events.length, events: bounded }, null, 2);
+        if (candidate.length <= TRACE_MAX_RESPONSE_CHARS)
+            break;
+        bounded.shift();
+    }
+    return { total: events.length, events: bounded };
+}
+export function formatTraceJsonMcp(events, requested) {
+    const bounded = boundedTraceEvents(events, requested);
+    return JSON.stringify({
+        total: bounded.total,
+        returned: bounded.events.length,
+        truncated: bounded.events.length < bounded.total,
+        events: bounded.events,
+    }, null, 2);
+}
+function formatTraceMcp(events, runId, flowName, requested) {
+    const bounded = boundedTraceEvents(events, requested);
+    events = bounded.events;
     const lines = [`Trace — ${flowName} / ${runId}  (${events.length} events)`];
+    if (events.length < bounded.total)
+        lines.push(`Showing newest ${events.length} of ${bounded.total} events.`);
     lines.push("");
     const out = (text, limit = 400) => {
         if (!text)
@@ -149,9 +264,55 @@ function formatTraceMcp(events, runId, flowName) {
         }
     }
     lines.push("");
-    lines.push("(Pass json:true for the complete machine-readable trace, including full subagent outputs.)");
+    lines.push("(Pass json:true for a bounded machine-readable envelope; total/returned/truncated report omitted events.)");
     return lines.join("\n");
 }
+/** Human-readable offline replay report (MCP). Zero tokens — re-folds the
+ *  recorded trace under alternate decision knobs. */
+function formatReplayMcp(r, runId, flowName) {
+    const lines = [
+        `Replay — ${flowName} / ${runId}  (${r.decisions.length} phase decision(s), zero tokens)`,
+    ];
+    lines.push("");
+    if (r.needsLiveRerun)
+        lines.push("⚠ Some phases need a live re-run (model/args override).");
+    lines.push(`Recorded usage cost ≈ $${r.totalUsage.cost.toFixed(4)}  tokens in=${r.totalUsage.input} out=${r.totalUsage.output}`);
+    lines.push("");
+    for (const d of r.decisions) {
+        const prior = d.priorOutcome ? ` prior=${d.priorOutcome}` : "";
+        const next = d.replayedOutcome ? ` → ${d.replayedOutcome}` : "";
+        lines.push(`  • ${d.phaseId}: [${d.outcome}]${prior}${next} — ${d.reason}`);
+    }
+    lines.push("");
+    lines.push("(Pass json:true for the full ReplayReport machine-readable record.)");
+    return lines.join("\n");
+}
+function parseReplayOverrides(args) {
+    const o = {};
+    if (typeof args.budgetMaxUSD === "number")
+        o.budgetMaxUSD = args.budgetMaxUSD;
+    if (typeof args.budgetMaxTokens === "number")
+        o.budgetMaxTokens = args.budgetMaxTokens;
+    if (args.thresholds && typeof args.thresholds === "object" && !Array.isArray(args.thresholds)) {
+        const t = {};
+        for (const [k, v] of Object.entries(args.thresholds)) {
+            if (typeof v === "number")
+                t[k] = v;
+        }
+        if (Object.keys(t).length)
+            o.thresholds = t;
+    }
+    if (args.models && typeof args.models === "object" && !Array.isArray(args.models)) {
+        const m = {};
+        for (const [k, v] of Object.entries(args.models)) {
+            if (typeof v === "string")
+                m[k] = v;
+        }
+        if (Object.keys(m).length)
+            o.models = m;
+    }
+    return o;
+}
 /** Human-readable recompute dry-run report (MCP). Mirrors the pi adapter's
  *  formatRecompute. */
 function formatRecomputeMcp(r) {
@@ -252,13 +413,40 @@ const TOOLS = [
     {
         name: "taskflow_trace",
         title: "Show a run's deterministic-replay event trace",
-        description: "Read the append-only event trace a run recorded (each subagent call's input/output + the runtime's own decisions: gate verdicts, when-guard results, budget hits, cache hits, unreplayable markers). This is the foundation for deterministic replay (re-evaluating a run against changed thresholds/budget offline, zero tokens — landing in a future release). For now it is a read-only observability view of exactly what the run did. Output is human-readable by default; pass json:true for the complete machine-readable record.",
+        description: "Read the append-only event trace a run recorded (each subagent call's input/output + runtime decisions). Foundation for taskflow_replay. Responses are bounded; use limit to select up to 1000 newest events.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
             properties: {
                 runId: { type: "string", description: "The run to inspect (from a prior taskflow_run or the runs index)." },
-                json: { type: "boolean", description: "Return the complete machine-readable trace (JSON) instead of a human-readable timeline. Use when you need the full subagent outputs (the human form truncates them)." },
+                json: { type: "boolean", description: "Return a bounded machine-readable envelope instead of a human timeline. The envelope reports total/returned/truncated; oversized strings are truncated." },
+                limit: { type: "number", minimum: 1, maximum: 1000, description: "Maximum newest trace events to return (default 200, max 1000). Large string fields and total response size are also bounded." },
+            },
+            required: ["runId"],
+        },
+    },
+    {
+        name: "taskflow_replay",
+        title: "Replay a recorded run under alternate decision knobs (zero tokens)",
+        description: "Re-evaluate a stored run's event trace offline against changed gate thresholds, budget caps, or model routes — without calling any model (zero tokens). Reports per-phase outcomes: reused, would-block, verdict-flipped, would-exceed-budget, needs-live-rerun, etc. Use after taskflow_trace when you want counterfactual analysis of a finished run.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                runId: { type: "string", description: "The run whose trace to replay (from a prior taskflow_run)." },
+                json: { type: "boolean", description: "Return the full ReplayReport as JSON." },
+                budgetMaxUSD: { type: "number", description: "Alternate max USD budget for would-exceed-budget checks." },
+                budgetMaxTokens: { type: "number", description: "Alternate max token budget." },
+                thresholds: {
+                    type: "object",
+                    additionalProperties: { type: "number" },
+                    description: "Map of phaseId → new score threshold (re-judges recorded gate-score events).",
+                },
+                models: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "Map of phaseId → model id (currently marks needs-live-rerun; quality cannot be re-judged offline).",
+                },
             },
             required: ["runId"],
         },
@@ -291,6 +479,24 @@ const TOOLS = [
             required: ["runId", "phaseId"],
         },
     },
+    {
+        name: "taskflow_reconcile_workspace",
+        title: "Acknowledge and reconcile the invocation workspace",
+        description: "Explicitly accept the current external filesystem state after a resolve-only writer failed with an unknown outcome. This does not restore files or prove correctness: inspect or repair the workspace first. The host operator must also launch Taskflow with TASKFLOW_WORKSPACE_RECONCILE_MODE=explicit. Reconciliation takes an exclusive whole-root lease, durably clears dirty-unknown intents, and advances the workspace generation.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                acknowledgement: {
+                    type: "string",
+                    enum: [WORKSPACE_RECONCILE_ACKNOWLEDGEMENT],
+                    description: `Must exactly equal: ${WORKSPACE_RECONCILE_ACKNOWLEDGEMENT}`,
+                },
+                reason: { type: "string", description: "Short audit reason describing what was inspected or repaired." },
+            },
+            required: ["acknowledgement"],
+        },
+    },
     {
         name: "taskflow_save",
         title: "Save a reusable taskflow",
@@ -328,9 +534,43 @@ const TOOLS = [
     },
 ];
 /** Resolve a flow from params: inline `define` (desugared), `defineFile` (disk), or saved `name`. */
+function resolvePermittedDefineFile(cwd, requested) {
+    const lexical = resolve(cwd, requested);
+    let candidate = lexical;
+    try {
+        candidate = realpathSync(lexical);
+    }
+    catch {
+        // Keep the lexical path so a permitted-but-missing file still receives the
+        // normal "not found" diagnostic from readDefineFile. Resolve its existing
+        // parent so aliases such as macOS /tmp -> /private/tmp remain contained.
+        try {
+            candidate = join(realpathSync(dirname(lexical)), basename(lexical));
+        }
+        catch { /* parent missing */ }
+    }
+    const rootCandidates = [cwd, tmpdir(), ...(process.platform === "win32" ? [] : ["/tmp"])]
+        .map((root) => {
+        try {
+            return realpathSync(resolve(root));
+        }
+        catch {
+            return resolve(root);
+        }
+    });
+    const allowed = rootCandidates.some((root) => {
+        const rel = relative(root, candidate);
+        return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    });
+    if (!allowed) {
+        throw new RpcError(RPC.INVALID_PARAMS, `defineFile must be contained in the server cwd or OS temp directory: ${requested}`);
+    }
+    return candidate;
+}
 function resolveFlow(cwd, params) {
     if (params.define === undefined && typeof params.defineFile === "string" && params.defineFile.trim()) {
-        const fromFile = readDefineFile(params.defineFile);
+        const filePath = resolvePermittedDefineFile(cwd, params.defineFile);
+        const fromFile = readDefineFile(filePath);
         if (!fromFile.ok)
             throw new RpcError(RPC.INVALID_PARAMS, describeLoadFailure(fromFile, "defineFile"));
         params = { ...params, define: fromFile.value };
@@ -357,8 +597,18 @@ function mkRunState(def, args, cwd) {
         createdAt: Date.now(),
         updatedAt: Date.now(),
         cwd,
+        invocationRootSnapshot: directoryIdentity(cwd),
     };
 }
+export function persistTerminalRun(state, cleanupConfig, write = saveRun) {
+    try {
+        write(state, cleanupConfig);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 /**
  * Build the per-call tool handlers. `cwd` is the directory the server was
  * launched in (where saved flows + agents are discovered, and where subagents
@@ -367,11 +617,28 @@ function mkRunState(def, args, cwd) {
  */
 export function makeToolHandlers(cwd, runner) {
     return {
-        taskflow_run: async (args) => {
+        taskflow_run: async (args, context) => {
+            const reusedSavedName = args.define === undefined && args.defineFile === undefined && typeof args.name === "string" && args.name.trim()
+                ? args.name.trim()
+                : undefined;
             const def = resolveFlow(cwd, args);
-            const v = validateTaskflow(def);
-            if (!v.ok)
-                return textContent(`Flow is invalid:\n- ${v.errors.join("\n- ")}`, true);
+            const structural = validateTaskflow(def);
+            if (!structural.ok)
+                return textContent(`Flow is invalid:\n- ${structural.errors.join("\n- ")}`, true);
+            const providedArgs = args.args && typeof args.args === "object" && !Array.isArray(args.args)
+                ? args.args
+                : {};
+            const resolvedArgs = resolveArgs(def, providedArgs);
+            const invocation = validateTaskflow(def, { args: resolvedArgs, cwd });
+            if (!invocation.ok)
+                return textContent(`Flow invocation is invalid:\n- ${invocation.errors.join("\n- ")}`, true);
+            const usageAccounting = runner.usageAccounting;
+            if (def.budget && usageAccounting === "unavailable") {
+                return textContent("This host does not report token or cost usage, so taskflow refuses to run a budgeted flow: the declared ceiling could not be enforced. Remove `budget` only if unmetered execution is intentional, or use a host with usage accounting.", true);
+            }
+            if (def.budget?.maxUSD !== undefined && usageAccounting === "tokens-only") {
+                return textContent("This host reports token usage but not cost, so taskflow refuses budget.maxUSD: the declared dollar ceiling could not be enforced. Use budget.maxTokens or a host with cost accounting.", true);
+            }
             // Resolve model roles (e.g. {{fast}} -> a real model id) so the built-in
             // agents' placeholder models map to something the host can launch. This is
             // the same lookup the pi adapter does; without it every phase fails with
@@ -382,8 +649,11 @@ export function makeToolHandlers(cwd, runner) {
                 cwd,
                 agents,
                 runTask: runner.runTask,
+                signal: context?.signal,
+                usageAccounting,
+                cwdBridgeMode: cwdBridgeModeFromEnv(),
             };
-            const state = mkRunState(def, args.args ?? {}, cwd);
+            const state = mkRunState(def, resolvedArgs, cwd);
             // Deterministic-replay trace (best-effort, fail-open).
             deps.trace = new FileTraceSink(traceFilePath(runsDir(cwd), state.flowName, state.runId));
             if (args.incremental === true)
@@ -399,19 +669,18 @@ export function makeToolHandlers(cwd, runner) {
                     saveRun(s, cleanupConfig);
                 }
             };
+            let terminalPersistError;
             const res = await executeTaskflow(state, deps).finally(() => {
                 // Terminal persist must survive a throwing runtime ("never lose work") —
                 // and persistence itself must never sink a completed run.
-                try {
-                    saveRun(state, cleanupConfig);
-                }
-                catch {
-                    /* fail-open */
-                }
+                terminalPersistError = persistTerminalRun(state, cleanupConfig);
             });
-            if (res.ok && args.reusedFromSearch === true && typeof args.name === "string" && args.name.trim()) {
+            if (terminalPersistError !== undefined) {
+                return textContent(`Taskflow execution finished, but terminal run persistence failed; no durable run ID can be promised: ${terminalPersistError}`, true);
+            }
+            if (res.ok && args.reusedFromSearch === true && reusedSavedName) {
                 try {
-                    bumpReuseInSidecar(cwd, args.name);
+                    bumpReuseInSidecar(cwd, reusedSavedName);
                 }
                 catch {
                     /* fail-open: reuse bookkeeping is best-effort */
@@ -446,8 +715,25 @@ export function makeToolHandlers(cwd, runner) {
             if (events.length === 0)
                 return textContent(`No trace recorded for run "${runId}" (the run predates tracing, or no trace sink was injected).`, true);
             if (args.json === true)
-                return textContent(JSON.stringify(events, null, 2));
-            return textContent(formatTraceMcp(events, run.runId, run.flowName));
+                return textContent(formatTraceJsonMcp(events, args.limit));
+            return textContent(formatTraceMcp(events, run.runId, run.flowName, args.limit));
+        },
+        taskflow_replay: async (args) => {
+            const runId = String(args.runId ?? "");
+            if (!runId)
+                return textContent("taskflow_replay requires `runId`.", true);
+            const runR = loadRunDiagnosed(cwd, runId);
+            if (!runR.ok)
+                return textContent(describeLoadFailure(runR, `Run "${runId}"`), true);
+            const run = runR.value;
+            const raw = readTrace(traceFilePath(runsDir(cwd), run.flowName, run.runId));
+            if (raw.length === 0)
+                return textContent(`No trace recorded for run "${runId}" (the run predates tracing, or no trace sink was injected).`, true);
+            const events = raw.map((e) => upgradeTraceEvent(e));
+            const report = replayRun(events, parseReplayOverrides(args));
+            if (args.json === true)
+                return textContent(JSON.stringify(report, null, 2));
+            return textContent(formatReplayMcp(report, run.runId, run.flowName));
         },
         taskflow_why_stale: async (args) => {
             const runId = String(args.runId ?? "");
@@ -462,7 +748,7 @@ export function makeToolHandlers(cwd, runner) {
             const seeds = typeof args.phaseId === "string" ? [args.phaseId] : [];
             return textContent(formatWhyStale(run.runId, run.flowName, reads, seeds, declared));
         },
-        taskflow_recompute: async (args) => {
+        taskflow_recompute: async (args, context) => {
             // MCP exposes recompute as DRY-RUN ONLY (never spends tokens). To actually
             // re-execute, hosts use the Pi adapter's /tf recompute --apply.
             const runId = String(args.runId ?? "");
@@ -475,10 +761,30 @@ export function makeToolHandlers(cwd, runner) {
             const run = runR.value;
             const settings = readSubagentSettings();
             const { agents } = discoverAgents(cwd, "both", settings.modelRoles, settings.taskflow);
-            const deps = { cwd, agents, runTask: runner.runTask };
+            const deps = { cwd, agents, runTask: runner.runTask, signal: context?.signal };
             const { report } = await recomputeTaskflow(run, deps, [phaseId], { dryRun: true });
             return textContent(formatRecomputeMcp(report));
         },
+        taskflow_reconcile_workspace: async (args, context) => {
+            try {
+                const result = await reconcileResolveOnlyWorkspace({
+                    invocationRoot: cwd,
+                    signal: context?.signal,
+                    allowReconcile: workspaceReconcileAllowedFromEnv(),
+                }, {
+                    acknowledgement: String(args.acknowledgement ?? ""),
+                    reason: typeof args.reason === "string" ? args.reason : undefined,
+                    signal: context?.signal,
+                });
+                const changed = result.reconciledIntentIds.length;
+                return textContent(changed === 0
+                    ? `Workspace is already clean at generation ${result.generation}; no dirty intent was changed.`
+                    : `Workspace reconciled: ${changed} dirty intent(s) accepted; generation ${result.previousGeneration} → ${result.generation}.`);
+            }
+            catch (error) {
+                return textContent(`Workspace reconciliation failed: ${error instanceof Error ? error.message : String(error)}`, true);
+            }
+        },
         taskflow_list: async () => {
             const flows = listFlows(cwd);
             if (flows.length === 0)
@@ -672,13 +978,17 @@ export function makeMcpHandlers(cwd, runner) {
         },
         ping: () => ({}),
         "tools/list": () => ({ tools: TOOLS }),
-        "tools/call": async (params) => {
+        "tools/call": async (params, context) => {
             const p = (params ?? {});
             const tool = tools[p.name ?? ""];
             if (!tool)
                 throw new RpcError(RPC.INVALID_PARAMS, `Unknown tool: ${p.name}`);
+            const descriptor = TOOLS.find((candidate) => candidate.name === p.name);
+            if (!descriptor)
+                throw new RpcError(RPC.INVALID_PARAMS, `Unknown tool schema: ${p.name}`);
+            const args = validateToolArguments(descriptor, p.arguments);
             void initialized; // tolerant: we don't hard-gate on initialize ordering
-            return await tool(p.arguments ?? {});
+            return await tool(args, context);
         },
     };
 }