@bridge_gpt/mcp-server 0.2.9 → 0.2.12

package/build/conductor-claude-hook-bin.js

@@ -1,21 +1,171 @@
 #!/usr/bin/env node
-/**
- * Standalone Claude Code → conductor lifecycle hook bin.
- *
- * Registered into a spawned Claude worker's `.claude/settings.local.json` by
- * `start-tickets`. Claude Code pipes the native hook payload to this process on
- * stdin; the runner maps it to a conductor event and shells to the `conductor`
- * CLI. It is intentionally non-blocking: {@link runClaudeConductorHookCli}
- * always returns `0`, and any unexpected top-level failure here also exits `0`
- * so the Claude tool loop is never blocked by hook problems.
- */
-import { runClaudeConductorHookCli } from "./conductor/claude-hook.js";
-let exitCode = 0;
-try {
-    exitCode = runClaudeConductorHookCli();
+
+// src/conductor/claude-hook.ts
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+var CONDUCTOR_HOOK_EMIT_FAILED_WARNING = "Warning: conductor hook emit failed.";
+function resolveClaudeHookEventName(payload) {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    return null;
+  }
+  const record = payload;
+  const candidates = ["hook_event_name", "hookEventName", "event_name", "event"];
+  for (const key of candidates) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+function mapClaudeHookEventToSemanticType(eventName) {
+  switch (eventName) {
+    case "SessionStart":
+      return "run.started";
+    case "Stop":
+      return "run.stopped";
+    case "SubagentStop":
+      return "run.stopped";
+    case "Notification":
+      return "agent.notification";
+    case "PreToolUse":
+      return "tool.intent";
+    default:
+      return null;
+  }
+}
+var REQUIRED_IDENTITY_ENV = [
+  "BAPI_CONDUCTOR_RUN_ID",
+  "BAPI_CONDUCTOR_WORKER_ID",
+  "BAPI_CONDUCTOR_TICKET_KEY",
+  "BAPI_CONDUCTOR_WORKTREE_PATH"
+];
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function buildClaudeHookConductorEvent(payload, env) {
+  const eventName = resolveClaudeHookEventName(payload);
+  const type = mapClaudeHookEventToSemanticType(eventName);
+  if (type === null) {
+    return null;
+  }
+  if (env.BAPI_CONDUCTOR_ENABLED !== "1") {
+    return null;
+  }
+  for (const key of REQUIRED_IDENTITY_ENV) {
+    if (!nonEmpty(env[key])) {
+      return null;
+    }
+  }
+  const ticketKey = env.BAPI_CONDUCTOR_TICKET_KEY.trim();
+  const worktreePath = env.BAPI_CONDUCTOR_WORKTREE_PATH.trim();
+  const details = {
+    ticket_key: ticketKey,
+    worktree_path: worktreePath
+  };
+  if (nonEmpty(env.BAPI_CONDUCTOR_REPO_NAME)) {
+    details.repo = env.BAPI_CONDUCTOR_REPO_NAME.trim();
+  }
+  const raw = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : { payload };
+  return {
+    source: "claude-code",
+    type,
+    subject: ticketKey,
+    run_id: env.BAPI_CONDUCTOR_RUN_ID.trim(),
+    worker_id: env.BAPI_CONDUCTOR_WORKER_ID.trim(),
+    producer: "claude-code-hook",
+    observed_via: "claude-code-hook",
+    data: {
+      details,
+      raw
+    }
+  };
+}
+function buildConductorEmitEventArgs(event) {
+  const args = ["--type", event.type, "--source", event.source];
+  if (nonEmpty(event.subject ?? void 0)) args.push("--subject", event.subject);
+  if (nonEmpty(event.run_id ?? void 0)) args.push("--run-id", event.run_id);
+  if (nonEmpty(event.worker_id ?? void 0)) args.push("--worker-id", event.worker_id);
+  if (nonEmpty(event.producer ?? void 0)) args.push("--producer", event.producer);
+  if (nonEmpty(event.observed_via ?? void 0)) {
+    args.push("--observed-via", event.observed_via);
+  }
+  args.push("--data-json-stdin", "--json");
+  return args;
 }
-catch {
-    // Defensive: never let a hook failure propagate into the Claude tool loop.
-    exitCode = 0;
+function resolveConductorEmitCommand(env, emitArgs) {
+  const cliFile = env.BAPI_CONDUCTOR_CLI_FILE;
+  if (nonEmpty(cliFile)) {
+    return {
+      command: process.execPath,
+      args: [cliFile.trim(), "emit-event", ...emitArgs]
+    };
+  }
+  const bin = nonEmpty(env.BAPI_CONDUCTOR_BIN) ? env.BAPI_CONDUCTOR_BIN.trim() : "conductor";
+  return { command: bin, args: ["emit-event", ...emitArgs] };
+}
+var defaultConductorSpawn = (command, args, input) => {
+  const result = spawnSync(command, args, {
+    input,
+    encoding: "utf-8",
+    // Never use a shell: list args + stdin keep raw payloads/secrets out of any
+    // shell-interpreted command string.
+    shell: false
+  });
+  return { status: result.status, error: result.error };
+};
+function emitClaudeHookEventWithConductorCli(event, deps = {}) {
+  const env = deps.env ?? process.env;
+  const spawn = deps.spawn ?? defaultConductorSpawn;
+  const emitArgs = buildConductorEmitEventArgs(event);
+  const { command, args } = resolveConductorEmitCommand(env, emitArgs);
+  const stdinPayload = JSON.stringify(event.data ?? {});
+  try {
+    const result = spawn(command, args, stdinPayload);
+    if (result.error) return false;
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+function runClaudeConductorHookCli(deps = {}) {
+  const env = deps.env ?? process.env;
+  const readStdin = deps.readStdin ?? (() => readStdinSync());
+  const warn = deps.warn ?? ((m) => process.stderr.write(`${m}
+`));
+  let payload;
+  try {
+    const raw = readStdin();
+    payload = JSON.parse(raw);
+  } catch {
+    warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
+    return 0;
+  }
+  let event;
+  try {
+    event = buildClaudeHookConductorEvent(payload, env);
+  } catch {
+    warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
+    return 0;
+  }
+  if (event === null) {
+    return 0;
+  }
+  const ok = emitClaudeHookEventWithConductorCli(event, { env, spawn: deps.spawn });
+  if (!ok) {
+    warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
+  }
+  return 0;
+}
+function readStdinSync() {
+  return readFileSync(0, "utf-8");
+}
+
+// src/conductor-claude-hook-bin.ts
+var exitCode = 0;
+try {
+  exitCode = runClaudeConductorHookCli();
+} catch {
+  exitCode = 0;
 }
 process.exit(exitCode);

package/build/decision-page-schema.js

@@ -192,3 +192,29 @@ export const DecisionPageInputShape = {
         .describe("Confirmed improvements displayed as informational list, not submitted."),
 };
 export const DecisionPageInputSchema = z.object(DecisionPageInputShape);
+// Lean schema for tool registration: keeps strict routing/output fields and
+// defers the heavy nested arrays to a single `content` object. This removes
+// ~1,800 tokens from the always-on core tools/list payload (BAPI-444).
+// The handler reconstructs the flat payload and validates with DecisionPageInputSchema.
+export const DecisionPageLeanInputShape = {
+    ticket_key: z.string().describe("Jira ticket key, e.g. BAPI-123"),
+    artifact_type: z
+        .enum(["review_decisions", "pre_ticket_planning"])
+        .optional()
+        .default("review_decisions")
+        .describe('Which flavor of page to render. "review_decisions" (default) or "pre_ticket_planning" (adds system_goals and implementation_order sections).'),
+    output_subdir: z
+        .string()
+        .optional()
+        .default("review")
+        .describe('Optional docs-relative subdirectory to write the page under (default "review"). No absolute paths, backslashes, ".." segments, null bytes, or encoded path tokens.'),
+    output_filename: z
+        .string()
+        .optional()
+        .describe('Optional output filename (default "${ticket_key}-decisions.html"). Must end with .html; no path separators.'),
+    labels: DecisionPageLabelsSchema.optional().describe("Optional presentation-label overrides (title, intro, section_heading, improvements_heading)."),
+    content: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Contains deferred heavy payloads like actionable_items or system_goals."),
+};

package/build/doctor.js

@@ -15,8 +15,11 @@
  * (`which`/`where`, `bash --version`, `git rev-parse`) through the injected deps.
  */
 import { readFile, stat } from "fs/promises";
+import { spawn } from "child_process";
 import os from "os";
+import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
+import { VERSION } from "./version.generated.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 /** User-facing usage text for the read-only `doctor` subcommand. */
@@ -161,6 +164,188 @@ export function formatDoctorReport(platform, agent, collection) {
         : "All required prerequisites are present.");
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// Launcher-cache diagnostics (BAPI-451 W3, E-4/E-9) — strictly read-only.
+//
+// install-bridge writes a launcher pinned to `@${VERSION}` (a specific `_npx`
+// bucket). The FIRST launch of a not-yet-cached pin pays a cold install inline,
+// which can exceed an MCP client's connect deadline. doctor inspects each
+// project-local config's actual `bridge-api` launcher spec and reports:
+//   - `unpinned`     — `@latest` / no version suffix (cache bucket is unstable).
+//   - `stale-pinned` — pinned to a version other than the running `VERSION`.
+//   - `warmed`       — pinned to `VERSION` and the `_npx` bucket is present.
+//   - `indeterminate`— pinned to `VERSION` but the bucket probe was not a clean
+//                      hit (a.k.a. `pinned-but-unwarmed`), or the config/spec was
+//                      ambiguous. Never silently reported as "warm".
+// The bucket probe is `npx --no-install <spec> --version`: `--no-install` means
+// the probe can never mutate (warm) the cache, honoring the read-only contract.
+// ---------------------------------------------------------------------------
+/** The npm package whose pinned launcher spec doctor inspects. */
+const BRIDGE_PACKAGE_NAME = "@bridge_gpt/mcp-server";
+/** Project-local MCP configs doctor inspects (mirrors install-bridge's targets). */
+const LAUNCHER_CONFIG_TARGETS = [
+    { relPath: ".mcp.json", topLevelKey: "mcpServers" },
+    { relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" },
+    { relPath: ".vscode/mcp.json", topLevelKey: "servers" },
+];
+/**
+ * Extract the `@bridge_gpt/mcp-server[@version]` launcher spec from an args array.
+ * The package name is itself scoped (`@scope/name`), so the version delimiter is
+ * the LAST `@`: `@bridge_gpt/mcp-server` is unpinned (no version), while
+ * `@bridge_gpt/mcp-server@0.2.11` pins `0.2.11`. Returns null when no spec matches.
+ */
+export function parseLauncherPin(args) {
+    if (!Array.isArray(args))
+        return null;
+    for (const arg of args) {
+        if (typeof arg !== "string")
+            continue;
+        if (arg === BRIDGE_PACKAGE_NAME)
+            return { spec: arg, version: null };
+        if (arg.startsWith(`${BRIDGE_PACKAGE_NAME}@`)) {
+            const version = arg.slice(BRIDGE_PACKAGE_NAME.length + 1).trim();
+            return { spec: arg, version: version.length > 0 ? version : null };
+        }
+    }
+    return null;
+}
+/**
+ * Default read-only cache probe. Spawns `npx --no-install <spec> --version`
+ * array-based (`shell: false`), ignores child stdio, and bounds the run with a
+ * timeout. A clean exit-0 means the pinned bucket is warm; any non-zero exit,
+ * spawn error, or timeout is classified `indeterminate` (never silently "warm").
+ * `--no-install` guarantees the probe never downloads/warms the bucket.
+ */
+function probeNpxNoInstallDefault(spec) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawn("npx", ["--no-install", spec, "--version"], {
+                shell: false,
+                stdio: "ignore",
+                timeout: 30_000,
+            });
+            child.on("error", () => resolve({ warmed: false, indeterminate: true }));
+            child.on("close", (code, signal) => {
+                if (signal)
+                    resolve({ warmed: false, indeterminate: true });
+                else if (code === 0)
+                    resolve({ warmed: true, indeterminate: false });
+                else
+                    resolve({ warmed: false, indeterminate: true });
+            });
+        }
+        catch {
+            resolve({ warmed: false, indeterminate: true });
+        }
+    });
+}
+/**
+ * Inspect every project-local MCP config's `bridge-api` launcher pin (read-only).
+ * Configs that are absent, unparseable, or carry no `bridge-api` entry are skipped
+ * (an absent config is not a finding). Each present launcher is classified and,
+ * when pinned to the running `VERSION`, probed read-only with `--no-install`.
+ */
+export async function inspectLauncherCache(deps) {
+    const inspections = [];
+    for (const { relPath, topLevelKey } of LAUNCHER_CONFIG_TARGETS) {
+        const fullPath = path.join(deps.cwd, relPath);
+        let raw;
+        try {
+            raw = await deps.readFile(fullPath);
+        }
+        catch {
+            continue; // config absent — not a finding.
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            inspections.push({
+                relPath,
+                spec: null,
+                pinnedVersion: null,
+                state: "indeterminate",
+                remediation: "config is not valid JSON — cannot determine the launcher pin.",
+            });
+            continue;
+        }
+        const entry = parsed && typeof parsed === "object"
+            ? parsed[topLevelKey]?.["bridge-api"]
+            : undefined;
+        if (!entry)
+            continue; // no bridge-api launcher in this config — not a finding.
+        const pin = parseLauncherPin(entry.args);
+        if (!pin) {
+            inspections.push({
+                relPath,
+                spec: null,
+                pinnedVersion: null,
+                state: "indeterminate",
+                remediation: `no ${BRIDGE_PACKAGE_NAME} spec found in the launcher args.`,
+            });
+            continue;
+        }
+        if (pin.version === null || pin.version === "latest") {
+            inspections.push({
+                relPath,
+                spec: pin.spec,
+                pinnedVersion: pin.version,
+                state: "unpinned",
+                remediation: `pin the launcher to ${BRIDGE_PACKAGE_NAME}@${VERSION} (run /install-bridge or the install-bridge subcommand to rewrite this config).`,
+            });
+            continue;
+        }
+        if (pin.version !== VERSION) {
+            inspections.push({
+                relPath,
+                spec: pin.spec,
+                pinnedVersion: pin.version,
+                state: "stale-pinned",
+                remediation: `config pins ${pin.version} but this package is ${VERSION}; run upgrade-bridge / install-bridge to repin and re-warm.`,
+            });
+            continue;
+        }
+        // Pinned to the running VERSION — probe the bucket read-only.
+        const probe = await deps.probeNpxNoInstall(pin.spec);
+        if (probe.warmed) {
+            inspections.push({ relPath, spec: pin.spec, pinnedVersion: pin.version, state: "warmed" });
+        }
+        else {
+            inspections.push({
+                relPath,
+                spec: pin.spec,
+                pinnedVersion: pin.version,
+                state: "indeterminate",
+                remediation: "pinned-but-unwarmed: the pinned _npx bucket is not a confirmed cache hit, so the first MCP launch may pay a one-time cold install. " +
+                    `Warm it with: npx ${pin.spec} --version, or raise MCP_TIMEOUT for the first launch.`,
+            });
+        }
+    }
+    return inspections;
+}
+/** Render the launcher-cache section of the doctor report (pure formatting). */
+export function formatLauncherCacheReport(inspections) {
+    const lines = ["", "Launcher cache (MCP cold-start readiness)", ""];
+    if (inspections.length === 0) {
+        lines.push("No project-local bridge-api launcher configs found to inspect.");
+        return lines.join("\n");
+    }
+    const labels = {
+        warmed: "WARMED ",
+        unpinned: "UNPINNED",
+        "stale-pinned": "STALE-PINNED",
+        indeterminate: "INDETERMINATE",
+    };
+    for (const i of inspections) {
+        const specText = i.spec ? ` (${i.spec})` : "";
+        lines.push(`${labels[i.state]} ${i.relPath}${specText}`);
+        if (i.remediation) {
+            lines.push(`  ${i.remediation}`);
+        }
+    }
+    return lines.join("\n");
+}
 /**
  * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
  * Help returns 0; parser errors return 1; otherwise it prints the report and
@@ -186,6 +371,21 @@ export async function runDoctorCli(argv, overrides = {}) {
     const agent = resolveAgentSpec(parsed.options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
     const collection = await collectDoctorResults(deps, parsed.options.agentName);
     log(formatDoctorReport(deps.platform, agent, collection));
+    // Strictly read-only launcher-cache diagnostics (BAPI-451). Best-effort: a probe
+    // failure never changes the doctor exit code (cold-start readiness is advisory,
+    // not a hard prerequisite). The exit code remains driven by required prereqs.
+    try {
+        const launcherDeps = {
+            cwd: overrides.launcherProbe?.cwd ?? deps.cwd,
+            readFile: overrides.launcherProbe?.readFile ?? ((p) => readFile(p, "utf-8")),
+            probeNpxNoInstall: overrides.launcherProbe?.probeNpxNoInstall ?? probeNpxNoInstallDefault,
+        };
+        const launcherInspections = await inspectLauncherCache(launcherDeps);
+        log(formatLauncherCacheReport(launcherInspections));
+    }
+    catch {
+        /* launcher-cache diagnostics are advisory; never block the doctor report */
+    }
     if (!collection.ok)
         return 1;
     return collection.results.some((r) => !r.found) ? 1 : 0;