@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/maintenance/docker-reclaim.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/maintenance/docker-reclaim.mjs — reclaim abandoned per-home Postgres
+ * containers and data volumes that outlived the HOME that created them.
+ *
+ * Construct derives a Postgres container/volume namespace from a sha256 slice
+ * of the resolved home directory (lib/home-namespace.mjs) so isolated HOMEs —
+ * test sandboxes, ephemeral /tmp footprint runs, deleted accounts — never
+ * collide on one machine. Each container carries a `restart: unless-stopped`
+ * policy. When the owning HOME or its compose project directory is deleted,
+ * Docker keeps the container alive with nothing left to reap it: an orphan that
+ * pins memory and leaks disk through its named volume.
+ *
+ * The reclaim runs from the upgrade flows (lib/update.mjs, lib/upgrade.mjs)
+ * once per upgrade and from `construct cleanup`, never from `construct sync`,
+ * which fires constantly and must not mutate machine-global Docker state.
+ *
+ * An orphan is removed only when every signal agrees it is abandoned:
+ *   - the name carries a Construct per-home suffix (construct-postgres-<8 hex>),
+ *     so hand-named and third-party containers stay untouched;
+ *   - the suffix differs from the current HOME's suffix, sparing the live install;
+ *   - the name differs from an operator-pinned CONSTRUCT_PG_CONTAINER;
+ *   - a container's compose working_dir label points at a path that is gone;
+ *   - a volume has no surviving container for its suffix.
+ * The legacy singular `construct-postgres` (no suffix) is out of scope.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+
+import { homeNamespaceSuffix } from '../home-namespace.mjs';
+
+const CONTAINER_RE = /^construct-postgres-([0-9a-f]{8})$/;
+const VOLUME_RE = /construct-postgres-([0-9a-f]{8})/;
+const CONTAINER_FORMAT = '{{.Names}}\t{{.Label "com.docker.compose.project.working_dir"}}';
+const DEFAULT_MAX = 25;
+
+export function defaultRunDocker(args) {
+  const r = spawnSync('docker', args, { encoding: 'utf8' });
+  return {
+    status: r.status ?? 1,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    error: r.error || null,
+  };
+}
+
+// `docker ps -a` lists every container with its compose working_dir label on a
+// tab. Anything that does not match the per-home naming scheme is dropped, so
+// the parser only surfaces Construct-managed candidates.
+
+export function parseContainers(stdout) {
+  const out = [];
+  for (const raw of String(stdout || '').split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line) continue;
+    const tab = line.indexOf('\t');
+    const name = (tab === -1 ? line : line.slice(0, tab)).trim();
+    const workingDir = tab === -1 ? '' : line.slice(tab + 1).trim();
+    const match = CONTAINER_RE.exec(name);
+    if (!match) continue;
+    out.push({ name, suffix: match[1], workingDir });
+  }
+  return out;
+}
+
+export function parseVolumes(stdout) {
+  const out = [];
+  for (const raw of String(stdout || '').split('\n')) {
+    const name = raw.trim();
+    if (!name) continue;
+    const match = VOLUME_RE.exec(name);
+    if (!match) continue;
+    out.push({ name, suffix: match[1] });
+  }
+  return out;
+}
+
+// A container is an orphan when it belongs to a foreign home namespace, is not
+// the operator-pinned container, and its compose project directory is gone. A
+// volume is an orphan when its suffix is foreign and no surviving container —
+// including containers spared this pass — still claims it.
+
+export function selectOrphans({
+  containers,
+  volumes,
+  currentSuffix,
+  pinnedName = null,
+  pathExists = (p) => fs.existsSync(p),
+}) {
+  const orphanContainers = containers.filter((c) =>
+    c.suffix !== currentSuffix &&
+    c.name !== pinnedName &&
+    c.workingDir &&
+    !pathExists(c.workingDir));
+
+  const orphanSuffixes = new Set(orphanContainers.map((c) => c.suffix));
+  const liveSuffixes = new Set(
+    containers.filter((c) => !orphanSuffixes.has(c.suffix)).map((c) => c.suffix),
+  );
+
+  const orphanVolumes = volumes.filter((v) =>
+    v.suffix &&
+    v.suffix !== currentSuffix &&
+    !liveSuffixes.has(v.suffix));
+
+  return { orphanContainers, orphanVolumes };
+}
+
+export function reclaimOrphanedDockerResources({
+  runDocker = defaultRunDocker,
+  homeDir = os.homedir(),
+  env = process.env,
+  dryRun = false,
+  max = DEFAULT_MAX,
+  pathExists = (p) => fs.existsSync(p),
+} = {}) {
+  const summary = {
+    available: false,
+    reason: null,
+    scanned: { containers: 0, volumes: 0 },
+    removedContainers: [],
+    removedVolumes: [],
+    skipped: [],
+    errors: [],
+    dryRun,
+  };
+
+  // A non-zero `docker ps` means the daemon is down or Docker is absent; the
+  // machine then holds no reclaimable state and the pass is a clean no-op.
+
+  const psResult = runDocker(['ps', '-a', '--format', CONTAINER_FORMAT]);
+  if (!psResult || psResult.status !== 0) {
+    summary.reason = 'docker-unavailable';
+    return summary;
+  }
+  summary.available = true;
+
+  const containers = parseContainers(psResult.stdout);
+  summary.scanned.containers = containers.length;
+
+  const volResult = runDocker(['volume', 'ls', '--format', '{{.Name}}']);
+  const volumes = volResult && volResult.status === 0 ? parseVolumes(volResult.stdout) : [];
+  summary.scanned.volumes = volumes.length;
+
+  const currentSuffix = homeNamespaceSuffix(homeDir);
+  const pinnedName = (env.CONSTRUCT_PG_CONTAINER || '').trim() || null;
+
+  const { orphanContainers, orphanVolumes } = selectOrphans({
+    containers,
+    volumes,
+    currentSuffix,
+    pinnedName,
+    pathExists,
+  });
+
+  let budget = Number.isFinite(max) && max > 0 ? max : DEFAULT_MAX;
+
+  for (const c of orphanContainers) {
+    if (budget <= 0) {
+      summary.skipped.push({ name: c.name, reason: 'reclaim-budget-exhausted' });
+      continue;
+    }
+    budget -= 1;
+    if (dryRun) {
+      summary.removedContainers.push(c.name);
+      continue;
+    }
+    const r = runDocker(['rm', '-f', '-v', c.name]);
+    if (r && r.status === 0) summary.removedContainers.push(c.name);
+    else summary.errors.push({ name: c.name, error: (r?.stderr || '').trim() || `docker rm exited ${r?.status}` });
+  }
+
+  // A named data volume only drops once nothing references it. `docker volume
+  // rm` exits non-zero for an in-use or already-gone volume, so a failure here
+  // is recorded as skipped rather than a hard error.
+
+  for (const v of orphanVolumes) {
+    if (budget <= 0) {
+      summary.skipped.push({ name: v.name, reason: 'reclaim-budget-exhausted' });
+      continue;
+    }
+    budget -= 1;
+    if (dryRun) {
+      summary.removedVolumes.push(v.name);
+      continue;
+    }
+    const r = runDocker(['volume', 'rm', v.name]);
+    if (r && r.status === 0) summary.removedVolumes.push(v.name);
+    else summary.skipped.push({ name: v.name, reason: 'in-use-or-missing' });
+  }
+
+  return summary;
+}
+
+export function formatReclaim(summary) {
+  if (!summary || !summary.available) return null;
+  const containers = summary.removedContainers.length;
+  const volumes = summary.removedVolumes.length;
+  if (!containers && !volumes) return null;
+  const parts = [];
+  if (containers) parts.push(`${containers} orphaned Postgres container${containers === 1 ? '' : 's'}`);
+  if (volumes) parts.push(`${volumes} abandoned data volume${volumes === 1 ? '' : 's'}`);
+  const verb = summary.dryRun ? 'Would reclaim' : 'Reclaimed';
+  return `${verb} ${parts.join(' and ')} from deleted home namespaces.`;
+}

package/lib/mcp/external-schema-cost.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/mcp/external-schema-cost.mjs — measured token cost for heavy external MCP servers.
+ *
+ * Committed fixtures under tests/fixtures/mcp-tool-schemas/ hold captured tools/list
+ * payloads per server. Regenerate with scripts/measure-external-mcp-schemas.mjs.
+ * Sums schemaTokens via estimateToolTokens (JSON length × 0.25) for sync-time trim
+ * comments and ADR-0032 footnotes.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HEAVY_EXTERNAL_MCP_IDS, estimateToolTokens } from './tool-budget.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..');
+export const EXTERNAL_MCP_SCHEMA_FIXTURE_DIR = join(REPO_ROOT, 'tests', 'fixtures', 'mcp-tool-schemas');
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+// Load one server's committed fixture; missing files throw so CI fails loudly.
+
+export function loadExternalMcpSchemaFixture(serverId) {
+  const path = join(EXTERNAL_MCP_SCHEMA_FIXTURE_DIR, `${serverId}.json`);
+  if (!existsSync(path)) {
+    throw new Error(`Missing external MCP schema fixture: ${path}`);
+  }
+  const doc = readJson(path);
+  const tools = Array.isArray(doc.tools) ? doc.tools : [];
+  const schemaTokens = Number.isFinite(doc.schemaTokens)
+    ? doc.schemaTokens
+    : estimateToolTokens(tools);
+  return {
+    serverId,
+    capturedAt: doc.capturedAt || null,
+    toolCount: tools.length,
+    schemaTokens,
+    tools,
+  };
+}
+
+// Per-server breakdown plus total for HEAVY_EXTERNAL_MCP_IDS.
+
+export function measuredHeavyExternalMcpCosts() {
+  const servers = {};
+  let totalSchemaTokens = 0;
+  for (const id of HEAVY_EXTERNAL_MCP_IDS) {
+    const row = loadExternalMcpSchemaFixture(id);
+    servers[id] = {
+      toolCount: row.toolCount,
+      schemaTokens: row.schemaTokens,
+      capturedAt: row.capturedAt,
+    };
+    totalSchemaTokens += row.schemaTokens;
+  }
+  return { servers, totalSchemaTokens };
+}
+
+export function measuredHeavyExternalMcpTokenCost() {
+  return measuredHeavyExternalMcpCosts().totalSchemaTokens;
+}
+
+// Lazy constant — fixtures may be absent while scripts/measure-external-mcp-schemas.mjs runs.
+
+let cachedMeasuredTotal = null;
+
+export function getMeasuredHeavyExternalMcpTokenCost() {
+  if (cachedMeasuredTotal === null) {
+    cachedMeasuredTotal = measuredHeavyExternalMcpTokenCost();
+  }
+  return cachedMeasuredTotal;
+}

package/lib/mcp/server.mjs

@@ -13,7 +13,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { loadToolkitEnv } from '../toolkit-env.mjs';
-import { loadConstructEnv } from '../env-config.mjs';
+import { loadConstructEnv, prepareConstructEnv } from '../runtime-env.mjs';
 import { getInstalledVersion } from '../version.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
@@ -21,7 +21,7 @@ import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } fr
 // Apply config.env values to process.env, letting config.env win over shell env
 // so telemetry/OpenRouter credentials are always correct regardless of host env.
 {
-  const confEnv = loadConstructEnv({ warn: false });
+  const confEnv = prepareConstructEnv({ warn: false });
   for (const [k, v] of Object.entries(confEnv)) {
     process.env[k] = v;
   }
@@ -170,7 +170,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'extract_document_text',
-      description: 'Extracts readable text from a local document path. High-fidelity backend (docling Python sidecar via uv, whisper.cpp for audio/video) is wired into `construct ingest`; this MCP path returns the legacy regex extraction for backwards compatibility. Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
+      description: 'Extracts readable text from a local document path. Uses node-native extractors (unpdf/mammoth) first; escalates to the docling Python sidecar or whisper.cpp when needed (same pipeline as `construct ingest`). Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -375,7 +375,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'get_skill',
-      description: 'Reads a specific skill playbook from the Construct knowledge base (e.g. "security/security-arch", "web/design-quality").',
+      description: 'Reads a specific skill playbook from the Construct knowledge base (e.g. "docs/adr-workflow", "roles/engineer", "architecture/security-arch").',
       inputSchema: {
         type: 'object',
         properties: {
@@ -932,15 +932,50 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'document_export',
-      description: 'Convert a markdown file into a distributable PDF, DOCX, or HTML document via Pandoc (DOCX/HTML) and Typst (PDF engine), per ADR-0024. Both engines are optional system binaries discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
+      description: 'Convert a markdown file into a distributable document — PDF, DOCX, legacy DOC (LibreOffice), deck HTML, PPTX, HTML, RTF, ODT, EPUB, LaTeX, plain text, or Markdown — via Pandoc and Typst (PDF engine) plus optional pptxgenjs/LibreOffice, per ADR-0024. Engines are optional dependencies discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
       inputSchema: {
         type: 'object',
         required: ['format'],
         properties: {
           input_path: { type: 'string', description: 'Absolute path to the markdown source file (required unless detect_only=true).' },
           output_path: { type: 'string', description: 'Optional absolute output path; defaults to <input>.<format> next to the source.' },
-          format: { type: 'string', enum: ['pdf', 'docx', 'html'], description: 'Target format.' },
+          format: { type: 'string', enum: ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'], description: 'Target format.' },
           detect_only: { type: 'boolean', description: 'When true, report binary availability without exporting. Default false.' },
+          figures: { type: 'boolean', description: 'When true, render d2/mermaid via pandoc-ext/diagram filter. Default false.' },
+        },
+      },
+    },
+    {
+      name: 'publish_detect',
+      description: 'Detect availability of publish pipeline tooling: Pandoc/Typst export, pandoc-ext/diagram figures, VHS terminal demos, and Playwright dashboard demos.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          format: { type: 'string', enum: ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'], description: 'Export format to probe (default pdf).' },
+          figures: { type: 'boolean', description: 'Include figure binaries (default true).' },
+          demo: { type: 'string', description: 'When set, require VHS/asciinema for terminal demo.' },
+          dashboard_demo: { type: 'string', description: 'When set, require Playwright workspace for dashboard demo.' },
+        },
+      },
+    },
+    {
+      name: 'publish_run',
+      description: 'Run the publish pipeline: export markdown with optional figure filter and optional demo recordings. Use dry_run=true to probe tooling only.',
+      inputSchema: {
+        type: 'object',
+        required: ['input_path'],
+        properties: {
+          input_path: { type: 'string', description: 'Absolute path to markdown research brief.' },
+          output_path: { type: 'string', description: 'Optional output path for export.' },
+          format: { type: 'string', enum: ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'], description: 'Target format (default pdf).' },
+          demo: { type: 'string', description: 'Terminal tape name to record.' },
+          dashboard_demo: { type: 'string', description: 'Dashboard Playwright demo spec basename.' },
+          figures: { type: 'boolean', description: 'Render diagrams (default true).' },
+          strict: { type: 'boolean', description: 'Fail when toolchain or release gate fails (default true).' },
+          source_only: { type: 'boolean', description: 'Write sources only (default false).' },
+          no_gate: { type: 'boolean', description: 'Skip artifact release gate (default false).' },
+          artifact_type: { type: 'string', description: 'Manifest doc type for release gate when path inference is ambiguous.' },
+          dry_run: { type: 'boolean', description: 'Detect tooling only (default false).' },
         },
       },
     },
@@ -1270,7 +1305,7 @@ export async function dispatchToolByName(name, args = {}) {
     if (name === 'agent_health') result = agentHealth(args);
     else if (name === 'summarize_diff') result = summarizeDiff(args);
     else if (name === 'scan_file') result = scanFile(args);
-    else if (name === 'extract_document_text') result = extractDocumentText(args);
+    else if (name === 'extract_document_text') result = await extractDocumentText(args);
     else if (name === 'ingest_document') result = await ingestDocument(args);
     else if (name === 'infer_document_schema') result = await inferDocumentSchemaTool(args);
     else if (name === 'list_schema_artifacts') result = listSchemaArtifactsTool(args);
@@ -1324,9 +1359,49 @@ export async function dispatchToolByName(name, args = {}) {
     else if (name === 'document_export') {
       const { detect, exportMarkdown } = await import('../document-export.mjs');
       if (args.detect_only) {
-        result = detect(args.format);
+        result = detect(args.format, process.env, { figures: Boolean(args.figures) });
+      } else {
+        result = exportMarkdown({
+          inputPath: args.input_path,
+          outputPath: args.output_path,
+          format: args.format,
+          figures: Boolean(args.figures),
+        });
+      }
+    }
+    else if (name === 'publish_detect') {
+      const { detectPublishPipeline } = await import('../publish-tooling.mjs');
+      result = detectPublishPipeline({
+        format: args.format || 'pdf',
+        includeFigures: args.figures !== false,
+        includeTerminalDemo: Boolean(args.demo),
+        includeDashboardDemo: Boolean(args.dashboard_demo),
+      });
+    }
+    else if (name === 'publish_run') {
+      const { runPublish } = await import('../publish.mjs');
+      if (args.dry_run) {
+        const { detectPublishPipeline } = await import('../publish-tooling.mjs');
+        result = detectPublishPipeline({
+          format: args.format || 'pdf',
+          includeFigures: args.figures !== false,
+          includeTerminalDemo: Boolean(args.demo),
+          includeDashboardDemo: Boolean(args.dashboard_demo),
+        });
       } else {
-        result = exportMarkdown({ inputPath: args.input_path, outputPath: args.output_path, format: args.format });
+        result = runPublish({
+          inputPath: args.input_path,
+          format: args.format || 'pdf',
+          outputPath: args.output_path,
+          demos: args.demo ? [args.demo] : [],
+          dashboardDemos: args.dashboard_demo ? [args.dashboard_demo] : [],
+          figures: args.figures !== false,
+          strict: args.strict !== false,
+          gate: args.no_gate !== true,
+          artifactType: args.artifact_type || args.type || null,
+          sourceOnly: Boolean(args.source_only),
+          repoRoot: process.cwd(),
+        });
       }
     }
     else if (name === 'profile_show') result = profileShow(args);

package/lib/mcp/stdio-mcp-probe.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/mcp/stdio-mcp-probe.mjs — newline-delimited JSON-RPC probe for stdio MCP servers.
+ *
+ * Spawns a child MCP process, completes initialize + notifications/initialized, then
+ * issues tools/list to capture serialized tool schemas for token-budget fixtures.
+ * Stdout is the only protocol channel; stderr is ignored.
+ */
+
+import { spawn } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 25_000;
+
+function parseFrames(chunk, state) {
+  state.buffer += chunk;
+  let idx;
+  while ((idx = state.buffer.indexOf('\n')) >= 0) {
+    const raw = state.buffer.slice(0, idx).trim();
+    state.buffer = state.buffer.slice(idx + 1);
+    if (!raw) continue;
+    try {
+      state.frames.push(JSON.parse(raw));
+    } catch {
+      /* non-JSON noise */
+    }
+  }
+}
+
+function send(child, frame) {
+  child.stdin.write(`${JSON.stringify(frame)}\n`);
+}
+
+function waitForFrame(frames, predicate, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tick = () => {
+      const hit = frames.find(predicate);
+      if (hit) {
+        resolve(hit);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        reject(new Error(`Timed out after ${timeoutMs}ms; frames=${frames.length}`));
+        return;
+      }
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+// Probe a stdio MCP server and return the tools/list result array.
+
+export async function probeStdioMcpTools(command, args, {
+  env = {},
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const child = spawn(command, args, {
+    env: { ...process.env, ...env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const state = { buffer: '', frames: [] };
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => parseFrames(chunk, state));
+
+  const cleanup = () => {
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      /* already exited */
+    }
+  };
+
+  try {
+    send(child, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'construct-mcp-probe', version: '1' },
+      },
+    });
+    await waitForFrame(state.frames, (f) => f.id === 1, timeoutMs);
+    send(child, { jsonrpc: '2.0', method: 'notifications/initialized' });
+    send(child, { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+    const listFrame = await waitForFrame(state.frames, (f) => f.id === 2, timeoutMs);
+    if (listFrame.error) {
+      throw new Error(listFrame.error.message || JSON.stringify(listFrame.error));
+    }
+    return listFrame.result?.tools || [];
+  } finally {
+    cleanup();
+  }
+}
+
+// Parse JSON or MCP-over-SSE (event: message / data: {...}) bodies from HTTP MCP hosts.
+
+function parseMcpHttpFrame(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('data:')) continue;
+      const payload = trimmed.slice(5).trim();
+      if (!payload) continue;
+      try {
+        return JSON.parse(payload);
+      } catch {
+        /* try next data line */
+      }
+    }
+    throw new Error('response was not JSON or SSE data');
+  }
+}
+
+// Probe an HTTP MCP endpoint (GitHub Copilot MCP) with bearer auth.
+
+export async function probeHttpMcpTools(url, headers = {}, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const initBody = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'construct-mcp-probe', version: '1' },
+    },
+  };
+  const listBody = { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} };
+  const commonHeaders = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+    ...headers,
+  };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  async function postRpc(body, extraHeaders = {}) {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { ...commonHeaders, ...extraHeaders },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    return { res, text };
+  }
+
+  try {
+    const { res: initRes, text: initText } = await postRpc(initBody);
+    if (!initRes.ok) {
+      throw new Error(`initialize HTTP ${initRes.status}: ${initText.slice(0, 160)}`);
+    }
+    parseMcpHttpFrame(initText);
+
+    const sessionId = initRes.headers.get('mcp-session-id')
+      || initRes.headers.get('Mcp-Session-Id')
+      || null;
+    const sessionHeaders = sessionId ? { 'mcp-session-id': sessionId } : {};
+
+    const { res: listRes, text: listText } = await postRpc(listBody, sessionHeaders);
+    if (!listRes.ok) {
+      throw new Error(`tools/list HTTP ${listRes.status}: ${listText.slice(0, 160)}`);
+    }
+    const frame = parseMcpHttpFrame(listText);
+    if (frame.error) {
+      throw new Error(frame.error.message || JSON.stringify(frame.error));
+    }
+    return frame.result?.tools || [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Probe the Construct memory stdio bridge, which forwards tools/list to cm.
+
+export async function probeMemoryBridgeTools({
+  bridgePath,
+  backendUrl = 'http://127.0.0.1:8765/',
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  return probeStdioMcpTools(process.execPath, [bridgePath], {
+    env: { CONSTRUCT_MEMORY_BRIDGE_URL: backendUrl },
+    timeoutMs,
+  });
+}