@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/mcp_server/prompts.ts

@@ -72,10 +72,16 @@ export interface SkillPrompt {
 }
 
 /** Walk up from this file to the repo root (parent of `scripts/`). */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 export function _project_root(): string {
     // Python: Path(__file__).resolve().parent.parent.parent.parent
     //   __file__ = src/scripts/mcp_server/prompts.py
     //   → .../src/scripts/mcp_server → src/scripts → src → repo root.
+    // Bundled (dist/mcp/server.mjs) the module sits two levels below the
+    // package root — the esbuild --define sentinel picks the right depth.
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+    }
     return path.resolve(fileURLToPath(import.meta.url), '..', '..', '..', '..');
 }
 

package/src/scripts/mcp_server/tool_catalog_source.ts

@@ -0,0 +1,332 @@
+// Source-of-truth data for `../build_mcp_catalog.ts` (Phase 3 of
+// road-to-credible-install — MCP hygiene: generated truth, honest stubs).
+//
+// `consumer_tool_catalog.json` used to be hand-maintained: every tool's
+// name/description/input_schema had to be kept in sync by hand across the
+// JSON file AND its real handler registration in `tools.ts`. The generator
+// derives the JSON from two registries instead of a third hand-edited copy:
+//
+//   - Implemented tools — `ALLOWLIST` in `./tools.ts`. Name, description,
+//     input_schema, and side_effect all live on the handler registration
+//     itself; the generator reads them directly.
+//   - Stub-only tools — `STUB_TOOLS` below. Catalog-listed discovery
+//     placeholders with no wired handler (or, for `catalog_search` /
+//     `catalog_inspect` / `catalog_load`, a handler that exists in
+//     `catalog_tools.ts` but is deliberately not promoted into ALLOWLIST
+//     yet — see the file header there). These have no other natural home
+//     in the codebase, so their metadata is authored here.
+//
+// Never hand-edit `consumer_tool_catalog.json` — run
+// `npm run build:mcp-catalog` (or `./scripts-run src/scripts/build_mcp_catalog
+// --write`) after changing a tool's registration or a `STUB_TOOLS` entry.
+import type { ToolSideEffect } from './tools.js';
+
+export type { ToolSideEffect };
+
+/** Free-text top-level `description` field. Human-facing only. */
+export const CATALOG_DESCRIPTION =
+    'Source-of-truth catalog of consumer-relevant MCP tools. Read by the ' +
+    'stdio server (scripts/mcp_server/) and packed into the Cloud Worker ' +
+    "bundle (internal/workers/mcp/). The 'implemented_on' field lists " +
+    'transports where the real handler is wired. Entries marked ' +
+    "'[stub — implemented on demand]' are DOCUMENTATION of the on-demand " +
+    'backlog: per ADR-132 they are NOT registered on the stdio tools/list ' +
+    "(the wire carries implemented tools only); the 'not_implemented' " +
+    'envelope contract (docs/contracts/mcp-tool-stub-envelope.md) remains ' +
+    'for Worker parity. Generated by `src/scripts/build_mcp_catalog.ts` — ' +
+    'never hand-edit this file.';
+
+export interface StubToolSource {
+    readonly name: string;
+    readonly description: string;
+    readonly side_effect: ToolSideEffect;
+    readonly input_schema: Record<string, unknown>;
+}
+
+/**
+ * Catalog-only tools with no wired ALLOWLIST handler. `implemented_on` is
+ * always `[]` for these — the generator adds the `[stub — implemented on
+ * demand]` description marker and omits `annotations` (no real behavior to
+ * annotate).
+ */
+export const STUB_TOOLS: readonly StubToolSource[] = [
+    {
+        name: 'skill_trigger_eval',
+        description:
+            'Score a user message against the compiled router and return ' +
+            'the skills whose triggers match, each with the reason it ' +
+            'fired. Use to predict which skills a given message would ' +
+            'activate, for debugging trigger coverage. Read-only and ' +
+            'deterministic. Returns a ranked list of matching skills with ' +
+            'their trigger reasons.',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: 'The user message to score against skill triggers.' },
+                context: { type: 'string', description: 'Optional recent-turn context to sharpen the match.' },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    default: 5,
+                    description: 'Maximum number of matching skills to return. Defaults to 5.',
+                },
+            },
+            required: ['message'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'suggest_command',
+        description:
+            'Run the command-suggestion engine: score the available slash ' +
+            'commands against a user message and context, and return a ' +
+            'ranked, numbered-options block of the best matches. Use to ' +
+            'recommend a command for a free-form request without invoking ' +
+            'anything. Read-only and deterministic. Returns the formatted ' +
+            'suggestion block plus the scored candidates.',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: 'The user message to match commands against.' },
+                context: { type: 'string', description: 'Optional recent-turn context to sharpen the match.' },
+            },
+            required: ['message'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'suggest_skill_for_task',
+        description:
+            'Match a free-form task description to the most relevant ' +
+            'skills, ranked by their frontmatter triggers. Use to pick a ' +
+            'skill for a described task before starting work. Read-only. ' +
+            'Returns a ranked list of skills with name, description, and ' +
+            'match reason.',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                task: { type: 'string', description: 'Free-form description of the task to find a skill for.' },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    default: 5,
+                    description: 'Maximum number of skills to return. Defaults to 5.',
+                },
+            },
+            required: ['task'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'mine_session',
+        description:
+            'Extract reusable patterns, decisions, and learnings from a ' +
+            'single chat-history session, as candidate memory entries. Use ' +
+            'to distill a finished session into durable memory before it ' +
+            'ages out. Read-only. Returns the mined candidates grouped by ' +
+            'kind.',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                session: { type: 'string', description: 'Session id to mine.' },
+                path: {
+                    type: 'string',
+                    description: 'Optional path to a chat-history JSONL; defaults to the standard location.',
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'update_form_request_messages',
+        description:
+            "Synchronise the `messages()` method of a Laravel FormRequest " +
+            'class: add entries for validation rules that lack a custom ' +
+            'message, link them to translation keys, and drop stale ones. ' +
+            "Use after changing a FormRequest's `rules()`. Edits the class " +
+            'file on disk and returns the planned or applied message ' +
+            'changes. Set `dry_run: true` to preview the diff without ' +
+            'writing.',
+        side_effect: 'fs-write',
+        input_schema: {
+            type: 'object',
+            properties: {
+                request_class: {
+                    type: 'string',
+                    description: 'Fully-qualified FormRequest class FQN or repo-relative file path.',
+                },
+                dry_run: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'When true, return the planned message changes without editing the file.',
+                },
+            },
+            required: ['request_class'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'sync_gitignore',
+        description:
+            'Synchronise the managed `event4u/agent-config` block in the ' +
+            "consumer project's `.gitignore` — add missing canonical " +
+            'entries while preserving user-added lines. Use after ' +
+            'upgrading the package or when generated paths are being ' +
+            'tracked by mistake. Edits `.gitignore` and returns the added ' +
+            '/ removed entries. Set `dry_run: true` to preview the changes.',
+        side_effect: 'fs-write',
+        input_schema: {
+            type: 'object',
+            properties: {
+                dry_run: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'When true, return the planned `.gitignore` changes without writing the file.',
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'sync_agent_settings',
+        description:
+            'Synchronise `.agent-settings.yml` against the current ' +
+            'template and active profile — add new sections and keys ' +
+            'while preserving existing user values. Use after a package ' +
+            'upgrade to pick up newly introduced settings. Edits the ' +
+            'settings file and returns the keys that were (or would be) ' +
+            'added. Set `dry_run: true` to preview.',
+        side_effect: 'fs-write',
+        input_schema: {
+            type: 'object',
+            properties: {
+                profile: { type: 'string', description: 'Override the profile pinned in the settings file.' },
+                dry_run: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'When true, return the planned settings changes without writing the file.',
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'run_quality_checks',
+        description:
+            "Run the consumer project's configured quality gate (PHPStan " +
+            '/ Rector / ECS or the stack equivalent) and return a ' +
+            'structured per-tool result. Use before committing to confirm ' +
+            'static-analysis and style gates pass. Shell-bound. Pass ' +
+            '`tool` to run a single gate; omit to run all.',
+        side_effect: 'shell',
+        input_schema: {
+            type: 'object',
+            properties: {
+                tool: { type: 'string', description: 'Restrict to a single quality tool by name (e.g. phpstan, rector, ecs).' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'compile_router',
+        description:
+            'Regenerate the compiled router (`router.compiled.json`) from ' +
+            'the current rule, skill, and command frontmatter, so ' +
+            'trigger-based routing reflects the latest artifacts. Use ' +
+            "after adding or editing a rule / skill / command's trigger " +
+            'metadata. Shell-bound — wraps `scripts/compile_router.py` — ' +
+            'and returns the regenerated router summary. Set `dry_run: ' +
+            'true` to compute the result without writing the file.',
+        side_effect: 'shell',
+        input_schema: {
+            type: 'object',
+            properties: {
+                dry_run: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'When true, compute the router without writing `router.compiled.json` to disk.',
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'catalog_search',
+        description:
+            "Search the package's own artifact catalog (skills, personas, " +
+            'commands) by free-text query and return ranked summaries — ' +
+            'name, description, tags, score — WITHOUT loading any body. ' +
+            'Use to discover which skill or persona fits a task when the ' +
+            'full catalog is not in context. Read-only, deterministic ' +
+            '(BM25 over an on-disk index). Activation deferred behind a ' +
+            'task-quality A/B (see catalog_tools.ts).',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Free-text search query.' },
+                class: {
+                    type: 'string',
+                    enum: ['skill', 'persona', 'command'],
+                    description: 'Optional: restrict to one artifact class.',
+                },
+                pack: { type: 'string', description: 'Optional: restrict to entries tagged with this pack/domain.' },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    default: 8,
+                    description: 'Maximum results. Defaults to 8.',
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'catalog_inspect',
+        description:
+            'Return the metadata for one catalog entry by id (id, class, ' +
+            'name, description, tags, path). Body is returned ONLY when ' +
+            'include_body is true. Use after catalog_search to look at a ' +
+            'candidate before loading it. Read-only. Activation deferred ' +
+            '(see catalog_search).',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Catalog id, e.g. `skill:api-design` or `persona:backend-architect`.' },
+                include_body: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'When true, include the full body. Defaults to false (metadata only).',
+                },
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'catalog_load',
+        description:
+            'Load the full body of one catalog entry by id, wrapped in a ' +
+            "neutral reference preamble that subordinates it to the user's " +
+            'request and system instructions. Use to bring a ' +
+            'skill/persona/command body into context on demand. Read-only, ' +
+            'path-confined to the package root. Never injects or acts — ' +
+            'the host decides what to do with the body. Activation ' +
+            'deferred (see catalog_search).',
+        side_effect: 'ro',
+        input_schema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Catalog id to load the body for.' },
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+];

package/src/scripts/mcp_server/tools.ts

@@ -30,6 +30,9 @@
 // TS port of the retired Python tools.py (ADR-200). Preserves the full public surface:
 //   STDIO_TRANSPORT, BuiltinTool, ToolHandler, ALLOWLIST, to_mcp_tool_meta,
 //   CATALOG_STUBS, STUB_NAMES, REGISTRY, ToolCache, boot_log_line.
+// TS-only addition (Phase 3 of road-to-credible-install): `ToolSideEffect` +
+// `BuiltinTool.side_effect` — the generated-catalog source of truth for a
+// tool's side-effect classification and `readOnlyHint` annotation.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -77,6 +80,16 @@ export type ToolHandler = (
     consumerRoot: string,
 ) => Promise<Record<string, unknown>>;
 
+/**
+ * Side-effect classification surfaced in `consumer_tool_catalog.json` and
+ * (for implemented tools) as the `readOnlyHint` MCP annotation. `ro` never
+ * writes or spawns; `fs-write` edits the filesystem; `shell` spawns a
+ * subprocess. Single source of truth for a tool's own classification — the
+ * catalog generator (`build_mcp_catalog.ts`) reads it directly off
+ * `ALLOWLIST` rather than a hand-maintained shadow list.
+ */
+export type ToolSideEffect = 'ro' | 'fs-write' | 'shell';
+
 /**
  * Static registration record for an allowlisted MCP tool.
  *
@@ -84,13 +97,16 @@ export type ToolHandler = (
  * each `tools/call`. `handler` is an async function that receives the
  * validated arguments + the resolved `consumer_root` path.
  *
- * Mirrors the Python frozen dataclass `BuiltinTool` (field order
- * preserved).
+ * Shape is pinned by `consumer_tool_catalog.json`: `build_mcp_catalog` derives
+ * the catalog from `ALLOWLIST` here, and `build_mcp_catalog --strict` fails CI
+ * on any drift (`.github/workflows/tests.yml`). `side_effect` is consumed by that
+ * generator, so adding or reordering a field means regenerating the catalog.
  */
 export interface BuiltinTool {
     readonly name: string;
     readonly description: string;
     readonly input_schema: Record<string, unknown>;
+    readonly side_effect: ToolSideEffect;
     readonly handler: ToolHandler;
 }
 
@@ -1197,6 +1213,7 @@ async function _readResourceBodyHandler(
 export const ALLOWLIST: Record<string, BuiltinTool> = {
     lint_skills: {
         name: 'lint_skills',
+        side_effect: 'ro',
         description:
             'Lint skill, rule, command, guideline, and persona markdown ' +
             'files for frontmatter and structural errors. Use before ' +
@@ -1225,6 +1242,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     chat_history_append: {
         name: 'chat_history_append',
+        side_effect: 'fs-write',
         description:
             "Append one structured entry to the consumer project's " +
             'chat-history log (a JSONL file). Use to record a decision, ' +
@@ -1286,6 +1304,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     chat_history_read: {
         name: 'chat_history_read',
+        side_effect: 'ro',
         description:
             "Read recent entries back from the consumer project's " +
             'chat-history JSONL ' +
@@ -1362,6 +1381,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     memory_lookup: {
         name: 'memory_lookup',
+        side_effect: 'ro',
         description:
             'Retrieve engineering-memory entries for one or more memory ' +
             'types, optionally narrowed to specific anchor paths. Use ' +
@@ -1429,6 +1449,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     memory_get: {
         name: 'memory_get',
+        side_effect: 'ro',
         description:
             'Batch-fetch FULL memory entries by id — the second half of ' +
             'the index-first retrieval workflow. Call memory_lookup with ' +
@@ -1453,6 +1474,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     memory_status: {
         name: 'memory_status',
+        side_effect: 'ro',
         description:
             'Report the memory backend status. Memory is entirely ' +
             'file-backed (`agents/memory/`); there is no external backend. ' +
@@ -1467,6 +1489,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     list_skills: {
         name: 'list_skills',
+        side_effect: 'ro',
         description:
             'Enumerate every skill the server currently exposes as a ' +
             'prompt, each with its name, description, and source. Use to ' +
@@ -1482,6 +1505,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     list_commands: {
         name: 'list_commands',
+        side_effect: 'ro',
         description:
             'Enumerate every slash command the server currently exposes ' +
             'as a prompt, each with its name and description. Use to ' +
@@ -1497,6 +1521,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     list_rules: {
         name: 'list_rules',
+        side_effect: 'ro',
         description:
             'Enumerate every behavioral rule the server exposes as a ' +
             'resource, each with its URI, name, and description. Use to ' +
@@ -1513,6 +1538,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     read_resource_body: {
         name: 'read_resource_body',
+        side_effect: 'ro',
         description:
             'Fetch the rendered body of a single resource URI (rule, ' +
             'guideline, or context document) in one call, without the ' +
@@ -1538,6 +1564,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     memory_signal: {
         name: 'memory_signal',
+        side_effect: 'fs-write',
         description:
             'Record an engineering-memory signal — a short, anchored ' +
             'observation such as a recurring bug pattern or an ownership ' +
@@ -1572,6 +1599,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     roadmap_progress: {
         name: 'roadmap_progress',
+        side_effect: 'fs-write',
         description:
             'Regenerate `agents/roadmaps-progress.md` from the current ' +
             'checkbox state of every active roadmap. Use after landing ' +
@@ -1595,6 +1623,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     roadmap_archive: {
         name: 'roadmap_archive',
+        side_effect: 'fs-write',
         description:
             'Archive every roadmap that has reached `count_open == 0` and ' +
             'was touched on the current branch — `git mv` to ' +
@@ -1611,6 +1640,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     capabilities_index: {
         name: 'capabilities_index',
+        side_effect: 'fs-write',
         description:
             "Regenerate `CAPABILITIES.yaml`, the package's coverage index " +
             'of skills, rules, commands, and guidelines. Use after adding ' +
@@ -1634,6 +1664,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     doctor_report: {
         name: 'doctor_report',
+        side_effect: 'ro',
         description:
             'Run the consumer-project doctor diagnostic and return a ' +
             'structured health report (install drift, hook wiring, ' +
@@ -1648,6 +1679,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     conformance_check: {
         name: 'conformance_check',
+        side_effect: 'ro',
         description:
             'Run the consumer conformance contract (`doctor --ci` plus ' +
             'installed-and-firing checks) and return pass/fail per check. ' +
@@ -1662,6 +1694,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     telemetry_report: {
         name: 'telemetry_report',
+        side_effect: 'ro',
         description:
             'Return the artefact-engagement telemetry report — essential ' +
             '/ useful / retirement-candidate skills and rules ranked by ' +
@@ -1684,6 +1717,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     council_estimate: {
         name: 'council_estimate',
+        side_effect: 'ro',
         description:
             'Estimate the token cost of an AI-council debate over a given ' +
             'input (roadmap, diff, prompt, or file set) without spending ' +
@@ -1713,6 +1747,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
     },
     run_tests: {
         name: 'run_tests',
+        side_effect: 'shell',
         description:
             "Run the consumer project's vitest test suite under a " +
             'compiled safety envelope: fixed argv (no shell ' +
@@ -1744,11 +1779,18 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
 
 /** Render a `BuiltinTool` as kwargs for `mcp.types.Tool`. */
 export function to_mcp_tool_meta(tool: BuiltinTool): Record<string, unknown> {
-    return {
+    const meta: Record<string, unknown> = {
         name: tool.name,
         description: tool.description,
         inputSchema: tool.input_schema,
     };
+    // Annotations are honest MCP tool-behavior hints (Phase 3 of
+    // road-to-credible-install): only the implemented set carries them — a
+    // stub never actually runs, so there is nothing true to annotate.
+    if (tool.name in ALLOWLIST) {
+        meta['annotations'] = { readOnlyHint: tool.side_effect === 'ro' };
+    }
+    return meta;
 }
 
 // ---------------------------------------------------------------------
@@ -1790,6 +1832,7 @@ function _buildCatalogRegistry(): [Record<string, BuiltinTool>, ReadonlySet<stri
             name: entry.name,
             description: entry.description,
             input_schema: entry.input_schema,
+            side_effect: entry.side_effect as ToolSideEffect,
             handler: _makeStubHandler(entry, installHintValue),
         };
         stubNames.add(entry.name);
@@ -1801,9 +1844,17 @@ const _catalogBuild = _buildCatalogRegistry();
 export const CATALOG_STUBS: Record<string, BuiltinTool> = _catalogBuild[0];
 export const STUB_NAMES: ReadonlySet<string> = _catalogBuild[1];
 
-// Full wire-surface registry — implemented + stubs. `tools/list` reads
-// from this; `tools/call` dispatches against it.
-export const REGISTRY: Record<string, BuiltinTool> = { ...ALLOWLIST, ...CATALOG_STUBS };
+// Wire-surface registry — IMPLEMENTED TOOLS ONLY (ADR-132, council revisit
+// 2026-07-27 after the evaluator scoring-model claim was verified: the
+// 40%-minimum term makes phantom stub tools the structural worst-scored
+// entries, and an unlisted tool is uncallable in compliant MCP clients
+// anyway — so a stub on `tools/list` is pure cost). The 12 stub entries
+// remain in the GENERATED catalog as the documented implemented-on-demand
+// backlog (marked "[stub — implemented on demand]"); they are no longer
+// registered as callable tools on the stdio transport. `CATALOG_STUBS` /
+// `STUB_NAMES` stay exported for the catalog surface, the cloud packer,
+// and the parity tests.
+export const REGISTRY: Record<string, BuiltinTool> = { ...ALLOWLIST };
 
 /**
  * Registry view backing the MCP `tools/*` handlers.

package/src/scripts/mcp_telemetry_query.ts

@@ -18,9 +18,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { DatabaseSync } from 'node:sqlite';
-import type * as NodeSqlite from 'node:sqlite';
 
 import { resolve_db } from './mcp_telemetry_store.js';
+import { loadSqlite } from './_lib/sqlite_guard.js';
 
 export interface ToolRow {
     tool_name: string;
@@ -48,43 +48,12 @@ function toolRowAsDict(t: ToolRow): Record<string, unknown> {
 /** Python error subclass marker so main() can mirror the FileNotFoundError branch. */
 class FileNotFoundLikeError extends Error {}
 
-// Python's stdlib sqlite3 emits nothing on stderr; node:sqlite is flagged
-// experimental on node 22 and prints an `ExperimentalWarning: SQLite …` line
-// to stderr on first import (stable / silent on node >= 23). Drop only that
-// specific warning so stderr stays byte-stable across node versions (tests
-// pin the exact bytes). Installed once, narrowly matched.
-let _sqliteWarningSilenced = false;
-function _silenceSqliteExperimentalWarning(): void {
-    if (_sqliteWarningSilenced) return;
-    _sqliteWarningSilenced = true;
-    const orig = process.emitWarning.bind(process);
-    process.emitWarning = ((warning: string | Error, ...rest: unknown[]): void => {
-        const text = typeof warning === 'string' ? warning : (warning?.message ?? '');
-        if (/SQLite is an experimental/i.test(text)) return;
-        (orig as (w: string | Error, ...a: unknown[]) => void)(warning, ...rest);
-    }) as typeof process.emitWarning;
-}
-
-/** Lazy `node:sqlite` import — keeps the module loadable on a runtime without it. */
-async function _loadSqlite(): Promise<typeof NodeSqlite> {
-    _silenceSqliteExperimentalWarning();
-    try {
-        return await import('node:sqlite');
-    } catch (exc) {
-        const message = exc instanceof Error ? exc.message : String(exc);
-        throw new Error(
-            `node:sqlite is unavailable in this runtime (${message}). ` +
-                'mcp_telemetry_query requires Node with the built-in SQLite module.',
-        );
-    }
-}
-
 /** Open read-only. Mirrors `_connect_ro`; raises FileNotFound-like on absence. */
 async function _connect_ro(db_path: string): Promise<DatabaseSync> {
     if (!fs.existsSync(db_path)) {
         throw new FileNotFoundLikeError(`telemetry db not found: ${db_path}`);
     }
-    const { DatabaseSync } = await _loadSqlite();
+    const { DatabaseSync } = await loadSqlite('mcp_telemetry_query');
     // `file:<posix>?mode=ro` — Python opens via the same URI form.
     const uri = `file:${_asPosix(db_path)}?mode=ro`;
     return new DatabaseSync(uri, { readOnly: true });