@tangle-network/agent-eval 0.93.0 → 0.95.0

package/dist/{run-campaign-RDGAM5KJ.js → run-campaign-WXY7KI67.js}

@@ -1,10 +1,10 @@
 import {
   runCampaign
-} from "./chunk-TWS7AZEY.js";
-import "./chunk-LMZQ2Z4U.js";
+} from "./chunk-2T4EZACH.js";
+import "./chunk-56GC6VYO.js";
 import "./chunk-3BFEG2F6.js";
 import "./chunk-PZ5AY32C.js";
 export {
   runCampaign
 };
-//# sourceMappingURL=run-campaign-RDGAM5KJ.js.map
+//# sourceMappingURL=run-campaign-WXY7KI67.js.map

package/dist/run-critic.d.ts

@@ -0,0 +1,23 @@
+import { type RunScore, type RunScoreWeights } from './run-score';
+import type { Artifact, BudgetLedgerEntry, Run, Span, TraceEvent, TraceStore } from './trace';
+export interface RunTrace {
+    run: Run;
+    spans: Span[];
+    events: TraceEvent[];
+    artifacts: Artifact[];
+    budget: BudgetLedgerEntry[];
+}
+export interface RunCriticOptions {
+    weights?: Partial<RunScoreWeights>;
+    driftPatterns?: RegExp[];
+}
+export declare class RunCritic {
+    private readonly weights?;
+    private readonly driftPatterns;
+    constructor(options?: RunCriticOptions);
+    score(store: TraceStore, runId: string): Promise<RunScore>;
+    scoreTrace(trace: RunTrace): RunScore;
+    rank(score: RunScore): number;
+    private isDrift;
+}
+//# sourceMappingURL=run-critic.d.ts.map

package/dist/run-critic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-critic.d.ts","sourceRoot":"","sources":["../src/run-critic.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7F,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAE7F,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,GAAG,CAAA;IACR,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,MAAM,EAAE,iBAAiB,EAAE,CAAA;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;IAClC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAWD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAE5B,OAAO,GAAE,gBAAqB;IAKpC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAYhE,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ;IAmHrC,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IAI7B,OAAO,CAAC,OAAO;CAGhB"}

package/dist/run-evidence.d.ts

@@ -0,0 +1,32 @@
+import type { ControlEvalResult, ControlRunResult } from './control-runtime';
+import { type RunRecord, type RunSplitTag, type RunTokenUsage } from './run-record';
+export interface RunEvidenceMetadata {
+    experimentId: string;
+    candidateId: string;
+    seed: number;
+    model: string;
+    promptHash: string;
+    configHash: string;
+    commitSha: string;
+    splitTag: RunSplitTag;
+    tokenUsage: RunTokenUsage;
+    queueMs?: number;
+    judgeMetadata?: RunRecord['judgeMetadata'];
+    raw?: Record<string, number>;
+}
+export interface ControlRunToRunRecordOptions extends RunEvidenceMetadata {
+    runId?: string;
+    score?: number;
+    failureMode?: string;
+}
+/**
+ * Project a completed control-loop run into the strict RunRecord shape used by
+ * release gates, optimizer tables, and research reports.
+ *
+ * The control loop owns live execution evidence. The caller still supplies the
+ * experiment-cell metadata because prompt/config hashes, split assignment,
+ * model snapshot, and commit SHA are product/harness concerns.
+ */
+export declare function controlRunToRunRecord<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(run: ControlRunResult<TState, TAction, TActionResult, TEval>, options: ControlRunToRunRecordOptions): RunRecord;
+export declare function scoreFromEvals(evals: readonly ControlEvalResult[]): number | undefined;
+//# sourceMappingURL=run-evidence.d.ts.map

package/dist/run-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-evidence.d.ts","sourceRoot":"","sources":["../src/run-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAA;AAGrB,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,WAAW,CAAA;IACrB,UAAU,EAAE,aAAa,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,SAAS,CAAC,eAAe,CAAC,CAAA;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EACN,OAAO,EACP,aAAa,EACb,KAAK,SAAS,iBAAiB,GAAG,iBAAiB,EAEnD,GAAG,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,EAC5D,OAAO,EAAE,4BAA4B,GACpC,SAAS,CA8BX;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,GAAG,SAAS,CAMtF"}

package/dist/{run-record-e7vj1uZQ.d.ts → run-record.d.ts}

@@ -1,110 +1,3 @@
-import { V as ValidationError } from './errors-CzMUYo7b.js';
-import { F as FailureClass } from './schema-m0gsnbt3.js';
-
-type AgentProfileCellSchemaVersion = 'agent-profile-cell/v1';
-type AgentProfileJson = string | number | boolean | null | AgentProfileJson[] | {
-    [key: string]: AgentProfileJson;
-};
-type AgentProfileDimensionValue = string | number | boolean | null;
-interface AgentProfileSource {
-    /** Runtime/profile contract being fingerprinted, e.g. `sandbox-agent-profile`. */
-    kind: string;
-    /** sha256 over the canonical source profile object. */
-    hash: string;
-}
-interface AgentProfileSourceInput {
-    kind: string;
-    /** Precomputed sha256 for callers that already sign their profile artifact. */
-    hash?: string;
-    /** Full canonical runtime profile; hashed and then discarded from the cell. */
-    profile?: AgentProfileJson;
-}
-interface AgentProfileHarness {
-    id: string;
-    version?: string;
-    hash?: string;
-}
-interface AgentProfileCellInput {
-    profileId: string;
-    sourceProfile: AgentProfileSourceInput;
-    harness?: AgentProfileHarness;
-    model?: string;
-    promptHash?: string;
-    dimensions?: Record<string, AgentProfileDimensionValue>;
-}
-interface AgentProfileCell {
-    schemaVersion: AgentProfileCellSchemaVersion;
-    cellId: string;
-    profileId: string;
-    sourceProfile: AgentProfileSource;
-    harness?: AgentProfileHarness;
-    model?: string;
-    promptHash?: string;
-    dimensions?: Record<string, AgentProfileDimensionValue>;
-}
-declare class AgentProfileCellValidationError extends ValidationError {
-    readonly path: string;
-    constructor(message: string, path?: string);
-}
-declare function buildAgentProfileCell(input: AgentProfileCellInput): Promise<AgentProfileCell>;
-declare function agentProfileCellHashMaterial(cell: AgentProfileCell): Omit<AgentProfileCell, 'cellId'>;
-declare function verifyAgentProfileCell(cell: AgentProfileCell): Promise<boolean>;
-declare function validateAgentProfileCell(input: unknown): AgentProfileCell;
-declare function requireAgentProfileCell(record: {
-    runId: string;
-    agentProfile?: AgentProfileCell;
-}): AgentProfileCell;
-declare function agentProfileCellKey(record: {
-    runId: string;
-    agentProfile?: AgentProfileCell;
-}): string;
-declare function assertRunAgentProfileCell(record: {
-    runId: string;
-    model: string;
-    promptHash: string;
-    agentProfile?: AgentProfileCell;
-}): Promise<AgentProfileCell>;
-declare function groupRunsByAgentProfileCell<T extends {
-    runId: string;
-    agentProfile?: AgentProfileCell;
-}>(records: readonly T[]): Map<string, T[]>;
-/** Canonical `sourceProfile.kind` values. Two products fingerprinting the
- *  same canonical profile MUST use the same kind for their cells to share
- *  `sourceProfile.hash`. Extend rather than create new strings — adding a
- *  new kind is a deliberate cross-product schema change. */
-declare const AGENT_PROFILE_KINDS: {
-    /** A profile declared via `defineAgentProfile(...)` from
-     *  `@tangle-network/sandbox`. The default kind for sandbox-hosted
-     *  products (gtm-agent, blueprint-agent, sandbox, evals). */
-    readonly SANDBOX_AGENT_PROFILE: "sandbox-agent-profile";
-};
-type AgentProfileKind = (typeof AGENT_PROFILE_KINDS)[keyof typeof AGENT_PROFILE_KINDS];
-/** Canonicalize an arbitrary value into `AgentProfileJson` by JSON
- *  round-trip. Throws when the value contains anything not representable
- *  as JSON (functions, BigInt, cycles) — non-portable profiles fail loud
- *  rather than silently dropping fields. */
-declare function toAgentProfileJson(value: unknown): AgentProfileJson;
-/** Minimal shape required of any sandbox-SDK `AgentProfile` — anything
- *  with a non-empty `name` and `version` plus JSON-serializable contents.
- *  Compatible with `defineAgentProfile(...)` output from
- *  `@tangle-network/sandbox`; products that have not yet declared a real
- *  profile can pass a `{ name, version, ...metadata }` stub. */
-interface SandboxAgentProfileLike {
-    name: string;
-    version: string;
-    [key: string]: unknown;
-}
-/** Higher-level helper that hard-codes the canonical
- *  `sandbox-agent-profile` kind plus the JSON canonicalization. Equivalent
- *  to calling `buildAgentProfileCell` with `profileId = \`${name}@${version}\``
- *  and `sourceProfile = { kind: SANDBOX_AGENT_PROFILE, profile: <round-tripped> }`.
- *
- *  Use this from any product consuming a sandbox-SDK `AgentProfile`; the
- *  manual `buildAgentProfileCell` call is reserved for advanced cases
- *  (custom kinds, pre-computed source hashes, alternate profileId
- *  conventions). */
-declare function buildSandboxAgentProfileCell(profile: SandboxAgentProfileLike, input: Omit<AgentProfileCellInput, 'profileId' | 'sourceProfile'>): Promise<AgentProfileCell>;
-
 /**
  * Paper-grade RunRecord schema + runtime validator.
  *
@@ -129,16 +22,18 @@ declare function buildSandboxAgentProfileCell(profile: SandboxAgentProfileLike,
  * The validator runs in pure TS — zod is intentionally NOT a
  * dependency. Round-trip tested in `tests/run-record.test.ts`.
  */
-
+import type { AgentProfileCell } from './agent-profile-cell';
+import { ValidationError } from './errors';
+import type { FailureClass } from './trace/schema';
 /** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
  *  combined train+test pool that the optimizer is allowed to read. */
-type RunSplitTag = 'search' | 'dev' | 'holdout';
-interface RunTokenUsage {
+export type RunSplitTag = 'search' | 'dev' | 'holdout';
+export interface RunTokenUsage {
     input: number;
     output: number;
     cached?: number;
 }
-interface RunJudgeMetadata {
+export interface RunJudgeMetadata {
     model: string;
     promptVersion: string;
     /** [0,1] confidence the judge declared. Constant judge confidence
@@ -167,7 +62,7 @@ interface RunJudgeMetadata {
  * by id. A missing key in `perJudge` is ambiguous (silent zero vs not
  * run); the explicit list makes a partial-failure recorded as such.
  */
-interface JudgeScoresRecord {
+export interface JudgeScoresRecord {
     /** Per-judge per-dimension scores. `{ "kimi-k2.6": { helpfulness: 0.8, clarity: 0.7 }, ... }`. */
     perJudge: Record<string, Record<string, number>>;
     /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
@@ -183,7 +78,7 @@ interface JudgeScoresRecord {
      *  first-judge only — consumer's choice). */
     notes?: string;
 }
-interface RunOutcome {
+export interface RunOutcome {
     /** Score on the search/optimization split. Optional because a
      *  holdout-only evaluation only fills `holdoutScore`. */
     searchScore?: number;
@@ -221,14 +116,14 @@ interface RunOutcome {
  *     model (after any steering bundle merge).
  *   - `configHash` is the sha256 of the effective run config (model,
  *     temperature, tools, judges, splits). The pair (promptHash,
- *     configHash) uniquely identifies an experimental cell.
+ *     configHash) uniquely identifies an experiment cell.
  *
  * Model snapshot discipline:
  *   - `model` MUST encode a snapshot version. Bare aliases like
  *     `claude-sonnet-4` or `gpt-4o` are banned — they remap silently.
  *     Use `claude-sonnet-4-6@2025-04-15` or `gpt-4o-2024-11-20`.
  */
-interface RunRecord {
+export interface RunRecord {
     /** UUID for the run. */
     runId: string;
     /** Logical experiment grouping (a treatment vs a baseline within
@@ -292,7 +187,7 @@ interface RunRecord {
      */
     agentProfile?: AgentProfileCell;
 }
-declare class RunRecordValidationError extends ValidationError {
+export declare class RunRecordValidationError extends ValidationError {
     readonly path: string;
     constructor(message: string, path?: string);
 }
@@ -301,11 +196,11 @@ declare class RunRecordValidationError extends ValidationError {
  * missing or wrongly-typed field. Returns the input cast to
  * `RunRecord` on success — the validator does not coerce.
  */
-declare function validateRunRecord(input: unknown): RunRecord;
+export declare function validateRunRecord(input: unknown): RunRecord;
 /** Boolean validator — convenience for filtering arrays. */
-declare function isRunRecord(input: unknown): input is RunRecord;
+export declare function isRunRecord(input: unknown): input is RunRecord;
 /** Non-throwing validator — returns a discriminated union. */
-declare function parseRunRecordSafe(input: unknown): {
+export declare function parseRunRecordSafe(input: unknown): {
     ok: true;
     value: RunRecord;
 } | {
@@ -313,6 +208,5 @@ declare function parseRunRecordSafe(input: unknown): {
     error: RunRecordValidationError;
 };
 /** Round-trip helper — `JSON.parse(JSON.stringify(record))` then validate. */
-declare function roundTripRunRecord(record: RunRecord): RunRecord;
-
-export { type AgentProfileCell as A, validateAgentProfileCell as B, validateRunRecord as C, verifyAgentProfileCell as D, type JudgeScoresRecord as J, type RunRecord as R, type SandboxAgentProfileLike as S, type RunSplitTag as a, type RunTokenUsage as b, type RunJudgeMetadata as c, type AgentProfileCellInput as d, AGENT_PROFILE_KINDS as e, type AgentProfileCellSchemaVersion as f, AgentProfileCellValidationError as g, type AgentProfileDimensionValue as h, type AgentProfileHarness as i, type AgentProfileJson as j, type AgentProfileKind as k, type AgentProfileSource as l, type AgentProfileSourceInput as m, type RunOutcome as n, RunRecordValidationError as o, agentProfileCellHashMaterial as p, agentProfileCellKey as q, assertRunAgentProfileCell as r, buildAgentProfileCell as s, buildSandboxAgentProfileCell as t, groupRunsByAgentProfileCell as u, isRunRecord as v, parseRunRecordSafe as w, requireAgentProfileCell as x, roundTripRunRecord as y, toAgentProfileJson as z };
+export declare function roundTripRunRecord(record: RunRecord): RunRecord;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/run-record.d.ts.map

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

package/dist/run-record.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-record.test.d.ts.map

package/dist/run-record.test.d.ts.map

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

package/dist/run-score.d.ts

@@ -0,0 +1,31 @@
+export interface RunScore {
+    success: number;
+    goalProgress: number;
+    repoGroundedness: number;
+    driftPenalty: number;
+    toolUseQuality: number;
+    patchQuality: number;
+    testReality: number;
+    finalGate: number;
+    reviewerBlockers: number;
+    costUsd: number;
+    wallSeconds: number;
+    notes?: string[];
+}
+export interface RunScoreWeights {
+    success: number;
+    goalProgress: number;
+    repoGroundedness: number;
+    driftPenalty: number;
+    toolUseQuality: number;
+    patchQuality: number;
+    testReality: number;
+    finalGate: number;
+    reviewerBlockers: number;
+    costUsd: number;
+    wallSeconds: number;
+}
+export declare const DEFAULT_RUN_SCORE_WEIGHTS: RunScoreWeights;
+export declare function aggregateRunScore(score: RunScore, weights?: Partial<RunScoreWeights>): number;
+export declare function clamp01(value: number): number;
+//# sourceMappingURL=run-score.d.ts.map

package/dist/run-score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-score.d.ts","sourceRoot":"","sources":["../src/run-score.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,eAAO,MAAM,yBAAyB,EAAE,eAYvC,CAAA;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,MAAM,CAejG;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7C"}

package/dist/runtime-trajectory.d.ts

@@ -0,0 +1,47 @@
+import type { RunSplitTag } from './run-record';
+export interface RuntimeTrajectoryHookEvent {
+    id: string;
+    runId: string;
+    scenarioId?: string;
+    target: string;
+    phase: string;
+    timestamp: number;
+    stepIndex?: number;
+    parentId?: string;
+    payload?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface RuntimeTrajectoryRecord {
+    id?: string;
+    scenarioId?: string;
+    splitTag?: RunSplitTag;
+    runtimeEvents?: unknown;
+    [key: string]: unknown;
+}
+export interface RuntimeTrajectoryRunRecord {
+    runId: string;
+    scenarioId?: string;
+    splitTag: RunSplitTag;
+}
+export interface RuntimeTrajectoryEvidenceSummary {
+    recordCount: number;
+    recordWithRuntimeEventsCount: number;
+    runtimeRunCount: number;
+    lifecycleEventCount: number;
+    defaultedSplitCount: number;
+}
+export interface RuntimeTrajectoryEvidenceProjection {
+    runs: RuntimeTrajectoryRunRecord[];
+    events: RuntimeTrajectoryHookEvent[];
+    summary: RuntimeTrajectoryEvidenceSummary;
+    diagnostics: string[];
+}
+export interface ProjectRuntimeTrajectoryEvidenceOptions<TRecord extends RuntimeTrajectoryRecord = RuntimeTrajectoryRecord> {
+    records: TRecord[];
+    defaultSplitTag?: RunSplitTag;
+    recordIdOf?: (record: TRecord, index: number) => string | undefined;
+    scenarioIdOf?: (record: TRecord, index: number) => string | undefined;
+}
+export declare function projectRuntimeTrajectoryEvidence<TRecord extends RuntimeTrajectoryRecord>(options: ProjectRuntimeTrajectoryEvidenceOptions<TRecord>): RuntimeTrajectoryEvidenceProjection;
+export declare function parseRuntimeTrajectoryHookEvent(input: unknown): RuntimeTrajectoryHookEvent | null;
+//# sourceMappingURL=runtime-trajectory.d.ts.map

package/dist/runtime-trajectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-trajectory.d.ts","sourceRoot":"","sources":["../src/runtime-trajectory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,MAAM,WAAW,gCAAgC;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,4BAA4B,EAAE,MAAM,CAAA;IACpC,eAAe,EAAE,MAAM,CAAA;IACvB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,mBAAmB,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,mCAAmC;IAClD,IAAI,EAAE,0BAA0B,EAAE,CAAA;IAClC,MAAM,EAAE,0BAA0B,EAAE,CAAA;IACpC,OAAO,EAAE,gCAAgC,CAAA;IACzC,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,MAAM,WAAW,uCAAuC,CACtD,OAAO,SAAS,uBAAuB,GAAG,uBAAuB;IAEjE,OAAO,EAAE,OAAO,EAAE,CAAA;IAClB,eAAe,CAAC,EAAE,WAAW,CAAA;IAC7B,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IACnE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;CACtE;AAID,wBAAgB,gCAAgC,CAAC,OAAO,SAAS,uBAAuB,EACtF,OAAO,EAAE,uCAAuC,CAAC,OAAO,CAAC,GACxD,mCAAmC,CA8DrC;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,GAAG,IAAI,CAoBjG"}

package/dist/{test-graded-scenario-BdVaPyHT.d.ts → sandbox-harness.d.ts}

@@ -1,7 +1,3 @@
-import { T as TraceEmitter } from './emitter-DEZwY14K.js';
-import { R as Run, F as FailureClass } from './schema-m0gsnbt3.js';
-import { T as TraceStore } from './store-CKUAgsJz.js';
-
 /**
  * SandboxHarness — executes a scenario in an isolated environment and
  * emits a rich SandboxSpan into the trace.
@@ -15,8 +11,8 @@ import { T as TraceStore } from './store-CKUAgsJz.js';
  * Consumers implement `SandboxDriver` for custom backends (Firecracker,
  * Cloudflare sandbox product, etc.). The harness doesn't care which.
  */
-
-interface HarnessConfig {
+import type { TraceEmitter } from './trace/emitter';
+export interface HarnessConfig {
     /** Setup command (e.g. "pnpm install"). Non-zero exit fails the run. */
     setupCommand?: string;
     /** Run command (e.g. "pnpm build"). */
@@ -27,6 +23,12 @@ interface HarnessConfig {
     cwd?: string;
     /** Max wall-clock per phase in ms. Default 10 minutes. */
     timeoutMs?: number;
+    /**
+     * Cap on captured stdout+stderr bytes per phase. A runaway process can
+     * otherwise grow the in-memory buffer without bound. Once hit, further
+     * output is dropped and `outputTruncated` is set. Default 16 MiB.
+     */
+    maxOutputBytes?: number;
     /** Image for the docker driver. */
     image?: string;
     /** Extra env vars (validated; shell-escaped). */
@@ -34,14 +36,14 @@ interface HarnessConfig {
     /** Parser for the test output — maps stdout/stderr/exit code → pass count. */
     testParser?: TestOutputParser;
 }
-interface TestOutputParser {
+export interface TestOutputParser {
     id: string;
     parse(stdout: string, stderr: string, exitCode: number): {
         testsTotal: number;
         testsPassed: number;
     } | undefined;
 }
-interface SandboxResult {
+export interface SandboxResult {
     phase: 'setup' | 'run' | 'test';
     exitCode: number;
     stdout: string;
@@ -49,20 +51,33 @@ interface SandboxResult {
     wallMs: number;
     testsTotal?: number;
     testsPassed?: number;
+    /**
+     * True when the process was killed because it exceeded `timeoutMs`. A
+     * SIGKILLed child can still close with exit code 0; callers MUST treat
+     * a timed-out phase as a hard failure regardless of `exitCode`, never
+     * as a pass. `undefined`/`false` means the process completed on its own.
+     */
+    killedByTimeout?: boolean;
+    /**
+     * True when captured stdout/stderr hit `maxOutputBytes` and further
+     * output was dropped. The result is still returned (the process was
+     * not killed for this), but downstream parsers see truncated text.
+     */
+    outputTruncated?: boolean;
 }
-interface SandboxDriver {
+export interface SandboxDriver {
     id: string;
     exec(phase: SandboxResult['phase'], command: string, config: HarnessConfig): Promise<SandboxResult>;
 }
 /** Vitest default summary line: "Tests  X passed | Y failed". */
-declare const vitestTestParser: TestOutputParser;
+export declare const vitestTestParser: TestOutputParser;
 /** Pytest default: "collected N items" + " X passed, Y failed". */
-declare const pytestTestParser: TestOutputParser;
+export declare const pytestTestParser: TestOutputParser;
 /** Jest: "Tests: X passed, Y total" (and optional failed). */
-declare const jestTestParser: TestOutputParser;
+export declare const jestTestParser: TestOutputParser;
 /** Composite parser — tries a list of parsers in order. */
-declare function composeParsers(...parsers: TestOutputParser[]): TestOutputParser;
-interface SubprocessSandboxDriverOptions {
+export declare function composeParsers(...parsers: TestOutputParser[]): TestOutputParser;
+export interface SubprocessSandboxDriverOptions {
     /**
      * Default cwd for all `exec` calls. Used when the per-call `HarnessConfig`
      * does not set its own `cwd`. Lets callers bind the driver to a working
@@ -78,18 +93,18 @@ interface SubprocessSandboxDriverOptions {
      */
     env?: Record<string, string>;
 }
-declare class SubprocessSandboxDriver implements SandboxDriver {
+export declare class SubprocessSandboxDriver implements SandboxDriver {
     id: string;
     private defaultCwd?;
     private defaultEnv?;
     constructor(options?: SubprocessSandboxDriverOptions);
     exec(phase: SandboxResult['phase'], command: string, config: HarnessConfig): Promise<SandboxResult>;
 }
-declare class DockerSandboxDriver implements SandboxDriver {
+export declare class DockerSandboxDriver implements SandboxDriver {
     id: string;
     exec(phase: SandboxResult['phase'], command: string, config: HarnessConfig): Promise<SandboxResult>;
 }
-interface SandboxHarnessResult {
+export interface SandboxHarnessResult {
     passed: boolean;
     setup?: SandboxResult;
     run?: SandboxResult;
@@ -98,50 +113,9 @@ interface SandboxHarnessResult {
     /** Final score — 0 when no tests; otherwise testsPassed/testsTotal. */
     score: number;
 }
-declare class SandboxHarness {
+export declare class SandboxHarness {
     private driver;
     constructor(driver?: SandboxDriver);
     run(config: HarnessConfig, emitter: TraceEmitter): Promise<SandboxHarnessResult>;
 }
-
-/**
- * TestGradedScenario — a scenario whose score comes from a test suite.
- *
- * This is the SWE-bench pattern generalized. The scenario ships:
- *   - fixture data (setup instructions)
- *   - a test command the harness runs
- *   - optional assertion overrides
- *
- * The runner emits a run, delegates to SandboxHarness, records the
- * outcome, and returns a structured verdict. Consumers bind their own
- * agent execution to this contract.
- */
-
-interface TestGradedScenario {
-    id: string;
-    description?: string;
-    harness: HarnessConfig;
-    /** Optional pass threshold in 0..1 (default 1.0 = all tests must pass). */
-    passThreshold?: number;
-    /** Provenance for dataset tracking. */
-    datasetVersion?: string;
-    /** Free-form tags (difficulty, category, etc.). */
-    tags?: Record<string, string>;
-}
-interface TestGradedRunOptions {
-    variantId?: string;
-    driver?: SandboxDriver;
-    /** Metadata recorded on the Run (codeSha, promptSha, modelFingerprint, seed). */
-    provenance?: Pick<Run, 'codeSha' | 'promptSha' | 'modelFingerprint' | 'seed' | 'envFingerprint'>;
-}
-interface TestGradedRunResult {
-    runId: string;
-    scenario: TestGradedScenario;
-    harness: SandboxHarnessResult;
-    pass: boolean;
-    score: number;
-    failureClass?: FailureClass;
-}
-declare function runTestGradedScenario(scenario: TestGradedScenario, store: TraceStore, options?: TestGradedRunOptions): Promise<TestGradedRunResult>;
-
-export { DockerSandboxDriver as D, type HarnessConfig as H, type SandboxDriver as S, type TestGradedScenario as T, type SandboxHarnessResult as a, type TestGradedRunResult as b, SandboxHarness as c, type SandboxResult as d, SubprocessSandboxDriver as e, type SubprocessSandboxDriverOptions as f, type TestGradedRunOptions as g, type TestOutputParser as h, composeParsers as i, jestTestParser as j, pytestTestParser as p, runTestGradedScenario as r, vitestTestParser as v };
+//# sourceMappingURL=sandbox-harness.d.ts.map

package/dist/sandbox-harness.d.ts.map

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

package/dist/sandbox-harness.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandbox-harness.test.d.ts.map

package/dist/sandbox-harness.test.d.ts.map

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

package/dist/sandbox-pool.d.ts

@@ -0,0 +1,74 @@
+/**
+ * SandboxPool — bounded checkout/release pool for mutation slots.
+ *
+ * The composite-mutator's `code` channel needs an isolated workspace per
+ * mutation attempt: a git worktree, a sandbox container, a tmpdir clone —
+ * whatever the consumer's runtime is. Without a pool, every consumer
+ * re-implements the same machinery (mint N slots, check one out per
+ * mutation, reset before reuse, drain at the end, track utilisation for
+ * the cost ledger). This primitive ships that machinery so consumers
+ * supply only a `SlotFactory`.
+ *
+ * Generic over a slot resource `T` so the same pool serves git worktrees
+ * (T = path), Tangle sandboxes (T = SandboxBox), or anything else with
+ * the create/reset/destroy lifecycle.
+ *
+ * Concurrency: FIFO via the shared `Mutex` primitive. Each `checkout()`
+ * either takes an idle slot or queues until one is released. Lifecycle
+ * is single-process — multi-process pools need external coordination
+ * (file locks, etc.) and are deliberately out of scope.
+ */
+export interface PoolSlot<T> {
+    /** Stable id assigned at slot creation. Use for telemetry / lineage. */
+    readonly id: string;
+    /** Consumer-defined resource. */
+    readonly resource: T;
+}
+export interface SlotFactory<T> {
+    /** Build a new slot. Called lazily as the pool grows up to `size`. */
+    create(slotId: string): Promise<T>;
+    /**
+     * Reset a slot to a clean state before reuse. Called BEFORE every
+     * checkout returns it (including the first — so the factory's
+     * `create` can leave the slot dirty and let `reset` normalise).
+     * Optional; default is a no-op.
+     */
+    reset?(slot: PoolSlot<T>): Promise<void>;
+    /** Tear the slot down. Called by `drain()`. */
+    destroy(slot: PoolSlot<T>): Promise<void>;
+}
+export interface SandboxPool<T> {
+    /**
+     * Take a slot. If all slots are busy, the promise resolves when one
+     * is released. Always pair with the returned `release` (or wrap with
+     * `withSlot`).
+     */
+    checkout(): Promise<{
+        slot: PoolSlot<T>;
+        release: () => void;
+    }>;
+    /**
+     * Run `fn` with a checked-out slot, releasing on completion or throw.
+     * The convenience wrapper most callers should use.
+     */
+    withSlot<R>(fn: (slot: PoolSlot<T>) => Promise<R>): Promise<R>;
+    /** Destroy every slot. Idempotent. */
+    drain(): Promise<void>;
+    /** How many slots have been minted (≤ `size`). */
+    poolSize(): number;
+    /** How many checkouts are currently outstanding. */
+    activeCheckouts(): number;
+    /** Snapshot of busy/total durations for the cost ledger. */
+    utilization(): {
+        busyMs: number;
+        totalMs: number;
+        checkouts: number;
+    };
+}
+export interface CreateSandboxPoolOpts<T> {
+    /** Maximum concurrent slots. Slots are minted on first need, not eagerly. */
+    size: number;
+    factory: SlotFactory<T>;
+}
+export declare function createSandboxPool<T>(opts: CreateSandboxPoolOpts<T>): SandboxPool<T>;
+//# sourceMappingURL=sandbox-pool.d.ts.map

package/dist/sandbox-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-pool.d.ts","sourceRoot":"","sources":["../src/sandbox-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;CACrB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,sEAAsE;IACtE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAClC;;;;;OAKG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,+CAA+C;IAC/C,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAC/D;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC9D,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,kDAAkD;IAClD,QAAQ,IAAI,MAAM,CAAA;IAClB,oDAAoD;IACpD,eAAe,IAAI,MAAM,CAAA;IACzB,4DAA4D;IAC5D,WAAW,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CACtE;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CACxB;AAOD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAyMnF"}

package/dist/sandbox-pool.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandbox-pool.test.d.ts.map

package/dist/sandbox-pool.test.d.ts.map

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