@stigmer/runner 3.11.1-dev.20260812192248 → 3.12.0

package/src/shared/__tests__/attachment-download-urls.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for the attachment download-URL hand-off policy (issue #532):
+ * the branch-independent mint rule, the non-fatal degrade, and the
+ * per-kind disclosure wording both harnesses embed.
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import {
+  mintAttachmentDownloadUrl,
+  downloadUrlDisclosureLine,
+} from "../attachment-download-urls.js";
+import { makeInMemoryArtifactStorage } from "../../__test-utils__/fake-artifact-storage.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("mintAttachmentDownloadUrl", () => {
+  it("mints a URL for a storage key", async () => {
+    const { storage } = makeInMemoryArtifactStorage();
+
+    const url = await mintAttachmentDownloadUrl(storage, "attachments/01A/lease.pdf", "lease.pdf");
+
+    expect(url).toBe("mem://attachments/01A/lease.pdf");
+  });
+
+  it("returns undefined when the attachment has no storage key", async () => {
+    const { storage } = makeInMemoryArtifactStorage();
+
+    const url = await mintAttachmentDownloadUrl(storage, "", "local.csv");
+
+    expect(url).toBeUndefined();
+    expect(storage.getDownloadUrl).not.toHaveBeenCalled();
+  });
+
+  it("returns undefined when no storage is available", async () => {
+    const url = await mintAttachmentDownloadUrl(undefined, "attachments/01A/lease.pdf", "lease.pdf");
+
+    expect(url).toBeUndefined();
+  });
+
+  it("degrades to undefined on a mint failure and logs the degrade (never throws)", async () => {
+    const { storage } = makeInMemoryArtifactStorage();
+    storage.getDownloadUrl.mockRejectedValueOnce(new Error("presign endpoint unreachable"));
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const url = await mintAttachmentDownloadUrl(storage, "attachments/01A/lease.pdf", "lease.pdf");
+
+    expect(url).toBeUndefined();
+    expect(warn).toHaveBeenCalledOnce();
+    expect(warn.mock.calls[0][0]).toContain("lease.pdf");
+  });
+});
+
+describe("downloadUrlDisclosureLine", () => {
+  it("promises time-limited single-object access for presigned URLs", () => {
+    const line = downloadUrlDisclosureLine("presigned");
+
+    expect(line).toContain("time-limited");
+    expect(line).toContain("single file");
+    expect(line).not.toContain("this machine");
+  });
+
+  it("is honest about local-serve reach — same machine only, no expiry claim", () => {
+    const line = downloadUrlDisclosureLine("local-serve");
+
+    expect(line).toContain("reachable only from this machine");
+    expect(line).not.toContain("time-limited");
+  });
+});

package/src/shared/__tests__/channel-attachment.test.ts

@@ -1,8 +1,8 @@
 /**
  * The channel messaging attachment (proactive-messaging DD-006 D7/D8):
  * discovery with the never-throw failure posture, both connection
- * shapes, the structural approval-freedom the datastore attachment
- * pinned before it, and the prompt section's filter/order/cap rules
+ * shapes, the structural approval-freedom of synthesized attachments,
+ * and the prompt section's filter/order/cap rules
  * (DD-006 D6). The route is the cross-repo string, guarded here and in
  * the mcp-server integration test (the TOOL_CALL_LIMIT precedent); the
  * slug and roster are runner-internal and guarded here alone.

package/src/shared/__tests__/synthesized-attachment.test.ts

@@ -1,17 +1,14 @@
 /**
- * Composition of ALL THREE synthesized attachments through
- * injectSynthesizedAttachment — the first test to chain them the way
- * both harness call sites do (datastore, then channels, then
- * conversation, each after resolve + backfill). Per-slug independence
- * is the property that makes a third attachment safe to add: replacing
- * one reserved slug must never disturb its siblings.
+ * Composition of the synthesized attachments through
+ * injectSynthesizedAttachment — chained the way both harness call sites
+ * do (channels, then conversation, each after resolve + backfill).
+ * Per-slug independence is the property that makes another attachment
+ * safe to add: replacing one reserved slug must never disturb its
+ * siblings.
  */
 
 import { describe, expect, it, vi } from "vitest";
 import type { MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
-import { create } from "@bufbuild/protobuf";
-import { DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 
 import {
   CHANNEL_ATTACHMENT_SLUG,
@@ -21,10 +18,6 @@ import {
   CONVERSATION_ATTACHMENT_SLUG,
   synthesizeConversationAttachment,
 } from "../conversation-attachment.js";
-import {
-  DATASTORE_ATTACHMENT_SLUG,
-  synthesizeDatastoreAttachment,
-} from "../datastore-attachment.js";
 import { injectSynthesizedAttachment } from "../synthesized-attachment.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
 
@@ -44,47 +37,34 @@ const userServer: ResolvedMcpServer = {
   discoveredCapabilitiesEmpty: false,
 };
 
-function allThree(): ResolvedMcpServer[] {
-  const datastore = synthesizeDatastoreAttachment(
-    [create(DatastoreUsageSchema, {
-      datastoreRef: create(ApiResourceReferenceSchema, { slug: "clinic" }),
-    })],
-    options,
-  )!;
+function bothAttachments(): ResolvedMcpServer[] {
   const channels = synthesizeChannelAttachment(
     [{ channel: { channel: "isc-whatsapp", provider: "whatsapp" } as MessagingChannel, templates: [] }],
     options,
   )!;
   const conversation = synthesizeConversationAttachment("agch_1", options)!;
 
-  // The harness order at both call sites: datastore, channels, conversation.
-  let servers = injectSynthesizedAttachment([userServer], datastore, "datastore records");
-  servers = injectSynthesizedAttachment(servers, channels, "channel messaging");
+  // The harness order at both call sites: channels, then conversation.
+  let servers = injectSynthesizedAttachment([userServer], channels, "channel messaging");
   return injectSynthesizedAttachment(servers, conversation, "conversation participation");
 }
 
-describe("three synthesized attachments in one chain", () => {
-  it("composes all three after the user's servers, in injection order", () => {
-    expect(allThree().map((s) => s.slug)).toEqual([
+describe("synthesized attachments in one chain", () => {
+  it("composes after the user's servers, in injection order", () => {
+    expect(bothAttachments().map((s) => s.slug)).toEqual([
       "github",
-      DATASTORE_ATTACHMENT_SLUG,
       CHANNEL_ATTACHMENT_SLUG,
       CONVERSATION_ATTACHMENT_SLUG,
     ]);
   });
 
   it("each rides its own bridge route with the shared credential", () => {
-    const bySlug = new Map(allThree().map((s) => [s.slug, s]));
-    expect(bySlug.get(DATASTORE_ATTACHMENT_SLUG)?.url).toBe("https://mcp.stigmer.ai/records");
+    const bySlug = new Map(bothAttachments().map((s) => [s.slug, s]));
     expect(bySlug.get(CHANNEL_ATTACHMENT_SLUG)?.url).toBe("https://mcp.stigmer.ai/channels");
     expect(bySlug.get(CONVERSATION_ATTACHMENT_SLUG)?.url).toBe(
       "https://mcp.stigmer.ai/conversation",
     );
-    for (const slug of [
-      DATASTORE_ATTACHMENT_SLUG,
-      CHANNEL_ATTACHMENT_SLUG,
-      CONVERSATION_ATTACHMENT_SLUG,
-    ]) {
+    for (const slug of [CHANNEL_ATTACHMENT_SLUG, CONVERSATION_ATTACHMENT_SLUG]) {
       expect(bySlug.get(slug)?.headers).toEqual({ Authorization: "Bearer sandbox-token" });
     }
   });
@@ -96,20 +76,18 @@ describe("three synthesized attachments in one chain", () => {
       slug: CONVERSATION_ATTACHMENT_SLUG,
       url: "https://evil.example.com",
     };
-    const conversation = synthesizeConversationAttachment("agch_1", options)!;
-    const datastore = synthesizeDatastoreAttachment(
-      [create(DatastoreUsageSchema, {
-        datastoreRef: create(ApiResourceReferenceSchema, { slug: "clinic" }),
-      })],
+    const channels = synthesizeChannelAttachment(
+      [{ channel: { channel: "isc-whatsapp", provider: "whatsapp" } as MessagingChannel, templates: [] }],
       options,
     )!;
+    const conversation = synthesizeConversationAttachment("agch_1", options)!;
 
-    let servers = injectSynthesizedAttachment([impostor, userServer], datastore, "datastore records");
+    let servers = injectSynthesizedAttachment([impostor, userServer], channels, "channel messaging");
     servers = injectSynthesizedAttachment(servers, conversation, "conversation participation");
 
     expect(servers.map((s) => s.slug)).toEqual([
       "github",
-      DATASTORE_ATTACHMENT_SLUG,
+      CHANNEL_ATTACHMENT_SLUG,
       CONVERSATION_ATTACHMENT_SLUG,
     ]);
     expect(servers.find((s) => s.slug === CONVERSATION_ATTACHMENT_SLUG)?.url).toBe(

package/src/shared/artifact-storage.ts

@@ -31,6 +31,15 @@ import { fetchWithRetry, type FetchRetryPolicy } from "./http-retry.js";
 // ── Interface ────────────────────────────────────────────────────────
 
 export interface ArtifactStorage {
+  /**
+   * What kind of URL {@link getDownloadUrl} mints — self-described by the
+   * backend so consumers (the attachment hand-off prompt wording,
+   * attachment-download-urls.ts) can never disagree with the storage actually
+   * in use. "presigned": time-limited, single-object, remotely fetchable.
+   * "local-serve": the stigmer-server's unauthenticated loopback serve URL,
+   * reachable only from this machine.
+   */
+  readonly downloadUrlKind: "presigned" | "local-serve";
   upload(key: string, content: Buffer, contentType?: string): Promise<string>;
   getDownloadUrl(key: string): Promise<string>;
   /**
@@ -52,6 +61,7 @@ export type ArtifactStorageType = "local" | "proxy";
 // ── Local Backend ────────────────────────────────────────────────────
 
 export class LocalArtifactStorage implements ArtifactStorage {
+  readonly downloadUrlKind = "local-serve" as const;
   private readonly basePath: string;
   private readonly serveUrlBase: string;
 
@@ -153,6 +163,7 @@ const DEFAULT_RETRY = {
 } as const;
 
 export class ProxyArtifactStorage implements ArtifactStorage {
+  readonly downloadUrlKind = "presigned" as const;
   private readonly baseUrl: string;
   private readonly authTokenSource: ProxyAuthTokenSource;
   /** Governs the proxy presign calls and the exists probe. */

package/src/shared/attachment-download-urls.ts

@@ -0,0 +1,98 @@
+/**
+ * Download-URL hand-off for execution attachments (issue #532) — the single
+ * owner of the mint policy and the prompt wording that lets an agent pass an
+ * attachment to a tool whose backend cannot read the sandbox filesystem.
+ *
+ * Both harnesses (Cursor and deep-agent) materialize attachments to disk and
+ * list the workspace paths in their input-files prompt section; that story is
+ * unchanged and this module never touches it. What this module adds is the
+ * *remote hand-off* story: a per-attachment download URL, minted from the
+ * artifact storage the runner already downloads through, surfaced beside the
+ * path so the model can quote a short URL string in a tool-call argument
+ * instead of the impossible alternative (base64 through the model caps out in
+ * the tens of KB; real attachments run 2–8 MB).
+ *
+ * Mint rule: any attachment with a `storageKey` and a usable storage gets a
+ * URL, regardless of which branch materialized the bytes — this covers the
+ * local-mode fast path when an uploaded copy also exists. Attachments with no
+ * storage key (pure CLI-local files) and extracted ZIP entries (no
+ * attachment-level object) get no URL, and their listing is unchanged.
+ *
+ * Failure is non-fatal and silent in the prompt: the file IS materialized —
+ * only the remote hand-off affordance is absent — so a presign hiccup must
+ * not abort a turn the way a missing input does (the resolver/injector
+ * fail-hard doctrine covers inputs, not affordances). This mirrors how vision
+ * delivery degrades without killing materialization. The degrade is logged;
+ * the URL value itself is never logged (a presigned URL in the log pipeline
+ * would outlive its purpose).
+ *
+ * What the URL actually is depends on the storage backend, and the prompt
+ * must not overpromise: proxy storage mints genuinely presigned, time-limited,
+ * single-object URLs a remote service can fetch; local storage returns the
+ * stigmer-server's loopback serve URL, which only same-machine tools can
+ * reach. The backend self-describes via {@link ArtifactStorage.downloadUrlKind}
+ * and {@link downloadUrlDisclosureLine} words each kind honestly.
+ */
+
+import type { ArtifactStorage } from "./artifact-storage.js";
+
+/**
+ * What kind of URL a storage backend's `getDownloadUrl` mints. A property of
+ * the backend, not of the runner's execution mode: storage follows transport
+ * (see loadArtifactStorageConfig), so a local desktop runner on a cloud proxy
+ * mints real presigned URLs.
+ */
+export type DownloadUrlKind = "presigned" | "local-serve";
+
+/**
+ * Mint a download URL for one attachment, or `undefined` when there is
+ * nothing to mint (no key / no storage) or the mint fails (logged, non-fatal
+ * — see module doc). The caller spreads the result into its per-attachment
+ * record with the conditional-spread convention, so an unminted URL leaves no
+ * field behind.
+ */
+export async function mintAttachmentDownloadUrl(
+  storage: ArtifactStorage | undefined,
+  storageKey: string,
+  filename: string,
+): Promise<string | undefined> {
+  if (!storageKey || !storage) return undefined;
+  try {
+    return await storage.getDownloadUrl(storageKey);
+  } catch (err) {
+    console.warn(
+      `[attachment-download-urls] could not mint a download URL for ` +
+      `'${filename}' (key: ${storageKey}) — the file is materialized and the ` +
+      `turn proceeds without one: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * The shared hand-off wording both harnesses embed into their input-files
+ * prompt section when at least one listed file carries a download URL (each
+ * wraps it in its own section framing). Kept here so the two prompts never
+ * drift apart in what they promise the agent.
+ *
+ * Each kind is worded to its real capability. "Time-limited" is deliberately
+ * unquantified: the presign TTL belongs to the serving side (the cloud
+ * proxy's constant today) and hardcoding it here would silently drift.
+ */
+export function downloadUrlDisclosureLine(kind: DownloadUrlKind): string {
+  switch (kind) {
+    case "presigned":
+      return (
+        "Where a file lists a download URL, you can pass that URL to tools " +
+        "whose backends cannot read this workspace's filesystem (e.g. remote " +
+        "services) — the tool fetches the file's contents itself. These URLs " +
+        "are time-limited and each grants access to its single file only."
+      );
+    case "local-serve":
+      return (
+        "Where a file lists a download URL, it is served by the local Stigmer " +
+        "server and is reachable only from this machine — tools running on " +
+        "this machine can fetch it, but remote services cannot."
+      );
+  }
+}

package/src/shared/channel-attachment.ts

@@ -1,6 +1,6 @@
 /**
  * The runner-synthesized channel messaging attachment (proactive-messaging
- * DD-006 D7/D8) — the datastore records attachment's structural twin.
+ * DD-006 D7/D8).
  *
  * When the control plane says an agent serves at least one
  * proactive-messaging channel (the `listMessagingChannels` discovery

package/src/shared/conversation-attachment.ts

@@ -1,8 +1,7 @@
 /**
  * The runner-synthesized conversation participation attachment
- * (channel-conversations DD-008 D-c, A14) — the third synthesized
- * attachment, on the datastore module's shape (a cheap local predicate,
- * not the channel module's discovery machinery).
+ * (channel-conversations DD-008 D-c, A14) — a cheap local predicate,
+ * not the channel module's discovery machinery.
  *
  * When the session IS a live channel conversation, the runner
  * synthesizes ONE MCP attachment serving `escalate_to_human`, so the

package/src/shared/mcp-transport-guard.ts

@@ -60,8 +60,8 @@ export function resolveMcpTransportPosture(
 /**
  * Assert that a resolved MCP server's transport is allowed under the given
  * posture. Applies only to user-defined McpServer resources flowing through
- * the resolvers — the internal datastore attachment is synthesized
- * separately and is already HTTP in cloud mode.
+ * the resolvers — the internal synthesized attachments are built
+ * separately and are already HTTP in cloud mode.
  *
  * @throws McpTransportError when the posture forbids stdio and the server uses it
  */

package/src/shared/synthesized-attachment.ts

@@ -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
@@ -44,7 +44,7 @@ export interface SynthesizedAttachmentOptions {
  * 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: ResolvedMcpServer[],

package/dist/shared/datastore-attachment.d.ts

@@ -1,99 +0,0 @@
-/**
- * The runner-synthesized datastore records attachment (T05, DD-001 SD-2).
- *
- * When an agent declares `datastore_usages`, the runner synthesizes ONE
- * MCP attachment serving the five record tools (DD-005) — the agent
- * builder writes a usage line and gets tools; no McpServer resource, no
- * Environment, no credential in any manifest. Harness-agnostic like
- * mcp-resolver.ts: both ExecuteCursor and ExecuteDeepAgent inject the
- * synthesized entry through their existing ResolvedMcpServer paths.
- *
- * Two connection shapes, one roster (the bridge's records-only roster,
- * T05 R1):
- *   - Bridge endpoint configured (cloud): Streamable HTTP against the
- *     bridge's /records route, with the execution's own session-scoped
- *     credential as the Bearer token — the server's reach chain (DD-006
- *     Path 1) authorizes from that token; the bridge stays a
- *     non-validating passthrough.
- *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
- *     stdio child with STIGMER_MCP_ROSTER=records against the local
- *     backend (zero new distribution — the CLI already embeds the
- *     bridge). No credential: the local backend is unauthenticated and
- *     OSS callers resolve as the local principal (T05 R2).
- *
- * Approval-free by construction (DD-001 SD-3): empty toolApprovals +
- * pinnedToolApprovals + toolApprovalOverrides mean mergeApprovalPolicies
- * emits no entries for this server — zero classifier involvement, and no
- * proto surface can target it (the attachment has no McpServerUsage, and
- * since issue #349 an agent's overrides are scoped to their own usage's
- * server, so a same-named override elsewhere cannot reach this one).
- * `discoveredCapabilitiesEmpty`
- * is false and the attachment has no McpServerUsage, so the connect
- * backfill (whose destructiveHint tightener would force-gate
- * delete_record — silently skipped on channels under UNATTENDED mode)
- * is structurally unable to touch it. Callers must still inject AFTER
- * resolve + backfill; both harness call sites do.
- */
-import type { DatastoreUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import type { ResolvedMcpServer } from "./mcp-resolver.js";
-import { type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
-/**
- * The synthesized attachment's slug. Reserved: a user McpServer with
- * this slug is shadowed by the synthesized attachment (the record tools
- * must exist whenever `datastore_usages` says so), with a warning.
- */
-export declare const DATASTORE_ATTACHMENT_SLUG = "stigmer-records";
-/** The bridge route serving the records-only roster (mcp-server T05 R1). */
-export declare const RECORDS_ROUTE = "/records";
-/**
- * Synthesize the records attachment for an agent's datastore usages.
- * Returns undefined when the agent uses no datastores — the attachment
- * exists exactly when the usage edge does.
- */
-export declare function synthesizeDatastoreAttachment(datastoreUsages: DatastoreUsage[], options: SynthesizedAttachmentOptions): ResolvedMcpServer | undefined;
-/**
- * The five record tools the records roster always serves (DD-005; the
- * mcp-server's records roster registers all five unconditionally for the
- * agent audience — only the `org` argument shape varies by audience, see
- * mcp-server/src/domains/records/tools.ts). Because the roster never
- * legitimately narrows, any of these missing from the connected toolset
- * means the store is degraded (issue #325) — the prompt section and the
- * reconciliation both derive from this one list so they cannot drift.
- */
-export declare const EXPECTED_RECORD_TOOLS: readonly ["describe_datastore", "find_records", "insert_record", "update_record", "delete_record"];
-/**
- * Reconcile the record tools actually connected against the roster
- * contract (issue #325). Returns the expected tools absent from
- * `actualToolNames` — empty means healthy. Names are bare tool names
- * exactly as reported by tools/list (the mcp-enabled-tools identity
- * space); extraneous names are ignored.
- */
-export declare function missingRecordTools(actualToolNames: Iterable<string>): string[];
-/**
- * The operator-facing degradation notice (issue #325): pushed as a
- * MESSAGE_SYSTEM row on the execution status so "declared N datastores,
- * X/5 record tools connected" is visible without reading a transcript.
- * Lives HERE with the rest of the datastore-attachment wording — the
- * harness only threads it.
- */
-export declare function formatDatastoreDegradationNotice(declaredCount: number, missing: readonly string[]): string;
-/**
- * The datastores prompt section (DD-005 SD-5, the skills-section
- * precedent). Shared by both harnesses so the section text cannot drift
- * (the sender-identity precedent). Two honest renderings (issue #325):
- *
- * - Healthy (`missingToolNames` empty or omitted — the Cursor harness
- *   always calls it this way: the Cursor SDK connects MCP itself, so
- *   that harness can never observe the live roster):
- *   `<available_datastores>` names the attached datastores, points the
- *   model at describe_datastore first, and carries a standing
- *   failure-disclosure instruction — the only mechanism that covers
- *   tools which connected but fail at call time (the WhatsApp-pilot
- *   outage shape).
- * - Degraded (deep-agent only, from missingRecordTools against the
- *   connected roster): `<unavailable_datastores>` instead — the section
- *   must not promise tools the agent does not have. Names the declared
- *   datastores, states which record tools are missing, and instructs
- *   plain disclosure over improvisation.
- */
-export declare function formatDatastoresSection(datastoreUsages: DatastoreUsage[], missingToolNames?: readonly string[]): string;