@stigmer/runner 3.12.1 → 3.12.3

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

@@ -7,10 +7,19 @@
  * - Uses a platform-managed directory outside the workspace
  * - Ensures the workspace `.stigmer` symlink (see stigmer-link.ts)
  * - Returns metadata for prompt injection
+ *
+ * The mount is cached by the skill's content-addressed version hash
+ * (stigmer/stigmer#672): metadata is fetched on every execution (that keeps
+ * latest-version freshness), but the artifact download and file rewrite are
+ * skipped when the mounted content's hash already matches. The session's
+ * platform dir survives across executions, so on an active session every
+ * message after the first pays a metadata read instead of a full artifact
+ * transfer.
  */
 
-import { mkdir, writeFile, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { ConnectError, Code } from "@connectrpc/connect";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -21,6 +30,25 @@ import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/work
 
 const SKILLS_SUBDIR = "skills";
 
+/**
+ * Marker recording what a skill's mount directory currently holds. Written
+ * LAST, after every file of the mount landed — a crash mid-write leaves no
+ * marker, so the next execution remounts instead of trusting a partial tree.
+ */
+const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+
+interface MountMarker {
+  /** Content-addressed version hash (`Skill.status.version_hash`) of the mounted content. */
+  versionHash: string;
+  /**
+   * Whether the artifact's files are part of the mount. `false` when the
+   * skill has no artifact OR when the download failed and the mount fell
+   * back to SKILL.md only — the latter makes the next execution retry the
+   * download rather than cache the degraded mount.
+   */
+  artifactMounted: boolean;
+}
+
 export interface SkillResolverOptions {
   sessionId: string;
   primaryWorkspaceDir: string;
@@ -61,29 +89,49 @@ export async function resolveSkills(
   for (const ref of skillRefs) {
     try {
       const skill = await client.getSkillByReference(ref);
+      const spec = skill.spec;
+      if (!spec?.skillMd) {
+        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
+        continue;
+      }
+
+      const name = spec.name || skill.metadata?.slug || "unknown";
+      const skillDir = join(skillsDir, name);
+      const versionHash = skill.status?.versionHash ?? "";
+      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
+      const meta: SkillMetadata = {
+        name,
+        description: spec.description || `Skill: ${name}`,
+        path: join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md"),
+      };
+
+      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+        results.push(meta);
+        console.log(
+          `[resolveSkills] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
+        );
+        continue;
+      }
 
       let artifactBytes: Uint8Array | undefined;
-      if (skill.status?.artifactStorageKey) {
+      if (wantsArtifact) {
         try {
-          const resp = await client.getSkillArtifact(skill.status.artifactStorageKey);
-          if (resp.artifact && resp.artifact.length > 0) {
-            artifactBytes = resp.artifact;
-          }
+          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
         } catch (err) {
-          console.warn(
-            `[resolveSkills] artifact download failed for ${ref.slug}, ` +
-            `falling back to SKILL.md only: ${err instanceof Error ? err.message : err}`,
+          // Deliberate degradation, but LOUD (#675): the session still gets
+          // SKILL.md (better than a dead run), yet a skill silently missing
+          // its scripts/references was exactly how oversized artifacts hid.
+          console.error(
+            `[resolveSkills] artifact download FAILED for ${ref.org || "(default)"}/${ref.slug} ` +
+            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
           );
         }
       }
 
-      const meta = await writeSkill(skill, skillsDir, options.primaryWorkspaceDir, artifactBytes);
-      if (meta) {
-        results.push(meta);
-        console.log(`[resolveSkills] wrote skill: ${meta.name} -> ${meta.path}`);
-      } else {
-        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
-      }
+      await writeSkillMount(skill, skillDir, artifactBytes);
+      results.push(meta);
+      console.log(`[resolveSkills] wrote skill: ${name} -> ${meta.path}`);
     } catch (err) {
       console.warn(
         `[resolveSkills] failed to resolve skill ${ref.org}/${ref.slug}: ${err instanceof Error ? err.message : err}`,
@@ -98,24 +146,89 @@ export async function resolveSkills(
   return results;
 }
 
-async function writeSkill(
+/**
+ * Whether the mount at `skillDir` already holds this version's content.
+ *
+ * Fresh means: the marker's hash matches AND the mount isn't a degraded
+ * SKILL.md-only fallback when the skill does carry an artifact. Any read or
+ * parse failure counts as stale — the remount is the safe default.
+ */
+async function mountIsFresh(skillDir: string, versionHash: string, wantsArtifact: boolean): Promise<boolean> {
+  try {
+    const raw = await readFile(join(skillDir, MOUNT_MARKER_FILE), "utf-8");
+    const marker = JSON.parse(raw) as Partial<MountMarker>;
+    return marker.versionHash === versionHash && (marker.artifactMounted === true || !wantsArtifact);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Download a skill artifact's ZIP bytes, transfer lane first (#675).
+ *
+ * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
+ * size; the unary getArtifact response is capped by the server's 10MB gRPC
+ * message limit. Servers that predate the lane (and cloud until its sibling
+ * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
+ * path, which behaves exactly as before for ≤10MB artifacts.
+ *
+ * Runs only on a mount-cache miss (#672's hash-keyed marker above) — a hit
+ * skips the transfer entirely, whichever lane would have carried it.
+ *
+ * Exported for tests.
+ */
+export async function downloadArtifact(
+  client: StigmerClient,
+  artifactStorageKey: string,
+): Promise<Uint8Array | undefined> {
+  let minted;
+  try {
+    minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+      const resp = await client.getSkillArtifact(artifactStorageKey);
+      return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
+    }
+    throw err;
+  }
+
+  const resp = await fetch(minted.url);
+  if (!resp.ok) {
+    throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
+  }
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+  if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
+    throw new Error(
+      `artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`,
+    );
+  }
+  return bytes.length > 0 ? bytes : undefined;
+}
+
+/**
+ * (Re)write a skill's mount directory from scratch.
+ *
+ * The directory is removed first so files deleted between versions don't
+ * linger in the mount, then SKILL.md and the artifact files are written, and
+ * the marker is stamped LAST (see MOUNT_MARKER_FILE for the crash-safety
+ * contract). SKILL.md always comes from `spec.skillMd` — the server's
+ * authoritative copy — never from the zip; both the zip's SKILL.md and any
+ * stray marker-named entry are excluded from extraction so the mount's
+ * ownership of those two files is unconditional.
+ */
+async function writeSkillMount(
   skill: Skill,
-  skillsDir: string,
-  workspaceDir: string,
-  artifactBytes?: Uint8Array,
-): Promise<SkillMetadata | null> {
-  const spec = skill.spec;
-  if (!spec?.skillMd) return null;
-
-  const name = spec.name || skill.metadata?.slug || "unknown";
-  const skillDir = join(skillsDir, name);
+  skillDir: string,
+  artifactBytes: Uint8Array | undefined,
+): Promise<void> {
+  await rm(skillDir, { recursive: true, force: true });
   await mkdir(skillDir, { recursive: true });
 
-  const skillMdPath = join(skillDir, "SKILL.md");
-  await writeFile(skillMdPath, spec.skillMd, "utf-8");
+  await writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd, "utf-8");
 
-  if (artifactBytes && artifactBytes.length > 0) {
-    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md"] });
+  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+  if (artifactMounted) {
+    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
     for (const entry of entries) {
       const filePath = join(skillDir, entry.path);
       await mkdir(dirname(filePath), { recursive: true });
@@ -123,13 +236,11 @@ async function writeSkill(
     }
   }
 
-  const relativePath = join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md");
-
-  return {
-    name,
-    description: spec.description || `Skill: ${name}`,
-    path: relativePath,
-  };
+  const versionHash = skill.status?.versionHash ?? "";
+  if (versionHash !== "") {
+    const marker: MountMarker = { versionHash, artifactMounted };
+    await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
+  }
 }
 
 /**

package/src/activities/execute-deep-agent/__test-utils__/scripted-model.ts

@@ -50,11 +50,20 @@ export type ScriptSelector = (boundToolNames: string[]) => ScriptStep;
  */
 export class ScriptedModel extends BaseChatModel {
   toolNames: string[] = [];
+  /**
+   * The tool objects from the most recent `bindTools` call, exactly as the
+   * agent bound them (post-middleware). Lets tests assert on the bound
+   * SCHEMAS — e.g. the tool-intent middleware's bind-time shell clone — not
+   * just the names. The array is shared across the clones `bindTools`
+   * returns, so the instance the test holds always sees the latest bind.
+   */
+  readonly boundTools: unknown[];
   private readonly select: ScriptSelector;
 
-  constructor(select: ScriptSelector) {
+  constructor(select: ScriptSelector, boundTools: unknown[] = []) {
     super({});
     this.select = select;
+    this.boundTools = boundTools;
   }
 
   _llmType(): string {
@@ -62,8 +71,10 @@ export class ScriptedModel extends BaseChatModel {
   }
 
   bindTools(tools: unknown[]): this {
-    const next = new ScriptedModel(this.select);
+    const next = new ScriptedModel(this.select, this.boundTools);
     next.toolNames = (tools as Array<{ name?: string }>).map((t) => t?.name ?? "");
+    this.boundTools.length = 0;
+    this.boundTools.push(...tools);
     return next as unknown as this;
   }
 

package/src/activities/execute-deep-agent/__tests__/subagent-wiring.test.ts

@@ -7,11 +7,12 @@ describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
     const stack = buildSubAgentMiddleware();
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack[0].name).toBe("LoopDetectionMiddleware");
     expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
-    expect(stack[2].name).toBe("ToolTruncationMiddleware");
-    expect(stack[3].name).toBe("ErrorHintsMiddleware");
+    expect(stack[2].name).toBe("StigmerToolIntentMiddleware");
+    expect(stack[3].name).toBe("ToolTruncationMiddleware");
+    expect(stack[4].name).toBe("ErrorHintsMiddleware");
   });
 
   it("includes cost cap view when parent cost cap is provided", () => {
@@ -25,9 +26,9 @@ describe("buildSubAgentMiddleware", () => {
 
     const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
 
-    expect(stack).toHaveLength(5);
-    expect(stack[3].name).toBe("CostCapSubAgentView");
-    expect(stack[4].name).toBe("ErrorHintsMiddleware");
+    expect(stack).toHaveLength(6);
+    expect(stack[4].name).toBe("CostCapSubAgentView");
+    expect(stack[5].name).toBe("ErrorHintsMiddleware");
   });
 
   it("sub-agent cost cap view shares parent state", () => {
@@ -43,7 +44,7 @@ describe("buildSubAgentMiddleware", () => {
 
     expect(parentCostCap.runningCost).toBe(0);
 
-    const subView = stack[3];
+    const subView = stack[4];
     expect(subView.afterModel).toBeDefined();
     expect(subView.wrapToolCall).toBeDefined();
     expect(subView.beforeAgent).toBeUndefined();
@@ -69,7 +70,7 @@ describe("buildSubAgentMiddleware", () => {
       toolTruncation: { maxChars: 5000 },
     });
 
-    expect(stack[2].name).toBe("ToolTruncationMiddleware");
+    expect(stack[3].name).toBe("ToolTruncationMiddleware");
   });
 
   it("installs the approval gate when an approvalGate config is provided", () => {
@@ -77,16 +78,16 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, error hints
-    expect(stack).toHaveLength(5);
-    expect(stack[3].name).toBe("ApprovalGateMiddleware");
-    expect(stack[3].wrapToolCall).toBeDefined();
+    // loop, budget, tool intent, truncation, approval gate, error hints
+    expect(stack).toHaveLength(6);
+    expect(stack[4].name).toBe("ApprovalGateMiddleware");
+    expect(stack[4].wrapToolCall).toBeDefined();
   });
 
   it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
     const stack = buildSubAgentMiddleware({ approvalGate: null });
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
   });
 
@@ -104,13 +105,13 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, cost cap view, error hints.
-    // Hints AFTER the gate matches the parent nesting: the gate's HITL
-    // interrupt stays outside the hints' try/catch (issue #255).
-    expect(stack).toHaveLength(6);
-    expect(stack[3].name).toBe("ApprovalGateMiddleware");
-    expect(stack[4].name).toBe("CostCapSubAgentView");
-    expect(stack[5].name).toBe("ErrorHintsMiddleware");
+    // loop, budget, tool intent, truncation, approval gate, cost cap view,
+    // error hints. Hints AFTER the gate matches the parent nesting: the
+    // gate's HITL interrupt stays outside the hints' try/catch (issue #255).
+    expect(stack).toHaveLength(7);
+    expect(stack[4].name).toBe("ApprovalGateMiddleware");
+    expect(stack[5].name).toBe("CostCapSubAgentView");
+    expect(stack[6].name).toBe("ErrorHintsMiddleware");
   });
 
   // captureIgnored is the structural coupling that makes sub-agent gitignored

package/src/activities/execute-deep-agent/cas-capture-backend.ts

@@ -21,7 +21,9 @@
  *
  * deepagents mutates only via `write` (create/overwrite) and `edit` (modify);
  * there is no backend delete/rename, so this observes CREATE and MODIFY. A
- * gitignored delete can only arrive via shell, which stays on the approval gate.
+ * delete-category tool consequently cannot be observed here — the approval gate
+ * records its before-bytes at authorization time instead (`captureDeleteBefore`,
+ * issue #303). A delete via shell (`rm`) stays on the approval gate as always.
  *
  * @since File-Change HITL Redesign (Phase 3 — CAS deep-agent wiring); sub-agent
  * gitignored capture parity (Session 26, DD-19); shell restore (issue #248)

package/src/activities/execute-deep-agent/setup.ts

@@ -676,6 +676,14 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
           isCapturablePath,
           captureIgnored: captureMode && !!artifactStorage,
           recordBlockedSecret: (rawPath: string) => casObserver.recordBlockedSecret(rawPath),
+          // Pre-delete byte capture (issue #303): deepagents has no backend
+          // delete method for the CAS backend to observe, so a flowing delete's
+          // before-bytes are recorded by the gate at authorization time, through
+          // the SAME shared observer — the turn boundary then reads after=null
+          // and authors a reviewable, restorable DELETE. recordBefore's own
+          // ownership predicate (gitignored-only in a git tree, everything in
+          // non-git) agrees with the gate's not-capturable condition.
+          captureDeleteBefore: (rawPath: string) => casObserver.recordBefore(rawPath),
           unattended,
           unattendedSkips,
         }

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -9,6 +9,9 @@
  *   same `permissions` option it bakes into the graph, keeping the rules
  *   and their normalization shim coupled.
  * - Fresh loop detection (independent cycle tracking)
+ * - Tool intent (issue #276) — the shell tool's bind-time schema gains the
+ *   optional model-authored `description`, so sub-agent shell rows carry
+ *   intent titles exactly like the parent's
  * - Fresh tool truncation (same limits as parent)
  * - Periodic execution budget (interval=30, max=4 advisories)
  * - Approval gate (so a mutating tool *inside* a sub-agent is gated, not
@@ -43,6 +46,7 @@ import { createPathNormalizationMiddleware } from "../../middleware/path-normali
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
 import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
+import { createToolIntentMiddleware } from "../../middleware/tool-intent.js";
 import {
   createApprovalGateMiddleware,
   type ApprovalGateConfig,
@@ -83,7 +87,8 @@ export interface SubAgentMiddlewareOptions {
  *
  * Returns an ordered array mirroring the parent composition:
  * [path normalization] → loop detection → execution budget (periodic) →
- * tool truncation → [approval gate] → cost cap view → error hints.
+ * tool intent → tool truncation → [approval gate] → cost cap view →
+ * error hints.
  * Normalization is outermost so everything downstream observes canonical
  * workspace-absolute paths (matching the parent). The gate sits before the
  * cost-cap view so an approval pause happens before budget accounting, and
@@ -107,22 +112,33 @@ export function buildSubAgentMiddleware(
     maxWarnings: SUB_AGENT_MAX_ADVISORIES,
   }));
 
+  // Sub-agent shell rows render in the same thread as the parent's and must
+  // carry the same model-authored intent titles (issue #276).
+  stack.push(createToolIntentMiddleware());
+
   stack.push(createToolTruncationMiddleware(options.toolTruncation));
 
   if (options.approvalGate) {
-    // captureIgnored (DD-19): a sub-agent flows gitignored writes into CAS iff a
-    // CAS observer backs its filesystem backend (compileSubagents passes this as
+    // captureIgnored (DD-19): a sub-agent flows gitignored writes — and, since
+    // issue #303, non-secret CAS-owned deletes — into CAS iff a CAS observer
+    // backs its filesystem backend (compileSubagents passes this as
     // `!!casObserver`). When true, inherit the parent gate verbatim so its
-    // captureIgnored + recordBlockedSecret feed the SAME shared observer that
-    // backs the sub-agent's writes. When false (default; non-capture mode, or no
-    // observer), force CAS routing off and drop the blocked-secret sink so
-    // gitignored paths stay on the interrupt gate — a flowed gitignored edit on an
-    // unobserved backend would apply unobserved, unreviewable bytes. Sub-agent
-    // git-tracked edits are always captured by the backend-agnostic boundary diff.
+    // captureIgnored + recordBlockedSecret + captureDeleteBefore feed the SAME
+    // shared observer that backs the sub-agent's writes. When false (default;
+    // non-capture mode, or no observer), force CAS routing off and drop both
+    // observer sinks so gitignored paths stay on the interrupt gate — a flowed
+    // gitignored edit on an unobserved backend would apply unobserved,
+    // unreviewable bytes. Sub-agent git-tracked edits are always captured by
+    // the backend-agnostic boundary diff.
     stack.push(createApprovalGateMiddleware(
       options.captureIgnored
         ? options.approvalGate
-        : { ...options.approvalGate, captureIgnored: false, recordBlockedSecret: undefined },
+        : {
+            ...options.approvalGate,
+            captureIgnored: false,
+            recordBlockedSecret: undefined,
+            captureDeleteBefore: undefined,
+          },
     ));
   }