@stigmer/runner 3.32.0 → 3.34.0

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

@@ -40,6 +40,7 @@ import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
 import type { DynamicStructuredTool } from "@langchain/core/tools";
 import type { Command } from "@langchain/langgraph";
 import { createDeepAgent } from "deepagents";
+import { todoListMiddleware } from "langchain";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 import type { Config } from "../../config.js";
@@ -71,6 +72,7 @@ import { resolveRecursionLimit, UNBOUNDED_ADVISORY_RECURSION_LIMIT } from "../..
 import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
 import { CasCaptureObserver } from "./cas-capture-observer.js";
 import { createCasCaptureBackend } from "./cas-capture-backend.js";
+import { mountPlatformRoute } from "./platform-route.js";
 import { resolveResumeInput, type GraphStateSnapshot } from "./hitl.js";
 import { buildEnhancedSystemPrompt, composeUserMessage, renderSkillsSection } from "./prompt-builder.js";
 import { buildShellEnv } from "./shell-env.js";
@@ -454,8 +456,14 @@ export async function buildEngine(
   // File capture point: the CAS-observing backend — git-tracked edits flow to
   // disk (the boundary's git diff is authoritative) and the shared observer
   // records the pre-turn bytes of every CAS-owned path. Gate-independent, so
-  // it holds even under the global bypass.
-  const fileBackend = await createCasCaptureBackend({ rootDir: primaryDir, observer: workspace.casObserver, shellEnv });
+  // it holds even under the global bypass. Platform content (skills, inputs,
+  // the approved plan) is mounted over it read-only at `.stigmer/`
+  // (`platform-route.ts`): the virtual-rooted backend refuses to follow the
+  // workspace link out of the root.
+  const fileBackend = await mountPlatformRoute(
+    await createCasCaptureBackend({ rootDir: primaryDir, observer: workspace.casObserver, shellEnv }),
+    { workspaceDir: primaryDir, platformDir: workspace.backend.platformDir },
+  );
   const graph = await createDeepAgent({
     model,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -463,8 +471,14 @@ export async function buildEngine(
     backend: fileBackend,
     systemPrompt,
     tools: graphTools,
+    // The to-do list rides ahead of Stigmer's stack: deepagents stopped
+    // installing it by default (1.12), and the product reads it — the parent's
+    // `write_todos` is what `status.todos` projects and what plan mode's
+    // build progress is instructed through (`shared/implement-plan-prompt.ts`).
+    // The framework's own middleware, with its default texts. Parent only: a
+    // sub-agent's list never reaches the execution (`harness/transcript/builder.ts`).
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    middleware: middleware as any,
+    middleware: [todoListMiddleware(), ...middleware] as any,
     subagents: compiledSubagents ?? undefined,
     ...(responseFormat ? { responseFormat } : {}),
     ...(planModePermissions ? { permissions: planModePermissions } : {}),

package/src/middleware/index.ts

@@ -4,9 +4,9 @@
  * Assembles the ordered middleware array from a MiddlewareStackConfig. The
  * order is load-bearing and reads top to bottom:
  *
- *   0. Path normalization (conditional: only on permission-rule-bearing
- *      graphs — FIRST, so every downstream middleware observes canonical
- *      workspace-absolute paths)
+ *   0. Path normalization (whenever configured, which every graph does
+ *      since issue #754 — FIRST, so every downstream middleware observes
+ *      canonical workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always — advises at ~80% of the tool-round budget
  *      that LangGraph's `recursionLimit` enforces)
@@ -25,6 +25,10 @@
  * graceful-stop middleware and the cost cap's tool block were second stops
  * inside the graph that the runtime could not see).
  *
+ * Ahead of this stack the parent graph adds the framework's to-do list
+ * middleware (`execute-deep-agent/turn-setup.ts`): it is langchain's, not
+ * Stigmer's, and only the parent carries it.
+ *
  * The sub-agent stack is `execute-deep-agent/subagent-wiring.ts`'s: the same
  * order over the parent's shared instances where one exists (the advisory's
  * running total), fresh ones otherwise.

package/src/shared/workspace/__tests__/stigmer-link.test.ts

@@ -2,25 +2,29 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mkdtemp, mkdir, rm, writeFile, readFile, lstat, readlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { FilesystemBackend } from "deepagents";
 
 import {
   ensureStigmerSymlink,
   removeStigmerSymlink,
+  stigmerSymlinkPointsAt,
   STIGMER_LOCAL_STATE_DIR,
 } from "../stigmer-link.js";
 import { LocalWorkspaceBackend } from "../local-backend.js";
 
 /**
  * The `.stigmer` symlink is the bridge that makes platform-mounted content
- * (approved plan, skills, attachment inputs) readable by the agent's file
- * tools in BOTH harnesses. The lifecycle tests pin the ownership contract
- * (ensure replaces, remove is symlink-only); the convergence tests pin the
- * end-to-end physics the native harness depends on: content written through
- * the platform-routing LocalWorkspaceBackend must be readable at the same
- * `.stigmer/…` path through a stock deepagents FilesystemBackend rooted at
- * the workspace — which is exactly what broke when the native harness had no
- * symlink (the "plan file doesn't exist" bug).
+ * (approved plan, skills, attachment inputs) readable at `.stigmer/…` by
+ * whatever reads from the workspace: the Cursor SDK and shell commands on
+ * both harnesses. The lifecycle tests pin the ownership contract (ensure
+ * replaces, remove is symlink-only); the convergence tests pin the physics:
+ * content written through the platform-routing LocalWorkspaceBackend is
+ * readable at the same `.stigmer/…` path from inside the workspace once the
+ * link exists, and not before (the "plan file doesn't exist" bug).
+ *
+ * The native harness's FILE tools do not read through the link — their
+ * virtual-rooted backend refuses a path whose real location leaves the
+ * workspace — so their side of the convergence is pinned on the production
+ * backends in `activities/execute-deep-agent/__tests__/platform-route.test.ts`.
  */
 describe("stigmer-link", () => {
   let workspaceDir: string;
@@ -104,16 +108,35 @@ describe("stigmer-link", () => {
     });
   });
 
-  // ── Write/read convergence (the native-harness bug, pinned) ─────────
+  describe("stigmerSymlinkPointsAt", () => {
+    it("is true only while the link points at this platform dir", async () => {
+      expect(await stigmerSymlinkPointsAt(workspaceDir, platformDir), "no link yet").toBe(false);
+      await ensureStigmerSymlink(workspaceDir, platformDir);
+      expect(await stigmerSymlinkPointsAt(workspaceDir, platformDir)).toBe(true);
+      expect(await stigmerSymlinkPointsAt(workspaceDir, join(platformDir, "elsewhere")), "another dir").toBe(false);
+      await removeStigmerSymlink(workspaceDir);
+      expect(await stigmerSymlinkPointsAt(workspaceDir, platformDir), "removed at turn end").toBe(false);
+    });
+
+    it("is false for a real .stigmer directory", async () => {
+      await mkdir(linkPath());
+      expect(await stigmerSymlinkPointsAt(workspaceDir, platformDir)).toBe(false);
+    });
+  });
+
+  // ── Write/read convergence (the link, pinned) ─────────
 
   describe("platform write / agent read convergence", () => {
-    /** Read through the agent's actual file-tool backend. */
-    function agentRead(path: string): Promise<{ content?: string; error?: string }> {
-      const agentBackend = new FilesystemBackend({ rootDir: workspaceDir });
-      return agentBackend.read(path) as Promise<{ content?: string; error?: string }>;
+    /** Read the way a process in the workspace does (the shell, the Cursor SDK): a path relative to its CWD. */
+    async function agentRead(path: string): Promise<{ content?: string; error?: string }> {
+      try {
+        return { content: await readFile(join(workspaceDir, path), "utf8") };
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
     }
 
-    it("an approved plan mounted under .stigmer/inputs is readable by the deepagents backend once the link exists", async () => {
+    it("an approved plan mounted under .stigmer/inputs is readable from the workspace once the link exists", async () => {
       const planFileName = "notes_ab12cd34.plan.md";
       const planText = "# The Approved Plan\n\nStep 1: do the thing.\n";
 
@@ -125,9 +148,9 @@ describe("stigmer-link", () => {
       const workspaceBackend = new LocalWorkspaceBackend(workspaceDir, platformDir);
       await workspaceBackend.writeFile(`.stigmer/inputs/${planFileName}`, planText);
 
-      // Without the symlink the agent cannot see the plan — the bug this
-      // module fixes for the native harness. Pinned so the link stays
-      // load-bearing in reviewers' and agents' mental models.
+      // Without the symlink nothing in the workspace can see the plan — the
+      // bug this module fixes. Pinned so the link stays load-bearing in
+      // reviewers' and agents' mental models.
       const before = await agentRead(`.stigmer/inputs/${planFileName}`);
       expect(before.content ?? "").not.toContain("The Approved Plan");
 

package/src/shared/workspace/stigmer-link.ts

@@ -7,10 +7,14 @@
  * physically lives in the platform dir, outside the workspace, so a real repo
  * is never polluted with Stigmer files (issue #173). But the agent reads from
  * the workspace: the Cursor SDK resolves paths against the workspace CWD, and
- * the native (deepagents) harness's file tools resolve against a
- * `FilesystemBackend` rooted at the workspace. The symlink is what makes the
+ * shell commands on both harnesses run there. The symlink is what makes the
  * `.stigmer/…` paths those agents are prompted with (skill locations,
- * `.stigmer/inputs/…` attachments) actually resolve.
+ * `.stigmer/inputs/…` attachments) actually resolve. The native harness's
+ * FILE tools are the exception: their virtual-rooted backend refuses a path
+ * whose real location leaves the workspace, so they read the platform dir
+ * through a read-only `.stigmer/` route instead
+ * (`activities/execute-deep-agent/platform-route.ts`), mounted on exactly
+ * the turns this link exists ({@link stigmerSymlinkPointsAt}).
  *
  * Lifecycle contract (same for both harnesses):
  * - Created per turn, under the workspace turn lock — the link is a
@@ -70,6 +74,21 @@ export async function ensureStigmerSymlink(
   await symlink(platformDir, linkPath, "dir");
 }
 
+/**
+ * Whether the workspace's `.stigmer` is, right now, the link
+ * {@link ensureStigmerSymlink} makes to `platformDir`. A turn that mounts no
+ * skill and no attachment creates no link, so this is also "does this turn
+ * expose platform content at all" — the native harness mounts its read-only
+ * `.stigmer/` route on exactly the turns where the link would resolve.
+ */
+export async function stigmerSymlinkPointsAt(workspaceDir: string, platformDir: string): Promise<boolean> {
+  try {
+    return (await readlink(join(workspaceDir, STIGMER_LOCAL_STATE_DIR))) === platformDir;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Remove the workspace `.stigmer` symlink created by
  * {@link ensureStigmerSymlink}.

package/src/shared/workspace/types.ts

@@ -54,9 +54,10 @@ export class WorkspaceProvisionError extends Error {
  * routed to the platform directory instead of the workspace root, keeping
  * platform files (skills, inputs) physically separate from the user's
  * workspace. The routing covers the RUNNER's own reads/writes through
- * this interface; the agent's file tools resolve against the workspace
- * root and see the same files through the per-turn `.stigmer` symlink
- * (see stigmer-link.ts).
+ * this interface; the agent sees the same files through the per-turn
+ * `.stigmer` symlink (see stigmer-link.ts), and the native file tools
+ * through their read-only `.stigmer/` route over the same dir
+ * (`activities/execute-deep-agent/platform-route.ts`).
  */
 export interface WorkspaceBackend {
   readonly rootDir: string;