@stigmer/runner 3.11.1-dev.20260812192248 → 3.12.1

package/src/shared/__tests__/zip-extract.test.ts

@@ -1,89 +1,12 @@
 import { describe, it, expect } from "vitest";
-import { deflateRawSync } from "node:zlib";
 import { extractZipFileEntries } from "../zip-extract.js";
-
-// ─── Helpers ─────────────────────────────────────────────────────────────
-
-/**
- * Build a minimal valid ZIP archive from an array of { name, content } entries.
- * Uses stored (method 0) compression for simplicity. Produces local file
- * headers only (no central directory) — sufficient for our parser.
- */
-function buildStoredZip(files: { name: string; content: string }[]): Uint8Array {
-  const parts: Uint8Array[] = [];
-
-  for (const file of files) {
-    const nameBytes = new TextEncoder().encode(file.name);
-    const contentBytes = new TextEncoder().encode(file.content);
-    const isDir = file.name.endsWith("/");
-
-    // Local file header: 30 bytes
-    const header = new ArrayBuffer(30);
-    const view = new DataView(header);
-    view.setUint32(0, 0x04034b50, true);  // signature
-    view.setUint16(4, 20, true);           // version needed
-    view.setUint16(6, 0, true);            // general purpose flags
-    view.setUint16(8, 0, true);            // compression method (stored)
-    view.setUint16(10, 0, true);           // last mod time
-    view.setUint16(12, 0, true);           // last mod date
-    view.setUint32(14, 0, true);           // crc-32 (unused for our purposes)
-    view.setUint32(18, isDir ? 0 : contentBytes.length, true); // compressed size
-    view.setUint32(22, isDir ? 0 : contentBytes.length, true); // uncompressed size
-    view.setUint16(26, nameBytes.length, true);  // file name length
-    view.setUint16(28, 0, true);           // extra field length
-
-    parts.push(new Uint8Array(header));
-    parts.push(nameBytes);
-    if (!isDir) {
-      parts.push(contentBytes);
-    }
-  }
-
-  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const part of parts) {
-    result.set(part, offset);
-    offset += part.length;
-  }
-  return result;
-}
-
-/**
- * Build a ZIP archive with a single deflated (method 8) entry.
- */
-function buildDeflatedZip(name: string, content: string): Uint8Array {
-  const nameBytes = new TextEncoder().encode(name);
-  const contentBytes = new TextEncoder().encode(content);
-  const compressed = deflateRawSync(contentBytes);
-
-  const header = new ArrayBuffer(30);
-  const view = new DataView(header);
-  view.setUint32(0, 0x04034b50, true);
-  view.setUint16(4, 20, true);
-  view.setUint16(6, 0, true);
-  view.setUint16(8, 8, true);            // deflated
-  view.setUint16(10, 0, true);
-  view.setUint16(12, 0, true);
-  view.setUint32(14, 0, true);
-  view.setUint32(18, compressed.length, true);
-  view.setUint32(22, contentBytes.length, true);
-  view.setUint16(26, nameBytes.length, true);
-  view.setUint16(28, 0, true);
-
-  const totalLength = 30 + nameBytes.length + compressed.length;
-  const result = new Uint8Array(totalLength);
-  result.set(new Uint8Array(header), 0);
-  result.set(nameBytes, 30);
-  result.set(new Uint8Array(compressed.buffer, compressed.byteOffset, compressed.length), 30 + nameBytes.length);
-  return result;
-}
+import { buildZip } from "../../__test-utils__/zip-fixtures.js";
 
 // ─── extractZipFileEntries ───────────────────────────────────────────────
 
 describe("extractZipFileEntries", () => {
   it("extracts stored files from a ZIP archive", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "# My Skill" },
       { name: "references/schema.md", content: "# Schema\n\nTable definitions." },
     ]);
@@ -96,7 +19,7 @@ describe("extractZipFileEntries", () => {
 
   it("extracts deflated files", async () => {
     const content = "This content is compressed with deflate.";
-    const zip = buildDeflatedZip("notes.txt", content);
+    const zip = buildZip([{ name: "notes.txt", content, method: "deflated" }]);
 
     const entries = await extractZipFileEntries(zip);
     expect(entries).toHaveLength(1);
@@ -104,7 +27,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("skips directory entries", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "references/", content: "" },
       { name: "references/data.md", content: "data" },
     ]);
@@ -115,7 +38,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("excludes files by basename", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "# Skill" },
       { name: "references/schema.md", content: "# Schema" },
       { name: "scripts/run.py", content: "print('hi')" },
@@ -127,7 +50,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("excludes files by full path", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "a.md", content: "a" },
       { name: "nested/a.md", content: "nested" },
     ]);
@@ -138,7 +61,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("excludes entries matching basename even when nested", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "root" },
       { name: "sub/SKILL.md", content: "sub" },
       { name: "data.md", content: "data" },
@@ -166,7 +89,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("handles multiple files with nested directories", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "# Skill" },
       { name: "references/", content: "" },
       { name: "references/database-schema.md", content: "# Schema" },
@@ -184,7 +107,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("returns all entries when no exclude option is provided", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "a.txt", content: "aaa" },
       { name: "b.txt", content: "bbb" },
     ]);
@@ -194,11 +117,105 @@ describe("extractZipFileEntries", () => {
   });
 
   it("returns all entries when exclude list is empty", async () => {
-    const zip = buildStoredZip([
-      { name: "a.txt", content: "aaa" },
-    ]);
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }]);
 
     const entries = await extractZipFileEntries(zip, { exclude: [] });
     expect(entries).toHaveLength(1);
   });
+
+  // ── Streaming entries (issue #450) ─────────────────────────────────────
+
+  it("extracts Go-default streaming archives (deflated, data descriptors)", async () => {
+    const zip = buildZip([
+      { name: "SKILL.md", content: "# Streamed Skill", method: "deflated", streaming: true },
+      { name: "references/notes.md", content: "streamed notes", method: "deflated", streaming: true },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([
+      { path: "SKILL.md", content: "# Streamed Skill" },
+      { path: "references/notes.md", content: "streamed notes" },
+    ]);
+  });
+
+  it("extracts a stored streaming entry whose payload embeds the data-descriptor signature", async () => {
+    // The four bytes of the descriptor signature (0x08074b50, little-endian
+    // "PK\x07\x08") planted mid-content, followed by twelve bytes a
+    // descriptor-scanning parser would misread as CRC and sizes. The old
+    // local-header walk truncated this entry at the planted signature and
+    // desynchronized everything after it — the exact defect of issue #450.
+    const poisoned = "before PK\u0007\u0008AAAABBBBCCCC after — full content survives";
+    const zip = buildZip([
+      { name: "poison.md", content: poisoned, streaming: true },
+      { name: "after.md", content: "the entry after the poisoned one" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([
+      { path: "poison.md", content: poisoned },
+      { path: "after.md", content: "the entry after the poisoned one" },
+    ]);
+  });
+
+  it("uses central-directory sizes when local header sizes are zeroed", async () => {
+    const content = "sizes live only in the central directory";
+    const zip = buildZip([{ name: "cd-sizes.txt", content, streaming: true }]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([{ path: "cd-sizes.txt", content }]);
+  });
+
+  // ── Central directory edge cases ───────────────────────────────────────
+
+  it("locates the EOCD behind a trailing archive comment", async () => {
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }], {
+      comment: "release archive — built by tooling",
+    });
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([{ path: "a.txt", content: "aaa" }]);
+  });
+
+  it("is not fooled by EOCD signature bytes inside the archive comment", async () => {
+    // "PK\x05\x06" inside the comment is a decoy EOCD; validation must
+    // reject it (its "fields" are comment text) and keep scanning backward
+    // to the real record.
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }], {
+      comment: "decoy: PK\u0005\u0006 not a real record",
+    });
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([{ path: "a.txt", content: "aaa" }]);
+  });
+
+  it("returns empty array when the central directory is missing", async () => {
+    // Local headers and payloads only — a download truncated before the
+    // archive's index. The parser must not fall back to guessing from
+    // local headers (design record 017).
+    const zip = buildZip(
+      [
+        { name: "a.txt", content: "aaa" },
+        { name: "b.txt", content: "bbb" },
+      ],
+      { omitCentralDirectory: true },
+    );
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([]);
+  });
+
+  it("returns empty array for an archive with entries but a truncated tail", async () => {
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }]);
+    const truncated = zip.subarray(0, zip.length - 10); // clips into the EOCD
+
+    const entries = await extractZipFileEntries(truncated);
+    expect(entries).toEqual([]);
+  });
+
+  it("extracts an empty archive (EOCD only) as no entries", async () => {
+    const zip = buildZip([]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([]);
+  });
 });

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-enabled-tools.ts

@@ -21,8 +21,12 @@
  * identity space as the sub-agent McpAccess filter and the approval-policy
  * maps. An enabled name the server does not expose is warned and dropped
  * (enforce the intersection): the restriction still holds and the run
- * proceeds with the valid subset; apply-time validation against
- * discovered_capabilities is the server-side follow-up that catches typos.
+ * proceeds with the valid subset. The server-side half (issue #402) rejects
+ * such names at apply time once the referenced server has discovered
+ * capabilities (stigmer-server validateEnabledToolsStep /
+ * validateDefaultEnabledToolsStep); this runtime leniency remains the
+ * safety net for manifests applied before a server's first connect and for
+ * toolsets that changed since the last discovery.
  */
 
 /**

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/plan-mode-permissions.ts

@@ -2,12 +2,26 @@
  * The Plan-mode filesystem permission rules — the enforcement twin of
  * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
  *
- * Plan mode is read-only BY CONSTRUCTION on the native harness: these rules
- * deny every filesystem write operation at the tool level so
- * write_file/edit_file cannot mutate the workspace regardless of what the
- * model was told. Rules are first-match-wins with a permissive default, so a
- * single deny-all-writes rule is sufficient. (The Cursor harness has no
- * tool-level lever and enforces plan mode via its prompt prefix instead.)
+ * Plan mode is contained BY CONSTRUCTION on the native harness: these rules
+ * deny every filesystem write everywhere AND scope reads to the session
+ * workspace (issue #528 — owner ruling: the workspace is plan mode's read
+ * boundary on cloud and desktop runners alike). Without the read boundary,
+ * model-provided absolute paths reached anywhere the process account could
+ * read — the pod filesystem (including /proc/self/environ) on cloud runners,
+ * the user's whole home directory on desktop — while plan mode still carries
+ * exfiltration-capable tools (web_fetch, MCP). Rules are first-match-wins
+ * with a permissive default (deepagents' decidePathAccess), so order is
+ * load-bearing: the workspace read-allow must precede the read-deny.
+ *
+ * The workspace-root pattern is matched as a STRING against the raw tool-call
+ * path (micromatch, dot:true), before the backend touches disk. That is
+ * exactly why the legitimate out-of-workspace reads keep working: skills,
+ * attachments, and the approved plan live in the platform dir but are
+ * addressed through the `{workspace}/.stigmer` symlink (see
+ * shared/workspace/stigmer-link.ts), so their path strings are in-root even
+ * though the bytes are not. The same holds for multi-workspace local entries
+ * (`{workspace}/{name}` symlinks). A realpath-based boundary would break
+ * both; do not "harden" this into one.
  *
  * Applied in execute-deep-agent/setup.ts to the parent graph AND threaded
  * into every compiled sub-agent graph: deepagents' parent-permission
@@ -18,9 +32,9 @@
  *
  * Rules travel with a companion: every graph that carries them also installs
  * the path-normalization middleware (middleware/path-normalization.ts,
- * issue #429), because deepagents' rule validation refuses workspace-relative
- * paths outright — without the shim, prompt-compliant relative READS die in
- * validation instead of just working. Both are derived from the same
+ * issues #429/#528), because deepagents' rule validation refuses
+ * workspace-relative paths outright and its `ls`/`glob`/`grep` schema default
+ * of "/" would deny the bare first listing. Both are derived from the same
  * expression at each composition site so they cannot drift apart.
  *
  * Invariant: never combine these rules with a shell-capable (sandbox)
@@ -30,8 +44,41 @@
  * for shell capability on both the parent and sub-agent backends.
  */
 
+import { resolve } from "node:path";
 import type { FilesystemPermission } from "deepagents";
 
-export const PLAN_MODE_PERMISSIONS: FilesystemPermission[] = [
-  { operations: ["write"], paths: ["/**"], mode: "deny" },
-];
+/**
+ * Backslash-escape every character micromatch/picomatch treats as glob
+ * syntax, so the result matches the input literally. micromatch exports no
+ * escape API of its own, and this is correctness, not caution: an unescaped
+ * `(` in a desktop project path would make the workspace read-allow rule
+ * silently never match — bricking every plan-mode read for that workspace.
+ * Semantics are pinned end-to-end through deepagents' own matcher by the
+ * special-character workspace suite in plan-mode-path-normalization.test.ts.
+ */
+export function escapeGlobLiteral(literal: string): string {
+  return literal.replace(/[\\*?()[\]{}!+@]/g, "\\$&");
+}
+
+/**
+ * Build the plan-mode rule set for a graph whose filesystem backend is
+ * rooted at `workspaceRootDir`. The three rules read as the policy:
+ * reads allowed in the workspace, reads denied everywhere else, writes
+ * denied everywhere.
+ *
+ * `{root}/**` matches the root itself as well as its subtree (verified
+ * against the installed micromatch), so one allow pattern suffices. The
+ * root is `path.resolve`d first because enforcement canonicalizes incoming
+ * paths (collapsed slashes, no trailing separator) before matching — a
+ * trailing slash in the pattern would silently match nothing.
+ */
+export function buildPlanModePermissions(
+  workspaceRootDir: string,
+): FilesystemPermission[] {
+  const canonicalRoot = resolve(workspaceRootDir);
+  return [
+    { operations: ["read"], paths: [`${escapeGlobLiteral(canonicalRoot)}/**`] },
+    { operations: ["read"], paths: ["/**"], mode: "deny" },
+    { operations: ["write"], paths: ["/**"], mode: "deny" },
+  ];
+}

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[],