@bridge_gpt/mcp-server 0.2.46 → 0.2.49

package/build/init.js

@@ -882,7 +882,7 @@ Each pipeline file must be a JSON object with these fields:
 | Field         | Type       | Required | Description                              |
 |---------------|------------|----------|------------------------------------------|
 | \`name\`        | string     | yes      | Display name of the pipeline             |
-| \`description\`  | string     | no       | Short description shown in list_pipelines |
+| \`description\`  | string     | no       | Short description of the pipeline         |
 | \`variables\`    | string[]   | no       | Variable names for substitution          |
 | \`steps\`        | Step[]     | yes      | Ordered list of steps to execute         |
 
@@ -934,29 +934,27 @@ automatically provided by the server.
 
 ## Executing Pipelines
 
-Pipelines defined here can be executed end-to-end via the \`run_pipeline\` MCP
-tool. \`run_pipeline\` returns a unified envelope keyed on \`status\`:
+Pipelines defined here are executed by the calling agent. Call the
+\`get_pipeline_recipe\` MCP tool with the pipeline name and any variables; it
+returns a fully resolved recipe:
 
-- \`completed\` — the pipeline finished and \`results\` holds the per-step output.
-- \`needs_agent_task\` — the orchestrator paused on an \`agent_task\` step (or an
-  approval-gated \`mcp_call\` when \`auto_approve\` was false). Perform the task
-  described by \`instruction\`, then call \`resume_pipeline\` with the
-  \`pipeline_run_id\` and the resulting string as \`agent_result\`.
-- \`failed\` — terminal failure; \`error_code\` is one of \`VALIDATION\`,
-  \`NOT_FOUND\`, \`EXPIRED\`, \`REPO_MISMATCH\`, or \`TOOL_ERROR\`.
+- \`steps\` — the ordered step array, with variables substituted and every
+  \`instruction_file\` reference already inlined as \`instruction\` text.
+- \`total_steps\`, \`auto_approve\`, and \`execution_mode\`.
 
-Paused runs auto-expire after an idle TTL (default 24 hours, override via
-\`ttl_seconds\` on \`run_pipeline\`). The TTL is reset on every state transition.
-Use \`list_pipeline_runs\` to recover a \`pipeline_run_id\` if the prior
-\`needs_agent_task\` envelope is no longer in scope.
+\`execution_mode\` is \`inline\`: there is no server-side orchestrator,
+and no run to resume. The agent executes each step itself in order — calling the named
+tool for an \`mcp_call\` step, following the instruction text for an
+\`agent_task\` step — and honours each step's \`on_error\` and
+\`requires_approval\` fields as it goes.
 
 ## \`agent_task\` Instruction Files
 
 When you reference an instruction file (\`instruction_file: "…"\`), the file
 markdown MUST end with a terminal \`## Return\` H2 section describing what the
-agent should pass back as \`resume_pipeline.agent_result\`. The return value
-is a string — do NOT ask the agent to wrap it in JSON unless the instruction
-body explicitly says to serialize structured output.
+agent should carry forward from that step. The return value is a string — do
+NOT ask the agent to wrap it in JSON unless the instruction body explicitly
+says to serialize structured output.
 `;
     const exampleContent = JSON.stringify({
         name: "Example Pipeline",

package/build/install-doctor.js

@@ -465,7 +465,7 @@ export async function collectInstallStatusChecks(deps) {
                 label: "Repository indexing",
                 status: "INFO",
                 detail: "no parse job currently running — if this repository has never been indexed, " +
-                    "queue one with /parse-repository (monitor with get_parse_status).",
+                    "queue one with /parse-repository (monitor with parse_repository action \"status\").",
             });
         }
     }

package/build/learn-tool-gating.js

@@ -0,0 +1,283 @@
+/**
+ * Learn/onboarding tool gating — SDK enabled-state, session lifetime (BAPI-912,
+ * decision D20).
+ *
+ * ---------------------------------------------------------------------------
+ * Which gating mechanism this is, and which one it is NOT
+ * ---------------------------------------------------------------------------
+ *
+ * Bridge has two independent mechanisms that can keep a tool out of a client's
+ * `tools/list`, and conflating them is the specific mistake this comment exists
+ * to prevent:
+ *
+ *   **Mechanism A — backend capability gating (BAPI-641).**
+ *   `tool-surface-gating.ts`. A fail-open, purely *subtractive* filter over the
+ *   SDK's own `tools/list` result, driven by a backend capability probe. That
+ *   module documents a hard **NEVER `.disable()`** invariant, because a probe
+ *   result must never mutate registration state. This module does not import
+ *   from, call into, or modify it.
+ *
+ *   **Mechanism B — SDK enabled state (used here).**
+ *   The `registerTool` wrapper in `index.ts` returns the SDK registration
+ *   handle and keeps a closure `active` flag in sync with `.enable()` /
+ *   `.disable()`, so a disabled tool is blocked for BOTH `tools/list` and
+ *   in-process `TOOL_HANDLERS` dispatch (returning the `TOOL_DISABLED`/503
+ *   envelope). `poll_ci_checks` has used exactly this since BAPI-338.
+ *
+ * Mechanism A's never-`.disable()` invariant governs Mechanism A only — it
+ * constrains the capability-gating module, not `index.ts`. Reading it as a
+ * blanket prohibition would make this feature look unimplementable.
+ *
+ * The two **compose as `SDK-enabled ∩ not-capability-hidden`**. This module
+ * moves only the first term, so enabling a tool whose repository lacks the
+ * required integration correctly leaves it absent from `tools/list`. That is a
+ * supported outcome, not a bug.
+ *
+ * ---------------------------------------------------------------------------
+ * The state machine
+ * ---------------------------------------------------------------------------
+ *
+ * The three learn/onboarding tools register normally (so registration order and
+ * the ordered `EXPECTED_TOOL_NAMES` pin are untouched) and are then disabled at
+ * startup. They are enabled **all three together, exactly once**, by the first
+ * of three qualifying triggers:
+ *
+ *   1. a *successful* `get_install_manifest` response,
+ *   2. `get_pipeline_recipe` successfully resolving `learn-repository`,
+ *   3. the post-initialize client fallback, for any client not on the
+ *      known-good list.
+ *
+ * Trigger 3 is why this is safe for clients that ignore a mid-session
+ * `notifications/tools/list_changed`: they simply receive the trio in their very
+ * first `tools/list`. The direction is deliberately **fail-open** — an
+ * unrecognized client gets the tools. Enabling only un-hides tools the resolved
+ * profile already registered; it never bypasses `ACTIVE_GROUPS`, the capability
+ * gate, or backend authorization.
+ *
+ * Nothing here writes a notification to the transport. The SDK's `update()` path
+ * (`mcp.js`) fires `sendToolListChanged()` itself and no-ops it while
+ * unconnected, so the startup `.disable()` emits nothing and a post-connect
+ * `.enable()` notifies automatically.
+ */
+/**
+ * The three gated tools, as a fixed list.
+ *
+ * This is the user-visible identity of the gated set and is asserted verbatim by
+ * tests; it is deliberately a literal rather than something derived from the
+ * registration order in `index.ts`.
+ */
+export const LEARN_GATED_TOOL_NAMES = [
+    "apply_install_manifest",
+    "invite_member",
+    "regenerate_directory_map",
+];
+/** The pipeline name whose successful resolution is a qualifying trigger. */
+export const LEARN_REPOSITORY_PIPELINE_NAME = "learn-repository";
+/**
+ * Clients empirically verified to honor a mid-session
+ * `notifications/tools/list_changed` — the only clients for which it is safe to
+ * hide the trio at startup.
+ *
+ * `claude-code` is an **observed MCP handshake identity**, captured on
+ * 2026-08-26 from a live Claude Code 2.1.246 session against a throwaway stdio
+ * MCP server, which recorded:
+ *
+ *     "clientInfo": { "name": "claude-code", "title": "Claude Code",
+ *                     "version": "2.1.246", ... }
+ *
+ * The same capture confirmed the behavior that matters: after the server emitted
+ * `notifications/tools/list_changed`, Claude Code re-issued `tools/list` and
+ * called the newly revealed tool inside the same session.
+ *
+ * It happens to equal the `MCP_HOST_TARGETS` id `"claude-code"`, but it is NOT
+ * copied from it — those ids are host-config target names, a different
+ * namespace. This constant is pinned to the observed handshake value.
+ *
+ * Deliberately NOT on this list:
+ *   - **Cursor** — reported to ignore mid-session list changes; could not be
+ *     verified locally (`cursor-agent` requires authentication). Fail-open
+ *     covers it: Cursor receives the trio at startup.
+ *   - **GitHub Copilot CLI** (`github-copilot-developer`) — *passed* the same
+ *     probe on 2026-08-26 (CLI 1.0.71 re-listed and called the revealed tool).
+ *     Left off pending owner sign-off, since this list ships with Claude Code as
+ *     its sole initial entry; promoting it is a one-line, zero-risk follow-up.
+ *   - **VS Code / Copilot Chat extension** — a different product from the CLI
+ *     above, with its own handshake identity. Not probed; not claimed.
+ */
+export const KNOWN_LIST_CHANGED_CLIENT_NAMES = new Set([
+    "claude-code",
+]);
+// ---------------------------------------------------------------------------
+// Client identity
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a client-supplied name for *matching*: require a string, trim it,
+ * lowercase it. Anything else — absent, null, number, object, array, blank — is
+ * unrecognized, which is the fail-open direction.
+ *
+ * The result of this function is only ever compared for exact membership. It is
+ * never logged; `sanitizeClientName` owns the display value, and the two must
+ * not be interchanged.
+ */
+export function normalizeClientName(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "" ? null : normalized;
+}
+/**
+ * Exact, trimmed, case-insensitive token membership.
+ *
+ * Deliberately NOT substring, prefix, or product-family matching:
+ * `clientInfo.name` is client-controlled, and a substring test would let
+ * `"not-claude-code"` or `"claude-code-preview"` keep tools hidden from a client
+ * that may not honor `tools/list_changed` at all.
+ */
+export function isKnownListChangedClient(raw) {
+    const normalized = normalizeClientName(raw);
+    return normalized !== null && KNOWN_LIST_CHANGED_CLIENT_NAMES.has(normalized);
+}
+/** Longest client name rendered into a log line. */
+export const MAX_LOGGED_CLIENT_NAME_LENGTH = 64;
+/** Substituted for absent, non-string, blank, or fully-stripped input. */
+export const UNKNOWN_CLIENT_NAME = "unknown";
+/**
+ * Bound and restrict an untrusted `clientInfo.name` for logging.
+ *
+ * `clientInfo.name` is attacker-controlled text that lands on stderr, so this is
+ * a log-forging control, not cosmetics: newlines, ANSI escapes, quotes, and
+ * shell punctuation all fall outside the safe class and become `_`, so no client
+ * can inject a second line that reads like a genuine record. The result is
+ * single-line, length-bounded, and drawn only from `[A-Za-z0-9._/-]`.
+ *
+ * The same posture `mcp-profile.ts` states for profile tokens: raw input is
+ * never echoed.
+ */
+export function sanitizeClientName(raw) {
+    if (typeof raw !== "string")
+        return UNKNOWN_CLIENT_NAME;
+    const cleaned = raw
+        .trim()
+        .slice(0, MAX_LOGGED_CLIENT_NAME_LENGTH)
+        .replace(/[^A-Za-z0-9._/-]/g, "_");
+    // A value made entirely of unsafe characters degrades to underscores, which
+    // reads as a real name; report it as unknown instead.
+    return cleaned === "" || /^_+$/.test(cleaned) ? UNKNOWN_CLIENT_NAME : cleaned;
+}
+// ---------------------------------------------------------------------------
+// Trigger predicates
+// ---------------------------------------------------------------------------
+/**
+ * Extract the text payload from either a raw string or an MCP `{content:[…]}`
+ * response envelope. Returns null when there is no text content.
+ */
+function extractResponseText(candidate) {
+    if (typeof candidate === "string")
+        return candidate;
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+        return null;
+    const content = candidate.content;
+    if (!Array.isArray(content))
+        return null;
+    for (const item of content) {
+        if (item && typeof item === "object" && !Array.isArray(item)) {
+            const text = item.text;
+            if (typeof text === "string")
+                return text;
+        }
+    }
+    return null;
+}
+/**
+ * `get_install_manifest` appends a save note (`\n\n---\nSaved to …`) to its JSON
+ * body whenever `save_locally` is not explicitly false — which is the default,
+ * and therefore the common case. Stripping it here is what keeps the predicate
+ * from silently rejecting every ordinary successful manifest.
+ */
+function stripSaveNote(text) {
+    const marker = text.indexOf("\n\n---\n");
+    return marker === -1 ? text : text.slice(0, marker);
+}
+/**
+ * True only for a genuinely successful install manifest.
+ *
+ * "Successful" is defined against the real response contract rather than
+ * "did not throw": the body must parse as a JSON object (not null, not an
+ * array), must not be an error envelope, and must carry a nonblank
+ * `snapshot_token` — the signed token `apply_install_manifest` requires, and the
+ * field whose presence distinguishes a real manifest from any other JSON the
+ * endpoint might return.
+ *
+ * Every parse failure is swallowed and reported as false, leaving gate state
+ * unchanged. A non-JSON body, an error response, `{}`, a blank token, or a
+ * whitespace-only token must never enable the set.
+ */
+export function isSuccessfulInstallManifestResponse(candidate) {
+    const text = extractResponseText(candidate);
+    if (text === null)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(stripSaveNote(text));
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return false;
+    const body = parsed;
+    // An explicit error envelope (handleResponse's failure shape, or the
+    // TOOL_DISABLED envelope) is never a success, even if it somehow carried a
+    // token-shaped field.
+    if (typeof body.error === "string")
+        return false;
+    const token = body.snapshot_token;
+    return typeof token === "string" && token.trim() !== "";
+}
+// ---------------------------------------------------------------------------
+// The one-shot gate
+// ---------------------------------------------------------------------------
+/**
+ * Build the learn-tool gate over three SDK handles.
+ *
+ * The gate owns one boolean for the whole set: the three tools are enabled
+ * atomically from the server's perspective, so no caller can observe a partially
+ * revealed trio, and there is no per-tool dispatch registry to drift.
+ */
+export function createLearnToolGate(deps) {
+    const sink = deps.sink ?? ((message) => console.error(message));
+    let enabled = false;
+    let cause = null;
+    const ordered = LEARN_GATED_TOOL_NAMES.map((name) => deps.handles[name]);
+    return {
+        disableAll() {
+            for (const handle of ordered)
+                handle.disable();
+        },
+        enableOnce(trigger) {
+            if (enabled)
+                return;
+            // Set the transition state BEFORE touching the handles: `.enable()` drives
+            // the SDK update path, which can notify synchronously, and a re-entrant
+            // trigger must find the set already transitioned rather than enable twice.
+            enabled = true;
+            cause = trigger;
+            for (const handle of ordered)
+                handle.enable();
+            // Exactly one structured stderr line per gated-set enable. Follows the
+            // established key=value shape (`tool-surface gating: reason=… hidden=…`).
+            // The client name is the sanitized display value — never the raw
+            // handshake input, and never the normalized matching token.
+            sink(`learn tool gating: enabled=${ordered.length} ` +
+                `trigger=${trigger} ` +
+                `client=${sanitizeClientName(deps.getClientName())} ` +
+                `tools=[${LEARN_GATED_TOOL_NAMES.join(",")}]`);
+        },
+        isEnabled() {
+            return enabled;
+        },
+        enabledBy() {
+            return cause;
+        },
+    };
+}

package/build/mcp-profile.js

@@ -5,13 +5,18 @@
  * profile to a multi-valued group set. BRIDGE_MCP_PROFILE accepts a
  * comma-separated list of group tokens; unknown tokens are silently dropped
  * (security sentinel — raw input is never echoed). "core" is always implicitly
- * included. "full" is an input shortcut that expands to every known group.
+ * included. "full" is an input shortcut that expands to all six known groups.
  *
- * Groups are resolved once at process startup and cannot change mid-session.
+ * Groups are resolved once at process startup and cannot change mid-session:
+ * changing BRIDGE_MCP_PROFILE requires restarting the MCP server. This is
+ * startup-time registration filtering, which is a different mechanism from the
+ * session-lifetime SDK enabled-state gating applied to the learn/onboarding
+ * trio in index.ts (BAPI-912).
  */
 const VALID_GROUPS = new Set([
     "core",
     "conductor",
+    "estimation",
     "pipeline-authoring",
     "sfcc",
     "sfcc-write",
@@ -20,7 +25,8 @@ const VALID_GROUPS = new Set([
  * Resolve the active MCP groups from a raw env-var string.
  *
  * - `undefined` or blank → `{"core"}` (fail-safe to smallest surface).
- * - `"full"` (any case) → all five groups, `sfcc-write` included.
+ * - `"full"` (any case) → all six groups, `estimation` and `sfcc-write`
+ *   included.
  * - Comma-separated list: each token is trimmed, lowercased, and checked
  *   against VALID_GROUPS. Unknown tokens are dropped. Known tokens are unioned
  *   with the implicit `"core"` baseline.
@@ -38,9 +44,13 @@ export function resolveProfiles(raw) {
         return baseline;
     const tokens = trimmed.split(",").map((t) => t.trim().toLowerCase());
     if (tokens.some((t) => t === "full")) {
+        // Deliberately a hard-coded complete expansion, not `VALID_GROUPS`: `full`
+        // must name every group so that adding a group is a conscious decision here
+        // rather than an implicit widening of an existing user's surface.
         return new Set([
             "core",
             "conductor",
+            "estimation",
             "pipeline-authoring",
             "sfcc",
             "sfcc-write",

package/build/mcp-server-invocation.js

@@ -30,6 +30,20 @@ export const MCP_SERVER_PACKAGE_NAME = MCP_PACKAGE_NAME;
  * reintroduce the ETARGET/404 failure the absolute-path form exists to remove.
  */
 export const DEFAULT_MCP_SERVER_NPM_CHANNEL_SPEC = `${MCP_PACKAGE_NAME}@latest`;
+/**
+ * Detect a packaged-CLI entry path that lives inside a transient npx cache
+ * directory (`~/.npm/_npx/<hash>/…` on POSIX, `…\npm-cache\_npx\<hash>\…` on
+ * Windows). Such an entry point may be garbage-collected when the npx cache is
+ * pruned, so anything that bakes it into durable state (a generated service
+ * unit, a registered schedule) would later fail with ENOENT on
+ * `node <gone-path>`. Matched on the `_npx` path *segment* so detection is
+ * independent of the surrounding cache root and works for either separator.
+ */
+export function isTransientNpxEntryPath(entryPath) {
+    if (!entryPath)
+        return false;
+    return /[\\/]_npx[\\/]/.test(entryPath);
+}
 /**
  * Build the concrete `{ command, args }` launch pair for a target + worktree from
  * a structured invocation. Pure — no filesystem or process access. The