@tangle-network/agent-eval 0.94.0 → 0.95.0

package/dist/diagnose/remediation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Remediation adapters — HOW DO WE MAKE IT HAPPEN?
+ *
+ * The diagnose chain ends by feeding existing improvement machinery,
+ * not by building new machinery:
+ *
+ *   - `toAnalystFindings` → the analyst contract (`makeFinding`), so
+ *     responsibility evidence flows into the same registry / steering /
+ *     diff pipeline every other analyst feeds.
+ *   - `toCorpusRecord` → the RL corpus (`CorpusRecord`), pinning the
+ *     diagnosed failure + validated repair as a permanent scenario.
+ *   - `suggestInvariant` → a plain-data hint in the shape the
+ *     trace-contracts machinery consumes (`never` / `without` clauses).
+ */
+import type { AnalystFinding, AnalystSeverity } from '../analyst/types';
+import type { CounterfactualMutation } from '../counterfactual';
+import type { CorpusRecord } from '../rl/corpus';
+import type { RunRecord } from '../run-record';
+import type { CausalResponsibilityReport, StepResponsibility } from './causal-sweep';
+import type { RepairReport, ValidatedRepair } from './repair';
+export declare const DIAGNOSE_ANALYST_ID = "diagnose-causal-sweep";
+/** Severity from causal effect size. Effects whose CI includes zero are
+ *  'info' regardless of magnitude — an indistinguishable-from-noise effect
+ *  must not steer remediation priority. */
+export declare function severityFromEffect(responsibility: StepResponsibility): AnalystSeverity;
+/** Deterministic human-readable rendering of a mutation — used in
+ *  recommended actions, corpus completions, and invariant hints. */
+export declare function describeMutation(mutation: CounterfactualMutation): string;
+/**
+ * Lift a responsibility report (and optionally its validated repairs) into
+ * `AnalystFinding`s via the real `makeFinding` factory. One finding per
+ * probed step; a validated repair for that step upgrades the finding with
+ * a `recommended_action` + the replay-validation evidence.
+ *
+ * Findings are OBSERVED causal probes (replay deltas), not judge verdicts,
+ * so `derived_from_judge` stays unset and they may steer.
+ */
+export declare function toAnalystFindings(report: CausalResponsibilityReport, repairs?: RepairReport): AnalystFinding[];
+/**
+ * Pin the diagnosed failure as a permanent corpus scenario. Takes the
+ * original run's `RunRecord` projection plus a validated repair and emits
+ * a fresh `CorpusRecord` (new runId, so corpus dedup keeps both the raw
+ * failure and the diagnosed entry).
+ *
+ * `completion` defaults to the validated mutation's rendering — "what
+ * should have happened" in machine-derived form. Supply `prompt` (and
+ * optionally a richer `completion`) when the trajectory text is available
+ * so the record is harvestable by `buildDatasetFromCorpus`.
+ */
+export declare function toCorpusRecord(run: RunRecord, repair: ValidatedRepair, opts?: {
+    prompt?: string;
+    completion?: string;
+}): CorpusRecord;
+/** Plain-data invariant hint. The trace-contracts machinery consumes this
+ *  shape: `never` is a pattern that must not appear in a passing trace;
+ *  `without` is a guard whose absence makes the failure reachable. */
+export interface InvariantHint {
+    description: string;
+    never?: string;
+    without?: string;
+}
+/**
+ * Derive an invariant hint from a validated repair. Deterministic per
+ * mutation kind — the hint names the contract a trace must satisfy so
+ * the diagnosed failure cannot silently recur.
+ */
+export declare function suggestInvariant(repair: ValidatedRepair): InvariantHint;
+//# sourceMappingURL=remediation.d.ts.map

package/dist/diagnose/remediation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediation.d.ts","sourceRoot":"","sources":["../../src/diagnose/remediation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAe,MAAM,kBAAkB,CAAA;AAEpF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,KAAK,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACpF,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE7D,eAAO,MAAM,mBAAmB,0BAA0B,CAAA;AAE1D;;2CAE2C;AAC3C,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,kBAAkB,GAAG,eAAe,CAOtF;AAED;oEACoE;AACpE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAazE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,0BAA0B,EAClC,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,EAAE,CA+ClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,YAAY,CAqBd;AAED;;sEAEsE;AACtE,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAoCvE"}

package/dist/diagnose/repair.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Replay-validated repair — WHAT SHOULD HAVE HAPPENED?
+ *
+ * Takes the blamed steps from a `CausalResponsibilityReport`, asks a
+ * consumer-supplied `proposeFix` (LLM-backed in live use) for candidate
+ * mutations, and machine-verifies each candidate by replaying the run
+ * WITH the mutation applied (through the same `runCounterfactual` seam
+ * the sweep uses).
+ *
+ * A repair is "what should have happened" ONLY when every validation
+ * replay crosses `flipThreshold` — a prescription is never speculated,
+ * it is demonstrated. Candidates that don't flip, or whose replay
+ * errors, land in `rejected` with a typed reason; nothing is dropped
+ * silently.
+ */
+import { type CounterfactualMutation, type CounterfactualRunner } from '../counterfactual';
+import type { TraceStore } from '../trace/store';
+import { type Trajectory, type TrajectoryStep } from '../trajectory';
+import type { StepRef, StepResponsibility } from './causal-sweep';
+/** Context handed to `proposeFix` so an LLM-backed proposer can see the
+ *  full trajectory plus the responsibility evidence for the blamed step. */
+export interface RepairContext {
+    runId: string;
+    trajectory: Trajectory;
+    originalScore: number;
+    responsibility: StepResponsibility;
+}
+export interface PrescribeRepairOptions {
+    store: TraceStore;
+    /** The failed run the sweep diagnosed. */
+    runId: string;
+    /** Execution seam — same `CounterfactualRunner` contract as the sweep. */
+    runner: CounterfactualRunner;
+    /** Blamed steps from `causalSweep` — typically `report.steps.slice(0, k)`. */
+    blamed: StepResponsibility[];
+    /** Candidate-fix generator. Consumer-supplied; LLM-backed in live use.
+     *  Returned mutations MUST target the blamed step's index. */
+    proposeFix: (step: TrajectoryStep, context: RepairContext) => Promise<CounterfactualMutation[]>;
+    /** Score every validation replay must reach for the repair to count. Default 0.5. */
+    flipThreshold?: number;
+    /** Validation replays per candidate mutation. Default 3. */
+    repsToValidate?: number;
+    /** Max candidate mutations tried per step. Default: all proposed. */
+    maxAttemptsPerStep?: number;
+}
+export interface ValidatedRepair {
+    stepRef: StepRef;
+    mutation: CounterfactualMutation;
+    /** Always true — presence in `repairs` IS the machine-verified claim. */
+    validated: true;
+    /** Mean counterfactual score across the validation reps. */
+    meanScore: number;
+    /** meanScore − originalScore. */
+    deltaScore: number;
+    reps: number;
+    /** Replay run ids backing the validation — audit trail. */
+    counterfactualRunIds: string[];
+}
+export interface RejectedRepair {
+    stepRef: StepRef;
+    mutation: CounterfactualMutation;
+    reason: 'did-not-flip' | 'error';
+    /** Present for 'did-not-flip': mean delta over the reps that ran. */
+    deltaScore?: number;
+    /** Present for 'error': the message, preserved for diagnosis. */
+    error?: string;
+}
+export interface RepairReport {
+    runId: string;
+    originalScore: number;
+    flipThreshold: number;
+    repairs: ValidatedRepair[];
+    rejected: RejectedRepair[];
+    replaysUsed: number;
+}
+export declare function prescribeRepair(opts: PrescribeRepairOptions): Promise<RepairReport>;
+//# sourceMappingURL=repair.d.ts.map

package/dist/diagnose/repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../src/diagnose/repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEjE;4EAC4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,UAAU,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,kBAAkB,CAAA;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,UAAU,CAAA;IACjB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,MAAM,EAAE,oBAAoB,CAAA;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,kBAAkB,EAAE,CAAA;IAC5B;kEAC8D;IAC9D,UAAU,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAA;IAC/F,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,sBAAsB,CAAA;IAChC,yEAAyE;IACzE,SAAS,EAAE,IAAI,CAAA;IACf,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,oBAAoB,EAAE,MAAM,EAAE,CAAA;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,sBAAsB,CAAA;IAChC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAA;IAChC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAgHzF"}

package/dist/diagnose.d.ts

@@ -1,251 +1 @@
-import { C as CounterfactualMutation, a as attributeCounterfactuals, b as CounterfactualRunner } from './counterfactual-DlOz8PBx.js';
-export { c as CounterfactualContext, d as CounterfactualResult } from './counterfactual-DlOz8PBx.js';
-import { S as Span } from './schema-m0gsnbt3.js';
-import { T as TraceStore } from './store-BcFXE6LG.js';
-import { a as TrajectoryStep, T as Trajectory } from './trajectory-2TkpSEVh.js';
-import { h as AnalystSeverity, c as AnalystFinding } from './types-Ce17tDlG.js';
-import { C as CorpusRecord } from './corpus-B8A4BDR3.js';
-import { R as RunRecord } from './run-record-e7vj1uZQ.js';
-import './emitter-C2rqGH_l.js';
-import './store-C1YxJDEK.js';
-import './types-C7DGg5ex.js';
-import '@tangle-network/tcloud';
-import './llm-client-Bj7g0rqu.js';
-import './errors-CzMUYo7b.js';
-import './raw-provider-sink-C46HDghv.js';
-
-/**
- * Causal sweep — WHY did this run fail?
- *
- * Orchestrates the dormant counterfactual primitives into a responsibility
- * report: for each candidate step, run `reps` counterfactual replays per
- * mutation (via `runCounterfactual` — the consumer's `CounterfactualRunner`
- * is the execution seam) and reduce the per-rep score deltas into a mean
- * effect + bootstrap confidence interval (via `confidenceInterval`).
- *
- * Why `reps` is REQUIRED: a single intervention delta is one stochastic
- * draw — LLM re-execution from a prefix is sampled, so one replay cannot
- * distinguish "this step caused the failure" from sampling noise. The
- * signal is the distribution of deltas across reps; the CI over that
- * distribution is what lets a caller say "this step's effect excludes
- * zero" instead of eyeballing a point estimate.
- *
- * Budget discipline: the sweep never silently drops cells. When the
- * remaining budget cannot fund a full `reps`-sized cell, the sweep halts
- * and every step not fully probed is named in `uncovered`.
- */
-
-/** Stable reference to a trajectory step — carried through reports,
- *  findings, and corpus records so evidence stays addressable. */
-interface StepRef {
-    index: number;
-    spanId: string;
-    kind: Span['kind'];
-    name: string;
-}
-declare function stepRefOf(step: TrajectoryStep): StepRef;
-interface CausalSweepOptions {
-    store: TraceStore;
-    /** The failed run to diagnose. Its `outcome.score` is the baseline every
-     *  counterfactual delta is measured against. */
-    runId: string;
-    /** Execution seam — identical contract to `runCounterfactual`: re-runs the
-     *  agent from the mutation point and MUST `endRun` with a numeric score. */
-    runner: CounterfactualRunner;
-    /** Trajectory indices to probe. Default: every llm + tool span — the kinds
-     *  the existing `CounterfactualMutation` set targets. */
-    candidateSteps?: number[];
-    /**
-     * Mutations to probe a given step with. Returned mutations MUST target
-     * `step.index`. Default probes are the payload-free existing kinds:
-     *   - tool span → `swap-tool-result` with `newResult: null` (knockout:
-     *     how much did the run depend on this tool's information?)
-     *   - llm span → `truncate-after` (re-roll: how much did the realized
-     *     turn deviate from the policy's typical continuation?)
-     * `swap-model` / `inject-system-message` need consumer payloads, so they
-     * are opt-in via this callback.
-     */
-    mutationsPerStep?: (step: TrajectoryStep) => CounterfactualMutation[];
-    /** Replays per (step, mutation) cell. Minimum 2 — see module doc. */
-    reps: number;
-    /** Hard cap on total counterfactual replays across the whole sweep. */
-    budget: number;
-    /** Seed for the bootstrap CI resampler. Deterministic default so two
-     *  sweeps over the same deltas report identical intervals. */
-    ciSeed?: number;
-    /** Bootstrap CI confidence level. Default 0.95. */
-    ciConfidence?: number;
-}
-interface StepResponsibility {
-    stepRef: StepRef;
-    mutationKind: CounterfactualMutation['kind'];
-    /** Mean of per-rep score deltas (counterfactual − original). */
-    meanEffect: number;
-    /** Bootstrap CI over the per-rep deltas. */
-    ci: {
-        mean: number;
-        lower: number;
-        upper: number;
-    };
-    /** `ci.lower > 0 || ci.upper < 0` — the effect is distinguishable from noise. */
-    ciExcludesZero: boolean;
-    reps: number;
-    /** Raw per-rep deltas — downstream evidence, never re-derived. */
-    deltas: number[];
-    /** Replay run ids (layer='meta', parentRunId=original) for audit. */
-    counterfactualRunIds: string[];
-}
-interface CausalResponsibilityReport {
-    runId: string;
-    originalScore: number;
-    /** Ranked by |meanEffect| descending — the blame ordering. */
-    steps: StepResponsibility[];
-    /** Kind-level aggregate from the existing `attributeCounterfactuals`. */
-    byMutationKind: ReturnType<typeof attributeCounterfactuals>;
-    replaysUsed: number;
-    budget: number;
-    /** Steps planned but not fully probed before the budget ran out.
-     *  Named, never silent: an absent step is "no effect found"; an
-     *  uncovered step is "not measured". */
-    uncovered: StepRef[];
-}
-declare function causalSweep(opts: CausalSweepOptions): Promise<CausalResponsibilityReport>;
-
-/**
- * Replay-validated repair — WHAT SHOULD HAVE HAPPENED?
- *
- * Takes the blamed steps from a `CausalResponsibilityReport`, asks a
- * consumer-supplied `proposeFix` (LLM-backed in live use) for candidate
- * mutations, and machine-verifies each candidate by replaying the run
- * WITH the mutation applied (through the same `runCounterfactual` seam
- * the sweep uses).
- *
- * A repair is "what should have happened" ONLY when every validation
- * replay crosses `flipThreshold` — a prescription is never speculated,
- * it is demonstrated. Candidates that don't flip, or whose replay
- * errors, land in `rejected` with a typed reason; nothing is dropped
- * silently.
- */
-
-/** Context handed to `proposeFix` so an LLM-backed proposer can see the
- *  full trajectory plus the responsibility evidence for the blamed step. */
-interface RepairContext {
-    runId: string;
-    trajectory: Trajectory;
-    originalScore: number;
-    responsibility: StepResponsibility;
-}
-interface PrescribeRepairOptions {
-    store: TraceStore;
-    /** The failed run the sweep diagnosed. */
-    runId: string;
-    /** Execution seam — same `CounterfactualRunner` contract as the sweep. */
-    runner: CounterfactualRunner;
-    /** Blamed steps from `causalSweep` — typically `report.steps.slice(0, k)`. */
-    blamed: StepResponsibility[];
-    /** Candidate-fix generator. Consumer-supplied; LLM-backed in live use.
-     *  Returned mutations MUST target the blamed step's index. */
-    proposeFix: (step: TrajectoryStep, context: RepairContext) => Promise<CounterfactualMutation[]>;
-    /** Score every validation replay must reach for the repair to count. Default 0.5. */
-    flipThreshold?: number;
-    /** Validation replays per candidate mutation. Default 3. */
-    repsToValidate?: number;
-    /** Max candidate mutations tried per step. Default: all proposed. */
-    maxAttemptsPerStep?: number;
-}
-interface ValidatedRepair {
-    stepRef: StepRef;
-    mutation: CounterfactualMutation;
-    /** Always true — presence in `repairs` IS the machine-verified claim. */
-    validated: true;
-    /** Mean counterfactual score across the validation reps. */
-    meanScore: number;
-    /** meanScore − originalScore. */
-    deltaScore: number;
-    reps: number;
-    /** Replay run ids backing the validation — audit trail. */
-    counterfactualRunIds: string[];
-}
-interface RejectedRepair {
-    stepRef: StepRef;
-    mutation: CounterfactualMutation;
-    reason: 'did-not-flip' | 'error';
-    /** Present for 'did-not-flip': mean delta over the reps that ran. */
-    deltaScore?: number;
-    /** Present for 'error': the message, preserved for diagnosis. */
-    error?: string;
-}
-interface RepairReport {
-    runId: string;
-    originalScore: number;
-    flipThreshold: number;
-    repairs: ValidatedRepair[];
-    rejected: RejectedRepair[];
-    replaysUsed: number;
-}
-declare function prescribeRepair(opts: PrescribeRepairOptions): Promise<RepairReport>;
-
-/**
- * Remediation adapters — HOW DO WE MAKE IT HAPPEN?
- *
- * The diagnose chain ends by feeding existing improvement machinery,
- * not by building new machinery:
- *
- *   - `toAnalystFindings` → the analyst contract (`makeFinding`), so
- *     responsibility evidence flows into the same registry / steering /
- *     diff pipeline every other analyst feeds.
- *   - `toCorpusRecord` → the RL corpus (`CorpusRecord`), pinning the
- *     diagnosed failure + validated repair as a permanent scenario.
- *   - `suggestInvariant` → a plain-data hint in the shape the
- *     trace-contracts machinery consumes (`never` / `without` clauses).
- */
-
-declare const DIAGNOSE_ANALYST_ID = "diagnose-causal-sweep";
-/** Severity from causal effect size. Effects whose CI includes zero are
- *  'info' regardless of magnitude — an indistinguishable-from-noise effect
- *  must not steer remediation priority. */
-declare function severityFromEffect(responsibility: StepResponsibility): AnalystSeverity;
-/** Deterministic human-readable rendering of a mutation — used in
- *  recommended actions, corpus completions, and invariant hints. */
-declare function describeMutation(mutation: CounterfactualMutation): string;
-/**
- * Lift a responsibility report (and optionally its validated repairs) into
- * `AnalystFinding`s via the real `makeFinding` factory. One finding per
- * probed step; a validated repair for that step upgrades the finding with
- * a `recommended_action` + the replay-validation evidence.
- *
- * Findings are OBSERVED causal probes (replay deltas), not judge verdicts,
- * so `derived_from_judge` stays unset and they may steer.
- */
-declare function toAnalystFindings(report: CausalResponsibilityReport, repairs?: RepairReport): AnalystFinding[];
-/**
- * Pin the diagnosed failure as a permanent corpus scenario. Takes the
- * original run's `RunRecord` projection plus a validated repair and emits
- * a fresh `CorpusRecord` (new runId, so corpus dedup keeps both the raw
- * failure and the diagnosed entry).
- *
- * `completion` defaults to the validated mutation's rendering — "what
- * should have happened" in machine-derived form. Supply `prompt` (and
- * optionally a richer `completion`) when the trajectory text is available
- * so the record is harvestable by `buildDatasetFromCorpus`.
- */
-declare function toCorpusRecord(run: RunRecord, repair: ValidatedRepair, opts?: {
-    prompt?: string;
-    completion?: string;
-}): CorpusRecord;
-/** Plain-data invariant hint. The trace-contracts machinery consumes this
- *  shape: `never` is a pattern that must not appear in a passing trace;
- *  `without` is a guard whose absence makes the failure reachable. */
-interface InvariantHint {
-    description: string;
-    never?: string;
-    without?: string;
-}
-/**
- * Derive an invariant hint from a validated repair. Deterministic per
- * mutation kind — the hint names the contract a trace must satisfy so
- * the diagnosed failure cannot silently recur.
- */
-declare function suggestInvariant(repair: ValidatedRepair): InvariantHint;
-
-export { type CausalResponsibilityReport, type CausalSweepOptions, CounterfactualMutation, CounterfactualRunner, DIAGNOSE_ANALYST_ID, type InvariantHint, type PrescribeRepairOptions, type RejectedRepair, type RepairContext, type RepairReport, type StepRef, type StepResponsibility, type ValidatedRepair, causalSweep, describeMutation, prescribeRepair, severityFromEffect, stepRefOf, suggestInvariant, toAnalystFindings, toCorpusRecord };
+export * from './diagnose/index'

package/dist/diagnose.js

@@ -13,7 +13,7 @@ import {
 } from "./chunk-56GC6VYO.js";
 import {
   validateRunRecord
-} from "./chunk-KWRRMR3J.js";
+} from "./chunk-LO6IOIJ2.js";
 import "./chunk-TVVP3ZZQ.js";
 import "./chunk-VSMTAMNK.js";
 import {

package/dist/discover-personas.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Walk a personas directory and return every file matching the convention
+ * `NN-slug.{yaml,yml,json,md}`. Sorted by filename so the numeric prefix
+ * gives stable persona ordering for reproducibility. Consumers filter
+ * through `include` / `exclude`.
+ */
+export interface DiscoverPersonasOptions {
+    /**
+     * Regex applied to filenames. Files that don't match are skipped.
+     * Default: `^[0-9]{2}-.+\.(yaml|yml|json|md)$`.
+     */
+    pattern?: RegExp;
+    /**
+     * Filenames (or basenames) to skip. Use this to exclude WIP / archived
+     * personas without removing the file.
+     */
+    exclude?: readonly string[];
+    /**
+     * If set, return only personas whose basename contains one of these
+     * substrings (post-pattern filter).
+     */
+    include?: readonly string[];
+    /** Recurse into subdirectories. Default false. */
+    recursive?: boolean;
+}
+export interface DiscoveredPersona {
+    /** Absolute file path. */
+    path: string;
+    /** Filename without directory. */
+    filename: string;
+    /** Filename without extension — the conventional persona id. */
+    id: string;
+}
+export declare function discoverPersonas(dir: string, opts?: DiscoverPersonasOptions): Promise<DiscoveredPersona[]>;
+//# sourceMappingURL=discover-personas.d.ts.map

package/dist/discover-personas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-personas.d.ts","sourceRoot":"","sources":["../src/discover-personas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAA;CACX;AAID,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA0C9B"}

package/dist/driver.d.ts

@@ -0,0 +1,95 @@
+import type { TCloud } from '@tangle-network/tcloud';
+import type { ProductClient } from './client';
+import type { DriverResult, DriverState, PersonaConfig } from './types';
+export interface AgentDriverConfig {
+    client: ProductClient;
+    driverModel?: string;
+    /** System prompt context for the driver LLM to understand the product */
+    productContext?: string;
+}
+/**
+ * AgentDriver — meta-agent that plays a persona against the real product.
+ *
+ * Uses a driver LLM (Claude/GPT-4o) to decide what to say each turn.
+ * Not scripted — the driver gets the current product state and decides
+ * the next realistic user message.
+ */
+export declare class AgentDriver {
+    private tc;
+    private client;
+    private driverModel;
+    private productContext;
+    constructor(tc: TCloud, config: AgentDriverConfig);
+    /**
+     * Run a persona through the product.
+     *
+     * Returns metrics on how many turns to completion, cost curve,
+     * quality curve, and convergence curve.
+     */
+    run(persona: PersonaConfig): Promise<DriverResult>;
+    /** Use the driver LLM to decide what the "user" says next */
+    private decideNextMessage;
+    /** Handle pending approvals based on persona feedback patterns */
+    private handleApprovals;
+}
+/**
+ * Build the driver LLM's system prompt. The simulated user is an
+ * adversarial senior professional: it judges the agent's last response by a
+ * professional standard, refuses vague answers, challenges undefended
+ * claims, probes the persona's pressure points without revealing them, and
+ * signs off (DONE) only when a real practitioner would act on the work
+ * unmodified. Pure function of persona, product state, and product context
+ * — exported so harness authors can inspect and regression-test it.
+ */
+export declare function buildDriverSystemPrompt(persona: PersonaConfig, state: DriverState, productContext?: string): string;
+export interface WorkerDriverContext {
+    /** The goal (or sub-goal) the driven worker must actually accomplish. */
+    goal: string;
+    /** The worker's harness — e.g. 'claude-code' | 'codex' | 'opencode' | 'router-tools'.
+     *  Names which capability profile the driver should exploit. */
+    harness?: string;
+    /** A capability + caveat brief for THIS harness (parallel tool calls, sub-agents and
+     *  their depth/concurrency limits, autonomy/runaway profile, MCP, native tool-isolation)
+     *  — sourced from the harness-compat matrix. Free text so the substrate stays decoupled
+     *  from any runtime harness type. */
+    harnessBrief?: string;
+    /** What the worker has done so far — the trace/state summary the driver reasons over to
+     *  write its next instruction. Empty on the first turn. */
+    progress?: string;
+    /** Optional extra context (repo, constraints, the deliverable's acceptance check). */
+    context?: string;
+}
+/**
+ * Build the WORKER-DRIVER system prompt — the harness-aware sibling of
+ * `buildDriverSystemPrompt`. Where that one role-plays a demanding *user* of a
+ * product, this one is a meta-agent that DRIVES a capable coding *worker* to
+ * complete a goal: it writes rich, high-signal instructions that direct the
+ * worker to exploit its harness's full power (parallelize, sub-agents, run-to-
+ * completion, tools/MCP), matched to what THAT harness can actually do. The
+ * load-bearing contract: the driver never writes a thin steer — every message
+ * is the dense, specific directive a world-class engineering lead would write.
+ * Pure function; exported so harness authors can inspect and regression-test it.
+ */
+export declare function buildWorkerDriverSystemPrompt(ctx: WorkerDriverContext): string;
+export interface DecideNextUserTurnOpts {
+    persona: PersonaConfig;
+    state: DriverState;
+    /** Conversation so far — alternating user/assistant messages, oldest first. */
+    history: {
+        role: string;
+        content: string;
+    }[];
+    /** Optional product context woven into the driver prompt. */
+    productContext?: string;
+    /** Driver LLM model. Defaults to claude-sonnet-4-6. */
+    model?: string;
+}
+/**
+ * Decide the simulated user's next turn — the reactive, adversarial
+ * turn-generation core of `AgentDriver`, exposed standalone so an in-process
+ * eval harness can drive multi-shot conversations without the `ProductClient`
+ * workspace machinery. Returns the next user message, or the literal "DONE"
+ * when the simulated professional would sign off.
+ */
+export declare function decideNextUserTurn(tc: TCloud, opts: DecideNextUserTurnOpts): Promise<string>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAG7C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAA6B,MAAM,SAAS,CAAA;AAElG,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAeD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAQ;IAClB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,cAAc,CAAQ;gBAElB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB;IAOjD;;;;;OAKG;IACG,GAAG,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiGxD,6DAA6D;YAC/C,iBAAiB;IAc/B,kEAAkE;YACpD,eAAe;CAwB9B;AAYD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,WAAW,EAClB,cAAc,SAAK,GAClB,MAAM,CA0CR;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ;oEACgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;yCAGqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;+DAC2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CA4B9E;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,aAAa,CAAA;IACtB,KAAK,EAAE,WAAW,CAAA;IAClB,+EAA+E;IAC/E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC5C,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAiCjB"}

package/dist/driver.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The simulated user is the eval's difficulty knob. These tests pin the
+ * adversarial contract of the driver system prompt so a future edit cannot
+ * quietly soften it back into a passive script-reader — a regression that
+ * would inflate every downstream agent score with no real improvement.
+ */
+export {};
+//# sourceMappingURL=driver.test.d.ts.map

package/dist/driver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.test.d.ts","sourceRoot":"","sources":["../src/driver.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/dual-agent-bench.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Dual-agent convergence bench.
+ *
+ * Pattern lifted from dual-worker review loops: two agents take turns until
+ * they converge on a consensus artifact. One proposes, the other critiques;
+ * the proposer revises; repeat until a score threshold is hit or max rounds.
+ *
+ * Generalized so any two "agents" (gateways, local functions, anything with
+ * `propose` + `critique`) compose in. Returns convergence rounds per
+ * scenario + whether convergence happened.
+ */
+export interface DualAgentScenario {
+    id: string;
+    initialPrompt: string;
+    /** Optional context the agents can read (e.g. source documents). */
+    context?: Record<string, unknown>;
+}
+export interface DualAgentRound {
+    roundIndex: number;
+    proposal: string;
+    critique: string;
+    convergenceScore: number;
+}
+export interface DualAgentScenarioResult {
+    scenarioId: string;
+    converged: boolean;
+    roundsToConverge: number | null;
+    finalProposal: string;
+    history: DualAgentRound[];
+    finalScore: number;
+}
+export interface DualAgentBenchConfig {
+    scenarios: DualAgentScenario[];
+    maxRounds?: number;
+    /** Convergence threshold in 0..1 (default 0.85). */
+    convergenceThreshold?: number;
+    /**
+     * Propose an answer given the scenario + the critic's prior critique (if any).
+     * Returns the proposal string.
+     */
+    propose: (args: {
+        scenario: DualAgentScenario;
+        roundIndex: number;
+        priorProposal?: string;
+        priorCritique?: string;
+    }) => Promise<string>;
+    /**
+     * Critique the proposer's current output. Returns a structured critique
+     * (free text) plus a convergence score: how close the proposal is to
+     * acceptable. 1.0 = accept, 0.0 = totally off.
+     */
+    critique: (args: {
+        scenario: DualAgentScenario;
+        roundIndex: number;
+        proposal: string;
+    }) => Promise<{
+        critique: string;
+        convergenceScore: number;
+    }>;
+    /** Optional per-round hook for progress + tracing. */
+    onRoundComplete?: (info: {
+        scenarioId: string;
+        round: DualAgentRound;
+    }) => void;
+}
+export interface DualAgentReport {
+    scenarios: DualAgentScenarioResult[];
+    aggregate: {
+        convergenceRate: number;
+        avgRoundsToConverge: number | null;
+        avgFinalScore: number;
+    };
+    config: {
+        maxRounds: number;
+        convergenceThreshold: number;
+    };
+}
+export declare class DualAgentBench {
+    run(config: DualAgentBenchConfig): Promise<DualAgentReport>;
+}
+//# sourceMappingURL=dual-agent-bench.d.ts.map

package/dist/dual-agent-bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-agent-bench.d.ts","sourceRoot":"","sources":["../src/dual-agent-bench.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,aAAa,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,OAAO,CAAA;IAClB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE;QACd,QAAQ,EAAE,iBAAiB,CAAA;QAC3B,UAAU,EAAE,MAAM,CAAA;QAClB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,aAAa,CAAC,EAAE,MAAM,CAAA;KACvB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACrB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,QAAQ,EAAE,iBAAiB,CAAA;QAC3B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,MAAM,CAAA;KACjB,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC7D,sDAAsD;IACtD,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,KAAK,IAAI,CAAA;CAChF;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,uBAAuB,EAAE,CAAA;IACpC,SAAS,EAAE;QACT,eAAe,EAAE,MAAM,CAAA;QACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;QAClC,aAAa,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,MAAM,EAAE;QACN,SAAS,EAAE,MAAM,CAAA;QACjB,oBAAoB,EAAE,MAAM,CAAA;KAC7B,CAAA;CACF;AAED,qBAAa,cAAc;IACnB,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;CAoFlE"}