@tangle-network/agent-runtime 0.48.0 → 0.50.0

package/dist/kb-gate-CHAyt4aI.d.ts

@@ -0,0 +1,1571 @@
+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 { 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
+ *
+ * Compact loop-trace tee for the delegation journal.
+ *
+ * The OTEL exporter ({@link createPropagatingTraceEmitter}) is a no-op
+ * without `OTEL_EXPORTER_OTLP_ENDPOINT`, which leaves delegated work streams
+ * dark in practice. This module derives the same loop → round → branch span
+ * tree (via the shared {@link buildLoopSpanNodes} builder) into a small,
+ * JSON-safe shape persisted directly on the `DelegationRecord` — observable
+ * through `delegation_status` with no collector infrastructure. Both sinks
+ * coexist: the OTEL export path is unchanged.
+ *
+ * Payload discipline: a record's trace is hard-capped (spans + serialized
+ * bytes). Past the cap the OLDEST spans are dropped and the record carries a
+ * `traceTruncated: true` marker — truncation is never silent.
+ */
+
+/**
+ * One span of a delegation's compact trace. Flat (parent linkage by id), all
+ * values JSON-safe scalars — `FileDelegationStore` round-trips records
+ * through `JSON.stringify`. `meta` carries the span's attributes (GenAI
+ * semconv keys + `tangle.loop.*` extensions) exactly as the OTEL sink emits
+ * them, so a consumer can re-export journal traces losslessly.
+ *
+ * @experimental
+ */
+interface DelegationTraceSpan {
+    spanId: string;
+    /** Absent on the tree root. */
+    parentSpanId?: string;
+    /** `'loop'` | `'loop.round'` | `'loop.iteration'` (or a sink-specific name). */
+    name: string;
+    /** Topology level: loop root, plan round, or iteration branch. */
+    kind: 'loop' | 'round' | 'branch';
+    startMs: number;
+    endMs: number;
+    meta?: Record<string, string | number | boolean>;
+}
+/** Default cap on spans retained per delegation record. @experimental */
+declare const DELEGATION_TRACE_MAX_SPANS = 512;
+/** Default cap on the serialized trace payload per record, in bytes. @experimental */
+declare const DELEGATION_TRACE_MAX_BYTES: number;
+/** @experimental */
+interface DelegationTraceCaps {
+    /** Default {@link DELEGATION_TRACE_MAX_SPANS}. */
+    maxSpans?: number;
+    /** Default {@link DELEGATION_TRACE_MAX_BYTES}. Approximate — measured as the
+     *  sum of per-span `JSON.stringify` lengths. */
+    maxBytes?: number;
+}
+/** @experimental */
+interface CappedDelegationTrace {
+    trace: DelegationTraceSpan[];
+    /** True when oldest spans were dropped to honor the caps. */
+    truncated: boolean;
+}
+/**
+ * Derive the compact span tree for ONE loop run from its buffered
+ * `LoopTraceEvent` stream. Same reconstruction as the OTEL exporter
+ * ({@link buildLoopSpanNodes}); tolerates partial streams.
+ *
+ * @experimental
+ */
+declare function buildDelegationTraceSpans(events: ReadonlyArray<LoopTraceEvent>): DelegationTraceSpan[];
+/**
+ * Enforce the trace caps over an ordered (oldest-first) span list. Drops the
+ * OLDEST spans first and reports `truncated: true` when anything was dropped;
+ * the newest span always survives, so a non-empty input never caps to empty.
+ * Dropping a parent may orphan surviving children's `parentSpanId` references
+ * — acceptable for the flat journal shape; consumers treat unresolved parents
+ * as roots.
+ *
+ * @experimental
+ */
+declare function capDelegationTrace(spans: ReadonlyArray<DelegationTraceSpan>, caps?: DelegationTraceCaps): CappedDelegationTrace;
+/**
+ * Per-delegation trace collector. Buffers `LoopTraceEvent`s per runId
+ * (mirroring the OTEL emitter's buffering) and hands the derived compact
+ * spans to `onSpans` when a run reaches `loop.ended`. `settle()` drains runs
+ * that never ended — a hard-aborted loop still leaves its partial tree in the
+ * journal, unlike the OTEL path which drops it.
+ *
+ * @experimental
+ */
+interface DelegationTraceCollector {
+    emitter: LoopTraceEmitter;
+    /** Flush buffered events of runs that never reached `loop.ended`. */
+    settle(): void;
+}
+/** @experimental */
+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;
+
+/**
+ * OTEL span exporter — streams LoopTraceEvents to an OTLP/HTTP collector.
+ *
+ * Reads OTEL_EXPORTER_OTLP_ENDPOINT + OTEL_EXPORTER_OTLP_HEADERS from env
+ * when no explicit config is given. Keeps the runtime dep-free from
+ * @opentelemetry/sdk-trace-base — minimal OTLP/JSON serializer.
+ *
+ * The exporter accepts both raw OtelSpan objects and LoopTraceEvents
+ * (which get converted to OTLP spans automatically).
+ */
+interface OtelExportConfig {
+    /** OTLP endpoint. Reads OTEL_EXPORTER_OTLP_ENDPOINT env by default. */
+    endpoint?: string;
+    /** OTLP headers. Reads OTEL_EXPORTER_OTLP_HEADERS env by default. */
+    headers?: Record<string, string>;
+    /** Batch size before flush. Default 64. */
+    batchSize?: number;
+    /** Flush interval ms. Default 5000. */
+    flushIntervalMs?: number;
+    /** Resource attributes stamped on every export. */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Service name. Default 'agent-runtime'. */
+    serviceName?: string;
+}
+interface OtelExporter {
+    /** Export a span. */
+    exportSpan(span: OtelSpan): void;
+    /** Force flush pending spans. */
+    flush(): Promise<void>;
+    /** Shutdown cleanly. */
+    shutdown(): Promise<void>;
+}
+interface OtelSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind?: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: OtelAttribute[];
+    status?: {
+        code: number;
+        message?: string;
+    };
+}
+interface OtelAttribute {
+    key: string;
+    value: {
+        stringValue?: string;
+        intValue?: string;
+        doubleValue?: number;
+        boolValue?: boolean;
+    };
+}
+/**
+ * Create an OTEL exporter. Returns undefined when no endpoint is configured.
+ */
+declare function createOtelExporter(config?: OtelExportConfig): OtelExporter | undefined;
+/**
+ * Convert a LoopTraceEvent into an OtelSpan for export.
+ */
+declare function loopEventToOtelSpan(event: {
+    kind: string;
+    runId: string;
+    timestamp: number;
+    payload: object;
+}, traceId: string, parentSpanId?: string): OtelSpan;
+/**
+ * Sink-neutral node in a reconstructed loop span tree. The root node's
+ * `parentSpanId` is `undefined` — sinks decide how to parent it (the OTEL
+ * mapper attaches the inherited delegation span; the delegation journal
+ * leaves it as the tree root).
+ */
+interface LoopSpanNode {
+    spanId: string;
+    parentSpanId?: string;
+    /** `'loop'` | `'loop.round'` | `'loop.iteration'`. */
+    name: string;
+    /** Topology level: loop root, plan round, or iteration branch. */
+    kind: 'loop' | 'round' | 'branch';
+    startMs: number;
+    endMs: number;
+    attrs: Record<string, string | number | boolean>;
+    /** True when the iteration carried an error — maps to OTEL status code 2. */
+    error: boolean;
+}
+/**
+ * Build a nested, real-duration OTLP span tree for ONE loop run from its full
+ * ordered `LoopTraceEvent` stream. Unlike `loopEventToOtelSpan` (one flat,
+ * zero-duration span per event), this reconstructs the topology hierarchy a
+ * GenAI trace viewer renders natively:
+ *
+ *   loop (invoke_workflow)
+ *     └─ loop.round[k] (invoke_workflow)   ← tangle.loop.move.{kind,width,rationale}
+ *          ├─ loop.iteration[i] (invoke_agent)  ← gen_ai.agent.name + usage + verdict + placement
+ *          └─ …
+ *
+ * Attributes follow the current GenAI semconv (`gen_ai.*`) where they apply and
+ * a namespaced `tangle.loop.*` / `tangle.cost.usd` extension for topology /
+ * verdict / placement / cost (not yet standardized). Pure: feed it a buffered
+ * per-runId event array (e.g. flushed on `loop.ended`) and export the result.
+ */
+declare function buildLoopOtelSpans(events: ReadonlyArray<{
+    kind: string;
+    runId: string;
+    timestamp: number;
+    payload: object;
+}>, traceId: string, rootParentSpanId?: string): OtelSpan[];
+/**
+ * Sink-neutral core behind {@link buildLoopOtelSpans}: reconstruct the
+ * loop → round → branch span tree from one run's ordered `LoopTraceEvent`
+ * stream. Consumed by the OTEL mapper above and by the MCP delegation
+ * journal's compact trace tee — one topology reconstruction, two sinks.
+ * Tolerates partial streams (a run that never reached `loop.ended` closes
+ * at the last observed event's timestamp).
+ */
+declare function buildLoopSpanNodes(events: ReadonlyArray<{
+    kind: string;
+    runId: string;
+    timestamp: number;
+    payload: object;
+}>): LoopSpanNode[];
+/** Wire version the eval-runs ingest enforces (X-Tangle-Wire-Version + body). */
+declare const INTELLIGENCE_WIRE_VERSION = "2026-05-26.v1";
+interface EvalRunGeneration {
+    /** 0-based ordinal of this generation within the run (required by ingest). */
+    index: number;
+    /** Identity of the proposed surface change (content-addressed hash). */
+    surfaceHash: string;
+    /** Arbitrary provenance for this generation (rationale, evidence, source). */
+    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;
+}
+/** @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
+ *
+ * State machine for async MCP delegations:
+ *
+ *   pending → running → completed | failed
+ *           ↘ cancelled (from any non-terminal state via cancel())
+ *
+ * Each `submit` returns a `taskId` immediately and kicks the work off in the
+ * background. The work function receives an `AbortSignal` the queue fires
+ * when `cancel(taskId)` is called. The queue does NOT supervise runtime
+ * timeouts — the underlying `runLoop` driver / sandbox imposes those.
+ *
+ * Idempotency: callers may supply an `idempotencyKey` (hash of the input).
+ * A duplicate `submit` with a known key returns the existing task instead of
+ * starting a new one. Mutated input → different key → different task.
+ *
+ * Durability: the working set lives in memory (reads stay synchronous) and
+ * every record mutation is journaled through a `DelegationStore`. The default
+ * `InMemoryDelegationStore` keeps today's semantics — a process restart drops
+ * all state. Construct via `DelegationTaskQueue.restore({ store })` with a
+ * `FileDelegationStore` to reload prior records on startup: terminal records
+ * stay queryable, in-flight records either re-attach through the
+ * `resumeDelegate` seam (when they carry a `detachedSessionRef`) or fail
+ * loud with a driver-restart error so `delegation_status` tells the truth.
+ */
+
+type AnyDelegateArgs = DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
+/**
+ * Must be JSON-safe end to end (`args`, `result`, `error`, `feedback`) —
+ * persistent stores round-trip records through `JSON.stringify`.
+ *
+ * @experimental
+ */
+interface DelegationRecord {
+    taskId: string;
+    profile: DelegationProfile;
+    namespace?: string;
+    args: AnyDelegateArgs;
+    status: DelegationStatus;
+    progress?: DelegationProgress;
+    result?: DelegationResultPayload;
+    error?: DelegationError;
+    costUsd?: number;
+    startedAt: string;
+    completedAt?: string;
+    /** Sha-prefix hash of the canonical input — used for idempotency lookup. */
+    idempotencyKey?: string;
+    /**
+     * Caller-generated deterministic id of a detached run (e.g. the sandbox
+     * session id a single-tick driver resumes by). Presence is what makes a
+     * restored in-flight record resumable via `resumeDelegate`; without it a
+     * restart settles the record as failed.
+     */
+    detachedSessionRef?: string;
+    /** Feedback events keyed by this delegation's taskId. */
+    feedback: DelegationFeedbackSnapshot[];
+    /**
+     * Compact loop-trace span tree teed from the delegation's run, oldest
+     * spans first. Appended when a delegated loop reaches `loop.ended` and
+     * settled (partial buffers included) at the terminal transition. Capped
+     * via `capDelegationTrace` — see `traceTruncated`.
+     */
+    trace?: DelegationTraceSpan[];
+    /** Present when oldest trace spans were dropped to honor the trace caps. */
+    traceTruncated?: true;
+    /**
+     * Inherited trace identity (the queue's `traceContext` at submit time —
+     * typically `readTraceContextFromEnv()`), distinct from the span payload:
+     * a journal consumer joins records into the parent trace by these ids
+     * without parsing spans. Restored records keep their persisted identity.
+     */
+    traceId?: string;
+    /** Caller span that dispatched the delegation, when one was inherited. */
+    parentSpanId?: string;
+}
+/** @experimental */
+interface SubmitInput<Args extends AnyDelegateArgs> {
+    profile: DelegationProfile;
+    args: Args;
+    namespace?: string;
+    idempotencyKey?: string;
+    /**
+     * Records the detached-run resume key on the new record. The submitted
+     * `run` function still executes in-process exactly as without it — the
+     * ref only matters after a restart, when `DelegationTaskQueue.restore`
+     * hands it to the `resumeDelegate` seam instead of failing the record.
+     */
+    detachedSessionRef?: string;
+    /**
+     * Runs the underlying delegation. The queue passes a fresh `AbortSignal`
+     * and a `report` channel for incremental progress updates. The function
+     * MUST resolve with the typed `DelegationResultPayload['output']`; the
+     * queue wraps it with the profile tag.
+     */
+    run: (ctx: DelegationRunContext) => Promise<DelegationResultPayload['output']>;
+}
+/** @experimental Context handed to a `SubmitInput.run` function. */
+interface DelegationRunContext {
+    signal: AbortSignal;
+    report(progress: DelegationProgress): void;
+    /** The `detachedSessionRef` recorded at submit, when one was supplied. */
+    detachedSessionRef?: string;
+    /**
+     * Replace the record's detached-run resume key — the detached dispatch path
+     * calls this once the sandbox id is known so the persisted ref names a
+     * resolvable box. Ignored after the record settles (a cancel racing the
+     * rebind is legitimate; the ref no longer matters then). Throws on an empty
+     * ref — erasing the resume key would silently make the record unresumable.
+     */
+    updateDetachedSessionRef(ref: string): void;
+    /**
+     * Per-delegation loop-trace sink, always provided by the queue. Events
+     * emitted here are journaled onto the record as a compact span tree
+     * (`record.trace`) when each loop run ends and at the delegation's
+     * terminal transition. Delegates forward it into their `runLoop` ctx,
+     * composed with any process-wide OTEL emitter
+     * (`composeLoopTraceEmitters`). Optional in the type so consumer-built
+     * contexts stay source-compatible.
+     */
+    traceEmitter?: LoopTraceEmitter;
+}
+/** @experimental */
+interface SubmitOutput {
+    taskId: string;
+    /** True when a prior matching `idempotencyKey` returned an existing record. */
+    reused: boolean;
+}
+/**
+ * One observation of a detached run, mapped 1:1 from a single-tick driver
+ * (e.g. the sandbox SDK's `driveTurn`, which reports
+ * completed | running | failed per pass). `running` schedules another tick
+ * after `intervalMs`; `completed` / `failed` settle the record.
+ *
+ * @experimental
+ */
+type DelegationResumeTick = {
+    state: 'running';
+} | {
+    state: 'completed';
+    output: DelegationResultPayload['output'];
+    costUsd?: number;
+} | {
+    state: 'failed';
+    error: DelegationError;
+};
+/** @experimental */
+interface DelegationResumeContext {
+    /** Fired by `cancel(taskId)`; the driver should stop the remote run when it can. */
+    signal: AbortSignal;
+    report(progress: DelegationProgress): void;
+}
+/**
+ * Re-attaches restored in-flight records to their detached runs. The queue
+ * calls `tick` repeatedly — it never awaits a whole run — so the driver can
+ * be a thin wrapper over a one-pass primitive: resolve the run named by
+ * `detachedSessionRef`, advance/poll it once, report where it stands. A
+ * thrown error settles the record as failed; `failed` ticks are treated as
+ * terminal and are not retried.
+ *
+ * @experimental
+ */
+interface DelegationResumeDriver {
+    tick(task: {
+        record: DelegationRecord;
+        detachedSessionRef: string;
+    }, ctx: DelegationResumeContext): Promise<DelegationResumeTick>;
+    /** Delay between `running` ticks, in milliseconds. Default 5000. */
+    intervalMs?: number;
+}
+/** @experimental */
+interface DelegationTaskQueueOptions {
+    /** ID generator override; default `randomTaskId`. */
+    generateId?: () => string;
+    /** Clock override; default `() => new Date().toISOString()`. */
+    now?: () => string;
+    /**
+     * Journal for record mutations and the `restore()` load source. Default
+     * `InMemoryDelegationStore` — observably identical to an unjournaled
+     * queue. Pass a `FileDelegationStore` through
+     * `DelegationTaskQueue.restore` for state that survives a restart;
+     * constructing with `new` never loads prior state.
+     */
+    store?: DelegationStore;
+    /** Resume seam for restored in-flight records that carry a `detachedSessionRef`. */
+    resumeDelegate?: DelegationResumeDriver;
+    /**
+     * Maximum number of terminal (completed | failed | cancelled) records
+     * retained; the oldest (by `completedAt`) are evicted from memory and
+     * store once the cap is exceeded. Default unbounded.
+     */
+    maxTerminalRecords?: number;
+    /**
+     * Observes the first store failure. After it fires, the queue refuses
+     * new submissions and `flush()` rejects with the same error. Default:
+     * rethrow on a microtask — an unhandled crash — because silently
+     * degrading durable mode to memory-only would lie to the caller.
+     */
+    onPersistError?: (error: DelegationPersistenceError) => void;
+    /**
+     * Inherited trace identity stamped on every submitted record
+     * (`traceId` / `parentSpanId`). The bin passes
+     * `readTraceContextFromEnv()` so journal consumers can join delegation
+     * records into the caller's trace. Restored records keep the identity
+     * they were persisted with.
+     */
+    traceContext?: TraceContext;
+}
+/** @experimental */
+declare class DelegationTaskQueue {
+    private readonly records;
+    private readonly controllers;
+    private readonly byIdempotencyKey;
+    private readonly generateId;
+    private readonly now;
+    private readonly store;
+    private readonly resumeDelegate?;
+    private readonly maxTerminalRecords;
+    private readonly onPersistError;
+    private readonly traceContext;
+    private persistTail;
+    private persistFailure;
+    constructor(options?: DelegationTaskQueueOptions);
+    /**
+     * Construct a queue from previously-persisted state. Loads every record
+     * from `options.store`, rebuilds the idempotency index (so a re-submitted
+     * identical task returns the prior taskId and its terminal state), then:
+     *
+     *   - terminal records stay queryable via `status()` / `history()`
+     *   - in-flight records with a `detachedSessionRef` re-attach through
+     *     `options.resumeDelegate` and report `running`
+     *   - other in-flight records settle as failed — their driver died with
+     *     the previous process and the result is unrecoverable
+     *
+     * The retention cap applies to the loaded set as well.
+     */
+    static restore(options?: DelegationTaskQueueOptions): Promise<DelegationTaskQueue>;
+    /**
+     * Kick off a delegation in the background. Returns immediately. The
+     * `taskId` is queryable via `status` once this method returns. Throws
+     * the recorded `DelegationPersistenceError` once the store has failed —
+     * the queue does not accept work it cannot journal.
+     */
+    submit<Args extends AnyDelegateArgs>(input: SubmitInput<Args>): SubmitOutput;
+    /**
+     * Snapshot the current state of a delegation. Returns `undefined` for
+     * unknown ids so callers can distinguish missing from terminal.
+     * `includeTrace` attaches the journaled loop-trace span tree — off by
+     * default so status polls stay light.
+     */
+    status(taskId: string, opts?: {
+        includeTrace?: boolean;
+    }): DelegationStatusResult | undefined;
+    /**
+     * Abort an in-flight delegation. Returns `false` if the task is unknown
+     * or already terminal. The underlying `run` function MUST honor the
+     * abort signal for the cancel to take effect; the queue marks the
+     * record `cancelled` regardless so a misbehaving runner cannot pin the
+     * UI on `running` forever.
+     */
+    cancel(taskId: string): boolean;
+    /**
+     * Append a feedback event to the matching delegation. Returns `false`
+     * when `ref` does not name a known taskId — the caller should still
+     * record the feedback through a different surface (artifact/outcome
+     * kinds are not queue-bound).
+     */
+    attachFeedback(taskId: string, snapshot: DelegationFeedbackSnapshot): boolean;
+    /**
+     * Query the recorded delegations. Returns entries newest-first (by
+     * `startedAt`), truncated to `limit`.
+     */
+    history(args?: DelegationHistoryArgs): DelegationHistoryEntry[];
+    /**
+     * Await every journal write issued so far. Rejects with the recorded
+     * `DelegationPersistenceError` when any of them failed. Call before
+     * handing the store's backing file to another process.
+     */
+    flush(): Promise<void>;
+    /** Test-only — number of in-flight (non-terminal) records. */
+    inflightCount(): number;
+    private execute;
+    private appendTrace;
+    private rehydrate;
+    private startResume;
+    private driveResume;
+    /**
+     * Journal the resumed segment of a detached run as one compact span. The
+     * resume driver re-attaches after a process restart, so the original
+     * process's loop events are gone — this span records the post-restart
+     * observation window (re-attach → terminal tick) under the
+     * `'detached-resume'` driver tag, keeping restored delegations observable
+     * in the journal alongside trace-carrying live runs.
+     */
+    private appendResumeSpan;
+    private persist;
+    private persistRemoval;
+    private failPersistence;
+    private enforceRetention;
+}
+/**
+ * Best-effort stable hash for use as `idempotencyKey`. Not cryptographic;
+ * collisions only affect dedupe, never correctness.
+ *
+ * @experimental
+ */
+declare function hashIdempotencyInput(value: unknown): string;
+
+/**
+ * @experimental
+ *
+ * Detached delegation turns over the sandbox SDK's `driveTurn` primitive.
+ *
+ * Two halves of one story:
+ *
+ *   - {@link runDetachedTurn} — the dispatch side. A single-session delegate
+ *     (single-variant coder / researcher) acquires a box, binds the sandbox id
+ *     into the record's `detachedSessionRef`, then advances the turn with
+ *     repeated `driveTurn` ticks instead of holding a live SSE stream. The
+ *     session id is deterministic and supplied at submit time, so a process
+ *     crash between ticks loses nothing — the turn keeps running in the box.
+ *
+ *   - {@link createDriveTurnResumeDriver} — the resume side. A
+ *     `DelegationResumeDriver` that re-attaches restored in-flight records to
+ *     their detached runs: parse the record's ref, resolve the box, advance the
+ *     turn one `driveTurn` pass per `tick()`, and map the SDK's three states
+ *     (`completed | running | failed`) onto `DelegationResumeTick`.
+ *
+ * Both sides type the box structurally ({@link DriveTurnCapableBox}) so tests
+ * inject fakes and the module never requires the sandbox SDK at runtime — the
+ * SDK stays an optional peer, exactly like the executors' `SandboxClient` seam.
+ *
+ * Tradeoffs of detached mode (why it is opt-in, not the default): a detached
+ * turn yields one terminal payload instead of a live event stream, so kernel
+ * token/cost aggregation is not produced for that turn. The trace sinks still
+ * observe detached work — `runDetachedTurn` synthesizes a single-iteration
+ * loop event stream (see `RunDetachedTurnOptions.traceEmitter`) so the span
+ * topology joins the inherited trace context, with cost/tokens reported as 0
+ * under the `'detached-turn'` driver tag. Multi-variant fanout stays on the
+ * streaming `runLoop` path — N concurrent sessions cannot be expressed as one
+ * resume key, and winner selection needs every candidate.
+ */
+
+/**
+ * Structural mirror of the sandbox SDK's `TurnDriveResult` (>= 0.6).
+ * Discriminated on `state`; `failed` is terminal and deterministic per the
+ * SDK contract — re-invoking with the same ids returns the same outcome.
+ *
+ * @experimental
+ */
+type DriveTurnTick = {
+    state: 'completed';
+    text: string;
+    result: Record<string, unknown>;
+} | {
+    state: 'running';
+    startedAt?: Date;
+    elapsedMs?: number;
+} | {
+    state: 'failed';
+    error: string;
+};
+/**
+ * The box surface detached turns need. `SandboxInstance`
+ * (`@tangle-network/sandbox` >= 0.6) satisfies it structurally; tests pass
+ * in-memory fakes. `_sessionCancel` is the SDK's remote-cancellation surface —
+ * optional here because older SDKs / fakes may not expose it; when present it
+ * is invoked on abort so the remote run actually stops.
+ *
+ * @experimental
+ */
+interface DriveTurnCapableBox {
+    driveTurn(message: string, opts: {
+        sessionId: string;
+        turnId?: string;
+        wallCapMs?: number;
+    }): Promise<DriveTurnTick>;
+    _sessionCancel?(id: string): Promise<void>;
+}
+/**
+ * Decoded `DelegationRecord.detachedSessionRef`. `sandboxId` is absent between
+ * submit and box acquisition — a record restored in that window is not
+ * resumable (there is no box to resume on) and the resume driver fails it
+ * loud rather than dispatching onto a guessed box.
+ *
+ * @experimental
+ */
+interface DetachedSessionRefParts {
+    sessionId: string;
+    sandboxId?: string;
+}
+/**
+ * Encode ref parts into the JSON-safe string stored on the record:
+ * `session=<id>` before the box exists, `sandbox=<id>;session=<id>` once
+ * bound. Ids must not contain the `;`/`=` delimiters.
+ *
+ * @experimental
+ */
+declare function formatDetachedSessionRef(parts: DetachedSessionRefParts): string;
+/** @experimental Inverse of {@link formatDetachedSessionRef}; throws `ValidationError` on malformed input. */
+declare function parseDetachedSessionRef(raw: string): DetachedSessionRefParts;
+/** @experimental The terminal payload of a finished detached turn. */
+interface DetachedTurn {
+    /** Final assistant text. */
+    text: string;
+    /** The SDK's cached AgentExecutionResult-shape record for the turn. */
+    result: Record<string, unknown>;
+}
+/**
+ * Synthesize the terminal event array a detached turn settles through. Shaped
+ * so the existing event-stream output adapters (coder, researcher) parse it:
+ * `data.result` for adapters that read a structured terminal record, `data.text`
+ * for adapters that scan assistant text for the fenced result block.
+ *
+ * @experimental
+ */
+declare function detachedTurnEvents(sessionId: string, turn: DetachedTurn): SandboxEvent[];
+/** @experimental */
+interface RunDetachedTurnOptions {
+    /** Sandbox client used to acquire the box (the delegate's executor client). */
+    client: SandboxClient;
+    /** Profile + overrides for box acquisition — same spec the streaming path uses. */
+    spec: AgentRunSpec<unknown>;
+    /** The full turn prompt; consumed by `driveTurn`'s dispatch leg. */
+    prompt: string;
+    /** Deterministic resume key, minted at submit time (`parseDetachedSessionRef(ref).sessionId`). */
+    sessionId: string;
+    /**
+     * Called once the box exists, with its sandbox id. Callers persist
+     * `formatDetachedSessionRef({ sandboxId, sessionId })` onto the record here so
+     * a restart can resolve the box again.
+     */
+    bindSandbox(sandboxId: string): void;
+    signal: AbortSignal;
+    report(progress: DelegationProgress): void;
+    /** Delay between `running` ticks (ms). Default 5000. */
+    tickIntervalMs?: number;
+    /** Wall-clock cap forwarded to `driveTurn` — the SDK cancels and fails a session past it. */
+    wallCapMs?: number;
+    /**
+     * Loop-trace sink. When set, the detached turn synthesizes a
+     * single-iteration loop span tree (`runId` = `sessionId`, driver
+     * `'detached-turn'`) so trace-context inheritance survives the detached
+     * path — the same events the streaming `runLoop` path would emit, minus
+     * per-token telemetry: `driveTurn` yields one terminal payload, so token
+     * and cost figures are structurally unavailable and reported as 0 under
+     * this driver tag.
+     */
+    traceEmitter?: LoopTraceEmitter;
+    /** Physical placement stamped on the synthesized dispatch event. Default `'sibling'`. */
+    placement?: 'sibling' | 'fleet';
+}
+/**
+ * Dispatch one detached turn and advance it to a terminal state with
+ * `driveTurn` ticks. The first tick dispatches (idempotent on `sessionId`);
+ * subsequent ticks poll. On abort the remote session is cancelled via
+ * `_sessionCancel` when the box exposes it. The box is torn down on every
+ * in-process exit path (success, failure, abort) — only a process death skips
+ * teardown, which is exactly the case the resume driver re-attaches to.
+ *
+ * @experimental
+ */
+declare function runDetachedTurn(options: RunDetachedTurnOptions): Promise<DetachedTurn>;
+/** @experimental */
+interface DriveTurnResumeDriverOptions {
+    /**
+     * Resolve the live box owning a detached session. The bin wires this to the
+     * sandbox client's `get(sandboxId)`; throw when the box no longer exists —
+     * a thrown tick settles the record as failed, which is the truth.
+     */
+    resolveSandbox(sandboxId: string): Promise<DriveTurnCapableBox>;
+    /**
+     * Rebuild the turn prompt from the persisted record. Only consumed by
+     * `driveTurn`'s dispatch leg — i.e. when the previous process died after
+     * binding the box but before the session was dispatched. Must reproduce the
+     * prompt the delegate would have sent.
+     */
+    buildMessage(record: DelegationRecord): string;
+    /**
+     * Map a completed turn onto the delegation's typed output payload (parse +
+     * validate per profile). Throw when the resumed result does not pass the
+     * profile's gate — the queue settles the record as failed with that error.
+     */
+    settleOutput(turn: DetachedTurn, record: DelegationRecord, ctx: {
+        signal: AbortSignal;
+    }): Promise<DelegationResultPayload['output']> | DelegationResultPayload['output'];
+    /** Delay between `running` ticks (ms). Default 5000. */
+    intervalMs?: number;
+    /** Wall-clock cap forwarded to `driveTurn` on every tick. */
+    wallCapMs?: number;
+}
+/**
+ * Build the `driveTurn`-backed {@link DelegationResumeDriver}. Each `tick()`
+ * is one settle/poll/dispatch pass:
+ *
+ *   - ref without a sandbox binding → `failed` (`DetachedSessionUnboundError`):
+ *     the previous process died before a box existed; there is nothing to resume.
+ *   - `driveTurn` `completed` → `settleOutput` → `completed` tick.
+ *   - `running` → progress via `ctx.report`, `running` tick (queue re-ticks
+ *     after `intervalMs`).
+ *   - `failed` → `failed` tick (`DetachedTurnFailedError`) — terminal per the
+ *     SDK's deterministic-failure contract.
+ *
+ * Abort: the queue stops ticking once `cancel()` flips the record, so remote
+ * cancellation is hooked onto `ctx.signal` (once per task) and fires
+ * `_sessionCancel` when the SDK surface exposes it. The driver never deletes
+ * boxes — it cannot know whether `sandboxId` is a disposable sibling or a
+ * fleet machine, and destroying a fleet machine would be unrecoverable.
+ *
+ * @experimental
+ */
+declare function createDriveTurnResumeDriver(options: DriveTurnResumeDriverOptions): DelegationResumeDriver;
+
+/**
+ * @experimental
+ *
+ * Delegation executors — the layer between MCP delegates and the sandbox
+ * substrate. Each executor exposes a {@link SandboxClient} the kernel
+ * consumes plus a placement tag so the trace pipeline can correlate workers
+ * with their physical placement.
+ *
+ * Two implementations ship in-box:
+ *
+ * - {@link createSiblingSandboxExecutor} — every delegation spawns a fresh
+ *   sandbox sibling to the caller. Default when the MCP server runs as a
+ *   standalone CLI mounted outside a fleet.
+ *
+ * - {@link createFleetWorkspaceExecutor} — delegations dispatch onto machines
+ *   in the caller's existing fleet so worker diffs land directly on the
+ *   caller's filesystem (the fleet's shared workspace). Selected when the
+ *   parent sandbox passes `TANGLE_FLEET_ID` into the MCP server's env.
+ */
+
+/** @experimental */
+interface DelegationExecutor {
+    /** Sandbox client the kernel calls. Returned with `describePlacement` set. */
+    readonly client: SandboxClient;
+    /** Best-effort one-liner used in stderr boot logs and diagnostics. */
+    describe(): string;
+    /**
+     * Where delegated work physically runs. `sibling` and `fleet` placements are
+     * session-backed (boxes expose `driveTurn`, so detached dispatch + resume
+     * apply); `in-process` spawns local harness CLIs with no sandbox session to
+     * detach. Optional so consumer-implemented executors stay source-compatible;
+     * absent means "unknown" and detached dispatch is not enabled for it.
+     */
+    readonly placement?: 'sibling' | 'fleet' | 'in-process';
+}
+/** @experimental */
+interface SiblingSandboxExecutorOptions {
+    client: SandboxClient;
+}
+/**
+ * Wrap a raw sandbox SDK client so the kernel emits
+ * `loop.iteration.dispatch` events with `{ placement: 'sibling', sandboxId }`.
+ *
+ * The returned client `.create()` delegates to the underlying client; the
+ * only added behavior is a `describePlacement` tag the kernel reads.
+ *
+ * @experimental
+ */
+declare function createSiblingSandboxExecutor(options: SiblingSandboxExecutorOptions): DelegationExecutor;
+/**
+ * Minimal `SandboxFleet` surface the fleet executor calls. Declared
+ * structurally so tests can pass an in-memory stub without instantiating the
+ * sandbox SDK.
+ *
+ * @experimental
+ */
+interface FleetHandle {
+    readonly fleetId: string;
+    /** Machine ids in dispatch-eligible order. The executor round-robins. */
+    readonly ids: ReadonlyArray<string>;
+    /** Resolve a machine id to its `SandboxInstance` — that machine is mounted
+     * on the fleet's shared workspace, so any diff the worker writes lands on
+     * every other fleet machine's filesystem too. */
+    sandbox(machineId: string): Promise<SandboxInstance>;
+}
+/** @experimental */
+interface FleetWorkspaceExecutorOptions {
+    fleet: FleetHandle;
+    /**
+     * Override the machine-selection policy. Default = round-robin across
+     * `fleet.ids`, skipping the optional `excludeMachineIds` set (typically the
+     * coordinator machine the MCP server is running on).
+     */
+    selectMachine?: (call: {
+        callIndex: number;
+        ids: ReadonlyArray<string>;
+    }) => string;
+    /**
+     * Machine ids to skip during default round-robin. Set to the caller's own
+     * machineId so workers don't compete with the orchestrator on the same VM.
+     */
+    excludeMachineIds?: ReadonlyArray<string>;
+}
+/**
+ * Build an executor that resolves each delegated iteration to an existing
+ * machine in `fleet`. The fleet's shared-workspace policy means the worker
+ * machine sees the caller's filesystem — diffs land in-place with no
+ * cross-sandbox copy step.
+ *
+ * @experimental
+ */
+declare function createFleetWorkspaceExecutor(options: FleetWorkspaceExecutorOptions): DelegationExecutor;
+
+/** @experimental */
+interface DelegateRunCtx {
+    signal: AbortSignal;
+    report(progress: DelegationProgress): void;
+    /**
+     * Detached-run resume key recorded on the queue record at submit time
+     * (`formatDetachedSessionRef`). Present only when the submit path requested
+     * detached dispatch — its presence is what routes a session-backed delegate
+     * onto the `driveTurn` tick path instead of holding a stream.
+     */
+    detachedSessionRef?: string;
+    /** Rebind the record's resume key (e.g. once the sandbox id is known). */
+    updateDetachedSessionRef?(ref: string): void;
+    /**
+     * Per-delegation trace sink supplied by the queue — loop events emitted
+     * here land on the delegation record as a compact span tree. Delegates
+     * compose it with their configured OTEL emitter so both sinks observe
+     * the same stream.
+     */
+    traceEmitter?: LoopTraceEmitter;
+}
+/** @experimental */
+type CoderDelegate = (args: DelegateCodeArgs, ctx: DelegateRunCtx) => Promise<CoderOutput>;
+/** @experimental */
+type ResearcherDelegate = (args: DelegateResearchArgs, ctx: DelegateRunCtx) => Promise<ResearchOutputShape>;
+/**
+ * UI-auditor delegate — fully consumer-injected. agent-runtime ships no
+ * default factory because the inputs are workspace path + judge function
+ * + (optionally) a `SandboxClient`, and the judge is the consumer's
+ * model seam. See `createInProcessUiAuditClient` + `uiAuditorProfile` in
+ * `@tangle-network/agent-runtime/profiles` for the canonical wiring.
+ *
+ * @experimental
+ */
+type UiAuditorDelegate = (args: DelegateUiAuditArgs, ctx: DelegateRunCtx) => Promise<UiAuditorDelegationOutput>;
+/** @experimental Structured review verdict over a coder candidate. */
+interface CoderReview {
+    /** Gate: only approved candidates are eligible to win. */
+    approved: boolean;
+    /** Reviewer's recommendation — surfaced in traces. */
+    recommendation: 'ship' | 'approve-with-nits' | 'changes-requested' | 'reject';
+    /** Readiness 0..1, used by the `highest-readiness` winner-selection strategy. */
+    readiness: number;
+    notes?: string;
+}
+/**
+ * @experimental
+ *
+ * Optional adversarial reviewer over a coder candidate that already passed
+ * mechanical validation (tests/typecheck/forbidden/diff/no-op/secrets). Folded
+ * from the ai-trading-blueprint delegation MCP: a candidate is only eligible to
+ * win if the reviewer approves it. The reviewer is the consumer's seam — an LLM
+ * judge, a `pnpm review` command, anything returning a `CoderReview`.
+ */
+type CoderReviewer = (output: CoderOutput, task: CoderTask, ctx: {
+    signal: AbortSignal;
+}) => Promise<CoderReview> | CoderReview;
+/**
+ * @experimental Winner-selection strategy among validated (+ reviewed)
+ * candidates. `highest-readiness` requires a `reviewer`. Default `highest-score`
+ * (the kernel's behavior — preserves backward compatibility).
+ */
+type CoderWinnerSelection = 'highest-score' | 'smallest-diff' | 'highest-readiness' | 'first-approved';
+/** @experimental */
+interface CreateDefaultCoderDelegateOptions {
+    /**
+     * Execution placement. Pass a {@link DelegationExecutor} (sibling or fleet)
+     * to control where worker iterations land. `sandboxClient` is a
+     * convenience shorthand that wraps the client in a sibling executor — pass
+     * one or the other, not both.
+     */
+    executor?: DelegationExecutor;
+    /**
+     * Convenience shorthand for sibling placement. Equivalent to
+     * `executor: createSiblingSandboxExecutor({ client: sandboxClient })`.
+     */
+    sandboxClient?: SandboxClient;
+    /** Backend harness for the single-coder path. Default comes from `coderProfile`. */
+    harness?: string;
+    /** Model override for the single-coder path. */
+    model?: string;
+    /** Default `['claude-code', 'codex', 'opencode/zai-coding-plan/glm-5.1']` when variants > 1. */
+    fanoutHarnesses?: string[];
+    /** Optional per-harness model override for `variants > 1`. */
+    fanoutModels?: (string | undefined)[];
+    /** Hard cap on the kernel's per-batch concurrency. Default 4. */
+    maxConcurrency?: number;
+    /**
+     * Optional adversarial reviewer. When set, a candidate must pass mechanical
+     * validation AND `reviewer.approved` to be eligible to win — empty/secret/
+     * test-failing patches are already gone; this catches the "compiles + passes
+     * but wrong/unsafe" class the deterministic validator can't see.
+     */
+    reviewer?: CoderReviewer;
+    /** Winner-selection strategy among eligible candidates. Default `highest-score`. */
+    winnerSelection?: CoderWinnerSelection;
+    /**
+     * Loop trace emitter forwarded into every delegated `runLoop`. Wire
+     * `createPropagatingTraceEmitter(readTraceContextFromEnv())` here (the bin
+     * does) so delegated build-loops export their topology spans to the OTLP /
+     * Tangle Intelligence sink when `OTEL_EXPORTER_OTLP_ENDPOINT` is set — and
+     * are a cheap no-op when it isn't. Configurable by construction.
+     *
+     * Detached single-variant turns (taken when `ctx.detachedSessionRef` is set)
+     * bypass `runLoop`; `runDetachedTurn` synthesizes a single-iteration loop
+     * event stream for them so this emitter observes detached work too.
+     */
+    traceEmitter?: LoopTraceEmitter;
+    /** Tick cadence (ms) for the detached single-variant path. Default 5000. */
+    detachedTickIntervalMs?: number;
+    /** Wall-clock cap (ms) forwarded to `driveTurn` for detached turns. */
+    detachedWallCapMs?: number;
+}
+/**
+ * Build a coder delegate that drives `runLoop` against the project's
+ * sandbox client + coder profile. When `args.variants > 1` it switches
+ * to the multi-harness fanout topology.
+ *
+ * @experimental
+ */
+declare function createDefaultCoderDelegate(options: CreateDefaultCoderDelegateOptions): CoderDelegate;
+/**
+ * Canonical `DelegateCodeArgs` → `CoderTask` mapping — the single source for
+ * the delegate's live dispatch AND the resume driver's settle/message
+ * rebuilding, so a resumed record reproduces exactly the task the original
+ * process dispatched.
+ *
+ * @experimental
+ */
+declare function coderTaskFromArgs(args: DelegateCodeArgs): CoderTask;
+/** @experimental */
+interface SettleDetachedCoderTurnOptions {
+    task: CoderTask;
+    /** Session id of the detached turn — used as the synthesized event id. */
+    sessionId: string;
+    signal: AbortSignal;
+    harness?: string;
+    model?: string;
+    /** Same gate as the streaming path: an unapproved candidate cannot win. */
+    reviewer?: CoderReviewer;
+}
+/**
+ * Settle a completed detached coder turn through the same gate the streaming
+ * path applies: parse the terminal payload with the coder output adapter,
+ * run the mechanical validator (tests/typecheck/forbidden/diff/no-op/secrets),
+ * then the optional reviewer. Throws when nothing survives — a resumed or
+ * detached run must not return an unvalidated patch.
+ *
+ * @experimental
+ */
+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 };