@tangle-network/agent-eval 0.116.0 → 0.117.0

package/dist/{insight-report-oMVxDTxl.d.ts → insight-report-DY4nDW9Q.d.ts}

@@ -1,4 +1,4 @@
-import { G as GainDistributionBin, P as ParetoFigureSpec } from './summary-report-DTNgQycC.js';
+import { G as GainDistributionBin, P as ParetoFigureSpec } from './summary-report-C5bKFfm-.js';
 import { C as ContinuousAgreement } from './judge-calibration-7C-IDmKr.js';
 
 /**

package/dist/{integrity-C6PZ73iC.d.ts → integrity-DqlBiLyK.d.ts}

@@ -1,6 +1,6 @@
 import { C as CaptureIntegrityError } from './errors-oeQrLqXC.js';
-import { R as RawProviderSink } from './store-9cAScOcb.js';
-import { T as TraceStore } from './store-BsVi7ncX.js';
+import { R as RawProviderSink } from './raw-provider-sink-C46HDghv.js';
+import { T as TraceStore } from './store-DGqD0Pyo.js';
 
 /**
  * Run-completion integrity check — at end of run, verify the expected event

package/dist/{kind-factory-DWOvXjR_.d.ts → kind-factory-ClZmO25A.d.ts}

@@ -1,7 +1,7 @@
 import { AxAIService, AxFunction } from '@ax-llm/ax';
-import { T as TraceAnalysisStore } from './store-9cAScOcb.js';
+import { T as TraceAnalysisStore } from './store-C1YxJDEK.js';
 import { z } from 'zod';
-import { h as AnalystCost, b as AnalystContext, A as Analyst } from './policy-edit-Clb2v6Oa.js';
+import { g as AnalystCost, a as AnalystContext, A as Analyst } from './policy-edit-wG9uFEFm.js';
 
 /**
  * Typed Ax output for analyst findings.

package/dist/llm-client-qoDd18Qz.d.ts

@@ -0,0 +1,289 @@
+import { c as CostReceiptInput, M as MaximumCharge } from './cost-ledger-DWy3XdJc.js';
+import { A as AgentEvalError, C as CaptureIntegrityError } from './errors-oeQrLqXC.js';
+import { R as RawProviderSink, P as ProviderRedactor } from './raw-provider-sink-C46HDghv.js';
+
+/**
+ * LLM client with graceful degrade.
+ *
+ * OpenAI-compatible `/v1/chat/completions` client with:
+ *   - Exponential-backoff retry on 429 + 5xx gateway errors (502/503/504).
+ *   - Retry on transient network errors (fetch failed, AbortError, ECONNRESET).
+ *   - Graceful json_schema → json_object degrade on 400 with schema-reject body.
+ *   - Fenced-JSON stripping (```json ... ```) for models that wrap structured output.
+ *   - Configurable base URL + api key / bearer, works with LiteLLM proxies, OpenAI
+ *     directly, cli-bridge subscriptions, and any router that speaks the spec.
+ *
+ * Usage:
+ *   const { value, result } = await callLlmJson<MyType>(
+ *     { model: 'gpt-4o', messages: [...], jsonSchema: { name: 'x', schema: {...} } },
+ *     { baseUrl: 'https://router.tangle.tools/v1', apiKey: process.env.KEY },
+ *   )
+ *
+ * This is THE llm-calling seam for agent-eval primitives that need structured
+ * output (semantic concept judge, reviewer directives, critic scores). Primitives
+ * that need free-form text use `callLlm` and parse output themselves.
+ */
+
+interface LlmMessage {
+    role: 'system' | 'user' | 'assistant';
+    /**
+     * Either a plain text content string OR a multimodal content array
+     * (text + image_url parts) for vision-capable models.
+     */
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image_url';
+        image_url: {
+            url: string;
+            detail?: 'auto' | 'low' | 'high';
+        };
+    }>;
+}
+interface LlmCallRequest {
+    model: string;
+    messages: LlmMessage[];
+    /** Optional JSON-mode response format (response_format: json_object). */
+    jsonMode?: boolean;
+    /** Optional structured output via JSON Schema. Falls back to json_object on 400. */
+    jsonSchema?: {
+        name: string;
+        schema: Record<string, unknown>;
+    };
+    temperature?: number;
+    maxTokens?: number;
+    /** Per-call timeout, default 300s. */
+    timeoutMs?: number;
+}
+/** Conservative priced bound for the exact text request sent to a provider.
+ * Returns undefined when output or multimodal input is not bounded, causing a
+ * capped CostLedger to reject the call before execution. */
+declare function maximumChargeForLlmRequest(request: Pick<LlmCallRequest, 'model' | 'messages' | 'jsonSchema' | 'maxTokens'>, options?: LlmClientOptions): MaximumCharge | undefined;
+interface LlmUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** False when the provider omitted or malformed prompt/completion usage. */
+    captured?: boolean;
+    /** Proxies populate this when prompt caching is on. */
+    cachedPromptTokens?: number;
+}
+interface LlmCallResult {
+    /** The text content of the first choice. Empty string if none. */
+    content: string;
+    usage: LlmUsage;
+    /**
+     * Cost in USD. Pulled from proxy's `_response_cost` field when present;
+     * `null` when neither the proxy nor the caller can derive it.
+     */
+    costUsd: number | null;
+    /** Model name actually used (echoed from response). */
+    model: string;
+    /** Wall-clock duration of the HTTP call (last attempt, if retried). */
+    durationMs: number;
+    /**
+     * `finish_reason` echoed from the first choice (`stop`, `length`,
+     * `content_filter`, `tool_calls`, ...). `null` when the provider omits it.
+     * Exposed so a free-form `callLlm` caller CAN detect a truncated answer
+     * (`length`) instead of treating a cut-off completion as complete. Note:
+     * `callLlm` does not itself reject on it — acting on this signal is the
+     * caller's responsibility (in-repo free-form drivers do not yet enforce it).
+     */
+    finishReason?: string | null;
+    /**
+     * True when `content.trim()` is empty. An empty completion is a silent zero
+     * for free-form `callLlm` callers; this flag is the signal a caller can
+     * inspect to fail loud rather than proceed on an empty string. `callLlm`
+     * surfaces it but does not throw on it.
+     */
+    contentEmpty?: boolean;
+    /** Raw response body. */
+    raw: Record<string, unknown>;
+}
+type LlmCallMetadata = Pick<LlmCallResult, 'usage' | 'costUsd' | 'model' | 'durationMs'>;
+/** Convert a provider result into the canonical paid-call receipt input. */
+declare function costReceiptFromLlm(result: LlmCallResult): CostReceiptInput;
+/** Structured-response failures retain their completed provider receipt. */
+declare function costReceiptFromLlmError(error: Error): CostReceiptInput | undefined;
+declare class LlmCallError extends AgentEvalError {
+    readonly status: number;
+    readonly body: string;
+    readonly model: string;
+    constructor(message: string, status: number, body: string, model: string);
+}
+/** A provider response completed and incurred measurable usage, but its content
+ *  could not satisfy the caller's response contract. The response envelope is
+ *  retained so accounting can commit the receipt before the error propagates. */
+declare class LlmResponseError extends AgentEvalError {
+    readonly result: LlmCallResult;
+    constructor(message: string, result: LlmCallResult, options?: {
+        cause?: unknown;
+    });
+}
+interface LlmClientOptions {
+    /** Base URL (without trailing slash). Must end at the `/v1` prefix. */
+    baseUrl?: string;
+    /** Bearer token — either `apiKey` or `bearer` populates `Authorization: Bearer ...`. */
+    apiKey?: string;
+    bearer?: string;
+    /** Override for the `Authorization` header (e.g. `X-Auth: ...`). Takes precedence over apiKey/bearer. */
+    authHeader?: {
+        name: string;
+        value: string;
+    };
+    /** Stable provider idempotency key, reused across retries of this logical call. */
+    idempotencyKey?: string;
+    /** Default timeout in ms. Per-call can override. */
+    defaultTimeoutMs?: number;
+    /**
+     * Caller-supplied abort signal — e.g. a campaign-wide cancel. Linked to
+     * each attempt's per-attempt timeout controller, so aborting it cancels
+     * the in-flight fetch. A caller abort is FATAL: it is not retried even
+     * though an AbortError otherwise matches the transient patterns.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cross-attempt wall-clock budget in ms, measured from the first attempt.
+     * Before launching each attempt the loop checks the remaining budget and
+     * stops retrying once it is exhausted, rather than waiting the full
+     * per-attempt timeout on every retry. Bounds total time independent of
+     * total attempts × `timeoutMs`.
+     */
+    deadlineMs?: number;
+    /** Total provider attempts. Legacy option name; default 3 (1 initial + 2 retries). */
+    maxRetries?: number;
+    /** Fetch implementation — defaults to global `fetch`. Override for custom transport (e.g. tests). */
+    fetch?: typeof fetch;
+    /**
+     * Optional raw HTTP capture sink. When provided, every request, response,
+     * and error (across all retry attempts) is recorded to the sink, with auth
+     * headers and credential-shaped body fields redacted by default. This is
+     * the layer-1 forensics primitive: structured `LlmSpan`s record intent,
+     * raw events record what actually crossed the wire.
+     */
+    rawSink?: RawProviderSink;
+    /**
+     * Logical provider id attached to raw events. When omitted, derived from
+     * `baseUrl` via `providerFromBaseUrl`.
+     */
+    provider?: string;
+    /** Trace context attached to raw events; populated by emitter-aware callers. */
+    traceContext?: {
+        runId?: string;
+        spanId?: string;
+    };
+    /** Override the redaction strategy for this call. Defaults to `defaultProviderRedactor`. */
+    redactor?: ProviderRedactor;
+}
+/**
+ * True when an error is a transient transport/network fault worth retrying,
+ * as opposed to a deterministic failure (4xx schema reject, JSON parse) that
+ * a retry cannot fix. Inspects `LlmCallError.status`, then the error's
+ * name/message/code, then recurses into `error.cause` — undici nests the
+ * real socket fault one or more levels under `.cause`.
+ *
+ * This is THE retry classifier for the package: `callLlm` and
+ * `withJudgeRetry` both route through it, so a connection-class error is
+ * treated identically whether it surfaces in the HTTP client or a
+ * TCloud-backed judge.
+ */
+declare function isTransientLlmError(err: unknown): boolean;
+/** Exponential backoff: 500ms, 1s, 2s, 4s, ... capped at 16s. Attempt is 0-indexed. */
+declare function backoffMs(attempt: number): number;
+/**
+ * Strip a ```json / ``` code fence if the model emitted one.
+ * Idempotent for naked JSON. Some models (claude-code via router, certain
+ * deepseek models) wrap output even under json_object.
+ */
+declare function stripFencedJson(raw: string): string;
+/**
+ * Low-level call. Returns raw content + usage + cost. Retries on transient
+ * failures; does NOT degrade schema here — callers that want graceful
+ * degrade use `callLlmJson`.
+ */
+declare function callLlm(req: LlmCallRequest, opts?: LlmClientOptions): Promise<LlmCallResult>;
+/**
+ * Structured-output call. Returns parsed JSON plus the raw result envelope.
+ * Degrades `jsonSchema` → `jsonMode` on a 400 that names the schema param —
+ * critical for deepseek-v3/v4, kimi-k2.6, and other models that don't accept
+ * the `response_format.json_schema` shape but DO accept `json_object`.
+ */
+declare function callLlmJson<T = unknown>(req: LlmCallRequest, opts?: LlmClientOptions): Promise<{
+    value: T;
+    result: LlmCallResult;
+}>;
+type LlmRouteAssertionReason = 'no_explicit_base_url' | 'base_url_blocked' | 'base_url_not_allowed' | 'no_auth' | 'wrong_provider';
+declare class LlmRouteAssertionError extends CaptureIntegrityError {
+    readonly reason: LlmRouteAssertionReason;
+    readonly baseUrl: string;
+    constructor(message: string, reason: LlmRouteAssertionReason, baseUrl: string);
+}
+interface LlmRouteRequirements {
+    /**
+     * Throw if `opts.baseUrl` is undefined, i.e. the call would fall back to
+     * `DEFAULT_BASE_URL`. Set this for evaluation runs where silently using
+     * the public/free-tier router is a defect — the launch reviewer needs to
+     * know exactly which provider answered.
+     */
+    requireExplicitBaseUrl?: boolean;
+    /**
+     * Allowlist of acceptable base URLs. Strings match by prefix
+     * (case-insensitive); RegExps test against the full base URL.
+     */
+    allowedBaseUrls?: Array<string | RegExp>;
+    /** Blocklist that takes precedence over `allowedBaseUrls`. */
+    blockedBaseUrls?: Array<string | RegExp>;
+    /** Throw if no auth header / api key is configured. */
+    requireAuth?: boolean;
+    /**
+     * Logical provider id the configured `baseUrl` is expected to match (via
+     * `providerFromBaseUrl`). Mainly useful when paired with `requireExplicitBaseUrl`.
+     */
+    expectedProvider?: string;
+}
+/**
+ * Fail-loud assertion that the configured LLM client points at the route
+ * the caller intends. Designed for the matrix-runner preflight: invoke
+ * once before any LLM call to catch misconfiguration before a sweep burns
+ * dollars on the wrong provider.
+ *
+ * Throws `LlmRouteAssertionError`. Pure — no I/O — so it's safe to call
+ * from constructors and CI gates.
+ */
+declare function assertLlmRoute(opts: LlmClientOptions, req?: LlmRouteRequirements): void;
+/**
+ * Probe whether a model is reachable. Returns latency + null error on
+ * success; `ok=false` + error message on any failure (HTTP, timeout,
+ * network, parse). Designed for sweep preflights — fail loud at the
+ * boundary before burning a 30-leaf run on a misconfigured router.
+ *
+ * Sends a tiny `ping` message with `maxTokens=64`. Reasoning models
+ * (glm-5.1, deepseek-v4) can burn the entire budget on internal reasoning
+ * for short prompts, so don't tighten this further. We don't validate
+ * content; HTTP 200 means reachable.
+ */
+declare function probeLlm(model: string, opts?: LlmClientOptions & {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    latencyMs: number;
+    error: string | null;
+}>;
+/**
+ * Stateful client — construct once with defaults, call many times.
+ * Thin wrapper around the free functions; exists for callers that want
+ * to inject a single configured instance into multiple primitives.
+ */
+declare class LlmClient {
+    readonly maximumAttempts: number;
+    private readonly opts;
+    constructor(opts?: LlmClientOptions);
+    call(req: LlmCallRequest, per?: LlmClientOptions): Promise<LlmCallResult>;
+    callJson<T = unknown>(req: LlmCallRequest, per?: LlmClientOptions): Promise<{
+        value: T;
+        result: LlmCallResult;
+    }>;
+}
+
+export { type LlmCallMetadata as L, type LlmClientOptions as a, type LlmRouteRequirements as b, type LlmCallRequest as c, type LlmCallResult as d, type LlmUsage as e, LlmCallError as f, LlmClient as g, type LlmMessage as h, LlmResponseError as i, LlmRouteAssertionError as j, assertLlmRoute as k, backoffMs as l, callLlm as m, callLlmJson as n, costReceiptFromLlm as o, costReceiptFromLlmError as p, isTransientLlmError as q, maximumChargeForLlmRequest as r, probeLlm as s, stripFencedJson as t };

package/dist/meta-eval/index.d.ts

@@ -1,15 +1,16 @@
-export { C as CalibrationBin, a as CalibrationOptions, b as CalibrationPair, c as CalibrationReport, d as CorrelationResult, e as CorrelationStudyOptions, f as CorrelationStudyResult, E as EvalMetricSpec, O as OutcomePair, g as calibrationCurve, h as calibrationFromPairs, i as correlationStudy } from '../calibration-Dz8TQV4y.js';
+export { C as CalibrationBin, a as CalibrationOptions, b as CalibrationPair, c as CalibrationReport, d as CorrelationResult, e as CorrelationStudyOptions, f as CorrelationStudyResult, E as EvalMetricSpec, O as OutcomePair, g as calibrationCurve, h as calibrationFromPairs, i as correlationStudy } from '../calibration-C8MTS7cw.js';
 export { D as DeploymentOutcome, F as FileSystemOutcomeStore, a as FileSystemOutcomeStoreOptions, I as InMemoryOutcomeStore, O as OutcomeFilter, b as OutcomeStore } from '../outcome-store-rnXLEqSn.js';
-export { R as RubricOutcomePair, a as RubricPredictiveValidityInput, b as RubricPredictiveValidityReport, c as RubricRanking, r as rubricPredictiveValidity } from '../rubric-predictive-validity-BIdf9h4R.js';
+export { R as RubricOutcomePair, a as RubricPredictiveValidityInput, b as RubricPredictiveValidityReport, c as RubricRanking, r as rubricPredictiveValidity } from '../rubric-predictive-validity-p49lLVrE.js';
 import { C as ContinuousAgreement, a as CalibrationResult, b as ContinuousCalibrationResult, c as CandidateScore, G as GoldenItem } from '../judge-calibration-7C-IDmKr.js';
 import { S as SeriesConvergenceOptions, a as SeriesConvergenceResult } from '../series-convergence-D5OWMBg6.js';
-import { C as CorpusAgreementReport } from '../statistics-oUbOJe-S.js';
-import '../store-BsVi7ncX.js';
-import '../schema-SGWcK9wa.js';
-import '../run-record-CZmcpWPo.js';
+import { C as CorpusAgreementReport } from '../statistics-KUnG73jH.js';
+import '../store-DGqD0Pyo.js';
+import '../schema-B3Q3l9Z_.js';
+import '../run-record-BDH49H2E.js';
 import '@tangle-network/agent-interface';
 import '../errors-oeQrLqXC.js';
-import '../types-C7DGg5ex.js';
+import '../types-BkfcQnxV.js';
+import '../cost-ledger-DWy3XdJc.js';
 import '@tangle-network/tcloud';
 
 /**

package/dist/meta-eval/index.js

@@ -19,7 +19,7 @@ import {
 import {
   aggregateLlm,
   llmSpans
-} from "../chunk-MHNQWM4I.js";
+} from "../chunk-LQUTGLOZ.js";
 import {
   ValidationError
 } from "../chunk-ONWEPEDO.js";

package/dist/multishot/index.d.ts

@@ -1,13 +1,16 @@
-import { J as JudgeScore } from '../types-Ca_63YSD.js';
+import { J as JudgeScore } from '../types-BSw1rOUB.js';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { M as MatrixResult } from '../types-BUxNaJ8c.js';
-import '../policy-edit-Clb2v6Oa.js';
-import '../run-record-CZmcpWPo.js';
+import '../policy-edit-wG9uFEFm.js';
+import '../run-record-BDH49H2E.js';
 import '../errors-oeQrLqXC.js';
-import '../schema-SGWcK9wa.js';
-import '../store-9cAScOcb.js';
-import '../types-C7DGg5ex.js';
+import '../schema-B3Q3l9Z_.js';
+import '../store-C1YxJDEK.js';
+import '../types-BkfcQnxV.js';
+import '../cost-ledger-DWy3XdJc.js';
 import '@tangle-network/tcloud';
+import '../llm-client-qoDd18Qz.js';
+import '../raw-provider-sink-C46HDghv.js';
 import '../verdict-C9MlYujm.js';
 
 interface MultishotMessage {

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "@tangle-network/agent-eval — wire protocol",
-    "version": "0.116.0",
+    "version": "0.117.0",
     "description": "HTTP and stdio RPC interface to agent-eval. The TypeScript runtime is the source of truth; this spec is the contract that cross-language clients (Python, Rust, Go) generate from.\n\nWire-protocol version: 1.0.0. Bumps on breaking changes to request/response schemas.",
     "contact": {
       "name": "Tangle Network",

package/dist/pipelines/index.d.ts

@@ -1,9 +1,9 @@
-import { h as BudgetSpec, R as Run, T as ToolSpan } from '../schema-SGWcK9wa.js';
-import { T as TraceStore, R as RunFilter } from '../store-BsVi7ncX.js';
-export { a as FailureCluster, F as FailureClusterReport, f as failureClusterView } from '../failure-cluster-C48PiReX.js';
-import { T as TrajectoryStep, B as BaselineOptions, a as BaselineReport } from '../baseline-DsNteOgR.js';
-export { c as computeToolUseMetrics } from '../baseline-DsNteOgR.js';
-import { l as llmSpans } from '../query-Ck190MOd.js';
+import { h as BudgetSpec, R as Run, T as ToolSpan } from '../schema-B3Q3l9Z_.js';
+import { T as TraceStore, R as RunFilter } from '../store-DGqD0Pyo.js';
+export { a as FailureCluster, F as FailureClusterReport, f as failureClusterView } from '../failure-cluster-DOAcSJ87.js';
+import { T as TrajectoryStep, B as BaselineOptions, a as BaselineReport } from '../baseline-DKq3gJpP.js';
+export { c as computeToolUseMetrics } from '../baseline-DKq3gJpP.js';
+import { l as llmSpans } from '../query-CF7PG61p.js';
 
 /**
  * BudgetBreachView — aggregates breach events across the corpus.
@@ -121,8 +121,11 @@ interface StuckLoopFinding {
     runId: string;
     toolName: string;
     argHash: string;
+    /** Calls in this episode's densest qualifying interval, not the whole-run total. */
     occurrences: number;
     spanIds: string[];
+    /** Nearest agent ancestor, or the direct parent when ancestry is incomplete. */
+    scopeSpanId?: string;
     /** Milliseconds between first and last call in the loop. */
     windowMs: number;
 }
@@ -134,6 +137,13 @@ interface StuckLoopReport {
 interface StuckLoopOptions {
     /** Minimum call count to flag a loop (default 3). */
     minOccurrences?: number;
+    /** Maximum time between the first and last repeated call (default 60 seconds). */
+    maxWindowMs?: number;
+    /**
+     * Maximum other tool calls allowed between adjacent repeats (default 0).
+     * Set to 1 to detect alternating patterns such as A,B,A,B,A.
+     */
+    maxInterveningToolCalls?: number;
     /** Filter to a specific runId; omit to scan the entire corpus. */
     runId?: string;
 }

package/dist/pipelines/index.js

@@ -4,7 +4,10 @@ import {
   classifyFailure,
   compareToBaseline,
   computeToolUseMetrics
-} from "../chunk-NYFUT3B3.js";
+} from "../chunk-ODVOOEWQ.js";
+import {
+  executionTrackByLane
+} from "../chunk-HHWE3POT.js";
 import {
   interRaterReliability,
   pearsonR
@@ -12,10 +15,12 @@ import {
 import {
   aggregateLlm,
   argHash,
+  hasCapturedToolArgs,
+  isToolSpan,
   llmSpans,
   runFailureClass,
   toolSpans
-} from "../chunk-MHNQWM4I.js";
+} from "../chunk-LQUTGLOZ.js";
 import "../chunk-ONWEPEDO.js";
 import "../chunk-PZ5AY32C.js";
 
@@ -80,7 +85,7 @@ async function failureClusterView(store, options = {}) {
       const trig = spans.find((s) => s.spanId === cls.triggerSpanId);
       if (trig?.kind === "tool") {
         toolName = trig.toolName;
-        argPrefix = argHash(trig.args).slice(0, 16);
+        if (hasCapturedToolArgs(trig)) argPrefix = argHash(trig.args).slice(0, 16);
       } else if (trig?.kind === "judge") {
         dimension = trig.dimension;
       }
@@ -90,7 +95,7 @@ async function failureClusterView(store, options = {}) {
       const errored = ts.filter((t) => t.status === "error").pop();
       if (errored) {
         toolName = errored.toolName;
-        argPrefix = argHash(errored.args).slice(0, 16);
+        if (hasCapturedToolArgs(errored)) argPrefix = argHash(errored.args).slice(0, 16);
       }
     }
     if (!dimension) {
@@ -296,33 +301,97 @@ function defaultExtract(metric) {
 }
 
 // src/pipelines/stuck-loop.ts
+var DEFAULT_MAX_WINDOW_MS = 6e4;
+var DEFAULT_MAX_INTERVENING_TOOL_CALLS = 0;
 async function stuckLoopView(store, options = {}) {
   const minOccurrences = options.minOccurrences ?? 3;
+  const maxWindowMs = options.maxWindowMs ?? DEFAULT_MAX_WINDOW_MS;
+  const maxInterveningToolCalls = options.maxInterveningToolCalls ?? DEFAULT_MAX_INTERVENING_TOOL_CALLS;
+  if (!Number.isInteger(minOccurrences) || minOccurrences < 1) {
+    throw new RangeError("minOccurrences must be a positive integer");
+  }
+  if (!Number.isFinite(maxWindowMs) || maxWindowMs < 0) {
+    throw new RangeError("maxWindowMs must be a finite non-negative number");
+  }
+  if (!Number.isInteger(maxInterveningToolCalls) || maxInterveningToolCalls < 0) {
+    throw new RangeError("maxInterveningToolCalls must be a non-negative integer");
+  }
   const runs = options.runId ? [{ runId: options.runId }] : (await store.listRuns()).map((r) => ({ runId: r.runId }));
   const findings = [];
   for (const { runId } of runs) {
-    const tools = await toolSpans(store, runId);
+    const spans = await store.spans({ runId });
+    const spansById = new Map(spans.map((span) => [span.spanId, span]));
+    const scopedTools = spans.filter(isToolSpan).map((span, sourceIndex) => ({ span, sourceIndex })).sort((a, b) => a.span.startedAt - b.span.startedAt || a.sourceIndex - b.sourceIndex).map(({ span }) => ({ span, ...executionScope(span, spansById) }));
+    const trackByLane = executionTrackByLane(
+      scopedTools.map((call) => {
+        const direct = call.laneSpanId === null || call.laneSpanId === call.scopeSpanId;
+        const timed = direct ? call.span : call.laneSpanId ? spansById.get(call.laneSpanId) : void 0;
+        return {
+          key: executionKey(call),
+          scopeKey: JSON.stringify(call.scopeSpanId),
+          start: timed?.startedAt ?? null,
+          end: timed?.endedAt ?? null
+        };
+      })
+    );
+    const nextToolIndexByTrack = /* @__PURE__ */ new Map();
+    const orderedTools = scopedTools.map((call) => {
+      const trackId = trackByLane.get(executionKey(call));
+      const toolCallIndex = nextToolIndexByTrack.get(trackId) ?? 0;
+      nextToolIndexByTrack.set(trackId, toolCallIndex + 1);
+      return { ...call, toolCallIndex, trackId };
+    });
     const byKey = /* @__PURE__ */ new Map();
-    for (const t of tools) {
-      const h = argHash(t.args);
-      const key = `${t.toolName}\0${h}`;
-      const bucket = byKey.get(key) ?? { spans: [], argHash: h, toolName: t.toolName };
-      bucket.spans.push(t);
+    for (const call of orderedTools) {
+      if (!hasCapturedToolArgs(call.span)) continue;
+      const h = argHash(call.span.args);
+      const key = JSON.stringify([call.trackId, call.span.toolName, h]);
+      const bucket = byKey.get(key) ?? {
+        calls: [],
+        argHash: h,
+        toolName: call.span.toolName,
+        scopeSpanId: call.scopeSpanId
+      };
+      bucket.calls.push(call);
       byKey.set(key, bucket);
     }
-    for (const { spans, argHash: h, toolName } of byKey.values()) {
-      if (spans.length < minOccurrences) continue;
-      const sorted = [...spans].sort((a, b) => a.startedAt - b.startedAt);
-      const first = sorted[0].startedAt;
-      const last = sorted[sorted.length - 1].startedAt;
-      findings.push({
-        runId,
-        toolName,
-        argHash: h,
-        occurrences: sorted.length,
-        spanIds: sorted.map((s) => s.spanId),
-        windowMs: last - first
-      });
+    for (const { calls, argHash: h, toolName, scopeSpanId } of byKey.values()) {
+      if (calls.length < minOccurrences) continue;
+      let episodeStart = 0;
+      for (let episodeEnd = 1; episodeEnd <= calls.length; episodeEnd += 1) {
+        const previous = calls[episodeEnd - 1];
+        const next = calls[episodeEnd];
+        const episodeEnded = next === void 0 || next.span.startedAt - previous.span.startedAt > maxWindowMs || next.toolCallIndex - previous.toolCallIndex - 1 > maxInterveningToolCalls || !callsAreSerial(previous, next);
+        if (!episodeEnded) continue;
+        const episode = calls.slice(episodeStart, episodeEnd);
+        let left = 0;
+        let bestStart = 0;
+        let bestEnd = -1;
+        for (let right = 0; right < episode.length; right += 1) {
+          while (episode[right].span.startedAt - episode[left].span.startedAt > maxWindowMs) {
+            left += 1;
+          }
+          if (right - left > bestEnd - bestStart) {
+            bestStart = left;
+            bestEnd = right;
+          }
+        }
+        if (bestEnd - bestStart + 1 >= minOccurrences) {
+          const loop = episode.slice(bestStart, bestEnd + 1);
+          const first = loop[0].span.startedAt;
+          const last = loop[loop.length - 1].span.startedAt;
+          findings.push({
+            runId,
+            toolName,
+            argHash: h,
+            occurrences: loop.length,
+            spanIds: loop.map((call) => call.span.spanId),
+            ...scopeSpanId ? { scopeSpanId } : {},
+            windowMs: last - first
+          });
+        }
+        episodeStart = episodeEnd;
+      }
     }
   }
   const affectedRuns = new Set(findings.map((f) => f.runId));
@@ -332,6 +401,33 @@ async function stuckLoopView(store, options = {}) {
     totalRuns: runs.length
   };
 }
+function laneKey(call) {
+  return JSON.stringify([call.scopeSpanId, call.laneSpanId]);
+}
+function executionKey(call) {
+  return call.laneSpanId === null || call.laneSpanId === call.scopeSpanId ? JSON.stringify([call.scopeSpanId, call.span.spanId]) : laneKey(call);
+}
+function executionScope(span, spansById) {
+  const directParent = span.parentSpanId;
+  if (!directParent) return { scopeSpanId: null, laneSpanId: null };
+  let currentId = directParent;
+  let laneSpanId = null;
+  const seen = /* @__PURE__ */ new Set();
+  while (currentId && !seen.has(currentId)) {
+    seen.add(currentId);
+    const current = spansById.get(currentId);
+    if (!current) return { scopeSpanId: directParent, laneSpanId: directParent };
+    if (current.kind === "agent") {
+      return { scopeSpanId: current.spanId, laneSpanId: laneSpanId ?? current.spanId };
+    }
+    laneSpanId = current.spanId;
+    currentId = current.parentSpanId;
+  }
+  return { scopeSpanId: directParent, laneSpanId: directParent };
+}
+function callsAreSerial(previous, next) {
+  return previous.span.endedAt !== void 0 && previous.span.endedAt <= next.span.startedAt;
+}
 
 // src/pipelines/tool-waste.ts
 async function toolWasteView(store, options = {}) {