@stigmer/runner 3.12.2 → 3.12.3

package/src/middleware/__tests__/tool-intent.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Tool-intent middleware (issue #276): the shell tool's bind-time schema
+ * gains an optional model-authored `description`, execution never sees it,
+ * and the argument survives verbatim into the message history.
+ *
+ * The integration block drives a REAL deepagents graph, because the two
+ * claims that matter most are framework claims: (1) `wrapModelCall` receives
+ * the library's built-in `execute` tool and the clone reaches `bindTools`,
+ * and (2) the original tool's strip-parsing drops the extra argument before
+ * the backend's `execute(command)` runs.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { z } from "zod";
+import { tool } from "@langchain/core/tools";
+import { convertToOpenAITool } from "@langchain/core/utils/function_calling";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent } from "deepagents";
+import {
+  createToolIntentMiddleware,
+  INTENT_ARG,
+  INTENT_ARG_PROMPT,
+} from "../tool-intent.js";
+import { buildSubAgentMiddleware } from "../../activities/execute-deep-agent/subagent-wiring.js";
+import { createCasCaptureBackend } from "../../activities/execute-deep-agent/cas-capture-backend.js";
+import { CasCaptureObserver } from "../../activities/execute-deep-agent/cas-capture-observer.js";
+import {
+  ScriptedModel,
+  type ScriptSelector,
+} from "../../activities/execute-deep-agent/__test-utils__/scripted-model.js";
+
+/** A stand-in for deepagents' `execute` tool: same name, same schema shape. */
+function makeShellTool(executed: string[]) {
+  return tool(
+    async ({ command }: { command: string }) => {
+      executed.push(command);
+      return "ok";
+    },
+    {
+      name: "execute",
+      description: "Run a shell command",
+      schema: z.object({ command: z.string().describe("The shell command to execute") }),
+    },
+  );
+}
+
+function makeReadTool() {
+  return tool(async () => "contents", {
+    name: "read_file",
+    description: "Read a file",
+    schema: z.object({ file_path: z.string() }),
+  });
+}
+
+type BoundSchema = {
+  type?: string;
+  properties?: Record<string, { type?: string; description?: string }>;
+  required?: string[];
+};
+
+function schemaOf(t: unknown): BoundSchema {
+  return (t as { schema: BoundSchema }).schema;
+}
+
+async function runWrap(
+  mw: ReturnType<typeof createToolIntentMiddleware>,
+  tools: unknown[],
+): Promise<unknown[]> {
+  let seen: unknown[] = [];
+  const handler = vi.fn(async (req: { tools?: unknown[] }) => {
+    seen = req.tools ?? [];
+    return new AIMessage({ content: "" });
+  });
+  await mw.wrapModelCall!(
+    { model: {}, messages: [], tools, state: {}, runtime: {} } as never,
+    handler as never,
+  );
+  return seen;
+}
+
+describe("ToolIntentMiddleware (unit)", () => {
+  it("passes a tool-less request through untouched", async () => {
+    const mw = createToolIntentMiddleware();
+    const request = { model: {}, messages: [], state: {}, runtime: {} } as never;
+    const handler = vi.fn(async () => new AIMessage({ content: "" }));
+    await mw.wrapModelCall!(request, handler as never);
+    expect(handler).toHaveBeenCalledWith(request);
+  });
+
+  it("extends the shell tool's bound schema with the optional intent arg", async () => {
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [shell]);
+
+    expect(bound).toHaveLength(1);
+    expect(bound[0]).not.toBe(shell);
+    const schema = schemaOf(bound[0]);
+    expect(schema.properties?.command?.type).toBe("string");
+    expect(schema.properties?.[INTENT_ARG]).toEqual({
+      type: "string",
+      description: INTENT_ARG_PROMPT,
+    });
+    // Optional by construction: required is untouched.
+    expect(schema.required ?? []).not.toContain(INTENT_ARG);
+  });
+
+  it("passes non-shell tools through by reference", async () => {
+    const read = makeReadTool();
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [read, shell]);
+    expect(bound[0]).toBe(read);
+    expect(bound[1]).not.toBe(shell);
+  });
+
+  it("never shadows a real argument named like the intent arg", async () => {
+    const conflicting = tool(async () => "ok", {
+      name: "shell",
+      description: "A shell tool that already has a description arg",
+      schema: z.object({ command: z.string(), [INTENT_ARG]: z.string() }),
+    });
+    const bound = await runWrap(createToolIntentMiddleware(), [conflicting]);
+    expect(bound[0]).toBe(conflicting);
+  });
+
+  it("passes through tools whose schema is not an object schema", async () => {
+    const odd = { name: "bash", description: "odd", schema: 42 };
+    const bound = await runWrap(createToolIntentMiddleware(), [odd]);
+    expect(bound[0]).toBe(odd);
+  });
+
+  it("reuses one clone across model calls (referential stability)", async () => {
+    const mw = createToolIntentMiddleware();
+    const shell = makeShellTool([]);
+    const first = await runWrap(mw, [shell]);
+    const second = await runWrap(mw, [shell]);
+    expect(first[0]).toBe(second[0]);
+  });
+
+  it("emits a non-executable declaration that provider converters accept", async () => {
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [shell]);
+    const declaration = bound[0] as Record<string, unknown>;
+
+    // Deliberately NOT an executable tool — the agent's validation forbids
+    // swapping same-name executable instances, and execution belongs to the
+    // registered original. StructuredToolParams is the sanctioned shape.
+    expect(declaration.invoke).toBeUndefined();
+
+    // The shape every provider's bindTools converts like a structured tool.
+    const openAiTool = convertToOpenAITool(declaration as never) as {
+      function: { name: string; parameters: { properties: Record<string, unknown> } };
+    };
+    expect(openAiTool.function.name).toBe("execute");
+    expect(openAiTool.function.parameters.properties[INTENT_ARG]).toEqual({
+      type: "string",
+      description: INTENT_ARG_PROMPT,
+    });
+    expect(openAiTool.function.parameters.properties.command).toBeDefined();
+  });
+
+  it("is idempotent: an already-extended declaration passes through", async () => {
+    const mw = createToolIntentMiddleware();
+    const shell = makeShellTool([]);
+    const [firstPass] = await runWrap(mw, [shell]);
+    // A second middleware instance (e.g. a sub-agent stack composed over the
+    // same request) must not re-wrap the extended declaration.
+    const [secondPass] = await runWrap(createToolIntentMiddleware(), [firstPass]);
+    expect(secondPass).toBe(firstPass);
+  });
+});
+
+describe("ToolIntentMiddleware (real deepagents graph)", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "tool-intent-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("binds the extended execute schema to the model and strips the arg at execution", async () => {
+    const marker = join(root, "intent-marker.txt");
+    const script: ScriptSelector = () => ({
+      toolCalls: [{
+        name: "execute",
+        args: {
+          command: "echo ran > intent-marker.txt",
+          [INTENT_ARG]: "Write the marker file",
+        },
+        id: "exec_intent_1",
+      }],
+      done: "done",
+    });
+    const model = new ScriptedModel(script);
+
+    const observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => false });
+    const backend = await createCasCaptureBackend({ rootDir: root, observer, shellEnv: {} });
+
+    const checkpointer = new MemorySaver();
+    const agent = await createDeepAgent({
+      model,
+      checkpointer: checkpointer as never,
+      backend,
+      middleware: [createToolIntentMiddleware()],
+    } as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "intent-thread" }, recursionLimit: 50 };
+    await agent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    // (1) The model saw the library's execute tool WITH the intent arg.
+    const boundExecute = model.boundTools.find(
+      (t) => (t as { name?: string }).name === "execute",
+    );
+    expect(boundExecute).toBeDefined();
+    const schema = schemaOf(boundExecute);
+    expect(schema.properties?.[INTENT_ARG]?.description).toBe(INTENT_ARG_PROMPT);
+    expect(schema.properties?.command).toBeDefined();
+    expect(schema.required ?? []).not.toContain(INTENT_ARG);
+
+    // (2) Execution ran the ORIGINAL tool: strip semantics dropped the intent
+    // arg and the command executed normally.
+    expect(await readFile(marker, "utf8")).toBe("ran\n");
+
+    // (3) The intent arg survived verbatim in the message history — the
+    // exact bytes the status builder persists onto ToolCall.args.
+    const state = (await agent.getState(config)) as unknown as {
+      values: { messages: Array<{ tool_calls?: Array<{ name: string; args: Record<string, unknown> }> }> };
+    };
+    const messages = state.values.messages;
+    const toolCall = messages
+      .flatMap((m) => m.tool_calls ?? [])
+      .find((tc) => tc.name === "execute");
+    expect(toolCall).toBeDefined();
+    expect(toolCall!.args[INTENT_ARG]).toBe("Write the marker file");
+    expect(toolCall!.args.command).toBe("echo ran > intent-marker.txt");
+  });
+});
+
+describe("sub-agent stack wiring", () => {
+  it("includes the tool-intent middleware in every sub-agent stack", () => {
+    const stack = buildSubAgentMiddleware({});
+    expect(stack.map((m) => m.name)).toContain("StigmerToolIntentMiddleware");
+  });
+});
+
+describe("wire-contract fixture", () => {
+  it("INTENT_ARG matches the cross-surface fixture key the SDK reads", () => {
+    // The reader side (sdk/react intent-title tests) asserts against the
+    // same file, so the writer and readers cannot drift apart silently.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const fixture = JSON.parse(
+      readFileSync(
+        resolve(here, "../../../../../../test/fixtures/tool-view/intent-title.json"),
+        "utf8",
+      ),
+    ) as { argField: string };
+    expect(INTENT_ARG).toBe(fixture.argField);
+  });
+});

package/src/middleware/index.ts

@@ -9,11 +9,12 @@
  *      workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always)
- *   3. Tool truncation (always)
- *   4. Graceful stop (always, inert until activated)
- *   5. Cost cap (conditional: only when maxCostUsd > 0)
- *   6. Error hints (always)
- *   7. OTel spans (always, no-op when OTel not configured)
+ *   3. Tool intent (always — bind-time shell schema extension, issue #276)
+ *   4. Tool truncation (always)
+ *   5. Graceful stop (always, inert until activated)
+ *   6. Cost cap (conditional: only when maxCostUsd > 0)
+ *   7. Error hints (always)
+ *   8. OTel spans (always, no-op when OTel not configured)
  */
 
 import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
@@ -21,6 +22,7 @@ import type { GracefulStopMiddleware } from "./graceful-stop.js";
 import { createPathNormalizationMiddleware } from "./path-normalization.js";
 import { createLoopDetectionMiddleware } from "./loop-detection.js";
 import { createExecutionBudgetMiddleware } from "./execution-budget.js";
+import { createToolIntentMiddleware } from "./tool-intent.js";
 import { createToolTruncationMiddleware } from "./tool-truncation.js";
 import { createGracefulStopMiddleware } from "./graceful-stop.js";
 import { createApprovalGateMiddleware } from "./approval-gate.js";
@@ -51,6 +53,8 @@ export function buildMiddlewareStack(
 
   stack.push(createExecutionBudgetMiddleware(config.executionBudget));
 
+  stack.push(createToolIntentMiddleware());
+
   stack.push(createToolTruncationMiddleware(config.toolTruncation));
 
   const gracefulStop = createGracefulStopMiddleware();

package/src/middleware/tool-intent.ts

@@ -0,0 +1,174 @@
+/**
+ * Tool-intent middleware — model-authored intent titles for shell tool calls
+ * (issue #276).
+ *
+ * The thread UI titles every shell row with the bare category label ("Shell");
+ * only the model knows *why* it is running a command, so a host-side rename
+ * can never close that gap. This middleware lets the model author the title:
+ * at model-call time it presents a schema-extended clone of the shell tool
+ * that adds one optional `description` argument. The model fills it in, the
+ * argument rides the tool call's args verbatim through checkpoints and the
+ * persisted ToolCall proto (no new state, no proto change), and the React SDK
+ * renders it as the row title with the command as secondary text.
+ *
+ * Why this seam:
+ * - The `execute` tool is owned by the deepagents library; its schema is not
+ *   ours to edit. `wrapModelCall` is the framework's intended point for
+ *   reshaping the model-visible tool list — langchain's own llmToolSelector
+ *   middleware swaps `request.tools` through exactly this hook.
+ * - Execution is untouched by construction: the agent's ToolNode is built
+ *   once from the ORIGINAL tools, and the original schema parses with strip
+ *   semantics, so the extra argument is dropped before the backend's
+ *   `execute(command)` ever runs. Approval fingerprints are equally
+ *   unaffected (`description` is not a salient arg field).
+ * - The argument name deliberately matches the Cursor harness, whose built-in
+ *   Shell tool already carries a model-authored `description` — both
+ *   harnesses converge on one wire key and the SDK reads a single field.
+ *
+ * The swapped-in declaration is a `StructuredToolParams` object — langchain's
+ * first-class shape for a non-executable, bind-time-only tool definition
+ * ("the most minimal interface … to be passed to a LLM for tool calling").
+ * A same-name RUNNABLE replacement is rejected by the agent's wrapModelCall
+ * validation (it would threaten ToolNode execution identity); a params
+ * object is exactly the declaration-without-execution the validation exists
+ * to protect, and the graph keeps executing the untouched original. Schema
+ * extension happens at the JSON-schema level via @langchain/core's interop
+ * serializer — the runner's zod (v3) must never construct fields inside the
+ * library's zod (v4) schema object.
+ */
+
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool } from "../shared/tool-kind.js";
+import type { StigmerMiddleware } from "./types.js";
+
+/**
+ * The wire name of the intent argument. Shared with the Cursor harness's
+ * built-in Shell tool and read by the SDK's tool presentation layer — the
+ * three surfaces must agree on this key.
+ */
+export const INTENT_ARG = "description";
+
+/**
+ * The behavior-shaping prompt for the intent argument (owner-approved
+ * wording, issue #276). This is prompt engineering, not documentation:
+ * changing it changes what the model writes into every shell row title.
+ */
+export const INTENT_ARG_PROMPT =
+  "A short present-tense phrase describing what this command does and why, " +
+  "shown to the user as the title of this action (5-10 words, e.g. " +
+  "'Run unit tests for the parser'). Do not restate the command syntax.";
+
+/** Structural shape of a bindable structured tool, checked at runtime. */
+interface StructuredToolLike {
+  readonly name: string;
+  readonly description: string;
+  readonly schema: unknown;
+}
+
+function isStructuredToolLike(candidate: unknown): candidate is StructuredToolLike {
+  if (candidate == null || typeof candidate !== "object") return false;
+  const t = candidate as Record<string, unknown>;
+  return (
+    typeof t.name === "string" &&
+    typeof t.description === "string" &&
+    "schema" in t
+  );
+}
+
+interface JsonObjectSchema {
+  readonly type: "object";
+  readonly properties?: Record<string, unknown>;
+  readonly [key: string]: unknown;
+}
+
+function isJsonObjectSchema(schema: unknown): schema is JsonObjectSchema {
+  return (
+    schema != null &&
+    typeof schema === "object" &&
+    (schema as Record<string, unknown>).type === "object"
+  );
+}
+
+/**
+ * Returns a bind-time `StructuredToolParams` declaration for `original`
+ * whose schema carries the optional intent argument, or `original` itself
+ * when the tool is not a shell tool, is not schema-extendable, or already
+ * defines an argument with that name (a real argument must never be
+ * shadowed by presentation metadata).
+ *
+ * Unexpected schemas pass through unchanged on purpose: a missing intent
+ * title degrades to today's rendering, while a mangled schema would break
+ * the tool for the whole execution.
+ */
+function maybeExtendShellTool(original: unknown): unknown {
+  if (!isStructuredToolLike(original)) return original;
+  if (classifyTool(original.name) !== ToolKind.SHELL) return original;
+
+  let jsonSchema: unknown;
+  try {
+    jsonSchema = toJsonSchema(original.schema as Parameters<typeof toJsonSchema>[0]);
+  } catch {
+    return original;
+  }
+  if (!isJsonObjectSchema(jsonSchema)) return original;
+
+  const properties = jsonSchema.properties ?? {};
+  if (INTENT_ARG in properties) return original;
+
+  // A plain frozen declaration, deliberately NOT an executable tool: the
+  // graph's ToolNode executes the ORIGINAL registered tool (it is built from
+  // the registered tools, not from the model request), and the agent's
+  // wrapModelCall validation only forbids swapping same-name EXECUTABLE
+  // instances. `isStructuredToolParams` recognizes this shape, so every
+  // provider's bindTools converts it exactly like a structured tool.
+  return Object.freeze({
+    name: original.name,
+    description: original.description,
+    schema: {
+      ...jsonSchema,
+      properties: {
+        ...properties,
+        [INTENT_ARG]: { type: "string", description: INTENT_ARG_PROMPT },
+      },
+    },
+  });
+}
+
+/**
+ * Creates the middleware. Install on the parent stack AND on every sub-agent
+ * stack (subagent-wiring.ts) — sub-agent shell rows render in the same
+ * thread and must carry the same titles.
+ */
+export function createToolIntentMiddleware(): StigmerMiddleware {
+  // One clone per original tool instance: repeated model calls (and repeated
+  // turns on the same graph) bind a referentially stable clone instead of
+  // re-serializing the schema every round.
+  const cloneCache = new WeakMap<object, unknown>();
+
+  const extendCached = (candidate: unknown): unknown => {
+    if (candidate == null || typeof candidate !== "object") return candidate;
+    const cached = cloneCache.get(candidate);
+    if (cached !== undefined) return cached;
+    const extended = maybeExtendShellTool(candidate);
+    cloneCache.set(candidate, extended);
+    return extended;
+  };
+
+  return {
+    name: "StigmerToolIntentMiddleware",
+    async wrapModelCall(request, handler) {
+      const tools = request.tools;
+      if (!tools || tools.length === 0) return handler(request);
+
+      let changed = false;
+      const mapped = tools.map((t) => {
+        const extended = extendCached(t);
+        if (extended !== t) changed = true;
+        return extended;
+      });
+
+      return handler(changed ? { ...request, tools: mapped } : request);
+    },
+  };
+}