@hegemonart/get-design-done 1.31.0 → 1.32.0

package/sdk/mcp/gdd-mcp/server.ts

@@ -0,0 +1,325 @@
+#!/usr/bin/env -S node --experimental-strip-types
+// sdk/mcp/gdd-mcp/server.ts
+//
+// MCP server `gdd-mcp` — read-mostly project-state surface (Phase 27.7).
+// Exposes STATE.md sections, phases, decisions, plans, telemetry, intel
+// slices, and the latest reflection as typed MCP tools backed by the
+// same `scripts/lib/*` + `sdk/*` modules the CLI uses.
+// (Moved from scripts/mcp-servers/gdd-mcp/ to sdk/mcp/gdd-mcp/ in Plan
+//  31-5-05 for MCP-server symmetry with sdk/mcp/gdd-state/ — D-08.)
+//
+// Lifecycle (mirrors Phase 20 `gdd-state` server):
+//   1. Construct a low-level Server (we use the low-level surface so we
+//      can speak JSON Schema directly — the high-level McpServer wants
+//      Zod shapes, and our per-tool schemas are Draft-07 JSON.)
+//   2. Register `tools/list` — returns the registered tools with their
+//      input JSON Schemas loaded from disk. Scaffold ships with 0
+//      tools; Plan 27.7-02 populates `TOOL_MODULES` with 12 entries.
+//   3. Register `tools/call` — dispatches by name to the matching
+//      handler. Each handler returns a typed ToolResponse; the server
+//      wraps it into the MCP CallToolResult shape. Unknown tool names
+//      return `isError: true` with a structured payload.
+//   4. Attach StdioServerTransport; await connect. NO port allocation
+//      (D-05 stdio-only).
+//   5. On SIGINT / SIGTERM: close the transport, exit 0. Re-entrant
+//      shutdown is guarded with a module-level `SHUTTING_DOWN` flag.
+//
+// Project-root discovery (D-05): `resolveProjectRoot()` lives in
+// `./tools/shared.ts` and walks up from `process.cwd()` looking for
+// `.design/` OR `.planning/` OR `.claude-plugin/plugin.json`. Server
+// infrastructure is allowed to import `node:fs`/`node:path` directly;
+// only individual TOOL files are bound by the thin-wrapper rule (D-06).
+//
+// Invariant: handler throws are contained. The dispatcher wraps every
+// call in a try/catch that funnels through `toToolError()` — the MCP
+// harness never sees an uncaught throw from our tools.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { toToolError } from '../../errors/classification.ts';
+import { TOOL_MODULES, type ToolModule } from './tools/index.ts';
+
+/** Server metadata advertised on initialize. */
+export const SERVER_NAME = 'gdd-mcp';
+export const SERVER_VERSION = '1.27.7';
+
+/**
+ * Resolve this module's directory. We deliberately avoid `import.meta.url`
+ * (not permitted by our tsconfig's Node16+CommonJS-compatible module
+ * resolution) and `__dirname` (not portable under strip-types ESM).
+ *
+ * Strategy: when this module is invoked as a script, `process.argv[1]`
+ * points at this file; resolve its dirname. When it is imported for
+ * tests, we fall back to walking from `process.cwd()` — tests run
+ * from the repo root by convention, so `sdk/mcp/gdd-mcp`
+ * resolves reliably. Both branches are canonicalized against the
+ * on-disk tools directory.
+ */
+function here(): string {
+  const expectedRel = join('sdk', 'mcp', 'gdd-mcp');
+  // Script invocation: process.argv[1] === .../server.ts (or a shim).
+  const entry = process.argv[1];
+  if (typeof entry === 'string' && entry.length > 0) {
+    const entryDir = dirname(resolve(entry));
+    if (existsSync(join(entryDir, 'tools', 'index.ts'))) {
+      return entryDir;
+    }
+  }
+  // Library-import path (tests): walk cwd forward.
+  const candidate = resolve(process.cwd(), expectedRel);
+  if (existsSync(join(candidate, 'tools', 'index.ts'))) {
+    return candidate;
+  }
+  // Last-resort: return the expected path even if it does not exist —
+  // the subsequent readFileSync() call will produce a clear error.
+  return candidate;
+}
+
+/** Eager cache of input schemas keyed by tool name. We load them once at
+ *  startup so a tool-call handler never hits the filesystem in the hot
+ *  path; subsequent schema edits (JSON file on disk) require a server
+ *  restart, which matches every other part of the pipeline.
+ *
+ *  Scaffold ships with 0 tools — loadTools() returns []. Plan 27.7-02
+ *  adds 12 tool modules, each with its own `schemaPath` pointing into
+ *  `sdk/mcp/gdd-mcp/schemas/`. */
+interface LoadedTool extends ToolModule {
+  inputSchema: Record<string, unknown>;
+}
+
+function loadTools(): LoadedTool[] {
+  const baseDir = here();
+  return TOOL_MODULES.map((m) => {
+    const absPath = join(baseDir, 'tools', m.schemaPath);
+    const raw = readFileSync(absPath, 'utf8');
+    const parsed = JSON.parse(raw) as {
+      properties?: {
+        input?: { type?: string; properties?: Record<string, unknown> };
+      };
+    };
+    // The per-tool schema files are Draft-07 wrappers shaped as:
+    //   { type: "object", properties: { input: {...}, output: {...} } }
+    // MCP's tools/list advertises only the INPUT half. We project
+    // `properties.input` here; when the schema is malformed we fall
+    // back to an open object so the tool is still listable.
+    const rawInput = parsed.properties?.input;
+    const inputSchema: Record<string, unknown> =
+      rawInput !== undefined && typeof rawInput === 'object'
+        ? (rawInput as Record<string, unknown>)
+        : { type: 'object' };
+    if (!('type' in inputSchema)) inputSchema['type'] = 'object';
+    return { ...m, inputSchema };
+  });
+}
+
+/**
+ * Tool descriptions — short, scannable, lifted from the plan. Skill
+ * prose uses these verbatim when suggesting a tool to the model.
+ *
+ * Plan 27.7-02 populates 12 entries — one per tool name in the canonical
+ * 12-tool list.
+ */
+export const TOOL_DESCRIPTIONS: Record<string, string> = {
+  gdd_status:
+    'gdd_status: current cycle phase, branch, last-3 decisions, last-3 completed plans, blocker count.',
+  gdd_phase_current:
+    'gdd_phase_current: STATE.md <position> block (phase, stage, task_progress, status).',
+  gdd_phases_list:
+    'gdd_phases_list: parsed ROADMAP.md overview (phase number, name, target version, shipped/planned).',
+  gdd_plans_list:
+    'gdd_plans_list: plans tracked in STATE.md must_haves (optionally filtered by input.phase).',
+  gdd_decisions_list:
+    'gdd_decisions_list: decisions from STATE.md (optionally filtered by input.status).',
+  gdd_intel_get:
+    'gdd_intel_get: read a slice from .design/intel/ (input.slice_id required); directory_not_found if absent.',
+  gdd_telemetry_query:
+    'gdd_telemetry_query: typed reader over .design/telemetry/*.jsonl with type/since/limit filters.',
+  gdd_cycle_recap:
+    'gdd_cycle_recap: diff current STATE against latest .design/snapshots/ snapshot; directory_not_found if absent.',
+  gdd_reflections_latest:
+    'gdd_reflections_latest: newest .design/reflections/ file (excerpt <= 4 KB); directory_not_found if absent.',
+  gdd_learnings_digest:
+    'gdd_learnings_digest: aggregate last N reflections into a compact digest (<= 5 KB).',
+  gdd_events_tail:
+    'gdd_events_tail: last-N events from .design/telemetry/events.jsonl with optional type filter.',
+  gdd_health:
+    'gdd_health: read-only mirror of gdd-health SKILL — 4 checks (CLAUDE.md, .planning/, .design/, package.json).',
+};
+
+/** Human-readable annotation hints (MCP clients use these to style the
+ *  tool in UI). `readOnlyHint: true` — tells clients this tool does NOT
+ *  modify disk. v1 is read-only (D-04) so every entry is `true`. */
+export const TOOL_READONLY: Record<string, boolean> = {
+  gdd_status: true,
+  gdd_phase_current: true,
+  gdd_phases_list: true,
+  gdd_plans_list: true,
+  gdd_decisions_list: true,
+  gdd_intel_get: true,
+  gdd_telemetry_query: true,
+  gdd_cycle_recap: true,
+  gdd_reflections_latest: true,
+  gdd_learnings_digest: true,
+  gdd_events_tail: true,
+  gdd_health: true,
+};
+
+/**
+ * Build the MCP server. The tools list and call handlers are the only
+ * two request handlers we register; everything else (initialize, ping,
+ * cancellation, shutdown) is handled internally by the Protocol class.
+ */
+export function buildServer(): Server {
+  const tools = loadTools();
+  const byName: Map<string, LoadedTool> = new Map();
+  for (const t of tools) byName.set(t.name, t);
+
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      capabilities: { tools: {} },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map((t) => {
+        const description = TOOL_DESCRIPTIONS[t.name] ?? t.name;
+        const readOnly = TOOL_READONLY[t.name] ?? true;
+        return {
+          name: t.name,
+          description,
+          inputSchema: t.inputSchema as {
+            type: 'object';
+            properties?: Record<string, unknown>;
+            required?: string[];
+          },
+          annotations: {
+            readOnlyHint: readOnly,
+            destructiveHint: !readOnly,
+            idempotentHint: false,
+          },
+        };
+      }),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name: toolName, arguments: args } = req.params;
+    const tool = byName.get(toolName);
+    if (tool === undefined) {
+      // Unknown tool — return as CallToolResult isError=true so the
+      // client gets a structured error rather than a JSON-RPC error.
+      const payload = toToolError(
+        new Error(`unknown tool: ${toolName}`),
+      );
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({ success: false, error: payload.error }),
+          },
+        ],
+        structuredContent: { success: false, error: payload.error },
+      };
+    }
+
+    let response;
+    try {
+      response = await tool.handle(args ?? {});
+    } catch (err) {
+      // Defensive catch — handlers shouldn't throw, but if one does
+      // we translate rather than crashing the server.
+      const payload = toToolError(err);
+      response = { success: false as const, error: payload.error };
+    }
+
+    const text = JSON.stringify(response);
+    if (response.success === true) {
+      return {
+        content: [{ type: 'text' as const, text }],
+        structuredContent: response as unknown as Record<string, unknown>,
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text' as const, text }],
+      structuredContent: response as unknown as Record<string, unknown>,
+    };
+  });
+
+  return server;
+}
+
+/**
+ * Run the server against stdio and block until the transport closes.
+ * Called from CLI when this file is invoked as a script.
+ */
+export async function runStdio(): Promise<void> {
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+
+  const shutdown = async (signal: string): Promise<void> => {
+    // Re-entrant: signal handlers can fire more than once on flaky
+    // shells. Guard with a module-level flag.
+    if (SHUTTING_DOWN) return;
+    SHUTTING_DOWN = true;
+    try {
+      await server.close();
+    } catch {
+      // best-effort; we're exiting anyway.
+    }
+    // SIGTERM / SIGINT convention: exit(0) — orderly shutdown.
+    process.exit(signal === 'SIGTERM' ? 0 : 0);
+  };
+
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+
+  await server.connect(transport);
+}
+
+/** Re-entrancy guard for `shutdown()`. */
+let SHUTTING_DOWN = false;
+
+/**
+ * Are we being invoked as a script? We compare the argv[1] file path's
+ * basename to `server.ts` — test imports never match this because
+ * `node --test tests/*.ts` sets argv[1] to the test runner entry, not
+ * our file. A direct `node sdk/mcp/gdd-mcp/server.ts`
+ * invocation DOES match. The Windows-safe path normalization uses
+ * `.replace(/\\/g, '/')` before the endsWith check.
+ */
+// Extension-agnostic (.ts | .js | .cjs | .mjs): the dual-mode bin trampoline
+// (Plan 31-5-9.5, D-16) runs the raw `.ts` in-repo via --experimental-strip-types
+// AND the esbuild-bundled `.js` from a packed/installed tarball. argv[1] ends in
+// `.js` in the compiled path, so a `.ts`-only check would never start the server.
+function isMain(): boolean {
+  const entry = process.argv[1];
+  if (typeof entry !== 'string' || entry.length === 0) return false;
+  return /sdk\/mcp\/gdd-mcp\/server\.(ts|js|cjs|mjs)$/.test(
+    entry.replace(/\\/g, '/'),
+  );
+}
+
+if (isMain()) {
+  runStdio().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    // eslint-disable-next-line no-console
+    console.error(`[gdd-mcp] fatal: ${msg}`);
+    process.exit(1);
+  });
+}

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_cycle_recap.ts

@@ -1,10 +1,10 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_cycle_recap.ts
+// sdk/mcp/gdd-mcp/tools/gdd_cycle_recap.ts
 //
 // Plan 27.7-02. Diffs current STATE.md against the latest .design/snapshots/
 // snapshot. SnapshotNotFoundError → directory_not_found via errorResponse.
 
-import { read } from '../../../lib/gdd-state/index.ts';
-import { readLatestSnapshot } from '../../../lib/snapshot-reader/index.cjs';
+import { read } from '../../../state/index.ts';
+import { readLatestSnapshot } from '../../../../scripts/lib/snapshot-reader/index.cjs';
 import { errorResponse, okResponse, resolveProjectRoot, resolveStatePath, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_cycle_recap';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_decisions_list.ts

@@ -1,9 +1,9 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_decisions_list.ts
+// sdk/mcp/gdd-mcp/tools/gdd_decisions_list.ts
 //
 // Plan 27.7-02. Reads <decisions> block from STATE.md. Optional
 // input.status filter narrows the list to one DecisionStatus.
 
-import { read } from '../../../lib/gdd-state/index.ts';
+import { read } from '../../../state/index.ts';
 import {
   errorResponse,
   okResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_events_tail.ts

@@ -1,9 +1,9 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_events_tail.ts
+// sdk/mcp/gdd-mcp/tools/gdd_events_tail.ts
 //
 // Plan 27.7-02. Last-N events from .design/telemetry/events.jsonl with
-// optional type filter. Uses scripts/lib/event-stream readEvents.
+// optional type filter. Uses sdk/event-stream readEvents.
 
-import { readEvents } from '../../../lib/event-stream/index.ts';
+import { readEvents } from '../../../event-stream/index.ts';
 import { errorResponse, okResponse, resolveTelemetryDir, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_events_tail';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_health.ts

@@ -1,9 +1,9 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts
+// sdk/mcp/gdd-mcp/tools/gdd_health.ts
 //
 // Plan 27.7-02 (lib renamed to health-mirror in Phase 30.6-08 per D-10).
 // Read-only mirror of skills/health/SKILL.md output. No subprocess spawn — pure inspection.
 
-import { getHealthChecks } from '../../../lib/health-mirror/index.cjs';
+import { getHealthChecks } from '../../../../scripts/lib/health-mirror/index.cjs';
 import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_health';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_intel_get.ts

@@ -1,10 +1,10 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_intel_get.ts
+// sdk/mcp/gdd-mcp/tools/gdd_intel_get.ts
 //
 // Plan 27.7-02. Reads a .design/intel/ slice via scripts/lib/intel-store/
 // (Warning #7: NOT design-search.cjs). IntelNotFoundError surfaces
 // gracefully via errorResponse's mcp_code projection (Warning #5).
 
-import { readSlice } from '../../../lib/intel-store/index.cjs';
+import { readSlice } from '../../../../scripts/lib/intel-store/index.cjs';
 import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_intel_get';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_learnings_digest.ts

@@ -1,9 +1,9 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_learnings_digest.ts
+// sdk/mcp/gdd-mcp/tools/gdd_learnings_digest.ts
 //
 // Plan 27.7-02. Aggregates last N reflections into a <= 5 KB digest
 // via scripts/lib/reflections-reader/.
 
-import { readNReflections, digestReflections } from '../../../lib/reflections-reader/index.cjs';
+import { readNReflections, digestReflections } from '../../../../scripts/lib/reflections-reader/index.cjs';
 import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_learnings_digest';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_phase_current.ts

@@ -1,8 +1,8 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_phase_current.ts
+// sdk/mcp/gdd-mcp/tools/gdd_phase_current.ts
 //
 // Plan 27.7-02. Returns the <position> block from STATE.md.
 
-import { read } from '../../../lib/gdd-state/index.ts';
+import { read } from '../../../state/index.ts';
 import {
   errorResponse,
   okResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_phases_list.ts

@@ -1,11 +1,11 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_phases_list.ts
+// sdk/mcp/gdd-mcp/tools/gdd_phases_list.ts
 //
 // Plan 27.7-02. Parses .planning/ROADMAP.md via scripts/lib/roadmap-reader.
 
 import {
   readRoadmapMd,
   parsePhases,
-} from '../../../lib/roadmap-reader/index.cjs';
+} from '../../../../scripts/lib/roadmap-reader/index.cjs';
 import {
   errorResponse,
   okResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_plans_list.ts

@@ -1,11 +1,11 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_plans_list.ts
+// sdk/mcp/gdd-mcp/tools/gdd_plans_list.ts
 //
 // Plan 27.7-02. STATE.md does not have a dedicated <plans> block — we
 // surface must_haves as the closest analog (the per-plan acceptance
 // criteria the pipeline tracks). Input.phase is reserved for future
 // multi-phase indexing.
 
-import { read } from '../../../lib/gdd-state/index.ts';
+import { read } from '../../../state/index.ts';
 import {
   errorResponse,
   okResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_reflections_latest.ts

@@ -1,10 +1,10 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_reflections_latest.ts
+// sdk/mcp/gdd-mcp/tools/gdd_reflections_latest.ts
 //
 // Plan 27.7-02. Reads newest reflection under .design/reflections/.
 // ReflectionsNotFoundError surfaces as mcp_code='directory_not_found'
 // via errorResponse (Warning #5).
 
-import { readLatestReflection } from '../../../lib/reflections-reader/index.cjs';
+import { readLatestReflection } from '../../../../scripts/lib/reflections-reader/index.cjs';
 import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_reflections_latest';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_status.ts

@@ -1,9 +1,9 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_status.ts
+// sdk/mcp/gdd-mcp/tools/gdd_status.ts
 //
-// Plan 27.7-02. Thin wrapper over scripts/lib/gdd-state. NO fs/path
+// Plan 27.7-02. Thin wrapper over sdk/state. NO fs/path
 // imports here — all I/O via gdd-state.read() + shared.ts helpers.
 
-import { read } from '../../../lib/gdd-state/index.ts';
+import { read } from '../../../state/index.ts';
 import {
   errorResponse,
   okResponse,

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/gdd_telemetry_query.ts

@@ -1,9 +1,9 @@
-// scripts/mcp-servers/gdd-mcp/tools/gdd_telemetry_query.ts
+// sdk/mcp/gdd-mcp/tools/gdd_telemetry_query.ts
 //
 // Plan 27.7-02. Typed reader over .design/telemetry/*.jsonl via
-// scripts/lib/event-stream/index.ts readEvents.
+// sdk/event-stream/index.ts readEvents.
 
-import { readEvents } from '../../../lib/event-stream/index.ts';
+import { readEvents } from '../../../event-stream/index.ts';
 import { errorResponse, okResponse, resolveTelemetryDir, type ToolResponse } from './shared.ts';
 
 export const name = 'gdd_telemetry_query';

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/index.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-mcp/tools/index.ts
+// sdk/mcp/gdd-mcp/tools/index.ts
 //
 // Tool registry for `gdd-mcp`. Plan 27.7-02 populates with 12 read-only
 // tools. The 12-tool cap is D-03 (hard); enforced at module load by a
@@ -8,7 +8,7 @@
 //   - Each tool exports `name`, `schemaPath`, and `handle` from its own
 //     module (e.g. `./gdd_status.ts`).
 //   - `schemaPath` is relative to THIS file's directory and points into
-//     `scripts/mcp-servers/gdd-mcp/schemas/`. Server.ts joins it
+//     `sdk/mcp/gdd-mcp/schemas/`. Server.ts joins it
 //     against `<baseDir>/tools/` to load the Draft-07 JSON.
 //   - `TOOL_MODULES` is the canonical registry — server.ts iterates it
 //     once at startup to populate the dispatch map.

package/{scripts/mcp-servers → sdk/mcp}/gdd-mcp/tools/shared.ts

@@ -1,4 +1,4 @@
-// scripts/mcp-servers/gdd-mcp/tools/shared.ts
+// sdk/mcp/gdd-mcp/tools/shared.ts
 //
 // Shared helpers for gdd-mcp tools. resolveProjectRoot() implements the
 // D-05 walk-up algorithm: scan from process.cwd() upward looking for
@@ -15,8 +15,8 @@
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
-import { toToolError } from '../../../lib/gdd-errors/classification.ts';
-import type { ToolErrorPayload } from '../../../lib/gdd-errors/classification.ts';
+import { toToolError } from '../../../errors/classification.ts';
+import type { ToolErrorPayload } from '../../../errors/classification.ts';
 
 /** Public tool-handler response shape (consistent across all tools). */
 export type ToolResponse =