@tangle-network/agent-eval 0.115.2 → 0.116.0

package/dist/policy-edit-Clb2v6Oa.d.ts

@@ -0,0 +1,708 @@
+import { R as RunRecord, A as AgentProfileCell, f as AgentProfileJson } from './run-record-CZmcpWPo.js';
+import { A as AgentEvalError, C as CaptureIntegrityError, V as ValidationError } from './errors-oeQrLqXC.js';
+import { R as RawProviderSink, P as ProviderRedactor, T as TraceAnalysisStore } from './store-9cAScOcb.js';
+import { a as JudgeInput } from './types-C7DGg5ex.js';
+
+/**
+ * LLM client with graceful degrade.
+ *
+ * OpenAI-compatible `/v1/chat/completions` client with:
+ *   - Exponential-backoff retry on 429 + 5xx gateway errors (502/503/504).
+ *   - Retry on transient network errors (fetch failed, AbortError, ECONNRESET).
+ *   - Graceful json_schema → json_object degrade on 400 with schema-reject body.
+ *   - Fenced-JSON stripping (```json ... ```) for models that wrap structured output.
+ *   - Configurable base URL + api key / bearer, works with LiteLLM proxies, OpenAI
+ *     directly, cli-bridge subscriptions, and any router that speaks the spec.
+ *
+ * Usage:
+ *   const { value, result } = await callLlmJson<MyType>(
+ *     { model: 'gpt-4o', messages: [...], jsonSchema: { name: 'x', schema: {...} } },
+ *     { baseUrl: 'https://router.tangle.tools/v1', apiKey: process.env.KEY },
+ *   )
+ *
+ * This is THE llm-calling seam for agent-eval primitives that need structured
+ * output (semantic concept judge, reviewer directives, critic scores). Primitives
+ * that need free-form text use `callLlm` and parse output themselves.
+ */
+
+interface LlmMessage {
+    role: 'system' | 'user' | 'assistant';
+    /**
+     * Either a plain text content string OR a multimodal content array
+     * (text + image_url parts) for vision-capable models.
+     */
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image_url';
+        image_url: {
+            url: string;
+            detail?: 'auto' | 'low' | 'high';
+        };
+    }>;
+}
+interface LlmCallRequest {
+    model: string;
+    messages: LlmMessage[];
+    /** Optional JSON-mode response format (response_format: json_object). */
+    jsonMode?: boolean;
+    /** Optional structured output via JSON Schema. Falls back to json_object on 400. */
+    jsonSchema?: {
+        name: string;
+        schema: Record<string, unknown>;
+    };
+    temperature?: number;
+    maxTokens?: number;
+    /** Per-call timeout, default 300s. */
+    timeoutMs?: number;
+}
+interface LlmUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** Proxies populate this when prompt caching is on. */
+    cachedPromptTokens?: number;
+}
+interface LlmCallResult {
+    /** The text content of the first choice. Empty string if none. */
+    content: string;
+    usage: LlmUsage;
+    /**
+     * Cost in USD. Pulled from proxy's `_response_cost` field when present;
+     * `null` when neither the proxy nor the caller can derive it.
+     */
+    costUsd: number | null;
+    /** Model name actually used (echoed from response). */
+    model: string;
+    /** Wall-clock duration of the HTTP call (last attempt, if retried). */
+    durationMs: number;
+    /**
+     * `finish_reason` echoed from the first choice (`stop`, `length`,
+     * `content_filter`, `tool_calls`, ...). `null` when the provider omits it.
+     * Exposed so a free-form `callLlm` caller CAN detect a truncated answer
+     * (`length`) instead of treating a cut-off completion as complete. Note:
+     * `callLlm` does not itself reject on it — acting on this signal is the
+     * caller's responsibility (in-repo free-form drivers do not yet enforce it).
+     */
+    finishReason?: string | null;
+    /**
+     * True when `content.trim()` is empty. An empty completion is a silent zero
+     * for free-form `callLlm` callers; this flag is the signal a caller can
+     * inspect to fail loud rather than proceed on an empty string. `callLlm`
+     * surfaces it but does not throw on it.
+     */
+    contentEmpty?: boolean;
+    /** Raw response body. */
+    raw: Record<string, unknown>;
+}
+declare class LlmCallError extends AgentEvalError {
+    readonly status: number;
+    readonly body: string;
+    readonly model: string;
+    constructor(message: string, status: number, body: string, model: string);
+}
+interface LlmClientOptions {
+    /** Base URL (without trailing slash). Must end at the `/v1` prefix. */
+    baseUrl?: string;
+    /** Bearer token — either `apiKey` or `bearer` populates `Authorization: Bearer ...`. */
+    apiKey?: string;
+    bearer?: string;
+    /** Override for the `Authorization` header (e.g. `X-Auth: ...`). Takes precedence over apiKey/bearer. */
+    authHeader?: {
+        name: string;
+        value: string;
+    };
+    /** Default timeout in ms. Per-call can override. */
+    defaultTimeoutMs?: number;
+    /**
+     * Caller-supplied abort signal — e.g. a campaign-wide cancel. Linked to
+     * each attempt's per-attempt timeout controller, so aborting it cancels
+     * the in-flight fetch. A caller abort is FATAL: it is not retried even
+     * though an AbortError otherwise matches the transient patterns.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cross-attempt wall-clock budget in ms, measured from the first attempt.
+     * Before launching each attempt the loop checks the remaining budget and
+     * stops retrying once it is exhausted, rather than waiting the full
+     * per-attempt timeout on every retry. Bounds total time independent of
+     * `maxRetries` × `timeoutMs`.
+     */
+    deadlineMs?: number;
+    /** Max retry attempts on retriable errors. Default 3 (1 initial + 2 retries). */
+    maxRetries?: number;
+    /** Fetch implementation — defaults to global `fetch`. Override for custom transport (e.g. tests). */
+    fetch?: typeof fetch;
+    /**
+     * Optional raw HTTP capture sink. When provided, every request, response,
+     * and error (across all retry attempts) is recorded to the sink, with auth
+     * headers and credential-shaped body fields redacted by default. This is
+     * the layer-1 forensics primitive: structured `LlmSpan`s record intent,
+     * raw events record what actually crossed the wire.
+     */
+    rawSink?: RawProviderSink;
+    /**
+     * Logical provider id attached to raw events. When omitted, derived from
+     * `baseUrl` via `providerFromBaseUrl`.
+     */
+    provider?: string;
+    /** Trace context attached to raw events; populated by emitter-aware callers. */
+    traceContext?: {
+        runId?: string;
+        spanId?: string;
+    };
+    /** Override the redaction strategy for this call. Defaults to `defaultProviderRedactor`. */
+    redactor?: ProviderRedactor;
+}
+/**
+ * True when an error is a transient transport/network fault worth retrying,
+ * as opposed to a deterministic failure (4xx schema reject, JSON parse) that
+ * a retry cannot fix. Inspects `LlmCallError.status`, then the error's
+ * name/message/code, then recurses into `error.cause` — undici nests the
+ * real socket fault one or more levels under `.cause`.
+ *
+ * This is THE retry classifier for the package: `callLlm` and
+ * `withJudgeRetry` both route through it, so a connection-class error is
+ * treated identically whether it surfaces in the HTTP client or a
+ * TCloud-backed judge.
+ */
+declare function isTransientLlmError(err: unknown): boolean;
+/** Exponential backoff: 500ms, 1s, 2s, 4s, ... capped at 16s. Attempt is 0-indexed. */
+declare function backoffMs(attempt: number): number;
+/**
+ * Strip a ```json / ``` code fence if the model emitted one.
+ * Idempotent for naked JSON. Some models (claude-code via router, certain
+ * deepseek models) wrap output even under json_object.
+ */
+declare function stripFencedJson(raw: string): string;
+/**
+ * Low-level call. Returns raw content + usage + cost. Retries on transient
+ * failures; does NOT degrade schema here — callers that want graceful
+ * degrade use `callLlmJson`.
+ */
+declare function callLlm(req: LlmCallRequest, opts?: LlmClientOptions): Promise<LlmCallResult>;
+/**
+ * Structured-output call. Returns parsed JSON plus the raw result envelope.
+ * Degrades `jsonSchema` → `jsonMode` on a 400 that names the schema param —
+ * critical for deepseek-v3/v4, kimi-k2.6, and other models that don't accept
+ * the `response_format.json_schema` shape but DO accept `json_object`.
+ */
+declare function callLlmJson<T = unknown>(req: LlmCallRequest, opts?: LlmClientOptions): Promise<{
+    value: T;
+    result: LlmCallResult;
+}>;
+type LlmRouteAssertionReason = 'no_explicit_base_url' | 'base_url_blocked' | 'base_url_not_allowed' | 'no_auth' | 'wrong_provider';
+declare class LlmRouteAssertionError extends CaptureIntegrityError {
+    readonly reason: LlmRouteAssertionReason;
+    readonly baseUrl: string;
+    constructor(message: string, reason: LlmRouteAssertionReason, baseUrl: string);
+}
+interface LlmRouteRequirements {
+    /**
+     * Throw if `opts.baseUrl` is undefined, i.e. the call would fall back to
+     * `DEFAULT_BASE_URL`. Set this for evaluation runs where silently using
+     * the public/free-tier router is a defect — the launch reviewer needs to
+     * know exactly which provider answered.
+     */
+    requireExplicitBaseUrl?: boolean;
+    /**
+     * Allowlist of acceptable base URLs. Strings match by prefix
+     * (case-insensitive); RegExps test against the full base URL.
+     */
+    allowedBaseUrls?: Array<string | RegExp>;
+    /** Blocklist that takes precedence over `allowedBaseUrls`. */
+    blockedBaseUrls?: Array<string | RegExp>;
+    /** Throw if no auth header / api key is configured. */
+    requireAuth?: boolean;
+    /**
+     * Logical provider id the configured `baseUrl` is expected to match (via
+     * `providerFromBaseUrl`). Mainly useful when paired with `requireExplicitBaseUrl`.
+     */
+    expectedProvider?: string;
+}
+/**
+ * Fail-loud assertion that the configured LLM client points at the route
+ * the caller intends. Designed for the matrix-runner preflight: invoke
+ * once before any LLM call to catch misconfiguration before a sweep burns
+ * dollars on the wrong provider.
+ *
+ * Throws `LlmRouteAssertionError`. Pure — no I/O — so it's safe to call
+ * from constructors and CI gates.
+ */
+declare function assertLlmRoute(opts: LlmClientOptions, req?: LlmRouteRequirements): void;
+/**
+ * Probe whether a model is reachable. Returns latency + null error on
+ * success; `ok=false` + error message on any failure (HTTP, timeout,
+ * network, parse). Designed for sweep preflights — fail loud at the
+ * boundary before burning a 30-leaf run on a misconfigured router.
+ *
+ * Sends a tiny `ping` message with `maxTokens=64`. Reasoning models
+ * (glm-5.1, deepseek-v4) can burn the entire budget on internal reasoning
+ * for short prompts, so don't tighten this further. We don't validate
+ * content; HTTP 200 means reachable.
+ */
+declare function probeLlm(model: string, opts?: LlmClientOptions & {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    latencyMs: number;
+    error: string | null;
+}>;
+/**
+ * Stateful client — construct once with defaults, call many times.
+ * Thin wrapper around the free functions; exists for callers that want
+ * to inject a single configured instance into multiple primitives.
+ */
+declare class LlmClient {
+    private readonly opts;
+    constructor(opts?: LlmClientOptions);
+    call(req: LlmCallRequest, per?: LlmClientOptions): Promise<LlmCallResult>;
+    callJson<T = unknown>(req: LlmCallRequest, per?: LlmClientOptions): Promise<{
+        value: T;
+        result: LlmCallResult;
+    }>;
+}
+
+/**
+ * ChatClient — the single LLM abstraction analysts call.
+ *
+ * agent-eval already ships an `LlmClient` (OpenAI-compatible, retry,
+ * graceful JSON-schema degrade) and judges that talk to `TCloud`. Two
+ * mixed patterns force every analyst author to pick a transport, which
+ * couples analyst code to runtime concerns (cli-bridge vs router vs
+ * sandbox-sdk) it shouldn't know about.
+ *
+ * `ChatClient` is one interface every analyst takes via `AnalystContext.chat`.
+ * The operator decides at the registry boundary which transport binds
+ * to it. Analyst code stays transport-agnostic; swapping production
+ * (sandbox-sdk) for local dev (cli-bridge) or tests (mock) is a one-
+ * line factory call.
+ *
+ * Designed to coexist: existing `LlmClient` callers and existing
+ * `TCloud`-based judges keep working untouched. New analyst code uses
+ * `ChatClient`. When old call sites migrate, they pick up budgeting,
+ * cancellation, and unified telemetry for free.
+ */
+
+/**
+ * Unified chat interface. Mirrors LlmCallRequest/Result so the OpenAI-
+ * compatible mental model stays. Two methods: a one-shot `chat()` and
+ * an `streamChat()` for future agentic loops (not yet exposed).
+ */
+interface ChatClient {
+    /** Display name of the bound transport — included in telemetry. */
+    readonly transport: ChatTransport;
+    /** Default model when caller omits — operators bind this per environment. */
+    readonly defaultModel?: string;
+    chat(req: ChatRequest, opts?: ChatCallOpts): Promise<ChatResponse>;
+}
+type ChatTransport = 'router' | 'sandbox-sdk' | 'cli-bridge' | 'direct-provider' | 'mock';
+interface ChatRequest extends Omit<LlmCallRequest, 'model'> {
+    /** Optional — falls back to ChatClient.defaultModel. */
+    model?: string;
+}
+type ChatResponse = LlmCallResult;
+interface ChatCallOpts {
+    /** Cancel the in-flight request. */
+    signal?: AbortSignal;
+    /** Hard USD ceiling for this single call (informational; the underlying transport may not enforce). */
+    maxCostUsd?: number;
+    /** Correlation tag carried into request headers when the transport allows. */
+    correlationId?: string;
+}
+type CreateChatClientOpts = RouterTransportOpts | CliBridgeTransportOpts | DirectProviderTransportOpts | SandboxSdkTransportOpts | MockTransportOpts;
+interface BaseTransportOpts {
+    defaultModel?: string;
+}
+interface RouterTransportOpts extends BaseTransportOpts {
+    transport: 'router';
+    baseUrl?: string;
+    apiKey: string;
+}
+interface CliBridgeTransportOpts extends BaseTransportOpts {
+    transport: 'cli-bridge';
+    baseUrl?: string;
+    bearer?: string;
+}
+interface DirectProviderTransportOpts extends BaseTransportOpts {
+    transport: 'direct-provider';
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * Sandbox-SDK transport. Provided as a thin pass-through: the caller
+ * supplies a callable that mimics LlmClient.chat() against an already-
+ * configured Sandbox handle. We don't import the SDK here to keep
+ * agent-eval dep-free of @tangle-network/sandbox.
+ */
+interface SandboxSdkTransportOpts extends BaseTransportOpts {
+    transport: 'sandbox-sdk';
+    chat: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Mock transport for tests. The handler receives the request and returns
+ * whatever the test wants. No retries, no JSON-schema degrade.
+ */
+interface MockTransportOpts extends BaseTransportOpts {
+    transport: 'mock';
+    handler: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Build a ChatClient bound to a specific transport. The returned client
+ * is safe to share across analysts in a single registry run.
+ */
+declare function createChatClient(opts: CreateChatClientOpts): ChatClient;
+
+/**
+ * Analyst contract — the missing orchestration layer over agent-eval's
+ * existing analyzers (analyzeTraces, MultiLayerVerifier, RunCritic,
+ * SemanticConceptJudge, JudgeFn, ...).
+ *
+ * Each existing primitive returns its own output shape. The Analyst
+ * contract is the single envelope every primitive lifts into, so a
+ * registry can run N analysts against a run and a single renderer can
+ * compose findings without knowing which analyzer produced them.
+ *
+ * The contract is intentionally domain-agnostic: nothing here knows
+ * about code, voice, RAG, or any particular agent stack. Analysts
+ * declare what INPUT KIND they need (a trace store, an artifact dir,
+ * a RunRecord, a JudgeInput, or `custom`), and the registry routes
+ * the matching input from `AnalystRunInputs`.
+ */
+
+/**
+ * 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;
+    /** FIREWALL provenance (docs/learning-flywheel.md): true iff this finding was
+     *  lifted from a JUDGE verdict (an acceptance score), not OBSERVED from the
+     *  agent's behavior. A judge-derived finding must NEVER be admitted as a
+     *  steering input — that is the held-out judge leaking into the loop. Set at
+     *  the lift site (createJudgeAdapter); checked by `assertNoJudgeVerdict`.
+     *  Provenance, not evidence presence, is the correct discriminator: an
+     *  evidence-less trace-analyst observation legitimately steers, while a judge
+     *  verdict that happens to cite an artifact must not. */
+    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';
+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[];
+}
+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;
+    /** Wall-clock deadline (epoch ms). Analysts SHOULD honor for graceful cancel. */
+    deadlineMs?: number;
+    /** Per-analyst USD budget. Analysts MAY check before issuing LLM calls. */
+    budgetUsd?: number;
+    /**
+     * 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>;
+    /** 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[]>;
+}
+/**
+ * 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;
+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;
+    cost_usd: number;
+    /** 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;
+}
+/**
+ * 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;
+};
+
+type PolicyEditSchemaVersion = 'policy-edit/v1';
+declare const POLICY_EDIT_AXES: readonly ["carrier", "representation", "budget", "sampling", "output_contract", "tool_contract", "routing", "memory", "agent_profile", "deployment_target"];
+type PolicyEditAxis = (typeof POLICY_EDIT_AXES)[number];
+declare const POLICY_EDIT_TARGET_SURFACES: readonly ["prompt", "tool-contract", "runtime-config", "memory", "agent-profile", "code", "deployment"];
+type PolicyEditTargetSurface = (typeof POLICY_EDIT_TARGET_SURFACES)[number];
+type PolicyEditRisk = 'low' | 'medium' | 'high' | 'unknown';
+type PolicyEditGainDirection = 'increase' | 'decrease';
+type PolicyEditGainUnit = 'absolute' | 'relative' | 'percent' | 'score';
+interface PolicyEditTarget {
+    surface: PolicyEditTargetSurface;
+    /** Stable path inside the target surface, for example `system-prompt:tools`
+     * or `budget.maxTurns`. */
+    path?: string;
+    /** Optional canonical deployment identity. Store the existing cell, not a
+     * local profile shape. */
+    agentProfileCell?: AgentProfileCell;
+    /** Human label when the path is not enough for a readable audit trail. */
+    label?: string;
+}
+type PolicyEditChange = {
+    kind: 'text';
+    mode: 'append' | 'prepend' | 'replace';
+    value: string;
+    /** Required when `mode === 'replace'`; exact match only. */
+    find?: string;
+} | {
+    kind: 'json';
+    mode: 'set' | 'merge' | 'remove';
+    path: string;
+    value?: AgentProfileJson;
+};
+interface PolicyEditExpectedGain {
+    /** Metric this edit is expected to move, e.g. `holdout.composite`. */
+    metric: string;
+    direction: PolicyEditGainDirection;
+    /** Positive magnitude in the metric's native units. */
+    amount: number;
+    unit?: PolicyEditGainUnit;
+    rationale?: string;
+}
+interface PolicyEditSource {
+    findingIds: string[];
+    analystIds: string[];
+    evidenceRefs: EvidenceRef[];
+    /** Mirrors `AnalystFinding.derived_from_judge`; admission rejects it. */
+    derivedFromJudge?: boolean;
+}
+interface PolicyEdit {
+    schemaVersion: PolicyEditSchemaVersion;
+    editId: string;
+    axis: PolicyEditAxis;
+    target: PolicyEditTarget;
+    change: PolicyEditChange;
+    claim: string;
+    expectedGain: PolicyEditExpectedGain;
+    confidence: number;
+    risk: PolicyEditRisk;
+    source: PolicyEditSource;
+    rationale?: string;
+    validationPlan?: string;
+    metadata?: Record<string, unknown>;
+}
+declare const POLICY_EDIT_CANDIDATE_RECORD_SCHEMA: "tangle.policy-edit-candidate.v1";
+/** JSON-safe attribution carried with a measured candidate and its scores. */
+interface PolicyEditCandidateRecord {
+    schema: typeof POLICY_EDIT_CANDIDATE_RECORD_SCHEMA;
+    policyEdit: PolicyEdit;
+}
+type PolicyEditInit = Omit<PolicyEdit, 'schemaVersion' | 'editId'> & {
+    schemaVersion?: PolicyEditSchemaVersion;
+    editId?: string;
+};
+declare class PolicyEditValidationError extends ValidationError {
+    readonly path: string;
+    constructor(message: string, path?: string);
+}
+interface FindingToPolicyEditOptions {
+    expectedGain?: PolicyEditExpectedGain | ((finding: AnalystFinding) => PolicyEditExpectedGain | null | undefined);
+    risk?: PolicyEditRisk | ((finding: AnalystFinding) => PolicyEditRisk);
+    defaultAxis?: PolicyEditAxis;
+    defaultTargetSurface?: PolicyEditTargetSurface;
+}
+interface PolicyEditAdmissionOptions {
+    minScore?: number;
+    minExpectedGain?: number;
+    allowHighRisk?: boolean;
+    requireEvidence?: boolean;
+}
+interface PolicyEditAdmission {
+    edit: PolicyEdit;
+    decision: 'admit' | 'reject';
+    score: number;
+    reasons: string[];
+}
+declare function makePolicyEdit(init: PolicyEditInit): PolicyEdit;
+declare function computePolicyEditId(edit: Omit<PolicyEdit, 'editId'> | PolicyEdit): string;
+declare function validatePolicyEdit(input: unknown): PolicyEdit;
+declare function makePolicyEditCandidateRecord(edit: PolicyEdit): PolicyEditCandidateRecord;
+declare function validatePolicyEditCandidateRecord(input: unknown): PolicyEditCandidateRecord;
+declare function isPolicyEdit(input: unknown): input is PolicyEdit;
+declare function policyEditsFromFindings(findings: ReadonlyArray<AnalystFinding>, opts?: FindingToPolicyEditOptions): PolicyEdit[];
+declare function policyEditFromFinding(finding: AnalystFinding, opts?: FindingToPolicyEditOptions): PolicyEdit | null;
+declare function scorePolicyEditReadiness(edit: PolicyEdit, opts?: PolicyEditAdmissionOptions): number;
+declare function admitPolicyEdit(edit: PolicyEdit, opts?: PolicyEditAdmissionOptions): PolicyEditAdmission;
+declare function applyPolicyEditToSurface(surface: unknown, edit: PolicyEdit): unknown;
+
+export { makePolicyEditCandidateRecord as $, type Analyst as A, type PolicyEditGainDirection as B, type ChatClient as C, type DirectProviderTransportOpts as D, type EvidenceRef as E, type FindingToPolicyEditOptions as F, type PolicyEditGainUnit as G, type PolicyEditInit as H, type PolicyEditRisk as I, type PolicyEditSchemaVersion as J, type PolicyEditSource as K, type LlmClientOptions as L, type MockTransportOpts as M, type PolicyEditTarget as N, type PolicyEditTargetSurface as O, type PolicyEditCandidateRecord as P, PolicyEditValidationError as Q, type RouterTransportOpts as R, type SandboxSdkTransportOpts as S, admitPolicyEdit as T, applyPolicyEditToSurface as U, computeFindingId as V, computePolicyEditId as W, createChatClient as X, isPolicyEdit as Y, makeFinding as Z, makePolicyEdit as _, type LlmRouteRequirements as a, policyEditFromFinding as a0, policyEditsFromFindings as a1, scorePolicyEditReadiness as a2, validatePolicyEdit as a3, validatePolicyEditCandidateRecord as a4, LlmCallError as a5, type LlmCallRequest as a6, type LlmCallResult as a7, LlmClient as a8, type LlmMessage as a9, LlmRouteAssertionError as aa, type LlmUsage as ab, assertLlmRoute as ac, backoffMs as ad, callLlm as ae, callLlmJson as af, isTransientLlmError as ag, probeLlm as ah, stripFencedJson as ai, type AnalystContext as b, type AnalystRunSummary as c, type AnalystFinding as d, type AnalystRunResult as e, type AnalystRunInputs as f, type AnalystRunEvent as g, type AnalystCost as h, type AnalystSeverity as i, type AnalystInputKind as j, type AnalystRequirements as k, type ChatCallOpts as l, type ChatRequest as m, type ChatResponse as n, type ChatTransport as o, type CliBridgeTransportOpts as p, type CreateChatClientOpts as q, POLICY_EDIT_AXES as r, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA as s, POLICY_EDIT_TARGET_SURFACES as t, type PolicyEdit as u, type PolicyEditAdmission as v, type PolicyEditAdmissionOptions as w, type PolicyEditAxis as x, type PolicyEditChange as y, type PolicyEditExpectedGain as z };