@tangle-network/agent-eval 0.115.3 → 0.117.0

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

@@ -1,4 +1,4 @@
-import { G as GainDistributionBin, P as ParetoFigureSpec } from './summary-report-BJ5aNwZ1.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-qemeBAyx.d.ts → integrity-DqlBiLyK.d.ts}

@@ -1,6 +1,6 @@
 import { C as CaptureIntegrityError } from './errors-oeQrLqXC.js';
 import { R as RawProviderSink } from './raw-provider-sink-C46HDghv.js';
-import { T as TraceStore } from './store-BsVi7ncX.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-ClZmO25A.d.ts

@@ -0,0 +1,171 @@
+import { AxAIService, AxFunction } from '@ax-llm/ax';
+import { T as TraceAnalysisStore } from './store-C1YxJDEK.js';
+import { z } from 'zod';
+import { g as AnalystCost, a as AnalystContext, A as Analyst } from './policy-edit-wG9uFEFm.js';
+
+/**
+ * Typed Ax output for analyst findings.
+ *
+ * Replaces the legacy `findings:string[]` pattern (where every bullet
+ * became a flat-severity `AnalystFinding`) with a structured object
+ * array. Ax binds the field as `findings:json[]` so the provider emits
+ * native structured output; at the kind-factory boundary we Zod-validate
+ * each emitted finding so malformed rows fail loud instead of being
+ * silently lifted with default severity.
+ *
+ * Why not `f.object().array()` directly in the signature? The Ax
+ * signature string `question:string -> findings:json[]` already lets
+ * the provider emit JSON arrays. A Zod boundary is required either
+ * way (the provider can return any JSON), and Zod gives us a single
+ * validation surface independent of which Ax version is installed.
+ */
+
+declare const ANALYST_SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+declare const RawAnalystFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        info: "info";
+        critical: "critical";
+        medium: "medium";
+        low: "low";
+        high: "high";
+    }>;
+    claim: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    evidence_uri: z.ZodString;
+    evidence_excerpt: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    recommended_action: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
+/**
+ * Description embedded into the actor prompt so the LLM knows what
+ * shape to emit. Kept here so kinds share one source of truth rather
+ * than restating the schema in every prompt.
+ */
+declare const RAW_FINDING_SCHEMA_PROMPT = "Each finding MUST be a JSON object with these fields:\n  - severity: one of \"critical\" | \"high\" | \"medium\" | \"low\" | \"info\"\n  - claim: one-sentence statement (max 2000 chars)\n  - subject?: the routing locus this finding is about. It MUST be one of the exact subject forms listed in this kind's instructions above (e.g. `system-prompt:<section>`, `agent-knowledge:wiki:<slug>`, `tool-doc:<tool>`). A free phrase, a bare noun, or any form not in that list is REJECTED at parse time and the finding is discarded \u2014 omit subject entirely rather than guess a form.\n  - evidence_uri: REQUIRED, never blank. Exactly one of \"span://<trace_id>/<span_id>\" (trace evidence), \"artifact://<relative-path>\" (files), \"metric://<name>\" (named scalars) \u2014 ALWAYS cite a real id surfaced by the tools. If you have no citable id, do not emit the finding.\n  - evidence_excerpt?: short quote (<=2000 chars) from the cited span/artifact\n  - confidence: number 0..1 \u2014 0.9+ when backed by exact quotes, 0.6-0.8 for inferred patterns, <0.5 for speculative\n  - rationale?: one or two sentences explaining the reasoning\n  - recommended_action?: concrete change phrased as an imperative (\"Add ...\", \"Replace ...\", \"Stop ...\") \u2014 omit when the finding is purely descriptive\n\nEmit an empty array when the question has no findings to report. Do not fabricate evidence.";
+/**
+ * Validate one row emitted by the LLM. Returns the typed finding on
+ * success; returns `null` and logs the reason on failure so the kind
+ * factory can skip-and-count rather than abort the whole analyst run.
+ */
+declare function parseRawFinding(row: unknown, log?: (msg: string, fields?: Record<string, unknown>) => void): RawAnalystFinding | null;
+
+/**
+ * Analyst-kind factory — the typed way to define trace analysts.
+ *
+ * A "kind" is a specialized analyst whose actor prompt, tool subset,
+ * and Ax recursion config target one failure-mode lens (failure-mode
+ * classification, knowledge gap discovery, knowledge poisoning, recursive
+ * self-improvement, ...). Kinds emit findings in the typed `RawAnalystFinding`
+ * shape via a JSON-array Ax output; the factory validates each row with
+ * Zod and lifts it into `AnalystFinding[]` with no shape guessing.
+ *
+ * Composition rules:
+ *   - Each kind owns its actor description. No generic "answer this
+ *     question" prompt — the prompt names the failure lens.
+ *   - Each kind picks a narrow tool subset from `ANALYST_TOOL_GROUPS`.
+ *     A kind that never needs full-trace dumps can drop `viewTrace` /
+ *     `viewSpans` and stay cheap.
+ *   - Each kind declares its recursion + parallelism budget. Discovery-
+ *     heavy kinds (failure-mode) get higher `maxDepth`; lens kinds
+ *     (poisoning) usually stay at 0 since they have a tighter brief.
+ *
+ * Optimizer hook: kinds may declare `goldens` — labeled examples used
+ * by `AxMiPRO` / `AxBootstrapFewShot` / `AxGEPA` to fit the actor
+ * description programmatically. Stored on the kind, not the registry,
+ * because the right metric is kind-specific.
+ */
+
+/**
+ * Per-kind specification. The factory turns this into a regular
+ * `Analyst<TraceAnalysisStore>` ready for `AnalystRegistry.register()`.
+ */
+interface TraceAnalystKindSpec {
+    /** Stable id. Appears in finding_id, telemetry, and registry exclusions. */
+    id: string;
+    /** One-sentence description shown in `registry.list()`. */
+    description: string;
+    /** Coarse classification stamped on every emitted finding (`failure-mode`, `knowledge-gap`, ...). */
+    area: string;
+    /** Bump on any breaking change to the actor prompt or output schema. */
+    version: string;
+    /** Actor system prompt. Must instruct the LLM to emit `findings` per the schema. */
+    actorDescription: string;
+    /** Responder system prompt; falls back to a minimal "format the findings" instruction. */
+    responderDescription?: string;
+    /** Tool functions the actor may call. Pick narrow subsets via `ANALYST_TOOL_GROUPS`. */
+    buildTools: (store: TraceAnalysisStore) => AxFunction[];
+    /** Recursion budget. `maxDepth: 0` disables subagents. */
+    recursion?: {
+        maxDepth: number;
+        maxParallelSubagents?: number;
+    };
+    /** Actor turn cap. Default 12. */
+    maxTurns?: number;
+    /** Runtime char cap. Default 6000. */
+    maxRuntimeChars?: number;
+    /** Cost classification surfaced in `registry.list()` and budget enforcement. */
+    cost: AnalystCost;
+    /** Per-finding-row hook — kinds may reject / rewrite before lifting. */
+    postProcess?: (row: RawAnalystFinding, ctx: AnalystContext) => RawAnalystFinding | null;
+    /** Optional optimizer hook — populated when a kind wants to fit its prompt against labeled examples. */
+    goldens?: TraceAnalystGolden[];
+}
+/**
+ * One labeled example consumed by Ax optimizers (MIPRO / GEPA / Bootstrap).
+ * Each input is the same `{question}` an analyst would receive; `expected`
+ * is the ground-truth finding set a fitted prompt should produce on this
+ * input. Metric: kind-specific (default: F1 on `finding_id` overlap).
+ */
+interface TraceAnalystGolden {
+    question: string;
+    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
+}
+interface CreateTraceAnalystKindOpts {
+    /** AxAIService bound at registration time. */
+    ai: AxAIService;
+    /** Optional model override; falls back to the AI service's default. */
+    model?: string;
+    /** Override the spec's `version` (e.g. when an optimizer has fitted a new prompt). */
+    versionSuffix?: string;
+    /**
+     * Optional two-phase recovery: when the agentic harvest is empty but the
+     * actor produced a substantive free-form `report`, extract findings from that
+     * prose via a tolerant chat-completions pass (`structureFindings`) — no
+     * strict-emission contract, so it works on weak models. Omit to leave the
+     * actor's harvest as-is (the report is still surfaced fail-loud either way).
+     */
+    recovery?: {
+        baseUrl: string;
+        apiKey?: string;
+        model?: string;
+        fetchImpl?: typeof fetch;
+    };
+}
+/**
+ * Build an `Analyst<TraceAnalysisStore>` from a kind spec.
+ *
+ * Lifts the Ax pipeline once at registration time so the registry
+ * gets a stateless analyst. The Ax agent is freshly constructed per
+ * `analyze()` call (the agent carries chat-log + usage state we don't
+ * want shared across analyst runs).
+ */
+declare function createTraceAnalystKind(spec: TraceAnalystKindSpec, opts: CreateTraceAnalystKindOpts): Analyst<TraceAnalysisStore>;
+/**
+ * Render a compact prior-findings block the actor reads alongside its
+ * brief. Each row is one line so the actor can scan dozens cheaply.
+ * The kind's prompt instructs the actor to (a) check whether a new
+ * cluster matches a prior `finding_id` (carry the id forward via
+ * `id_basis` to keep diffs stable) and (b) raise severity / confidence
+ * when a prior finding has reappeared without remediation.
+ *
+ * Returns the empty string when there are no prior findings — most
+ * runs are "first-of-its-kind" and the prompt stays unchanged.
+ *
+ * Exported for tests + for consumers that build their own actor
+ * prompts (e.g. specialized analysts living outside the default kinds).
+ */
+declare function renderPriorFindings(prior: AnalystContext['priorFindings']): string;
+
+export { ANALYST_SEVERITIES as A, type CreateTraceAnalystKindOpts as C, RAW_FINDING_SCHEMA_PROMPT as R, type TraceAnalystKindSpec as T, type RawAnalystFinding as a, RawAnalystFindingSchema as b, type TraceAnalystGolden as c, createTraceAnalystKind as d, parseRawFinding as p, renderPriorFindings as r };

package/dist/{llm-client-DyqEH4jH.d.ts → llm-client-qoDd18Qz.d.ts}

@@ -1,3 +1,4 @@
+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';
 
@@ -55,10 +56,16 @@ interface LlmCallRequest {
     /** 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;
 }
@@ -94,12 +101,26 @@ interface LlmCallResult {
     /** 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;
@@ -111,6 +132,8 @@ interface LlmClientOptions {
         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;
     /**
@@ -125,10 +148,10 @@ interface LlmClientOptions {
      * 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
-     * `maxRetries` × `timeoutMs`.
+     * total attempts × `timeoutMs`.
      */
     deadlineMs?: number;
-    /** Max retry attempts on retriable errors. Default 3 (1 initial + 2 retries). */
+    /** 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;
@@ -253,6 +276,7 @@ declare function probeLlm(model: string, opts?: LlmClientOptions & {
  * 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>;
@@ -262,4 +286,4 @@ declare class LlmClient {
     }>;
 }
 
-export { type LlmClientOptions as L, type LlmRouteRequirements as a, type LlmCallRequest as b, type LlmCallResult as c, LlmCallError as d, LlmClient as e, type LlmMessage as f, LlmRouteAssertionError as g, type LlmUsage as h, assertLlmRoute as i, backoffMs as j, callLlm as k, callLlmJson as l, isTransientLlmError as m, probeLlm as p, stripFencedJson as s };
+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-DYTLjGWu.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-B7RTi_ix.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,9 +1,16 @@
-import { J as JudgeScore } from '../types-C5gJrOVT.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 '../run-record-B7RTi_ix.js';
+import '../policy-edit-wG9uFEFm.js';
+import '../run-record-BDH49H2E.js';
 import '../errors-oeQrLqXC.js';
-import '../schema-SGWcK9wa.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.115.3",
+    "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 = {}) {