@stigmer/runner 3.36.0 → 3.37.1

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/__tests__/model-client-sampling.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The native execution turn's request against the REAL @langchain/anthropic
+ * (stigmer/stigmer#1341): the unit suite in model-client.test.ts mocks the
+ * wrapper, so it cannot see the wrapper's own parameter validation. That
+ * validation is what failed every native turn on claude-opus-4.7,
+ * claude-opus-4.8 and claude-fable-5 while the runner pinned temperature 0.
+ * These tests build the client the way the execution turn does and read the
+ * request parameters offline; no request leaves the process.
+ */
+import { ChatAnthropic } from "@langchain/anthropic";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { buildChatModel } from "../model-client.js";
+import { _resetRegistryCache } from "../model-registry.js";
+
+// Ids the wrapper treats as adaptive-only and refuses a sampling override
+// for, and ids it lets one through for (the provider itself refuses it on
+// claude-sonnet-5); the registry is unreachable in these tests, so each id
+// reaches the wrapper unchanged.
+const ADAPTIVE_ONLY_IDS = ["claude-opus-4-7", "claude-opus-4-8", "claude-fable-5"];
+const SAMPLING_TOLERANT_IDS = ["claude-sonnet-4-6", "claude-opus-4-6", "claude-sonnet-5", "claude-haiku-4-5-20251001"];
+
+async function executionTurnParams(modelName: string, temperature: number | null | undefined) {
+  const { model } = await buildChatModel({
+    modelName,
+    proxyEndpoint: "http://127.0.0.1:9",
+    stigmerToken: "sampling-test",
+    temperature,
+  });
+  return (model as ChatAnthropic).invocationParams({});
+}
+
+describe("the native execution turn's sampling parameters (real @langchain/anthropic)", () => {
+  beforeEach(() => {
+    _resetRegistryCache();
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("registry unreachable in this test"));
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    _resetRegistryCache();
+    vi.restoreAllMocks();
+  });
+
+  it.each(ADAPTIVE_ONLY_IDS)("%s: the pinned temperature 0 is refused before any request", async (id) => {
+    await expect(executionTurnParams(id, undefined)).rejects.toThrow(/temperature is not supported/);
+  });
+
+  it.each([...ADAPTIVE_ONLY_IDS, ...SAMPLING_TOLERANT_IDS])(
+    "%s: with no temperature the request builds and carries no sampling override",
+    async (id) => {
+      const params = await executionTurnParams(id, null);
+      expect(params).not.toHaveProperty("temperature");
+    },
+  );
+});

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

@@ -156,6 +156,21 @@ describe("buildChatModel", () => {
     expect(lastAnthropicArgs()).toMatchObject({ maxTokens: 4096 });
   });
 
+  it("pins temperature 0 by default, and sends none when the caller passes null", async () => {
+    mockRegistryResponse([
+      { id: "claude-opus-4.8", apiModelId: "claude-opus-4-8", provider: "anthropic" },
+    ]);
+
+    await buildChatModel({ modelName: "claude-opus-4.8" });
+    expect(lastAnthropicArgs()).toMatchObject({ temperature: 0 });
+
+    await buildChatModel({ modelName: "claude-opus-4.8", temperature: 0.3 });
+    expect(lastAnthropicArgs()).toMatchObject({ temperature: 0.3 });
+
+    await buildChatModel({ modelName: "claude-opus-4.8", temperature: null });
+    expect(lastAnthropicArgs()).not.toHaveProperty("temperature");
+  });
+
   it("passes the model id through unchanged when the registry is unavailable", async () => {
     vi.spyOn(globalThis, "fetch").mockRejectedValueOnce(new Error("network down"));
 

package/src/shared/__tests__/worker-shutdown.test.ts

@@ -54,8 +54,8 @@ describe("classifyTurnInterruption", () => {
     expect(classifyTurnInterruption({ cancellationReason: undefined, shutdownSignalAborted: true })).toBe("none");
   });
 
-  it("a workflow-requested cancellation without a shutdown signal is the orchestrator's pause", () => {
-    expect(classifyTurnInterruption({ cancellationReason: "CANCELLED", shutdownSignalAborted: false })).toBe("pause");
+  it("a workflow-requested cancellation without a shutdown signal is the orchestrator's stop (a Pause or a Cancel, indistinguishable here)", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "CANCELLED", shutdownSignalAborted: false })).toBe("orchestrator-stop");
   });
 
   it("a delivered cancellation WITH the shutdown signal aborted is a worker shutdown, not a pause (the #776 misclassification)", () => {

package/src/shared/model-client.ts

@@ -53,8 +53,16 @@ export interface BuildChatModelOptions {
     mcpServerId?: string;
     workflowExecutionId?: string;
   };
-  /** Defaults to 0. */
-  readonly temperature?: number;
+  /**
+   * Defaults to 0. `null` sends no sampling override at all, so the
+   * provider's default applies: the native execution turn passes it,
+   * because current Anthropic models refuse a temperature other than their
+   * default (claude-opus-4.7 and later, claude-sonnet-5, claude-fable-5;
+   * @langchain/anthropic throws before the request for some of them) and
+   * the Cursor harness sends none either (stigmer/stigmer#1341). Utility
+   * calls keep their deterministic 0.
+   */
+  readonly temperature?: number | null;
   /**
    * Pass-through only; intentionally no default. Anthropic requires a value,
    * but callers differ (setup omits it, call-llm uses 4096), so the default
@@ -258,7 +266,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     ? { maxRetries: opts.maxRetries ?? 0 }
     : {};
   const common = {
-    temperature: opts.temperature ?? 0,
+    ...(opts.temperature === null ? {} : { temperature: opts.temperature ?? 0 }),
     apiKey,
     ...(maxTokens ? { maxTokens } : {}),
     ...maxRetries,

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/worker-shutdown.ts

@@ -1,12 +1,12 @@
 /**
  * Per-task-queue worker-shutdown signals — the classification channel that
  * lets an in-flight activity distinguish "my worker is shutting down" from
- * "the orchestrator cancelled me" (a user pause).
+ * "the orchestrator cancelled me" (a user's Pause or Cancel).
  *
  * The signal carries NO lifecycle authority: aborting it never stops a
  * worker or an activity (Temporal's own drain does that). It exists purely
  * so the activity's cancellation handling can classify the interruption
- * honestly — a shutdown is not a pause, and must surface as the
+ * honestly — a shutdown is not a user's stop, and must surface as the
  * worker-shutdown failure shape the control planes recognize (issue #776).
  *
  * Ownership contract:
@@ -88,13 +88,18 @@ export interface TurnInterruptionEvidence {
  * How Temporal's cancellation reads to the turn:
  *  - `worker-shutdown`: the runner is draining (the queue's signal, or the
  *    SDK's own `WORKER_SHUTDOWN`); FAILED with the shutdown copy, thrown.
- *  - `pause`: the workflow asked (`CANCELLED`, the Pause RPC's path);
- *    PAUSED, thrown.
+ *  - `orchestrator-stop`: the workflow asked (`CANCELLED`). That is a Pause
+ *    or a Cancel, and the turn cannot tell which: both reach the activity
+ *    as the same workflow-requested cancellation, and both RPCs signal the
+ *    engine before they persist the phase, so no stored fact tells them
+ *    apart in time. The turn settles its transcript with no phase and no
+ *    row, thrown; the workflow, which knows which stop it runs, writes the
+ *    phase and the stop row (stigmer#980).
  *  - `infrastructure`: the platform cancelled for its own reason (a heartbeat
  *    timeout, a closed run); FAILED with the unresponsive copy, thrown.
  *  - `none`: nothing was delivered.
  */
-export type TurnInterruption = "worker-shutdown" | "pause" | "infrastructure" | "none";
+export type TurnInterruption = "worker-shutdown" | "orchestrator-stop" | "infrastructure" | "none";
 
 /**
  * Classify how (whether) Temporal interrupted the turn, from the two live
@@ -125,5 +130,5 @@ export function classifyTurnInterruption(evidence: TurnInterruptionEvidence): Tu
   if (shutdownSignalAborted || cancellationReason === "WORKER_SHUTDOWN") {
     return "worker-shutdown";
   }
-  return cancellationReason === "CANCELLED" ? "pause" : "infrastructure";
+  return cancellationReason === "CANCELLED" ? "orchestrator-stop" : "infrastructure";
 }

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."),
       }),