@stigmer/runner 3.5.1 → 3.5.3

package/src/activities/execute-cursor/__tests__/error-classifier-billing.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Tests for the billing category of the Cursor error classifier
+ * (stigmer/stigmer#330 follow-through: the Cursor arm kept working during
+ * the incident, but its classifier had no billing category — quota
+ * exhaustion of Cursor-managed keys would have classified as retryable
+ * rate-limit or unknown, burning retries against an exhausted account).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { synthesizeError } from "../error-classifier.js";
+import type { CapturedRejection } from "../rejection-capture.js";
+
+const FALLBACK = { model: "default", mode: "cloud", agentId: "agent-1" };
+
+function base() {
+  return {
+    sdkResultFields: undefined,
+    streamErrorMessage: undefined,
+    capturedRejection: undefined,
+    isResumedHandle: false,
+    fallbackContext: FALLBACK,
+  } as const;
+}
+
+describe("error-classifier billing category", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("classifies credit-balance prose as non-retryable billing", () => {
+    const result = synthesizeError({
+      ...base(),
+      streamErrorMessage:
+        "Your credit balance is too low to access the Anthropic API.",
+    });
+    expect(result.category).toBe("billing");
+    expect(result.retryable).toBe(false);
+  });
+
+  it("classifies insufficient_quota as billing even though it carries '429'", () => {
+    // Billing must be checked before rate-limit: this message matches both
+    // pattern lists, and only the billing diagnosis is terminal.
+    const result = synthesizeError({
+      ...base(),
+      sdkError: { code: "insufficient_quota", status: 429, message: "You have no credits remaining." },
+    });
+    expect(result.source).toBe("sdk");
+    expect(result.category).toBe("billing");
+    expect(result.retryable).toBe(false);
+  });
+
+  it("'usage limit' is billing (terminal), no longer a retryable rate-limit", () => {
+    const result = synthesizeError({
+      ...base(),
+      streamErrorMessage: "You have reached your usage limit for this billing period.",
+    });
+    expect(result.category).toBe("billing");
+    expect(result.retryable).toBe(false);
+  });
+
+  it("plain rate limits remain retryable rate-limit", () => {
+    const result = synthesizeError({
+      ...base(),
+      streamErrorMessage: "rate limit exceeded, retry after 2s",
+    });
+    expect(result.category).toBe("rate-limit");
+    expect(result.retryable).toBe(true);
+  });
+
+  it("the platform capacity sentinel is diagnosed as billing", () => {
+    const result = synthesizeError({
+      ...base(),
+      streamErrorMessage:
+        "Model capacity unavailable [code: STIGMER_PLATFORM_MODEL_CAPACITY]",
+    });
+    expect(result.category).toBe("billing");
+    expect(result.retryable).toBe(false);
+  });
+
+  it("billing via captured rejection is non-retryable", () => {
+    const rejection: CapturedRejection = {
+      code: "resource_exhausted",
+      message: "You exceeded your current quota",
+      timestamp: Date.now(),
+    };
+    const result = synthesizeError({
+      ...base(),
+      capturedRejection: rejection,
+    });
+    expect(result.source).toBe("rejection");
+    expect(result.category).toBe("billing");
+    expect(result.retryable).toBe(false);
+  });
+
+  it("billing is never upgraded to agent-stale on resumed handles", () => {
+    const result = synthesizeError({
+      ...base(),
+      isResumedHandle: true,
+      streamErrorMessage: "Your credit balance is too low to access the Anthropic API.",
+    });
+    expect(result.category).toBe("billing");
+  });
+});

package/src/activities/execute-cursor/error-classifier.ts

@@ -23,6 +23,7 @@ import type { CapturedRejection } from "./rejection-capture.js";
 
 export type ErrorCategory =
   | "auth"
+  | "billing"
   | "rate-limit"
   | "network"
   | "agent-stale"
@@ -51,9 +52,19 @@ const AUTH_PATTERNS = [
   "unauthenticated", "unauthorized", "401", "forbidden",
   "permission_denied", "invalid api key", "not logged in",
 ];
+// Billing/quota exhaustion is terminal, unlike a transient rate limit —
+// retrying cannot succeed until someone adds credits. "usage limit" moved
+// here from RATE_LIMIT_PATTERNS (it previously classified as retryable,
+// which burned retries against an exhausted account). Includes the platform
+// sentinel (see shared/model-error.ts) so a platform-attributed rewrite
+// relayed through Cursor infrastructure is also diagnosed as billing.
+const BILLING_PATTERNS = [
+  "credit balance is too low", "insufficient_quota",
+  "no credits remaining", "exceeded your current quota",
+  "usage limit", "stigmer_platform_model_capacity",
+];
 const RATE_LIMIT_PATTERNS = [
   "resource_exhausted", "rate limit", "429", "too many",
-  "usage limit",
 ];
 const NETWORK_PATTERNS = [
   "unavailable", "deadline_exceeded", "503", "504",
@@ -71,6 +82,9 @@ function matchesAny(text: string, patterns: string[]): boolean {
 }
 
 function classifyText(text: string): { category: ErrorCategory; retryable: boolean } {
+  // Billing before auth/rate-limit: billing prose can carry "429" or quota
+  // wording that would otherwise match the transient rate-limit patterns.
+  if (matchesAny(text, BILLING_PATTERNS)) return { category: "billing", retryable: false };
   if (matchesAny(text, AUTH_PATTERNS)) return { category: "auth", retryable: false };
   if (matchesAny(text, RATE_LIMIT_PATTERNS)) return { category: "rate-limit", retryable: true };
   if (matchesAny(text, NETWORK_PATTERNS)) return { category: "network", retryable: true };
@@ -183,7 +197,9 @@ function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
     return {
       category: category === "unknown" ? "network" : category,
       message: `[${opts.capturedRejection.code}] ${opts.capturedRejection.message}`,
-      retryable: category !== "auth",
+      // Rejections default to retryable (transport flakes), except the two
+      // terminal diagnoses that cannot self-heal on retry.
+      retryable: category !== "auth" && category !== "billing",
       source: "rejection",
     };
   }

package/src/activities/execute-cursor/index.ts

@@ -39,6 +39,7 @@ import type { Run, ConversationTurn } from "@cursor/sdk";
 
 import type { Config } from "../../config.js";
 import { StigmerClient } from "../../client/stigmer-client.js";
+import { describeExecutionError } from "../../shared/model-error.js";
 import { resolveAgentWithTransportRecovery } from "./session-lifecycle.js";
 import type { AgentResolution, CreateAgentOptions, CreateCloudAgentOptions } from "./session-lifecycle.js";
 import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
@@ -1991,8 +1992,13 @@ async function executeCursorInner(
       }      return slimStatus(status);
     }
 
-    const errMsg = err instanceof Error ? err.message : String(err);
-    const errType = err instanceof Error ? err.constructor.name : "Unknown";
+    // Unwrap + classify before formatting: the structured-output extraction
+    // path uses a LangChain model whose errors arrive MiddlewareError-wrapped
+    // with raw provider prose — the same leak the deep-agent harness fixes.
+    // Non-model errors keep the root error's own identity.
+    const { errorType: errType, errorMessage: errMsg } = describeExecutionError(err, {
+      proxyMode: !!config.proxyEndpoint,
+    });
     console.error(`ExecuteCursor failed: execution=${executionId}, [${errType}] ${errMsg}`);
 
     status.phase = ExecutionPhase.EXECUTION_FAILED;

package/src/activities/execute-deep-agent/index.ts

@@ -76,10 +76,24 @@ import {
 } from "../../shared/tool-row.js";
 import { stampFlowedFileEditRows, stampFlowedSubAgentFileEditRows } from "./stamp-flowed-rows.js";
 import { deriveTurnCommandProvenance } from "./command-provenance.js";
+import { describeExecutionError } from "../../shared/model-error.js";
+import { inferProvider, type LlmProvider } from "../../shared/llm-proxy.js";
 
 /** The harness id stamped on the deep-agent's file-review ledger events. */
 const DEEP_AGENT_HARNESS_ID = "deep-agent";
 
+/**
+ * Best-effort provider inference for error-message wording. inferProvider
+ * throws on unrecognized names; an error path must never throw over a label.
+ */
+function tryInferProvider(modelName: string): LlmProvider | undefined {
+  try {
+    return inferProvider(modelName);
+  } catch {
+    return undefined;
+  }
+}
+
 export function createDeepAgentActivities(config: Config) {
   const client = new StigmerClient({
     endpoint: config.stigmerBackendEndpoint,
@@ -752,8 +766,15 @@ export function createDeepAgentActivities(config: Config) {
           throw new CancelledFailure("Activity paused by orchestrator (error during cancellation)");
         }
 
-        const errorMessage = err instanceof Error ? err.message : String(err);
-        const errorType = err instanceof Error ? err.constructor.name : "UnknownError";
+        // Classify before formatting: model-call failures get stable codes
+        // and platform-vs-user attribution (LangChain's MiddlewareError
+        // wrapper is unwrapped to the root SDK error); non-model failures
+        // keep the root error's own identity. See shared/model-error.ts.
+        const { errorType, errorMessage } = describeExecutionError(err, {
+          proxyMode: !!config.proxyEndpoint,
+          modelId: setup?.modelName,
+          provider: setup ? tryInferProvider(setup.modelName) : undefined,
+        });
 
         console.error(
           `[ExecuteDeepAgent] Failed for execution ${executionId}: ` +

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

@@ -0,0 +1,252 @@
+/**
+ * Tests for the shared model-call error unwrapping and classification
+ * (stigmer/stigmer#330).
+ *
+ * The scenarios mirror the production incident: the platform proxy rewrites
+ * a platform-account billing rejection into a 503 carrying the sentinel
+ * code, LangChain wraps the SDK error in a MiddlewareError whose message is
+ * copied verbatim and whose `cause` is the original — and the runner must
+ * (a) attribute platform faults to the platform, (b) attribute direct-mode
+ * billing faults to the user's own provider account, and (c) never relabel
+ * a non-model error.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  PLATFORM_CAPACITY_SENTINEL,
+  classifyModelCallError,
+  describeExecutionError,
+  unwrapModelError,
+} from "../model-error.js";
+
+/**
+ * Mimic LangChain's MiddlewareError: message copied from the inner error,
+ * original preserved on `cause` (langchain dist/agents/errors.js:50-57).
+ */
+function middlewareWrap(inner: Error): Error {
+  const wrapped = new Error(inner.message);
+  wrapped.cause = inner;
+  return wrapped;
+}
+
+/** Mimic a provider SDK APIError: message + numeric `.status`. */
+function sdkError(status: number, message: string): Error {
+  return Object.assign(new Error(message), { status });
+}
+
+/** The exact message shape the incident produced on the Anthropic arm. */
+const ANTHROPIC_BILLING_MESSAGE =
+  '400 {"type":"error","error":{"type":"invalid_request_error","message":"Your credit balance is too low' +
+  ' to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits."}}';
+
+/** The rewritten message the cloud proxy now returns for platform faults. */
+const PLATFORM_REWRITE_MESSAGE =
+  "The Stigmer platform's model capacity for anthropic is temporarily unavailable." +
+  ` [code: ${PLATFORM_CAPACITY_SENTINEL}]`;
+
+describe("unwrapModelError", () => {
+  it("returns the error itself when there is no cause", () => {
+    const err = new Error("plain");
+    expect(unwrapModelError(err)).toBe(err);
+  });
+
+  it("walks a MiddlewareError-style cause chain to the root SDK error", () => {
+    const root = sdkError(400, ANTHROPIC_BILLING_MESSAGE);
+    const wrapped = middlewareWrap(root);
+    expect(unwrapModelError(wrapped)).toBe(root);
+  });
+
+  it("walks nested cause chains", () => {
+    const root = sdkError(503, "boom");
+    const wrapped = middlewareWrap(middlewareWrap(root));
+    expect(unwrapModelError(wrapped)).toBe(root);
+  });
+
+  it("survives a pathological cause cycle via the depth cap", () => {
+    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);
+  });
+
+  it("passes non-Error values through", () => {
+    expect(unwrapModelError("string error")).toBe("string error");
+  });
+});
+
+describe("classifyModelCallError — platform sentinel", () => {
+  it("classifies the platform rewrite as non-retryable platform capacity", () => {
+    const err = middlewareWrap(sdkError(503, PLATFORM_REWRITE_MESSAGE));
+
+    const classified = classifyModelCallError(err, { proxyMode: true, provider: "anthropic" });
+
+    expect(classified?.code).toBe("LLM_PLATFORM_CAPACITY");
+    expect(classified?.retryable).toBe(false);
+    expect(classified?.message).toContain("platform-side issue");
+    expect(classified?.message).toContain("credits were not charged");
+  });
+
+  it("sentinel wins over status mapping (a 503 would otherwise be retryable)", () => {
+    const classified = classifyModelCallError(
+      sdkError(503, PLATFORM_REWRITE_MESSAGE),
+      { proxyMode: true },
+    );
+    expect(classified?.code).toBe("LLM_PLATFORM_CAPACITY");
+    expect(classified?.retryable).toBe(false);
+  });
+});
+
+describe("classifyModelCallError — provider billing prose", () => {
+  it("in direct mode, attributes billing to the user's own provider account", () => {
+    const err = middlewareWrap(sdkError(400, ANTHROPIC_BILLING_MESSAGE));
+
+    const classified = classifyModelCallError(err, { proxyMode: false, provider: "anthropic" });
+
+    expect(classified?.code).toBe("LLM_PROVIDER_BILLING");
+    expect(classified?.retryable).toBe(false);
+    expect(classified?.message).toContain("Your Anthropic account");
+    // Direct mode keeps the provider message — it IS the user's account.
+    expect(classified?.message).toContain("credit balance is too low");
+  });
+
+  it("in proxy mode, raw billing prose (version-skewed proxy) attributes to the platform", () => {
+    const err = sdkError(400, ANTHROPIC_BILLING_MESSAGE);
+
+    const classified = classifyModelCallError(err, { proxyMode: true, provider: "anthropic" });
+
+    expect(classified?.code).toBe("LLM_PLATFORM_CAPACITY");
+    expect(classified?.message).not.toContain("Plans & Billing");
+  });
+
+  it("recognizes OpenAI quota exhaustion wordings", () => {
+    for (const msg of [
+      "429 You have no credits remaining. Add credits to continue using the API.",
+      "429 You exceeded your current quota, please check your plan and billing details.",
+      '429 {"error":{"type":"insufficient_quota"}}',
+    ]) {
+      const classified = classifyModelCallError(
+        sdkError(429, msg),
+        { proxyMode: false, provider: "openai" },
+      );
+      expect(classified?.code).toBe("LLM_PROVIDER_BILLING");
+    }
+  });
+});
+
+describe("classifyModelCallError — status mapping", () => {
+  it("maps statuses to the stable codes with call-llm's retryability policy", () => {
+    const cases: Array<[number, string, boolean]> = [
+      [401, "LLM_AUTHENTICATION_ERROR", false],
+      [403, "LLM_PERMISSION_DENIED", false],
+      [404, "LLM_MODEL_NOT_FOUND", false],
+      [400, "LLM_BAD_REQUEST", false],
+      [422, "LLM_UNPROCESSABLE_REQUEST", false],
+      [429, "LLM_RATE_LIMIT", false],
+      [500, "LLM_PROVIDER_ERROR", true],
+      [529, "LLM_PROVIDER_ERROR", true],
+      [418, "LLM_API_ERROR", false],
+    ];
+    for (const [status, code, retryable] of cases) {
+      const classified = classifyModelCallError(
+        sdkError(status, `HTTP ${status}`),
+        { proxyMode: false, provider: "openai", modelId: "gpt-4o" },
+      );
+      expect(classified?.code, `status ${status}`).toBe(code);
+      expect(classified?.retryable, `status ${status}`).toBe(retryable);
+    }
+  });
+
+  it("proxy-mode 401/403 wording points at the platform session, not a user API key", () => {
+    const classified = classifyModelCallError(
+      sdkError(401, "unauthorized"),
+      { proxyMode: true, provider: "anthropic" },
+    );
+    expect(classified?.message).toContain("Stigmer platform");
+    expect(classified?.message).not.toContain("your API key");
+  });
+
+  it("unwraps before duck-typing status (the incident shape end-to-end)", () => {
+    const classified = classifyModelCallError(
+      middlewareWrap(sdkError(429, "Too many requests")),
+      { proxyMode: false, provider: "openai" },
+    );
+    expect(classified?.code).toBe("LLM_RATE_LIMIT");
+  });
+});
+
+describe("classifyModelCallError — connection heuristics and no-signal", () => {
+  it("always recognizes the SDKs' own APIConnection* classes as retryable", () => {
+    class APIConnectionTimeoutError extends Error {}
+    class APIConnectionError extends Error {}
+    expect(
+      classifyModelCallError(new APIConnectionTimeoutError("timed out"), { proxyMode: false })?.code,
+    ).toBe("LLM_CONNECTION_TIMEOUT");
+    expect(
+      classifyModelCallError(new APIConnectionError("refused"), { proxyMode: false })?.code,
+    ).toBe("LLM_CONNECTION_ERROR");
+  });
+
+  it("loose Timeout/Connection names classify only when the caller vouches assumeModelCall", () => {
+    class ConnectTimeoutError extends Error {}
+
+    // A model-call-only catch (call-llm) keeps the loose heuristics.
+    expect(
+      classifyModelCallError(new ConnectTimeoutError("undici timeout"), {
+        proxyMode: false,
+        assumeModelCall: true,
+      })?.code,
+    ).toBe("LLM_CONNECTION_TIMEOUT");
+
+    // A broad catch must not relabel arbitrary *TimeoutError classes.
+    expect(
+      classifyModelCallError(new ConnectTimeoutError("undici timeout"), { proxyMode: false }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined for errors with no model-call signal", () => {
+    expect(classifyModelCallError(new Error("ENOSPC: disk full"), { proxyMode: true })).toBeUndefined();
+    expect(classifyModelCallError("not even an error", { proxyMode: false })).toBeUndefined();
+  });
+});
+
+describe("describeExecutionError", () => {
+  it("labels classified model errors with the stable code, not the wrapper class", () => {
+    const { errorType, errorMessage } = describeExecutionError(
+      middlewareWrap(sdkError(503, PLATFORM_REWRITE_MESSAGE)),
+      { proxyMode: true },
+    );
+    expect(errorType).toBe("LLM_PLATFORM_CAPACITY");
+    expect(errorMessage).toContain("credits were not charged");
+    expect(errorMessage).not.toContain("MiddlewareError");
+  });
+
+  it("keeps the root error's identity for non-model failures", () => {
+    class WorkspaceLockTimeoutError extends Error {}
+    const root = new WorkspaceLockTimeoutError("workspace busy");
+
+    const { errorType, errorMessage } = describeExecutionError(
+      middlewareWrap(root),
+      { proxyMode: true },
+    );
+
+    expect(errorType).toBe("WorkspaceLockTimeoutError");
+    expect(errorMessage).toBe("workspace busy");
+  });
+
+  it("handles non-Error throwables", () => {
+    const { errorType, errorMessage } = describeExecutionError("oops", { proxyMode: false });
+    expect(errorType).toBe("UnknownError");
+    expect(errorMessage).toBe("oops");
+  });
+
+  it("never surfaces provider billing-console prose in proxy mode", () => {
+    const { errorMessage } = describeExecutionError(
+      middlewareWrap(sdkError(400, ANTHROPIC_BILLING_MESSAGE)),
+      { proxyMode: true },
+    );
+    expect(errorMessage).not.toContain("Plans & Billing");
+    expect(errorMessage).toContain("platform-side issue");
+  });
+});