@stigmer/runner 3.11.0 → 3.12.0

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/attachment-resolver.ts

@@ -40,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 { mintAttachmentDownloadUrl } from "../../shared/attachment-download-urls.js";
 import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import {
   isVisionCandidate,
@@ -73,6 +74,17 @@ export interface ResolvedAttachment {
    * Attachments that were never image-shaped carry neither field.
    */
   visionDegraded?: VisionDegradedReason;
+  /**
+   * A download URL for the attachment's stored object, listed in the prompt's
+   * `<input_files>` section so the agent can hand the file to a tool whose
+   * backend cannot read the sandbox filesystem (issue #532). Minted whenever
+   * the attachment has a `storageKey` and a usable storage — including on the
+   * localPath fast path when an uploaded copy also exists. Absent when there
+   * is nothing to mint or the mint failed (non-fatal — the policy, the
+   * degrade log, and the prompt wording all live in
+   * shared/attachment-download-urls.ts).
+   */
+  downloadUrl?: string;
 }
 
 export interface AttachmentResolverOptions {
@@ -165,11 +177,18 @@ async function resolveAttachment(
         `${err instanceof Error ? err.message : String(err)}`,
       );
     }
+    // The fast path skips storage for the BYTES, but an uploaded copy (an
+    // attachment carrying both localPath and storageKey) still supports the
+    // URL hand-off — the mint rule is branch-independent.
+    const downloadUrl = await mintAttachmentDownloadUrl(
+      options.storage, attachment.storageKey, filename,
+    );
     return {
       filename,
       relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
       ...(renamedFrom !== undefined ? { renamedFrom } : {}),
       ...visionOutcomeFields(vision),
+      ...(downloadUrl !== undefined ? { downloadUrl } : {}),
     };
   }
 
@@ -209,11 +228,16 @@ async function resolveAttachment(
   // no pre-filter needed on this branch).
   const vision = options.visionBudget?.offer(filename, attachment.contentType, content);
 
+  const downloadUrl = await mintAttachmentDownloadUrl(
+    options.storage, attachment.storageKey, filename,
+  );
+
   return {
     filename,
     relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
     ...(renamedFrom !== undefined ? { renamedFrom } : {}),
     ...visionOutcomeFields(vision),
+    ...(downloadUrl !== undefined ? { downloadUrl } : {}),
   };
 }
 

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

@@ -14,7 +14,7 @@
 import { resolve } from "node:path";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
-import type { AgentSpec, DatastoreUsage, McpServerUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { AgentSpec, McpServerUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
@@ -46,14 +46,6 @@ export interface ResolvedBlueprint {
   subAgents: SubAgent[];
   mergedMcpServerUsages: McpServerUsage[];
   mergedSkillRefs: ApiResourceReference[];
-  /**
-   * The agent's datastore usages (AgentSpec only — sessions carry no
-   * datastore overlay by design: the usage edge is authorization-bearing
-   * for the server's reach chain, DD-006, so it binds per-blueprint).
-   * Non-empty triggers the synthesized records attachment
-   * (shared/datastore-attachment.ts).
-   */
-  datastoreUsages: DatastoreUsage[];
   workspaceDirs: string[];
   cloudRepos: CloudRepo[];
 }
@@ -98,7 +90,6 @@ export async function resolveBlueprint(
     subAgents: agentSpec.subAgents,
     mergedMcpServerUsages,
     mergedSkillRefs,
-    datastoreUsages: agentSpec.datastoreUsages,
     workspaceDirs,
     cloudRepos,
   };

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

@@ -131,6 +131,29 @@ function extractFromCandidate(v: unknown): RunErrorSources | undefined {
   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",
@@ -317,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",
     };
@@ -332,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",
   };
 }