@stigmer/runner 3.40.0 → 3.41.0

package/src/runner.ts

@@ -18,6 +18,7 @@ import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import type { Config, TokenRef } from "./config.js";
 import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS, DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./config.js";
+import type { NativeConnection } from "@temporalio/worker";
 import type { WorkerActivities } from "./worker.js";
 import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "./bootstrap.js";
 import { createRunnerTokenCoordinator } from "./runner-token-coordinator.js";
@@ -348,7 +349,7 @@ export async function createStigmerRunner(
   const shutdownController = registerWorkerShutdownSignal(config.taskQueue);
 
   const { startWorker } = await import("./worker.js");
-  const worker = await startWorker({ config, activities, payloadCodecs });
+  const { worker, connection } = await startWorker({ config, activities, payloadCodecs });
   markBoot("worker_created");
 
   return {
@@ -363,18 +364,10 @@ export async function createStigmerRunner(
       emitRunnerBootTiming({ task_queue: config.taskQueue, mode: config.mode });
       await worker.run();
       console.log("Worker stopped");
-      // The worker has drained — every harness releases what it still holds
-      // (the Cursor harness: its parked session agents, whose executor leases
-      // dispose with the process, #215). Logged, never thrown: the drain has
-      // already happened and the process is exiting, so a teardown failure
-      // must not mask a clean stop.
-      try {
-        await shutdownHarnesses(adaptersOf(HARNESS_ADAPTERS));
-      } catch (err) {
-        console.error(
-          `[runner] Harness shutdown failed after the worker drained (continuing): ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }
+      await releaseAfterDrain({
+        shutdownHarnesses: () => shutdownHarnesses(adaptersOf(HARNESS_ADAPTERS)),
+        connection,
+      });
     },
     shutdown() {
       tokenRenewal?.stop();
@@ -404,6 +397,54 @@ function validateOptions(options: StigmerRunnerOptions): void {
   // localhost when no token is present.
 }
 
+/** What a drained static worker still holds, released by {@link releaseAfterDrain}. */
+export interface DrainedWorkerResources {
+  /** Releases what every harness still holds (the registry's `shutdownHarnesses` over the table). */
+  readonly shutdownHarnesses: () => Promise<void>;
+  /** The Temporal connection the drained worker polled on; this runner opened it, so it closes it. */
+  readonly connection: Pick<NativeConnection, "close">;
+}
+
+/**
+ * The static runner's teardown once `worker.run()` has resolved, in the
+ * manager's order (runner-manager.ts `shutdown`): harnesses, then the
+ * Temporal connection.
+ *
+ * - Harnesses first: they release what they still hold (the Cursor harness:
+ *   its parked session agents, whose executor leases dispose with the
+ *   process, #215) over their own channels, never the Temporal one.
+ * - The connection last, and only after the drain: the SDK refuses to close
+ *   a connection a worker still holds, and `run()` releases it on its way
+ *   out.
+ *
+ * Each step is logged, never thrown: the drain has already happened and the
+ * process is exiting, so a teardown failure must not mask a clean stop, and
+ * one step failing does not skip the next.
+ */
+export async function releaseAfterDrain(
+  resources: DrainedWorkerResources,
+  logError: (line: string) => void = (line) => console.error(line),
+): Promise<void> {
+  try {
+    await resources.shutdownHarnesses();
+  } catch (err) {
+    logError(
+      `[runner] Harness shutdown failed after the worker drained (continuing): ${errorText(err)}`,
+    );
+  }
+  try {
+    await resources.connection.close();
+  } catch (err) {
+    logError(
+      `[runner] Temporal connection close failed after the worker drained (continuing): ${errorText(err)}`,
+    );
+  }
+}
+
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * The runtime `Config` for the static root. The refs are the root's: it
  * creates them before mapping and writes them on every rotation (the
@@ -437,9 +478,10 @@ export function mapOptionsToConfig(
     stigmerTokenRef: tokenRef,
     stigmerRunnerTokenRef: runnerTokenRef,
     proxyTokenRef: tokenRef,
-    // Env-only like the env-loaded path (loadConfig): the bridge endpoint
-    // is deployment topology, not per-session state.
+    // Env-only like the env-loaded path (loadConfig): the bridge and public
+    // endpoints are deployment topology, not per-session state.
     mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
+    mcpPublicEndpoint: process.env.STIGMER_MCP_PUBLIC_ENDPOINT || null,
     cursorApiKey: proxyActive
       ? (options.cursorApiKey ?? "proxy-managed")
       : (options.cursorApiKey ?? ""),

package/src/shared/__tests__/approval-policy.test.ts

@@ -11,6 +11,7 @@ import {
   mergeApprovalPolicies,
   lookupMcpToolPolicy,
   resolveApprovalMessage,
+  resolveBuiltInApprovalMessage,
   deriveActiveLeases,
   resolveApprovalProvenance,
   resolveToolApproval,
@@ -551,6 +552,14 @@ describe("resolveToolApproval — THE gate decision, shared by the gate and the
     });
   });
 
+  it("a gated native file write waits with the file named on its card (#1112)", () => {
+    expect(resolveToolApproval("write_file", "", { file_path: "/workspace/src/app.ts", content: "x" }, new Map(), NO_CATEGORIES)).toEqual({
+      requiresApproval: true,
+      message: "Write file: /workspace/src/app.ts",
+      source: "builtin_category",
+    });
+  });
+
   it("a mutating built-in whose category is leased runs, source approval_lease", () => {
     expect(resolveToolApproval("execute", "", { command: "ls" }, new Map(), new Set<ToolApprovalCategory>(["shell"]))).toEqual({
       requiresApproval: false,
@@ -565,6 +574,38 @@ describe("resolveToolApproval — THE gate decision, shared by the gate and the
   });
 });
 
+describe("resolveBuiltInApprovalMessage — the one card wording for a gated built-in, either harness", () => {
+  it("names the file a native write or edit touches: deepagents' file tools send file_path (#1112)", () => {
+    expect(resolveBuiltInApprovalMessage("write_file", { file_path: "/workspace/src/app.ts", content: "x" })).toBe("Write file: /workspace/src/app.ts");
+    expect(resolveBuiltInApprovalMessage("edit_file", { file_path: "/workspace/README.md", old_string: "a", new_string: "b" })).toBe("Write file: /workspace/README.md");
+  });
+
+  it("names the file from path in the Cursor stream's taxonomy, and from file_path in its hook's", () => {
+    expect(resolveBuiltInApprovalMessage("edit", { path: "src/app.ts" })).toBe("Write file: src/app.ts");
+    expect(resolveBuiltInApprovalMessage("Write", { file_path: "src/app.ts" })).toBe("Write file: src/app.ts");
+    expect(resolveBuiltInApprovalMessage("Delete", { file_path: "old.txt" })).toBe("Delete: old.txt");
+    expect(resolveBuiltInApprovalMessage("delete", { path: "old.txt" })).toBe("Delete: old.txt");
+  });
+
+  it("prefers path when a call carries both names", () => {
+    expect(resolveBuiltInApprovalMessage("write_file", { path: "a.txt", file_path: "b.txt" })).toBe("Write file: a.txt");
+  });
+
+  it("still reads <unknown> when a file call names no file at all", () => {
+    expect(resolveBuiltInApprovalMessage("write_file", { content: "x" })).toBe("Write file: <unknown>");
+  });
+
+  it("words a shell card from the command, in either taxonomy", () => {
+    expect(resolveBuiltInApprovalMessage("execute", { command: "rm -rf build" })).toBe("Run command: rm -rf build");
+    expect(resolveBuiltInApprovalMessage("Shell", { command: "ls" })).toBe("Run command: ls");
+  });
+
+  it("answers undefined for a built-in that is not gated", () => {
+    expect(resolveBuiltInApprovalMessage("read_file", { file_path: "/x" })).toBeUndefined();
+    expect(resolveBuiltInApprovalMessage("Read", { file_path: "/x" })).toBeUndefined();
+  });
+});
+
 describe("toProtoPolicySource", () => {
   it("maps undefined (no governing layer) to UNSPECIFIED", () => {
     expect(toProtoPolicySource(undefined)).toBe(ApprovalPolicySource.UNSPECIFIED);

package/src/shared/__tests__/artifact-storage.test.ts

@@ -647,6 +647,7 @@ describe("loadArtifactStorageConfig", () => {
     temporalConnection: {},
     stigmerBackendEndpoint: "http://localhost:7234",
     mcpBridgeEndpoint: null,
+    mcpPublicEndpoint: null,
     cursorApiKey: "",
     workspaceRootDir: "/tmp",
     maxConcurrentActivities: 5,

package/src/shared/__tests__/connect-backfill.test.ts

@@ -5,6 +5,10 @@ import {
   extractRuntimeEnvForServer,
 } from "../connect-backfill.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+
+/** The runner endpoints resolution fills STIGMER_SERVER_ADDRESS from. */
+const PLATFORM_ENDPOINTS = testConfig();
 
 function makeServer(overrides: Partial<ResolvedMcpServer> = {}): ResolvedMcpServer {
   return {
@@ -125,7 +129,7 @@ describe("backfillMcpServersIfNeeded", () => {
     const client = makeMockClient();
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, [], {}, "org", "stdio-allowed",
+      client, servers, [], {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result).toBe(servers);
@@ -138,7 +142,7 @@ describe("backfillMcpServersIfNeeded", () => {
     const client = makeMockClient();
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, [], {}, "org", "stdio-allowed",
+      client, servers, [], {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result).toBe(servers);
@@ -156,7 +160,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed",
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(client.getMcpServerByReference).toHaveBeenCalledOnce();
@@ -182,7 +186,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed",
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(client.connectMcpServer).toHaveBeenCalledOnce();
@@ -207,7 +211,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     await backfillMcpServersIfNeeded(
-      client, servers, usages, mergedEnv, "org", "stdio-allowed",
+      client, servers, usages, mergedEnv, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(client.connectMcpServer).toHaveBeenCalledWith(
@@ -225,7 +229,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed",
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result).toBe(servers);
@@ -243,7 +247,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed",
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result).toBe(servers);
@@ -262,7 +266,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed", onHeartbeat,
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS, onHeartbeat,
     );
 
     expect(onHeartbeat).toHaveBeenCalledTimes(2);
@@ -275,7 +279,7 @@ describe("backfillMcpServersIfNeeded", () => {
     const client = makeMockClient();
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, [], {}, "org", "stdio-allowed",
+      client, servers, [], {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(client.getMcpServerByReference).not.toHaveBeenCalled();
@@ -295,7 +299,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed",
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(client.connectMcpServer).not.toHaveBeenCalled();
@@ -338,7 +342,7 @@ describe("backfillMcpServersIfNeeded", () => {
     });
 
     const result = await backfillMcpServersIfNeeded(
-      client, servers, usages, {}, "org", "stdio-allowed",
+      client, servers, usages, {}, "org", "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(callCount).toBe(2);

package/src/shared/__tests__/mcp-resolver.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { mcpServerToResolved, mergeMcpServerUsages, resolveMcpServers } from "../mcp-resolver.js";
 import { McpTransportError } from "../mcp-transport-guard.js";
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+
+/** The runner endpoints resolution fills STIGMER_SERVER_ADDRESS from. */
+const PLATFORM_ENDPOINTS = testConfig();
 
 function makeUsage(
   slug: string,
@@ -60,7 +64,7 @@ describe("resolveMcpServers — transport guard integration", () => {
     const client = clientReturning({ filesystem: stdioMcpServer("filesystem") });
 
     await expect(
-      resolveMcpServers(client, [makeUsage("filesystem")], {}, "stdio-forbidden"),
+      resolveMcpServers(client, [makeUsage("filesystem")], {}, "stdio-forbidden", PLATFORM_ENDPOINTS),
     ).rejects.toThrow(McpTransportError);
   });
 
@@ -75,7 +79,7 @@ describe("resolveMcpServers — transport guard integration", () => {
         client,
         [makeUsage("github"), makeUsage("filesystem")],
         {},
-        "stdio-forbidden",
+        "stdio-forbidden", PLATFORM_ENDPOINTS,
       ),
     ).rejects.toThrow(McpTransportError);
   });
@@ -84,7 +88,7 @@ describe("resolveMcpServers — transport guard integration", () => {
     const client = clientReturning({ github: httpMcpServer("github") });
 
     const result = await resolveMcpServers(
-      client, [makeUsage("github")], {}, "stdio-forbidden",
+      client, [makeUsage("github")], {}, "stdio-forbidden", PLATFORM_ENDPOINTS,
     );
 
     expect(result.resolvedServers).toHaveLength(1);
@@ -95,7 +99,7 @@ describe("resolveMcpServers — transport guard integration", () => {
     const client = clientReturning({ filesystem: stdioMcpServer("filesystem") });
 
     const result = await resolveMcpServers(
-      client, [makeUsage("filesystem")], {}, "stdio-allowed",
+      client, [makeUsage("filesystem")], {}, "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result.resolvedServers).toHaveLength(1);
@@ -106,7 +110,7 @@ describe("resolveMcpServers — transport guard integration", () => {
     const client = clientReturning({});
 
     const result = await resolveMcpServers(
-      client, [makeUsage("ghost")], {}, "stdio-forbidden",
+      client, [makeUsage("ghost")], {}, "stdio-forbidden", PLATFORM_ENDPOINTS,
     );
 
     expect(result.resolvedServers).toHaveLength(0);
@@ -123,7 +127,7 @@ describe("resolveMcpServers — enabled_tools threading (issue #350)", () => {
     const client = clientReturning({ github: httpMcpServer("github") });
 
     const result = await resolveMcpServers(
-      client, [makeUsage("github", "test-org", ["create_pr"])], {}, "stdio-allowed",
+      client, [makeUsage("github", "test-org", ["create_pr"])], {}, "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result.resolvedServers[0].enabledTools).toEqual(["create_pr"]);
@@ -135,7 +139,7 @@ describe("resolveMcpServers — enabled_tools threading (issue #350)", () => {
     });
 
     const result = await resolveMcpServers(
-      client, [makeUsage("github")], {}, "stdio-allowed",
+      client, [makeUsage("github")], {}, "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result.resolvedServers[0].enabledTools).toEqual(["search_code"]);
@@ -145,7 +149,7 @@ describe("resolveMcpServers — enabled_tools threading (issue #350)", () => {
     const client = clientReturning({ github: httpMcpServer("github") });
 
     const result = await resolveMcpServers(
-      client, [makeUsage("github")], {}, "stdio-allowed",
+      client, [makeUsage("github")], {}, "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     expect(result.resolvedServers[0].enabledTools).toBeUndefined();
@@ -179,7 +183,7 @@ describe("resolveMcpServers — tool_approval_overrides threading (issue #349)",
         makeUsage("slack"),
       ],
       {},
-      "stdio-allowed",
+      "stdio-allowed", PLATFORM_ENDPOINTS,
     );
 
     const bySlug = new Map(result.resolvedServers.map((s) => [s.slug, s]));
@@ -208,7 +212,7 @@ describe("resolveMcpServers — tool_approval_overrides threading (issue #349)",
       [makeUsage("github", "test-org", [], [{ toolName: "push", requiresApproval: false }])],
     );
 
-    const result = await resolveMcpServers(client, merged, {}, "stdio-allowed");
+    const result = await resolveMcpServers(client, merged, {}, "stdio-allowed", PLATFORM_ENDPOINTS);
 
     expect(result.resolvedServers[0].toolApprovalOverrides).toEqual([
       { toolName: "push", requiresApproval: false },
@@ -216,6 +220,64 @@ describe("resolveMcpServers — tool_approval_overrides threading (issue #349)",
   });
 });
 
+describe("resolveMcpServers — the platform STIGMER_SERVER_ADDRESS (stigmer/stigmer#1433)", () => {
+  function declaringAddress(server: any, headers: Record<string, string> = {}) {
+    server.spec.env = { STIGMER_SERVER_ADDRESS: {} };
+    if (server.spec.serverType.case === "http") server.spec.serverType.value.headers = headers;
+    return server;
+  }
+
+  it("fills a stdio server's missing address from the runner's backend endpoint", async () => {
+    const client = clientReturning({ stigmer: declaringAddress(stdioMcpServer("stigmer")) });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("stigmer")], {}, "stdio-allowed", PLATFORM_ENDPOINTS,
+    );
+
+    // testConfig's backend endpoint is http://127.0.0.1:1.
+    expect(result.resolvedServers[0].env).toEqual({ STIGMER_SERVER_ADDRESS: "127.0.0.1:1" });
+  });
+
+  it("keeps the address the execution environment carries", async () => {
+    const client = clientReturning({ stigmer: declaringAddress(stdioMcpServer("stigmer")) });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("stigmer")], { STIGMER_SERVER_ADDRESS: "api.example.com:443" },
+      "stdio-allowed", PLATFORM_ENDPOINTS,
+    );
+
+    expect(result.resolvedServers[0].env).toEqual({ STIGMER_SERVER_ADDRESS: "api.example.com:443" });
+  });
+
+  it("templates an http header from the operator's public endpoint", async () => {
+    const client = clientReturning({
+      remote: declaringAddress(httpMcpServer("remote"), { "X-Stigmer-Server": "${STIGMER_SERVER_ADDRESS}" }),
+    });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("remote")], {}, "stdio-forbidden",
+      testConfig({ mcpPublicEndpoint: "https://api.example.com" }),
+    );
+
+    expect(result.resolvedServers[0].headers).toEqual({ "X-Stigmer-Server": "api.example.com:443" });
+  });
+
+  it("never hands an http server the backend endpoint: an unknown address drops it with the named error", async () => {
+    const client = clientReturning({
+      remote: declaringAddress(httpMcpServer("remote"), { "X-Stigmer-Server": "${STIGMER_SERVER_ADDRESS}" }),
+    });
+    const errorLog = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("remote")], {}, "stdio-forbidden", PLATFORM_ENDPOINTS,
+    );
+
+    expect(result.resolvedServers).toEqual([]);
+    expect(errorLog).toHaveBeenCalledWith(expect.stringContaining("STIGMER_SERVER_ADDRESS"));
+    errorLog.mockRestore();
+  });
+});
+
 describe("mergeMcpServerUsages — session-wins-per-slug (shared by both harnesses)", () => {
   it("session usage replaces the agent's WHOLE usage for the same slug, including enabled_tools", () => {
     const merged = mergeMcpServerUsages(

package/src/shared/__tests__/model-error.test.ts

@@ -13,6 +13,7 @@
 
 import { describe, it, expect, vi, afterEach } from "vitest";
 import {
+  ORGANIZATION_PROVIDER_KEY_SENTINEL,
   PLATFORM_CAPACITY_SENTINEL,
   classifyModelCallError,
   describeExecutionError,
@@ -29,6 +30,20 @@ function middlewareWrap(inner: Error): Error {
   return wrapped;
 }
 
+/**
+ * Wrap as a native turn does: LangChain adds one MiddlewareError per
+ * middleware implementing `wrapModelCall`, and the production stack has
+ * more than ten of them (stigmer/stigmer#1450).
+ */
+function wrapLikeMiddlewareStack(inner: Error, layers: number): Error {
+  let wrapped = inner;
+  for (let layer = 0; layer < layers; layer++) wrapped = middlewareWrap(wrapped);
+  return wrapped;
+}
+
+/** A middleware stack deeper than any native turn's today. */
+const DEEP_STACK = 30;
+
 /** Mimic a provider SDK APIError: message + numeric `.status`. */
 function sdkError(status: number, message: string): Error {
   return Object.assign(new Error(message), { status });
@@ -62,13 +77,17 @@ describe("unwrapModelError", () => {
     expect(unwrapModelError(wrapped)).toBe(root);
   });
 
-  it("survives a pathological cause cycle via the depth cap", () => {
+  it("walks to the root however deep the middleware stack wraps it", () => {
+    const root = sdkError(401, "401 authentication_error");
+    expect(unwrapModelError(wrapLikeMiddlewareStack(root, DEEP_STACK))).toBe(root);
+  });
+
+  it("ends a cause cycle at the first error seen twice", () => {
     const a = new Error("a");
     const b = new Error("b");
     a.cause = b;
     b.cause = a;
-    // Any chain member is acceptable; the point is it terminates.
-    expect(unwrapModelError(a)).toBeInstanceOf(Error);
+    expect(unwrapModelError(a)).toBe(b);
   });
 
   it("passes non-Error values through", () => {
@@ -538,3 +557,52 @@ describe("describeExecutionError", () => {
     expect(errorMessage).toContain("platform-side issue");
   });
 });
+
+describe("classifyModelCallError on the organization's own provider key", () => {
+  const proxied = { proxyMode: true, provider: "anthropic" as const, modelId: "claude-sonnet-4-6" };
+  const marked = (message: string) => `${message} [code: ${ORGANIZATION_PROVIDER_KEY_SENTINEL}]`;
+
+  it("words the key's billing exhaustion as the organization's account, never platform capacity", () => {
+    const err = middlewareWrap(sdkError(400, marked(ANTHROPIC_BILLING_MESSAGE)));
+    const classified = classifyModelCallError(err, proxied);
+    expect(classified?.code).toBe("LLM_PROVIDER_BILLING");
+    expect(classified?.retryable).toBe(false);
+    expect(classified?.message).toContain("organization's own Anthropic key");
+    expect(classified?.message).not.toContain(PLATFORM_CAPACITY_SENTINEL);
+  });
+
+  it("words a rejected key as the organization's key, not an expired Stigmer session", () => {
+    const err = sdkError(401, marked('401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}'));
+    const classified = classifyModelCallError(err, proxied);
+    expect(classified?.code).toBe("LLM_AUTHENTICATION_ERROR");
+    expect(classified?.message).toContain("rejected your organization's own key");
+    expect(classified?.message).not.toContain("Stigmer platform");
+  });
+
+  it("words a rejected key as the organization's through a native turn's middleware stack", () => {
+    const rejected = sdkError(401, marked('401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}'));
+    const { errorType, errorMessage } = describeExecutionError(wrapLikeMiddlewareStack(rejected, DEEP_STACK), proxied);
+    expect(errorType).toBe("LLM_AUTHENTICATION_ERROR");
+    expect(errorMessage).toContain("rejected your organization's own key");
+    expect(errorMessage).not.toContain("MiddlewareError");
+  });
+
+  it("words a forbidden model as the key's account permission", () => {
+    const classified = classifyModelCallError(sdkError(403, marked("403 permission_error")), proxied);
+    expect(classified?.code).toBe("LLM_PERMISSION_DENIED");
+    expect(classified?.message).toContain("denied your organization's own key");
+  });
+
+  it("classifies the key's other failures as direct mode would", () => {
+    const rateLimited = classifyModelCallError(sdkError(429, marked("429 rate_limit_error")), proxied);
+    expect(rateLimited?.code).toBe("LLM_RATE_LIMIT");
+    const serverError = classifyModelCallError(sdkError(529, marked("529 overloaded_error")), proxied);
+    expect(serverError?.code).toBe("LLM_PROVIDER_ERROR");
+    expect(serverError?.retryable).toBe(true);
+  });
+
+  it("leaves an unmarked proxied 401 on the platform wording", () => {
+    const classified = classifyModelCallError(sdkError(401, "401 unauthorized"), proxied);
+    expect(classified?.message).toContain("Stigmer platform rejected");
+  });
+});

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

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for the platform STIGMER_SERVER_ADDRESS: the one dial-target
+ * rule, which endpoint answers for which transport, the fill that never
+ * overrides, and that the address is the only key the platform fills: a
+ * declared STIGMER_API_KEY is the user's to save (stigmer/stigmer#1446).
+ */
+
+import { describe, it, expect } from "vitest";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import {
+  SERVER_ADDRESS_ENV_KEY,
+  fillPlatformServerAddress,
+  grpcTarget,
+  platformServerAddress,
+  type PlatformEndpoints,
+} from "../platform-server-address.js";
+
+const LOCAL: PlatformEndpoints = {
+  stigmerBackendEndpoint: "http://localhost:7234",
+  mcpPublicEndpoint: null,
+};
+
+const WITH_PUBLIC: PlatformEndpoints = {
+  stigmerBackendEndpoint: "http://stigmer-server.internal:80",
+  mcpPublicEndpoint: "https://api.example.com",
+};
+
+function server(
+  transport: "stdio" | "http",
+  declared: readonly string[] = [SERVER_ADDRESS_ENV_KEY],
+): McpServer {
+  const env = Object.fromEntries(declared.map((key) => [key, {}]));
+  const serverType = transport === "stdio"
+    ? { case: "stdio", value: { command: "stigmer", args: ["mcp-server"] } }
+    : { case: "http", value: { url: "https://mcp.example.com/mcp", headers: {} } };
+  return { metadata: { slug: "stigmer" }, spec: { serverType, env } } as unknown as McpServer;
+}
+
+describe("grpcTarget", () => {
+  it.each([
+    ["http://localhost:7234", "localhost:7234"],
+    ["https://api.stigmer.ai", "api.stigmer.ai:443"],
+    ["https://api.stigmer.ai:8443", "api.stigmer.ai:8443"],
+    ["http://api.local", "api.local:80"],
+    ["http://stigmer.lan:80", "stigmer.lan:80"],
+    ["http://[::1]:7234", "[::1]:7234"],
+    ["http://localhost:7234/", "localhost:7234"],
+    ["https://api.stigmer.ai/v1/rpc", "api.stigmer.ai:443"],
+  ])("takes an http(s) URL apart with an explicit port: %s -> %s", (input, expected) => {
+    expect(grpcTarget(input)).toBe(expected);
+  });
+
+  it.each([
+    ["localhost:7234"],
+    ["stigmer-server.stigmer-prod.svc.cluster.local:80"],
+    ["api.stigmer.ai"],
+    ["not a url"],
+  ])("passes a value that is not an http(s) URL through: %s", (input) => {
+    expect(grpcTarget(input)).toBe(input);
+  });
+});
+
+describe("platformServerAddress", () => {
+  it("answers the operator's public endpoint for every transport", () => {
+    expect(platformServerAddress("http", WITH_PUBLIC)).toBe("api.example.com:443");
+    expect(platformServerAddress("stdio", WITH_PUBLIC)).toBe("api.example.com:443");
+  });
+
+  it("answers the runner's own backend endpoint for a stdio child", () => {
+    expect(platformServerAddress("stdio", LOCAL)).toBe("localhost:7234");
+  });
+
+  it("knows no address for a remote server without a public endpoint", () => {
+    expect(platformServerAddress("http", LOCAL)).toBeNull();
+    expect(platformServerAddress(undefined, LOCAL)).toBeNull();
+  });
+});
+
+describe("fillPlatformServerAddress", () => {
+  it("fills a declared, missing address for a stdio server", () => {
+    const env = { OTHER: "x" };
+    const result = fillPlatformServerAddress(server("stdio"), env, LOCAL);
+    expect(result).toEqual({ OTHER: "x", [SERVER_ADDRESS_ENV_KEY]: "localhost:7234" });
+    expect(env).toEqual({ OTHER: "x" });
+  });
+
+  it("fills a declared, empty address", () => {
+    const result = fillPlatformServerAddress(
+      server("stdio"),
+      { [SERVER_ADDRESS_ENV_KEY]: "" },
+      LOCAL,
+    );
+    expect(result[SERVER_ADDRESS_ENV_KEY]).toBe("localhost:7234");
+  });
+
+  it("never overrides a value already present", () => {
+    const env = { [SERVER_ADDRESS_ENV_KEY]: "other.example:7234" };
+    expect(fillPlatformServerAddress(server("stdio"), env, WITH_PUBLIC)).toBe(env);
+  });
+
+  it("gives nothing to a server that does not declare the key", () => {
+    const env = {};
+    expect(fillPlatformServerAddress(server("stdio", ["OTHER"]), env, LOCAL)).toBe(env);
+  });
+
+  it("fills a remote server only from the public endpoint", () => {
+    expect(
+      fillPlatformServerAddress(server("http"), {}, WITH_PUBLIC)[SERVER_ADDRESS_ENV_KEY],
+    ).toBe("api.example.com:443");
+    const env = {};
+    expect(fillPlatformServerAddress(server("http"), env, LOCAL)).toBe(env);
+  });
+
+  it("fills the address alone, never a declared STIGMER_API_KEY", () => {
+    const result = fillPlatformServerAddress(
+      server("http", [SERVER_ADDRESS_ENV_KEY, "STIGMER_API_KEY"]),
+      {},
+      WITH_PUBLIC,
+    );
+    expect(result).toEqual({ [SERVER_ADDRESS_ENV_KEY]: "api.example.com:443" });
+  });
+});