@tangle-network/agent-runtime 0.48.0 → 0.49.0

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

@@ -0,0 +1,1145 @@
+import { C as CoderOutput, a as CoderTask } from './coder-CVZNGbyg.js';
+import { S as SandboxClient, A as AgentRunSpec, e as LoopTraceEmitter } from './types-nBMuollC.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
+ *
+ * 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;
+}
+/** @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;
+}
+/** @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;
+}
+/** @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[];
+}
+/** @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;
+}
+/** @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;
+}
+/** @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 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.
+     */
+    status(taskId: string): 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 rehydrate;
+    private startResume;
+    private driveResume;
+    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 per-token
+ * loop trace events and kernel token/cost aggregation are not produced for that
+ * turn. 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;
+}
+/**
+ * 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;
+}
+/** @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` and therefore emit no loop trace events for that turn.
+     */
+    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 FeedbackRating as $, type DelegationError as A, type DelegationHistoryEntry as B, type CoderReviewer as C, type DelegateCodeArgs as D, DelegationPersistenceError as E, type FactCandidate as F, type DelegationProfile as G, type DelegationProgress as H, type DelegationRecord as I, type DelegationResultPayload as J, type DelegationResumeContext as K, type DelegationResumeDriver as L, type DelegationResumeTick as M, type DelegationRunContext as N, DelegationStateCorruptError as O, type DelegationStatus as P, type DelegationStore as Q, type ResearcherDelegate as R, type DelegationTaskQueueOptions as S, type DetachedSessionRefParts as T, type UiAuditorDelegate as U, type DetachedTurn as V, type DriveTurnCapableBox as W, type DriveTurnResumeDriverOptions as X, type DriveTurnTick as Y, type FactJudge as Z, type FactJudgeVerdict as _, type CoderWinnerSelection as a, type FeedbackRefersTo as a0, FileDelegationStore as a1, type FileDelegationStoreOptions as a2, type FleetWorkspaceExecutorOptions as a3, InMemoryDelegationStore as a4, type KbGateResult as a5, type ResearchOutputShape as a6, type RunDetachedTurnOptions as a7, type SettleDetachedCoderTurnOptions as a8, type SiblingSandboxExecutorOptions as a9, type SubmitInput as aa, type SubmitOutput as ab, type UiAuditorDelegationOutput as ac, coderTaskFromArgs as ad, createDefaultCoderDelegate as ae, createDriveTurnResumeDriver as af, createFleetWorkspaceExecutor as ag, createKbGate as ah, createSiblingSandboxExecutor as ai, detachedTurnEvents as aj, formatDetachedSessionRef as ak, hashIdempotencyInput as al, parseDetachedSessionRef as am, runDetachedTurn as an, settleDetachedCoderTurn as ao, 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 CoderReview as t, type CreateDefaultCoderDelegateOptions as u, type DelegateCodeConfig as v, type DelegateResearchConfig as w, type DelegateRunCtx as x, type DelegateUiAuditConfig as y, type DelegateUiAuditRoute as z };