@stigmer/runner 3.8.0 → 3.10.0

package/src/shared/mcp-manager.ts

@@ -10,9 +10,22 @@
  * 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";
@@ -32,11 +45,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") {
@@ -91,23 +111,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/model-registry.ts

@@ -1,10 +1,13 @@
 /**
- * Model registry — provider lookup and economy-tier model derivation.
+ * Model registry — provider lookup, economy-tier model derivation, and
+ * model capability resolution.
  *
  * Fetches the model registry from the runner's control plane (see
  * registry-endpoint.ts for endpoint resolution — same endpoint as
  * model-pricing-data.ts) and uses `costTier` + `harness` fields to
- * dynamically resolve economy-tier models for extraction/summarization.
+ * dynamically resolve economy-tier models for extraction/summarization,
+ * plus `capabilities` catalog metadata for per-model capability lookups
+ * (getModelVisionCapability).
  */
 
 import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
@@ -22,6 +25,14 @@ interface RegistryModel {
   costTier: string;
   harness: string;
   featured: boolean;
+  /**
+   * Tri-state vision capability from the registry's `capabilities` block.
+   * The registry serializes `capabilities` only for models whose capabilities
+   * have actually been assessed, so `undefined` means "never assessed" —
+   * deliberately distinct from an explicit `false` ("assessed as blind").
+   * Consumers gate only on the explicit `false` (see attachment-vision.ts).
+   */
+  visionCapability?: boolean;
 }
 
 let cache: { models: readonly RegistryModel[]; expiresAt: number } | null = null;
@@ -41,9 +52,20 @@ function parseRegistry(json: unknown): RegistryModel[] {
       costTier: (m.costTier as string) ?? "standard",
       harness: (m.harness as string) ?? "native",
       featured: !!m.featured,
+      visionCapability: parseVisionCapability(m.capabilities),
     }));
 }
 
+/**
+ * Extract `capabilities.vision` preserving the tri-state: a missing or
+ * malformed `capabilities` block stays `undefined` (never coerced to false).
+ */
+function parseVisionCapability(capabilities: unknown): boolean | undefined {
+  if (!capabilities || typeof capabilities !== "object") return undefined;
+  const vision = (capabilities as Record<string, unknown>).vision;
+  return typeof vision === "boolean" ? vision : undefined;
+}
+
 async function fetchRegistry(): Promise<readonly RegistryModel[]> {
   const url = resolveModelRegistryUrl();
   const res = await fetch(url, { headers: buildRegistryHeaders() });
@@ -211,6 +233,32 @@ export async function resolveToApiModelId(registryId: string): Promise<string> {
   return entry.apiModelId ?? registryId;
 }
 
+/**
+ * Look up a model's vision capability from the registry's `capabilities`
+ * catalog metadata. Returns the tri-state the vision policy expects
+ * (attachment-vision.ts): `false` only when the registry explicitly says the
+ * model cannot see images; `undefined` whenever the answer is unknown —
+ * capability never assessed, model not in the registry, registry
+ * unreachable, or no concrete model name (the Cursor harness's ""/"default"
+ * Auto pool). Callers gate on the explicit `false` only, so every unknown
+ * degrades to today's behavior instead of blocking images.
+ *
+ * Matches by registry `id` OR `apiModelId`: getDefaultModel() hands the
+ * deep-agent harness the provider API id, while executionConfig.modelName
+ * carries the registry id, so both forms arrive here.
+ */
+export async function getModelVisionCapability(
+  modelName: string,
+): Promise<boolean | undefined> {
+  if (!modelName || modelName === "default") return undefined;
+
+  const registry = await getRegistry();
+  const entry = registry.find(
+    (m) => m.id === modelName || m.apiModelId === modelName,
+  );
+  return entry?.visionCapability;
+}
+
 /** Exposed for testing — resets the in-memory cache. */
 export function _resetRegistryCache(): void {
   cache = null;