@stigmer/runner 3.40.1 → 3.41.0

package/src/shared/__tests__/tool-rounds.test.ts

@@ -1,35 +1,52 @@
+/**
+ * max_tool_rounds resolution and the budget's stop signal.
+ *
+ * Pins the proto contract's arithmetic (0/unset = unlimited, the 10–1000
+ * clamp and its warnings), the backstop that must never bind before the
+ * round count, and the classifier the native turn uses to read a thrown
+ * error as the `tool_call_limit` outcome. The classifier cases use
+ * LangChain's and LangGraph's own error classes, so an engine upgrade that
+ * changes how a middleware's throw reaches the turn fails here, not in a
+ * production run that would otherwise read the stop as a failure.
+ */
+
 import { describe, expect, it, vi, afterEach } from "vitest";
+import { MiddlewareError } from "langchain";
+import { GraphRecursionError } from "@langchain/langgraph";
 import {
   MAX_TOOL_ROUNDS,
   MIN_TOOL_ROUNDS,
-  SUPER_STEPS_PER_ROUND,
-  resolveRecursionLimit,
+  SUPER_STEPS_BACKSTOP_PER_ROUND,
+  ToolRoundLimitError,
+  backstopRecursionLimit,
+  isToolCallBudgetStop,
+  resolveToolRoundLimit,
 } from "../tool-rounds.js";
 
-describe("resolveRecursionLimit", () => {
+describe("resolveToolRoundLimit", () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
   it("returns null for unset (proto contract: 0 = unlimited)", () => {
-    expect(resolveRecursionLimit(undefined)).toBeNull();
-    expect(resolveRecursionLimit(0)).toBeNull();
+    expect(resolveToolRoundLimit(undefined)).toBeNull();
+    expect(resolveToolRoundLimit(0)).toBeNull();
   });
 
   it("returns null for negative values (treated as unset, never a tiny limit)", () => {
-    expect(resolveRecursionLimit(-5)).toBeNull();
+    expect(resolveToolRoundLimit(-5)).toBeNull();
   });
 
-  it("converts rounds to super-steps at the contract's x6 factor", () => {
-    expect(resolveRecursionLimit(10)).toBe(60);
-    expect(resolveRecursionLimit(100)).toBe(600);
-    expect(resolveRecursionLimit(MAX_TOOL_ROUNDS)).toBe(MAX_TOOL_ROUNDS * SUPER_STEPS_PER_ROUND);
+  it("returns an in-range value as the round count itself", () => {
+    expect(resolveToolRoundLimit(10)).toBe(10);
+    expect(resolveToolRoundLimit(100)).toBe(100);
+    expect(resolveToolRoundLimit(MAX_TOOL_ROUNDS)).toBe(MAX_TOOL_ROUNDS);
   });
 
   it("clamps below-range values up to the minimum with a warning", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 
-    expect(resolveRecursionLimit(3)).toBe(MIN_TOOL_ROUNDS * SUPER_STEPS_PER_ROUND);
+    expect(resolveToolRoundLimit(3)).toBe(MIN_TOOL_ROUNDS);
 
     expect(warn).toHaveBeenCalledOnce();
     expect(warn.mock.calls[0][0]).toContain("max_tool_rounds=3");
@@ -39,7 +56,7 @@ describe("resolveRecursionLimit", () => {
   it("clamps above-range values down to the maximum with a warning", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 
-    expect(resolveRecursionLimit(5000)).toBe(MAX_TOOL_ROUNDS * SUPER_STEPS_PER_ROUND);
+    expect(resolveToolRoundLimit(5000)).toBe(MAX_TOOL_ROUNDS);
 
     expect(warn).toHaveBeenCalledOnce();
     expect(warn.mock.calls[0][0]).toContain("max_tool_rounds=5000");
@@ -49,9 +66,42 @@ describe("resolveRecursionLimit", () => {
   it("does not warn for in-range values", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 
-    resolveRecursionLimit(MIN_TOOL_ROUNDS);
-    resolveRecursionLimit(MAX_TOOL_ROUNDS);
+    resolveToolRoundLimit(MIN_TOOL_ROUNDS);
+    resolveToolRoundLimit(MAX_TOOL_ROUNDS);
 
     expect(warn).not.toHaveBeenCalled();
   });
 });
+
+describe("backstopRecursionLimit", () => {
+  it("allows the backstop's super-steps per round, far above what one round costs", () => {
+    expect(backstopRecursionLimit(MIN_TOOL_ROUNDS)).toBe(MIN_TOOL_ROUNDS * SUPER_STEPS_BACKSTOP_PER_ROUND);
+    expect(backstopRecursionLimit(MAX_TOOL_ROUNDS)).toBe(MAX_TOOL_ROUNDS * SUPER_STEPS_BACKSTOP_PER_ROUND);
+  });
+});
+
+describe("isToolCallBudgetStop", () => {
+  it("reads the round count's own error as the budget's stop", () => {
+    expect(isToolCallBudgetStop(new ToolRoundLimitError(10))).toBe(true);
+  });
+
+  it("reads it through LangChain's MiddlewareError wrapping, once per wrapModelCall layer", () => {
+    let wrapped: unknown = new ToolRoundLimitError(10);
+    for (const layer of ["ExecutionBudgetMiddleware", "todoListMiddleware", "SummarizationMiddleware"]) {
+      wrapped = MiddlewareError.wrap(wrapped, layer);
+    }
+    expect(wrapped).toBeInstanceOf(MiddlewareError);
+    expect(isToolCallBudgetStop(wrapped)).toBe(true);
+  });
+
+  it("reads the backstop's recursion error as the same stop", () => {
+    expect(isToolCallBudgetStop(new GraphRecursionError("Recursion limit of 200 reached without hitting a stop condition."))).toBe(true);
+  });
+
+  it("does not read any other failure as the budget's stop, wrapped or not", () => {
+    expect(isToolCallBudgetStop(new Error("upstream 529"))).toBe(false);
+    expect(isToolCallBudgetStop(MiddlewareError.wrap(new Error("upstream 529"), "ExecutionBudgetMiddleware"))).toBe(false);
+    expect(isToolCallBudgetStop("Recursion limit")).toBe(false);
+    expect(isToolCallBudgetStop(undefined)).toBe(false);
+  });
+});

package/src/shared/approval-policy.ts

@@ -20,6 +20,7 @@ import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexe
 import { ApprovalAction, ApprovalMode, ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { SENSITIVE_ARG_KEYS } from "./args-preview.js";
 import { toolApprovalCategory, type ToolApprovalCategory } from "./tool-kind.js";
+import { extractFilePath } from "./file-tools.js";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 
 /**
@@ -480,18 +481,15 @@ export function resolveApprovalMessage(
  * THE approval-message template per mutating built-in category — the one
  * table both harnesses word their approval cards from (since #1097).
  * Keyed by category (not raw tool name) so every alias of a mutation renders
- * one message; placeholders resolve against the stream arg shape
- * (`path`/`command`; `resolveApprovalMessage`). The native gate decides with
- * it (`resolveToolApproval`), the Cursor translator words its `gate` from it
- * (`execute-cursor/approval-policy.ts` `getBuiltInApprovalMessage`), and the
- * Cursor boundary resolves a denied call's message through the same path.
+ * one message. It is read only through {@link resolveBuiltInApprovalMessage},
+ * which the native gate (`resolveToolApproval`), the Cursor translator's `gate`
+ * and the Cursor boundary's denied-call message all call, so the three can
+ * never word a card differently.
  *
  * Until then the Cursor harness carried a table of its own and the two differed
  * by a word — `shell` read "Run command" there and "Execute command" here.
  * Unified on the plainer word: a user reads "Run command" and knows
- * what is being asked. Known and deliberately left (#1112):
- * `write` resolves `{{args.path}}`, while deepagents' file tools send
- * `file_path`, so a gated native write reads "Write file: <unknown>".
+ * what is being asked.
  */
 export const CATEGORY_APPROVAL_MESSAGE: Record<ToolApprovalCategory, string> = {
   write: "Write file: {{args.path}}",
@@ -499,6 +497,50 @@ export const CATEGORY_APPROVAL_MESSAGE: Record<ToolApprovalCategory, string> = {
   shell: "Run command: {{args.command}}",
 };
 
+/**
+ * THE approval-card message for a built-in tool of either harness taxonomy, or
+ * `undefined` when the tool is not a gated built-in.
+ *
+ * The `{{args.path}}` a file card reads is filled from `extractFilePath`
+ * (`file-tools.ts`), the one home of "which argument names the file" across
+ * both taxonomies: deepagents' file tools and the Cursor hook send
+ * `file_path`, the Cursor stream sends `path`. Resolving the raw args instead
+ * rendered a gated native write as "Write file: <unknown>" (#1112). The
+ * template keeps its one placeholder, so the table stays harness-neutral.
+ */
+export function resolveBuiltInApprovalMessage(
+  toolName: string,
+  args: Record<string, unknown>,
+): string | undefined {
+  const category = toolApprovalCategory(toolName);
+  return category ? resolveCategoryApprovalMessage(category, toolName, args) : undefined;
+}
+
+function resolveCategoryApprovalMessage(
+  category: ToolApprovalCategory,
+  toolName: string,
+  args: Record<string, unknown>,
+): string {
+  return resolveApprovalMessage(CATEGORY_APPROVAL_MESSAGE[category], toolName, categoryTemplateArgs(category, args));
+}
+
+/** The args a category's template resolves against: a file card reads the file from wherever its taxonomy names it. */
+function categoryTemplateArgs(category: ToolApprovalCategory, args: Record<string, unknown>): Record<string, unknown> {
+  switch (category) {
+    case "write":
+    case "delete": {
+      const path = extractFilePath(args);
+      return path === null ? args : { ...args, path };
+    }
+    case "shell":
+      return args;
+    default: {
+      const exhaustive: never = category;
+      throw new Error(`categoryTemplateArgs: unknown approval category ${String(exhaustive)}`);
+    }
+  }
+}
+
 /** What the gate decides for one call: whether it waits, the message the card shows, and which layer said so. */
 export interface ApprovalRequirement {
   readonly requiresApproval: boolean;
@@ -508,11 +550,12 @@ export interface ApprovalRequirement {
 }
 
 /**
- * THE approval decision for one tool call — the same function the native gate
- * (`middleware/approval-gate.ts`) interrupts on and the native translator
- * reports as `tool_started.gate`, so the row can never disagree with the gate
- * about whether a call waits (since #1097; until then the transcript
- * builder carried its own weaker copy that gated MCP tools only). Its
+ * THE approval decision for one tool call — the function the native gate
+ * (`middleware/approval-gate.ts`) interrupts on. A held call reaches the
+ * transcript only through that interrupt (`approval_proposed`), so the row can
+ * never disagree with the gate about whether a call waits (since #1097; until
+ * then the transcript builder carried its own weaker copy that gated MCP tools
+ * only). Its
  * read-side twin is {@link resolveApprovalProvenance}, which answers "which
  * layer governs this call" for EVERY call, gated or not.
  *
@@ -561,7 +604,7 @@ export function resolveToolApproval(
     }
     return {
       requiresApproval: true,
-      message: resolveApprovalMessage(CATEGORY_APPROVAL_MESSAGE[category], toolName, args),
+      message: resolveCategoryApprovalMessage(category, toolName, args),
       source: "builtin_category",
     };
   }

package/src/shared/caller-identity.ts

@@ -139,9 +139,8 @@ export function resolveCallerIdentity(
 
 /**
  * Return a NEW env map with the reserved caller-identity keys set —
- * platform values are authoritative over same-named user entries (the
- * injectPlatformEnv precedent: a user env var must never be able to
- * impersonate a caller).
+ * platform values are authoritative over same-named user entries (a user
+ * env var must never be able to impersonate a caller).
  *
  * Call this on the env map handed to MCP resolution ONLY — never on the
  * map that reaches agent subprocess environments. Per-server opt-in is
@@ -174,8 +173,8 @@ export function injectCallerIdentityEnv(
  * Discovery-context injection: the connect workflow resolves the same
  * header templates with no session, so every declared reserved key gets
  * the anonymous sentinel — otherwise a caller-identity-templating server
- * can never be discovered. Gated on the server's declared keys, matching
- * injectPlatformEnv's contract in the discovery activity.
+ * can never be discovered. Gated on the server's declared keys, as every
+ * platform key is (platform-server-address.ts).
  */
 export function injectAnonymousCallerIdentityForDiscovery(
   declaredEnvKeys: ReadonlySet<string>,

package/src/shared/channel-attachment.ts

@@ -45,8 +45,8 @@ import type {
 } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { grpcTarget, SERVER_ADDRESS_ENV_KEY } from "./platform-server-address.js";
 import {
-  grpcTarget,
   stdioCredentialEnv,
   type SynthesizedAttachmentOptions,
 } from "./synthesized-attachment.js";
@@ -157,7 +157,7 @@ export function synthesizeChannelAttachment(
     args: ["mcp-server"],
     env: {
       STIGMER_MCP_ROSTER: "channels",
-      STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+      [SERVER_ADDRESS_ENV_KEY]: grpcTarget(options.backendEndpoint),
       ...stdioCredentialEnv(options.credential),
     },
   };

package/src/shared/connect-backfill.ts

@@ -21,6 +21,7 @@
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 import { resolveMcpServers } from "./mcp-resolver.js";
 import type { McpTransportPosture } from "./mcp-transport-guard.js";
+import type { PlatformEndpoints } from "./platform-server-address.js";
 import { withTimeout } from "./with-timeout.js";
 import type { StigmerClient } from "../client/stigmer-client.js";
 import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -67,6 +68,7 @@ export async function backfillMcpServersIfNeeded(
   envVars: Record<string, string>,
   org: string,
   transportPosture: McpTransportPosture,
+  platformEndpoints: PlatformEndpoints,
   onHeartbeat?: () => void,
   secretKeys?: ReadonlySet<string>,
 ): Promise<ResolvedMcpServer[]> {
@@ -131,7 +133,9 @@ export async function backfillMcpServersIfNeeded(
 
   // Same posture as the initial resolution: every server here already
   // passed the transport guard once, so re-resolving cannot newly reject.
-  const refreshed = await resolveMcpServers(client, usages, envVars, transportPosture);
+  const refreshed = await resolveMcpServers(
+    client, usages, envVars, transportPosture, platformEndpoints,
+  );
   return refreshed.resolvedServers;
 }
 

package/src/shared/mcp-resolver.ts

@@ -12,6 +12,11 @@
  * toCursorMcpConfig (execute-cursor/cursor-mcp-config.ts) for the Cursor
  * SDK — so a behavioral change here (like the transport guard) lands in
  * both execution paths by construction.
+ *
+ * The one platform key filled here is STIGMER_SERVER_ADDRESS
+ * (platform-server-address.ts), before the declared-key filter so the filter
+ * sees the key present; discovery applies the same fill itself because it
+ * resolves a single server without a usage.
  */
 
 import type { McpServerUsage, ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -30,6 +35,7 @@ import {
   PlaceholderResolutionError,
 } from "./placeholder-resolver.js";
 import { effectiveEnabledTools } from "./mcp-enabled-tools.js";
+import { fillPlatformServerAddress, type PlatformEndpoints } from "./platform-server-address.js";
 
 /**
  * Harness-agnostic intermediate representation of a resolved MCP server.
@@ -86,12 +92,16 @@ export interface McpResolutionResult {
  *        resolveMcpTransportPosture(config.mode)). A stdio server under a
  *        forbidding posture throws {@link McpTransportError} and fails the
  *        whole resolution — never degraded to a skipped server.
+ * @param platformEndpoints The runner's endpoints a missing
+ *        STIGMER_SERVER_ADDRESS is filled from (the runner Config satisfies
+ *        it). Required so no resolution path can forget the fill.
  */
 export async function resolveMcpServers(
   client: StigmerClient,
   usages: McpServerUsage[],
   envVars: Record<string, string>,
   transportPosture: McpTransportPosture,
+  platformEndpoints: PlatformEndpoints,
 ): Promise<McpResolutionResult> {
   const resolved: ResolvedMcpServer[] = [];
 
@@ -103,7 +113,7 @@ export async function resolveMcpServers(
       const mcpServer = await client.getMcpServerByReference(ref);
       const serverEnv = filterEnvToDeclaredKeys(
         mcpServer.spec?.env,
-        envVars,
+        fillPlatformServerAddress(mcpServer, envVars, platformEndpoints),
         ref.slug,
       );
       const server = mcpServerToResolved(

package/src/shared/memory-attachment.ts

@@ -51,8 +51,8 @@
 
 import type { RecalledMemories } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { grpcTarget, SERVER_ADDRESS_ENV_KEY } from "./platform-server-address.js";
 import {
-  grpcTarget,
   stdioCredentialEnv,
   type SynthesizedAttachmentOptions,
 } from "./synthesized-attachment.js";
@@ -159,7 +159,7 @@ export function synthesizeMemoryAttachment(
     args: ["mcp-server"],
     env: {
       STIGMER_MCP_ROSTER: "memory",
-      STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+      [SERVER_ADDRESS_ENV_KEY]: grpcTarget(options.backendEndpoint),
       ...stdioCredentialEnv(options.credential),
       ...nonEmptyEntries([
         [MEMORY_ORG_ENV, context.org],

package/src/shared/model-error.ts

@@ -19,6 +19,14 @@
  *    (BYO-key) mode, attributes billing errors to the user's own account
  *    with actionable wording.
  *
+ * 3. On Stigmer Cloud an organization may bring its own provider key, which
+ *    the proxy injects upstream in place of the platform's. A failure on
+ *    that key is the organization's, not the platform's, yet it reaches the
+ *    runner in proxy mode. The proxy keeps the provider's status and message
+ *    and marks the message with ORGANIZATION_PROVIDER_KEY_SENTINEL; this
+ *    module words a marked failure as the organization's key, never as a
+ *    platform fault.
+ *
  * Classification order is load-bearing: the sentinel check must precede
  * status mapping, otherwise the proxy's 503 would classify as a retryable
  * 5xx and waste Temporal retries against a dead platform account.
@@ -43,6 +51,14 @@ import {
  */
 export const PLATFORM_CAPACITY_SENTINEL = "STIGMER_PLATFORM_MODEL_CAPACITY";
 
+/**
+ * Machine-readable code the cloud proxy embeds in a provider failure it
+ * relays from a call served on the organization's own provider key. The
+ * message text carries it, as it carries PLATFORM_CAPACITY_SENTINEL.
+ * Duplicated in stigmer-cloud's LLM proxy lane; change both or neither.
+ */
+export const ORGANIZATION_PROVIDER_KEY_SENTINEL = "STIGMER_ORGANIZATION_PROVIDER_KEY";
+
 export interface ClassifiedModelError {
   /** Stable machine-readable code (doubles as the Temporal failure type). */
   readonly code: string;
@@ -72,17 +88,22 @@ export interface ModelErrorContext {
 
 /**
  * Walk the `cause` chain to the root error. LangChain's MiddlewareError (and
- * anything else that chains causes) preserves the original SDK error there.
- * Depth-capped so a pathological cause cycle cannot spin forever.
+ * anything else that chains causes) preserves the original SDK error there,
+ * and the root is the one link carrying the provider's `.status`.
+ *
+ * The chain is as long as the agent's middleware stack: LangChain wraps a
+ * model call's failure once per middleware that implements `wrapModelCall`
+ * (`MiddlewareError.wrap` in its AgentNode), and a native turn stacks
+ * deepagents' own middleware, the to-do list and Stigmer's, well past ten
+ * layers. So the walk has no depth bound; a cause cycle ends it instead, at
+ * the first error seen twice.
  */
 export function unwrapModelError(err: unknown): unknown {
+  const seen = new Set<unknown>([err]);
   let current = err;
-  for (let depth = 0; depth < 10; depth++) {
-    if (current instanceof Error && current.cause instanceof Error) {
-      current = current.cause;
-    } else {
-      return current;
-    }
+  while (current instanceof Error && current.cause instanceof Error && !seen.has(current.cause)) {
+    current = current.cause;
+    seen.add(current);
   }
   return current;
 }
@@ -99,10 +120,21 @@ export function unwrapModelError(err: unknown): unknown {
  */
 export function classifyModelCallError(
   err: unknown,
-  ctx: ModelErrorContext,
+  callerCtx: ModelErrorContext,
 ): ClassifiedModelError | undefined {
   const root = unwrapModelError(err);
   const message = root instanceof Error ? root.message : String(root);
+
+  // 0. Organization-key sentinel — before everything that reads proxyMode:
+  //    the call went through the proxy but on the organization's own key,
+  //    so its failures are the organization's. The key-specific failures
+  //    get key-specific wording; the rest classify as direct mode would.
+  const organizationKey = message.includes(ORGANIZATION_PROVIDER_KEY_SENTINEL);
+  if (organizationKey) {
+    const classified = classifyOrganizationKeyError(root, message, callerCtx);
+    if (classified !== undefined) return classified;
+  }
+  const ctx = organizationKey ? { ...callerCtx, proxyMode: false } : callerCtx;
   const backend = resolveDirectBackend(ctx);
 
   // 1. Platform sentinel — before status mapping (see module doc).
@@ -235,6 +267,52 @@ export function classifyModelCallError(
   return undefined;
 }
 
+/**
+ * The failures an organization's own provider key causes, worded for the
+ * organization's admin: out of credit or quota at the provider, the key
+ * rejected, or the key's account not permitted the model. Undefined for
+ * every other failure, which classifies as direct mode would.
+ */
+function classifyOrganizationKeyError(
+  root: unknown,
+  message: string,
+  ctx: ModelErrorContext,
+): ClassifiedModelError | undefined {
+  const provider = providerSubject(ctx);
+  if (isProviderBillingMessage(message)) {
+    return {
+      code: "LLM_PROVIDER_BILLING",
+      retryable: false,
+      message:
+        `Your organization's own ${providerLabel(ctx)} key is out of credits or over quota. ` +
+        `Add credits to that provider account, or update the key in Settings → Provider keys. ` +
+        `Provider message: ${message}`,
+    };
+  }
+  const status = typeof (root as { status?: unknown }).status === "number"
+    ? (root as { status: number }).status
+    : undefined;
+  if (status === 401) {
+    return {
+      code: "LLM_AUTHENTICATION_ERROR",
+      retryable: false,
+      message:
+        `${provider} rejected your organization's own key (authentication, HTTP 401) for ${modelLabel(ctx)}. ` +
+        `Update the key in Settings → Provider keys.`,
+    };
+  }
+  if (status === 403) {
+    return {
+      code: "LLM_PERMISSION_DENIED",
+      retryable: false,
+      message:
+        `${provider} denied your organization's own key (authorization, HTTP 403) for ${modelLabel(ctx)}. ` +
+        `Check that the key's account may use this model, or update the key in Settings → Provider keys.`,
+    };
+  }
+  return undefined;
+}
+
 /**
  * Retryability policy (unchanged from the original call-llm classifier):
  *   - 4xx (except 429): nonRetryable — client/config errors won't self-heal

package/src/shared/platform-server-address.ts

@@ -0,0 +1,123 @@
+/**
+ * The Stigmer server's address for user-defined MCP servers — the reserved
+ * STIGMER_SERVER_ADDRESS key, and the one dial-target rule every writer of
+ * that key shares (stigmer/stigmer#1433, #1446).
+ *
+ * The runner is the one component that supplies it, because the runner is
+ * the one that knows where the consumer runs:
+ *
+ *   - A remote HTTP server receives the key only through a templated header,
+ *     so it needs the server's PUBLIC address: STIGMER_MCP_PUBLIC_ENDPOINT,
+ *     which the server hands every sandbox it provisions from its own
+ *     configuration (stigmer/stigmer#1447), or an operator names to a
+ *     runner it starts by hand.
+ *   - A stdio server is a child of this runner (only a local runner spawns
+ *     one; mcp-transport-guard.ts), so the address the runner itself dials,
+ *     STIGMER_BACKEND_ENDPOINT, is right for it by construction.
+ *
+ * No page supplies it: a value written into a run's runtime_env sits in the
+ * top merge layer, above every value the user saved (stigmer/stigmer#1446).
+ *
+ * The runner FILLS, it never overrides: a non-empty value already in the
+ * environment (one the user saved or typed to aim a server elsewhere)
+ * stands. A key nobody can supply stays missing, and a
+ * header that templates it fails with the resolver's named
+ * PlaceholderResolutionError instead of dialing a guess.
+ *
+ * Injection is opt-in exactly as for the caller-identity keys
+ * (caller-identity.ts): only a server whose spec.env declares the key
+ * receives it. Applied before filterEnvToDeclaredKeys at execution
+ * (mcp-resolver.ts) and before placeholder resolution at discovery
+ * (activities/discover-mcp-server.ts), so both phases share one rule.
+ */
+
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { Config } from "../config.js";
+
+/**
+ * Reserved env key: the Stigmer server's gRPC dial target, host:port. The
+ * name the mcp-server reads its target from (mcp-server/src/config.ts) and
+ * `@stigmer/react` keeps out of its setup prompts
+ * (sdk/react/src/environment/systemEnvVars.ts); a cross-package string,
+ * pinned on every side.
+ */
+export const SERVER_ADDRESS_ENV_KEY = "STIGMER_SERVER_ADDRESS";
+
+/** The two runner-known endpoints an address can be filled from. */
+export type PlatformEndpoints = Pick<Config, "mcpPublicEndpoint" | "stigmerBackendEndpoint">;
+
+/**
+ * The gRPC dial target (host:port) for an endpoint, the shape
+ * STIGMER_SERVER_ADDRESS wants.
+ *
+ * An http(s) URL becomes its host with an explicit port: the URL's own, else
+ * 80 for http and 443 for https. The port is never left implicit, because
+ * the mcp-server derives TLS from it and assumes :443 with TLS for a
+ * non-loopback host that has none (mcp-server/src/config.ts). Any other
+ * input (a scheme-less host:port, a bare host) is already a dial target and
+ * passes through unchanged.
+ */
+export function grpcTarget(endpoint: string): string {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return endpoint;
+  }
+  // `new URL("host:7234")` parses with `host:` as its scheme, so only a
+  // real http(s) URL is taken apart.
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return endpoint;
+  }
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  return `${url.hostname}:${port}`;
+}
+
+/**
+ * The address the platform supplies for a server of this transport, or
+ * `null` when the runner knows none: the operator's public endpoint for any
+ * transport, else the runner's own backend endpoint for a stdio child.
+ */
+export function platformServerAddress(
+  transport: McpServerTransport | undefined,
+  endpoints: PlatformEndpoints,
+): string | null {
+  if (endpoints.mcpPublicEndpoint) {
+    return grpcTarget(endpoints.mcpPublicEndpoint);
+  }
+  if (transport === "stdio") {
+    return grpcTarget(endpoints.stigmerBackendEndpoint);
+  }
+  return null;
+}
+
+/**
+ * Return the env map with STIGMER_SERVER_ADDRESS filled for `server` when it
+ * declares the key and the map holds no non-empty value for it; otherwise the
+ * map itself, unchanged. Never mutates its input.
+ */
+export function fillPlatformServerAddress(
+  server: McpServer,
+  envVars: Record<string, string>,
+  endpoints: PlatformEndpoints,
+): Record<string, string> {
+  const declared = server.spec?.env ?? {};
+  if (!(SERVER_ADDRESS_ENV_KEY in declared) || envVars[SERVER_ADDRESS_ENV_KEY]) {
+    return envVars;
+  }
+  const value = platformServerAddress(server.spec?.serverType.case, endpoints);
+  if (value === null) {
+    return envVars;
+  }
+  const source = endpoints.mcpPublicEndpoint
+    ? "STIGMER_MCP_PUBLIC_ENDPOINT"
+    : "STIGMER_BACKEND_ENDPOINT";
+  console.info(
+    `MCP server '${server.metadata?.slug ?? ""}': ${SERVER_ADDRESS_ENV_KEY} ` +
+    `filled from ${source} (no value in the execution environment)`,
+  );
+  return { ...envVars, [SERVER_ADDRESS_ENV_KEY]: value };
+}
+
+/** The transports a McpServer spec declares (its `serverType` oneof). */
+type McpServerTransport = NonNullable<NonNullable<McpServer["spec"]>["serverType"]["case"]>;

package/src/shared/synthesized-attachment.ts

@@ -98,15 +98,3 @@ export function injectSynthesizedAttachment(
     attachment,
   ];
 }
-
-/**
- * The gRPC dial target (host:port) for a backend endpoint URL — the
- * shape STIGMER_SERVER_ADDRESS wants (the bridge warns on schemes).
- */
-export function grpcTarget(endpoint: string): string {
-  try {
-    return new URL(endpoint).host;
-  } catch {
-    return endpoint;
-  }
-}