@stigmer/runner 3.11.0 → 3.12.0

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

@@ -56,6 +56,7 @@ describe("buildChatModel", () => {
     delete process.env.STIGMER_ANTHROPIC_BACKEND;
     delete process.env.STIGMER_OPENAI_BACKEND;
     delete process.env.CLOUD_ML_REGION;
+    delete process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS;
   });
 
   afterEach(() => {
@@ -215,6 +216,51 @@ describe("buildChatModel", () => {
         },
       });
     });
+
+    // The env default resolves INSIDE buildChatModel (#468): before this,
+    // each caller parsed STIGMER_LLM_REQUEST_TIMEOUT_MS itself, and every
+    // caller except the deep-agent main path — including its own sub-agent
+    // modelFactory — dropped the bound.
+    it("defaults to STIGMER_LLM_REQUEST_TIMEOUT_MS when the caller passes no timeout", async () => {
+      process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS = "7000";
+      mockRegistryResponse([
+        { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+      ]);
+
+      await buildChatModel({ modelName: "claude-haiku-4.5" });
+
+      expect(lastAnthropicArgs()).toMatchObject({
+        clientOptions: { timeout: 7000 },
+        maxRetries: 0,
+      });
+    });
+
+    it("lets an explicit caller timeout win over the env default", async () => {
+      process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS = "7000";
+      mockRegistryResponse([
+        { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+      ]);
+
+      await buildChatModel({ modelName: "claude-haiku-4.5", timeoutMs: 5000 });
+
+      expect(lastAnthropicArgs()).toMatchObject({ clientOptions: { timeout: 5000 } });
+    });
+
+    it.each(["0", "-1", "not-a-number", ""])(
+      "normalizes a non-positive env value (%j) to no bound",
+      async (envValue) => {
+        process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS = envValue;
+        mockRegistryResponse([
+          { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+        ]);
+
+        await buildChatModel({ modelName: "claude-haiku-4.5" });
+
+        const args = lastAnthropicArgs();
+        expect(args).not.toHaveProperty("clientOptions");
+        expect(args).not.toHaveProperty("maxRetries");
+      },
+    );
   });
 
   // ─── Provider backends (STIGMER_ANTHROPIC_BACKEND) ─────────────────────────

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

@@ -1,6 +1,11 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { computeLlmCostMicros, computeTurnCost, getModelPricing, resolveModelId, ensureLoaded } from "../model-pricing.js";
-import type { ModelPricing } from "../model-pricing-data.js";
+import {
+  getPricingTable,
+  _resetPricingCache,
+  DEFAULT_PRICING,
+  type ModelPricing,
+} from "../model-pricing-data.js";
 
 describe("computeLlmCostMicros", () => {
   it("falls back to DEFAULT_PRICING when registry is not loaded", () => {
@@ -83,3 +88,58 @@ describe("getModelPricing", () => {
     expect(pricing.model).toBe("custom-model");
   });
 });
+
+describe("getPricingTable failure caching (#468)", () => {
+  beforeEach(() => {
+    _resetPricingCache();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    _resetPricingCache();
+    vi.useRealTimers();
+  });
+
+  const registryResponse = () =>
+    new Response(
+      JSON.stringify({
+        models: [
+          {
+            id: "claude-sonnet-4-6",
+            displayName: "Claude Sonnet",
+            costTier: "standard",
+            pricing: {
+              inputPricePerMillion: 3.0,
+              outputPricePerMillion: 15.0,
+              cacheWritePricePerMillion: 3.75,
+              cacheReadPricePerMillion: 0.3,
+            },
+          },
+        ],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+
+  it("retries after the short failure TTL instead of pinning DEFAULT_PRICING for an hour", async () => {
+    // The model-registry.ts failure-cache policy, applied here: wrong default
+    // rates for cost tracking must not persist a full success TTL.
+    vi.useFakeTimers();
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockRejectedValueOnce(new Error("network error"))
+      .mockResolvedValueOnce(registryResponse());
+
+    // First call fails and degrades to the default table.
+    expect((await getPricingTable())[0]).toBe(DEFAULT_PRICING);
+
+    // Within the failure TTL the fallback stays cached (no refetch).
+    vi.advanceTimersByTime(30_000);
+    expect((await getPricingTable())[0]).toBe(DEFAULT_PRICING);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    // Past the failure TTL the registry is refetched and real rates recover.
+    vi.advanceTimersByTime(31_000);
+    expect((await getPricingTable())[0]?.model).toBe("claude-sonnet-4-6");
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -223,6 +223,28 @@ describe("resolveToApiModelId", () => {
     expect(result).toBe("claude-haiku-4.5");
   });
 
+  it("recovers from a transient network failure without engaging the failure cache (#468)", async () => {
+    // undici's retryable shape (TypeError) — the shared bounded-backoff loop
+    // absorbs it, so resolution succeeds on the SAME call and the 60 s
+    // degraded window never opens. Pre-#468 code failed the fetch outright.
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockRejectedValueOnce(new TypeError("fetch failed"))
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            models: [
+              { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic", costTier: "economy", harness: "native" },
+            ],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      );
+
+    expect(await resolveToApiModelId("claude-haiku-4.5")).toBe("claude-haiku-4-5-20251001");
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
   it("retries after the short failure TTL instead of caching the failure for an hour", async () => {
     vi.useFakeTimers();
     const fetchSpy = vi

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

@@ -13,6 +13,11 @@
  * The runner never holds R2/S3 credentials — in cloud mode it calls the proxy
  * to obtain a presigned upload URL, then PUTs content over plain HTTPS.
  *
+ * Every proxy-backend request rides the shared bounded-backoff loop
+ * (http-retry.ts) with a per-request abort timeout, so a momentary
+ * stigmer-service interruption is retried and a hung connection cannot
+ * stall an agent turn unboundedly (stigmer/stigmer#468).
+ *
  * DD-6: No direct R2 backend. Local + Proxy only.
  */
 
@@ -20,10 +25,21 @@ import { mkdir, writeFile, readFile, access, rm } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import type { Config } from "../config.js";
+import type { RetryOptions } from "./grpc-retry.js";
+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>;
   /**
@@ -45,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;
 
@@ -117,13 +134,65 @@ export class LocalArtifactStorage implements ArtifactStorage {
 
 // ── Proxy Backend ────────────────────────────────────────────────────
 
+/** Retry policy plus the two per-request bounds; every field is defaulted. */
+export interface ProxyArtifactStorageOptions extends RetryOptions {
+  /** Bound for proxy presign calls and the 1-byte exists probe. Default 30 s. */
+  readonly requestTimeoutMs?: number;
+  /**
+   * Bound for the presigned R2 PUT/GET, which move whole artifact payloads
+   * (claim-check offloads, tool outputs, file-review captures — MB scale).
+   * Deliberately wider than requestTimeoutMs so a legitimate slow transfer
+   * is never aborted by a bound sized for JSON round-trips. Default 120 s.
+   */
+  readonly transferTimeoutMs?: number;
+}
+
+/**
+ * Default transient-retry policy (stigmer/stigmer#468): the checkpointer's
+ * budget — sized to span a pod-restart reroute, ~7.75 s of delays across
+ * 5 retries. Retrying is safe at every site: the presign POSTs are
+ * idempotent mints, the PUT re-sends identical bytes to the same key (a
+ * keyed overwrite), and the GETs are reads.
+ */
+const DEFAULT_RETRY = {
+  baseDelayMs: 250,
+  backoffFactor: 2,
+  maxRetries: 5,
+  requestTimeoutMs: 30_000,
+  transferTimeoutMs: 120_000,
+} as const;
+
 export class ProxyArtifactStorage implements ArtifactStorage {
+  readonly downloadUrlKind = "presigned" as const;
   private readonly baseUrl: string;
   private readonly authTokenSource: ProxyAuthTokenSource;
-
-  constructor(proxyEndpoint: string, authToken: ProxyAuthTokenSource) {
+  /** Governs the proxy presign calls and the exists probe. */
+  private readonly requestPolicy: FetchRetryPolicy;
+  /** Governs the presigned R2 transfers; same budget, wider timeout. */
+  private readonly transferPolicy: FetchRetryPolicy;
+
+  constructor(
+    proxyEndpoint: string,
+    authToken: ProxyAuthTokenSource,
+    options: ProxyArtifactStorageOptions = {},
+  ) {
     this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/artifacts`;
     this.authTokenSource = authToken;
+    const shared = {
+      label: "ProxyArtifactStorage",
+      baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
+      backoffFactor: options.backoffFactor ?? DEFAULT_RETRY.backoffFactor,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY.maxRetries,
+      delayFn: options.delayFn,
+    };
+    this.requestPolicy = {
+      ...shared,
+      requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_RETRY.requestTimeoutMs,
+    };
+    this.transferPolicy = {
+      ...shared,
+      requestTimeoutMs: options.transferTimeoutMs ?? DEFAULT_RETRY.transferTimeoutMs,
+    };
   }
 
   /**
@@ -141,14 +210,14 @@ export class ProxyArtifactStorage implements ArtifactStorage {
   async upload(key: string, content: Buffer, contentType?: string): Promise<string> {
     const ct = contentType ?? "application/octet-stream";
 
-    const presignResp = await fetch(`${this.baseUrl}/presigned-upload-url`, {
+    const presignResp = await fetchWithRetry(`${this.baseUrl}/presigned-upload-url`, {
       method: "POST",
       headers: {
         "Authorization": `Bearer ${this.authToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ key, content_type: ct }),
-    });
+    }, this.requestPolicy);
     if (!presignResp.ok) {
       throw new Error(
         `Failed to get presigned upload URL (HTTP ${presignResp.status}): ` +
@@ -180,11 +249,14 @@ export class ProxyArtifactStorage implements ArtifactStorage {
       uploadHeaders["Content-Type"] = ct;
     }
 
-    const putResp = await fetch(data.url, {
+    // Retrying the PUT alone (not the presign+PUT pair) is deliberate: the
+    // retry budget's few seconds of delays sit far inside presign validity,
+    // and re-sending the same Buffer to the same key is a keyed overwrite.
+    const putResp = await fetchWithRetry(data.url, {
       method: "PUT",
       headers: uploadHeaders,
       body: content,
-    });
+    }, this.transferPolicy);
     if (!putResp.ok) {
       throw new Error(
         `Presigned upload failed (HTTP ${putResp.status}): ` +
@@ -196,14 +268,14 @@ export class ProxyArtifactStorage implements ArtifactStorage {
   }
 
   async getDownloadUrl(key: string): Promise<string> {
-    const resp = await fetch(`${this.baseUrl}/presigned-download-url`, {
+    const resp = await fetchWithRetry(`${this.baseUrl}/presigned-download-url`, {
       method: "POST",
       headers: {
         "Authorization": `Bearer ${this.authToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ key }),
-    });
+    }, this.requestPolicy);
     if (!resp.ok) {
       throw new Error(
         `Failed to get presigned download URL (HTTP ${resp.status}): ` +
@@ -216,7 +288,7 @@ export class ProxyArtifactStorage implements ArtifactStorage {
 
   async download(key: string): Promise<Buffer> {
     const url = await this.getDownloadUrl(key);
-    const resp = await fetch(url);
+    const resp = await fetchWithRetry(url, undefined, this.transferPolicy);
     if (!resp.ok) {
       throw new Error(
         `Artifact download failed (HTTP ${resp.status}) for key '${key}': ` +
@@ -242,7 +314,11 @@ export class ProxyArtifactStorage implements ArtifactStorage {
       // addressed CAS blob dedup) then re-uploads, which is idempotent.
       return false;
     }
-    const resp = await fetch(url, { headers: { Range: "bytes=0-0" } });
+    const resp = await fetchWithRetry(
+      url,
+      { headers: { Range: "bytes=0-0" } },
+      this.requestPolicy,
+    );
     await resp.arrayBuffer().catch(() => undefined); // drain the <=1-byte body
     if (resp.status === 404) return false;
     if (resp.status === 200 || resp.status === 206 || resp.status === 416) return true;

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