@tangle-network/agent-runtime 0.8.0 → 0.11.0

package/README.md

@@ -15,8 +15,8 @@ pnpm add @tangle-network/agent-runtime @tangle-network/agent-eval
 |---|---|
 | `runAgentTask` | Single-shot adapter-driven task with eval/verification |
 | `runAgentTaskStream` | Streaming product loop with session resume + backends |
-| `startRuntimeRun` | Canonical production-run row + cost ledger (NEW in 0.7.0) |
-| `createTraceBridge` | Map `RuntimeStreamEvent` → `agent-eval` `TraceEvent` (NEW in 0.7.0) |
+| `startRuntimeRun` | Canonical production-run row + cost ledger |
+| `createTraceBridge` | Map `RuntimeStreamEvent` → `agent-eval` `TraceEvent` |
 | `decideKnowledgeReadiness` | `ready` / `blocked` / `caveat` branch for routes / UI |
 | `createOpenAICompatibleBackend` | OpenAI-compatible streaming backend (TCloud / cli-bridge) |
 | `createSandboxPromptBackend` | Sandbox / sidecar `streamPrompt` clients |
@@ -50,13 +50,11 @@ const result = await runAgentTask({
 console.log(result.status, result.runRecords)
 ```
 
-## Canonical production-run lifecycle (NEW in 0.7.0)
+## Canonical production-run lifecycle
 
-`startRuntimeRun` is the ONE abstraction for "the agent did a thing on
-behalf of a customer; record what it did, what it cost, how it ended."
-Replaces bespoke `agentRuns`-row helpers (legal-agent's
-`completeProductionAgentRun` + `persistRuntimeRun` pair is the canonical
-example of what this subsumes).
+`startRuntimeRun` records what the agent did on behalf of a customer,
+what it cost, and how it ended. Replaces bespoke `agentRuns`-row helpers
+across consumer repos with a single contract.
 
 ```ts
 import { startRuntimeRun, runAgentTaskStream } from '@tangle-network/agent-runtime'
@@ -87,11 +85,11 @@ console.log(run.cost()) // { tokensIn, tokensOut, costUsd, wallMs, llmCalls }
 
 Full runnable: [`examples/runtime-run/`](./examples/runtime-run/).
 
-## agent-eval trace bridge (NEW in 0.7.0)
+## agent-eval trace bridge
 
-If you persist traces in agent-eval's `TraceStore`, map runtime stream
-events to `TraceEvent` once and stop hand-rolling the adapter in every
-domain repo:
+If you persist traces in agent-eval's `TraceStore`, the bridge maps
+runtime stream events to `TraceEvent` so consumer repos don't hand-roll
+the adapter:
 
 ```ts
 import { createTraceBridge } from '@tangle-network/agent-runtime'
@@ -146,10 +144,41 @@ details. Private diagnostics opt-in via `RuntimeTelemetryOptions`.
 | Package | Owns |
 |---|---|
 | `agent-runtime` | Lifecycle, adapters, backends, `RuntimeRunHandle`, trace bridge |
+| `agent-runtime/platform` | Server-side clients for the Tangle platform: cross-site SSO (`PlatformAuthClient`) and integrations hub (`PlatformHubClient`) |
 | `agent-eval` | Control loops, readiness scoring, traces, evals, failure classes, release evidence |
 | `agent-knowledge` | Evidence, claims, wiki pages, retrieval, knowledge bundle builders |
 | Domain packages | Domain tools, policies, credentials, UI text, rubrics |
 
+### `agent-runtime/platform` — Login with Tangle + integrations hub
+
+```ts
+import {
+  PlatformAuthClient,
+  PlatformHubClient,
+} from '@tangle-network/agent-runtime/platform'
+
+// Login with Tangle (cross-site SSO bridge).
+const auth = new PlatformAuthClient({
+  baseUrl: process.env.TANGLE_PLATFORM_URL!, // https://id.tangle.tools
+  appId: 'gtm-agent',                        // must be registered in TRUSTED_APPS
+})
+const url = auth.authorizeUrl({ state: csrfToken, redirectUri: callbackUrl })
+// …user redirected to `url`, returns to callbackUrl with ?code=…
+const { apiKey, user } = await auth.exchange(code)
+
+// Integrations hub (uses the user's apiKey from cross-site exchange).
+const hub = new PlatformHubClient({
+  baseUrl: process.env.TANGLE_PLATFORM_URL!,
+  bearer: apiKey,
+})
+const connections = await hub.listConnections()
+const { authorizationUrl } = await hub.startAuth({
+  providerId: 'google',
+  connectorId: 'gmail',
+  returnUrl: 'https://gtm.tangle.tools/integrations',
+})
+```
+
 The API uses `runAgentTask`, not `runVerticalAgentTask`. `domain` is
 metadata on the task because the runtime is reusable across many kinds of
 agents without baking taxonomy into type names.
@@ -165,4 +194,4 @@ Runnable in [`examples/`](./examples/):
 - [`sse-stream/`](./examples/sse-stream/) — Server-Sent Events for browser clients
 - [`sandbox-stream-backend/`](./examples/sandbox-stream-backend/) — `createSandboxPromptBackend`
 - [`openai-stream-backend/`](./examples/openai-stream-backend/) — `createOpenAICompatibleBackend`
-- [`runtime-run/`](./examples/runtime-run/) — `startRuntimeRun` + cost ledger + persistence adapter (NEW)
+- [`runtime-run/`](./examples/runtime-run/) — `startRuntimeRun` + cost ledger + persistence adapter

package/dist/agent.d.ts

@@ -0,0 +1,537 @@
+import * as _tangle_network_agent_eval from '@tangle-network/agent-eval';
+import { FindingSubject, TraceAnalystKindSpec, AnalystFinding } from '@tangle-network/agent-eval';
+import { I as ImprovementAdapter, K as KnowledgeAdapter, a as RunAnalystLoopResult } from './types-D_MXrmJP.js';
+
+/**
+ * `AgentSurfaces` — declarative map of the mutable file/directory paths
+ * the self-improvement loop can edit on behalf of an agent.
+ *
+ * The substrate uses this map to resolve every parsed `FindingSubject`
+ * (from agent-eval) to a real on-disk path. No per-vertical glue;
+ * no fabricated paths; no silent `existsSync(...)` skips that hide
+ * misconfiguration from the operator.
+ *
+ * Surfaces are validated at `defineAgent` time — missing paths fail
+ * loud with a list of every offender. A surface that's not needed
+ * (e.g. an agent with no RAG corpora) is simply omitted; the loop
+ * refuses to route those subjects rather than fabricating a target.
+ */
+
+/**
+ * Surface declarations. Every path is repo-relative (or absolute) at
+ * `defineAgent` time. At resolution time, paths are joined against the
+ * agent's `repoRoot`.
+ *
+ * `systemPrompt`, `tools`, `personas` are DIRECTORIES; the loop appends
+ * `<section>.md`, `<tool>/README.md`, `<persona-id>.yaml` etc.
+ * `rubric`, `outputSchema` are SINGLE FILES; the loop edits them in
+ * place.
+ *
+ * `knowledge` is the agent-knowledge root (typically `.agent-knowledge`);
+ * `applyKnowledgeWriteBlocks` writes pages relative to it.
+ *
+ * Optional surfaces (`scaffolding`, `memory`, `rag`, `outputSchema`)
+ * can be omitted — the loop will reject findings targeting them with a
+ * clear log message instead of fabricating a path.
+ */
+interface AgentSurfaces {
+    /** Directory containing one markdown file per system-prompt section. */
+    systemPrompt: string;
+    /** Directory containing one subdir per tool (`<tool>/README.md`). */
+    tools: string;
+    /** Single file (TypeScript module) defining the rubric weights + dimensions. */
+    rubric: string;
+    /** Knowledge-base root; typically `.agent-knowledge`. */
+    knowledge: string;
+    /** Directory containing one YAML/JSON file per persona. */
+    personas: string;
+    /** Optional: directory containing scaffolding rules (precondition checks, retry policies). */
+    scaffolding?: string;
+    /** Optional: memory store path (JSONL / SQLite / DB). */
+    memory?: string;
+    /** Optional: directory containing RAG corpora (`<corpus>/<doc-id>.md`). */
+    rag?: string;
+    /** Optional: single file defining the output schema (Zod / JSON Schema). */
+    outputSchema?: string;
+}
+interface ResolvedSurface {
+    /** Absolute filesystem path the operator can `cat` / `vim`. */
+    absolutePath: string;
+    /** Repo-relative path for PR descriptions, diffs, audit logs. */
+    repoRelativePath: string;
+    /** Whether the path currently exists on disk. */
+    exists: boolean;
+    /** The substrate's intent: edit an existing file or create a new one. */
+    intent: 'edit-existing' | 'create-new';
+}
+/**
+ * Resolve a parsed `FindingSubject` to the file path the substrate
+ * should edit (or create) on disk.
+ *
+ * Returns `null` when:
+ *   - the subject targets a surface the agent didn't declare
+ *     (e.g. `rag:*` when `surfaces.rag` is undefined), OR
+ *   - the subject is a `cluster` (failure-mode emits these as evidence,
+ *     not actionable mutations — they don't route to a file).
+ *
+ * Returns a `ResolvedSurface` with `intent: 'create-new'` when the
+ * subject names a path that doesn't yet exist (e.g. a new wiki page).
+ * The caller chooses whether to honour the create — for tightly-managed
+ * surfaces like `systemPrompt` it's usually a contract violation
+ * (the analyst named a section that doesn't exist); for `knowledge`
+ * it's the whole point.
+ */
+declare function resolveSubjectPath(subject: FindingSubject, surfaces: AgentSurfaces, repoRoot: string): ResolvedSurface | null;
+/**
+ * Validate that every declared surface exists on disk under `repoRoot`.
+ *
+ * Returns an array of `SurfaceValidationIssue` — empty when all required
+ * surfaces resolve. `defineAgent` throws with the issues rendered, so
+ * a misconfigured manifest fails at startup (not at the first finding
+ * the loop produces 20 minutes later).
+ */
+interface SurfaceValidationIssue {
+    surface: keyof AgentSurfaces;
+    path: string;
+    reason: 'missing' | 'not-directory' | 'not-file';
+}
+declare function validateSurfaces(surfaces: AgentSurfaces, repoRoot: string): ReadonlyArray<SurfaceValidationIssue>;
+declare function renderSurfaceIssues(issues: ReadonlyArray<SurfaceValidationIssue>, repoRoot: string): string;
+
+/**
+ * The full agent manifest. Each agent ships ONE of these.
+ *
+ * Generics:
+ *   `TPersona` — the agent's persona shape (loaded from
+ *     `surfaces.personas`). Defaults to `unknown` so the substrate's
+ *     persona discovery (`loadPersonas`) can accept anything; per-agent
+ *     code re-narrows when it matters.
+ *   `TRunOutput` — the shape `runtime.act` returns. Used by the rubric
+ *     scorers and emitted into the trace.
+ */
+interface AgentManifest<TPersona = unknown, TRunOutput = unknown> {
+    /**
+     * Stable identifier — used as `projectId` in traces, as the analyst
+     * loop's `runId` prefix, and as the namespace under which findings
+     * are persisted. MUST match the agent's repo name to keep
+     * cross-repo telemetry joinable.
+     */
+    id: string;
+    /**
+     * Filesystem root the substrate resolves surface paths against.
+     * Typically `process.cwd()` or a fixed absolute path. Use an
+     * absolute path when the agent's tests may run from subdirectories
+     * (vitest sometimes shifts cwd).
+     */
+    repoRoot: string;
+    /**
+     * Map of mutable surfaces the self-improvement loop can edit. See
+     * `AgentSurfaces` — required: `systemPrompt`, `tools`, `rubric`,
+     * `knowledge`, `personas`. Optional: `scaffolding`, `memory`, `rag`,
+     * `outputSchema`.
+     *
+     * Every required path is validated at `defineAgent` time. Missing
+     * paths throw with the full list of offenders.
+     */
+    surfaces: AgentSurfaces;
+    /**
+     * Rubric the substrate uses to score each run. Dimensions × weights
+     * × judges. The substrate computes the weighted composite and
+     * stamps it into the RunRecord.
+     */
+    rubric: AgentRubric<TRunOutput>;
+    /**
+     * Runtime adapter — how the substrate INVOKES the agent against a
+     * persona. The `act` function takes a persona + a context (with the
+     * tracer the substrate threads through for span emission) and
+     * returns the run output the rubric will score.
+     *
+     * The agent's existing production runtime goes in here; the
+     * substrate is intentionally thin around it.
+     */
+    runtime: AgentRuntime<TPersona, TRunOutput>;
+    /**
+     * Persona discovery — the substrate loads personas via this function
+     * at eval start. Can read from `surfaces.personas`, an API, or be
+     * hardcoded. The substrate calls it once per `runAgentEval` call;
+     * persona ordering is preserved.
+     */
+    personas: () => Promise<ReadonlyArray<TPersona>>;
+    /**
+     * Analyst kinds the substrate runs against each persona's trace.
+     * Defaults to `DEFAULT_TRACE_ANALYST_KINDS` from agent-eval. Per-agent
+     * authors can prune (e.g. skip `knowledge-poisoning` when there's no
+     * knowledge base) or extend (custom domain kinds).
+     *
+     * Empty array disables the loop — useful for `pnpm eval --no-analyst`.
+     */
+    analystKinds: ReadonlyArray<TraceAnalystKindSpec>;
+    /**
+     * Analyst LLM configuration. The substrate uses these for all four
+     * kinds (override per-kind via `analystKinds` if needed).
+     */
+    analyst: AnalystConfig;
+    /**
+     * Auto-apply policy. Knowledge / improvement edits land only when
+     * `enabled === true` AND the source finding's confidence meets the
+     * threshold. `mode` controls how applies happen: `'write'` mutates
+     * files in-place; `'open-pr'` writes to a branch and opens a PR.
+     *
+     * Default: knowledge auto-applies at confidence ≥0.85 in `'write'`
+     * mode (wiki edits are git-reversible); improvement stays at
+     * `enabled: false` until the agent author has measured precision.
+     */
+    autoApply?: AutoApplyPolicy;
+}
+interface AgentRubric<TRunOutput> {
+    /** Dimensions composing the weighted score. Weights sum to 1.0 by convention. */
+    dimensions: ReadonlyArray<RubricDimension<TRunOutput>>;
+    /**
+     * Optional judges layered on top of deterministic dimensions. Each
+     * judge returns a score per dimension; the substrate averages judges
+     * (mean by default) for the LLM contribution.
+     */
+    judges?: ReadonlyArray<JudgeConfig<TRunOutput>>;
+}
+interface RubricDimension<TRunOutput> {
+    /** Unique identifier — appears in finding subjects (`rubric:<id>`). */
+    id: string;
+    /** 0..1 — weight in the composite. */
+    weight: number;
+    /**
+     * Deterministic scorer: given the persona + run output, returns a
+     * 0..1 score. The substrate sums weight × score across dimensions
+     * for the deterministic composite; judges supplement subjective dims.
+     */
+    score: (input: {
+        persona: unknown;
+        output: TRunOutput;
+    }) => number;
+    /** Optional human-readable label for reports. */
+    label?: string;
+}
+interface JudgeConfig<TRunOutput> {
+    /** Judge identifier — appears in trace spans + manifest. */
+    id: string;
+    /** Model snapshot to invoke. Pin the snapshot (`claude-sonnet-4-6@2025-04-15`); the validator rejects bare aliases. */
+    model: string;
+    /** Dimensions this judge scores. */
+    dimensions: ReadonlyArray<string>;
+    /**
+     * Optional rubric anchors — text examples the judge sees as a
+     * few-shot prompt to calibrate. STRONGLY recommended for subjective
+     * dimensions; required by the calibration gate (Pearson ≥0.7).
+     */
+    anchors?: ReadonlyArray<{
+        input: string;
+        output: TRunOutput;
+        expected: Record<string, number>;
+    }>;
+}
+interface AgentRuntime<TPersona, TRunOutput> {
+    /**
+     * Invoke the agent against one persona. Returns the structured run
+     * output the rubric will score.
+     *
+     * `ctx.emitter` is the substrate-threaded `TraceEmitter` — agents
+     * SHOULD record their LLM calls / tool calls through it for capture
+     * integrity. `ctx.deadlineMs` is wall-clock; the runtime SHOULD
+     * honour it for graceful cancel.
+     */
+    act: (persona: TPersona, ctx: AgentRunContext) => Promise<TRunOutput>;
+}
+interface AgentRunContext {
+    /** Substrate-managed trace emitter. */
+    emitter: _tangle_network_agent_eval.TraceEmitter;
+    /** Stable run id for this persona × variant cell. */
+    runId: string;
+    /** Variant the runtime is exercising (e.g. `'baseline'`, `'source-grounded'`). */
+    variantId?: string;
+    /** Wall-clock deadline (epoch ms). The runtime SHOULD honour for graceful cancel. */
+    deadlineMs?: number;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+}
+interface AnalystConfig {
+    /** Model the analyst kinds use. Override per-kind via `analystKinds[i].cost.models`. */
+    model: string;
+    /** Optional total budget across all kinds for one run. Substrate enforces via `BudgetGuard`. */
+    budgetUsd?: number;
+    /** Backend hint for the AxAIService factory — same shape every kind uses. */
+    backend?: {
+        name?: 'openai' | 'router';
+        apiKey?: string;
+        baseUrl?: string;
+    };
+}
+interface AutoApplyPolicy {
+    knowledge?: {
+        enabled: boolean;
+        confidenceThreshold?: number;
+        mode?: 'write' | 'open-pr';
+    };
+    improvement?: {
+        enabled: boolean;
+        confidenceThreshold?: number;
+        mode?: 'write' | 'open-pr';
+    };
+}
+declare class AgentManifestError extends Error {
+    readonly agentId: string;
+    readonly issues: ReadonlyArray<unknown>;
+    constructor(message: string, agentId: string, issues?: ReadonlyArray<unknown>);
+}
+/**
+ * Construct a validated agent manifest. Throws `AgentManifestError`
+ * if any required surface is missing on disk.
+ *
+ * Generics: pass your persona / output types if you want narrowed
+ * `runtime.act` signatures:
+ *   `defineAgent<TaxPersona, TaxRunOutput>({ ... })`
+ *
+ * Most callers don't need the generics — the substrate operates on
+ * `unknown` payloads internally and the manifest's `score` /
+ * `runtime.act` see the typed shapes via TypeScript inference at
+ * the call site.
+ */
+declare function defineAgent<TPersona = unknown, TRunOutput = unknown>(manifest: AgentManifest<TPersona, TRunOutput>): AgentManifest<TPersona, TRunOutput>;
+
+/**
+ * Substrate-default `ImprovementAdapter` — surfaces-driven, LLM-drafted
+ * patches, optional auto-apply or PR-open.
+ *
+ * This is the one ImprovementAdapter every vertical agent uses. The
+ * substrate parses each finding's `subject` via
+ * `parseFindingSubject` (agent-eval), resolves it to a real file path
+ * via the agent's `AgentSurfaces`, reads the current content, and asks
+ * an LLM to draft a unified-diff patch given the finding + current
+ * content + per-kind editing-discipline rules.
+ *
+ * Auto-apply gates on the source-finding's confidence and the
+ * autoApply.improvement policy. Two modes:
+ *   `write` — apply the patch in-place via `git apply -p0`. Operator
+ *     reviews via `git diff`.
+ *   `open-pr` — write to a branch, commit, push, open a PR via `gh`.
+ *     Operator reviews via the PR UI.
+ *
+ * Fail-loud rules:
+ *   - Findings whose subject doesn't parse → counted in `errors`.
+ *   - Findings whose subject targets an undeclared surface → counted in
+ *     `errors` with the offending kind in the message.
+ *   - Findings whose target path doesn't exist AND the kind isn't a
+ *     create-new variant (`new-tool`, `knowledge.wiki`) → counted in
+ *     `errors` with the resolved path in the message.
+ *   - LLM drafts that fail JSON-schema validation → counted in
+ *     `errors` with the schema issue.
+ *
+ * No silent skips. Every dropped finding has a recorded reason the
+ * loop's report surfaces.
+ */
+
+interface SurfaceImprovementEdit {
+    /** Stable id derived from the source finding so re-proposals are idempotent. */
+    id: string;
+    /** The finding that produced this edit — for revert + audit trail. */
+    sourceFindingId: string;
+    /** Parsed subject; included so the apply step doesn't re-parse. */
+    subject: FindingSubject;
+    /** Resolved on-disk target. */
+    target: ResolvedSurface;
+    /** SHA-256 of the current file content the patch was drafted against. */
+    baseSha256: string;
+    /** Unified-diff patch the LLM drafted (relative to `target.absolutePath`). */
+    patch: string;
+    /** One-line summary the operator sees in the report / PR title. */
+    summary: string;
+    /** Multi-line rationale for the PR body — finding context + LLM reasoning. */
+    rationale: string;
+    /** Carry-forward from the finding so the apply gate can check the threshold. */
+    confidence: number;
+    /** Carry-forward severity for prioritization. */
+    severity: AnalystFinding['severity'];
+}
+interface CreateSurfaceImprovementAdapterOpts {
+    surfaces: AgentSurfaces;
+    repoRoot: string;
+    /**
+     * LLM-draft callback. Given a finding + current file content + the
+     * resolved target, returns a unified-diff patch + summary + rationale.
+     *
+     * Required — the substrate doesn't ship a hardcoded prompt; the agent
+     * author picks the model (Haiku for cheap routine drafts, Sonnet for
+     * substantive prompt rewrites, etc.) via this callback.
+     */
+    draftPatch: (input: DraftPatchInput) => Promise<DraftPatchOutput>;
+    /**
+     * Apply mode:
+     *   `write` — `git apply` in-place; operator reviews via `git diff`
+     *   `open-pr` — branch + commit + push + `gh pr create`
+     *   `none` — never apply; collect proposals for the report only
+     *
+     * The `apply` method honours this even when the loop calls it; the
+     * effective behaviour is also gated on the per-finding confidence
+     * threshold via `runAnalystLoop`'s `autoApply` policy.
+     */
+    mode?: 'write' | 'open-pr' | 'none';
+    /** When `mode === 'open-pr'`, the base branch new PRs target. Default: `main`. */
+    baseBranch?: string;
+    /** Required for `mode === 'open-pr'` — the GH owner/repo (`tangle-network/tax-agent`). */
+    ghRepo?: string;
+    /**
+     * When the resolved target doesn't exist, allow the substrate to
+     * CREATE the file (for `knowledge.wiki`, `new-tool` subjects). Default
+     * true for those kinds, false for `system-prompt` / `rubric` / etc.
+     * (named sections that don't exist are a contract violation, not a
+     * scaffolding opportunity).
+     */
+    allowCreateForKinds?: ReadonlyArray<FindingSubject['kind']>;
+}
+interface DraftPatchInput {
+    finding: AnalystFinding;
+    subject: FindingSubject;
+    target: ResolvedSurface;
+    /** Current file content (empty string when `intent === 'create-new'`). */
+    currentContent: string;
+}
+interface DraftPatchOutput {
+    /** Unified diff against the current file content. Empty string skips this finding. */
+    patch: string;
+    /** One-line summary for the operator. */
+    summary: string;
+    /** Multi-line rationale for the PR body. */
+    rationale: string;
+}
+declare function createSurfaceImprovementAdapter(opts: CreateSurfaceImprovementAdapterOpts): ImprovementAdapter<SurfaceImprovementEdit>;
+
+/**
+ * Substrate-default `KnowledgeAdapter` — wraps agent-knowledge's
+ * `proposeFromFindings` + `applyKnowledgeWriteBlocks` with substrate
+ * defaults (auto-lint after apply, source linkage via finding id).
+ *
+ * Every agent that ships a `.agent-knowledge/` tree uses this adapter
+ * unmodified. Per-agent customization happens at the manifest level
+ * (`autoApply.knowledge.confidenceThreshold`, etc.), not by writing a
+ * new adapter.
+ *
+ * Lint discipline: after each apply we run agent-knowledge's
+ * `lintKnowledgeIndex` to catch broken links / circular claims /
+ * duplicate pages introduced by the new writes. Findings that fail the
+ * post-apply lint are recorded in `warnings`; the apply itself is not
+ * rolled back (lint failures are soft — humans review the wiki state).
+ */
+
+interface CreateSurfaceKnowledgeAdapterOpts {
+    /** `.agent-knowledge/` root (absolute path the substrate writes blocks against). */
+    knowledgeRoot: string;
+}
+/**
+ * Build the adapter. We accept the agent-knowledge functions as DI so
+ * the substrate stays decoupled from a specific agent-knowledge
+ * version — the agent author imports them in their manifest module
+ * and hands them to the factory.
+ *
+ * `proposeFromFindings(findings)` returns
+ *   `{ proposals: KnowledgeProposal[]; skipped: number; errors: ... }`.
+ *
+ * `applyKnowledgeWriteBlocks(root, content)` returns
+ *   `{ written: string[]; warnings: string[] }`.
+ *
+ * `lintKnowledgeIndex(index)` (optional) returns `KnowledgeLintFinding[]`.
+ */
+interface KnowledgeAdapterDeps<TProposal> {
+    proposeFromFindings: (findings: ReadonlyArray<AnalystFinding>) => {
+        proposals: TProposal[];
+        skipped: number;
+        errors: Array<{
+            findingId: string;
+            subject: string;
+            message: string;
+        }>;
+    };
+    applyKnowledgeWriteBlocks: (root: string, proposalText: string) => Promise<{
+        written: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Optional post-apply lint hook. The substrate runs it after each
+     * batch of writes; failures land in `warnings` (the apply is not
+     * rolled back — lint signals drift to review, not block).
+     */
+    lintAfterApply?: (root: string) => Promise<ReadonlyArray<string>>;
+}
+declare function createSurfaceKnowledgeAdapter<TProposal>(opts: CreateSurfaceKnowledgeAdapterOpts, deps: KnowledgeAdapterDeps<TProposal>): KnowledgeAdapter<TProposal>;
+
+/**
+ * `OutcomeMeasurement` — the missing metric that turns the analyst
+ * loop from "observability" into "self-improvement".
+ *
+ * Without this hook, the loop reports process counts (`findings: 42`,
+ * `applied: 7`) and never proves the applied edits actually improved
+ * anything. With this hook, the substrate re-runs the cohort against
+ * the same personas after each apply pass and reports a composite
+ * score delta. A negative delta is the substrate's strongest signal
+ * to either roll back or surface for review.
+ *
+ * Wiring is intentionally simple: pass the manifest + the `runAgentEval`
+ * function and a list of `personaIds` to re-run. The wrapper:
+ *   1. Captures the baseline composite from the just-finished run.
+ *   2. After `runAnalystLoop` returns, re-invokes `runAgentEval` against
+ *      the same persona slice.
+ *   3. Computes the delta and appends to `loop-report.json`.
+ *   4. If `rollbackOnRegression` and delta < 0, reverts applied edits.
+ */
+
+interface OutcomeMeasurement {
+    /** Baseline composite before applies — captured from the most-recent eval run. */
+    baselineComposite: number;
+    /** Composite after re-running the cohort with applied edits. */
+    afterComposite: number;
+    /** `afterComposite - baselineComposite`. Positive = the loop improved the agent. */
+    delta: number;
+    /** Per-persona deltas for finer-grained review. */
+    perPersona: ReadonlyArray<{
+        personaId: string;
+        before: number;
+        after: number;
+        delta: number;
+    }>;
+    /** When the substrate rolled back applies due to regression, the paths reverted. */
+    rolledBackPaths: ReadonlyArray<string>;
+}
+interface OutcomeMeasurementOpts {
+    /** Composite scores from the run that produced the findings. */
+    baseline: ReadonlyArray<{
+        personaId: string;
+        composite: number;
+    }>;
+    /**
+     * Re-run callback — the substrate invokes this after applies. The
+     * agent author provides their `runAgentEval`-equivalent so the
+     * substrate can ask "score this persona slice now."
+     *
+     * The callback SHOULD reuse the same cohort + judges + variant as
+     * the baseline run; only the agent's mutable surfaces have changed.
+     */
+    reRunCohort: (personaIds: ReadonlyArray<string>) => Promise<ReadonlyArray<{
+        personaId: string;
+        composite: number;
+    }>>;
+    /** When `true`, applied edits are reverted on negative delta. Default `false`. */
+    rollbackOnRegression?: boolean;
+    /** Callback to revert a list of paths (typically `git checkout HEAD --`). */
+    revert?: (paths: ReadonlyArray<string>) => Promise<void>;
+}
+/**
+ * Run `runAnalystLoop` and stamp an `OutcomeMeasurement` onto the
+ * result. The substrate calls this after each canonical eval; the
+ * delta lands in `loop-report.json` for cross-run trend analysis.
+ *
+ * The function returns the original `RunAnalystLoopResult` enriched
+ * with `outcome` so callers stay backwards-compatible (the field is
+ * optional on the type; missing means no measurement was wired).
+ */
+declare function measureOutcome<TProposal, TEdit>(result: RunAnalystLoopResult<TProposal, TEdit>, opts: OutcomeMeasurementOpts): Promise<RunAnalystLoopResult<TProposal, TEdit> & {
+    outcome: OutcomeMeasurement;
+}>;
+
+export { type AgentManifest, AgentManifestError, type AgentRubric, type AgentRunContext, type AgentRuntime, type AgentSurfaces, type AnalystConfig, type AutoApplyPolicy, type CreateSurfaceImprovementAdapterOpts, type CreateSurfaceKnowledgeAdapterOpts, type DraftPatchInput, type DraftPatchOutput, type JudgeConfig, type KnowledgeAdapterDeps, type OutcomeMeasurement, type OutcomeMeasurementOpts, type ResolvedSurface, type RubricDimension, type SurfaceImprovementEdit, type SurfaceValidationIssue, createSurfaceImprovementAdapter, createSurfaceKnowledgeAdapter, defineAgent, measureOutcome, renderSurfaceIssues, resolveSubjectPath, validateSurfaces };