@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/src/activities/execute-cursor/__tests__/turn-recovery.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Unit tests for the turn-recovery digest (issue #366).
+ *
+ * The digest is the replacement agent's only account of the work its lost
+ * predecessor did, so these pins cover the three doctrine properties it
+ * inherits from the DD-013 bridge composer — bounded lines, drop-oldest
+ * budget enforcement with disclosure, never-throw — plus the rendering
+ * contract per message/tool-call kind.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+  type AgentMessage,
+  type ToolCall,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { composeTurnRecoveryDigest, formatTurnRecoveryText } from "../turn-recovery.js";
+
+function aiMessage(content: string, toolCalls: ToolCall[] = []): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content, toolCalls });
+}
+
+type ToolCallFields = Partial<
+  Pick<ToolCall, "name" | "argsPreview" | "approvalMessage" | "status" | "error">
+>;
+
+function toolCall(overrides: ToolCallFields): ToolCall {
+  return create(ToolCallSchema, {
+    id: "tc-1",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    ...overrides,
+  });
+}
+
+describe("composeTurnRecoveryDigest", () => {
+  it("renders assistant text and tool calls oldest-first", () => {
+    const digest = composeTurnRecoveryDigest([
+      aiMessage("Let me check the config first.", [
+        toolCall({ name: "Read", argsPreview: '{"path":"config.yaml"}' }),
+      ]),
+      aiMessage("The port is wrong — fixing it."),
+    ]);
+    expect(digest).toBe(
+      [
+        "Assistant: Let me check the config first.",
+        'Tool: Read({"path":"config.yaml"}) — completed',
+        "Assistant: The port is wrong — fixing it.",
+      ].join("\n"),
+    );
+  });
+
+  it("prefers the resolved approval message for a tool line — the same description the user approved against", () => {
+    const digest = composeTurnRecoveryDigest([
+      aiMessage("", [
+        toolCall({
+          approvalMessage: "Write file: gated.txt",
+          argsPreview: '{"path":"gated.txt","content":"..."}',
+          status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+        }),
+      ]),
+    ]);
+    expect(digest).toBe("Tool: Write file: gated.txt — paused for user approval");
+  });
+
+  it("maps each terminal status honestly and treats in-flight calls as interrupted", () => {
+    const digest = composeTurnRecoveryDigest([
+      aiMessage("", [
+        toolCall({ name: "A", status: ToolCallStatus.TOOL_CALL_COMPLETED }),
+        toolCall({ name: "B", status: ToolCallStatus.TOOL_CALL_FAILED, error: "exit 1" }),
+        toolCall({ name: "C", status: ToolCallStatus.TOOL_CALL_FAILED }),
+        toolCall({ name: "D", status: ToolCallStatus.TOOL_CALL_SKIPPED }),
+        toolCall({ name: "E", status: ToolCallStatus.TOOL_CALL_RUNNING }),
+        toolCall({ name: "F", status: ToolCallStatus.TOOL_CALL_PENDING }),
+      ]),
+    ]);
+    expect(digest).toBe(
+      [
+        "Tool: A — completed",
+        "Tool: B — failed: exit 1",
+        "Tool: C — failed",
+        "Tool: D — skipped",
+        "Tool: E — interrupted before it finished",
+        "Tool: F — interrupted before it finished",
+      ].join("\n"),
+    );
+  });
+
+  it("keeps system notices but skips human messages (already in <user_request>), thinking, and blanks", () => {
+    const digest = composeTurnRecoveryDigest([
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_HUMAN, content: "Fix the build" }),
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_SYSTEM, content: "Budget warning: 80% used" }),
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_THINKING, content: "hmm, maybe the lockfile" }),
+      aiMessage("   "),
+    ]);
+    expect(digest).toBe("System: Budget warning: 80% used");
+  });
+
+  it("returns undefined when nothing renders", () => {
+    expect(composeTurnRecoveryDigest([])).toBeUndefined();
+    expect(
+      composeTurnRecoveryDigest([
+        create(AgentMessageSchema, { type: MessageType.MESSAGE_HUMAN, content: "only the request" }),
+      ]),
+    ).toBeUndefined();
+  });
+
+  it("truncates a long assistant line at the per-line budget with an ellipsis", () => {
+    const digest = composeTurnRecoveryDigest([aiMessage("x".repeat(1000))]);
+    expect(digest).toBe(`Assistant: ${"x".repeat(400)}\u2026`);
+  });
+
+  it("drops the OLDEST lines when over the whole-digest budget and discloses the omission", () => {
+    // 30 lines of ~311 chars each (~9.6k total) against the 4000-char budget:
+    // the newest lines must survive, the oldest go, and the notice leads.
+    const messages = Array.from({ length: 30 }, (_, i) =>
+      aiMessage(`step ${String(i).padStart(2, "0")} ${"y".repeat(300)}`),
+    );
+    const digest = composeTurnRecoveryDigest(messages);
+    expect(digest).toBeDefined();
+    expect(digest!.length).toBeLessThanOrEqual(4000);
+    const lines = digest!.split("\n");
+    expect(lines[0]).toBe("[\u2026 earlier activity in this turn omitted for length]");
+    // Recency wins: the last line is the newest entry, the first entries are gone.
+    expect(lines[lines.length - 1]).toContain("step 29");
+    expect(digest).not.toContain("step 00");
+  });
+
+  it("never throws — a malformed message degrades to no digest, not a failed recovery", () => {
+    // Force the internal iteration to blow up: content getter that throws.
+    const poison = new Proxy(aiMessage("ok"), {
+      get(target, prop, receiver) {
+        if (prop === "content") throw new Error("corrupt row");
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    expect(composeTurnRecoveryDigest([poison as AgentMessage])).toBeUndefined();
+  });
+});
+
+describe("formatTurnRecoveryText", () => {
+  it("frames a digest with the work-already-done preamble", () => {
+    const text = formatTurnRecoveryText("Assistant: did things");
+    expect(text).toContain("session holding that conversation was lost");
+    expect(text).toContain("do not start the task over");
+    expect(text.endsWith("Assistant: did things")).toBe(true);
+  });
+
+  it("still discloses the state loss when there is no transcript — without it the appended decisions would read as reactions to proposals this agent never made", () => {
+    for (const empty of [undefined, "", "   "]) {
+      const text = formatTurnRecoveryText(empty);
+      expect(text).toContain("session holding that conversation was lost");
+      expect(text).toContain("no transcript of your progress is available");
+    }
+  });
+});

package/src/activities/execute-cursor/__tests__/turn-stream.test.ts

@@ -222,6 +222,19 @@ describe("consumeCursorTurnStream", () => {
     expect(state.streamErrorMessage).toBe("boom");
   });
 
+  it("does not capture a non-string stream ERROR message (oss#299 hardening)", async () => {
+    // message is untyped at runtime; a structured value assigned here would
+    // crash classifyText downstream (.toLowerCase() on a non-string).
+    const { deps, state } = buildDeps();
+
+    await consumeCursorTurnStream(
+      mockRun([ev({ type: "status", status: "ERROR", message: { code: 14 } })]),
+      deps,
+    );
+
+    expect(state.streamErrorMessage).toBeUndefined();
+  });
+
   describe("first-denial early stop", () => {
     let hitlDir: string;
 

package/src/activities/execute-cursor/approval-state.ts

@@ -13,6 +13,7 @@
  *   "mcpToolPolicies": {
  *     "apply_cloud_resource": { "requiresApproval": true, "message": "..." }
  *   },
+ *   "mcpServerEnabledTools": { "planton": ["get_cloud_resource"] },
  *   "approvedGrants": [{ "toolName": "edit", "mcpServerSlug": "", "key": "write", "salient": "a.txt", "contentDigest": "<sha256>" }],
  *   "approvedGrantTokens": ["<base64(key\nsalient[\ncontentDigest])>"]
  * }
@@ -174,6 +175,21 @@ export interface ApprovalStateFile {
    */
   leasedCategories: string[];
   mcpToolPolicies: Record<string, McpToolPolicyEntry>;
+  /**
+   * Per-server effective enabled_tools allow-lists (issue #350), keyed by
+   * MCP server slug — ONLY restricted servers appear (an absent slug means
+   * unrestricted, so the common case stays an empty object). The Cursor SDK
+   * config cannot hide a server's tools, so the hook enforces the manifest
+   * instead: on beforeMCPExecution it matches the payload's mcp_server_name
+   * against this map and denies a non-listed tool with the non-pausing,
+   * permanent "disabled" kind — BEFORE autoApproveAll and grants, because
+   * enabled_tools is a capability manifest, not an approval gate (no bypass
+   * may resurrect a disabled tool, and no human may be offered "approve" on
+   * one). Unlike mcpToolPolicies (name-keyed, server-blind), this map is
+   * server-scoped: the hook payload carries the server identity, so equal
+   * tool names on different servers cannot cross-grant.
+   */
+  mcpServerEnabledTools: Record<string, string[]>;
   approvedGrants: ApprovalGrant[];
   approvedGrantTokens: string[];
   /**
@@ -381,6 +397,8 @@ function parseArgs(argsPreview: string): Record<string, unknown> | undefined {
  * - leasedCategories: built-in categories with a run-lifetime lease
  * - mcpToolPolicies: per-tool policy for MCP tools requiring approval (leased
  *   servers are already absent — dropped upstream by mergeApprovalPolicies)
+ * - mcpServerEnabledTools: per-server enabled_tools allow-lists (issue #350,
+ *   restricted servers only) for the hook's permanent "disabled" arm
  * - approvedGrants / approvedGrantTokens: tools approved in the current HITL
  *   cycle, allowed through on reinvocation
  *
@@ -396,6 +414,7 @@ export function buildApprovalState(
   captureIgnored = false,
   gitWorkspace = true,
   unattendedSkip = false,
+  mcpServerEnabledTools: Record<string, string[]> = {},
 ): ApprovalStateFile {
   const approvedGrants = grants ?? [];
 
@@ -411,6 +430,7 @@ export function buildApprovalState(
     autoApproveAll: globalBypass,
     leasedCategories: [...leasedCategories],
     mcpToolPolicies,
+    mcpServerEnabledTools,
     approvedGrants,
     // The hook matches a tool call's PRIMARY token (content when it can compute a
     // digest from tool_input, else coarse). A content-identified grant authorizes
@@ -474,12 +494,18 @@ const DENIAL_LEDGER_FILE = "denials.jsonl";
  *                     classification may never have run).
  * - `fail-closed`   — the approval state file was missing, so everything gated
  *                     denied. A turn-level "the gate itself was broken" fact.
+ * - `disabled`      — the agent's enabled_tools manifest excludes this MCP
+ *                     tool (issue #350). Permanent for the run and
+ *                     mode-independent: NOT an approval (a human must never be
+ *                     offered "approve" on a manifest-disabled tool), so it is
+ *                     non-pausing and the model adapts — the same consumer
+ *                     semantics as `secret`.
  *
  * An unknown kind string is preserved as-is: it is treated as non-pausing (an
  * unknown deny must never manufacture an approval) but still attributes the
  * blocked call to our own hook.
  */
-export type DenialKind = "approval" | "unattended" | "secret" | "capture-error" | "fail-closed";
+export type DenialKind = "approval" | "unattended" | "secret" | "capture-error" | "fail-closed" | "disabled";
 
 /** The one kind that pauses the run for user approval. */
 export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
@@ -487,6 +513,9 @@ export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
 /** The unattended-mode resolution kind (non-pausing; stamped SKIPPED). */
 export const UNATTENDED_DENIAL_KIND: DenialKind = "unattended";
 
+/** The enabled_tools manifest denial kind (non-pausing, permanent; issue #350). */
+export const DISABLED_DENIAL_KIND: DenialKind = "disabled";
+
 /**
  * One denial recorded by the preToolUse hook. `token` is the call's identity in
  * the same space as grantToken() (base64 of `toolName \n salientArg`), used to

package/src/activities/execute-cursor/attachment-resolver.ts

@@ -22,6 +22,13 @@
  * directives are built from the RESOLVED paths, so prompt and filesystem can
  * never disagree.
  *
+ * Duplicate filenames are renamed, never overwritten (issue #364): because
+ * placement keys purely on the filename, two attachments with the same name
+ * contend for one path — the later one takes the platform's `stem-2.ext`
+ * rename (shared/attachment-naming.ts, same semantics as the deep-agent
+ * injector and the React composer) and the rename is disclosed in the
+ * prompt's `<input_files>` section via {@link ResolvedAttachment.renamedFrom}.
+ *
  * Error model: fail-hard, matching the native harness's attachment injector.
  * Attachments are explicit user inputs — an execution that silently runs
  * without one produces silently incorrect results (the "plan file wasn't
@@ -33,6 +40,7 @@ import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import {
   isVisionCandidate,
   type VisionBudget,
@@ -46,9 +54,16 @@ import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/work
 const INPUTS_SUBDIR = "inputs";
 
 export interface ResolvedAttachment {
+  /** The final on-disk basename — after any duplicate rename. */
   filename: string;
   /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
   relativePath: string;
+  /**
+   * The attachment's original filename, present only when a duplicate name
+   * was renamed (shared/attachment-naming.ts) — rendered as disclosure in
+   * the prompt's `<input_files>` section.
+   */
+  renamedFrom?: string;
   /** Present when the attachment was accepted into the turn's vision payload. */
   vision?: VisionImage;
   /**
@@ -111,9 +126,13 @@ export async function resolveAttachments(
   // it, but only when the agent has skills).
   await ensureStigmerSymlink(options.primaryWorkspaceDir, platformDir);
 
+  // Placement keys purely on the filename, so this set is the whole
+  // collision domain — sequential resolution means each attachment sees
+  // every name claimed before it (see module doc on duplicate handling).
+  const takenNames = new Set<string>();
   const results: ResolvedAttachment[] = [];
   for (const attachment of attachments) {
-    results.push(await resolveAttachment(attachment, inputsDir, options));
+    results.push(await resolveAttachment(attachment, inputsDir, takenNames, options));
   }
 
   console.log(
@@ -127,11 +146,15 @@ export async function resolveAttachments(
 async function resolveAttachment(
   attachment: Attachment,
   inputsDir: string,
+  takenNames: Set<string>,
   options: AttachmentResolverOptions,
 ): Promise<ResolvedAttachment> {
   // Local-mode fast path: the file is already on this machine's disk.
   if (options.mode === "local" && attachment.localPath) {
-    const filename = safeInputName(attachment.filename || attachment.localPath);
+    const { name: filename, renamedFrom } = allocateUniqueName(
+      safeInputName(attachment.filename || attachment.localPath),
+      takenNames,
+    );
     let vision: VisionOutcome | undefined;
     try {
       vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
@@ -145,6 +168,7 @@ async function resolveAttachment(
     return {
       filename,
       relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+      ...(renamedFrom !== undefined ? { renamedFrom } : {}),
       ...visionOutcomeFields(vision),
     };
   }
@@ -164,7 +188,10 @@ async function resolveAttachment(
     );
   }
 
-  const filename = safeInputName(attachment.filename || attachment.storageKey);
+  const { name: filename, renamedFrom } = allocateUniqueName(
+    safeInputName(attachment.filename || attachment.storageKey),
+    takenNames,
+  );
   let content: Buffer;
   try {
     content = await options.storage.download(attachment.storageKey);
@@ -185,6 +212,7 @@ async function resolveAttachment(
   return {
     filename,
     relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+    ...(renamedFrom !== undefined ? { renamedFrom } : {}),
     ...visionOutcomeFields(vision),
   };
 }

package/src/activities/execute-cursor/blueprint-resolver.ts

@@ -20,6 +20,13 @@ import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { CloudRepo } from "./session-lifecycle.js";
+import { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
+
+// Both harnesses must merge agent + session usages identically (session wins
+// per slug — the usage whose enabled_tools the enforcement honors), so the
+// merge lives in shared/mcp-resolver.ts. Re-exported here for its historical
+// home alongside mergeSkillRefs.
+export { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
 
 /**
  * Path segments that identify runner-internal directories. Any workspace dir
@@ -130,33 +137,6 @@ export function resolveCloudRepos(workspaceEntries: WorkspaceEntry[]): CloudRepo
 // MCP and skill merging
 // ---------------------------------------------------------------------------
 
-/**
- * Merge MCP server usages from agent (base) and session (overlay).
- *
- * Replicates session_context_merge.py::merge_mcp_server_usages():
- * - Agent-level usages are the base set
- * - Session-level usages extend or override by mcp_server_ref.slug
- * - If both reference the same slug, session-level takes precedence
- */
-export function mergeMcpServerUsages(
-  agentUsages: McpServerUsage[],
-  sessionUsages: McpServerUsage[],
-): McpServerUsage[] {
-  const bySlug = new Map<string, McpServerUsage>();
-
-  for (const usage of agentUsages) {
-    const slug = usage.mcpServerRef?.slug;
-    if (slug) bySlug.set(slug, usage);
-  }
-
-  for (const usage of sessionUsages) {
-    const slug = usage.mcpServerRef?.slug;
-    if (slug) bySlug.set(slug, usage);
-  }
-
-  return [...bySlug.values()];
-}
-
 /**
  * Merge skill refs from agent and session.
  *

package/src/activities/execute-cursor/env-resolver.ts

@@ -25,7 +25,9 @@ export async function resolveExecutionEnv(
 ): Promise<EnvResult> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this execution's session, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would resolve redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     agentExecutionId: executionId,
   });

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

@@ -7,8 +7,9 @@
  * 3. Surface isRetryable for future workflow-level retry decisions
  *
  * Error detail can come from several sources (in priority order):
- * - A thrown CursorSdkError's structured fields (highest fidelity)
- * - run.wait().result (SDK-provided string, often bare/generic)
+ * - Structured fields, either from a thrown CursorSdkError or lifted from a
+ *   structured run.wait() error value (highest fidelity)
+ * - run.wait() error text (SDK-provided string, often bare/generic)
  * - SDKStatusMessage with status "ERROR" from the stream
  * - ConnectError captured from process unhandledRejection
  * - Text extracted from the failing run.conversation() turn
@@ -39,7 +40,8 @@ export interface ClassifiedError {
 
 /**
  * Structured fields lifted from a thrown CursorSdkError (errors.d.ts:
- * { code, status, isRetryable, cause, endpoint, requestId, operation }).
+ * { code, status, isRetryable, cause, endpoint, requestId, operation }) or
+ * from a structured run.wait() error value (see extractRunErrorSources).
  * Only the fields used for classification are retained.
  */
 export interface SdkErrorFields {
@@ -48,6 +50,110 @@ export interface SdkErrorFields {
   message?: string;
 }
 
+/**
+ * What String() produces for any plain object. Carries zero signal, so it is
+ * refused everywhere: extraction never emits it, and classifyFromSources
+ * treats it as absent should any other producer leak it through.
+ */
+const OBJECT_JUNK_STRING = "[object Object]";
+
+/**
+ * Error detail lifted from a run.wait() result, split by fidelity: structured
+ * values land in sdkError, plain text in sdkResultFields. At most one of the
+ * two is set; both undefined means the result carried nothing usable and the
+ * classifier's lower-priority sources should decide.
+ */
+export interface RunErrorSources {
+  sdkError: SdkErrorFields | undefined;
+  sdkResultFields: string | undefined;
+}
+
+const NO_RUN_ERROR_SOURCES: RunErrorSources = {
+  sdkError: undefined,
+  sdkResultFields: undefined,
+};
+
+/**
+ * Lift error detail from a run.wait() result whose status is "error".
+ *
+ * The SDK types RunResult.result as `string`, but structured values (Error
+ * instances, { code, message } objects) have been observed at runtime, both
+ * in `result` and in the undeclared error/message/reason fields (oss#299).
+ * A bare String() on those yields "[object Object]", which both destroys the
+ * message users see and — worse — shadows the lower-priority classifier
+ * sources (stream, rejection, conversation introspection) that often hold
+ * the real reason.
+ *
+ * Walks the candidate fields in order and answers from the FIRST one that
+ * yields usable content: strings keep flowing to the string channel
+ * (sdkResultFields), structured values are lifted into the same structured
+ * channel a thrown CursorSdkError uses (sdkError), and hopeless values are
+ * skipped so a later candidate — or the classifier's fallback sources — can
+ * win. (The previous `??` chain stopped at the first non-nullish value, so a
+ * hopeless object or empty string hid usable text one field later.)
+ *
+ * Deliberately NO JSON.stringify fallback for unrecognized object shapes:
+ * the error arm already logs the raw result in full server-side, and a JSON
+ * blob shown to the user would shadow the introspection sources that exist
+ * precisely to recover the real reason.
+ */
+export function extractRunErrorSources(result: unknown): RunErrorSources {
+  if (result === null || typeof result !== "object") return NO_RUN_ERROR_SOURCES;
+  const r = result as Record<string, unknown>;
+  for (const candidate of [r.result, r.error, r.message, r.reason]) {
+    const extracted = extractFromCandidate(candidate);
+    if (extracted) return extracted;
+  }
+  return NO_RUN_ERROR_SOURCES;
+}
+
+function extractFromCandidate(v: unknown): RunErrorSources | undefined {
+  if (v == null) return undefined;
+  if (typeof v === "string") {
+    if (v.length === 0 || v === OBJECT_JUNK_STRING) return undefined;
+    return { sdkError: undefined, sdkResultFields: v };
+  }
+  if (typeof v === "object") {
+    // Covers Error instances too: their message (and, on SDK/Node error
+    // shapes, code/status) are readable as plain properties.
+    const o = v as Record<string, unknown>;
+    const fields: SdkErrorFields = {};
+    if (typeof o.code === "string" && o.code.length > 0) fields.code = o.code;
+    if (typeof o.status === "number") fields.status = o.status;
+    if (typeof o.message === "string" && o.message.length > 0) fields.message = o.message;
+    if (fields.code !== undefined || fields.status !== undefined || fields.message !== undefined) {
+      return { sdkError: fields, sdkResultFields: undefined };
+    }
+    return undefined;
+  }
+  // Remaining primitives (number, boolean, ...) stringify losslessly.
+  const text = String(v);
+  return text.length > 0 ? { sdkError: undefined, sdkResultFields: text } : undefined;
+}
+
+/**
+ * Stable lead sentence of the detail-free fallback error (all five detail
+ * channels empty — empirically the shape of Cursor-side capacity rejections,
+ * oss#492). This is what end users read in embedded surfaces, so it must be
+ * actionable product copy, not a diagnostic; the diagnostic context follows
+ * in a parenthetical. Mirrors the COST_LIMIT_ERROR_PREFIX convention: a
+ * consumer that needs to recognize this failure can match on the prefix.
+ * Do not reword without checking consumers, and NEVER include the phrase
+ * "retry or resume" — sdk-react's isInterruptedError (MessageThread.tsx)
+ * reframes any error containing it as a neutral resumable notice instead of
+ * a failure alert.
+ */
+export const DETAIL_FREE_FALLBACK_USER_PREFIX =
+  "The model may be temporarily overloaded — please retry, or switch to a different model.";
+
+/**
+ * Stable lead sentence of the transport-timeout fallback error (0 messages,
+ * ~30s duration — the SDK's default timeout with no stream established).
+ * Same user-facing rules as DETAIL_FREE_FALLBACK_USER_PREFIX above.
+ */
+export const TRANSPORT_TIMEOUT_USER_PREFIX =
+  "The connection to the model could not be established — please retry.";
+
 const AUTH_PATTERNS = [
   "unauthenticated", "unauthorized", "401", "forbidden",
   "permission_denied", "invalid api key", "not logged in",
@@ -168,7 +274,11 @@ function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
   }
 
   if (opts.sdkResultFields) {
-    const isBareGeneric = opts.sdkResultFields === "Cursor run failed";
+    // "Cursor run failed" is the SDK's bare generic; "[object Object]" is
+    // String()-coerced junk from any producer that bypassed the shape-aware
+    // extraction. Neither carries signal — fall through to better sources.
+    const isBareGeneric = opts.sdkResultFields === "Cursor run failed"
+      || opts.sdkResultFields === OBJECT_JUNK_STRING;
     if (!isBareGeneric) {
       const { category, retryable } = classifyText(opts.sdkResultFields);
       return {
@@ -230,7 +340,10 @@ function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
     const { model, mode, agentId } = opts.fallbackContext;
     return {
       category: "network",
-      message: `Transport timeout (${opts.durationMs}ms, 0 messages received). Model=${model}, mode=${mode}, agentId=${agentId}`,
+      message:
+        `${TRANSPORT_TIMEOUT_USER_PREFIX} ` +
+        `(Transport timeout: ${opts.durationMs}ms, 0 messages received. ` +
+        `Model=${model}, mode=${mode}, agentId=${agentId})`,
       retryable: true,
       source: "fallback",
     };
@@ -245,11 +358,22 @@ function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
     };
   }
 
+  // The honest last resort: every detail channel was empty. Observed in prod
+  // only during provider capacity incidents (oss#492: Composer 2.5 degradation
+  // — the SDK rejection that carries ERROR_RESOURCE_EXHAUSTED in Cursor's IDE
+  // arrives here detail-free), so the copy leads with the capacity hypothesis
+  // hedged ("may be"), and retryable is true: the observed cause is transient
+  // by nature, and nothing gates a recovery loop on unknown+retryable. The
+  // parenthetical keeps the exact Model=/mode=/agentId= tokens for log-grep
+  // continuity and the env integration test's matcher.
   const { model, mode, agentId } = opts.fallbackContext;
   return {
     category: "unknown",
-    message: `Cursor run failed (no detail from SDK). Model=${model}, mode=${mode}, agentId=${agentId}`,
-    retryable: false,
+    message:
+      `${DETAIL_FREE_FALLBACK_USER_PREFIX} ` +
+      `(No error detail from the Cursor SDK. ` +
+      `Model=${model}, mode=${mode}, agentId=${agentId})`,
+    retryable: true,
     source: "fallback",
   };
 }

package/src/activities/execute-cursor/extract-structured-output.ts

@@ -0,0 +1,72 @@
+/**
+ * Tier-2 structured-output extraction for the Cursor harness.
+ *
+ * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
+ * the agent's free-text response, this tier asks an economy-tier LLM to
+ * extract it via withStructuredOutput (function-calling), which guarantees
+ * schema-conformant output through the API's tool-use mechanism.
+ *
+ * Lives in its own module (rather than inside execute-cursor/index.ts) so
+ * the LangChain construction path stays out of the Cursor activity's module
+ * graph until a run actually needs tier 2 — index.ts imports this module
+ * lazily at the call site, mirroring its tier-1 import, which is what
+ * bundle-slim's deferred evaluation preserves.
+ */
+
+import type { Config } from "../../config.js";
+import { getEconomyModel } from "../../shared/model-registry.js";
+import { buildChatModel } from "../../shared/model-client.js";
+import { checkDirectCredentials } from "../../shared/llm-backend.js";
+import { tryInferProvider } from "../../shared/llm-proxy.js";
+import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
+
+/**
+ * Extract structured data from an agent's free-text response using an
+ * economy-tier LLM with withStructuredOutput (function-calling).
+ *
+ * Construction (registry-id resolution, provider inference, proxy wiring) is
+ * delegated to the shared buildChatModel so the economy model's registry id
+ * is always resolved to a provider API id before the call.
+ *
+ * Throws when no LLM is reachable (no proxy and no credential path for the
+ * extraction model's provider) — the caller treats any throw here as "tier 2
+ * unavailable", logs it, and returns the agent's text without structured
+ * output, so the failure mode is a diagnosable log line, never a lost run.
+ */
+export async function extractStructuredOutput(
+  agentResponse: string,
+  schema: Record<string, unknown>,
+  config: Config,
+  primaryModel: string,
+): Promise<unknown | null> {
+  const extractionModel = await getEconomyModel(primaryModel);
+  const proxyEndpoint = config.proxyEndpoint ?? undefined;
+
+  if (!proxyEndpoint) {
+    const provider = tryInferProvider(extractionModel);
+    const missing = provider === null ? null : checkDirectCredentials(provider);
+    if (missing !== null) {
+      throw new Error(
+        `Structured-output extraction needs the ${provider} model ` +
+        `'${extractionModel}' but has no credential path. ${missing}`,
+      );
+    }
+  }
+
+  const { model: llm } = await buildChatModel({
+    modelName: extractionModel,
+    proxyEndpoint,
+    stigmerToken: config.stigmerToken ?? undefined,
+    maxTokens: 4096,
+  });
+
+  const zodSchema = jsonSchemaToZod(schema);
+  const structured = llm.withStructuredOutput(zodSchema);
+
+  const result = await structured.invoke([
+    { role: "system", content: "Extract the structured data from the agent's response. Return only the data that matches the schema." },
+    { role: "user", content: agentResponse },
+  ]);
+
+  return result ?? null;
+}