@tangle-network/agent-runtime 0.52.0 → 0.54.0

package/dist/{kb-gate-CHAyt4aI.d.ts → delegates-BPLIl8EC.d.ts}

@@ -1,123 +1,9 @@
-import { C as CoderOutput, b as CoderTask } from './coder-_YCf3BAK.js';
-import { f as LoopTraceEmitter, g as LoopTraceEvent, S as SandboxClient, A as AgentRunSpec } from './types-BEQsBhOE.js';
+import { C as CoderOutput, b as CoderTask } from './coder-CEkUFv8h.js';
+import { g as LoopTraceEmitter, e as LoopTraceEvent, S as SandboxClient, A as AgentRunSpec } from './types-C8rNlxfV.js';
 import { SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
 import { AgentEvalError } from '@tangle-network/agent-eval';
 import { a as UiLens, U as UiFinding } from './substrate-CUgk7F7s.js';
 
-/**
- * @experimental
- *
- * Persistence port for the MCP delegation queue.
- *
- * `DelegationTaskQueue` keeps its working set in memory (status/history
- * reads stay synchronous) and journals every record mutation through a
- * `DelegationStore`. `DelegationTaskQueue.restore({ store })` is the load
- * path: it reads the full record set once at construction and rehydrates
- * the queue from it. After that the store only sees writes.
- *
- * Records MUST be JSON-safe — `FileDelegationStore` round-trips them
- * through `JSON.stringify`/`JSON.parse`, so a `Date`, `Map`, or function
- * smuggled into `args`/`result` would corrupt the journal.
- */
-
-/** @experimental */
-interface DelegationStore {
-    /**
-     * Read every persisted record. Called once, by
-     * `DelegationTaskQueue.restore`, before any write. A missing backing
-     * file is an empty store; an unparseable one throws
-     * `DelegationStateCorruptError`.
-     */
-    loadAll(): Promise<DelegationRecord[]>;
-    /** Insert or replace the record keyed by `record.taskId`. */
-    upsert(record: DelegationRecord): Promise<void>;
-    /**
-     * Resolve an idempotency key to the taskId that claimed it, if any.
-     * The queue serves submit-time dedupe from its rehydrated in-memory
-     * index; this read exists for consumers that share a store across
-     * processes without holding the full record set.
-     */
-    lookupIdempotencyKey(key: string): Promise<string | undefined>;
-    /** Delete the named records — the retention-cap eviction path. */
-    remove(taskIds: readonly string[]): Promise<void>;
-}
-/**
- * The persisted delegation state exists but cannot be parsed into
- * records. Fail loud: silently starting empty over a corrupt journal
- * would erase delegation history and re-run idempotent work. Opt into
- * recovery explicitly via `FileDelegationStoreOptions.recoverCorrupt`
- * (the bin maps `AGENT_RUNTIME_DELEGATION_STATE_RECOVER=1` onto it),
- * which archives the corrupt file and starts fresh.
- *
- * @experimental
- */
-declare class DelegationStateCorruptError extends AgentEvalError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * A delegation-store read or write failed (filesystem error, store
- * called before `loadAll`, ...). Once the queue observes one, it stops
- * accepting new submissions — accepting work it cannot journal would
- * silently demote durable mode to in-memory mode.
- *
- * @experimental
- */
-declare class DelegationPersistenceError extends AgentEvalError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** @experimental */
-declare class InMemoryDelegationStore implements DelegationStore {
-    private readonly records;
-    loadAll(): Promise<DelegationRecord[]>;
-    upsert(record: DelegationRecord): Promise<void>;
-    lookupIdempotencyKey(key: string): Promise<string | undefined>;
-    remove(taskIds: readonly string[]): Promise<void>;
-}
-/** @experimental */
-interface FileDelegationStoreOptions {
-    /** Absolute path of the JSON state file. Parent directories are created on first write. */
-    filePath: string;
-    /**
-     * When the state file exists but cannot be parsed, archive it to
-     * `<filePath>.corrupt-<timestamp>` and start empty instead of
-     * throwing `DelegationStateCorruptError`. Default false.
-     */
-    recoverCorrupt?: boolean;
-}
-/**
- * JSON-file persistence for the delegation queue. Each write serializes
- * the full record set and lands it atomically (write to a sibling tmp
- * file, then `rename`), so readers never observe a torn file — a crash
- * mid-write leaves the previous snapshot intact. Writes are serialized
- * internally; concurrent `upsert`/`remove` calls cannot interleave.
- *
- * Built for the MCP server's scale (one stdio process, hundreds of
- * records): full-snapshot writes keep the format trivially inspectable
- * and corruption-detectable without a database dependency.
- *
- * @experimental
- */
-declare class FileDelegationStore implements DelegationStore {
-    private readonly filePath;
-    private readonly recoverCorrupt;
-    private readonly records;
-    private loaded;
-    private writeTail;
-    private tmpSeq;
-    constructor(options: FileDelegationStoreOptions);
-    loadAll(): Promise<DelegationRecord[]>;
-    upsert(record: DelegationRecord): Promise<void>;
-    lookupIdempotencyKey(key: string): Promise<string | undefined>;
-    remove(taskIds: readonly string[]): Promise<void>;
-    private assertLoaded;
-    private enqueueWrite;
-    private writeSnapshot;
-}
-
 /**
  * @experimental
  *
@@ -209,16 +95,418 @@ interface DelegationTraceCollector {
     settle(): void;
 }
 /** @experimental */
-declare function createDelegationTraceCollector(onSpans: (spans: DelegationTraceSpan[]) => void): DelegationTraceCollector;
+declare function createDelegationTraceCollector(onSpans: (spans: DelegationTraceSpan[]) => void): DelegationTraceCollector;
+/**
+ * Fan one `LoopTraceEvent` stream into several emitters — e.g. the
+ * process-wide OTEL exporter AND the per-delegation journal collector.
+ * `undefined` entries are skipped; returns `undefined` when nothing is left
+ * so callers keep the kernel's "no emitter, no events" fast path.
+ *
+ * @experimental
+ */
+declare function composeLoopTraceEmitters(...emitters: ReadonlyArray<LoopTraceEmitter | undefined>): LoopTraceEmitter | undefined;
+
+/**
+ * @experimental
+ *
+ * MCP delegation tool surface — the typed inputs/outputs the product agent
+ * sees over the wire. These types are the contract; the JSON schemas under
+ * `tools/*` mirror them for the MCP `tools/list` advertisement.
+ *
+ * Async semantics: `delegate_code` + `delegate_research` return a `taskId`
+ * immediately. The product agent polls `delegation_status` until the task
+ * transitions to `completed` | `failed` | `cancelled`. `delegate_feedback`
+ * + `delegation_history` are synchronous reads / writes against the local
+ * task queue + feedback store.
+ */
+
+/** @experimental */
+type DelegationProfile = 'coder' | 'researcher' | 'ui-auditor';
+/** @experimental */
+type DelegationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Minimal `CoderTask` overrides exposed over the MCP wire. The full
+ * `CoderTask` carries fields the kernel synthesizes from `goal` +
+ * `repoRoot` — the agent only edits the few that materially gate
+ * validator behavior.
+ *
+ * @experimental
+ */
+interface DelegateCodeConfig {
+    testCmd?: string;
+    typecheckCmd?: string;
+    forbiddenPaths?: string[];
+    maxDiffLines?: number;
+}
+/** @experimental */
+interface DelegateCodeArgs {
+    /** Natural-language description of what the coder must accomplish. */
+    goal: string;
+    /** Absolute path inside the sandbox where the repo lives. */
+    repoRoot: string;
+    /** Optional free-form context the agent surfaces in the prompt prelude. */
+    contextHint?: string;
+    /**
+     * When > 1, dispatches `multiHarnessCoderFanout` across N harnesses
+     * (claude-code, codex, opencode-glm) and picks the highest-scoring
+     * passing patch. Default 1.
+     */
+    variants?: number;
+    /** Validator + prompt overrides the agent knows for this repo. */
+    config?: DelegateCodeConfig;
+    /** Multi-tenant scope (customer-id, workspace-id). */
+    namespace?: string;
+}
+/** @experimental */
+interface DelegateCodeResult {
+    taskId: string;
+    /** Best-effort hint — coder loops can take minutes-to-hours. */
+    estimatedDurationMs?: number;
+}
+/** @experimental */
+type ResearchSource = 'web' | 'corpus' | 'twitter' | 'github' | 'docs';
+/** @experimental */
+interface DelegateResearchConfig {
+    recencyWindow?: {
+        since?: string;
+        until?: string;
+    };
+    maxItems?: number;
+    minConfidence?: number;
+}
+/** @experimental */
+interface DelegateResearchArgs {
+    question: string;
+    namespace: string;
+    scope?: string;
+    sources?: ResearchSource[];
+    variants?: number;
+    config?: DelegateResearchConfig;
+}
+/** @experimental */
+interface DelegateResearchResult {
+    taskId: string;
+    estimatedDurationMs?: number;
+}
+/** @experimental */
+interface FeedbackRefersTo {
+    kind: 'delegation' | 'artifact' | 'outcome';
+    /** For `'delegation'`, this is the taskId. */
+    ref: string;
+}
+/** @experimental */
+interface FeedbackRating {
+    /** [0, 1]. */
+    score: number;
+    label?: 'good' | 'bad' | 'neutral' | 'mixed';
+    notes: string;
+}
+/** @experimental */
+interface DelegateFeedbackArgs {
+    refersTo: FeedbackRefersTo;
+    rating: FeedbackRating;
+    by: 'agent' | 'user' | 'downstream-judge';
+    /** ISO timestamp; defaults to server clock when omitted. */
+    capturedAt?: string;
+    namespace?: string;
+}
+/** @experimental */
+interface DelegateFeedbackResult {
+    recorded: true;
+    id: string;
+}
+/** @experimental */
+interface DelegationStatusArgs {
+    taskId: string;
+    /**
+     * Return the delegation's compact loop-trace span tree alongside the
+     * status. Default false — status polls stay light; opt in when you need
+     * the topology (which iterations ran, where they were placed, what each
+     * cost) rather than just the state machine.
+     */
+    includeTrace?: boolean;
+}
+/** @experimental */
+interface DelegationProgress {
+    iteration: number;
+    phase: string;
+}
+/** @experimental */
+interface DelegationError {
+    message: string;
+    kind: string;
+}
+/**
+ * Polymorphic `result` field: `CoderOutput` when the underlying profile
+ * is `'coder'`, a structurally-typed research output when `'researcher'`.
+ * The MCP wire carries it as JSON either way.
+ *
+ * @experimental
+ */
+type DelegationResultPayload = {
+    profile: 'coder';
+    output: CoderOutput;
+} | {
+    profile: 'researcher';
+    output: ResearchOutputShape;
+} | {
+    profile: 'ui-auditor';
+    output: UiAuditorDelegationOutput;
+};
+/**
+ * Wire-shape of a completed UI-audit delegation. The `findings` array
+ * contains every finding persisted to the workspace during the run,
+ * already enriched with `id` and `createdAt` by the writer. `workspaceDir`
+ * is the absolute path to the workspace; `indexFile` is the workspace-
+ * relative path to the regenerated index.md.
+ *
+ * @experimental
+ */
+interface UiAuditorDelegationOutput {
+    workspaceDir: string;
+    indexFile: string;
+    findings: UiFinding[];
+    /** Total iterations the loop ran for this delegation. */
+    iterations: number;
+}
+/** @experimental */
+type UiAuditLensFilter = readonly UiLens[];
+/** Optional per-route capture spec the agent surfaces over the wire. */
+interface DelegateUiAuditRoute {
+    /** Stable route name (used in screenshot filenames + finding metadata). */
+    name: string;
+    /** Fully-qualified URL. */
+    url: string;
+    /** Viewports to capture at. Defaults to `[{ width: 1280, height: 800 }]`. */
+    viewports?: readonly {
+        width: number;
+        height: number;
+    }[];
+    /** Default false. Full-page captures for the broad lenses. */
+    fullPage?: boolean;
+    /** Selector to wait for before capture. */
+    waitFor?: string;
+}
+/** @experimental */
+interface DelegateUiAuditConfig {
+    /**
+     * Lenses to iterate. Default: every lens except `'other'`. Order is
+     * preserved — the driver iterates lens-by-lens.
+     */
+    lenses?: UiAuditLensFilter;
+    /** Maximum total iterations across all (lens × route) pairs. Default 33 (11 lenses × 3 routes). */
+    maxIterations?: number;
+    /** Maximum concurrent iterations within a single plan() round. Default 2. */
+    maxConcurrency?: number;
+    /** Free-form product context surfaced to the judge. */
+    productContext?: string;
+}
+/** @experimental */
+interface DelegateUiAuditArgs {
+    /** Workspace root for the audit (absolute path). */
+    workspaceDir: string;
+    /** Routes to audit. Must be non-empty. */
+    routes: readonly DelegateUiAuditRoute[];
+    /** Multi-tenant scope. */
+    namespace?: string;
+    config?: DelegateUiAuditConfig;
+}
+/** @experimental */
+interface DelegateUiAuditResult {
+    taskId: string;
+    estimatedDurationMs?: number;
+}
+/**
+ * Loose shape of a research output over the wire — the substrate cannot
+ * import the `ResearchOutput` type from agent-knowledge without inducing
+ * a dependency cycle, so the MCP layer treats it structurally.
+ *
+ * @experimental
+ */
+interface ResearchOutputShape {
+    items: unknown[];
+    citations: unknown[];
+    proposedWrites: unknown[];
+    gaps?: string[];
+    notes?: string;
+    [key: string]: unknown;
+}
+/** @experimental */
+interface DelegationStatusResult {
+    taskId: string;
+    profile: DelegationProfile;
+    status: DelegationStatus;
+    progress?: DelegationProgress;
+    result?: DelegationResultPayload;
+    error?: DelegationError;
+    costUsd?: number;
+    startedAt: string;
+    completedAt?: string;
+    /** Compact loop-trace span tree; present only when `includeTrace: true` was passed and spans were recorded. */
+    trace?: DelegationTraceSpan[];
+    /** Present when oldest trace spans were dropped to honor the trace caps. */
+    traceTruncated?: true;
+    /** Inherited trace identity recorded at submit — join key into the caller's trace. */
+    traceId?: string;
+    /** Caller span that dispatched the delegation, when one was inherited. */
+    parentSpanId?: string;
+}
+/** @experimental */
+interface DelegationHistoryArgs {
+    namespace?: string;
+    profile?: DelegationProfile;
+    /** ISO date — only delegations started at-or-after `since` are returned. */
+    since?: string;
+    /** Default 50. Hard cap 500. */
+    limit?: number;
+}
+/** @experimental */
+interface DelegationFeedbackSnapshot {
+    id: string;
+    score: number;
+    label?: FeedbackRating['label'];
+    by: DelegateFeedbackArgs['by'];
+    notes: string;
+    capturedAt: string;
+}
+/** @experimental */
+interface DelegationHistoryEntry {
+    taskId: string;
+    profile: DelegationProfile;
+    namespace?: string;
+    args: DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
+    status: DelegationStatus;
+    feedback?: DelegationFeedbackSnapshot[];
+    costUsd?: number;
+    startedAt: string;
+    completedAt?: string;
+    /**
+     * True when the record carries a journaled loop trace. History stays
+     * light by design — fetch the spans via
+     * `delegation_status { taskId, includeTrace: true }`.
+     */
+    hasTrace: boolean;
+    /** Inherited trace identity recorded at submit — join key into the caller's trace. */
+    traceId?: string;
+}
+/** @experimental */
+interface DelegationHistoryResult {
+    delegations: DelegationHistoryEntry[];
+}
+
+/**
+ * @experimental
+ *
+ * Persistence port for the MCP delegation queue.
+ *
+ * `DelegationTaskQueue` keeps its working set in memory (status/history
+ * reads stay synchronous) and journals every record mutation through a
+ * `DelegationStore`. `DelegationTaskQueue.restore({ store })` is the load
+ * path: it reads the full record set once at construction and rehydrates
+ * the queue from it. After that the store only sees writes.
+ *
+ * Records MUST be JSON-safe — `FileDelegationStore` round-trips them
+ * through `JSON.stringify`/`JSON.parse`, so a `Date`, `Map`, or function
+ * smuggled into `args`/`result` would corrupt the journal.
+ */
+
+/** @experimental */
+interface DelegationStore {
+    /**
+     * Read every persisted record. Called once, by
+     * `DelegationTaskQueue.restore`, before any write. A missing backing
+     * file is an empty store; an unparseable one throws
+     * `DelegationStateCorruptError`.
+     */
+    loadAll(): Promise<DelegationRecord[]>;
+    /** Insert or replace the record keyed by `record.taskId`. */
+    upsert(record: DelegationRecord): Promise<void>;
+    /**
+     * Resolve an idempotency key to the taskId that claimed it, if any.
+     * The queue serves submit-time dedupe from its rehydrated in-memory
+     * index; this read exists for consumers that share a store across
+     * processes without holding the full record set.
+     */
+    lookupIdempotencyKey(key: string): Promise<string | undefined>;
+    /** Delete the named records — the retention-cap eviction path. */
+    remove(taskIds: readonly string[]): Promise<void>;
+}
+/**
+ * The persisted delegation state exists but cannot be parsed into
+ * records. Fail loud: silently starting empty over a corrupt journal
+ * would erase delegation history and re-run idempotent work. Opt into
+ * recovery explicitly via `FileDelegationStoreOptions.recoverCorrupt`
+ * (the bin maps `AGENT_RUNTIME_DELEGATION_STATE_RECOVER=1` onto it),
+ * which archives the corrupt file and starts fresh.
+ *
+ * @experimental
+ */
+declare class DelegationStateCorruptError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A delegation-store read or write failed (filesystem error, store
+ * called before `loadAll`, ...). Once the queue observes one, it stops
+ * accepting new submissions — accepting work it cannot journal would
+ * silently demote durable mode to in-memory mode.
+ *
+ * @experimental
+ */
+declare class DelegationPersistenceError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** @experimental */
+declare class InMemoryDelegationStore implements DelegationStore {
+    private readonly records;
+    loadAll(): Promise<DelegationRecord[]>;
+    upsert(record: DelegationRecord): Promise<void>;
+    lookupIdempotencyKey(key: string): Promise<string | undefined>;
+    remove(taskIds: readonly string[]): Promise<void>;
+}
+/** @experimental */
+interface FileDelegationStoreOptions {
+    /** Absolute path of the JSON state file. Parent directories are created on first write. */
+    filePath: string;
+    /**
+     * When the state file exists but cannot be parsed, archive it to
+     * `<filePath>.corrupt-<timestamp>` and start empty instead of
+     * throwing `DelegationStateCorruptError`. Default false.
+     */
+    recoverCorrupt?: boolean;
+}
 /**
- * Fan one `LoopTraceEvent` stream into several emitters — e.g. the
- * process-wide OTEL exporter AND the per-delegation journal collector.
- * `undefined` entries are skipped; returns `undefined` when nothing is left
- * so callers keep the kernel's "no emitter, no events" fast path.
+ * JSON-file persistence for the delegation queue. Each write serializes
+ * the full record set and lands it atomically (write to a sibling tmp
+ * file, then `rename`), so readers never observe a torn file — a crash
+ * mid-write leaves the previous snapshot intact. Writes are serialized
+ * internally; concurrent `upsert`/`remove` calls cannot interleave.
+ *
+ * Built for the MCP server's scale (one stdio process, hundreds of
+ * records): full-snapshot writes keep the format trivially inspectable
+ * and corruption-detectable without a database dependency.
  *
  * @experimental
  */
-declare function composeLoopTraceEmitters(...emitters: ReadonlyArray<LoopTraceEmitter | undefined>): LoopTraceEmitter | undefined;
+declare class FileDelegationStore implements DelegationStore {
+    private readonly filePath;
+    private readonly recoverCorrupt;
+    private readonly records;
+    private loaded;
+    private writeTail;
+    private tmpSeq;
+    constructor(options: FileDelegationStoreOptions);
+    loadAll(): Promise<DelegationRecord[]>;
+    upsert(record: DelegationRecord): Promise<void>;
+    lookupIdempotencyKey(key: string): Promise<string | undefined>;
+    remove(taskIds: readonly string[]): Promise<void>;
+    private assertLoaded;
+    private enqueueWrite;
+    private writeSnapshot;
+}
 
 /**
  * OTEL span exporter — streams LoopTraceEvents to an OTLP/HTTP collector.
@@ -354,386 +642,98 @@ interface EvalRunGeneration {
     surface?: unknown;
     /** Per-scenario results; empty until the generation is measured. */
     cells?: unknown[];
-    /** Mean composite score (0 when unmeasured — pair with labels.measured). */
-    compositeMean: number;
-    costUsd: number;
-    durationMs: number;
-}
-interface EvalRunEvent {
-    runId: string;
-    runDir: string;
-    /** ISO timestamp. */
-    timestamp: string;
-    status: 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored';
-    labels?: Record<string, string>;
-    baseline?: EvalRunGeneration;
-    generations?: EvalRunGeneration[];
-    gateDecision?: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
-    holdoutLift?: number;
-    totalCostUsd: number;
-    totalDurationMs: number;
-    errorMessage?: string;
-}
-interface EvalRunsExportConfig {
-    /** Bearer key — tenant is resolved server-side from it. Reads TANGLE_API_KEY. */
-    apiKey?: string;
-    /** Intelligence base. Reads INTELLIGENCE_BASE env, else prod. */
-    base?: string;
-    /** Idempotency-Key header (e.g. the runId) — safe retries + upsert. */
-    idempotencyKey?: string;
-}
-interface EvalRunsExportResult {
-    ok: boolean;
-    status: number;
-    accepted: number;
-    rejected: Array<{
-        index: number;
-        reason: string;
-    }>;
-}
-/**
- * Ship self-improvement eval-run events to Tangle Intelligence. Unlike the
- * best-effort span exporter, this RESOLVES with the ingest verdict (accepted /
- * rejected per event) so a consumer's loop can assert its provenance landed.
- * Throws only on a missing key or network failure.
- */
-declare function exportEvalRuns(events: EvalRunEvent[], config?: EvalRunsExportConfig): Promise<EvalRunsExportResult>;
-
-/**
- * @experimental
- *
- * Trace context propagation for MCP subprocess.
- *
- * When the MCP server is launched as a child process by a sandbox harness,
- * the parent passes trace context via environment variables:
- *
- *   TRACE_ID=<current-run-trace-id>
- *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>
- *
- * The MCP server reads these at startup and uses them as the root of its
- * internal trace tree. All spans emitted by `runLoop` invocations inside
- * the MCP are children of the parent's delegation span.
- *
- * When these env vars are absent, the MCP generates a fresh trace root —
- * the server operates standalone without trace joining.
- */
-
-interface TraceContext {
-    /** Trace id inherited from the parent process, or a fresh one. */
-    traceId: string;
-    /** Parent span id from the delegation that launched this MCP server. */
-    parentSpanId?: string;
-}
-/**
- * Read trace context from the process environment.
- * Returns a context with inherited ids or a freshly generated root.
- */
-declare function readTraceContextFromEnv(): TraceContext;
-/**
- * Create a LoopTraceEmitter that:
- *   1. Parents all spans under the inherited PARENT_SPAN_ID.
- *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.
- *
- * Returns both the emitter and the optional exporter handle for shutdown.
- */
-declare function createPropagatingTraceEmitter(ctx: TraceContext): {
-    emitter: LoopTraceEmitter;
-    exporter: OtelExporter | undefined;
-    context: TraceContext;
-};
-/**
- * Build env vars to pass to a child MCP subprocess so it inherits the
- * current trace context.
- */
-declare function traceContextToEnv(ctx: TraceContext): Record<string, string>;
-
-/**
- * @experimental
- *
- * MCP delegation tool surface — the typed inputs/outputs the product agent
- * sees over the wire. These types are the contract; the JSON schemas under
- * `tools/*` mirror them for the MCP `tools/list` advertisement.
- *
- * Async semantics: `delegate_code` + `delegate_research` return a `taskId`
- * immediately. The product agent polls `delegation_status` until the task
- * transitions to `completed` | `failed` | `cancelled`. `delegate_feedback`
- * + `delegation_history` are synchronous reads / writes against the local
- * task queue + feedback store.
- */
-
-/** @experimental */
-type DelegationProfile = 'coder' | 'researcher' | 'ui-auditor';
-/** @experimental */
-type DelegationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-/**
- * Minimal `CoderTask` overrides exposed over the MCP wire. The full
- * `CoderTask` carries fields the kernel synthesizes from `goal` +
- * `repoRoot` — the agent only edits the few that materially gate
- * validator behavior.
- *
- * @experimental
- */
-interface DelegateCodeConfig {
-    testCmd?: string;
-    typecheckCmd?: string;
-    forbiddenPaths?: string[];
-    maxDiffLines?: number;
-}
-/** @experimental */
-interface DelegateCodeArgs {
-    /** Natural-language description of what the coder must accomplish. */
-    goal: string;
-    /** Absolute path inside the sandbox where the repo lives. */
-    repoRoot: string;
-    /** Optional free-form context the agent surfaces in the prompt prelude. */
-    contextHint?: string;
-    /**
-     * When > 1, dispatches `multiHarnessCoderFanout` across N harnesses
-     * (claude-code, codex, opencode-glm) and picks the highest-scoring
-     * passing patch. Default 1.
-     */
-    variants?: number;
-    /** Validator + prompt overrides the agent knows for this repo. */
-    config?: DelegateCodeConfig;
-    /** Multi-tenant scope (customer-id, workspace-id). */
-    namespace?: string;
-}
-/** @experimental */
-interface DelegateCodeResult {
-    taskId: string;
-    /** Best-effort hint — coder loops can take minutes-to-hours. */
-    estimatedDurationMs?: number;
-}
-/** @experimental */
-type ResearchSource = 'web' | 'corpus' | 'twitter' | 'github' | 'docs';
-/** @experimental */
-interface DelegateResearchConfig {
-    recencyWindow?: {
-        since?: string;
-        until?: string;
-    };
-    maxItems?: number;
-    minConfidence?: number;
-}
-/** @experimental */
-interface DelegateResearchArgs {
-    question: string;
-    namespace: string;
-    scope?: string;
-    sources?: ResearchSource[];
-    variants?: number;
-    config?: DelegateResearchConfig;
-}
-/** @experimental */
-interface DelegateResearchResult {
-    taskId: string;
-    estimatedDurationMs?: number;
-}
-/** @experimental */
-interface FeedbackRefersTo {
-    kind: 'delegation' | 'artifact' | 'outcome';
-    /** For `'delegation'`, this is the taskId. */
-    ref: string;
-}
-/** @experimental */
-interface FeedbackRating {
-    /** [0, 1]. */
-    score: number;
-    label?: 'good' | 'bad' | 'neutral' | 'mixed';
-    notes: string;
-}
-/** @experimental */
-interface DelegateFeedbackArgs {
-    refersTo: FeedbackRefersTo;
-    rating: FeedbackRating;
-    by: 'agent' | 'user' | 'downstream-judge';
-    /** ISO timestamp; defaults to server clock when omitted. */
-    capturedAt?: string;
-    namespace?: string;
-}
-/** @experimental */
-interface DelegateFeedbackResult {
-    recorded: true;
-    id: string;
-}
-/** @experimental */
-interface DelegationStatusArgs {
-    taskId: string;
-    /**
-     * Return the delegation's compact loop-trace span tree alongside the
-     * status. Default false — status polls stay light; opt in when you need
-     * the topology (which iterations ran, where they were placed, what each
-     * cost) rather than just the state machine.
-     */
-    includeTrace?: boolean;
+    /** Mean composite score (0 when unmeasured — pair with labels.measured). */
+    compositeMean: number;
+    costUsd: number;
+    durationMs: number;
 }
-/** @experimental */
-interface DelegationProgress {
-    iteration: number;
-    phase: string;
+interface EvalRunEvent {
+    runId: string;
+    runDir: string;
+    /** ISO timestamp. */
+    timestamp: string;
+    status: 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored';
+    labels?: Record<string, string>;
+    baseline?: EvalRunGeneration;
+    generations?: EvalRunGeneration[];
+    gateDecision?: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
+    holdoutLift?: number;
+    totalCostUsd: number;
+    totalDurationMs: number;
+    errorMessage?: string;
 }
-/** @experimental */
-interface DelegationError {
-    message: string;
-    kind: string;
+interface EvalRunsExportConfig {
+    /** Bearer key — tenant is resolved server-side from it. Reads TANGLE_API_KEY. */
+    apiKey?: string;
+    /** Intelligence base. Reads INTELLIGENCE_BASE env, else prod. */
+    base?: string;
+    /** Idempotency-Key header (e.g. the runId) — safe retries + upsert. */
+    idempotencyKey?: string;
+}
+interface EvalRunsExportResult {
+    ok: boolean;
+    status: number;
+    accepted: number;
+    rejected: Array<{
+        index: number;
+        reason: string;
+    }>;
 }
 /**
- * Polymorphic `result` field: `CoderOutput` when the underlying profile
- * is `'coder'`, a structurally-typed research output when `'researcher'`.
- * The MCP wire carries it as JSON either way.
- *
- * @experimental
+ * Ship self-improvement eval-run events to Tangle Intelligence. Unlike the
+ * best-effort span exporter, this RESOLVES with the ingest verdict (accepted /
+ * rejected per event) so a consumer's loop can assert its provenance landed.
+ * Throws only on a missing key or network failure.
  */
-type DelegationResultPayload = {
-    profile: 'coder';
-    output: CoderOutput;
-} | {
-    profile: 'researcher';
-    output: ResearchOutputShape;
-} | {
-    profile: 'ui-auditor';
-    output: UiAuditorDelegationOutput;
-};
+declare function exportEvalRuns(events: EvalRunEvent[], config?: EvalRunsExportConfig): Promise<EvalRunsExportResult>;
+
 /**
- * Wire-shape of a completed UI-audit delegation. The `findings` array
- * contains every finding persisted to the workspace during the run,
- * already enriched with `id` and `createdAt` by the writer. `workspaceDir`
- * is the absolute path to the workspace; `indexFile` is the workspace-
- * relative path to the regenerated index.md.
- *
  * @experimental
+ *
+ * Trace context propagation for MCP subprocess.
+ *
+ * When the MCP server is launched as a child process by a sandbox harness,
+ * the parent passes trace context via environment variables:
+ *
+ *   TRACE_ID=<current-run-trace-id>
+ *   PARENT_SPAN_ID=<span-that-dispatched-the-delegation>
+ *
+ * The MCP server reads these at startup and uses them as the root of its
+ * internal trace tree. All spans emitted by `runLoop` invocations inside
+ * the MCP are children of the parent's delegation span.
+ *
+ * When these env vars are absent, the MCP generates a fresh trace root —
+ * the server operates standalone without trace joining.
  */
-interface UiAuditorDelegationOutput {
-    workspaceDir: string;
-    indexFile: string;
-    findings: UiFinding[];
-    /** Total iterations the loop ran for this delegation. */
-    iterations: number;
-}
-/** @experimental */
-type UiAuditLensFilter = readonly UiLens[];
-/** Optional per-route capture spec the agent surfaces over the wire. */
-interface DelegateUiAuditRoute {
-    /** Stable route name (used in screenshot filenames + finding metadata). */
-    name: string;
-    /** Fully-qualified URL. */
-    url: string;
-    /** Viewports to capture at. Defaults to `[{ width: 1280, height: 800 }]`. */
-    viewports?: readonly {
-        width: number;
-        height: number;
-    }[];
-    /** Default false. Full-page captures for the broad lenses. */
-    fullPage?: boolean;
-    /** Selector to wait for before capture. */
-    waitFor?: string;
-}
-/** @experimental */
-interface DelegateUiAuditConfig {
-    /**
-     * Lenses to iterate. Default: every lens except `'other'`. Order is
-     * preserved — the driver iterates lens-by-lens.
-     */
-    lenses?: UiAuditLensFilter;
-    /** Maximum total iterations across all (lens × route) pairs. Default 33 (11 lenses × 3 routes). */
-    maxIterations?: number;
-    /** Maximum concurrent iterations within a single plan() round. Default 2. */
-    maxConcurrency?: number;
-    /** Free-form product context surfaced to the judge. */
-    productContext?: string;
-}
-/** @experimental */
-interface DelegateUiAuditArgs {
-    /** Workspace root for the audit (absolute path). */
-    workspaceDir: string;
-    /** Routes to audit. Must be non-empty. */
-    routes: readonly DelegateUiAuditRoute[];
-    /** Multi-tenant scope. */
-    namespace?: string;
-    config?: DelegateUiAuditConfig;
-}
-/** @experimental */
-interface DelegateUiAuditResult {
-    taskId: string;
-    estimatedDurationMs?: number;
+
+interface TraceContext {
+    /** Trace id inherited from the parent process, or a fresh one. */
+    traceId: string;
+    /** Parent span id from the delegation that launched this MCP server. */
+    parentSpanId?: string;
 }
 /**
- * Loose shape of a research output over the wire — the substrate cannot
- * import the `ResearchOutput` type from agent-knowledge without inducing
- * a dependency cycle, so the MCP layer treats it structurally.
+ * Read trace context from the process environment.
+ * Returns a context with inherited ids or a freshly generated root.
+ */
+declare function readTraceContextFromEnv(): TraceContext;
+/**
+ * Create a LoopTraceEmitter that:
+ *   1. Parents all spans under the inherited PARENT_SPAN_ID.
+ *   2. Exports spans to OTEL when OTEL_EXPORTER_OTLP_ENDPOINT is set.
  *
- * @experimental
+ * Returns both the emitter and the optional exporter handle for shutdown.
  */
-interface ResearchOutputShape {
-    items: unknown[];
-    citations: unknown[];
-    proposedWrites: unknown[];
-    gaps?: string[];
-    notes?: string;
-    [key: string]: unknown;
-}
-/** @experimental */
-interface DelegationStatusResult {
-    taskId: string;
-    profile: DelegationProfile;
-    status: DelegationStatus;
-    progress?: DelegationProgress;
-    result?: DelegationResultPayload;
-    error?: DelegationError;
-    costUsd?: number;
-    startedAt: string;
-    completedAt?: string;
-    /** Compact loop-trace span tree; present only when `includeTrace: true` was passed and spans were recorded. */
-    trace?: DelegationTraceSpan[];
-    /** Present when oldest trace spans were dropped to honor the trace caps. */
-    traceTruncated?: true;
-    /** Inherited trace identity recorded at submit — join key into the caller's trace. */
-    traceId?: string;
-    /** Caller span that dispatched the delegation, when one was inherited. */
-    parentSpanId?: string;
-}
-/** @experimental */
-interface DelegationHistoryArgs {
-    namespace?: string;
-    profile?: DelegationProfile;
-    /** ISO date — only delegations started at-or-after `since` are returned. */
-    since?: string;
-    /** Default 50. Hard cap 500. */
-    limit?: number;
-}
-/** @experimental */
-interface DelegationFeedbackSnapshot {
-    id: string;
-    score: number;
-    label?: FeedbackRating['label'];
-    by: DelegateFeedbackArgs['by'];
-    notes: string;
-    capturedAt: string;
-}
-/** @experimental */
-interface DelegationHistoryEntry {
-    taskId: string;
-    profile: DelegationProfile;
-    namespace?: string;
-    args: DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
-    status: DelegationStatus;
-    feedback?: DelegationFeedbackSnapshot[];
-    costUsd?: number;
-    startedAt: string;
-    completedAt?: string;
-    /**
-     * True when the record carries a journaled loop trace. History stays
-     * light by design — fetch the spans via
-     * `delegation_status { taskId, includeTrace: true }`.
-     */
-    hasTrace: boolean;
-    /** Inherited trace identity recorded at submit — join key into the caller's trace. */
-    traceId?: string;
-}
-/** @experimental */
-interface DelegationHistoryResult {
-    delegations: DelegationHistoryEntry[];
-}
+declare function createPropagatingTraceEmitter(ctx: TraceContext): {
+    emitter: LoopTraceEmitter;
+    exporter: OtelExporter | undefined;
+    context: TraceContext;
+};
+/**
+ * Build env vars to pass to a child MCP subprocess so it inherits the
+ * current trace context.
+ */
+declare function traceContextToEnv(ctx: TraceContext): Record<string, string>;
 
 /**
  * @experimental
@@ -1493,79 +1493,4 @@ interface SettleDetachedCoderTurnOptions {
  */
 declare function settleDetachedCoderTurn(turn: DetachedTurn, options: SettleDetachedCoderTurnOptions): Promise<CoderOutput>;
 
-/**
- * @experimental
- *
- * `createKbGate` — the valid-only knowledge-base growth gate, distilled from
- * physim's KB-research subsystem. A research-in-a-loop delegate (or any KB
- * writer) runs candidate facts through this before persisting, so the KB grows
- * with ONLY grounded facts — hallucinated, unsourced, or laundered claims are
- * vetoed at the gate.
- *
- * Fail-closed by construction: every judge must `accept`; the FIRST veto wins
- * and the fact is rejected. The non-negotiable floor (always on, can't be
- * disabled) is the **passage-present guard** — a fact's `verbatimPassage` MUST
- * literally appear in its `sourceText`. That single check kills the dominant
- * failure mode (a confident claim decoupled from any real source).
- *
- * Pure + dependency-free: it operates on fact candidates, not on a store, so it
- * composes with `@tangle-network/agent-knowledge` or any persistence layer
- * without importing it. The remediation policy (correct-on-veto vs
- * escalate-as-unverified) is the caller's — this returns the verdict; it never
- * drops a fact silently.
- */
-/** @experimental A fact proposed for the KB, with its grounding. */
-interface FactCandidate {
-    /** The atomic claim text. */
-    claim: string;
-    /** Optional extracted value (number or string) the claim asserts. */
-    value?: string | number;
-    /** Verbatim span lifted from the source that backs the claim. */
-    verbatimPassage: string;
-    /** The raw source text the passage must be grounded in. */
-    sourceText: string;
-    /** Where the fact claims to come from — checked for circular/self citations. */
-    citation?: string;
-}
-/** @experimental */
-interface FactJudgeVerdict {
-    accept: boolean;
-    reason?: string;
-}
-/** @experimental A pluggable fact validator. Throw is NOT allowed — return a
- *  verdict; a thrown judge is a programmer error, not a veto. */
-interface FactJudge {
-    name: string;
-    judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>;
-}
-/** @experimental */
-interface KbGateResult {
-    accepted: boolean;
-    /** Name of the judge that vetoed; undefined when accepted. */
-    vetoedBy?: string;
-    reason?: string;
-}
-/** @experimental */
-interface CreateKbGateOptions {
-    /** Extra judges appended after the built-in floor (e.g. an LLM judge). */
-    judges?: FactJudge[];
-    /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */
-    minPassageChars?: number;
-    /**
-     * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,
-     * `'cad_params'`, `'requirements'`). A citation naming one is circular
-     * (laundering) — the fact cites a derived artifact, not a real source.
-     * Default `[]` (no circular check unless the consumer declares its kinds).
-     */
-    selfArtifactKinds?: string[];
-}
-/**
- * @experimental
- *
- * Build a fail-closed KB gate. The returned function runs the built-in floor
- * (passage-non-empty → passage-present → value-in-passage → no-circular-citation)
- * then any consumer judges, returning on the first veto.
- */
-declare function createKbGate(options?: CreateKbGateOptions): (candidate: FactCandidate) => Promise<KbGateResult>;
-
-export { type DetachedSessionRefParts as $, type DelegateRunCtx as A, type DelegateUiAuditConfig as B, type CoderReviewer as C, type DelegateCodeArgs as D, type DelegateUiAuditRoute as E, type FactCandidate as F, type DelegationError as G, type DelegationHistoryEntry as H, DelegationPersistenceError as I, type DelegationProfile as J, type DelegationProgress as K, type DelegationRecord as L, type DelegationResultPayload as M, type DelegationResumeContext as N, type DelegationResumeDriver as O, type DelegationResumeTick as P, type DelegationRunContext as Q, type ResearcherDelegate as R, DelegationStateCorruptError as S, type TraceContext as T, type UiAuditorDelegate as U, type DelegationStatus as V, type DelegationStore as W, type DelegationTaskQueueOptions as X, type DelegationTraceCaps as Y, type DelegationTraceCollector as Z, type DelegationTraceSpan as _, type CoderWinnerSelection as a, type DetachedTurn as a0, type DriveTurnCapableBox as a1, type DriveTurnResumeDriverOptions as a2, type DriveTurnTick as a3, type FactJudge as a4, type FactJudgeVerdict as a5, type FeedbackRating as a6, type FeedbackRefersTo as a7, FileDelegationStore as a8, type FileDelegationStoreOptions as a9, runDetachedTurn as aA, settleDetachedCoderTurn as aB, traceContextToEnv as aC, type EvalRunEvent as aD, type EvalRunGeneration as aE, type EvalRunsExportConfig as aF, type EvalRunsExportResult as aG, INTELLIGENCE_WIRE_VERSION as aH, type LoopSpanNode as aI, type OtelAttribute as aJ, type OtelExportConfig as aK, type OtelExporter as aL, type OtelSpan as aM, buildLoopOtelSpans as aN, buildLoopSpanNodes as aO, createOtelExporter as aP, exportEvalRuns as aQ, loopEventToOtelSpan as aR, type FleetWorkspaceExecutorOptions as aa, InMemoryDelegationStore as ab, type KbGateResult as ac, type ResearchOutputShape as ad, type RunDetachedTurnOptions as ae, type SettleDetachedCoderTurnOptions as af, type SiblingSandboxExecutorOptions as ag, type SubmitInput as ah, type SubmitOutput as ai, type UiAuditorDelegationOutput as aj, buildDelegationTraceSpans as ak, capDelegationTrace as al, coderTaskFromArgs as am, composeLoopTraceEmitters as an, createDefaultCoderDelegate as ao, createDelegationTraceCollector as ap, createDriveTurnResumeDriver as aq, createFleetWorkspaceExecutor as ar, createKbGate as as, createPropagatingTraceEmitter as at, createSiblingSandboxExecutor as au, detachedTurnEvents as av, formatDetachedSessionRef as aw, hashIdempotencyInput as ax, parseDetachedSessionRef as ay, readTraceContextFromEnv as az, type CreateKbGateOptions as b, type FleetHandle as c, type DelegationExecutor as d, type DelegateFeedbackArgs as e, type DelegationFeedbackSnapshot as f, DelegationTaskQueue as g, type CoderDelegate as h, type DelegateCodeResult as i, type DelegateFeedbackResult as j, type ResearchSource as k, type DelegateResearchArgs as l, type DelegateResearchResult as m, type DelegateUiAuditArgs as n, type DelegateUiAuditResult as o, type DelegationHistoryResult as p, type DelegationHistoryArgs as q, type DelegationStatusResult as r, type DelegationStatusArgs as s, type CappedDelegationTrace as t, type CoderReview as u, type CreateDefaultCoderDelegateOptions as v, DELEGATION_TRACE_MAX_BYTES as w, DELEGATION_TRACE_MAX_SPANS as x, type DelegateCodeConfig as y, type DelegateResearchConfig as z };
+export { type DriveTurnCapableBox as $, type DelegateUiAuditRoute as A, type DelegationError as B, type CoderReviewer as C, type DelegateCodeArgs as D, type DelegationHistoryEntry as E, type FleetHandle as F, DelegationPersistenceError as G, type DelegationProfile as H, type DelegationProgress as I, type DelegationRecord as J, type DelegationResultPayload as K, type DelegationResumeContext as L, type DelegationResumeDriver as M, type DelegationResumeTick as N, type DelegationRunContext as O, DelegationStateCorruptError as P, type DelegationStatus as Q, type ResearcherDelegate as R, type DelegationStore as S, type TraceContext as T, type UiAuditorDelegate as U, type DelegationTaskQueueOptions as V, type DelegationTraceCaps as W, type DelegationTraceCollector as X, type DelegationTraceSpan as Y, type DetachedSessionRefParts as Z, type DetachedTurn as _, type CoderWinnerSelection as a, type DriveTurnResumeDriverOptions as a0, type DriveTurnTick as a1, type FeedbackRating as a2, type FeedbackRefersTo as a3, FileDelegationStore as a4, type FileDelegationStoreOptions as a5, type FleetWorkspaceExecutorOptions as a6, InMemoryDelegationStore as a7, type ResearchOutputShape as a8, type RunDetachedTurnOptions as a9, type EvalRunsExportResult as aA, INTELLIGENCE_WIRE_VERSION as aB, type LoopSpanNode as aC, type OtelAttribute as aD, type OtelExportConfig as aE, type OtelExporter as aF, type OtelSpan as aG, buildLoopOtelSpans as aH, buildLoopSpanNodes as aI, createOtelExporter as aJ, exportEvalRuns as aK, loopEventToOtelSpan as aL, type SettleDetachedCoderTurnOptions as aa, type SiblingSandboxExecutorOptions as ab, type SubmitInput as ac, type SubmitOutput as ad, type UiAuditorDelegationOutput as ae, buildDelegationTraceSpans as af, capDelegationTrace as ag, coderTaskFromArgs as ah, composeLoopTraceEmitters as ai, createDefaultCoderDelegate as aj, createDelegationTraceCollector as ak, createDriveTurnResumeDriver as al, createFleetWorkspaceExecutor as am, createPropagatingTraceEmitter as an, createSiblingSandboxExecutor as ao, detachedTurnEvents as ap, formatDetachedSessionRef as aq, hashIdempotencyInput as ar, parseDetachedSessionRef as as, readTraceContextFromEnv as at, runDetachedTurn as au, settleDetachedCoderTurn as av, traceContextToEnv as aw, type EvalRunEvent as ax, type EvalRunGeneration as ay, type EvalRunsExportConfig as az, type DelegateFeedbackArgs as b, type DelegationFeedbackSnapshot as c, DelegationTaskQueue as d, type CoderDelegate as e, type DelegationExecutor as f, type DelegateCodeResult as g, type DelegateFeedbackResult as h, type ResearchSource as i, type DelegateResearchArgs as j, type DelegateResearchResult as k, type DelegateUiAuditArgs as l, type DelegateUiAuditResult as m, type DelegationHistoryResult as n, type DelegationHistoryArgs as o, type DelegationStatusResult as p, type DelegationStatusArgs as q, type CappedDelegationTrace as r, type CoderReview as s, type CreateDefaultCoderDelegateOptions as t, DELEGATION_TRACE_MAX_BYTES as u, DELEGATION_TRACE_MAX_SPANS as v, type DelegateCodeConfig as w, type DelegateResearchConfig as x, type DelegateRunCtx as y, type DelegateUiAuditConfig as z };