@stigmer/runner 3.11.1-dev.20260812192248 → 3.12.0

package/dist/shared/synthesized-attachment.js

@@ -1,8 +1,8 @@
 /**
  * Shared mechanics of runner-synthesized MCP attachments — the pieces
- * the datastore records attachment (T05) and the channel messaging
- * attachment (proactive-messaging DD-006 D8) have in common, extracted
- * when the second attachment arrived.
+ * the channel messaging attachment (proactive-messaging DD-006 D8) and
+ * the conversation participation attachment (DD-008 D-c) have in
+ * common, extracted when the second attachment arrived.
  *
  * A synthesized attachment is a first-party MCP server entry the runner
  * builds itself (no McpServer resource, no Environment, no credential in
@@ -17,7 +17,7 @@
  * Inject a synthesized attachment into a resolved server list — AFTER
  * resolve + backfill (see the module header). A user server shadowing
  * the reserved slug is replaced, loudly; `label` names the attachment
- * in that warning (e.g. "datastore records").
+ * in that warning (e.g. "channel messaging").
  */
 export function injectSynthesizedAttachment(resolvedServers, attachment, label) {
     const shadowed = resolvedServers.some((s) => s.slug === attachment.slug);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.11.1-dev.20260812192248",
+  "version": "3.12.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -90,7 +90,7 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.11.1-dev.20260812192248",
+    "@stigmer/protos": "3.12.0",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/common": "^1.11.0",
     "@temporalio/interceptors-opentelemetry": "~1.16.0",

package/src/__test-utils__/fake-artifact-storage.ts

@@ -25,12 +25,20 @@ import type { ArtifactStorage } from "../shared/artifact-storage.js";
 
 /** An {@link ArtifactStorage} whose methods are `vi.fn` spies over a shared Map. */
 export type InMemoryArtifactStorage = {
-  [K in keyof ArtifactStorage]: ReturnType<typeof vi.fn>;
+  [K in keyof ArtifactStorage as ArtifactStorage[K] extends (...args: never[]) => unknown
+    ? K
+    : never]: ReturnType<typeof vi.fn>;
 } & ArtifactStorage;
 
 export interface InMemoryArtifactStorageOptions {
   /** Prefix for the URLs `getDownloadUrl` returns. Defaults to `mem://`. */
   readonly urlBase?: string;
+  /**
+   * The URL kind the double self-describes as (attachment-download-urls.ts).
+   * Defaults to "presigned" — the backend whose URLs the hand-off story is
+   * built for; tests exercising the local-serve wording pass "local-serve".
+   */
+  readonly downloadUrlKind?: ArtifactStorage["downloadUrlKind"];
 }
 
 export interface InMemoryArtifactStorageHandle {
@@ -55,6 +63,7 @@ export function makeInMemoryArtifactStorage(
   const blobs = new Map<string, Buffer>();
 
   const storage = {
+    downloadUrlKind: opts.downloadUrlKind ?? "presigned",
     upload: vi.fn(async (key: string, content: Buffer, _contentType?: string) => {
       blobs.set(key, Buffer.from(content));
       return key;

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

@@ -78,7 +78,11 @@ describe("resolveAttachments", () => {
     const result = await resolveAttachments([makeAttachment()], options({ storage }));
 
     expect(result).toEqual([
-      { filename: "plan.md", relativePath: ".stigmer/inputs/plan.md" },
+      {
+        filename: "plan.md",
+        relativePath: ".stigmer/inputs/plan.md",
+        downloadUrl: "mem://attachments/01ABC/plan.md",
+      },
     ]);
     expect(readFileSync(join(platformDir, "inputs", "plan.md"), "utf-8")).toBe("# The Plan");
   });
@@ -130,11 +134,16 @@ describe("resolveAttachments", () => {
     );
 
     expect(result).toEqual([
-      { filename: "report.pdf", relativePath: ".stigmer/inputs/report.pdf" },
+      {
+        filename: "report.pdf",
+        relativePath: ".stigmer/inputs/report.pdf",
+        downloadUrl: "mem://attachments/01AAA/report.pdf",
+      },
       {
         filename: "report-2.pdf",
         relativePath: ".stigmer/inputs/report-2.pdf",
         renamedFrom: "report.pdf",
+        downloadUrl: "mem://attachments/01BBB/report.pdf",
       },
     ]);
     expect(readFileSync(join(platformDir, "inputs", "report.pdf"), "utf-8")).toBe("first bytes");
@@ -155,12 +164,15 @@ describe("resolveAttachments", () => {
       options({ storage }),
     );
 
+    // The key-less local file lists no URL; the storage twin does — the
+    // per-file split the prompt renders.
     expect(result).toEqual([
       { filename: "notes.md", relativePath: ".stigmer/inputs/notes.md" },
       {
         filename: "notes-2.md",
         relativePath: ".stigmer/inputs/notes-2.md",
         renamedFrom: "notes.md",
+        downloadUrl: "mem://attachments/01ABC/notes.md",
       },
     ]);
     expect(readFileSync(join(platformDir, "inputs", "notes.md"), "utf-8")).toBe("local copy");
@@ -225,7 +237,11 @@ describe("resolveAttachments", () => {
     );
 
     expect(result).toEqual([
-      { filename: "evil.md", relativePath: ".stigmer/inputs/evil.md" },
+      {
+        filename: "evil.md",
+        relativePath: ".stigmer/inputs/evil.md",
+        downloadUrl: "mem://attachments/01ABC/x",
+      },
     ]);
     expect(readFileSync(join(platformDir, "inputs", "evil.md"), "utf-8")).toBe("contained");
     // Nothing escaped two levels up (where `../../evil.md` would have landed).
@@ -247,6 +263,50 @@ describe("resolveAttachments", () => {
     expect(readFileSync(join(platformDir, "inputs", "evil.txt"), "utf-8")).toBe("local-contained");
   });
 
+  // ── Download-URL hand-off (issue #532) ───────────────────────────────────
+  // The URL is strictly additive (shared/attachment-download-urls.ts): every
+  // case below also asserts the file materialized exactly as it would
+  // without one.
+
+  describe("download-URL minting during resolution", () => {
+    it("degrades to no URL when the mint fails — file still materialized, turn proceeds", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await storage.upload("attachments/01ABC/plan.md", Buffer.from("# The Plan"), "text/markdown");
+      storage.getDownloadUrl.mockRejectedValueOnce(new Error("presign endpoint unreachable"));
+
+      const result = await resolveAttachments([makeAttachment()], options({ storage }));
+
+      expect(result).toEqual([
+        { filename: "plan.md", relativePath: ".stigmer/inputs/plan.md" },
+      ]);
+      expect(readFileSync(join(platformDir, "inputs", "plan.md"), "utf-8")).toBe("# The Plan");
+    });
+
+    it("mints a URL on the localPath fast path when an uploaded copy also exists", async () => {
+      // The fast path skips storage for the BYTES; the mint rule is
+      // branch-independent, so the uploaded copy still backs the URL.
+      const srcPath = join(workspaceDir, "src.csv");
+      writeFileSync(srcPath, "a,b,c");
+      const { storage } = makeInMemoryArtifactStorage();
+
+      const result = await resolveAttachments(
+        [makeAttachment({ filename: "data.csv", storageKey: "attachments/01ABC/data.csv", localPath: srcPath })],
+        options({ storage }),
+      );
+
+      expect(result).toEqual([
+        {
+          filename: "data.csv",
+          relativePath: ".stigmer/inputs/data.csv",
+          downloadUrl: "mem://attachments/01ABC/data.csv",
+        },
+      ]);
+      // Bytes came off local disk, not storage — the fast path is intact.
+      expect(storage.download).not.toHaveBeenCalled();
+      expect(readFileSync(join(platformDir, "inputs", "data.csv"), "utf-8")).toBe("a,b,c");
+    });
+  });
+
   // ── Vision selection (T04) ────────────────────────────────────────────────
   // Vision is strictly additive: every case below also asserts the file
   // materialized exactly as it would without a budget.

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -9,10 +9,8 @@
 
 import { describe, it, expect } from "vitest";
 import { create } from "@bufbuild/protobuf";
-import { DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 
 import { appendStructuredOutputDirective, buildPrompt, isHitlReinvocation, primarySendCarriesImages } from "../index.js";
 import type { BuildPromptInput } from "../index.js";
@@ -89,33 +87,6 @@ describe("buildPrompt", () => {
     expect(prompt).toContain(USER_MESSAGE);
   });
 
-  it("renders the <available_datastores> section on the first execution (T05)", () => {
-    const prompt = buildPrompt(
-      input({
-        resolution: resolution("local", "created_first_execution"),
-        datastoreUsages: [
-          create(DatastoreUsageSchema, {
-            datastoreRef: create(ApiResourceReferenceSchema, { slug: "clinic" }),
-          }),
-        ],
-      }),
-    );
-    expect(prompt).toContain("<available_datastores>");
-    expect(prompt).toContain("- clinic");
-    expect(prompt).toContain("describe_datastore");
-    // The standing failure-disclosure instruction (issue #325) is this
-    // harness's ONLY outage coverage: the Cursor SDK connects MCP itself,
-    // so the runner can never reconcile the live roster here.
-    expect(prompt).toContain("do not answer from memory");
-  });
-
-  it("omits the datastores section when the agent uses no datastores", () => {
-    const prompt = buildPrompt(
-      input({ resolution: resolution("local", "created_first_execution") }),
-    );
-    expect(prompt).not.toContain("<available_datastores>");
-  });
-
   it("carries the rollover context bridge on the first execution (DD-013)", () => {
     const prompt = buildPrompt(
       input({
@@ -454,6 +425,68 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     expect(prompt).toContain("Attached inline and visible to you, in order: 1. a.jpg");
   });
 
+  it("lists a minted download URL beside its file with the presigned hand-off line (issue #532)", () => {
+    const prompt = buildPrompt(
+      input({
+        ...RESUMED,
+        attachments: [
+          { path: ".stigmer/inputs/lease.pdf", downloadUrl: "https://r2.example/lease?sig=abc" },
+          { path: ".stigmer/inputs/notes.md" },
+        ],
+        downloadUrlKind: "presigned",
+      }),
+    );
+    expect(prompt).toContain(
+      "- `.stigmer/inputs/lease.pdf` — download URL: https://r2.example/lease?sig=abc",
+    );
+    // The URL-less file keeps a clean entry.
+    expect(prompt).toContain("- `.stigmer/inputs/notes.md`\n");
+    expect(prompt).toContain("These URLs are time-limited");
+  });
+
+  it("words a local-serve URL honestly — reachable only from this machine", () => {
+    const prompt = buildPrompt(
+      input({
+        ...RESUMED,
+        attachments: [
+          { path: ".stigmer/inputs/lease.pdf", downloadUrl: "http://localhost:7235/attachments/01A/lease.pdf" },
+        ],
+        downloadUrlKind: "local-serve",
+      }),
+    );
+    expect(prompt).toContain("download URL: http://localhost:7235/attachments/01A/lease.pdf");
+    expect(prompt).toContain("reachable only from this machine");
+    expect(prompt).not.toContain("time-limited");
+  });
+
+  it("renders no hand-off line when no listed file carries a URL (kind alone is not enough)", () => {
+    const prompt = buildPrompt(
+      input({
+        ...RESUMED,
+        attachments: [{ path: ".stigmer/inputs/local-only.csv" }],
+        downloadUrlKind: "presigned",
+      }),
+    );
+    expect(prompt).toContain("<input_files>");
+    expect(prompt).not.toContain("download URL");
+    expect(prompt).not.toContain("time-limited");
+  });
+
+  it("renders the download URL inside the enhanced first-turn prompt too", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        attachments: [
+          { path: ".stigmer/inputs/lease.pdf", downloadUrl: "https://r2.example/lease?sig=abc" },
+        ],
+        downloadUrlKind: "presigned",
+      }),
+    );
+    expect(prompt).toContain("<input_files>");
+    expect(prompt).toContain("download URL: https://r2.example/lease?sig=abc");
+    expect(prompt).toContain("These URLs are time-limited");
+  });
+
   it("a HITL re-invocation carries no input-files section — its prompt has no user message at all", () => {
     const prompt = buildPrompt(
       input({

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/index.ts

@@ -72,7 +72,6 @@ import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/stre
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
 import { resolveMcpServers, toCursorMcpConfig, validateMcpServerEnv } from "./mcp-resolver.js";
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
-import { synthesizeDatastoreAttachment } from "../../shared/datastore-attachment.js";
 import {
   discoverChannelMessaging,
   synthesizeChannelAttachment,
@@ -665,35 +664,16 @@ async function executeCursorInner(
       ?? config.stigmerTokenRef?.current
       ?? config.stigmerToken;
 
-    // Phase 4a2: Synthesize the datastore records attachment (T05).
-    // Deliberately AFTER resolve + backfill: the attachment has no
-    // McpServerUsage and reports discovered capabilities, so the
-    // backfill's destructiveHint tightener can never force-gate
-    // delete_record (which on channels would be silently skipped).
-    // Empty approval maps keep it approval-free by construction.
-    if (blueprint.datastoreUsages.length > 0) {
-      const attachment = synthesizeDatastoreAttachment(blueprint.datastoreUsages, {
-        bridgeEndpoint: config.mcpBridgeEndpoint,
-        credential: attachmentCredential,
-        backendEndpoint: config.stigmerBackendEndpoint,
-      });
-      if (attachment) {
-        const resolvedServers = injectSynthesizedAttachment(
-          mcpResolution.resolvedServers, attachment, "datastore records",
-        );
-        mcpResolution = {
-          resolvedServers,
-          cursorConfig: toCursorMcpConfig(resolvedServers),
-        };
-      }
-    }
-
-    // Phase 4a3: Synthesize the channel messaging attachment (DD-006
-    // D7/D8), the records attachment's twin. The discovery read is the
-    // attachment decision — the control plane runs the SAME candidate
-    // computation the send authorization uses — and every failure mode
-    // (no channel, OSS, registry down, pre-3a control plane) degrades
-    // to honest absence: no tool, no section, execution unharmed.
+    // Phase 4a2: Synthesize the channel messaging attachment (DD-006
+    // D7/D8). Deliberately AFTER resolve + backfill: the attachment has
+    // no McpServerUsage and reports discovered capabilities, so the
+    // backfill's destructiveHint tightener can never force-gate its
+    // tools; empty approval maps keep it approval-free by construction.
+    // The discovery read is the attachment decision — the control plane
+    // runs the SAME candidate computation the send authorization uses —
+    // and every failure mode (no channel, OSS, registry down, pre-3a
+    // control plane) degrades to honest absence: no tool, no section,
+    // execution unharmed.
     const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
     if (channelMessaging.length > 0) {
       const attachment = synthesizeChannelAttachment(channelMessaging, {
@@ -802,6 +782,7 @@ async function executeCursorInner(
     const attachmentEntries = attachmentResults.map((a) => ({
       path: a.relativePath,
       ...(a.renamedFrom !== undefined ? { renamedFrom: a.renamedFrom } : {}),
+      ...(a.downloadUrl !== undefined ? { downloadUrl: a.downloadUrl } : {}),
     }));
     // Vision facts, derived once from the single resolution result: the
     // images the model will see inline (in attachment order) and the ones
@@ -1147,13 +1128,13 @@ async function executeCursorInner(
       instructions: blueprint.instructions,
       userMessage: spec.message,
       skills: skillMetadata,
-      datastoreUsages: blueprint.datastoreUsages,
       channelMessaging,
       subAgents: blueprint.subAgents,
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
       attachments: attachmentEntries,
       vision: visionPromptInfo,
+      downloadUrlKind: artifactStorage?.downloadUrlKind,
       pendingApprovals: adjudicatedApprovals,
       appliedToolCallIds,
       interactionMode,
@@ -1821,13 +1802,13 @@ async function executeCursorInner(
             instructions: blueprint.instructions,
             userMessage: spec.message,
             skills: skillMetadata,
-            datastoreUsages: blueprint.datastoreUsages,
             channelMessaging,
             subAgents: blueprint.subAgents,
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
             attachments: attachmentEntries,
             vision: visionPromptInfo,
+            downloadUrlKind: artifactStorage?.downloadUrlKind,
             pendingApprovals: adjudicatedApprovals,
             // Without the applied set, the HITL-recovery prompt would tell
             // the fresh agent to carry out writes the runner already
@@ -2367,8 +2348,6 @@ export interface BuildPromptInput {
   instructions: string;
   userMessage: string;
   skills: import("./prompt-builder.js").SkillMetadata[];
-  /** Datastores attached via `datastore_usages` — the `<available_datastores>` section. */
-  datastoreUsages?: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").DatastoreUsage[];
   /**
    * Serving proactive channels + their templates (the DD-006 D2
    * discovery read) — the `<available_channel_templates>` section.
@@ -2388,6 +2367,12 @@ export interface BuildPromptInput {
    * catchup — it rides both the enhanced prompt and a resumed turn's prefix.
    */
   vision?: import("./prompt-builder.js").VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints (issue #532) — keys
+   * the input-files hand-off wording. Sourced from the resolved
+   * artifactStorage's self-description; absent when no storage resolved.
+   */
+  downloadUrlKind?: import("../../shared/attachment-download-urls.js").DownloadUrlKind;
   pendingApprovals: import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb").PendingApproval[];
   /**
    * Approved whole-file writes the runner already applied itself (exact-apply).
@@ -2546,13 +2531,13 @@ export function buildPrompt(input: BuildPromptInput): string {
           instructions,
           userMessage,
           skills,
-          datastoreUsages: input.datastoreUsages ?? [],
           channelMessaging: input.channelMessaging ?? [],
           subAgents,
           workspaceDirs,
           workspaceFileRefs,
           attachments,
           vision: input.vision,
+          downloadUrlKind: input.downloadUrlKind,
           interactionMode,
           buildFromPlan,
           contextBridge: input.contextBridge,
@@ -2594,7 +2579,7 @@ export function buildPrompt(input: BuildPromptInput): string {
       formatInteractionModePrefix(interactionMode),
       formatImplementPlanSection(buildFromPlan, attachments),
       attachments.length > 0
-        ? formatInputFiles(attachments, input.vision)
+        ? formatInputFiles(attachments, input.vision, input.downloadUrlKind)
         : undefined,
       conversationCatchup !== undefined
         ? formatConversationCatchupSection(conversationCatchup)
@@ -2612,13 +2597,13 @@ export function buildPrompt(input: BuildPromptInput): string {
     instructions,
     userMessage,
     skills,
-    datastoreUsages: input.datastoreUsages ?? [],
     channelMessaging: input.channelMessaging ?? [],
     subAgents,
     workspaceDirs,
     workspaceFileRefs,
     attachments,
     vision: input.vision,
+    downloadUrlKind: input.downloadUrlKind,
     interactionMode,
     buildFromPlan,
     contextBridge: input.contextBridge,

package/src/activities/execute-cursor/prompt-builder.ts

@@ -17,12 +17,11 @@
  */
 
 import { resolve } from "node:path";
-import type { DatastoreUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { formatContextBridgeText } from "../../shared/context-bridge.js";
 import { formatConversationCatchupText } from "../../shared/conversation-catchup.js";
-import { formatDatastoresSection } from "../../shared/datastore-attachment.js";
 import {
   formatChannelTemplatesSection,
   type ChannelMessagingInfo,
@@ -36,6 +35,10 @@ import {
   visionDisclosureLines,
   type NotViewableEntry,
 } from "../../shared/attachment-vision.js";
+import {
+  downloadUrlDisclosureLine,
+  type DownloadUrlKind,
+} from "../../shared/attachment-download-urls.js";
 import { formatTurnRecoveryText } from "./turn-recovery.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
@@ -82,21 +85,18 @@ export interface AttachmentPromptEntry {
   path: string;
   /** Original filename, present only when a duplicate name was renamed. */
   renamedFrom?: string;
+  /**
+   * Download URL for the attachment's stored object, when one was minted
+   * (shared/attachment-download-urls.ts) — rendered beside the path so the
+   * agent can hand the file to tools that cannot read this filesystem.
+   */
+  downloadUrl?: string;
 }
 
 export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
   skills: SkillMetadata[];
-  /**
-   * Datastores attached via `datastore_usages` — rendered as the
-   * `<available_datastores>` section (DD-005 SD-5, skills precedent)
-   * pointing the model at the synthesized record tools. Always the healthy
-   * rendering here: the Cursor SDK connects MCP itself, so this harness can
-   * never observe the live roster — the section's standing
-   * failure-disclosure instruction is its whole coverage (issue #325).
-   */
-  datastoreUsages?: DatastoreUsage[];
   /**
    * Serving proactive channels + their approved templates — rendered as
    * the `<available_channel_templates>` section (proactive-messaging
@@ -109,6 +109,12 @@ export interface EnhancedPromptOptions {
   attachments: AttachmentPromptEntry[];
   /** Inline/degraded image facts for the input-files section (T04 vision). */
   vision?: VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints — keys the input-files
+   * section's hand-off wording (attachment-download-urls.ts). One turn-level
+   * fact: all attachments ride the one configured storage.
+   */
+  downloadUrlKind?: DownloadUrlKind;
   interactionMode?: InteractionMode;
   /**
    * The execution is a Build-from-plan turn (spec.execution_config
@@ -183,10 +189,6 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatSkillsSection(options.skills));
   }
 
-  if (options.datastoreUsages !== undefined && options.datastoreUsages.length > 0) {
-    sections.push(formatDatastoresSection(options.datastoreUsages));
-  }
-
   if (options.channelMessaging !== undefined && options.channelMessaging.length > 0) {
     // "" when nothing is sendable — the tool alone still serves text
     // sends inside a 24-hour window (DD-006 D6).
@@ -212,7 +214,7 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
   }
 
   if (options.attachments.length > 0) {
-    sections.push(formatInputFiles(options.attachments, options.vision));
+    sections.push(formatInputFiles(options.attachments, options.vision, options.downloadUrlKind));
   }
 
   if (options.workspaceFileRefs.length > 0) {
@@ -548,15 +550,28 @@ export function formatWorkspaceContext(dirs: string[]): string {
 export function formatInputFiles(
   attachments: readonly AttachmentPromptEntry[],
   vision?: VisionPromptInfo,
+  downloadUrlKind?: DownloadUrlKind,
 ): string {
   // A duplicate-renamed file (attachment-naming.ts) discloses its original
   // name so the agent can connect "the two report.pdfs" in the user's
-  // message to distinct files on disk.
-  const entries = attachments.map((a) =>
-    a.renamedFrom !== undefined
-      ? `- \`${a.path}\` (renamed from duplicate '${a.renamedFrom}')`
-      : `- \`${a.path}\``,
-  );
+  // message to distinct files on disk. A file with a minted download URL
+  // (attachment-download-urls.ts) lists it beside the path for the remote
+  // hand-off story.
+  const entries = attachments.map((a) => {
+    const rename =
+      a.renamedFrom !== undefined
+        ? ` (renamed from duplicate '${a.renamedFrom}')`
+        : "";
+    const url = a.downloadUrl !== undefined ? ` — download URL: ${a.downloadUrl}` : "";
+    return `- \`${a.path}\`${rename}${url}`;
+  });
+  // The URL hand-off line (shared wording, attachment-download-urls.ts)
+  // renders only when some listed file actually carries a URL — its wording
+  // keys on what kind of URL the storage backend mints.
+  const urlDisclosure =
+    downloadUrlKind !== undefined && attachments.some((a) => a.downloadUrl !== undefined)
+      ? [downloadUrlDisclosureLine(downloadUrlKind)]
+      : [];
   // The vision lines (shared wording, attachment-vision.ts) tell the model
   // which of these files it can already SEE inline versus which degraded to
   // path-only — without them an agent silently ignores a photo the user
@@ -568,6 +583,7 @@ export function formatInputFiles(
     "<input_files>",
     "The following files have been provided as inputs. Read them when relevant to the task:",
     ...entries,
+    ...urlDisclosure,
     ...disclosure,
     "</input_files>",
   ].join("\n");