@stigmer/runner 3.9.0 → 3.11.0

package/src/shared/mcp-manager.ts

@@ -4,21 +4,37 @@
  * Wraps @langchain/mcp-adapters MultiServerMCPClient with:
  * - Conversion from ResolvedMcpServer[] to the SDK's Connection config
  * - Proper async cleanup via close()
- * - Tool filtering based on discovered capabilities
+ * - Tool filtering by each server's effective enabled_tools allow-list
+ *   (issue #350; semantics in shared/mcp-enabled-tools.ts) — the model only
+ *   ever sees the tools the agent's manifest enables
  *
  * Transport policy (stdio is local-runner-only) is enforced upstream at
  * resolution time by shared/mcp-transport-guard.ts — servers reaching
  * this manager have already passed it.
  *
+ * Stdio env contract (oss#256): a subprocess receives exactly the
+ * variables declared in the server's spec.env (resolved upstream by
+ * filterEnvToDeclaredKeys) plus the MCP SDK's minimal base environment
+ * (HOME, LOGNAME, PATH, SHELL, TERM, USER — getDefaultEnvironment in
+ * @modelcontextprotocol/sdk, merged under whatever we pass). The
+ * runner's own process env is never passed: it carries runner-internal
+ * credentials (STIGMER_TOKEN, STIGMER_RUNNER_HITL_SECRET,
+ * CURSOR_API_KEY, LLM provider keys) that no third-party MCP subprocess
+ * may see. A declared-empty env and an undeclared env are deliberately
+ * equivalent — both yield the SDK base environment.
+ *
  * The Cursor execution path does NOT use this manager — it passes MCP
  * configs directly to the Cursor SDK via toCursorMcpConfig(). This
- * manager is exclusively for LangGraph-based deep agent executions.
+ * manager serves LangGraph-based deep agent executions, and discovery
+ * (activities/discover-mcp-server.ts) builds its spawn config through
+ * toMcpClientConfig too.
  */
 
 import { MultiServerMCPClient } from "@langchain/mcp-adapters";
 import type { Connection } from "@langchain/mcp-adapters";
 import type { DynamicStructuredTool } from "@langchain/core/tools";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { filterToolsByEnabledTools } from "./mcp-enabled-tools.js";
 
 /**
  * Convert harness-agnostic ResolvedMcpServer[] into the
@@ -32,11 +48,18 @@ export function toMcpClientConfig(
   for (const server of servers) {
     if (server.connectionType === "stdio") {
       if (!server.command) continue;
+      if (!server.env || Object.keys(server.env).length === 0) {
+        console.log(
+          `[MCP] Server '${server.slug}' declares no env — its subprocess ` +
+          `starts with the minimal base environment only. Declare variables ` +
+          `in the McpServer's spec.env to pass them.`,
+        );
+      }
       config[server.slug] = {
         transport: "stdio",
         command: server.command,
         args: server.args ?? [],
-        env: server.env ?? processEnvAsStrings(),
+        env: server.env,
         cwd: server.cwd,
       };
     } else if (server.connectionType === "http" || server.connectionType === "sse") {
@@ -75,11 +98,25 @@ export async function connectMcpServers(
   }
 
   const client = new MultiServerMCPClient(connectionConfig);
-  const serverToolMap = await client.initializeConnections();
+  const discoveredToolMap = await client.initializeConnections();
 
+  // Enforce each server's effective enabled_tools allow-list (issue #350)
+  // HERE, before anything downstream sees the tools: the parent tool list,
+  // the approval gate's toolServerMap, and the sub-agent McpAccess filter
+  // (whose subset-of-parent check is only real against a narrowed map) all
+  // derive from this result. Servers without a restriction (enabledTools
+  // absent — including synthesized attachments) pass through untouched.
+  const enabledBySlug = new Map(
+    servers.map((s) => [s.slug, s.enabledTools]),
+  );
+  const serverToolMap: Record<string, DynamicStructuredTool[]> = {};
   const tools: DynamicStructuredTool[] = [];
-  for (const serverTools of Object.values(serverToolMap)) {
-    tools.push(...serverTools);
+  for (const [slug, discovered] of Object.entries(discoveredToolMap)) {
+    const filtered = filterToolsByEnabledTools(
+      slug, discovered, enabledBySlug.get(slug),
+    );
+    serverToolMap[slug] = filtered;
+    tools.push(...filtered);
   }
 
   console.log(
@@ -91,23 +128,3 @@ export async function connectMcpServers(
 
   return { client, tools, serverToolMap };
 }
-
-/**
- * Snapshot of process.env as a string-only record (no undefined values).
- * Used as a fallback when an MCP server has no declared env — the
- * subprocess inherits the runner's full environment, matching standard
- * Unix child-process behavior.
- *
- * Without this, @modelcontextprotocol/sdk only passes a restricted
- * whitelist (HOME, PATH, USER, etc.) which drops platform variables
- * like STIGMER_SERVER_ADDRESS.
- */
-function processEnvAsStrings(): Record<string, string> {
-  const env: Record<string, string> = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (value !== undefined) {
-      env[key] = value;
-    }
-  }
-  return env;
-}

package/src/shared/mcp-resolver.ts

@@ -11,7 +11,7 @@
  * there until the two are consolidated.
  */
 
-import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { McpServerUsage, ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
@@ -26,6 +26,7 @@ import {
   filterEnvToDeclaredKeys,
   PlaceholderResolutionError,
 } from "./placeholder-resolver.js";
+import { effectiveEnabledTools } from "./mcp-enabled-tools.js";
 
 /**
  * Harness-agnostic intermediate representation of a resolved MCP server.
@@ -45,6 +46,28 @@ export interface ResolvedMcpServer {
   toolApprovals: ToolApprovalPolicy[];
   pinnedToolApprovals: ToolApprovalPolicy[];
   discoveredCapabilitiesEmpty: boolean;
+  /**
+   * The EFFECTIVE tool allow-list for this server (issue #350): the usage's
+   * enabled_tools, falling back to the server's default_enabled_tools when
+   * the usage's list is empty (see shared/mcp-enabled-tools.ts). Absent when
+   * unrestricted — which keeps synthesized attachment servers (built without
+   * a usage) and the discovery path unfiltered by construction. Enforced at
+   * connect time by connectMcpServers (shared/mcp-manager.ts).
+   */
+  enabledTools?: string[];
+  /**
+   * Layer-3 per-agent approval overrides from the usage that resolved this
+   * server (issue #349): riding the resolved server is what SCOPES an
+   * override to its own server — a flat cross-server list is how an
+   * override once leaked onto (or silently un-gated) a same-named tool on
+   * another server. Deliberately REQUIRED, not optional: empty means "no
+   * overrides", and every construction site — including the near-duplicate
+   * Cursor resolver and the synthesized attachments, which have no usage
+   * and therefore no layer 3 — must say so explicitly, so a forgotten
+   * mirror cannot compile. Consumed by mergeApprovalPolicies
+   * (shared/approval-policy.ts).
+   */
+  toolApprovalOverrides: ToolApprovalOverride[];
 }
 
 export interface McpResolutionResult {
@@ -78,7 +101,13 @@ export async function resolveMcpServers(
         envVars,
         ref.slug,
       );
-      const server = mcpServerToResolved(mcpServer, ref.slug, serverEnv);
+      const server = mcpServerToResolved(
+        mcpServer,
+        ref.slug,
+        serverEnv,
+        usage.enabledTools,
+        usage.toolApprovalOverrides ?? [],
+      );
       if (server) {
         assertTransportAllowed(server.slug, server.connectionType, transportPosture);
         resolved.push(server);
@@ -108,6 +137,8 @@ export function mcpServerToResolved(
   server: McpServer,
   slug: string,
   envVars: Record<string, string>,
+  usageEnabledTools?: readonly string[],
+  usageToolApprovalOverrides: ToolApprovalOverride[] = [],
 ): ResolvedMcpServer | null {
   const spec = server.spec;
   if (!spec) return null;
@@ -123,6 +154,13 @@ export function mcpServerToResolved(
     toolApprovals,
     pinnedToolApprovals,
     discoveredCapabilitiesEmpty,
+    // Callers without a usage (the discovery activity) pass nothing, so the
+    // default_enabled_tools fallback still applies but a per-agent
+    // restriction cannot: discovery must see the server's full toolset.
+    enabledTools: effectiveEnabledTools(usageEnabledTools, spec.defaultEnabledTools),
+    // Same no-usage rule for layer 3: discovery has no agent context, so no
+    // per-agent overrides exist — defaulting to [] keeps that structural.
+    toolApprovalOverrides: usageToolApprovalOverrides,
   };
 
   switch (spec.serverType.case) {
@@ -170,4 +208,37 @@ export function extractMcpServerSlugs(usages: McpServerUsage[]): string[] {
     .filter((s): s is string => !!s);
 }
 
+/**
+ * Merge MCP server usages from agent (base) and session (overlay).
+ *
+ * Replicates session_context_merge.py::merge_mcp_server_usages():
+ * - Agent-level usages are the base set
+ * - Session-level usages extend or override by mcp_server_ref.slug
+ * - If both reference the same slug, session-level takes precedence —
+ *   the WHOLE usage, including enabled_tools and approval overrides
+ *
+ * Shared by both harnesses (blueprint-resolver.ts for Cursor,
+ * execute-deep-agent/setup.ts for the native harness) so a duplicate slug
+ * resolves identically everywhere: exactly one usage per server, whose
+ * enabled_tools is the one the enforcement filter honors.
+ */
+export function mergeMcpServerUsages(
+  agentUsages: McpServerUsage[],
+  sessionUsages: McpServerUsage[],
+): McpServerUsage[] {
+  const bySlug = new Map<string, McpServerUsage>();
+
+  for (const usage of agentUsages) {
+    const slug = usage.mcpServerRef?.slug;
+    if (slug) bySlug.set(slug, usage);
+  }
+
+  for (const usage of sessionUsages) {
+    const slug = usage.mcpServerRef?.slug;
+    if (slug) bySlug.set(slug, usage);
+  }
+
+  return [...bySlug.values()];
+}
+
 export { PlaceholderResolutionError } from "./placeholder-resolver.js";

package/src/shared/model-client.ts

@@ -6,10 +6,11 @@
  * (e.g. "claude-haiku-4-5-20251001") before a client is built — so no
  * activity can bypass the translation and 404 the provider.
  *
- * Layering: `llm-proxy.ts` stays pure routing utilities (no LangChain
- * dependency); this module is the LangChain-aware layer above it that owns
- * the resolve -> infer-provider -> strip-prefix -> proxy-wire -> construct
- * sequence that used to be copy-pasted across every LLM activity.
+ * Layering: `llm-proxy.ts` and `llm-backend.ts` stay pure routing utilities
+ * (no LangChain dependency); this module is the LangChain-aware layer above
+ * them that owns the resolve -> infer-provider -> strip-prefix ->
+ * proxy-or-backend-wire -> construct sequence that used to be copy-pasted
+ * across every LLM activity.
  */
 
 import { ChatAnthropic } from "@langchain/anthropic";
@@ -23,6 +24,15 @@ import {
   buildProxyHeaders,
   type LlmProvider,
 } from "./llm-proxy.js";
+import {
+  resolveAnthropicBackend,
+  checkVertexPrerequisites,
+  checkBedrockPrerequisites,
+  checkFoundryPrerequisites,
+  toVertexModelId,
+  toBedrockModelId,
+  toFoundryDeploymentName,
+} from "./llm-backend.js";
 import { resolveToApiModelId } from "./model-registry.js";
 
 export interface BuildChatModelOptions {
@@ -52,7 +62,13 @@ export interface BuildChatModelOptions {
 export interface BuiltChatModel {
   readonly model: BaseChatModel;
   readonly provider: LlmProvider;
-  /** The resolved id actually handed to the provider. */
+  /**
+   * The canonical provider API id the registry resolved to — what pricing
+   * and usage metrics key on. A backend adapter may translate it for the
+   * wire (Vertex separates the snapshot date with `@`), but the translated
+   * form never leaves the adapter: this field stays canonical (the
+   * canonical-id invariant in design decision 001-provider-backends).
+   */
   readonly apiModelId: string;
 }
 
@@ -67,6 +83,105 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   const provider = inferProvider(resolved);
   const apiModelId = stripProviderPrefix(resolved);
 
+  // Backend precedence by construction: a proxied call never consults the
+  // backend var — the proxy owns provider routing (the factories' preflight
+  // warns when both are configured). Selection is deployment-static and read
+  // here the same way provider API keys are, not plumbed through Config.
+  const anthropicBackend =
+    provider === "anthropic" && !opts.proxyEndpoint
+      ? resolveAnthropicBackend()
+      : "public";
+
+  // Backend SDKs (and their auth subtrees: google-auth-library, AWS smithy)
+  // load lazily so deployments that never configure a backend never
+  // evaluate them — cheap cold starts stay cheap, and bundle-slim's CJS
+  // output preserves exactly this deferred evaluation (see
+  // scripts/bundle-slim.mjs). The factory is invoked lazily by
+  // ChatAnthropic once per cached client (batch + streaming), so the class
+  // is captured here, in async context.
+  //
+  // Each factory MUST honor options.maxRetries and options.timeout:
+  // LangChain owns retrying and hands the factory maxRetries: 0 — a factory
+  // that drops it nests the SDK's default 2 retries inside LangChain's
+  // retry loop, multiplying every transient failure — and `timeout` arrives
+  // through the same options object (ChatAnthropic spreads clientOptions
+  // into it), so a factory that drops it silently unbounds
+  // STIGMER_LLM_REQUEST_TIMEOUT_MS on that backend. Pinned by the seam
+  // tests. Prerequisites are re-checked here (not only in
+  // the factories' preflight) so paths that construct models without a
+  // runner factory still fail at dispatch with the catalog message instead
+  // of mid-request. Credentials are read natively by each SDK from its
+  // standard conventions (GCP: CLOUD_ML_REGION + ADC; AWS: AWS_REGION +
+  // the credential chain / AWS_BEARER_TOKEN_BEDROCK; Foundry:
+  // ANTHROPIC_FOUNDRY_API_KEY, or the Azure credential chain when no key
+  // is set).
+  let backendCreateClient:
+    | ((options: { maxRetries?: number; timeout?: number }) => unknown)
+    | undefined;
+  let wireModelId = apiModelId;
+  let maxTokens = opts.maxTokens;
+  if (anthropicBackend === "vertex") {
+    const prereq = checkVertexPrerequisites();
+    if (prereq !== null) throw new Error(prereq);
+    const { AnthropicVertex } = await import("@anthropic-ai/vertex-sdk");
+    backendCreateClient = (options) =>
+      new AnthropicVertex({ maxRetries: options.maxRetries, timeout: options.timeout });
+    wireModelId = toVertexModelId(apiModelId);
+  } else if (anthropicBackend === "bedrock") {
+    const prereq = checkBedrockPrerequisites();
+    if (prereq !== null) throw new Error(prereq);
+    const { AnthropicBedrock } = await import("@anthropic-ai/bedrock-sdk");
+    backendCreateClient = (options) =>
+      new AnthropicBedrock({ maxRetries: options.maxRetries, timeout: options.timeout });
+    wireModelId = toBedrockModelId(apiModelId);
+    if (maxTokens === undefined) {
+      // LangChain's per-model maxTokens table prefix-matches the model
+      // name. Vertex's translated ids still match their canonical prefix;
+      // Bedrock's `anthropic.…` ids match nothing and silently fall back
+      // to 4096 — a silent output cap. Probe the CANONICAL id with a
+      // throwaway construction (pure field assignment, no I/O; the key is
+      // never used) so bedrock inherits exactly the default the public API
+      // and vertex get for the same model — including models the table
+      // doesn't know yet, where all backends agree on the fallback.
+      // Pinned by the canonical-parity test in bedrock-adapter.test.ts.
+      maxTokens = new ChatAnthropic({ model: apiModelId, apiKey: "max-tokens-probe" }).maxTokens;
+    }
+  } else if (anthropicBackend === "foundry") {
+    const prereq = checkFoundryPrerequisites();
+    if (prereq !== null) throw new Error(prereq);
+    const { AnthropicFoundry } = await import("@anthropic-ai/foundry-sdk");
+    // Auth is an explicit either/or (the Foundry constructor throws when
+    // given both a key and a token provider): ANTHROPIC_FOUNDRY_API_KEY if
+    // present, otherwise keyless Microsoft Entra ID through the Azure
+    // credential chain (env service principal -> workload identity ->
+    // managed identity -> az CLI) — the Azure analogue of Vertex ADC and
+    // the AWS chain, resolved at request time. The provider is built once
+    // here (getBearerTokenProvider caches tokens until near-expiry) and
+    // shared by both cached clients; the SDK still consults it per request,
+    // so refreshed tokens flow without reconstruction (pinned by
+    // foundry-seam.test.ts). Endpoint (resource or base URL) and the key
+    // are read natively by the SDK from its own env vars.
+    let azureADTokenProvider: (() => Promise<string>) | undefined;
+    if (!process.env.ANTHROPIC_FOUNDRY_API_KEY?.trim()) {
+      const { DefaultAzureCredential, getBearerTokenProvider } = await import("@azure/identity");
+      azureADTokenProvider = getBearerTokenProvider(
+        new DefaultAzureCredential(),
+        "https://ai.azure.com/.default",
+      );
+    }
+    backendCreateClient = (options) =>
+      new AnthropicFoundry({
+        maxRetries: options.maxRetries,
+        timeout: options.timeout,
+        ...(azureADTokenProvider ? { azureADTokenProvider } : {}),
+      });
+    // Unlike the vertex/bedrock ids, the deployment name needs no maxTokens
+    // handling: stripping the snapshot date preserves LangChain's per-model
+    // default (probed 2026-08-11 across the full catalog; pinned by the
+    // parity test in foundry-adapter.test.ts).
+    wireModelId = toFoundryDeploymentName(apiModelId);
+  }
+
   const baseUrl = opts.proxyEndpoint
     ? resolveProxyBaseUrl(opts.proxyEndpoint, provider)
     : undefined;
@@ -85,9 +200,29 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   const common = {
     temperature: opts.temperature ?? 0,
     apiKey,
-    ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
-    ...(opts.timeoutMs ? { maxRetries: opts.maxRetries ?? 0, timeout: opts.timeoutMs } : {}),
+    ...(maxTokens ? { maxTokens } : {}),
+    ...(opts.timeoutMs ? { maxRetries: opts.maxRetries ?? 0 } : {}),
+  };
+
+  // The request timeout lives in a different slot per wrapper: ChatOpenAI
+  // reads `timeout` as a constructor field, but ChatAnthropic ignores it
+  // there — its slot is `clientOptions.timeout`, which the wrapper spreads
+  // into the createClient factory options and (on the default factory) the
+  // SDK constructor. This split is what makes STIGMER_LLM_REQUEST_TIMEOUT_MS
+  // bound every path; putting `timeout` in the shared constructor spread is
+  // the exact regression that made it inert for Anthropic (T02 finding 2).
+  // The `maxRetries` half above stays constructor-level for both wrappers:
+  // that is LangChain's own retry knob, distinct from the SDK-level
+  // maxRetries the factories receive.
+  const anthropicClientOptions = {
+    ...(opts.timeoutMs ? { timeout: opts.timeoutMs } : {}),
+    ...(baseUrl ? { baseURL: baseUrl } : {}),
+    ...(headers ? { defaultHeaders: headers } : {}),
   };
+  const anthropicClientOptionsField =
+    Object.keys(anthropicClientOptions).length > 0
+      ? { clientOptions: anthropicClientOptions }
+      : {};
 
   // The two SDKs name the transport-override block differently (OpenAI:
   // `configuration`, Anthropic: `clientOptions`) — encapsulating that here is
@@ -96,6 +231,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     ? new ChatOpenAI({
         model: apiModelId,
         ...common,
+        ...(opts.timeoutMs ? { timeout: opts.timeoutMs } : {}),
         ...(baseUrl || headers
           ? {
               configuration: {
@@ -105,18 +241,24 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
             }
           : {}),
       })
-    : new ChatAnthropic({
-        model: apiModelId,
-        ...common,
-        ...(baseUrl || headers
-          ? {
-              clientOptions: {
-                ...(baseUrl ? { baseURL: baseUrl } : {}),
-                ...(headers ? { defaultHeaders: headers } : {}),
-              },
-            }
-          : {}),
-      });
+    : backendCreateClient
+      ? // Backend adapter: the translated id is wire detail only — each
+        // client moves it from the JSON body into its URL path. The waiver
+        // in ChatAnthropic (an API key is not required when createClient is
+        // provided) is what lets this construct with no ANTHROPIC_API_KEY.
+        // (Backend mode never has a proxy — see the precedence rule above —
+        // so the clientOptions here carry at most the timeout.)
+        new ChatAnthropic({
+          model: wireModelId,
+          ...common,
+          ...anthropicClientOptionsField,
+          createClient: backendCreateClient,
+        })
+      : new ChatAnthropic({
+          model: apiModelId,
+          ...common,
+          ...anthropicClientOptionsField,
+        });
 
   return { model, provider, apiModelId };
 }