@stigmer/runner 3.40.0 → 3.41.0

package/src/shared/__tests__/prompt-sections.test.ts

@@ -1,8 +1,6 @@
 /**
- * The shared prompt glue (`shared/prompt-sections.ts`): the standing order,
- * the input-files lines, the skill selection and the also-available sentence
- * (the sentence's arms came from `skill-writer.test.ts`, retired with its
- * module in #1096). What each harness renders AROUND these is pinned whole by
+ * The shared prompt glue (`shared/prompt-sections.ts`): the standing order
+ * and the input-files lines. What each harness renders AROUND these is pinned whole by
  * the two builders' prompt goldens (`execute-deep-agent/__tests__/
  * prompt-goldens.test.ts`, `execute-cursor/__tests__/prompt-goldens.test.ts`);
  * this file pins the glue's own contract, harness-free.
@@ -10,16 +8,12 @@
 
 import { describe, it, expect } from "vitest";
 import {
-  alsoAvailableSkillsNote,
   inputFileLines,
-  selectSkillsForPrompt,
   standingContextSections,
   visionPromptInfoOf,
   type StandingSectionKind,
 } from "../prompt-sections.js";
 import type { ResolvedAttachment } from "../attachment-resolver.js";
-import type { SkillMetadata } from "../skill-resolver.js";
-import { SKILL_COUNT_THRESHOLD } from "../skill-relevance.js";
 import { formatDeclaredPreferencesText } from "../declared-preferences.js";
 
 describe("standingContextSections", () => {
@@ -119,49 +113,3 @@ describe("visionPromptInfoOf", () => {
     });
   });
 });
-
-describe("selectSkillsForPrompt", () => {
-  const skill = (name: string, description: string): SkillMetadata => ({ name, description, path: `.stigmer/skills/${name}/SKILL.md` });
-
-  it("highlights every skill below the threshold, in mount order, and names none as also-available", () => {
-    const skills = [skill("alpha", "Deploy to kubernetes"), skill("beta", "Reshape CSV exports")];
-    const selection = selectSkillsForPrompt("deploy the service", skills);
-    expect(selection.highlighted).toEqual(skills);
-    expect(selection.alsoAvailable).toEqual([]);
-  });
-
-  it("at the threshold, highlights the skills the message reaches and names the rest", () => {
-    const skills = Array.from({ length: SKILL_COUNT_THRESHOLD }, (_, i) =>
-      i === 0 ? skill("k8s-deploy", "Deploy services to kubernetes clusters") : skill(`other-${i}`, `Unrelated thing number ${i}`),
-    );
-    const selection = selectSkillsForPrompt("Deploy the payments service to kubernetes", skills);
-    expect(selection.highlighted.map((s) => s.name)).toContain("k8s-deploy");
-    expect(selection.alsoAvailable.length).toBeGreaterThan(0);
-    expect(selection.highlighted.length + selection.alsoAvailable.length).toBe(SKILL_COUNT_THRESHOLD);
-  });
-
-  it("selects nothing from nothing", () => {
-    expect(selectSkillsForPrompt("anything", [])).toEqual({ highlighted: [], alsoAvailable: [] });
-  });
-});
-
-describe("alsoAvailableSkillsNote", () => {
-  it("returns empty for no excluded names", () => {
-    expect(alsoAvailableSkillsNote([])).toBe("");
-  });
-
-  it("lists excluded skills with backtick formatting", () => {
-    const note = alsoAvailableSkillsNote(["alpha", "beta", "gamma"]);
-    expect(note).toContain("`alpha`");
-    expect(note).toContain("`beta`");
-    expect(note).toContain("`gamma`");
-  });
-
-  it("includes activation instructions that name no tool, so any harness can carry it", () => {
-    const note = alsoAvailableSkillsNote(["some-skill"]);
-    expect(note).toContain(".stigmer/skills/<name>/SKILL.md");
-    expect(note).toContain("relevant to your task");
-    expect(note).not.toMatch(/\b(read|Read) tool\b/);
-    expect(note.startsWith("#")).toBe(false);
-  });
-});

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