@stigmer/runner 3.11.0 → 3.11.1-dev.20260812192248

package/src/shared/mcp-schema-sanitizer.ts

@@ -0,0 +1,224 @@
+/**
+ * Unicode-flag regex sanitization for MCP tool input schemas (issue #420).
+ *
+ * Why this exists: real-world MCP servers ship JSON-schema `pattern` values
+ * that are legal as plain ECMAScript regexes but invalid under the unicode
+ * flag (PayPal's `^https\:\/\/` — `\:` is an invalid escape under /u).
+ * @langchain/core validates tool input on EVERY call with
+ * @cfworker/json-schema, which compiles patterns via `new RegExp(p, "u")`
+ * at exactly two uncaught sites: the `pattern` keyword and each
+ * `patternProperties` key. One bad vendor pattern therefore makes the tool
+ * permanently uncallable on the deep-agent path — every invocation dies
+ * with a cryptic SyntaxError before the tool is ever reached. (The third
+ * /u compile site, `format: "regex"`, validates instance values inside a
+ * try/catch and fails gracefully — not a crash surface.)
+ *
+ * The fix: at the deep-agent connect funnel (mcp-manager.ts
+ * connectMcpServers), drop every pattern that cannot compile under /u.
+ * Dropping is deliberate — rewriting to a /u-safe equivalent would need an
+ * Annex-B-aware regex transpiler, disproportionate machinery for what is
+ * best-effort client-side validation; the MCP server still validates its
+ * own inputs server-side. This mirrors the loosening posture of
+ * @langchain/mcp-adapters' own schema pipeline (dereferenceJsonSchema →
+ * simplifyJsonSchemaForLLM), which already normalizes schemas for this
+ * exact validator.
+ *
+ * THE INVARIANT: sanitization may only ever LOOSEN validation, never
+ * tighten it. Dropping a `patternProperties` entry naively would violate
+ * this — @cfworker marks pattern-matched keys as "evaluated" and routes
+ * unevaluated keys into the `additionalProperties` / `unevaluatedProperties`
+ * checks, so under `additionalProperties: false` the drop would flip a
+ * crash into a false REJECTION of valid inputs. Whenever a
+ * `patternProperties` entry is dropped, any restrictive
+ * `additionalProperties` / `unevaluatedProperties` at that schema level is
+ * therefore relaxed too.
+ *
+ * Scope: this sanitizer serves the EXECUTION path only. Discovery
+ * (activities/discover-mcp-server.ts) persists tool schemas verbatim from
+ * listTools — deliberately: the stored schema is the vendor's truth for
+ * display, and discovery never invokes tools, so it cannot hit the crash.
+ * Do not "extend" sanitization there.
+ */
+
+/** One dropped regex constraint, for the caller's log line. */
+export interface DroppedPattern {
+  /** JSON-pointer-style path of the dropped constraint within the schema. */
+  location: string;
+  /** The pattern source that failed to compile under the unicode flag. */
+  pattern: string;
+  /**
+   * True when the pattern compiles WITHOUT the /u flag — vendor sloppiness
+   * (Annex B legacy syntax), the oss#420 class. False means the regex is
+   * broken outright; either way validation could only crash, so both drop.
+   */
+  compilesWithoutUnicodeFlag: boolean;
+}
+
+/** Keywords whose value is a single subschema. */
+const SINGLE_SCHEMA_KEYWORDS = [
+  "additionalProperties",
+  "unevaluatedProperties",
+  "propertyNames",
+  "items",
+  "additionalItems",
+  "unevaluatedItems",
+  "contains",
+  "not",
+  "if",
+  "then",
+  "else",
+] as const;
+
+/** Keywords whose value is an array of subschemas. */
+const SCHEMA_ARRAY_KEYWORDS = ["anyOf", "allOf", "oneOf", "prefixItems"] as const;
+
+/** Keywords whose value is an object mapping names to subschemas. */
+const SCHEMA_MAP_KEYWORDS = [
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions",
+] as const;
+
+function compilesUnderUnicodeFlag(pattern: string): boolean {
+  try {
+    new RegExp(pattern, "u");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function compilesWithoutUnicodeFlag(pattern: string): boolean {
+  try {
+    new RegExp(pattern);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** JSON-pointer token escaping (RFC 6901): `~` → `~0`, `/` → `~1`. */
+function pointerToken(token: string): string {
+  return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/**
+ * Drop unicode-invalid regex patterns from a JSON schema, in place.
+ *
+ * Walks only schema positions (the recursion set is @cfworker's own
+ * validated-keyword list), so a property literally NAMED "pattern" under
+ * `properties` is never touched. The walker handles composition keywords
+ * (anyOf/allOf/oneOf/not/if-then-else) even though the adapter's
+ * simplifyJsonSchemaForLLM currently strips them, and carries a visited-set
+ * cycle guard even though the adapter's $ref inlining currently guarantees
+ * an acyclic result — correctness here must not depend on another
+ * package's internals holding across dependency bumps.
+ *
+ * Returns the dropped constraints (empty for clean schemas — the common
+ * case, which this walk leaves byte-identical).
+ */
+export function sanitizeSchemaPatterns(schema: unknown): DroppedPattern[] {
+  const dropped: DroppedPattern[] = [];
+  if (!isPlainObject(schema)) return dropped;
+  walkSchema(schema, "", dropped, new Set());
+  return dropped;
+}
+
+function recordDrop(dropped: DroppedPattern[], location: string, pattern: string): void {
+  dropped.push({
+    location,
+    pattern,
+    compilesWithoutUnicodeFlag: compilesWithoutUnicodeFlag(pattern),
+  });
+}
+
+function walkSchema(
+  node: Record<string, unknown>,
+  path: string,
+  dropped: DroppedPattern[],
+  seen: Set<object>,
+): void {
+  if (seen.has(node)) return;
+  seen.add(node);
+
+  if (typeof node.pattern === "string" && !compilesUnderUnicodeFlag(node.pattern)) {
+    recordDrop(dropped, `${path}/pattern`, node.pattern);
+    delete node.pattern;
+  }
+
+  if (isPlainObject(node.patternProperties)) {
+    const patternProperties = node.patternProperties;
+    let droppedEntry = false;
+    for (const key of Object.keys(patternProperties)) {
+      if (compilesUnderUnicodeFlag(key)) continue;
+      recordDrop(dropped, `${path}/patternProperties/${pointerToken(key)}`, key);
+      delete patternProperties[key];
+      droppedEntry = true;
+    }
+    if (droppedEntry) {
+      // Never-tighten: keys the dropped pattern used to match would now
+      // fall through to these checks and could be falsely rejected.
+      if (node.additionalProperties !== undefined && node.additionalProperties !== true) {
+        delete node.additionalProperties;
+      }
+      if (node.unevaluatedProperties !== undefined && node.unevaluatedProperties !== true) {
+        delete node.unevaluatedProperties;
+      }
+      if (Object.keys(patternProperties).length === 0) {
+        delete node.patternProperties;
+      }
+    }
+  }
+
+  for (const keyword of SINGLE_SCHEMA_KEYWORDS) {
+    const value = node[keyword];
+    if (isPlainObject(value)) {
+      walkSchema(value, `${path}/${keyword}`, dropped, seen);
+    }
+  }
+
+  for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+    const value = node[keyword];
+    if (!Array.isArray(value)) continue;
+    value.forEach((entry, index) => {
+      if (isPlainObject(entry)) {
+        walkSchema(entry, `${path}/${keyword}/${index}`, dropped, seen);
+      }
+    });
+  }
+
+  for (const keyword of SCHEMA_MAP_KEYWORDS) {
+    const value = node[keyword];
+    if (!isPlainObject(value)) continue;
+    for (const [name, entry] of Object.entries(value)) {
+      if (isPlainObject(entry)) {
+        walkSchema(entry, `${path}/${keyword}/${pointerToken(name)}`, dropped, seen);
+      }
+    }
+  }
+
+  // Draft-07 `items` tuple form and `dependencies` schema form — both
+  // keywords are dual-shaped, so the typed loops above miss these arms.
+  if (Array.isArray(node.items)) {
+    node.items.forEach((entry, index) => {
+      if (isPlainObject(entry)) {
+        walkSchema(entry, `${path}/items/${index}`, dropped, seen);
+      }
+    });
+  }
+  if (isPlainObject(node.dependencies)) {
+    for (const [name, entry] of Object.entries(node.dependencies)) {
+      // Array-valued entries are dependentRequired (property names, not
+      // schemas) — only schema-valued entries are walked.
+      if (isPlainObject(entry)) {
+        walkSchema(entry, `${path}/dependencies/${pointerToken(name)}`, dropped, seen);
+      }
+    }
+  }
+}

package/src/shared/model-client.ts

@@ -55,10 +55,27 @@ export interface BuildChatModelOptions {
    * stays the caller's decision to avoid silently changing behavior.
    */
   readonly maxTokens?: number;
+  /**
+   * Per-request bound. When omitted, defaults to the operator's
+   * STIGMER_LLM_REQUEST_TIMEOUT_MS — resolved HERE, not per caller, so no
+   * call site can drop the bound by forgetting to plumb it (the sub-agent
+   * factory did exactly that; stigmer/stigmer#468). An explicit value wins.
+   */
   readonly timeoutMs?: number;
   readonly maxRetries?: number;
 }
 
+/**
+ * The operator's request-timeout bound. Only a positive integer means
+ * "bound the request" — unset, non-numeric, zero, and negative all
+ * normalize to no bound. Deployment-static env, read here the same way
+ * provider API keys are.
+ */
+function resolveDefaultTimeoutMs(): number | undefined {
+  const parsed = Number.parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "", 10);
+  return parsed > 0 ? parsed : undefined;
+}
+
 export interface BuiltChatModel {
   readonly model: BaseChatModel;
   readonly provider: LlmProvider;
@@ -82,6 +99,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   const resolved = await resolveToApiModelId(opts.modelName);
   const provider = inferProvider(resolved);
   const apiModelId = stripProviderPrefix(resolved);
+  const timeoutMs = opts.timeoutMs ?? resolveDefaultTimeoutMs();
 
   // Backend precedence by construction: a proxied call never consults the
   // backend var — the proxy owns provider routing (the factories' preflight
@@ -201,7 +219,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     temperature: opts.temperature ?? 0,
     apiKey,
     ...(maxTokens ? { maxTokens } : {}),
-    ...(opts.timeoutMs ? { maxRetries: opts.maxRetries ?? 0 } : {}),
+    ...(timeoutMs ? { maxRetries: opts.maxRetries ?? 0 } : {}),
   };
 
   // The request timeout lives in a different slot per wrapper: ChatOpenAI
@@ -215,7 +233,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   // that is LangChain's own retry knob, distinct from the SDK-level
   // maxRetries the factories receive.
   const anthropicClientOptions = {
-    ...(opts.timeoutMs ? { timeout: opts.timeoutMs } : {}),
+    ...(timeoutMs ? { timeout: timeoutMs } : {}),
     ...(baseUrl ? { baseURL: baseUrl } : {}),
     ...(headers ? { defaultHeaders: headers } : {}),
   };
@@ -231,7 +249,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     ? new ChatOpenAI({
         model: apiModelId,
         ...common,
-        ...(opts.timeoutMs ? { timeout: opts.timeoutMs } : {}),
+        ...(timeoutMs ? { timeout: timeoutMs } : {}),
         ...(baseUrl || headers
           ? {
               configuration: {

package/src/shared/model-pricing-data.ts

@@ -30,9 +30,18 @@ interface RegistryEntry {
   };
 }
 
-import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
+import {
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+  REGISTRY_RETRY_POLICY,
+} from "./registry-endpoint.js";
+import { fetchWithRetry } from "./http-retry.js";
 
 const CACHE_TTL_MS = 3_600_000;
+// Failed fetches are cached much shorter than successes (the model-registry.ts
+// policy): a transient failure must not pin DEFAULT_PRICING — wrong rates for
+// cost tracking — for a full hour.
+const FAILURE_CACHE_TTL_MS = 60_000;
 
 export const DEFAULT_PRICING: ModelPricing = {
   model: "unknown",
@@ -66,7 +75,11 @@ function parsePricingTable(json: unknown): ModelPricing[] {
 }
 
 async function fetchFromApi(): Promise<readonly ModelPricing[]> {
-  const res = await fetch(resolveModelRegistryUrl(), { headers: buildRegistryHeaders() });
+  const res = await fetchWithRetry(
+    resolveModelRegistryUrl(),
+    { headers: buildRegistryHeaders() },
+    REGISTRY_RETRY_POLICY,
+  );
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   const table = parsePricingTable(data);
@@ -93,7 +106,7 @@ export async function getPricingTable(): Promise<readonly ModelPricing[]> {
         `Failed to fetch model registry, using default pricing: ${err}`,
       );
       const fallback = [DEFAULT_PRICING];
-      cache = { data: fallback, expiresAt: Date.now() + CACHE_TTL_MS };
+      cache = { data: fallback, expiresAt: Date.now() + FAILURE_CACHE_TTL_MS };
       return fallback;
     })
     .finally(() => {
@@ -102,3 +115,9 @@ export async function getPricingTable(): Promise<readonly ModelPricing[]> {
 
   return inflightFetch;
 }
+
+/** Exposed for testing — resets the in-memory cache. */
+export function _resetPricingCache(): void {
+  cache = null;
+  inflightFetch = null;
+}

package/src/shared/model-registry.ts

@@ -10,7 +10,12 @@
  * (getModelVisionCapability).
  */
 
-import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
+import {
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+  REGISTRY_RETRY_POLICY,
+} from "./registry-endpoint.js";
+import { fetchWithRetry } from "./http-retry.js";
 
 const CACHE_TTL_MS = 3_600_000;
 // Failed fetches are cached much shorter than successes: a transient failure
@@ -68,7 +73,7 @@ function parseVisionCapability(capabilities: unknown): boolean | undefined {
 
 async function fetchRegistry(): Promise<readonly RegistryModel[]> {
   const url = resolveModelRegistryUrl();
-  const res = await fetch(url, { headers: buildRegistryHeaders() });
+  const res = await fetchWithRetry(url, { headers: buildRegistryHeaders() }, REGISTRY_RETRY_POLICY);
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   return parseRegistry(data);

package/src/shared/plan-mode-permissions.ts

@@ -16,6 +16,13 @@
  * (issue #255). Kept as its own side-effect-free module so tests can pin the
  * production rules without dragging in setup.ts's import graph.
  *
+ * Rules travel with a companion: every graph that carries them also installs
+ * the path-normalization middleware (middleware/path-normalization.ts,
+ * issue #429), because deepagents' rule validation refuses workspace-relative
+ * paths outright — without the shim, prompt-compliant relative READS die in
+ * validation instead of just working. Both are derived from the same
+ * expression at each composition site so they cannot drift apart.
+ *
  * Invariant: never combine these rules with a shell-capable (sandbox)
  * backend — deepagents rejects that pairing at graph construction (see the
  * cas-capture-backend.ts header). Plan mode guarantees it by construction:

package/src/shared/registry-endpoint.ts

@@ -20,10 +20,37 @@
  */
 
 import { normalizeEndpoint } from "../config.js";
+import type { FetchRetryPolicy } from "./http-retry.js";
 
 /** Default local stigmer-server origin — mirrors config.ts's local-mode default. */
 const DEFAULT_LOCAL_BACKEND = "http://localhost:7234";
 
+/**
+ * Shared retry policy for the three registry fetch clients (model-registry.ts
+ * and both model-pricing-data.ts modules) — stigmer/stigmer#468.
+ *
+ * The timeout is the load-bearing half: each consumer deduplicates callers
+ * through a single in-flight promise, so one hung fetch strands every
+ * concurrent caller behind it — model-registry.ts's sits in front of every
+ * LLM client build. 10 s (not the checkpointer's 30 s) because the response
+ * is a small JSON document and the callers degrade gracefully; what they must
+ * never do is wait forever.
+ *
+ * The retry half matters because the degrade is not free: a failed registry
+ * fetch is cached (60 s empty registry → unresolved model ids that 404 at the
+ * provider; pricing falls back to defaults), so a budget spanning a
+ * pod-restart reroute converts that poisoned window into ~1.75 s of backoff.
+ * Worst case fully bounded: ~31 s of cold-cache stall when the control plane
+ * is genuinely down, versus an infinite hang before #468.
+ */
+export const REGISTRY_RETRY_POLICY: FetchRetryPolicy = {
+  label: "registry-endpoint",
+  baseDelayMs: 250,
+  backoffFactor: 2,
+  maxRetries: 3,
+  requestTimeoutMs: 10_000,
+};
+
 /**
  * Resolve the base URL (origin, no path) for model-registry and pricing
  * fetches. See module doc for the tier order.

package/src/shared/runner-credential-keys.ts

@@ -0,0 +1,46 @@
+/**
+ * Env var names of the runner's own credentials — the single source of truth
+ * for every surface that isolates agent-spawned processes from the runner's
+ * process env (issue #385).
+ *
+ * Inclusion rule: a name belongs here iff the runner reads it from its own
+ * `process.env` to authenticate the runner's own outbound calls. User-supplied
+ * credentials resolved from ExecutionContext (e.g. GITHUB_TOKEN, read only
+ * from mergedEnvVars) must NEVER be listed — the ExecutionContext overlay is
+ * their sanctioned delivery channel, and denying them here would break it.
+ *
+ * Consumers:
+ * - shell-env.ts: SHELL_ENV_DENYLIST for the native harness `execute` tool.
+ * - mcp-manager.test.ts: leak-tripwire canaries for MCP stdio subprocesses
+ *   (that path passes NO runner env by construction; the test plants these
+ *   names to prove none leak through).
+ *
+ * Ambient cloud-SDK chain vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
+ * GOOGLE_APPLICATION_CREDENTIALS, ...) are deliberately absent: they are
+ * dual-use on local runners (operators expect agent shells to keep their
+ * ambient aws/gcloud auth), and on a local backend the shell can read the
+ * credential files off disk regardless (owner ruling on #385).
+ */
+export const RUNNER_CREDENTIAL_ENV_KEYS: readonly string[] = [
+  // Derives HITL approval fingerprints (fingerprint-secret.ts) — an agent
+  // that reads this could forge approval receipts.
+  "STIGMER_RUNNER_HITL_SECRET",
+  // Stigmer control-plane auth (config.ts; rotated at runtime by
+  // runner-manager.ts). Executions receive theirs via ExecutionContext.
+  "STIGMER_TOKEN",
+  // Fallback bearer token for model-registry/pricing fetches when
+  // STIGMER_TOKEN is unset (registry-endpoint.ts).
+  "STIGMER_AUTH_TOKEN",
+  // Cursor harness credential (config.ts) — agent-spawned processes never
+  // need direct Cursor API access.
+  "CURSOR_API_KEY",
+  // Direct-mode Anthropic key for the native harness (model-client.ts).
+  "ANTHROPIC_API_KEY",
+  // Direct-mode OpenAI key for the native harness (model-client.ts).
+  "OPENAI_API_KEY",
+  // Azure AI Foundry backend key (model-client.ts).
+  "ANTHROPIC_FOUNDRY_API_KEY",
+  // Bedrock backend bearer credential, read by the AWS SDK's chain
+  // (llm-backend.ts documents it as a supported auth path).
+  "AWS_BEARER_TOKEN_BEDROCK",
+];