@stigmer/runner 3.36.0 → 3.37.0

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

@@ -22,7 +22,7 @@
  * - Empty subagent list returns null (no subagents configured)
  */
 
-import { createDeepAgent, FilesystemBackend, LocalShellBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT } from "deepagents";
+import { createDeepAgent, FilesystemBackend, LocalShellBackend, DEFAULT_SUBAGENT_PROMPT } from "deepagents";
 import type { AnyBackendProtocol, CompiledSubAgent, FilesystemPermission } from "deepagents";
 import type { StructuredTool } from "@langchain/core/tools";
 import type { RunnableConfig } from "@langchain/core/runnables";
@@ -42,6 +42,7 @@ import { SubAgentGate } from "../../shared/subagent-gate.js";
 import { isModelRegistered } from "../../shared/model-registry.js";
 import type { SkillMetadata } from "../../shared/skill-resolver.js";
 import { renderSkillsSection } from "./prompt-builder.js";
+import { ENGINE_TOOL } from "./engine-tools.js";
 
 // =========================================================================
 // Built-in subagent types and prompts
@@ -53,33 +54,44 @@ export const BUILTIN_SUBAGENT_TYPES: ReadonlySet<string> = new Set([
   "general-purpose",
 ]);
 
+// The task arrives as the sub-agent's first message (deepagents' `task`
+// tool), so a prompt carries no slot for it. Tool names come from the one
+// table of bound names (`engine-tools.ts`).
 const EXPLORE_SYSTEM_PROMPT = `\
 You are an exploration specialist. Your ONLY job is to explore codebases \
 and report findings back to the parent agent.
 
 STRICT BOUNDARIES:
-- Use ONLY the read-only tools provided (read_file, list_dir, glob, grep, search)
+- Use ONLY the read-only tools (${ENGINE_TOOL.readFile}, ${ENGINE_TOOL.ls}, ${ENGINE_TOOL.glob}, ${ENGINE_TOOL.grep})
 - Do NOT write files, create files, or modify anything
 - Do NOT execute shell commands
 - Do NOT follow skill activation instructions from any context
 - Do NOT create deliverables, scaffolds, or run initialization scripts
-- Report your findings concisely — the parent agent has direct file access
-
-Your task: {description}`;
+- Report your findings concisely — the parent agent has direct file access`;
 
 const SHELL_SYSTEM_PROMPT = `\
 You are a command execution specialist. Your ONLY job is to run shell \
 commands and report the results back to the parent agent.
 
 STRICT BOUNDARIES:
-- Use ONLY the tools provided (execute, read_file, list_dir)
+- Use ONLY ${ENGINE_TOOL.execute}, ${ENGINE_TOOL.readFile} and ${ENGINE_TOOL.ls}
 - Do NOT write or modify files directly — use shell commands if needed
 - Do NOT search extensively or explore the codebase beyond what is needed
 - Do NOT follow skill activation instructions from any context
 - Do NOT create deliverables, scaffolds, or run initialization scripts
-- Report command output concisely — the parent agent will interpret results
+- Report command output concisely — the parent agent will interpret results`;
 
-Your task: {description}`;
+/**
+ * The general-purpose sub-agent's line in the `task` tool. Stigmer's own
+ * words rather than upstream's `DEFAULT_GENERAL_PURPOSE_DESCRIPTION`, which
+ * invites delegating a search ("use this agent to perform the search for
+ * you") that the parent's working rules tell it to do itself
+ * (`prompt-builder.ts`): each delegation is a sub-agent's own rounds on top
+ * of the parent's.
+ */
+const GENERAL_PURPOSE_DESCRIPTION =
+  "Runs a multi-step task with the same tools as you, in its own context, and returns one report. " +
+  "Use it only for independent work you need as a summary.";
 
 const BUILTIN_DESCRIPTIONS: ReadonlyMap<string, string> = new Map([
   ["explore", (
@@ -102,8 +114,8 @@ const RESPONSE_RULES = `\
 
 ## Response rules
 
-- After using the read tool, NEVER reprint, echo, list, or \
-summarize file contents in your response. Tool results are \
+- After reading a file with ${ENGINE_TOOL.readFile}, NEVER reprint, echo, \
+list, or summarize file contents in your response. Tool results are \
 already in your context. Proceed directly to the task.
 - Your response is returned to the parent agent as a task \
 result. Return concise findings and actionable results — not \
@@ -215,8 +227,11 @@ export interface SubagentTransformOptions {
  * general-purpose is the gated replacement for the sub-agent deepagents would
  * otherwise auto-inject WITHOUT our approval gate (suppressed process-wide in
  * deepagents-profiles.ts; supplying our own under the same name is the
- * documented override path). It uses deepagents' own description/prompt so the
- * model's delegation behavior is unchanged, and receives the parent's MCP tools
+ * documented override path). It keeps deepagents' own prompt, but its line in
+ * the `task` tool is Stigmer's ({@link GENERAL_PURPOSE_DESCRIPTION}): it was
+ * upstream's while the goal was parity with the suppressed original, and
+ * upstream's invites the delegation the parent's rules advise against. It
+ * receives the parent's MCP tools
  * for capability parity with the injected original. Conscious simplification:
  * the parent's skills prompt is NOT inherited — a sub-agent needing skills
  * should be declared explicitly in the Agent spec.
@@ -239,7 +254,7 @@ export function createBuiltinSubagents(
     if (subagentType === "general-purpose") {
       result.push({
         name: "general-purpose",
-        description: DEFAULT_GENERAL_PURPOSE_DESCRIPTION,
+        description: GENERAL_PURPOSE_DESCRIPTION,
         systemPrompt: DEFAULT_SUBAGENT_PROMPT + RESPONSE_RULES,
         // Parent-parity tool set: MCP tools plus the native web_fetch the
         // parent always carries. explore/shell stay web-less on purpose —

package/src/activities/execute-deep-agent/todo-list.ts

@@ -0,0 +1,56 @@
+/**
+ * The parent's to-do list: langchain's `todoListMiddleware`, with Stigmer's
+ * words for its tool and its system line.
+ *
+ * Why the middleware and not our own: it owns the `todos` state channel, the
+ * tool, and the refusal of two list updates in one response, and the
+ * product reads what it writes (the parent's `write_todos` is what
+ * `status.todos` projects and what the clients' progress card renders,
+ * `harness/transcript/builder.ts`, `shared/todos.ts`). Parent only: a
+ * sub-agent's list never reaches the execution.
+ *
+ * Why our own words: langchain's defaults are an 11.4 KB tool description
+ * and a 1 KB system block, sent on every model call of every turn whether
+ * or not a list is kept, and they ask for the list to be updated "as soon
+ * as you are done with a step. Do not batch", which the benchmark's
+ * per-call record showed as one model call per update, five of seventeen on
+ * a multi-part task. These texts keep what the product relies on (a list for
+ * work of several parts, the three states the card shows, one item in
+ * progress) and make each update ride with another tool call.
+ *
+ * The threshold is "several separate parts", not a step count: a first cut
+ * said "three or more distinct steps", and the model then kept a list on a
+ * one-change edit (read, edit, test) with every update in a round of its
+ * own. A soft "update with your next action" was not followed either, so
+ * the rule names the call's company outright.
+ *
+ * Plan mode's build progress names no tool: its directive says "your to-do
+ * list" (`shared/implement-plan-prompt.ts`) and leaves each harness's tool
+ * to say what it is, so the description opens by saying exactly that.
+ *
+ * The system line cannot be empty: the middleware appends it as a block of
+ * its own, and an empty option would still send a whitespace block.
+ */
+
+import { todoListMiddleware } from "langchain";
+import { ENGINE_TOOL } from "./engine-tools.js";
+
+/** The to-do tool's description, as the model reads it. */
+export const TODO_TOOL_DESCRIPTION =
+  "Your to-do list, shown to the user as your progress. Use it when a request has several separate parts, " +
+  "or when the user asks for one. Skip it for a single change, however many steps it takes, and for questions.\n" +
+  "- Send the whole list each time. Each item is pending, in_progress or completed; keep exactly one " +
+  "in_progress while you work.\n" +
+  `- A \`${ENGINE_TOOL.writeTodos}\` call always shares its response with another tool call: update the list ` +
+  "alongside your next action, never in a response of its own, and send the last update with your last tool call.\n" +
+  "- Call this tool at most once per response.";
+
+/** The line the middleware adds to the system prompt. */
+export const TODO_SYSTEM_PROMPT =
+  `Keep a to-do list with \`${ENGINE_TOOL.writeTodos}\` when a request has several separate parts; ` +
+  "the user sees it as your progress.";
+
+/** The parent graph's to-do middleware, with Stigmer's texts. */
+export function createTodoListMiddleware(): ReturnType<typeof todoListMiddleware> {
+  return todoListMiddleware({ toolDescription: TODO_TOOL_DESCRIPTION, systemPrompt: TODO_SYSTEM_PROMPT });
+}

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

@@ -40,7 +40,6 @@ 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";
@@ -77,6 +76,7 @@ import { resolveResumeInput, type GraphStateSnapshot } from "./hitl.js";
 import { buildEnhancedSystemPrompt, composeUserMessage, renderSkillsSection } from "./prompt-builder.js";
 import { buildShellEnv } from "./shell-env.js";
 import { modelHasNativeThinking, transformAndCompileSubagents } from "./subagent-transformer.js";
+import { createTodoListMiddleware } from "./todo-list.js";
 
 /**
  * The runner config this harness reads per turn, as a named slice
@@ -472,13 +472,11 @@ export async function buildEngine(
     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`).
+    // installing it by default (1.12), and the product reads it. The
+    // framework's own middleware with Stigmer's texts; parent only
+    // (`todo-list.ts` says why for both).
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    middleware: [todoListMiddleware(), ...middleware] as any,
+    middleware: [createTodoListMiddleware(), ...middleware] as any,
     subagents: compiledSubagents ?? undefined,
     ...(responseFormat ? { responseFormat } : {}),
     ...(planModePermissions ? { permissions: planModePermissions } : {}),

package/src/middleware/__tests__/path-normalization.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import { ToolMessage } from "@langchain/core/messages";
 import {
   createPathNormalizationMiddleware,
+  normalizeGlobPattern,
   normalizeWorkspacePathArg,
 } from "../path-normalization.js";
 import type { ToolCallRequest } from "../types.js";
@@ -110,6 +111,23 @@ describe("createPathNormalizationMiddleware", () => {
     }
   });
 
+  it("maps a glob pattern that opens with the real root to its virtual form", async () => {
+    const args = await argsSeenByHandler("glob", { pattern: `${ROOT}/duration/*_test.go` });
+    expect(args.pattern).toBe("/duration/*_test.go");
+  });
+
+  it("repairs the glob pattern and the base path of one call together", async () => {
+    const args = await argsSeenByHandler("glob", { path: `${ROOT}/src`, pattern: `${ROOT}/src/**/*.go` });
+    expect(args.path).toBe("/src");
+    expect(args.pattern).toBe("/src/**/*.go");
+  });
+
+  it("rewrites a real-root prefix in glob's pattern only, never in grep's", async () => {
+    // grep's pattern is literal text to find, which may well be a path.
+    const args = await argsSeenByHandler("grep", { pattern: `${ROOT}/config` });
+    expect(args.pattern).toBe(`${ROOT}/config`);
+  });
+
   it("passes canonical virtual paths through byte-untouched", async () => {
     const args = await argsSeenByHandler("read_file", { file_path: "/etc/hosts" });
     expect(args.file_path).toBe("/etc/hosts");
@@ -164,3 +182,17 @@ describe("createPathNormalizationMiddleware", () => {
     expect(original.toolCall.args.file_path).toBe("notes.md");
   });
 });
+
+describe("normalizeGlobPattern", () => {
+  it("replaces a whole leading root, keeping every wildcard", () => {
+    expect(normalizeGlobPattern(`${ROOT}/**/*.md`, ROOT)).toBe("/**/*.md");
+    expect(normalizeGlobPattern(`${ROOT}/a/*.go`, `${ROOT}/`)).toBe("/a/*.go");
+  });
+
+  it("leaves a pattern that only resembles the root, or is the root itself", () => {
+    expect(normalizeGlobPattern("**/*.go", ROOT)).toBeUndefined();
+    expect(normalizeGlobPattern(`${ROOT}-other/*.go`, ROOT)).toBeUndefined();
+    expect(normalizeGlobPattern(`${ROOT}/`, ROOT)).toBeUndefined();
+    expect(normalizeGlobPattern(`/x${ROOT}/a`, ROOT)).toBeUndefined();
+  });
+});

package/src/middleware/error-hints.ts

@@ -37,10 +37,10 @@ export function enrichErrorMessage(toolName: string, error: string): string {
   }
 
   if (errorLower.includes("text to replace not found")) {
-    hints.push("Re-read the file with the read tool to see its current contents");
-    hints.push("The file content may have changed — use the actual text from read output");
+    hints.push("Re-read the file to see its current contents");
+    hints.push("The file content may have changed — use the actual text from the read output");
     hints.push("Check for whitespace differences (tabs vs spaces, trailing newlines)");
-    hints.push("If the exact text cannot be matched, use write to replace the entire file");
+    hints.push("If the exact text cannot be matched, write the whole file instead");
   }
 
   if (toolLower.includes("edit") || toolLower.includes("write")) {

package/src/middleware/path-normalization.ts

@@ -19,7 +19,13 @@
  *    filesystem paths that a model may still echo back;
  *  - interior `..` segments that stay inside the root ("src/../notes.md" →
  *    "/notes.md") — the virtual resolver rejects `..` outright, so a safe
- *    interior collapse is repaired here rather than burning a tool round.
+ *    interior collapse is repaired here rather than burning a tool round;
+ *  - a `glob` PATTERN that opens with the real root ("{root}/src/*.go") to
+ *    its virtual form ("/src/*.go"). deepagents strips a pattern's leading
+ *    "/" and matches the rest under the search path, so a real-root pattern
+ *    silently matches nothing and the model goes looking with `ls`; the
+ *    benchmark's per-call record showed it doing so for three rounds. Only
+ *    that exact prefix is rewritten, never the pattern's wildcards.
  *
  * Nothing becomes newly reachable: escaping relatives ("../x") and
  * `~`-carrying paths are left raw so the upstream refusal keeps speaking,
@@ -38,9 +44,9 @@
  *
  * Tool matching is by bare built-in name, the house doctrine (an MCP server
  * is not expected to shadow a built-in name — see shared/tool-kind.ts); the
- * rewrite touches only the tool's path-bearing argument, never glob/grep
- * patterns. Install FIRST in the stack so every downstream middleware
- * observes canonical paths.
+ * rewrite touches the tool's path-bearing argument and, for `glob`, a
+ * real-root prefix of the pattern; nothing else in a pattern. Install FIRST
+ * in the stack so every downstream middleware observes canonical paths.
  */
 
 import { isAbsolute, relative, posix } from "node:path";
@@ -60,6 +66,10 @@ const PATH_ARG_BY_TOOL: ReadonlyMap<string, string> = new Map([
   ["edit_file", "file_path"],
 ]);
 
+/** The one built-in whose pattern can carry a path prefix, and its argument. */
+const GLOB_TOOL = "glob";
+const GLOB_PATTERN_ARG = "pattern";
+
 export interface PathNormalizationConfig {
   /**
    * The REAL workspace root the graph's backend is rooted at — used only for
@@ -116,6 +126,19 @@ export function normalizeWorkspacePathArg(
   return virtual === raw ? undefined : virtual;
 }
 
+/**
+ * Rewrite a `glob` pattern that opens with the real workspace root to its
+ * virtual form, or return undefined to leave it untouched. Only a whole
+ * leading `{root}/` is replaced; a pattern that merely contains the root's
+ * text elsewhere, or is the root itself, is left as the model wrote it.
+ * Exported for direct unit testing.
+ */
+export function normalizeGlobPattern(pattern: string, rootDir: string): string | undefined {
+  const prefix = rootDir.endsWith("/") ? rootDir : `${rootDir}/`;
+  if (!pattern.startsWith(prefix) || pattern.length === prefix.length) return undefined;
+  return `/${pattern.slice(prefix.length)}`;
+}
+
 /**
  * Create the dialect-repair middleware (see module header). Stateless per
  * request; safe on every graph.
@@ -132,18 +155,23 @@ export function createPathNormalizationMiddleware(
       const argKey = PATH_ARG_BY_TOOL.get(request.toolCall.name);
       if (!argKey) return handler(request);
 
-      const raw = request.toolCall.args[argKey];
-      if (typeof raw !== "string") return handler(request);
-
-      const normalized = normalizeWorkspacePathArg(raw, rootDir);
-      if (normalized === undefined) return handler(request);
+      const args = request.toolCall.args;
+      const rewritten: Record<string, string> = {};
+      const raw = args[argKey];
+      if (typeof raw === "string") {
+        const normalized = normalizeWorkspacePathArg(raw, rootDir);
+        if (normalized !== undefined) rewritten[argKey] = normalized;
+      }
+      const pattern = args[GLOB_PATTERN_ARG];
+      if (request.toolCall.name === GLOB_TOOL && typeof pattern === "string") {
+        const normalized = normalizeGlobPattern(pattern, rootDir);
+        if (normalized !== undefined) rewritten[GLOB_PATTERN_ARG] = normalized;
+      }
+      if (Object.keys(rewritten).length === 0) return handler(request);
 
       return handler({
         ...request,
-        toolCall: {
-          ...request.toolCall,
-          args: { ...request.toolCall.args, [argKey]: normalized },
-        },
+        toolCall: { ...request.toolCall, args: { ...args, ...rewritten } },
       });
     },
   };

package/src/shared/subagent-gate.ts

@@ -13,7 +13,12 @@
 
 import { RunnableLambda, type RunnableConfig } from "@langchain/core/runnables";
 
-const DEFAULT_MAX_CONCURRENT = 3;
+/**
+ * How many sub-agents run at once by default. The native prompt states this
+ * number to the model (`execute-deep-agent/prompt-builder.ts`), so it has one
+ * home: this constant.
+ */
+export const DEFAULT_MAX_CONCURRENT = 3;
 
 export interface SubAgentGateOptions {
   readonly maxConcurrent?: number;

package/src/shared/workspace/sources/local-path.ts

@@ -63,8 +63,12 @@ export function provisionLocalPath(options: LocalPathProvisionOptions): Provisio
     rootDir: path,
     sourceType: "local_path",
     consumedKeys: [],
+    // No host path in the model's text: the native file tools see this
+    // directory as `/` and its commands run in it, so the path would only be
+    // echoed back where it cannot resolve (a glob pattern, a mistyped
+    // prefix). The directory is `rootDir`'s to carry.
     workspaceDescription:
-      `Your workspace is the user's project directory: ${path}\n` +
+      "Your workspace is the user's project directory.\n" +
       "IMPORTANT: You are operating directly on the user's files. " +
       "Changes are immediate and persistent.\n" +
       "Use git to track and verify your changes before finalizing.",

package/src/tools/__tests__/think-tool.test.ts

@@ -7,9 +7,10 @@ describe("createThinkTool", () => {
     expect(thinkTool.name).toBe("think");
   });
 
-  it("has a description explaining its purpose", () => {
+  it("keeps its description short: it rides on every model call, and every use is a round", () => {
     const thinkTool = createThinkTool();
-    expect(thinkTool.description).toContain("think through a problem");
+    expect(thinkTool.description.length).toBeGreaterThan(0);
+    expect(thinkTool.description.length).toBeLessThan(400);
   });
 
   it("returns 'ok' for any thought input", async () => {

package/src/tools/think-tool.ts

@@ -8,6 +8,13 @@
  *
  * Follows the Anthropic "think tool" pattern:
  * https://www.anthropic.com/engineering/claude-think-tool
+ *
+ * The description says when a call is worth it, because every call is a
+ * model round of its own: the whole prompt re-sent for a thought. The
+ * earlier text suggested one "after reading files or tool output", and the
+ * benchmark's per-call record showed think rounds right after reads and
+ * right before the reply. Whether the tool is bound at all is the thinking
+ * mode's question, not this module's.
  */
 
 import { tool } from "@langchain/core/tools";
@@ -19,17 +26,9 @@ export function createThinkTool() {
     {
       name: "think",
       description:
-        "Use this tool to think through a problem step-by-step. " +
-        "The think tool does not read files, execute commands, or make any changes — " +
-        "it simply records your reasoning. Call it when you need to pause and work " +
-        "something out before acting.\n\n" +
-        "Good times to use think:\n" +
-        "- After reading files or tool output, to analyse what you learned\n" +
-        "- Before a complex or multi-step operation, to plan your approach\n" +
-        "- When you need to choose between several possible strategies\n" +
-        "- When debugging — to reason about what might have gone wrong\n\n" +
-        "You do NOT need to use think for every step — only when genuine " +
-        "reasoning will improve the quality of your next action.",
+        "Record your reasoning when a decision is genuinely hard: choosing between approaches, " +
+        "or working out why something failed. It reads nothing and changes nothing. Do not use it " +
+        "to restate a tool result or to announce your next step; take the step.",
       schema: z.object({
         thought: z.string().describe("Your reasoning, analysis, or plan."),
       }),