@stigmer/runner 3.0.1

package/dist/middleware/execution-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-budget.js","sourceRoot":"","sources":["../../src/middleware/execution-budget.ts"],"names":[],"mappings":"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"}

package/dist/middleware/graceful-stop.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Platform-level graceful stop middleware.
+ *
+ * Activated externally when the platform signals the runner to stop
+ * (e.g. via ExecutionControlSignal.STOP from the updateStatus RPC).
+ * Once activated, blocks all tool execution and gives the model one
+ * final tool-free round to produce a summary.
+ *
+ * Always injected into the agent graph. Inert until activate() is called.
+ */
+import type { StigmerMiddleware } from "./types.js";
+export interface GracefulStopMiddleware extends StigmerMiddleware {
+    readonly activated: boolean;
+    activate(reason?: string): void;
+    forSubAgent(): StigmerMiddleware;
+}
+export declare function createGracefulStopMiddleware(): GracefulStopMiddleware;

package/dist/middleware/graceful-stop.js

@@ -0,0 +1,63 @@
+/**
+ * Platform-level graceful stop middleware.
+ *
+ * Activated externally when the platform signals the runner to stop
+ * (e.g. via ExecutionControlSignal.STOP from the updateStatus RPC).
+ * Once activated, blocks all tool execution and gives the model one
+ * final tool-free round to produce a summary.
+ *
+ * Always injected into the agent graph. Inert until activate() is called.
+ */
+import { ToolMessage, SystemMessage } from "@langchain/core/messages";
+const DEFAULT_STOP_MESSAGE = "The platform has requested this execution to stop. All tool calls are " +
+    "now blocked. Respond with a concise summary of what you accomplished " +
+    "and what work remains so the user can continue in their next session.";
+export function createGracefulStopMiddleware() {
+    let _activated = false;
+    let _messageInjected = false;
+    let _reason = "";
+    const middleware = {
+        name: "GracefulStopMiddleware",
+        get activated() {
+            return _activated;
+        },
+        activate(reason = "") {
+            if (!_activated) {
+                _activated = true;
+                _reason = reason;
+                console.warn(`[PLATFORM_STOP] GracefulStopMiddleware activated (reason=${reason || "unspecified"})`);
+            }
+        },
+        afterModel() {
+            if (!_activated || _messageInjected)
+                return;
+            _messageInjected = true;
+            const msg = _reason || DEFAULT_STOP_MESSAGE;
+            return { messages: [new SystemMessage({ content: msg })] };
+        },
+        async wrapToolCall(request, handler) {
+            if (!_activated)
+                return handler(request);
+            console.log(`[PLATFORM_STOP] Blocking tool '${request.toolCall.name}' (id=${request.toolCall.id})`);
+            return new ToolMessage({
+                content: "[Execution stopped by platform: tool execution blocked. " +
+                    "Summarize your progress for the user.]",
+                tool_call_id: request.toolCall.id,
+                name: request.toolCall.name,
+            });
+        },
+        forSubAgent() {
+            return {
+                name: "GracefulStopSubAgentView",
+                afterModel() {
+                    return middleware.afterModel({}, {});
+                },
+                async wrapToolCall(request, handler) {
+                    return middleware.wrapToolCall(request, handler);
+                },
+            };
+        },
+    };
+    return middleware;
+}
+//# sourceMappingURL=graceful-stop.js.map

package/dist/middleware/graceful-stop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-stop.js","sourceRoot":"","sources":["../../src/middleware/graceful-stop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGtE,MAAM,oBAAoB,GACxB,wEAAwE;IACxE,uEAAuE;IACvE,uEAAuE,CAAC;AAQ1E,MAAM,UAAU,4BAA4B;IAC1C,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,gBAAgB,GAAG,KAAK,CAAC;IAC7B,IAAI,OAAO,GAAG,EAAE,CAAC;IAEjB,MAAM,UAAU,GAA2B;QACzC,IAAI,EAAE,wBAAwB;QAE9B,IAAI,SAAS;YACX,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,QAAQ,CAAC,MAAM,GAAG,EAAE;YAClB,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,UAAU,GAAG,IAAI,CAAC;gBAClB,OAAO,GAAG,MAAM,CAAC;gBACjB,OAAO,CAAC,IAAI,CACV,4DAA4D,MAAM,IAAI,aAAa,GAAG,CACvF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,UAAU;YACR,IAAI,CAAC,UAAU,IAAI,gBAAgB;gBAAE,OAAO;YAC5C,gBAAgB,GAAG,IAAI,CAAC;YACxB,MAAM,GAAG,GAAG,OAAO,IAAI,oBAAoB,CAAC;YAC5C,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;QAC7D,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO;YACjC,IAAI,CAAC,UAAU;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;YAEzC,OAAO,CAAC,GAAG,CACT,kCAAkC,OAAO,CAAC,QAAQ,CAAC,IAAI,SAAS,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,CACvF,CAAC;YACF,OAAO,IAAI,WAAW,CAAC;gBACrB,OAAO,EACL,0DAA0D;oBAC1D,wCAAwC;gBAC1C,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE;gBACjC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;aAC5B,CAAC,CAAC;QACL,CAAC;QAED,WAAW;YACT,OAAO;gBACL,IAAI,EAAE,0BAA0B;gBAEhC,UAAU;oBACR,OAAO,UAAU,CAAC,UAAW,CAAC,EAAS,EAAE,EAAE,CAAC,CAAC;gBAC/C,CAAC;gBAED,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO;oBACjC,OAAO,UAAU,CAAC,YAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACpD,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Middleware stack factory.
+ *
+ * Assembles the ordered middleware array from a MiddlewareStackConfig.
+ * The composition order matches the Python create_deep_agent injection:
+ *
+ *   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)
+ */
+import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
+import type { GracefulStopMiddleware } from "./graceful-stop.js";
+import { type CostCapMiddleware } from "./cost-cap.js";
+export { createThinkTool } from "./think-tool.js";
+export type { GracefulStopMiddleware } from "./graceful-stop.js";
+export type { CostCapMiddleware } from "./cost-cap.js";
+export type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
+export interface MiddlewareStackResult {
+    readonly middleware: StigmerMiddleware[];
+    readonly gracefulStop: GracefulStopMiddleware;
+    readonly costCap: CostCapMiddleware | null;
+}
+export declare function buildMiddlewareStack(config?: MiddlewareStackConfig): MiddlewareStackResult;

package/dist/middleware/index.js

@@ -0,0 +1,45 @@
+/**
+ * Middleware stack factory.
+ *
+ * Assembles the ordered middleware array from a MiddlewareStackConfig.
+ * The composition order matches the Python create_deep_agent injection:
+ *
+ *   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)
+ */
+import { createLoopDetectionMiddleware } from "./loop-detection.js";
+import { createExecutionBudgetMiddleware } from "./execution-budget.js";
+import { createToolTruncationMiddleware } from "./tool-truncation.js";
+import { createGracefulStopMiddleware } from "./graceful-stop.js";
+import { createApprovalGateMiddleware } from "./approval-gate.js";
+import { createCostCapMiddleware } from "./cost-cap.js";
+import { createErrorHintsMiddleware } from "./error-hints.js";
+import { createOtelSpansMiddleware } from "./otel-spans.js";
+export { createThinkTool } from "./think-tool.js";
+export function buildMiddlewareStack(config = {}) {
+    const stack = [];
+    stack.push(createLoopDetectionMiddleware(config.loopDetection));
+    stack.push(createExecutionBudgetMiddleware(config.executionBudget));
+    stack.push(createToolTruncationMiddleware(config.toolTruncation));
+    const gracefulStop = createGracefulStopMiddleware();
+    stack.push(gracefulStop);
+    if (config.approvalGate) {
+        stack.push(createApprovalGateMiddleware(config.approvalGate));
+    }
+    if (config.costCap && config.costCap.maxCostUsd > 0) {
+        const costCapMiddleware = createCostCapMiddleware(config.costCap);
+        stack.push(costCapMiddleware);
+        stack.push(createErrorHintsMiddleware());
+        stack.push(createOtelSpansMiddleware(config.otelSpans));
+        return { middleware: stack, gracefulStop, costCap: costCapMiddleware };
+    }
+    stack.push(createErrorHintsMiddleware());
+    stack.push(createOtelSpansMiddleware(config.otelSpans));
+    return { middleware: stack, gracefulStop, costCap: null };
+}
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAA0B,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAWlD,MAAM,UAAU,oBAAoB,CAClC,SAAgC,EAAE;IAElC,MAAM,KAAK,GAAwB,EAAE,CAAC;IAEtC,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAEhE,KAAK,CAAC,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAEpE,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;IAElE,MAAM,YAAY,GAAG,4BAA4B,EAAE,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAEzB,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAE9B,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAExD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAExD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC"}

package/dist/middleware/loop-detection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 type { StigmerMiddleware, LoopDetectionConfig } from "./types.js";
+export declare function createLoopDetectionMiddleware(config?: Partial<LoopDetectionConfig>): StigmerMiddleware;

package/dist/middleware/loop-detection.js

@@ -0,0 +1,156 @@
+/**
+ * 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";
+const DEFAULTS = {
+    historySize: 20,
+    consecutiveThreshold: 7,
+    totalThreshold: 20,
+    enabled: true,
+};
+function hashParams(params) {
+    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) {
+    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) {
+    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, consecutiveCount, totalCount, isFinal) {
+    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 = {}) {
+    const cfg = { ...DEFAULTS, ...config };
+    let history = [];
+    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 ?? []);
+            let lastAi = null;
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const msg = messages[i];
+                if (msg?._getType?.() === "ai") {
+                    lastAi = msg;
+                    break;
+                }
+            }
+            if (!lastAi)
+                return;
+            const toolCalls = lastAi.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}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=loop-detection.js.map

package/dist/middleware/loop-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-detection.js","sourceRoot":"","sources":["../../src/middleware/loop-detection.ts"],"names":[],"mappings":"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"}

package/dist/middleware/otel-spans.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+export declare function createOtelSpansMiddleware(config?: Partial<OtelSpansConfig>): StigmerMiddleware;

package/dist/middleware/otel-spans.js

@@ -0,0 +1,177 @@
+/**
+ * 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.
+ */
+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) {
+    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 = {}) {
+    const toolServerMap = config.toolServerMap ?? new Map();
+    // Metric instruments are created lazily on first use
+    let metricsInitialized = false;
+    let llmCallDuration = null;
+    let llmCallCount = null;
+    let llmTokensInput = null;
+    let llmTokensOutput = null;
+    let mcpToolDuration = null;
+    let mcpToolCount = null;
+    async function ensureMetrics() {
+        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 ?? {};
+            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.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;
+            }
+        },
+    };
+}
+//# sourceMappingURL=otel-spans.js.map

package/dist/middleware/otel-spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-spans.js","sourceRoot":"","sources":["../../src/middleware/otel-spans.ts"],"names":[],"mappings":"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"}

package/dist/middleware/think-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { z } from "zod";
+export declare function createThinkTool(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    thought: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    thought: string;
+}, {
+    thought: string;
+}>, {
+    thought: string;
+}, {
+    thought: string;
+}, string, unknown, "think">;

package/dist/middleware/think-tool.js

@@ -0,0 +1,33 @@
+/**
+ * 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) => "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."),
+        }),
+    });
+}
+//# sourceMappingURL=think-tool.js.map

package/dist/middleware/think-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"think-tool.js","sourceRoot":"","sources":["../../src/middleware/think-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,CACT,KAAK,EAAE,MAA2B,EAAE,EAAE,CAAC,IAAI,EAC3C;QACE,IAAI,EAAE,OAAO;QACb,WAAW,EACT,yDAAyD;YACzD,8EAA8E;YAC9E,4EAA4E;YAC5E,kCAAkC;YAClC,4BAA4B;YAC5B,qEAAqE;YACrE,qEAAqE;YACrE,iEAAiE;YACjE,mEAAmE;YACnE,kEAAkE;YAClE,yDAAyD;QAC3D,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;SACnE,CAAC;KACH,CACF,CAAC;AACJ,CAAC"}

package/dist/middleware/tool-truncation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 type { StigmerMiddleware, ToolTruncationConfig } from "./types.js";
+export declare function createToolTruncationMiddleware(config?: Partial<ToolTruncationConfig>): StigmerMiddleware & {
+    readonly truncationCount: number;
+    readonly totalCharsTruncated: number;
+};