@stigmer/runner 3.0.1

package/src/middleware/loop-detection.ts

@@ -0,0 +1,192 @@
+/**
+ * Loop detection middleware for autonomous agents.
+ *
+ * Detects and prevents infinite loops by tracking tool invocations:
+ *
+ * afterModel — inspects AIMessage tool_calls, tracks signatures
+ *   (tool name + param hash) in a sliding window, injects
+ *   SystemMessage interventions when repetitive patterns are detected.
+ *
+ * wrapToolCall — when the total-repetition threshold has been exceeded,
+ *   short-circuits tool execution with a ToolMessage halt notice.
+ */
+
+import { createHash } from "node:crypto";
+import { ToolMessage, SystemMessage } from "@langchain/core/messages";
+import type { AIMessage } from "@langchain/core/messages";
+import type { StigmerMiddleware, LoopDetectionConfig } from "./types.js";
+
+const DEFAULTS: LoopDetectionConfig = {
+  historySize: 20,
+  consecutiveThreshold: 7,
+  totalThreshold: 20,
+  enabled: true,
+};
+
+type Signature = readonly [name: string, hash: string];
+
+function hashParams(params: Record<string, unknown>): string {
+  try {
+    const normalized = JSON.stringify(params, Object.keys(params).sort(), undefined);
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  } catch {
+    return "error";
+  }
+}
+
+function detectConsecutive(history: Signature[]): { isLoop: boolean; toolName: string; count: number } {
+  if (history.length === 0) return { isLoop: false, toolName: "", count: 0 };
+
+  const [recentName, recentHash] = history[history.length - 1];
+  let count = 1;
+
+  for (let i = history.length - 2; i >= 0; i--) {
+    if (history[i][0] === recentName && history[i][1] === recentHash) {
+      count++;
+    } else {
+      break;
+    }
+  }
+
+  return { isLoop: false, toolName: recentName, count };
+}
+
+function detectTotal(history: Signature[]): { isExcessive: boolean; toolName: string; count: number } {
+  if (history.length === 0) return { isExcessive: false, toolName: "", count: 0 };
+
+  const [recentName, recentHash] = history[history.length - 1];
+  let count = 0;
+  for (const [name, hash] of history) {
+    if (name === recentName && hash === recentHash) count++;
+  }
+
+  return { isExcessive: false, toolName: recentName, count };
+}
+
+function buildIntervention(
+  toolName: string,
+  consecutiveCount: number,
+  totalCount: number,
+  isFinal: boolean,
+): SystemMessage {
+  if (isFinal) {
+    return new SystemMessage({
+      content:
+        `\u26a0\ufe0f LOOP DETECTED: Critical repetition limit reached.\n\n` +
+        `You have called '${toolName}' ${totalCount} times with similar parameters. ` +
+        `This indicates you are stuck in a loop and unable to make progress.\n\n` +
+        `**You MUST conclude your work now:**\n` +
+        `1. Summarize what you have learned so far\n` +
+        `2. Explain the obstacle preventing progress\n` +
+        `3. Provide your best assessment based on available information\n` +
+        `4. Do NOT call '${toolName}' again\n\n` +
+        `Conclude gracefully with the information you have gathered.`,
+    });
+  }
+
+  return new SystemMessage({
+    content:
+      `\u26a0\ufe0f LOOP WARNING: Repetitive pattern detected.\n\n` +
+      `You have called '${toolName}' ${consecutiveCount} times in a row. ` +
+      `This suggests you may be stuck or approaching the problem incorrectly.\n\n` +
+      `**Recommended actions:**\n` +
+      `1. Try a completely different approach or tool\n` +
+      `2. Re-examine your assumptions about the problem\n` +
+      `3. Consider if you have enough information to conclude\n` +
+      `4. Avoid calling '${toolName}' again unless absolutely necessary\n\n` +
+      `Adapt your strategy to make progress.`,
+  });
+}
+
+export function createLoopDetectionMiddleware(
+  config: Partial<LoopDetectionConfig> = {},
+): StigmerMiddleware {
+  const cfg = { ...DEFAULTS, ...config };
+  let history: Signature[] = [];
+  let interventionCount = 0;
+  let stopped = false;
+
+  return {
+    name: "LoopDetectionMiddleware",
+
+    beforeAgent() {
+      history = [];
+      interventionCount = 0;
+      stopped = false;
+    },
+
+    afterModel(state) {
+      if (!cfg.enabled || stopped) return;
+
+      const messages = (state.messages ?? []) as unknown[];
+      let lastAi: AIMessage | null = null;
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i] as { _getType?: () => string; tool_calls?: unknown[] };
+        if (msg?._getType?.() === "ai") {
+          lastAi = msg as unknown as AIMessage;
+          break;
+        }
+      }
+
+      if (!lastAi) return;
+      const toolCalls = (lastAi as unknown as { tool_calls?: Array<{ name?: string; args?: Record<string, unknown> }> }).tool_calls;
+      if (!toolCalls || toolCalls.length === 0) return;
+
+      for (const tc of toolCalls) {
+        const name = tc.name ?? "unknown";
+        const args = tc.args ?? {};
+        const paramHash = hashParams(args);
+
+        history.push([name, paramHash]);
+        if (history.length > cfg.historySize) {
+          history = history.slice(-cfg.historySize);
+        }
+
+        const { toolName: consToolName, count: consCount } = detectConsecutive(history);
+        const { toolName: totalToolName, count: totalCount } = detectTotal(history);
+
+        if (totalCount >= cfg.totalThreshold) {
+          const intervention = buildIntervention(totalToolName, consCount, totalCount, true);
+          interventionCount++;
+          stopped = true;
+          console.warn(
+            `[LoopDetection] STOP: ${totalToolName} called ${totalCount} times (threshold: ${cfg.totalThreshold})`,
+          );
+          return { messages: [intervention] };
+        }
+
+        if (consCount >= cfg.consecutiveThreshold && interventionCount === 0) {
+          const intervention = buildIntervention(consToolName, consCount, totalCount, false);
+          interventionCount++;
+          console.warn(
+            `[LoopDetection] WARNING: ${consToolName} called ${consCount} times in a row (threshold: ${cfg.consecutiveThreshold})`,
+          );
+          return { messages: [intervention] };
+        }
+      }
+    },
+
+    async wrapToolCall(request, handler) {
+      if (stopped) {
+        return new ToolMessage({
+          content:
+            "[Loop detected: tool execution halted by loop detection middleware. " +
+            "Conclude your work with the information you have gathered.]",
+          tool_call_id: request.toolCall.id,
+          name: request.toolCall.name,
+        });
+      }
+      return handler(request);
+    },
+
+    afterAgent() {
+      if (history.length > 0) {
+        const unique = new Set(history.map(([n, h]) => `${n}:${h}`)).size;
+        console.log(
+          `[LoopDetection] Summary: ${history.length} tool calls tracked, ` +
+          `${unique} unique signatures, ${interventionCount} interventions, stopped=${stopped}`,
+        );
+      }
+    },
+  };
+}

package/src/middleware/otel-spans.ts

@@ -0,0 +1,205 @@
+/**
+ * OpenTelemetry spans and metrics middleware for deep-agent execution.
+ *
+ * Creates stigmer.llm.call and stigmer.mcp.tool_call spans with
+ * attributes matching the Go workflow-runner schema (pkg/otel/spans.go).
+ * Also records metrics (histograms + counters) for aggregate dashboards.
+ *
+ * Graceful no-op when no TracerProvider/MeterProvider is configured.
+ */
+
+import type { StigmerMiddleware, OtelSpansConfig } from "./types.js";
+
+const SPAN_LLM_CALL = "stigmer.llm.call";
+const SPAN_MCP_TOOL = "stigmer.mcp.tool_call";
+
+const ATTR_LLM_PROVIDER = "stigmer.llm.provider";
+const ATTR_LLM_MODEL = "stigmer.llm.model";
+const ATTR_LLM_INPUT_TOKENS = "stigmer.llm.input_tokens";
+const ATTR_LLM_OUTPUT_TOKENS = "stigmer.llm.output_tokens";
+const ATTR_MCP_TOOL_NAME = "stigmer.mcp.tool_name";
+const ATTR_MCP_SERVER_NAME = "stigmer.mcp.server_name";
+
+const METRIC_LLM_CALL_DURATION = "stigmer.llm.call.duration";
+const METRIC_LLM_CALL_COUNT = "stigmer.llm.call.count";
+const METRIC_LLM_TOKENS_INPUT = "stigmer.llm.tokens.input";
+const METRIC_LLM_TOKENS_OUTPUT = "stigmer.llm.tokens.output";
+const METRIC_MCP_TOOL_CALL_DURATION = "stigmer.mcp.tool_call.duration";
+const METRIC_MCP_TOOL_CALL_COUNT = "stigmer.mcp.tool_call.count";
+
+const TRACER_NAME = "stigmer-runner";
+const METER_NAME = "stigmer-runner";
+
+function inferProvider(modelName: string): string {
+  const lower = modelName.toLowerCase();
+  if (lower.startsWith("claude")) return "anthropic";
+  if (lower.startsWith("gpt") || lower.startsWith("o1") || lower.startsWith("o3") || lower.startsWith("o4")) return "openai";
+  if (["qwen", "llama", "deepseek", "codellama", "mistral", "phi"].some(p => lower.startsWith(p))) return "ollama";
+  return "unknown";
+}
+
+/**
+ * Lazy OTel accessor. Returns null-object implementations when
+ * @opentelemetry/api is not available or no provider is configured.
+ */
+async function getOtel() {
+  try {
+    const api = await import("@opentelemetry/api");
+    return api;
+  } catch {
+    return null;
+  }
+}
+
+export function createOtelSpansMiddleware(
+  config: Partial<OtelSpansConfig> = {},
+): StigmerMiddleware {
+  const toolServerMap = config.toolServerMap ?? new Map();
+
+  // Metric instruments are created lazily on first use
+  let metricsInitialized = false;
+  let llmCallDuration: { record(v: number, attrs?: Record<string, unknown>): void } | null = null;
+  let llmCallCount: { add(v: number, attrs?: Record<string, unknown>): void } | null = null;
+  let llmTokensInput: { add(v: number, attrs?: Record<string, unknown>): void } | null = null;
+  let llmTokensOutput: { add(v: number, attrs?: Record<string, unknown>): void } | null = null;
+  let mcpToolDuration: { record(v: number, attrs?: Record<string, unknown>): void } | null = null;
+  let mcpToolCount: { add(v: number, attrs?: Record<string, unknown>): void } | null = null;
+
+  async function ensureMetrics(): Promise<void> {
+    if (metricsInitialized) return;
+    metricsInitialized = true;
+
+    const api = await getOtel();
+    if (!api) return;
+
+    try {
+      const meter = api.metrics.getMeter(METER_NAME);
+      llmCallDuration = meter.createHistogram(METRIC_LLM_CALL_DURATION, {
+        unit: "ms",
+        description: "Duration of LLM API calls in milliseconds",
+      });
+      llmCallCount = meter.createCounter(METRIC_LLM_CALL_COUNT, {
+        description: "Total number of LLM API calls",
+      });
+      llmTokensInput = meter.createCounter(METRIC_LLM_TOKENS_INPUT, {
+        unit: "{token}",
+        description: "Total input tokens consumed across LLM calls",
+      });
+      llmTokensOutput = meter.createCounter(METRIC_LLM_TOKENS_OUTPUT, {
+        unit: "{token}",
+        description: "Total output tokens produced across LLM calls",
+      });
+      mcpToolDuration = meter.createHistogram(METRIC_MCP_TOOL_CALL_DURATION, {
+        unit: "ms",
+        description: "Duration of MCP tool calls in milliseconds",
+      });
+      mcpToolCount = meter.createCounter(METRIC_MCP_TOOL_CALL_COUNT, {
+        description: "Total number of MCP tool calls",
+      });
+    } catch {
+      // Metrics not available
+    }
+  }
+
+  return {
+    name: "OtelSpansMiddleware",
+
+    async wrapModelCall(request, handler) {
+      const api = await getOtel();
+      await ensureMetrics();
+
+      if (!api) return handler(request);
+
+      const invocationParams = (request.model as { model?: string; model_name?: string }) ?? {};
+      const modelName = invocationParams.model ?? invocationParams.model_name ?? "";
+      const provider = inferProvider(modelName);
+
+      const tracer = api.trace.getTracer(TRACER_NAME);
+      const span = tracer.startSpan(SPAN_LLM_CALL, {
+        attributes: {
+          [ATTR_LLM_PROVIDER]: provider,
+          [ATTR_LLM_MODEL]: modelName,
+        },
+      });
+
+      const startTime = performance.now();
+      try {
+        const response = await api.context.with(
+          api.trace.setSpan(api.context.active(), span),
+          () => handler(request),
+        );
+
+        const elapsedMs = performance.now() - startTime;
+
+        const usage = (response as unknown as {
+          usage_metadata?: {
+            input_tokens?: number;
+            output_tokens?: number;
+          };
+        }).usage_metadata;
+
+        const inputTokens = usage?.input_tokens ?? 0;
+        const outputTokens = usage?.output_tokens ?? 0;
+
+        if (inputTokens) span.setAttribute(ATTR_LLM_INPUT_TOKENS, inputTokens);
+        if (outputTokens) span.setAttribute(ATTR_LLM_OUTPUT_TOKENS, outputTokens);
+        span.end();
+
+        const attrs = { [ATTR_LLM_PROVIDER]: provider, [ATTR_LLM_MODEL]: modelName };
+        llmCallDuration?.record(elapsedMs, attrs);
+        llmCallCount?.add(1, attrs);
+        if (inputTokens) llmTokensInput?.add(inputTokens, attrs);
+        if (outputTokens) llmTokensOutput?.add(outputTokens, attrs);
+
+        return response;
+      } catch (err) {
+        span.setStatus({ code: api.SpanStatusCode.ERROR, message: String(err) });
+        if (err instanceof Error) span.recordException(err);
+        span.end();
+        throw err;
+      }
+    },
+
+    async wrapToolCall(request, handler) {
+      const toolName = request.toolCall.name;
+      const serverName = toolServerMap.get(toolName);
+
+      if (!serverName) return handler(request);
+
+      const api = await getOtel();
+      await ensureMetrics();
+
+      if (!api) return handler(request);
+
+      const tracer = api.trace.getTracer(TRACER_NAME);
+      const span = tracer.startSpan(SPAN_MCP_TOOL, {
+        attributes: {
+          [ATTR_MCP_TOOL_NAME]: toolName,
+          [ATTR_MCP_SERVER_NAME]: serverName,
+        },
+      });
+
+      const startTime = performance.now();
+      try {
+        const result = await api.context.with(
+          api.trace.setSpan(api.context.active(), span),
+          () => handler(request),
+        );
+
+        const elapsedMs = performance.now() - startTime;
+        span.end();
+
+        const attrs = { [ATTR_MCP_TOOL_NAME]: toolName, [ATTR_MCP_SERVER_NAME]: serverName };
+        mcpToolDuration?.record(elapsedMs, attrs);
+        mcpToolCount?.add(1, attrs);
+
+        return result;
+      } catch (err) {
+        span.setStatus({ code: api.SpanStatusCode.ERROR, message: String(err) });
+        if (err instanceof Error) span.recordException(err);
+        span.end();
+        throw err;
+      }
+    },
+  };
+}

package/src/middleware/think-tool.ts

@@ -0,0 +1,38 @@
+/**
+ * Think tool for structured agent reasoning.
+ *
+ * A no-op tool that gives LLMs a dedicated place to reason before acting.
+ * The thought is captured as a regular tool-call argument, making it
+ * observable through the existing status pipeline (StatusBuilder, gRPC
+ * updates, CLI rendering) without any special handling.
+ *
+ * Follows the Anthropic "think tool" pattern:
+ * https://www.anthropic.com/engineering/claude-think-tool
+ */
+
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+export function createThinkTool() {
+  return tool(
+    async (_input: { thought: string }) => "ok",
+    {
+      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.",
+      schema: z.object({
+        thought: z.string().describe("Your reasoning, analysis, or plan."),
+      }),
+    },
+  );
+}

package/src/middleware/tool-truncation.ts

@@ -0,0 +1,94 @@
+/**
+ * Tool result truncation middleware.
+ *
+ * Prevents any single tool result from consuming an excessive share of
+ * the LLM's context window. Applied uniformly to ALL tools via
+ * wrapToolCall. When a ToolMessage result exceeds maxChars, the content
+ * is prefix-truncated and a marker is appended telling the LLM to
+ * request specific sections.
+ *
+ * Default limit: 30,000 characters (~7,500 tokens).
+ */
+
+import { ToolMessage } from "@langchain/core/messages";
+import type {
+  StigmerMiddleware,
+  ToolCallRequest,
+  ToolTruncationConfig,
+} from "./types.js";
+
+const DEFAULT_MAX_CHARS = 30_000;
+
+export function createToolTruncationMiddleware(
+  config: Partial<ToolTruncationConfig> = {},
+): StigmerMiddleware & { readonly truncationCount: number; readonly totalCharsTruncated: number } {
+  const maxChars = config.maxChars ?? DEFAULT_MAX_CHARS;
+  if (maxChars <= 0) {
+    throw new Error(`maxChars must be positive, got ${maxChars}`);
+  }
+
+  let truncationCount = 0;
+  let totalCharsTruncated = 0;
+
+  function buildMarker(originalChars: number): string {
+    return (
+      `\n\n[truncated — result was ${originalChars.toLocaleString()} chars, ` +
+      `exceeded ${maxChars.toLocaleString()} char limit. ` +
+      `Ask for specific sections or narrow your query.]`
+    );
+  }
+
+  const middleware: StigmerMiddleware & { readonly truncationCount: number; readonly totalCharsTruncated: number } = {
+    name: "ToolTruncationMiddleware",
+
+    get truncationCount() { return truncationCount; },
+    get totalCharsTruncated() { return totalCharsTruncated; },
+
+    beforeAgent() {
+      truncationCount = 0;
+      totalCharsTruncated = 0;
+    },
+
+    async wrapToolCall(request, handler) {
+      const result = await handler(request);
+
+      if (!(result instanceof ToolMessage)) return result;
+
+      const content = result.content;
+      if (typeof content !== "string") return result;
+      if (content.length <= maxChars) return result;
+
+      const originalChars = content.length;
+      const charsTruncated = originalChars - maxChars;
+      const truncatedContent = content.slice(0, maxChars) + buildMarker(originalChars);
+
+      truncationCount++;
+      totalCharsTruncated += charsTruncated;
+
+      const toolName = request.toolCall.name;
+      console.warn(
+        `[TRUNCATED] tool=${toolName} original_chars=${originalChars} ` +
+        `limit=${maxChars} chars_truncated=${charsTruncated}`,
+      );
+
+      config.onTruncation?.(toolName, charsTruncated);
+
+      return new ToolMessage({
+        content: truncatedContent,
+        tool_call_id: request.toolCall.id,
+        name: toolName,
+      });
+    },
+
+    afterAgent() {
+      if (truncationCount > 0) {
+        console.log(
+          `[ToolTruncation] Summary: ${truncationCount} results truncated, ` +
+          `${totalCharsTruncated} total chars removed (limit=${maxChars})`,
+        );
+      }
+    },
+  };
+
+  return middleware;
+}

package/src/middleware/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared configuration types for the middleware stack.
+ *
+ * Each middleware module reads its own slice of MiddlewareStackConfig.
+ * The factory in index.ts assembles the config from ExecutionConfig
+ * proto fields and passes it to buildMiddlewareStack().
+ */
+
+import type { ToolMessage, SystemMessage, AIMessage } from "@langchain/core/messages";
+import type { Command } from "@langchain/langgraph";
+
+export type { ToolMessage, SystemMessage, AIMessage };
+
+/**
+ * Minimal AgentMiddleware interface matching the langchain JS contract.
+ *
+ * The canonical type lives in langchain (nested under deepagents), but
+ * is not directly importable from our dependency graph. This structural
+ * type is wire-compatible — langchain uses structural typing, not
+ * nominal, so any object matching this shape is accepted as middleware.
+ */
+export interface StigmerMiddleware {
+  readonly name: string;
+  beforeAgent?: (state: Record<string, unknown>, runtime: unknown) => unknown;
+  afterModel?: (state: Record<string, unknown>, runtime: unknown) => unknown;
+  wrapToolCall?: (
+    request: ToolCallRequest,
+    handler: (request: ToolCallRequest) => Promise<ToolMessage | Command> | ToolMessage | Command,
+  ) => Promise<ToolMessage | Command> | ToolMessage | Command;
+  wrapModelCall?: (
+    request: ModelCallRequest,
+    handler: (request: ModelCallRequest) => Promise<AIMessage | Command> | AIMessage | Command,
+  ) => Promise<AIMessage | Command> | AIMessage | Command;
+  afterAgent?: (state: Record<string, unknown>, runtime: unknown) => unknown;
+}
+
+/**
+ * Tool call request — the shape passed to wrapToolCall.
+ * Matches langchain ToolCallRequest structurally.
+ */
+export interface ToolCallRequest {
+  readonly toolCall: {
+    readonly id: string;
+    readonly name: string;
+    readonly args: Record<string, unknown>;
+  };
+  readonly tool: unknown;
+  readonly state: Record<string, unknown> & { messages?: unknown[] };
+  readonly runtime: unknown;
+}
+
+/**
+ * Model call request — the shape passed to wrapModelCall.
+ * Matches langchain ModelRequest structurally.
+ */
+export interface ModelCallRequest {
+  readonly model: unknown;
+  readonly messages: unknown[];
+  readonly systemPrompt?: string;
+  readonly systemMessage?: SystemMessage;
+  readonly tools?: unknown[];
+  readonly state: Record<string, unknown> & { messages?: unknown[] };
+  readonly runtime: unknown;
+}
+
+export interface LoopDetectionConfig {
+  readonly historySize: number;
+  readonly consecutiveThreshold: number;
+  readonly totalThreshold: number;
+  readonly enabled: boolean;
+}
+
+export interface ExecutionBudgetConfig {
+  readonly recursionLimit: number;
+  readonly warningPct: number;
+  readonly warningInterval: number | null;
+  readonly maxWarnings: number;
+}
+
+export interface ToolTruncationConfig {
+  readonly maxChars: number;
+  readonly onTruncation?: (toolName: string, charsTruncated: number) => void;
+}
+
+export interface CostCapConfig {
+  readonly maxCostUsd: number;
+  readonly inputPricePerMillion: number;
+  readonly outputPricePerMillion: number;
+  readonly cacheReadPricePerMillion: number;
+  readonly warningPct: number;
+}
+
+export interface OtelSpansConfig {
+  readonly toolServerMap: ReadonlyMap<string, string>;
+}
+
+export interface ApprovalGateConfig {
+  readonly policies: ReadonlyMap<string, import("../shared/approval-policy.js").MergedToolPolicy>;
+  readonly autoApproveAll: boolean;
+  readonly toolServerMap: ReadonlyMap<string, string>;
+}
+
+/**
+ * Top-level configuration for buildMiddlewareStack().
+ * All sections are optional — the factory applies sensible defaults.
+ */
+export interface MiddlewareStackConfig {
+  readonly loopDetection?: Partial<LoopDetectionConfig>;
+  readonly executionBudget?: Partial<ExecutionBudgetConfig>;
+  readonly toolTruncation?: Partial<ToolTruncationConfig>;
+  readonly costCap?: CostCapConfig | null;
+  readonly otelSpans?: Partial<OtelSpansConfig>;
+  readonly approvalGate?: ApprovalGateConfig | null;
+}