@tangle-network/agent-eval 0.133.2 → 0.134.0

package/dist/tool-use-metrics-DEGMKycK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-use-metrics-DEGMKycK.js","names":[],"sources":["../src/failure-taxonomy.ts","../src/tool-use-metrics.ts"],"sourcesContent":["/**\n * Failure taxonomy — canonical classes + a default classifier.\n *\n * Every failed run should end up in a named class. The classifier here\n * is rule-based (fast, deterministic); an LLM fallback can be added by\n * the consumer for novel cases and trained into the rule base over time.\n *\n * Consumers call `classifyFailure(run, spans, events)` and persist the\n * returned class as `Run.outcome.failureClass`.\n */\n\nimport type { FailureClass, Run, Span, TraceEvent } from './trace/schema'\nimport { FAILURE_CLASSES } from './trace/schema'\n\nexport { FAILURE_CLASSES, type FailureClass }\n\nexport interface FailureContext {\n  run: Run\n  spans: Span[]\n  events: TraceEvent[]\n}\n\nexport interface FailureClassification {\n  failureClass: FailureClass\n  reason: string\n  triggerSpanId?: string\n  triggerEventId?: string\n}\n\n/** Ordered rules — first match wins. */\nexport interface FailureRule {\n  id: string\n  match: (ctx: FailureContext) => {\n    failureClass: FailureClass\n    reason: string\n    triggerSpanId?: string\n    triggerEventId?: string\n  } | null\n}\n\nexport const DEFAULT_RULES: FailureRule[] = [\n  // Outcome already named? Respect it.\n  {\n    id: 'explicit-outcome',\n    match: ({ run }) => {\n      const fc = run.outcome?.failureClass\n      if (fc && fc !== 'unknown')\n        return { failureClass: fc, reason: 'outcome.failureClass set explicitly' }\n      return null\n    },\n  },\n  {\n    id: 'knowledge-readiness-blocked',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'readiness_scored' &&\n          e.payload.passed === false,\n      )\n      return event\n        ? {\n            failureClass: 'knowledge_readiness_blocked',\n            reason: 'knowledge readiness report blocked execution',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'bad-integration-manifest',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          ((e.payload.kind === 'integration_manifest_validated' && e.payload.valid === false) ||\n            (e.payload.kind === 'integration_invoke_failed' &&\n              e.payload.code === 'manifest_invalid')),\n      )\n      return event\n        ? {\n            failureClass: 'bad_integration_manifest',\n            reason: 'integration manifest validation failed before launch',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'missing-integration-connection',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'integration_manifest_resolved' &&\n          hasResolutionStatus(e.payload, 'missing_connection'),\n      )\n      return event\n        ? {\n            failureClass: 'missing_integration_connection',\n            reason: 'required integration connection was missing',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'missing-integration-scope',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          ((e.payload.kind === 'integration_manifest_resolved' && hasMissingScopes(e.payload)) ||\n            (e.payload.kind === 'integration_invoke_failed' && e.payload.code === 'scope_denied')),\n      )\n      return event\n        ? {\n            failureClass: 'missing_integration_scope',\n            reason: 'integration grant or connection lacks required scopes',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'integration-approval-required',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          ((e.payload.kind === 'integration_invoke' && e.payload.status === 'approval_required') ||\n            (e.payload.kind === 'integration_invoke_failed' &&\n              e.payload.code === 'approval_required') ||\n            e.payload.kind === 'integration_approval_required'),\n      )\n      return event\n        ? {\n            failureClass: 'integration_approval_required',\n            reason: 'integration write paused for user approval',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'integration-auth-expired',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'integration_invoke_failed' &&\n          (e.payload.code === 'auth_expired' ||\n            e.payload.code === 'connection_not_active' ||\n            e.payload.code === 'capability_expired' ||\n            e.payload.status === 'expired'),\n      )\n      return event\n        ? {\n            failureClass: 'integration_auth_expired',\n            reason: 'integration connection or capability expired',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'unsafe-integration-write-denied',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'integration_invoke_failed' &&\n          (e.payload.code === 'unsafe_write_denied' ||\n            e.payload.code === 'policy_denied' ||\n            e.payload.code === 'action_denied'),\n      )\n      return event\n        ? {\n            failureClass: 'unsafe_integration_write_denied',\n            reason: 'integration write was denied by policy or capability scope',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'integration-provider-failure',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'integration_invoke_failed' &&\n          ![\n            'scope_denied',\n            'approval_required',\n            'auth_expired',\n            'connection_not_active',\n            'capability_expired',\n            'unsafe_write_denied',\n            'policy_denied',\n            'action_denied',\n            'manifest_invalid',\n          ].includes(String(e.payload.code)),\n      )\n      return event\n        ? {\n            failureClass: 'integration_provider_failure',\n            reason: 'integration provider invocation failed',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'missing-credentials',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'knowledge_gap' &&\n          e.payload.category === 'credential_or_secret',\n      )\n      return event\n        ? {\n            failureClass: 'missing_credentials',\n            reason: 'required credential or secret was missing',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'bad-retrieval',\n    match: ({ run, spans }) => {\n      if (run.outcome?.pass !== false) return null\n      const retrieval = spans.find(\n        (s) =>\n          s.kind === 'retrieval' && (s.hits.length === 0 || s.hits.every((hit) => hit.score <= 0)),\n      )\n      return retrieval\n        ? {\n            failureClass: 'bad_retrieval',\n            reason: 'retrieval returned no useful hits for a failed run',\n            triggerSpanId: retrieval.spanId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'insufficient-evidence',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'knowledge_gap' &&\n          e.payload.reason === 'insufficient_evidence',\n      )\n      return event\n        ? {\n            failureClass: 'insufficient_evidence',\n            reason: 'task proceeded with insufficient supporting evidence',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  {\n    id: 'contradictory-evidence',\n    match: ({ events }) => {\n      const event = events.find(\n        (e) =>\n          e.kind === 'custom' &&\n          e.payload.kind === 'knowledge_gap' &&\n          e.payload.reason === 'contradictory_evidence',\n      )\n      return event\n        ? {\n            failureClass: 'contradictory_evidence',\n            reason: 'supporting evidence contradicted itself',\n            triggerEventId: event.eventId,\n          }\n        : null\n    },\n  },\n  // Budget breach events\n  {\n    id: 'budget-breach',\n    match: ({ events }) => {\n      const breach = events.find((e) => e.kind === 'budget_breach')\n      return breach\n        ? {\n            failureClass: 'budget_exceeded',\n            reason: `budget breached on ${breach.payload.dimension ?? 'unknown dimension'}`,\n            triggerEventId: breach.eventId,\n          }\n        : null\n    },\n  },\n  // Policy violations\n  {\n    id: 'policy-violation',\n    match: ({ events }) => {\n      const e = events.find((x) => x.kind === 'policy_violation')\n      return e\n        ? {\n            failureClass: 'policy_violation',\n            reason: 'policy_violation event emitted',\n            triggerEventId: e.eventId,\n          }\n        : null\n    },\n  },\n  // Sandbox non-zero exit code\n  {\n    id: 'sandbox-failure',\n    match: ({ spans }) => {\n      const s = spans.find(\n        (x) => x.kind === 'sandbox' && typeof x.exitCode === 'number' && x.exitCode !== 0,\n      )\n      if (!s) return null\n      return {\n        failureClass: 'sandbox_failure',\n        reason: `sandbox exited ${(s as Extract<Span, { kind: 'sandbox' }>).exitCode}`,\n        triggerSpanId: s.spanId,\n      }\n    },\n  },\n  // Timeout: run aborted by external signal\n  {\n    id: 'timeout',\n    match: ({ run, events }) => {\n      if (run.status !== 'aborted') return null\n      const hasTimeout = events.some(\n        (e) =>\n          e.kind === 'error' &&\n          String(e.payload.reason ?? '')\n            .toLowerCase()\n            .includes('timeout'),\n      )\n      const note = (run.outcome?.notes ?? '').toLowerCase()\n      if (hasTimeout || note.includes('timeout') || note.includes('deadline')) {\n        return { failureClass: 'timeout', reason: 'timeout signal observed' }\n      }\n      return null\n    },\n  },\n  // Tool recovery failure: many consecutive tool errors on the same tool\n  {\n    id: 'tool-recovery-failure',\n    match: ({ spans }) => {\n      const tools = spans.filter((s) => s.kind === 'tool')\n      const byTool = new Map<string, Span[]>()\n      for (const t of tools) {\n        const name = (t as Extract<Span, { kind: 'tool' }>).toolName\n        const arr = byTool.get(name) ?? []\n        arr.push(t)\n        byTool.set(name, arr)\n      }\n      for (const [name, arr] of byTool) {\n        const errs = arr.filter((s) => s.status === 'error')\n        if (errs.length >= 3 && errs.length === arr.length) {\n          return {\n            failureClass: 'tool_recovery_failure',\n            reason: `${errs.length} consecutive errors on tool \"${name}\"`,\n            triggerSpanId: errs[errs.length - 1]!.spanId,\n          }\n        }\n      }\n      return null\n    },\n  },\n  // Tool selection error: the run failed and agent called zero tools despite having them\n  {\n    id: 'tool-selection-error',\n    match: ({ run, spans }) => {\n      if (run.outcome?.pass !== false) return null\n      const hasToolsAvailable = spans.some(\n        (s) =>\n          s.kind === 'agent' &&\n          (s.attributes?.toolsAvailable as number | undefined) !== undefined &&\n          (s.attributes?.toolsAvailable as number) > 0,\n      )\n      const tools = spans.filter((s) => s.kind === 'tool')\n      if (hasToolsAvailable && tools.length === 0) {\n        return {\n          failureClass: 'tool_selection_error',\n          reason: 'tools were available but none were called',\n        }\n      }\n      return null\n    },\n  },\n  // Format drift: scored by a judge with dimension='format' below threshold\n  {\n    id: 'format-drift',\n    match: ({ spans }) => {\n      const judge = spans.find(\n        (s) =>\n          s.kind === 'judge' &&\n          (s as Extract<Span, { kind: 'judge' }>).dimension === 'format' &&\n          (s as Extract<Span, { kind: 'judge' }>).score < 0.5,\n      )\n      return judge\n        ? {\n            failureClass: 'format_drift',\n            reason: 'format judge scored below 0.5',\n            triggerSpanId: judge.spanId,\n          }\n        : null\n    },\n  },\n]\n\nfunction hasResolutionStatus(payload: Record<string, unknown>, status: string): boolean {\n  if (status === 'missing_connection' && stringArray(payload.missingConnections).length > 0)\n    return true\n  return resolutionItems(payload).some((item) => item.status === status)\n}\n\nfunction hasMissingScopes(payload: Record<string, unknown>): boolean {\n  if (stringArray(payload.missingScopes).length > 0) return true\n  return resolutionItems(payload).some(\n    (item) => Array.isArray(item.missingScopes) && item.missingScopes.length > 0,\n  )\n}\n\nfunction resolutionItems(payload: Record<string, unknown>): Array<Record<string, unknown>> {\n  return [\n    ...records(payload.missing),\n    ...records(payload.optionalMissing),\n    ...records(payload.ready),\n  ]\n}\n\nfunction records(value: unknown): Array<Record<string, unknown>> {\n  if (!Array.isArray(value)) return []\n  return value.filter(\n    (item): item is Record<string, unknown> =>\n      Boolean(item) && typeof item === 'object' && !Array.isArray(item),\n  )\n}\n\nfunction stringArray(value: unknown): string[] {\n  return Array.isArray(value)\n    ? value.filter((item): item is string => typeof item === 'string')\n    : []\n}\n\n/** Classify the failure mode of a run using an ordered rule list. */\nexport function classifyFailure(\n  ctx: FailureContext,\n  rules: FailureRule[] = DEFAULT_RULES,\n): FailureClassification {\n  if (ctx.run.outcome?.pass !== false && ctx.run.status === 'completed') {\n    return { failureClass: 'success', reason: 'run completed with pass=true (or no explicit fail)' }\n  }\n  for (const rule of rules) {\n    const hit = rule.match(ctx)\n    if (hit) return hit\n  }\n  return { failureClass: 'unknown', reason: 'no rule matched; run failed for unclassified reason' }\n}\n","/**\n * Tool-use metrics — derived purely from trace data.\n *\n * No scoring assumptions: consumers supply optional ground-truth tool\n * selections per turn + optional \"information used downstream\" signals.\n * Without those, we still compute descriptive metrics (error rate,\n * retry rate, duplicate-call rate) that are useful on their own.\n */\n\nimport { argHash, groupBy, hasCapturedToolArgs, toolSpans } from './trace/query'\nimport type { Span } from './trace/schema'\nimport type { TraceStore } from './trace/store'\n\nexport interface ToolUseMetrics {\n  runId: string\n  totalCalls: number\n  /** Calls whose arguments were captured and can be compared for duplication. */\n  callsWithCapturedArgs: number\n  byTool: Record<string, ToolStats>\n  errorRate: number\n  /** Ratio of captured-argument calls already seen with the same tool name and arguments. */\n  duplicateRate: number\n  /** Ratio of error calls followed by ≥1 retry on same tool. */\n  retryRate: number\n  /** Optional: of the calls agent made, fraction the evaluator marked as \"correct selection\". */\n  selectionAccuracy?: number\n}\n\nexport interface ToolStats {\n  calls: number\n  callsWithCapturedArgs: number\n  errors: number\n  avgLatencyMs: number\n  duplicates: number\n}\n\nexport interface ToolUseOptions {\n  /** Map of spanId → whether the evaluator judged the tool selection correct. Optional. */\n  selectionLabels?: Record<string, boolean>\n}\n\nexport async function computeToolUseMetrics(\n  store: TraceStore,\n  runId: string,\n  options: ToolUseOptions = {},\n): Promise<ToolUseMetrics> {\n  const tools = await toolSpans(store, runId)\n  if (tools.length === 0) {\n    return {\n      runId,\n      totalCalls: 0,\n      callsWithCapturedArgs: 0,\n      byTool: {},\n      errorRate: 0,\n      duplicateRate: 0,\n      retryRate: 0,\n    }\n  }\n\n  const byTool: Record<string, ToolStats> = {}\n  let totalErrors = 0\n  let totalDuplicates = 0\n  let callsWithCapturedArgs = 0\n  const sortedTools = [...tools].sort((a, b) => a.startedAt - b.startedAt)\n  const seenSignatures = new Set<string>()\n\n  // duplicate detection + per-tool aggregation\n  for (const t of sortedTools) {\n    byTool[t.toolName] ??= {\n      calls: 0,\n      callsWithCapturedArgs: 0,\n      errors: 0,\n      avgLatencyMs: 0,\n      duplicates: 0,\n    }\n    const stat = byTool[t.toolName]!\n    stat.calls += 1\n    if (t.status === 'error') {\n      stat.errors += 1\n      totalErrors += 1\n    }\n    if (typeof t.latencyMs === 'number') stat.avgLatencyMs += t.latencyMs\n    if (hasCapturedToolArgs(t)) {\n      callsWithCapturedArgs += 1\n      stat.callsWithCapturedArgs += 1\n      const sig = `${t.toolName}|${argHash(t.args)}`\n      if (seenSignatures.has(sig)) {\n        stat.duplicates += 1\n        totalDuplicates += 1\n      }\n      seenSignatures.add(sig)\n    }\n  }\n\n  for (const stat of Object.values(byTool)) {\n    stat.avgLatencyMs = stat.calls > 0 ? stat.avgLatencyMs / stat.calls : 0\n  }\n\n  // retry detection: per-tool chronological adjacency where error → next same-tool call\n  let retryOpportunities = 0\n  let retriesFollowed = 0\n  for (const [, arr] of groupBy(sortedTools, (t) => t.toolName)) {\n    for (let i = 0; i < arr.length; i++) {\n      if (arr[i]!.status !== 'error') continue\n      retryOpportunities += 1\n      if (arr[i + 1]) retriesFollowed += 1\n    }\n  }\n  const retryRate = retryOpportunities > 0 ? retriesFollowed / retryOpportunities : 0\n\n  let selectionAccuracy: number | undefined\n  if (options.selectionLabels) {\n    const labeled = sortedTools.filter((t) => t.spanId in options.selectionLabels!)\n    if (labeled.length > 0) {\n      selectionAccuracy =\n        labeled.filter((t) => options.selectionLabels![t.spanId]).length / labeled.length\n    }\n  }\n\n  return {\n    runId,\n    totalCalls: sortedTools.length,\n    callsWithCapturedArgs,\n    byTool,\n    errorRate: totalErrors / sortedTools.length,\n    duplicateRate: callsWithCapturedArgs > 0 ? totalDuplicates / callsWithCapturedArgs : 0,\n    retryRate,\n    selectionAccuracy,\n  }\n}\n\nexport type { Span }\n"],"mappings":"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"}

package/dist/types-DVjczBM9.d.ts

@@ -0,0 +1,276 @@
+import { c as CostLedgerHandle } from "./cost-ledger-fGS_u_O1.js";
+import { a as RunRecord, n as RunCostProvenance, u as RunTokenUsage } from "./run-record-DcObtIGh.js";
+import { A as ChatClient, m as JudgeInput } from "./types-Cc3qbqzj.js";
+import { t as TraceAnalysisStore } from "./store-CxJry_cs.js";
+//#region src/analyst/types.d.ts
+/**
+ * Unified envelope every analyst emits. Schema-versioned so renderers
+ * and time-series diffs survive future field additions.
+ */
+interface AnalystFinding {
+  schema_version: '1.0.0';
+  /**
+   * Stable hash over identity-defining fields (analyst_id + canonical
+   * claim + area + optional subject). Two findings from two runs that
+   * "are the same finding" share this id — that's what `diffFindings`
+   * uses to compute appeared/disappeared sets across runs.
+   */
+  finding_id: string;
+  analyst_id: string;
+  produced_at: string;
+  severity: AnalystSeverity;
+  /**
+   * Coarse classification. Renderers group by this. Free-form so
+   * domain-specific analysts can introduce categories without a
+   * schema change ('agent-reasoning', 'verification', 'cost',
+   * 'tool-use', 'safety', 'latency', 'data-quality', ...).
+   */
+  area: string;
+  claim: string;
+  rationale?: string;
+  evidence_refs: EvidenceRef[];
+  recommended_action?: string;
+  validation_plan?: string;
+  /** 0..1 — the analyst's own confidence. Not calibrated across analysts. */
+  confidence: number;
+  /**
+   * Optional subject the finding is about — leaf id, agent id, request
+   * id. Included in finding_id when present so per-subject findings
+   * diff cleanly across runs.
+   */
+  subject?: string;
+  /** True when this finding was lifted from a judge result rather than observed
+   *  directly in a trace or artifact. Descriptive only: proposal access is
+   *  controlled by `ProposalFinding.proposal_origin`. */
+  derived_from_judge?: boolean;
+  /** Analyst-private extras; renderers ignore unless they know the analyst. */
+  metadata?: Record<string, unknown>;
+}
+type AnalystSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/** Data sources that candidate generation may intentionally learn from. */
+type ProposalFindingOrigin = 'search' | 'production';
+/** A finding explicitly admitted as candidate-generation input. */
+type ProposalFinding = AnalystFinding & {
+  readonly proposal_origin: ProposalFindingOrigin;
+};
+interface EvidenceRef {
+  /**
+   * Where the evidence lives. `span` and `event` refer to OTLP trace
+   * elements; `artifact` to a file inside the run's artifact tree;
+   * `finding` to another AnalystFinding (cross-analyst chaining);
+   * `metric` to a named scalar reading the renderer knows how to read.
+   */
+  kind: 'span' | 'event' | 'artifact' | 'finding' | 'metric';
+  uri: string;
+  excerpt?: string;
+}
+/**
+ * The discriminator the registry uses to pass the right input.
+ * `custom` is the escape hatch — analysts that need something else
+ * (e.g. an embedding cache, a partner SDK handle) read it from
+ * `AnalystRunInputs.custom[<analyst id>]`.
+ */
+type AnalystInputKind = 'trace-store' | 'artifact-dir' | 'run-record' | 'judge-input' | 'custom';
+interface AnalystCost {
+  /** `deterministic` analysts MUST NOT call the LLM. */
+  kind: 'deterministic' | 'llm';
+  /** Optional declared upper bound; the registry can enforce a budget. */
+  est_usd_per_run?: number;
+  /** Models the analyst expects to use (informational). */
+  models?: string[];
+  /** Maximum post-cancellation wait for provider usage. Model analysts default to 5 seconds. */
+  settlement_timeout_ms?: number;
+}
+interface AnalystRequirements {
+  /** Min number of shots / samples the analyst needs to produce signal. */
+  min_shots?: number;
+  /** Capabilities the runtime must supply (e.g. ['network', 'gpu']). */
+  capabilities?: string[];
+}
+/**
+ * What's passed to every analyst call. The registry resolves which
+ * field the analyst's `inputKind` selects and asserts it's present.
+ */
+interface AnalystRunInputs {
+  traceStore?: TraceAnalysisStore;
+  artifactDir?: string;
+  runRecord?: RunRecord;
+  judgeInput?: JudgeInput;
+  /** Keyed by analyst id; populated by callers that registered custom analysts. */
+  custom?: Record<string, unknown>;
+}
+interface AnalystContext {
+  runId: string;
+  /** Stable correlation id so logs from a single registry.run() share a tag. */
+  correlationId: string;
+  /** Enforced wall-clock deadline (epoch ms). */
+  deadlineMs?: number;
+  /** Per-analyst USD budget. Analysts MAY check before issuing LLM calls. */
+  budgetUsd?: number;
+  /** Shared paid-call account when the analyst runs inside a larger campaign. */
+  costLedger?: CostLedgerHandle;
+  /** Attribution phase used when writing to the shared paid-call account. */
+  costPhase?: string;
+  /**
+   * Shared chat client. Analysts that call an LLM go through this so
+   * the operator picks transport (sandbox-sdk | router | cli-bridge |
+   * direct-provider | mock) at the registry boundary without touching
+   * analyst code.
+   */
+  chat?: ChatClient;
+  /**
+   * Findings from a prior run the operator wants the analyst to see as
+   * retrieval context. Kinds that take advantage of cross-run memory
+   * (failure-mode "I saw this cluster last run", knowledge-gap "the wiki
+   * page I asked for is still missing") render these into the actor's
+   * working set. Filtering is the operator's job: pass the slice that
+   * matches the analyst's id, or pass everything and let the kind
+   * filter. Empty / absent means no cross-run context.
+   */
+  priorFindings?: ReadonlyArray<AnalystFinding>;
+  /**
+   * Findings emitted by analysts that completed earlier in this registry run.
+   * This is separate from `priorFindings`: upstream findings are dependency
+   * context for the current pass, while prior findings are cross-run memory.
+   * The registry populates this only when `RegistryRunOpts.chainFindings` is on.
+   */
+  upstreamFindings?: ReadonlyArray<AnalystFinding>;
+  /**
+   * Report metered work independently of findings. This keeps an empty finding
+   * set from erasing token/cost telemetry. Multiple receipts are accumulated.
+   */
+  recordUsage?: (receipt: AnalystUsageReceipt) => void;
+  /** Free-form runtime tags (env, host, op). Findings can echo these into metadata. */
+  tags?: Record<string, string>;
+  /** Logger callback — analysts SHOULD prefer this over console.* for testability. */
+  log?: (msg: string, fields?: Record<string, unknown>) => void;
+  /** Optional abort signal. Analysts SHOULD pass it through to LLM calls. */
+  signal?: AbortSignal;
+}
+/**
+ * The minimal contract. Concrete analysts can refine `TInput` so
+ * implementations stay type-safe (e.g. a trace analyst's `TInput` is
+ * `TraceAnalysisStore`); the registry passes the right field from
+ * `AnalystRunInputs` based on `inputKind`.
+ */
+interface Analyst<TInput = unknown> {
+  /** Stable identifier — appears in finding_id, telemetry, and registry exclusion lists. */
+  readonly id: string;
+  /** Human-readable. One sentence. */
+  readonly description: string;
+  readonly inputKind: AnalystInputKind;
+  readonly cost: AnalystCost;
+  readonly requires?: AnalystRequirements;
+  /** Bump on breaking changes to claim wording or area so old finding_ids don't collide. */
+  readonly version: string;
+  analyze(input: TInput, ctx: AnalystContext): Promise<AnalystFinding[]>;
+}
+/** Metered work performed by one analyst call. */
+interface AnalystUsageReceipt {
+  /** Number of model-usage records observed at the provider boundary. */
+  calls: number | null;
+  /** Null when the provider did not return token accounting. */
+  tokens: RunTokenUsage | null;
+  /** Observed, estimated, or explicitly uncaptured dollar cost. */
+  cost: RunCostProvenance;
+  /** Known lower bound when one or more calls have uncaptured cost. */
+  knownCostUsd?: number;
+}
+/**
+ * Compute the stable finding_id from the identity-defining fields.
+ * Default implementation hashes {analyst_id, area, subject, normalized claim}.
+ * Analysts that emit findings whose claim text varies per run (timestamps,
+ * counts) SHOULD either: (a) pass an explicit `id_basis` to fix the hash,
+ * or (b) move the variable part into `rationale`/`metadata` and keep the
+ * `claim` static.
+ */
+declare function computeFindingId(input: {
+  analyst_id: string;
+  area: string;
+  subject?: string;
+  claim: string;
+  /** Override the claim for hashing — use when the displayed claim has run-specific bits. */
+  id_basis?: string;
+}): string;
+/**
+ * Convenience factory: produce a fully-formed AnalystFinding with the
+ * id computed automatically. Analyst code stays terse.
+ */
+declare function makeFinding(init: Omit<AnalystFinding, 'schema_version' | 'finding_id' | 'produced_at'> & {
+  id_basis?: string;
+  produced_at?: string;
+}): AnalystFinding;
+/** Build a finding whose source is explicitly allowed during candidate generation. */
+declare function makeProposalFinding(init: Omit<ProposalFinding, 'schema_version' | 'finding_id' | 'produced_at'> & {
+  id_basis?: string;
+  produced_at?: string;
+}): ProposalFinding;
+interface AnalystRunSummary {
+  analyst_id: string;
+  status: 'ok' | 'skipped' | 'failed';
+  /** Why skipped — missing input, budget exceeded, capability unmet. */
+  reason?: string;
+  findings_count: number;
+  latency_ms: number;
+  /** Additive model usage and cost provenance for this analyst. */
+  usage: AnalystUsageReceipt;
+  /** When `status='failed'`: the error class + message, never the full stack. */
+  error?: {
+    class: string;
+    message: string;
+  };
+}
+interface AnalystRunResult {
+  run_id: string;
+  correlation_id: string;
+  started_at: string;
+  ended_at: string;
+  findings: AnalystFinding[];
+  per_analyst: AnalystRunSummary[];
+  /** Total LLM cost in USD across all analysts in this registry.run(). */
+  total_cost_usd: number;
+  /**
+   * Provenance for `total_cost_usd`. When uncaptured, the numeric field is only
+   * the known subtotal and must not be treated as the run's total spend.
+   */
+  total_cost_provenance?: RunCostProvenance;
+}
+/**
+ * Events emitted by `AnalystRegistry.runStream(...)` in real time as
+ * the registry executes. UIs subscribe via `for await (const ev of
+ * registry.runStream(...))`; `registry.run(...)` is a thin collector
+ * over the same stream, so the two surfaces share their invariants.
+ *
+ * Per-finding events are intentionally omitted — analyzers are batch
+ * operations (an Ax actor returns the full `findings:json[]` at the
+ * end of the responder), so streaming inside one analyst would only
+ * emit partial JSON consumers can't render. The kind-completion event
+ * is the right granularity; subscribers wanting per-finding rendering
+ * iterate `event.findings` themselves.
+ */
+type AnalystRunEvent = {
+  type: 'run-started';
+  run_id: string;
+  correlation_id: string;
+  started_at: string;
+  /** The ordered list of analyst ids the registry will run. */
+  analyst_ids: ReadonlyArray<string>;
+} | {
+  type: 'analyst-skipped';
+  summary: AnalystRunSummary;
+} | {
+  type: 'analyst-started';
+  analyst_id: string;
+  started_at: string;
+} | {
+  type: 'analyst-completed';
+  /** `summary.status` is `'ok'` for clean completion or `'failed'` for thrown analysts. */
+  summary: AnalystRunSummary;
+  findings: ReadonlyArray<AnalystFinding>;
+} | {
+  type: 'run-completed';
+  result: AnalystRunResult;
+};
+//#endregion
+export { makeFinding as _, AnalystInputKind as a, AnalystRunInputs as c, AnalystSeverity as d, AnalystUsageReceipt as f, computeFindingId as g, ProposalFindingOrigin as h, AnalystFinding as i, AnalystRunResult as l, ProposalFinding as m, AnalystContext as n, AnalystRequirements as o, EvidenceRef as p, AnalystCost as r, AnalystRunEvent as s, Analyst as t, AnalystRunSummary as u, makeProposalFinding as v };
+//# sourceMappingURL=types-DVjczBM9.d.ts.map

package/dist/types-DVjczBM9.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DVjczBM9.d.ts","names":[],"sources":["../src/analyst/types.ts"],"mappings":";;;;;;;;;UA4BiB;EACf;;;;;;;EAOA;EACA;EACA;EACA,UAAU;;;;;;;EAOV;EACA;EACA;EACA,eAAe;EACf;EACA;;EAEA;;;;;;EAMA;;;;EAIA;;EAEA,WAAW;;KAGD;;KAGA;;KAGA,kBAAkB;WACnB,iBAAiB;;UAGX;;;;;;;EAOf;EACA;EACA;;;;;;;;KAWU;UAOK;;EAEf;;EAEA;;EAEA;;EAEA;;UAGe;;EAEf;;EAEA;;;;;;UAOe;EACf,aAAa;EACb;EACA,YAAY;EACZ,aAAa;;EAEb,SAAS;;UAGM;EACf;;EAEA;;EAEA;;EAEA;;EAEA,aAAa;;EAEb;;;;;;;EAOA,OAAO;;;;;;;;;;EAUP,gBAAgB,cAAc;;;;;;;EAO9B,mBAAmB,cAAc;;;;;EAKjC,eAAe,SAAS;;EAExB,OAAO;;EAEP,OAAO,aAAa,SAAS;;EAE7B,SAAS;;;;;;;;UASM,QAAQ;;WAEd;;WAEA;WACA,WAAW;WACX,MAAM;WACN,WAAW;;WAEX;EACT,QAAQ,OAAO,QAAQ,KAAK,iBAAiB,QAAQ;;;UAItC;;EAEf;;EAEA,QAAQ;;EAER,MAAM;;EAEN;;;;;;;;;;iBAac,iBAAiB;EAC/B;EACA;EACA;EACA;;EAEA;;;;;;iBAyBc,YACd,MAAM,KAAK;EACT;EACA;IAED;;iBAiBa,oBACd,MAAM,KAAK;EACT;EACA;IAED;UAOc;EACf;EACA;;EAEA;EACA;EACA;;EAEA,OAAO;;EAEP;IAAU;IAAe;;;UAGV;EACf;EACA;EACA;EACA;EACA,UAAU;EACV,aAAa;;EAEb;;;;;EAKA,wBAAwB;;;;;;;;;;;;;;;KAkBd;EAEN;EACA;EACA;EACA;;EAEA,aAAa;;EAGb;EACA,SAAS;;EAGT;EACA;EACA;;EAGA;;EAEA,SAAS;EACT,UAAU,cAAc;;EAGxB;EACA,QAAQ"}

package/dist/{types-BokuXvOG.d.ts → types-DiWLru6Z.d.ts}

@@ -1,6 +1,7 @@
 import { S as PaidCallResult, T as RunPaidCallInput, a as CostChannel, c as CostLedgerHandle, f as CostLedgerSummary } from "./cost-ledger-fGS_u_O1.js";
 import { u as RunTokenUsage } from "./run-record-DcObtIGh.js";
 import { n as LlmCallMetadata } from "./llm-client-BiK4HW0u.js";
+import { m as ProposalFinding } from "./types-DVjczBM9.js";
 //#region src/campaign/types.d.ts
 /** Stable identifier + kind tag for any scenario. Consumers
  *  extend with their per-domain payload (persona, task, requirement, ...). */
@@ -239,56 +240,38 @@ interface ScoredSurfaceOutcome {
     scorableCells: number;
   };
 }
-/** Everything a proposer may read to plan the next
- *  batch of candidates. The first six fields are always present; the rest are
- *  optional context the loop supplies when available, so simple proposers can
- *  ignore them while a code-tier agentic generator consumes the report and
- *  dataset.
- *  See `docs/campaign-proposers.md`. */
-interface ProposeContext<TFindings = unknown> {
-  currentSurface: MutableSurface;
-  history: GenerationRecord[];
-  findings: TFindings[];
+/** Search state supplied to one candidate-generation call.
+ *  Final evaluation data is not represented in this contract. */
+interface ProposeContext<TFindings = ProposalFinding> {
+  readonly currentSurface: MutableSurface;
+  readonly history: ReadonlyArray<GenerationRecord>;
+  readonly findings: ReadonlyArray<TFindings>;
   /** BREADTH: how many candidate surfaces to return this generation. */
-  populationSize: number;
-  generation: number;
-  signal: AbortSignal;
+  readonly populationSize: number;
+  readonly generation: number;
+  readonly signal: AbortSignal;
   /** Present when a multi-track lineage requests this proposal. */
-  track?: ProposalTrackContext;
+  readonly track?: ProposalTrackContext;
   /** Measured baseline for this optimization run. `runOptimization` always
    *  supplies it; optional for standalone proposer callers. */
-  baselineOutcome?: ScoredSurfaceOutcome;
+  readonly baselineOutcome?: ScoredSurfaceOutcome;
   /** Measured result for `currentSurface`, the complete global incumbent every
    *  new candidate mutates. `runOptimization` always supplies it. */
-  incumbentOutcome?: ScoredSurfaceOutcome;
-  /** Optional analysis report produced before proposal. Opaque to the substrate:
-   *  the proposer that consumes it owns the shape. */
-  report?: unknown;
-  /** Handle to all captured data — the proposer samples traces / artifacts /
-   *  rewards here to ground its proposals. */
-  dataset?: LabeledScenarioStore;
+  readonly incumbentOutcome?: ScoredSurfaceOutcome;
   /** DEPTH: max iterations the agentic generator may take per candidate.
    *  1 = single-shot; >1 = it may iterate on its own change before handing it
    *  back to be measured. */
-  maxImprovementShots?: number;
+  readonly maxImprovementShots?: number;
   /** GEPA Pareto frontier across ALL generations so far — the non-dominated
    *  surfaces by per-scenario objective vector. Empty/absent on generation 0
    *  (only the baseline is scored). A reflective proposer combines the
    *  complementary lessons of these parents (each excels on different
    *  scenarios) into a merged candidate. Proposers doing pure single-parent
    *  reflection may ignore it. See {@link ParetoParent}. */
-  paretoParents?: ParetoParent[];
+  readonly paretoParents?: ReadonlyArray<ParetoParent>;
   /** Shared run spend account and receipt attribution phase. */
-  costLedger?: CostLedgerHandle;
-  costPhase?: string;
-  /** FIREWALL (non-negotiable): the held-out judge is write-only — its verdicts
-   *  score the chosen output and gate promotion, and are NEVER an input to
-   *  proposal/steering (else the optimizer games the acceptance axis = an
-   *  oracle). This `never`-typed field makes that a compile-time tripwire: a
-   *  proposer that tries to thread judge verdicts into the proposal will not type.
-   *  Steering may consume TRACE-OBSERVABLE signals (what the agent did) via
-   *  `findings`/`report`; it may NOT consume the judge's held-out verdict. */
-  judgeScores?: never;
+  readonly costLedger?: CostLedgerHandle;
+  readonly costPhase?: string;
 }
 /** A surface-improvement strategy. Given the current best
  *  surface, the history of what's been tried + scored, and any external
@@ -302,7 +285,7 @@ interface ProposeContext<TFindings = unknown> {
  *  behavior-fuzzing `MutationProposer` (`fuzz/types`), a scenario generator for
  *  a different loop.
  */
-interface SurfaceProposer<TFindings = unknown> {
+interface SurfaceProposer<TFindings = ProposalFinding> {
   kind: string;
   /** Plan: propose N candidate surfaces for the next generation. A proposer
    *  may return bare `MutableSurface`s or `ProposedCandidate`s that carry the
@@ -312,7 +295,7 @@ interface SurfaceProposer<TFindings = unknown> {
   /** Decide: stop early when the proposer judges the search converged or
    *  exhausted. Default (omitted) runs all `maxGenerations`. */
   decide?(args: {
-    history: GenerationRecord[];
+    history: ReadonlyArray<GenerationRecord>;
   }): {
     stop: boolean;
     reason?: string;
@@ -637,4 +620,4 @@ interface CampaignResult<TArtifact = unknown, TScenario extends Scenario = Scena
 }
 //#endregion
 export { LabeledScenarioWrite as A, ScoredSurfaceOutcome as B, JudgeDimension as C, LabeledScenarioSampleArgs as D, LabeledScenarioRecord as E, ProposeContext as F, labelTrustRank as G, SurfaceProposer as H, ProposedCandidate as I, RedactionStatus as L, OptimizerConfig as M, ParetoParent as N, LabeledScenarioSource as O, ProposalTrackContext as P, Scenario as R, JudgeConfig as S, LabelTrust as T, TraceSpan as U, SessionScript as V, isProposedCandidate as W, GateDecision as _, CampaignResult as a, GenerationRecord as b, CampaignTraceWriter as c, DispatchContext as d, DispatchFn as f, GateContribution as g, GateContext as h, CampaignCostMeter as i, MutableSurface as j, LabeledScenarioStore as k, CodeSurface as l, GateCheckStatus as m, CampaignArtifactWriter as n, CampaignScenarioIdentity as o, Gate as p, CampaignCellResult as r, CampaignTokenUsage as s, CampaignAggregates as t, ComponentSurface as u, GateResult as v, JudgeScore as w, JudgeAggregate as x, GenerationCandidate as y, ScenarioAggregate as z };
-//# sourceMappingURL=types-BokuXvOG.d.ts.map
+//# sourceMappingURL=types-DiWLru6Z.d.ts.map

package/dist/types-DiWLru6Z.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DiWLru6Z.d.ts","names":[],"sources":["../src/campaign/types.ts"],"mappings":"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"}

package/docs/campaign-proposers.md

@@ -407,6 +407,11 @@ Concurrent processes cannot write the same compatible run at the same time.
 
 Use `SurfaceProposer` when your code or runtime owns candidate creation.
 The proposer receives the current surface, prior campaign history, findings, generation number, requested population size, and cancellation signal.
+Every proposal finding must declare `proposal_origin: 'search' | 'production'`.
+`runOptimization()` rejects unclassified findings before it calls the proposer.
+Opaque reports and capture stores are not proposal input.
+Convert analysis into explicit findings or close over a caller-owned knowledge source in your proposer.
+Any caller-owned source must exclude final evaluation cases and results.
 
 ```ts
 import type { SurfaceProposer } from '@tangle-network/agent-eval/campaign'