@tangle-network/agent-eval 0.85.0 → 0.89.0

package/dist/chunk-UHMJT4T7.js

@@ -0,0 +1,200 @@
+import {
+  OtlpFileTraceStore,
+  TraceFileMissingError,
+  buildTraceAnalystTools
+} from "./chunk-QAY5UIJO.js";
+
+// src/trace-analyst/prompts.ts
+var TRACE_ANALYST_ACTOR_DESCRIPTION = `You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the \`traces\` namespace.
+
+DISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol \u2014 follow exactly:
+
+1. ALWAYS call \`traces.getDatasetOverview({})\` FIRST without a regex_pattern. The result tells you total_traces, raw_jsonl_bytes, services, agents, models, and sample_trace_ids (real ids \u2014 never fabricate one).
+
+2. Use raw_jsonl_bytes to gauge how expensive raw scans will be. \`filters.regex_pattern\` is the one scan-heavy filter on getDatasetOverview / queryTraces / countTraces \u2014 narrow with indexed fields (has_errors, model_names, service_names, agent_names, time bounds) BEFORE adding a regex on a large dataset.
+
+3. To list more traces than the sample, call \`traces.queryTraces({ filters?, limit, offset? })\`. Each summary carries raw_jsonl_bytes \u2014 use it to choose between viewTrace and searchTrace BEFORE calling either.
+
+4. Per-trace inspection:
+   - SMALL trace (raw_jsonl_bytes well under 150_000): call \`traces.viewTrace({ trace_id })\`. Returns all spans. Per-attribute payloads are head-capped at ~4KB; large \`input.value\` / \`output.value\` / \`llm.input_messages\` will show a \`[trace-analyst truncated: N bytes]\` marker.
+   - LARGE trace (raw_jsonl_bytes near or above 150_000, or you saw an \`oversized\` response): use \`traces.searchTrace({ trace_id, regex_pattern })\` to get bounded SpanMatchRecords (span metadata + matched text + surrounding context). Then call \`traces.viewSpans({ trace_id, span_ids: [...] })\` for surgical reads (~16KB cap, 4\xD7 higher than discovery), or \`traces.searchSpan({ trace_id, span_id, regex_pattern })\` for one large span. Stays bounded regardless of trace size.
+   - Useful regex patterns: \`STATUS_CODE_ERROR\` (failures), tool names like \`grep\` or \`view_trace\`, error strings like \`MaxTurnsExceeded\`, model names, attribute keys.
+
+5. ONLY call viewTrace / viewSpans / searchTrace / searchSpan with trace/span ids you have already seen in sample_trace_ids, a queryTraces page, or a previous search result. Never invent ids.
+
+5a. **Result-shape contract** \u2014 searchTrace and searchSpan return \`{ trace_id, hits, total_matches, has_more }\`. Iterate \`result.hits\` (NOT result.matches). Each hit has \`{ span_id, span_name, span_kind, attribute_path, matched_text, context_before, context_after, match_offset }\`. viewTrace returns \`{ trace_id, spans }\` (or \`oversized\`). viewSpans returns \`{ trace_id, spans, missing_span_ids, truncated_attribute_count }\`. Never assume a field name \u2014 log the result shape first if unsure.
+
+6. If viewTrace returns an \`oversized\` summary instead of \`spans\`, DO NOT retry the same call. Read the summary's top_span_names, span_count, span_response_bytes_max, error_span_count to plan a follow-up: switch to searchTrace (or searchSpan for one large span), then viewSpans on a smaller, surgical span_ids set.
+
+7. If searchTrace or searchSpan returns has_more=true, REFINE the regex to be more specific rather than blindly raising max_matches.
+
+8. If a tool errors (invalid regex, range error), STOP and reconsider \u2014 don't retry with a guessed id or argument. Use the discovery tools above to recover.
+
+9. If a ~4KB-truncated payload from viewTrace / searchTrace matters for your answer, first try viewSpans on that span id (~16KB cap). If a 16KB-truncated payload from viewSpans still matters, narrow further with searchSpan against a more specific regex rather than asking for the full payload again.
+
+10. If maxDepth > 0 and the question splits into independent semantic branches, delegate well-defined subtasks to subagents using \`await llmQuery(...)\`. Pass narrow context and a focused query. Examples:
+
+    const reviews = await llmQuery([
+      { query: 'Drill into trace abc123 \u2014 what tool calls preceded the failure?', context: { trace_id: 'abc123' } },
+      { query: 'Drill into trace def456 \u2014 same failure mode?', context: { trace_id: 'def456' } },
+    ]);
+
+OBSERVABILITY rules:
+- Each non-final actor turn must emit at least one \`console.log(...)\` for evidence. Up to 3 logs per turn is fine when correlating multiple data sources (e.g. one log for findings list, one for source-file content, one for derived analysis).
+- Do NOT combine \`console.log\` with \`final(...)\` or \`askClarification(...)\` in the same turn \u2014 finish gathering data first, then call final on its own turn.
+- Reuse runtime variables across turns; don't recompute.
+- When done, call \`await final(answer)\` with the fully-formed report. The responder rewrites the answer into output fields; if you only pass a vague summary string the responder has nothing concrete to format.
+
+CRITICAL \u2014 \`final()\` payload contract for evidence-grounded analysis tasks:
+- Pass a STRUCTURED object as the second arg with the actual data the responder needs to format the answer. Do NOT pass abstract instructions; pass evidence.
+- Example for per-item verdict tasks:
+  \`\`\`js
+  await final("Format the per-item verdict report from the evidence below.", {
+    findings: [
+      { id: 'sub-1-finding-1', claim: '...', verdict: 'TRUE-POSITIVE', evidence: 'lines 42-45 of contracts/X.sol show ...' },
+      ...all items
+    ],
+    systemic_summary: '3 sentences I wrote based on the evidence above'
+  });
+  \`\`\`
+- Calling \`final("answer", {})\` with no evidence is a failure mode \u2014 the responder will hallucinate or echo back the field names. Always include the gathered data.
+- Premature final after a single viewSpans call is INSUFFICIENT for per-finding analysis tasks. Read the requested attributes (e.g. \`spans[i].attributes['redteam.finding.title']\`), and for each one perform the requested cross-reference (e.g. read the source SPAN's \`attributes['source.content']\`).
+
+OUTPUT contract \u2014 your final answer must include:
+- A clear prose conclusion answering the user's question.
+- Trace ids and span ids cited as evidence for each claim.
+- Failure modes named in the user's domain language, with frequency and concrete examples.
+
+Do NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.`;
+var TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v5-2026-05-06";
+var TRACE_ANALYST_SUBAGENT_DESCRIPTION = `You are a trace-analyst subagent. Your parent has delegated a focused trace-inspection question. Use the same DISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol but stay tightly scoped: do exactly what was asked, return a concise compact answer, do NOT spawn further subagents unless the parent's question is genuinely multi-branch.
+
+Cite trace ids and span ids for every claim. Do NOT invent ids.`;
+
+// src/trace-analyst/analyst.ts
+import { AxJSRuntime, agent } from "@ax-llm/ax";
+async function analyzeTraces(input, options) {
+  if (!input.question || typeof input.question !== "string") {
+    throw new TypeError("analyzeTraces: input.question must be a non-empty string");
+  }
+  const store = typeof options.source === "string" ? new OtlpFileTraceStore({ path: options.source }) : options.source;
+  if (store instanceof OtlpFileTraceStore) {
+    await store.ensureIndexed();
+  }
+  const tools = buildTraceAnalystTools({ store });
+  const turns = [];
+  let progressFs;
+  if (options.progressLogPath) {
+    const { createWriteStream } = await import("fs");
+    const { mkdir } = await import("fs/promises");
+    const { dirname } = await import("path");
+    await mkdir(dirname(options.progressLogPath), { recursive: true });
+    progressFs = createWriteStream(options.progressLogPath, { flags: "a" });
+  }
+  const actorTurnCallback = async (turn) => {
+    const snap = {
+      turn: turn.turn,
+      isError: turn.isError,
+      code: turn.code,
+      output: turn.output,
+      thought: turn.thought
+    };
+    turns.push(snap);
+    if (progressFs) {
+      try {
+        progressFs.write(`${JSON.stringify({ ...snap, ts: Date.now() })}
+`);
+      } catch {
+      }
+    }
+    if (options.onTurn) await options.onTurn(snap);
+  };
+  const maxDepth = options.maxDepth ?? 1;
+  const maxTurns = options.maxTurns ?? 12;
+  const maxParallelSubagents = options.maxParallelSubagents ?? 2;
+  const maxRuntimeChars = options.maxRuntimeChars ?? 6e3;
+  const analyst = agent(
+    // `reasoning!` is an internal (Ax `!`) scratchpad field: generated first to
+    // force reason-before-conclude, stripped from the returned output — so the
+    // consumed shape stays { answer, findings }. Brings the trace-analyst to the
+    // same prose-first CoT ordering the kind-factory gets from its `report` field.
+    "question:string -> reasoning!:string, answer:string, findings:string[]",
+    {
+      agentIdentity: {
+        name: "TraceAnalyst",
+        description: "Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes."
+      },
+      contextFields: ["question"],
+      runtime: new AxJSRuntime({
+        permissions: [],
+        blockDynamicImport: true,
+        allowedModules: [],
+        freezeIntrinsics: true,
+        blockShadowRealm: true,
+        // RLM stdout mode relies on runtime bindings persisting across turns.
+        preventGlobalThisExtensions: false
+      }),
+      mode: maxDepth > 0 ? "advanced" : "simple",
+      recursionOptions: maxDepth > 0 ? { maxDepth } : void 0,
+      maxTurns,
+      maxRuntimeChars,
+      maxBatchedLlmQueryConcurrency: maxParallelSubagents,
+      promptLevel: "detailed",
+      // Trace analysis depends on exact prior tool results and runtime variables.
+      contextPolicy: { preset: "full", budget: "balanced" },
+      functions: { local: tools },
+      actorOptions: {
+        description: options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION,
+        ...options.model ? { model: options.model } : {},
+        // Keep actor messages tool-call/content shaped across reasoning models.
+        showThoughts: false,
+        thinkingTokenBudget: "none"
+      },
+      responderOptions: {
+        ...options.model ? { model: options.model } : {},
+        description: options.subagentDescription ?? TRACE_ANALYST_SUBAGENT_DESCRIPTION,
+        showThoughts: false
+      },
+      actorTurnCallback,
+      bubbleErrors: [TraceFileMissingError]
+    }
+  );
+  let result;
+  try {
+    result = await analyst.forward(options.ai, { question: input.question });
+  } finally {
+    if (progressFs) {
+      await new Promise((resolve) => progressFs.end(() => resolve()));
+    }
+  }
+  return {
+    answer: typeof result.answer === "string" ? result.answer : String(result.answer ?? ""),
+    findings: Array.isArray(result.findings) ? result.findings.filter((s) => typeof s === "string") : [],
+    turns,
+    turnCount: turns.length,
+    usage: normalizeRoleArrays(analyst.getUsage()),
+    chatLog: normalizeRoleArrays(analyst.getChatLog()),
+    actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION
+  };
+}
+function normalizeRoleArrays(value) {
+  const record = value && typeof value === "object" ? value : {};
+  return {
+    actor: normalizeRecordArray(record.actor),
+    responder: normalizeRecordArray(record.responder)
+  };
+}
+function normalizeRecordArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(
+    (item) => item && typeof item === "object" ? { ...item } : { value: item }
+  );
+}
+
+export {
+  TRACE_ANALYST_ACTOR_DESCRIPTION,
+  TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,
+  TRACE_ANALYST_SUBAGENT_DESCRIPTION,
+  analyzeTraces
+};
+//# sourceMappingURL=chunk-UHMJT4T7.js.map

package/dist/chunk-UHMJT4T7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-analyst/prompts.ts","../src/trace-analyst/analyst.ts"],"sourcesContent":["/** Ax RLM prompt for bounded trace discovery and evidence-backed analysis. */\n\nexport const TRACE_ANALYST_ACTOR_DESCRIPTION = `You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the \\`traces\\` namespace.\n\nDISCOVERY → NARROW → DEEP-READ protocol — follow exactly:\n\n1. ALWAYS call \\`traces.getDatasetOverview({})\\` FIRST without a regex_pattern. The result tells you total_traces, raw_jsonl_bytes, services, agents, models, and sample_trace_ids (real ids — never fabricate one).\n\n2. Use raw_jsonl_bytes to gauge how expensive raw scans will be. \\`filters.regex_pattern\\` is the one scan-heavy filter on getDatasetOverview / queryTraces / countTraces — narrow with indexed fields (has_errors, model_names, service_names, agent_names, time bounds) BEFORE adding a regex on a large dataset.\n\n3. To list more traces than the sample, call \\`traces.queryTraces({ filters?, limit, offset? })\\`. Each summary carries raw_jsonl_bytes — use it to choose between viewTrace and searchTrace BEFORE calling either.\n\n4. Per-trace inspection:\n   - SMALL trace (raw_jsonl_bytes well under 150_000): call \\`traces.viewTrace({ trace_id })\\`. Returns all spans. Per-attribute payloads are head-capped at ~4KB; large \\`input.value\\` / \\`output.value\\` / \\`llm.input_messages\\` will show a \\`[trace-analyst truncated: N bytes]\\` marker.\n   - LARGE trace (raw_jsonl_bytes near or above 150_000, or you saw an \\`oversized\\` response): use \\`traces.searchTrace({ trace_id, regex_pattern })\\` to get bounded SpanMatchRecords (span metadata + matched text + surrounding context). Then call \\`traces.viewSpans({ trace_id, span_ids: [...] })\\` for surgical reads (~16KB cap, 4× higher than discovery), or \\`traces.searchSpan({ trace_id, span_id, regex_pattern })\\` for one large span. Stays bounded regardless of trace size.\n   - Useful regex patterns: \\`STATUS_CODE_ERROR\\` (failures), tool names like \\`grep\\` or \\`view_trace\\`, error strings like \\`MaxTurnsExceeded\\`, model names, attribute keys.\n\n5. ONLY call viewTrace / viewSpans / searchTrace / searchSpan with trace/span ids you have already seen in sample_trace_ids, a queryTraces page, or a previous search result. Never invent ids.\n\n5a. **Result-shape contract** — searchTrace and searchSpan return \\`{ trace_id, hits, total_matches, has_more }\\`. Iterate \\`result.hits\\` (NOT result.matches). Each hit has \\`{ span_id, span_name, span_kind, attribute_path, matched_text, context_before, context_after, match_offset }\\`. viewTrace returns \\`{ trace_id, spans }\\` (or \\`oversized\\`). viewSpans returns \\`{ trace_id, spans, missing_span_ids, truncated_attribute_count }\\`. Never assume a field name — log the result shape first if unsure.\n\n6. If viewTrace returns an \\`oversized\\` summary instead of \\`spans\\`, DO NOT retry the same call. Read the summary's top_span_names, span_count, span_response_bytes_max, error_span_count to plan a follow-up: switch to searchTrace (or searchSpan for one large span), then viewSpans on a smaller, surgical span_ids set.\n\n7. If searchTrace or searchSpan returns has_more=true, REFINE the regex to be more specific rather than blindly raising max_matches.\n\n8. If a tool errors (invalid regex, range error), STOP and reconsider — don't retry with a guessed id or argument. Use the discovery tools above to recover.\n\n9. If a ~4KB-truncated payload from viewTrace / searchTrace matters for your answer, first try viewSpans on that span id (~16KB cap). If a 16KB-truncated payload from viewSpans still matters, narrow further with searchSpan against a more specific regex rather than asking for the full payload again.\n\n10. If maxDepth > 0 and the question splits into independent semantic branches, delegate well-defined subtasks to subagents using \\`await llmQuery(...)\\`. Pass narrow context and a focused query. Examples:\n\n    const reviews = await llmQuery([\n      { query: 'Drill into trace abc123 — what tool calls preceded the failure?', context: { trace_id: 'abc123' } },\n      { query: 'Drill into trace def456 — same failure mode?', context: { trace_id: 'def456' } },\n    ]);\n\nOBSERVABILITY rules:\n- Each non-final actor turn must emit at least one \\`console.log(...)\\` for evidence. Up to 3 logs per turn is fine when correlating multiple data sources (e.g. one log for findings list, one for source-file content, one for derived analysis).\n- Do NOT combine \\`console.log\\` with \\`final(...)\\` or \\`askClarification(...)\\` in the same turn — finish gathering data first, then call final on its own turn.\n- Reuse runtime variables across turns; don't recompute.\n- When done, call \\`await final(answer)\\` with the fully-formed report. The responder rewrites the answer into output fields; if you only pass a vague summary string the responder has nothing concrete to format.\n\nCRITICAL — \\`final()\\` payload contract for evidence-grounded analysis tasks:\n- Pass a STRUCTURED object as the second arg with the actual data the responder needs to format the answer. Do NOT pass abstract instructions; pass evidence.\n- Example for per-item verdict tasks:\n  \\`\\`\\`js\n  await final(\"Format the per-item verdict report from the evidence below.\", {\n    findings: [\n      { id: 'sub-1-finding-1', claim: '...', verdict: 'TRUE-POSITIVE', evidence: 'lines 42-45 of contracts/X.sol show ...' },\n      ...all items\n    ],\n    systemic_summary: '3 sentences I wrote based on the evidence above'\n  });\n  \\`\\`\\`\n- Calling \\`final(\"answer\", {})\\` with no evidence is a failure mode — the responder will hallucinate or echo back the field names. Always include the gathered data.\n- Premature final after a single viewSpans call is INSUFFICIENT for per-finding analysis tasks. Read the requested attributes (e.g. \\`spans[i].attributes['redteam.finding.title']\\`), and for each one perform the requested cross-reference (e.g. read the source SPAN's \\`attributes['source.content']\\`).\n\nOUTPUT contract — your final answer must include:\n- A clear prose conclusion answering the user's question.\n- Trace ids and span ids cited as evidence for each claim.\n- Failure modes named in the user's domain language, with frequency and concrete examples.\n\nDo NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.`\n\nexport const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = 'trace-analyst-actor-v5-2026-05-06'\n\n/** Subagent prompt for focused trace-inspection subtasks. */\nexport const TRACE_ANALYST_SUBAGENT_DESCRIPTION = `You are a trace-analyst subagent. Your parent has delegated a focused trace-inspection question. Use the same DISCOVERY → NARROW → DEEP-READ protocol but stay tightly scoped: do exactly what was asked, return a concise compact answer, do NOT spawn further subagents unless the parent's question is genuinely multi-branch.\n\nCite trace ids and span ids for every claim. Do NOT invent ids.`\n","import { type AxActorTurn, type AxAIService, type AxFunction, AxJSRuntime, agent } from '@ax-llm/ax'\nimport {\n  TRACE_ANALYST_ACTOR_DESCRIPTION,\n  TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,\n  TRACE_ANALYST_SUBAGENT_DESCRIPTION,\n} from './prompts'\nimport type { TraceAnalysisStore } from './store'\nimport { OtlpFileTraceStore, TraceFileMissingError } from './store-otlp'\nimport { buildTraceAnalystTools } from './tools'\n\nexport interface AnalyzeTracesInput {\n  /** The user-facing question. Domain framing belongs here, not in the\n   *  actor description. */\n  question: string\n}\n\nexport interface AnalyzeTracesResult {\n  /** The responder's prose answer. */\n  answer: string\n  /** Bulleted findings extracted from the responder's structured output. */\n  findings: string[]\n  /** Per-actor-turn snapshots captured via `actorTurnCallback`. */\n  turns: AnalyzeTracesTurnSnapshot[]\n  /** Total turns the actor took. */\n  turnCount: number\n  /** Token usage by role. */\n  usage: TraceAnalystUsage\n  /** Full system + assistant + tool message log by role. */\n  chatLog: TraceAnalystChatLog\n  /** Prompt version that produced this run. */\n  actorPromptVersion: string\n}\n\nexport interface TraceAnalystUsage {\n  actor: TraceAnalystUsageEntry[]\n  responder: TraceAnalystUsageEntry[]\n}\n\nexport interface TraceAnalystUsageEntry {\n  [key: string]: unknown\n}\n\nexport interface TraceAnalystChatLog {\n  actor: TraceAnalystChatMessage[]\n  responder: TraceAnalystChatMessage[]\n}\n\nexport interface TraceAnalystChatMessage {\n  [key: string]: unknown\n}\n\nexport interface AnalyzeTracesTurnSnapshot {\n  turn: number\n  isError: boolean\n  /** The JS code the actor produced for this turn. */\n  code: string\n  /** The formatted action-log entry the actor sees on the next turn. */\n  output: string\n  /** Provider thought (when `actorOptions.showThoughts` is true and the\n   *  provider returns it). */\n  thought?: string\n}\n\nexport interface AnalyzeTracesOptions {\n  /** Trace data source. Pass either an OTLP-JSONL path or a custom store. */\n  source: string | TraceAnalysisStore\n  /** Caller-provided AxAIService. */\n  ai: AxAIService\n  /** Model id forwarded to actor + responder. */\n  model?: string\n  /** Recursion depth. 0 = no sub-agent dispatch. Default 1. */\n  maxDepth?: number\n  /** Maximum actor turns. Default 12. */\n  maxTurns?: number\n  /** Maximum parallel sub-agent calls in batched llmQuery. Default 2. */\n  maxParallelSubagents?: number\n  /** Override the actor description. */\n  actorDescription?: string\n  /** Override the subagent description. */\n  subagentDescription?: string\n  /** Per-turn observability hook. */\n  onTurn?: (turn: AnalyzeTracesTurnSnapshot) => void | Promise<void>\n  /** Override max runtime characters per turn. Default 6000. */\n  maxRuntimeChars?: number\n  /** When set, every turn's snapshot is appended to this JSONL file\n   *  immediately. If the analyst crashes mid-loop (provider 503,\n   *  network error, validator reject) the partial reasoning is still\n   *  on disk. Replay the file with the responder afterward to recover\n   *  evidence. */\n  progressLogPath?: string\n}\n\n/**\n * Run the trace analyst.\n *\n * Throws:\n *   - `TraceFileMissingError` if `source` is a path and doesn't exist.\n *   - `AxAgentClarificationError` if the analyst asks for clarification.\n *   - Provider errors (auth, rate limits) propagate from the AI service.\n */\nexport async function analyzeTraces(\n  input: AnalyzeTracesInput,\n  options: AnalyzeTracesOptions,\n): Promise<AnalyzeTracesResult> {\n  if (!input.question || typeof input.question !== 'string') {\n    throw new TypeError('analyzeTraces: input.question must be a non-empty string')\n  }\n\n  const store: TraceAnalysisStore =\n    typeof options.source === 'string'\n      ? new OtlpFileTraceStore({ path: options.source })\n      : options.source\n\n  // Pre-warm file stores so missing inputs fail before the RLM starts.\n  if (store instanceof OtlpFileTraceStore) {\n    await store.ensureIndexed()\n  }\n\n  const tools: AxFunction[] = buildTraceAnalystTools({ store })\n  const turns: AnalyzeTracesTurnSnapshot[] = []\n\n  // Persist each turn as JSONL so interrupted analyst runs keep useful evidence.\n  let progressFs: import('node:fs').WriteStream | undefined\n  if (options.progressLogPath) {\n    const { createWriteStream } = await import('node:fs')\n    const { mkdir } = await import('node:fs/promises')\n    const { dirname } = await import('node:path')\n    await mkdir(dirname(options.progressLogPath), { recursive: true })\n    progressFs = createWriteStream(options.progressLogPath, { flags: 'a' })\n  }\n\n  const actorTurnCallback = async (turn: AxActorTurn): Promise<void> => {\n    const snap: AnalyzeTracesTurnSnapshot = {\n      turn: turn.turn,\n      isError: turn.isError,\n      code: turn.code,\n      output: turn.output,\n      thought: turn.thought,\n    }\n    turns.push(snap)\n    if (progressFs) {\n      try {\n        progressFs.write(`${JSON.stringify({ ...snap, ts: Date.now() })}\\n`)\n      } catch {\n        // Progress logging must never fail the analyst.\n      }\n    }\n    if (options.onTurn) await options.onTurn(snap)\n  }\n\n  const maxDepth = options.maxDepth ?? 1\n  const maxTurns = options.maxTurns ?? 12\n  const maxParallelSubagents = options.maxParallelSubagents ?? 2\n  const maxRuntimeChars = options.maxRuntimeChars ?? 6000\n\n  const analyst = agent<{ question: string }, { answer: string; findings: string[] }>(\n    // `reasoning!` is an internal (Ax `!`) scratchpad field: generated first to\n    // force reason-before-conclude, stripped from the returned output — so the\n    // consumed shape stays { answer, findings }. Brings the trace-analyst to the\n    // same prose-first CoT ordering the kind-factory gets from its `report` field.\n    'question:string -> reasoning!:string, answer:string, findings:string[]',\n    {\n      agentIdentity: {\n        name: 'TraceAnalyst',\n        description:\n          'Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes.',\n      },\n      contextFields: ['question'],\n      runtime: new AxJSRuntime({\n        permissions: [],\n        blockDynamicImport: true,\n        allowedModules: [],\n        freezeIntrinsics: true,\n        blockShadowRealm: true,\n        // RLM stdout mode relies on runtime bindings persisting across turns.\n        preventGlobalThisExtensions: false,\n      }),\n      mode: maxDepth > 0 ? 'advanced' : 'simple',\n      recursionOptions: maxDepth > 0 ? { maxDepth } : undefined,\n      maxTurns,\n      maxRuntimeChars,\n      maxBatchedLlmQueryConcurrency: maxParallelSubagents,\n      promptLevel: 'detailed',\n      // Trace analysis depends on exact prior tool results and runtime variables.\n      contextPolicy: { preset: 'full', budget: 'balanced' },\n      functions: { local: tools },\n      actorOptions: {\n        description: options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION,\n        ...(options.model ? { model: options.model } : {}),\n        // Keep actor messages tool-call/content shaped across reasoning models.\n        showThoughts: false,\n        thinkingTokenBudget: 'none',\n      },\n      responderOptions: {\n        ...(options.model ? { model: options.model } : {}),\n        description: options.subagentDescription ?? TRACE_ANALYST_SUBAGENT_DESCRIPTION,\n        showThoughts: false,\n      },\n      actorTurnCallback,\n      bubbleErrors: [TraceFileMissingError],\n    },\n  )\n\n  let result: { answer: unknown; findings: unknown }\n  try {\n    result = await analyst.forward(options.ai, { question: input.question })\n  } finally {\n    if (progressFs) {\n      await new Promise<void>((resolve) => progressFs!.end(() => resolve()))\n    }\n  }\n\n  return {\n    answer: typeof result.answer === 'string' ? result.answer : String(result.answer ?? ''),\n    findings: Array.isArray(result.findings)\n      ? result.findings.filter((s): s is string => typeof s === 'string')\n      : [],\n    turns,\n    turnCount: turns.length,\n    usage: normalizeRoleArrays(analyst.getUsage()),\n    chatLog: normalizeRoleArrays(analyst.getChatLog()),\n    actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,\n  }\n}\n\nfunction normalizeRoleArrays(value: unknown): {\n  actor: Record<string, unknown>[]\n  responder: Record<string, unknown>[]\n} {\n  const record = value && typeof value === 'object' ? (value as Record<string, unknown>) : {}\n  return {\n    actor: normalizeRecordArray(record.actor),\n    responder: normalizeRecordArray(record.responder),\n  }\n}\n\nfunction normalizeRecordArray(value: unknown): Record<string, unknown>[] {\n  if (!Array.isArray(value)) return []\n  return value.map((item) =>\n    item && typeof item === 'object' ? { ...(item as Record<string, unknown>) } : { value: item },\n  )\n}\n"],"mappings":";;;;;;;AAEO,IAAM,kCAAkC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8DxC,IAAM,0CAA0C;AAGhD,IAAM,qCAAqC;AAAA;AAAA;;;ACnElD,SAA8D,aAAa,aAAa;AAoGxF,eAAsB,cACpB,OACA,SAC8B;AAC9B,MAAI,CAAC,MAAM,YAAY,OAAO,MAAM,aAAa,UAAU;AACzD,UAAM,IAAI,UAAU,0DAA0D;AAAA,EAChF;AAEA,QAAM,QACJ,OAAO,QAAQ,WAAW,WACtB,IAAI,mBAAmB,EAAE,MAAM,QAAQ,OAAO,CAAC,IAC/C,QAAQ;AAGd,MAAI,iBAAiB,oBAAoB;AACvC,UAAM,MAAM,cAAc;AAAA,EAC5B;AAEA,QAAM,QAAsB,uBAAuB,EAAE,MAAM,CAAC;AAC5D,QAAM,QAAqC,CAAC;AAG5C,MAAI;AACJ,MAAI,QAAQ,iBAAiB;AAC3B,UAAM,EAAE,kBAAkB,IAAI,MAAM,OAAO,IAAS;AACpD,UAAM,EAAE,MAAM,IAAI,MAAM,OAAO,aAAkB;AACjD,UAAM,EAAE,QAAQ,IAAI,MAAM,OAAO,MAAW;AAC5C,UAAM,MAAM,QAAQ,QAAQ,eAAe,GAAG,EAAE,WAAW,KAAK,CAAC;AACjE,iBAAa,kBAAkB,QAAQ,iBAAiB,EAAE,OAAO,IAAI,CAAC;AAAA,EACxE;AAEA,QAAM,oBAAoB,OAAO,SAAqC;AACpE,UAAM,OAAkC;AAAA,MACtC,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,MACd,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,SAAS,KAAK;AAAA,IAChB;AACA,UAAM,KAAK,IAAI;AACf,QAAI,YAAY;AACd,UAAI;AACF,mBAAW,MAAM,GAAG,KAAK,UAAU,EAAE,GAAG,MAAM,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;AAAA,CAAI;AAAA,MACrE,QAAQ;AAAA,MAER;AAAA,IACF;AACA,QAAI,QAAQ,OAAQ,OAAM,QAAQ,OAAO,IAAI;AAAA,EAC/C;AAEA,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,uBAAuB,QAAQ,wBAAwB;AAC7D,QAAM,kBAAkB,QAAQ,mBAAmB;AAEnD,QAAM,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA,IAKd;AAAA,IACA;AAAA,MACE,eAAe;AAAA,QACb,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,eAAe,CAAC,UAAU;AAAA,MAC1B,SAAS,IAAI,YAAY;AAAA,QACvB,aAAa,CAAC;AAAA,QACd,oBAAoB;AAAA,QACpB,gBAAgB,CAAC;AAAA,QACjB,kBAAkB;AAAA,QAClB,kBAAkB;AAAA;AAAA,QAElB,6BAA6B;AAAA,MAC/B,CAAC;AAAA,MACD,MAAM,WAAW,IAAI,aAAa;AAAA,MAClC,kBAAkB,WAAW,IAAI,EAAE,SAAS,IAAI;AAAA,MAChD;AAAA,MACA;AAAA,MACA,+BAA+B;AAAA,MAC/B,aAAa;AAAA;AAAA,MAEb,eAAe,EAAE,QAAQ,QAAQ,QAAQ,WAAW;AAAA,MACpD,WAAW,EAAE,OAAO,MAAM;AAAA,MAC1B,cAAc;AAAA,QACZ,aAAa,QAAQ,oBAAoB;AAAA,QACzC,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;AAAA;AAAA,QAEhD,cAAc;AAAA,QACd,qBAAqB;AAAA,MACvB;AAAA,MACA,kBAAkB;AAAA,QAChB,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;AAAA,QAChD,aAAa,QAAQ,uBAAuB;AAAA,QAC5C,cAAc;AAAA,MAChB;AAAA,MACA;AAAA,MACA,cAAc,CAAC,qBAAqB;AAAA,IACtC;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,aAAS,MAAM,QAAQ,QAAQ,QAAQ,IAAI,EAAE,UAAU,MAAM,SAAS,CAAC;AAAA,EACzE,UAAE;AACA,QAAI,YAAY;AACd,YAAM,IAAI,QAAc,CAAC,YAAY,WAAY,IAAI,MAAM,QAAQ,CAAC,CAAC;AAAA,IACvE;AAAA,EACF;AAEA,SAAO;AAAA,IACL,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS,OAAO,OAAO,UAAU,EAAE;AAAA,IACtF,UAAU,MAAM,QAAQ,OAAO,QAAQ,IACnC,OAAO,SAAS,OAAO,CAAC,MAAmB,OAAO,MAAM,QAAQ,IAChE,CAAC;AAAA,IACL;AAAA,IACA,WAAW,MAAM;AAAA,IACjB,OAAO,oBAAoB,QAAQ,SAAS,CAAC;AAAA,IAC7C,SAAS,oBAAoB,QAAQ,WAAW,CAAC;AAAA,IACjD,oBAAoB;AAAA,EACtB;AACF;AAEA,SAAS,oBAAoB,OAG3B;AACA,QAAM,SAAS,SAAS,OAAO,UAAU,WAAY,QAAoC,CAAC;AAC1F,SAAO;AAAA,IACL,OAAO,qBAAqB,OAAO,KAAK;AAAA,IACxC,WAAW,qBAAqB,OAAO,SAAS;AAAA,EAClD;AACF;AAEA,SAAS,qBAAqB,OAA2C;AACvE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACnC,SAAO,MAAM;AAAA,IAAI,CAAC,SAChB,QAAQ,OAAO,SAAS,WAAW,EAAE,GAAI,KAAiC,IAAI,EAAE,OAAO,KAAK;AAAA,EAC9F;AACF;","names":[]}

package/dist/chunk-UMMZHCPB.js

@@ -0,0 +1,190 @@
+import {
+  AnalystRegistry,
+  DEFAULT_TRACE_ANALYST_KINDS,
+  createTraceAnalystKind
+} from "./chunk-D3V5B42D.js";
+import {
+  makeFinding
+} from "./chunk-45EEMHTC.js";
+
+// src/trace-analyst/behavioral-metrics.ts
+var INPUT_GROWTH_FACTOR = 3;
+var MIN_TOOL_CALLS = 3;
+var VERIFY_RE = /verif|eval|inspect|check|assert|validat|review|confirm/i;
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function inputTokensOf(s) {
+  return num(s.attributes["llm.input_tokens"]) ?? num(s.attributes["llm.usage.input_tokens"]);
+}
+function outputTokensOf(s) {
+  return num(s.attributes["llm.output_tokens"]) ?? num(s.attributes["llm.usage.output_tokens"]);
+}
+function stepOf(s) {
+  return num(s.attributes.step);
+}
+function toolNameOf(s) {
+  if (s.tool_name) return s.tool_name;
+  const t = s.attributes["tool.name"];
+  return typeof t === "string" && t.length > 0 ? t : null;
+}
+function computeTraceMetrics(spans) {
+  const ordered = [...spans].sort((a, b) => {
+    const sa = stepOf(a);
+    const sb = stepOf(b);
+    if (sa !== null && sb !== null && sa !== sb) return sa - sb;
+    return a.start_time.localeCompare(b.start_time);
+  });
+  const inputTokenTrajectory = [];
+  const outputTokenTrajectory = [];
+  const toolHistogram = {};
+  let hasSelfVerification = false;
+  for (const s of ordered) {
+    const inT = inputTokensOf(s);
+    if (inT !== null) inputTokenTrajectory.push(inT);
+    const outT = outputTokensOf(s);
+    if (outT !== null) outputTokenTrajectory.push(outT);
+    const tool = toolNameOf(s);
+    if (tool) {
+      toolHistogram[tool] = (toolHistogram[tool] ?? 0) + 1;
+      if (VERIFY_RE.test(tool)) hasSelfVerification = true;
+    }
+  }
+  const totalToolCalls = Object.values(toolHistogram).reduce((a, b) => a + b, 0);
+  const distinctTools = Object.keys(toolHistogram).length;
+  const toolDiversityRatio = totalToolCalls === 0 ? 1 : distinctTools / totalToolCalls;
+  const signals = [];
+  if (inputTokenTrajectory.length >= 3) {
+    const first = inputTokenTrajectory[0];
+    const last = inputTokenTrajectory[inputTokenTrajectory.length - 1];
+    const growth = first > 0 ? last / first : 0;
+    if (last > first && growth >= INPUT_GROWTH_FACTOR) {
+      signals.push({
+        code: "monotonic-input-growth",
+        severity: "high",
+        detail: `LLM input tokens grew ${growth.toFixed(1)}x (${first}\u2192${last}) across ${inputTokenTrajectory.length} calls \u2014 full history re-sent each step with no compression.`,
+        evidence: {
+          first,
+          last,
+          growth_x: Number(growth.toFixed(2)),
+          calls: inputTokenTrajectory.length
+        }
+      });
+    }
+  }
+  if (outputTokenTrajectory.length >= 3) {
+    const first = outputTokenTrajectory[0];
+    const last = outputTokenTrajectory[outputTokenTrajectory.length - 1];
+    if (last < first) {
+      signals.push({
+        code: "output-length-decay",
+        severity: "medium",
+        detail: `LLM output tokens shrank ${first}\u2192${last} over ${outputTokenTrajectory.length} calls \u2014 less planning/reasoning per step as context grows.`,
+        evidence: { first, last, calls: outputTokenTrajectory.length }
+      });
+    }
+  }
+  if (totalToolCalls >= MIN_TOOL_CALLS && distinctTools === 1) {
+    const only = Object.keys(toolHistogram)[0];
+    signals.push({
+      code: "single-tool-dependency",
+      severity: "medium",
+      detail: `All ${totalToolCalls} tool calls are \`${only}\` \u2014 no tool diversity and no fallback path.`,
+      evidence: { tool: only, calls: totalToolCalls, distinct_tools: 1 }
+    });
+  }
+  if (totalToolCalls >= MIN_TOOL_CALLS && !hasSelfVerification) {
+    signals.push({
+      code: "no-self-verification",
+      severity: "medium",
+      detail: `${totalToolCalls} tool calls and none verify/inspect/check state \u2014 the agent never validates its own actions.`,
+      evidence: { tool_calls: totalToolCalls, verification_calls: 0 }
+    });
+  }
+  return {
+    llmCallCount: inputTokenTrajectory.length,
+    inputTokenTrajectory,
+    outputTokenTrajectory,
+    toolHistogram,
+    totalToolCalls,
+    distinctTools,
+    toolDiversityRatio,
+    hasSelfVerification,
+    signals
+  };
+}
+
+// src/analyst/behavioral-analyst.ts
+var RECOMMENDED_ACTION = {
+  "monotonic-input-growth": "Add a context-budget instruction: once prior context exceeds a threshold, summarize earlier steps into a short status line instead of re-sending full history.",
+  "output-length-decay": "Require a minimum planning/reasoning budget per step so late steps do not degrade into terse, error-prone commands.",
+  "single-tool-dependency": "Direct the agent to use the full toolset (verify / inspect / alternate actions), not a single execute call, and to plan a fallback when a call returns an unexpected result.",
+  "no-self-verification": "After every state-mutating action, verify the result (eval / inspect / assert) before proceeding."
+};
+var ANALYST_ID = "efficiency-behavioral";
+function deriveEfficiencyFindings(metrics, opts = {}) {
+  const analystId = opts.analystId ?? ANALYST_ID;
+  return metrics.signals.map(
+    (sig) => makeFinding({
+      analyst_id: analystId,
+      area: "efficiency",
+      subject: sig.code,
+      // kebab — passes the cluster grammar; stable key for diffFindings
+      claim: sig.detail,
+      severity: sig.severity,
+      // Deterministic arithmetic over spans, not a model judgment → certain.
+      confidence: 1,
+      evidence_refs: [
+        {
+          kind: "metric",
+          uri: `metric://efficiency/${sig.code}`,
+          excerpt: JSON.stringify(sig.evidence)
+        }
+      ],
+      recommended_action: RECOMMENDED_ACTION[sig.code],
+      metadata: { deterministic: true, evidence: sig.evidence },
+      ...opts.producedAt ? { produced_at: opts.producedAt } : {}
+    })
+  );
+}
+function behavioralAnalyst() {
+  return {
+    id: ANALYST_ID,
+    description: "Deterministic behavioral/efficiency findings over OTLP spans \u2014 token-growth, output-decay, tool-monoculture, missing self-verification. Zero LLM; model-agnostic by construction.",
+    inputKind: "trace-store",
+    cost: { kind: "deterministic" },
+    version: "1.0.0",
+    async analyze(store) {
+      const overview = await store.getOverview();
+      const spans = [];
+      for (const traceId of overview.sample_trace_ids) {
+        const viewed = await store.viewTrace({ trace_id: traceId });
+        if (viewed.spans) spans.push(...viewed.spans);
+      }
+      return deriveEfficiencyFindings(computeTraceMetrics(spans));
+    }
+  };
+}
+
+// src/analyst/default-registry.ts
+function buildDefaultAnalystRegistry(opts = {}) {
+  const registry = new AnalystRegistry(opts.registry);
+  if (opts.includeBehavioral !== false) {
+    registry.register(behavioralAnalyst());
+  }
+  if (opts.ai) {
+    const kinds = opts.kinds ?? DEFAULT_TRACE_ANALYST_KINDS;
+    for (const spec of kinds) {
+      registry.register(createTraceAnalystKind(spec, { ai: opts.ai, model: opts.model }));
+    }
+  }
+  return registry;
+}
+
+export {
+  computeTraceMetrics,
+  deriveEfficiencyFindings,
+  behavioralAnalyst,
+  buildDefaultAnalystRegistry
+};
+//# sourceMappingURL=chunk-UMMZHCPB.js.map

package/dist/chunk-UMMZHCPB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-analyst/behavioral-metrics.ts","../src/analyst/behavioral-analyst.ts","../src/analyst/default-registry.ts"],"sourcesContent":["/**\n * Deterministic behavioral metrics over OTLP spans — pure arithmetic, no LLM.\n *\n * These are the model-independent multiplier: the four trace-quality signals a\n * tolerant analyzer (e.g. HALO) re-derives per run inside the model — token\n * growth, output decay, tool monoculture, missing self-verification — computed\n * here once, in TypeScript, with zero model judgment. A finding that falls out\n * of arithmetic is trivially model-agnostic and cannot hallucinate the trend.\n *\n * General, not trace-specific: the detectors key off token trajectories and\n * tool usage present in any agentic OTLP trace, not any one benchmark.\n */\n\nimport type { TraceAnalystSpan } from './types'\n\nexport type SuboptimalCode =\n  | 'monotonic-input-growth'\n  | 'output-length-decay'\n  | 'single-tool-dependency'\n  | 'no-self-verification'\n\nexport interface SuboptimalSignal {\n  code: SuboptimalCode\n  severity: 'high' | 'medium' | 'low'\n  /** Human-readable claim, with the backing numbers inlined. */\n  detail: string\n  /** The exact figures the detector fired on — auditable, no model in the loop. */\n  evidence: Record<string, number | string | boolean>\n}\n\nexport interface BehavioralMetrics {\n  llmCallCount: number\n  inputTokenTrajectory: number[]\n  outputTokenTrajectory: number[]\n  toolHistogram: Record<string, number>\n  totalToolCalls: number\n  distinctTools: number\n  /** distinct/total tool calls; 1.0 when there are no tool calls. */\n  toolDiversityRatio: number\n  hasSelfVerification: boolean\n  signals: SuboptimalSignal[]\n}\n\n/** ≥ this input-token growth ratio across a run, with no compression, fires. */\nconst INPUT_GROWTH_FACTOR = 3\n/** Tool-usage signals need at least this many calls to be meaningful. */\nconst MIN_TOOL_CALLS = 3\n/** Tool names matching this are self-verification, not state mutation. */\nconst VERIFY_RE = /verif|eval|inspect|check|assert|validat|review|confirm/i\n\nfunction num(v: unknown): number | null {\n  return typeof v === 'number' && Number.isFinite(v) ? v : null\n}\nfunction inputTokensOf(s: TraceAnalystSpan): number | null {\n  return num(s.attributes['llm.input_tokens']) ?? num(s.attributes['llm.usage.input_tokens'])\n}\nfunction outputTokensOf(s: TraceAnalystSpan): number | null {\n  return num(s.attributes['llm.output_tokens']) ?? num(s.attributes['llm.usage.output_tokens'])\n}\nfunction stepOf(s: TraceAnalystSpan): number | null {\n  return num(s.attributes.step)\n}\nfunction toolNameOf(s: TraceAnalystSpan): string | null {\n  if (s.tool_name) return s.tool_name\n  const t = s.attributes['tool.name']\n  return typeof t === 'string' && t.length > 0 ? t : null\n}\n\n/**\n * Reduce a span list to behavioral metrics + fired suboptimality signals.\n * Pure + deterministic: same spans → same output, on any machine, no model.\n */\nexport function computeTraceMetrics(spans: readonly TraceAnalystSpan[]): BehavioralMetrics {\n  // Order by step (when present) then start_time so trajectories reflect run order.\n  const ordered = [...spans].sort((a, b) => {\n    const sa = stepOf(a)\n    const sb = stepOf(b)\n    if (sa !== null && sb !== null && sa !== sb) return sa - sb\n    return a.start_time.localeCompare(b.start_time)\n  })\n\n  const inputTokenTrajectory: number[] = []\n  const outputTokenTrajectory: number[] = []\n  const toolHistogram: Record<string, number> = {}\n  let hasSelfVerification = false\n\n  for (const s of ordered) {\n    const inT = inputTokensOf(s)\n    if (inT !== null) inputTokenTrajectory.push(inT)\n    const outT = outputTokensOf(s)\n    if (outT !== null) outputTokenTrajectory.push(outT)\n    const tool = toolNameOf(s)\n    if (tool) {\n      toolHistogram[tool] = (toolHistogram[tool] ?? 0) + 1\n      if (VERIFY_RE.test(tool)) hasSelfVerification = true\n    }\n  }\n\n  const totalToolCalls = Object.values(toolHistogram).reduce((a, b) => a + b, 0)\n  const distinctTools = Object.keys(toolHistogram).length\n  const toolDiversityRatio = totalToolCalls === 0 ? 1 : distinctTools / totalToolCalls\n\n  const signals: SuboptimalSignal[] = []\n\n  if (inputTokenTrajectory.length >= 3) {\n    const first = inputTokenTrajectory[0]!\n    const last = inputTokenTrajectory[inputTokenTrajectory.length - 1]!\n    const growth = first > 0 ? last / first : 0\n    if (last > first && growth >= INPUT_GROWTH_FACTOR) {\n      signals.push({\n        code: 'monotonic-input-growth',\n        severity: 'high',\n        detail: `LLM input tokens grew ${growth.toFixed(1)}x (${first}→${last}) across ${inputTokenTrajectory.length} calls — full history re-sent each step with no compression.`,\n        evidence: {\n          first,\n          last,\n          growth_x: Number(growth.toFixed(2)),\n          calls: inputTokenTrajectory.length,\n        },\n      })\n    }\n  }\n\n  if (outputTokenTrajectory.length >= 3) {\n    const first = outputTokenTrajectory[0]!\n    const last = outputTokenTrajectory[outputTokenTrajectory.length - 1]!\n    if (last < first) {\n      signals.push({\n        code: 'output-length-decay',\n        severity: 'medium',\n        detail: `LLM output tokens shrank ${first}→${last} over ${outputTokenTrajectory.length} calls — less planning/reasoning per step as context grows.`,\n        evidence: { first, last, calls: outputTokenTrajectory.length },\n      })\n    }\n  }\n\n  if (totalToolCalls >= MIN_TOOL_CALLS && distinctTools === 1) {\n    const only = Object.keys(toolHistogram)[0]!\n    signals.push({\n      code: 'single-tool-dependency',\n      severity: 'medium',\n      detail: `All ${totalToolCalls} tool calls are \\`${only}\\` — no tool diversity and no fallback path.`,\n      evidence: { tool: only, calls: totalToolCalls, distinct_tools: 1 },\n    })\n  }\n\n  if (totalToolCalls >= MIN_TOOL_CALLS && !hasSelfVerification) {\n    signals.push({\n      code: 'no-self-verification',\n      severity: 'medium',\n      detail: `${totalToolCalls} tool calls and none verify/inspect/check state — the agent never validates its own actions.`,\n      evidence: { tool_calls: totalToolCalls, verification_calls: 0 },\n    })\n  }\n\n  return {\n    llmCallCount: inputTokenTrajectory.length,\n    inputTokenTrajectory,\n    outputTokenTrajectory,\n    toolHistogram,\n    totalToolCalls,\n    distinctTools,\n    toolDiversityRatio,\n    hasSelfVerification,\n    signals,\n  }\n}\n","/**\n * `behavioralAnalyst` — a DETERMINISTIC analyst (cost.kind = 'deterministic',\n * never calls the LLM). It produces the efficiency/behavioral findings a\n * tolerant agentic analyzer (HALO) re-derives per run inside the model —\n * context bloat, output decay, tool monoculture, missing self-verification —\n * directly from arithmetic over spans (`computeTraceMetrics`).\n *\n * Why it matters: these findings are model-agnostic BY CONSTRUCTION (no model\n * in the loop), so they cannot return 0 on a weak model the way the Ax-RLM\n * does — and they are strictly more reliable than HALO, which spends tokens\n * re-deriving the same numbers and can hallucinate the trend. The agentic\n * RLM kinds remain for SEMANTIC findings that genuinely need a model; this\n * analyst owns the behavioral class.\n */\n\nimport {\n  type BehavioralMetrics,\n  computeTraceMetrics,\n  type SuboptimalCode,\n} from '../trace-analyst/behavioral-metrics'\nimport type { TraceAnalysisStore } from '../trace-analyst/store'\nimport type { TraceAnalystSpan } from '../trace-analyst/types'\nimport { type Analyst, type AnalystFinding, makeFinding } from './types'\n\nconst RECOMMENDED_ACTION: Record<SuboptimalCode, string> = {\n  'monotonic-input-growth':\n    'Add a context-budget instruction: once prior context exceeds a threshold, summarize earlier steps into a short status line instead of re-sending full history.',\n  'output-length-decay':\n    'Require a minimum planning/reasoning budget per step so late steps do not degrade into terse, error-prone commands.',\n  'single-tool-dependency':\n    'Direct the agent to use the full toolset (verify / inspect / alternate actions), not a single execute call, and to plan a fallback when a call returns an unexpected result.',\n  'no-self-verification':\n    'After every state-mutating action, verify the result (eval / inspect / assert) before proceeding.',\n}\n\nconst ANALYST_ID = 'efficiency-behavioral'\n\n/**\n * Map computed signals → structured AnalystFindings. Pure: no LLM, no clock\n * dependence beyond `produced_at` (overridable for deterministic tests).\n */\nexport function deriveEfficiencyFindings(\n  metrics: BehavioralMetrics,\n  opts: { analystId?: string; producedAt?: string } = {},\n): AnalystFinding[] {\n  const analystId = opts.analystId ?? ANALYST_ID\n  return metrics.signals.map((sig) =>\n    makeFinding({\n      analyst_id: analystId,\n      area: 'efficiency',\n      subject: sig.code, // kebab — passes the cluster grammar; stable key for diffFindings\n      claim: sig.detail,\n      severity: sig.severity,\n      // Deterministic arithmetic over spans, not a model judgment → certain.\n      confidence: 1,\n      evidence_refs: [\n        {\n          kind: 'metric',\n          uri: `metric://efficiency/${sig.code}`,\n          excerpt: JSON.stringify(sig.evidence),\n        },\n      ],\n      recommended_action: RECOMMENDED_ACTION[sig.code],\n      metadata: { deterministic: true, evidence: sig.evidence },\n      ...(opts.producedAt ? { produced_at: opts.producedAt } : {}),\n    }),\n  )\n}\n\n/** The deterministic behavioral/efficiency analyst (no LLM, any-model). */\nexport function behavioralAnalyst(): Analyst<TraceAnalysisStore> {\n  return {\n    id: ANALYST_ID,\n    description:\n      'Deterministic behavioral/efficiency findings over OTLP spans — token-growth, output-decay, tool-monoculture, missing self-verification. Zero LLM; model-agnostic by construction.',\n    inputKind: 'trace-store',\n    cost: { kind: 'deterministic' },\n    version: '1.0.0',\n    async analyze(store) {\n      const overview = await store.getOverview()\n      const spans: TraceAnalystSpan[] = []\n      for (const traceId of overview.sample_trace_ids) {\n        const viewed = await store.viewTrace({ trace_id: traceId })\n        if (viewed.spans) spans.push(...viewed.spans)\n      }\n      return deriveEfficiencyFindings(computeTraceMetrics(spans))\n    },\n  }\n}\n","/**\n * `buildDefaultAnalystRegistry` — the canonical analyst suite, so consumers\n * stop hand-wiring `new AnalystRegistry()` + per-kind `createTraceAnalystKind`.\n *\n * The deterministic `behavioralAnalyst` is ALWAYS registered (it needs no\n * model and is model-agnostic by construction). The agentic RLM kinds are\n * registered only when an `ai` service is supplied — so a caller with no LLM\n * still gets the full behavioral/efficiency diagnosis, and the substrate's\n * \"any model (including no model)\" guarantee holds at the suite level.\n */\n\nimport type { AxAIService } from '@ax-llm/ax'\nimport { behavioralAnalyst } from './behavioral-analyst'\nimport { createTraceAnalystKind, type TraceAnalystKindSpec } from './kind-factory'\nimport { DEFAULT_TRACE_ANALYST_KINDS } from './kinds'\nimport { AnalystRegistry, type AnalystRegistryOptions } from './registry'\n\nexport interface DefaultAnalystRegistryOptions {\n  /** Ax service for the agentic RLM kinds. Omit → only the deterministic analyst. */\n  ai?: AxAIService\n  /** Model for the agentic kinds (falls back to the ai service default). */\n  model?: string\n  /** Which agentic kinds to register when `ai` is present. Default = the shipped suite. */\n  kinds?: readonly TraceAnalystKindSpec[]\n  /** Set false to omit the deterministic behavioral analyst (default: include). */\n  includeBehavioral?: boolean\n  /** Forwarded to the AnalystRegistry constructor (signal, tags, priorFindings). */\n  registry?: AnalystRegistryOptions\n}\n\nexport function buildDefaultAnalystRegistry(\n  opts: DefaultAnalystRegistryOptions = {},\n): AnalystRegistry {\n  const registry = new AnalystRegistry(opts.registry)\n  if (opts.includeBehavioral !== false) {\n    registry.register(behavioralAnalyst())\n  }\n  if (opts.ai) {\n    const kinds = opts.kinds ?? DEFAULT_TRACE_ANALYST_KINDS\n    for (const spec of kinds) {\n      registry.register(createTraceAnalystKind(spec, { ai: opts.ai, model: opts.model }))\n    }\n  }\n  return registry\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-VZSRQ272.js

@@ -0,0 +1,149 @@
+// src/rl/active-curriculum.ts
+function varianceBasedCurriculum(observations, candidateCells, opts) {
+  const variancePrior = opts.variancePrior ?? 0.05;
+  const floor = opts.floorPerCell ?? 1;
+  const budget = opts.budget;
+  const grouped = /* @__PURE__ */ new Map();
+  for (const o of observations) {
+    const k = `${o.variantId}::${o.scenarioId}`;
+    const arr = grouped.get(k) ?? [];
+    arr.push(o.score);
+    grouped.set(k, arr);
+  }
+  const cellStats = candidateCells.map((c) => {
+    const k = `${c.variantId}::${c.scenarioId}`;
+    const samples = grouped.get(k) ?? [];
+    const n = samples.length;
+    const mean = n === 0 ? 0.5 : samples.reduce((s, v) => s + v, 0) / n;
+    const variance = n < 2 ? variancePrior : samples.reduce((s, v) => s + (v - mean) ** 2, 0) / (n - 1) + variancePrior;
+    const weight = Math.sqrt(variance) + 1 / Math.sqrt(Math.max(1, n));
+    return { variantId: c.variantId, scenarioId: c.scenarioId, n, mean, variance, weight };
+  });
+  const floorTotal = floor * cellStats.length;
+  if (floorTotal >= budget) {
+    const each = Math.max(1, Math.floor(budget / Math.max(1, cellStats.length)));
+    return cellStats.map((c) => ({
+      variantId: c.variantId,
+      scenarioId: c.scenarioId,
+      count: each,
+      reason: `floor allocation (budget tight; n=${c.n})`
+    }));
+  }
+  const remaining = budget - floorTotal;
+  const totalWeight = cellStats.reduce((s, c) => s + c.weight, 0);
+  return cellStats.map((c) => {
+    const proportional = totalWeight === 0 ? 0 : Math.round(c.weight / totalWeight * remaining);
+    return {
+      variantId: c.variantId,
+      scenarioId: c.scenarioId,
+      count: floor + proportional,
+      reason: `variance ${c.variance.toFixed(3)} (n=${c.n}, mean=${c.mean.toFixed(3)})`
+    };
+  });
+}
+function thompsonCurriculum(observations, candidateCells, opts) {
+  const threshold = opts.decisionThreshold ?? 0.5;
+  const alpha0 = opts.priorAlpha ?? 1;
+  const beta0 = opts.priorBeta ?? 1;
+  const rng = makeRng(opts.seed);
+  const grouped = /* @__PURE__ */ new Map();
+  for (const o of observations) {
+    const k = `${o.variantId}::${o.scenarioId}`;
+    const cur = grouped.get(k) ?? { passes: 0, failures: 0 };
+    const pass = o.pass ?? o.score >= threshold;
+    if (pass) cur.passes += 1;
+    else cur.failures += 1;
+    grouped.set(k, cur);
+  }
+  const stats = candidateCells.map((c) => {
+    const k = `${c.variantId}::${c.scenarioId}`;
+    const cur = grouped.get(k) ?? { passes: 0, failures: 0 };
+    const a = alpha0 + cur.passes;
+    const b = beta0 + cur.failures;
+    const sampled = sampleBeta(a, b, rng);
+    const distance = Math.abs(sampled - threshold);
+    const variance = a * b / ((a + b) ** 2 * (a + b + 1));
+    const sigma = Math.max(0.05, Math.sqrt(variance));
+    const weight = Math.exp(-((distance / sigma) ** 2));
+    return {
+      variantId: c.variantId,
+      scenarioId: c.scenarioId,
+      n: cur.passes + cur.failures,
+      sampled,
+      sigma,
+      weight,
+      a,
+      b
+    };
+  });
+  const totalWeight = stats.reduce((s, c) => s + c.weight, 0);
+  return stats.map((c) => {
+    const proportional = totalWeight === 0 ? 0 : Math.round(c.weight / totalWeight * opts.budget);
+    return {
+      variantId: c.variantId,
+      scenarioId: c.scenarioId,
+      count: Math.max(0, proportional),
+      reason: `Beta(${c.a.toFixed(1)},${c.b.toFixed(1)}) sample=${c.sampled.toFixed(3)} (target ${threshold})`
+    };
+  });
+}
+function observationsFromRunRecords(runs, opts = {}) {
+  const threshold = opts.passThreshold ?? 0.5;
+  const useHoldout = opts.useHoldout ?? true;
+  const out = [];
+  for (const r of runs) {
+    if (!r.scenarioId) continue;
+    const score = useHoldout ? r.outcome.holdoutScore ?? r.outcome.searchScore : r.outcome.searchScore ?? r.outcome.holdoutScore;
+    if (typeof score !== "number" || !Number.isFinite(score)) continue;
+    out.push({
+      variantId: r.candidateId,
+      scenarioId: r.scenarioId,
+      score,
+      pass: score >= threshold
+    });
+  }
+  return out;
+}
+function makeRng(seed) {
+  if (seed === void 0) return Math.random;
+  let s = seed >>> 0;
+  return () => {
+    s = s + 1831565813 >>> 0;
+    let t = s;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function sampleBeta(alpha, beta, rng) {
+  const a = Math.max(1, alpha);
+  const b = Math.max(1, beta);
+  const x = sampleGamma(a, rng);
+  const y = sampleGamma(b, rng);
+  return x / (x + y);
+}
+function sampleGamma(shape, rng) {
+  const d = shape - 1 / 3;
+  const c = 1 / Math.sqrt(9 * d);
+  while (true) {
+    let x;
+    let v;
+    do {
+      const u1 = rng() || 1e-12;
+      const u2 = rng() || 1e-12;
+      x = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+      v = 1 + c * x;
+    } while (v <= 0);
+    v = v * v * v;
+    const u = rng();
+    if (u < 1 - 0.0331 * x ** 4) return d * v;
+    if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v;
+  }
+}
+
+export {
+  varianceBasedCurriculum,
+  thompsonCurriculum,
+  observationsFromRunRecords
+};
+//# sourceMappingURL=chunk-VZSRQ272.js.map