@tangle-network/agent-runtime 0.19.0 → 0.20.1

package/dist/mcp/index.d.ts

@@ -0,0 +1,827 @@
+import { CoderOutput } from '../profiles.js';
+import { g as LoopSandboxClient } from '../types-Bx-tArkc.js';
+import '@tangle-network/sandbox';
+import '../runtime-run-B2j-hvBj.js';
+import '../types-DvJIha6w.js';
+import '@tangle-network/agent-eval';
+
+/**
+ * @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';
+/** @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;
+};
+/**
+ * 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;
+    status: DelegationStatus;
+    feedback?: DelegationFeedbackSnapshot[];
+    costUsd?: number;
+    startedAt: string;
+    completedAt?: string;
+}
+/** @experimental */
+interface DelegationHistoryResult {
+    delegations: DelegationHistoryEntry[];
+}
+
+/** @experimental */
+interface DelegateRunCtx {
+    signal: AbortSignal;
+    report(progress: DelegationProgress): void;
+}
+/** @experimental */
+type CoderDelegate = (args: DelegateCodeArgs, ctx: DelegateRunCtx) => Promise<CoderOutput>;
+/** @experimental */
+type ResearcherDelegate = (args: DelegateResearchArgs, ctx: DelegateRunCtx) => Promise<ResearchOutputShape>;
+/** @experimental */
+interface CreateDefaultCoderDelegateOptions {
+    sandboxClient: LoopSandboxClient;
+    /** Default `['claude-code', 'codex', 'opencode/zai-coding-plan/glm-5.1']` when variants > 1. */
+    fanoutHarnesses?: string[];
+    /** Hard cap on the kernel's per-batch concurrency. Default 4. */
+    maxConcurrency?: 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;
+
+/**
+ * @experimental
+ *
+ * Feedback persistence surface for the MCP layer.
+ *
+ * The substrate cannot import `@tangle-network/agent-knowledge` (it would
+ * induce a dependency cycle), so the store is an abstract interface. The
+ * default implementation is in-memory; consumers wire their own adapter
+ * (a real KbStore-backed sink, an HTTP relay to gtm-agent's knowledge
+ * service, etc.) via `createMcpServer({ feedbackStore })`.
+ *
+ * Feedback events are append-only: every rating is a new event with a
+ * fresh id, even when the same delegation is rated multiple times. The
+ * caller decides how to roll up scores downstream.
+ */
+
+/** @experimental */
+interface FeedbackEvent {
+    id: string;
+    refersTo: DelegateFeedbackArgs['refersTo'];
+    rating: DelegateFeedbackArgs['rating'];
+    by: DelegateFeedbackArgs['by'];
+    capturedAt: string;
+    namespace?: string;
+}
+/** @experimental */
+interface FeedbackStore {
+    /** Append a new event. Never dedupes — every rating is its own event. */
+    put(event: FeedbackEvent): Promise<void>;
+    /**
+     * List events filtered by `namespace`. When `namespace` is omitted, list
+     * across all namespaces. Returns events in insertion order.
+     */
+    list(filter?: {
+        namespace?: string;
+        refersToRef?: string;
+    }): Promise<FeedbackEvent[]>;
+}
+/** @experimental */
+declare class InMemoryFeedbackStore implements FeedbackStore {
+    private readonly events;
+    put(event: FeedbackEvent): Promise<void>;
+    list(filter?: {
+        namespace?: string;
+        refersToRef?: string;
+    }): Promise<FeedbackEvent[]>;
+}
+/**
+ * Project a `FeedbackEvent` down to the snapshot shape carried on
+ * `delegation_history` entries.
+ *
+ * @experimental
+ */
+declare function eventToSnapshot(event: FeedbackEvent): DelegationFeedbackSnapshot;
+
+/**
+ * @experimental
+ *
+ * In-memory state for async MCP delegations. State machine:
+ *
+ *   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.
+ *
+ * Persistent state (sqlite) is a Phase 2 follow-up. The README documents the
+ * in-memory limitation explicitly so consumers know a worker restart drops
+ * pending delegations.
+ */
+
+/** @experimental */
+interface DelegationRecord {
+    taskId: string;
+    profile: DelegationProfile;
+    namespace?: string;
+    args: DelegateCodeArgs | DelegateResearchArgs;
+    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;
+    /** Feedback events keyed by this delegation's taskId. */
+    feedback: DelegationFeedbackSnapshot[];
+}
+/** @experimental */
+interface SubmitInput<Args extends DelegateCodeArgs | DelegateResearchArgs> {
+    profile: DelegationProfile;
+    args: Args;
+    namespace?: string;
+    idempotencyKey?: 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: {
+        signal: AbortSignal;
+        report(progress: DelegationProgress): void;
+    }) => Promise<DelegationResultPayload['output']>;
+}
+/** @experimental */
+interface SubmitOutput {
+    taskId: string;
+    /** True when a prior matching `idempotencyKey` returned an existing record. */
+    reused: boolean;
+}
+/** @experimental */
+interface DelegationTaskQueueOptions {
+    /** ID generator override; default `randomTaskId`. */
+    generateId?: () => string;
+    /** Clock override; default `() => new Date().toISOString()`. */
+    now?: () => string;
+}
+/** @experimental */
+declare class DelegationTaskQueue {
+    private readonly records;
+    private readonly controllers;
+    private readonly byIdempotencyKey;
+    private readonly generateId;
+    private readonly now;
+    constructor(options?: DelegationTaskQueueOptions);
+    /**
+     * Kick off a delegation in the background. Returns immediately. The
+     * `taskId` is queryable via `status` once this method returns.
+     */
+    submit<Args extends DelegateCodeArgs | DelegateResearchArgs>(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[];
+    /** Test-only — number of in-flight (non-terminal) records. */
+    inflightCount(): number;
+    private execute;
+}
+/**
+ * Best-effort stable hash for use as `idempotencyKey`. Not cryptographic;
+ * collisions only affect dedupe, never correctness.
+ *
+ * @experimental
+ */
+declare function hashIdempotencyInput(value: unknown): string;
+
+/**
+ * @experimental
+ *
+ * Stdio JSON-RPC MCP server exposing the 5 delegation tools to sandbox
+ * coding-harness agents (claude-code, codex, opencode, ...).
+ *
+ * The server is transport-bound but topology-free: tool execution is
+ * delegated to handler functions composed from a queue, a feedback
+ * store, and per-profile run delegates. Consumers wire those at
+ * construction time. The `agent-runtime-mcp` bin spins up a default
+ * configuration for the common case (real sandbox client + coder).
+ *
+ * Wire protocol: line-delimited JSON-RPC 2.0 over stdio. Each line is
+ * one request; each response is one line. `tools/list` and `tools/call`
+ * mirror the MCP 2024-11-05 spec; we do not pull in
+ * `@modelcontextprotocol/sdk` to keep the dependency footprint zero.
+ */
+
+/** @experimental */
+interface McpServerOptions {
+    /** Required to enable delegate_code. */
+    coderDelegate?: CoderDelegate;
+    /**
+     * Required to enable delegate_research. The substrate cannot ship a
+     * default — wire one that closes over your `runLoop` + a
+     * researcher profile (typically `@tangle-network/agent-knowledge`'s
+     * `researcherProfile` / `multiHarnessResearcherFanout`).
+     */
+    researcherDelegate?: ResearcherDelegate;
+    /** Override the default in-memory feedback store. */
+    feedbackStore?: FeedbackStore;
+    /** Override the default in-memory task queue. */
+    queue?: DelegationTaskQueue;
+    /** Server display name surfaced via `initialize`. Default `'agent-runtime-mcp'`. */
+    serverName?: string;
+    /** Server version surfaced via `initialize`. Default = the package version baked at build time. */
+    serverVersion?: string;
+}
+/** @experimental */
+interface McpToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (raw: unknown) => Promise<unknown>;
+}
+/** @experimental */
+interface McpServer {
+    /** Tools currently registered (depend on which delegates were wired). */
+    readonly tools: ReadonlyMap<string, McpToolDescriptor>;
+    /** The underlying queue — exposed so tests can introspect it. */
+    readonly queue: DelegationTaskQueue;
+    /** The feedback store — exposed for the same reason. */
+    readonly feedbackStore: FeedbackStore;
+    /** Handle a single parsed JSON-RPC message. Returns the response object (or `null` for notifications). */
+    handle(message: JsonRpcMessage): Promise<JsonRpcResponse | null>;
+    /** Drive the server on a stdio-shaped transport until `stop()` is called. */
+    serve(transport?: McpTransport): Promise<void>;
+    /** Stop a `serve` call. Subsequent requests are rejected. */
+    stop(): void;
+}
+/** @experimental */
+interface McpTransport {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+/** @experimental */
+interface JsonRpcMessage {
+    jsonrpc: '2.0';
+    id?: number | string | null;
+    method: string;
+    params?: unknown;
+}
+/** @experimental */
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** @experimental */
+declare function createMcpServer(options?: McpServerOptions): McpServer;
+/**
+ * In-process pair of `Readable` + `Writable` streams suitable for driving
+ * `server.serve(...)` from a test. Returns the agent-side stream (the
+ * client writes to it) and the server-side stream (the test reads from it).
+ *
+ * @experimental
+ */
+declare function createInProcessTransport(): {
+    transport: McpTransport;
+    clientWrite(line: string): void;
+    clientClose(): void;
+    readServer(): Promise<JsonRpcResponse[]>;
+};
+
+/**
+ * @experimental
+ *
+ * `delegate_code` MCP tool — async kickoff. The handler validates the
+ * input, computes an idempotency key over the canonical fields, hands
+ * the task to the queue, and returns `{ taskId, estimatedDurationMs }`.
+ */
+
+/** @experimental */
+declare const DELEGATE_CODE_TOOL_NAME = "delegate_code";
+/** @experimental */
+declare const DELEGATE_CODE_DESCRIPTION: string;
+/** @experimental */
+declare const DELEGATE_CODE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly goal: {
+            readonly type: "string";
+            readonly description: "Natural-language description of what the coder must accomplish.";
+        };
+        readonly repoRoot: {
+            readonly type: "string";
+            readonly description: "Absolute path inside the sandbox where the repo lives.";
+        };
+        readonly contextHint: {
+            readonly type: "string";
+            readonly description: "Optional free-form context the coder sees in the prompt prelude.";
+        };
+        readonly variants: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 8;
+            readonly description: "Number of parallel coder harnesses. Default 1.";
+        };
+        readonly config: {
+            readonly type: "object";
+            readonly properties: {
+                readonly testCmd: {
+                    readonly type: "string";
+                };
+                readonly typecheckCmd: {
+                    readonly type: "string";
+                };
+                readonly forbiddenPaths: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly maxDiffLines: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly namespace: {
+            readonly type: "string";
+            readonly description: "Multi-tenant scope (customer-id, workspace-id).";
+        };
+    };
+    readonly required: readonly ["goal", "repoRoot"];
+    readonly additionalProperties: false;
+};
+/** @experimental */
+declare function validateDelegateCodeArgs(raw: unknown): DelegateCodeArgs;
+/** @experimental */
+interface DelegateCodeHandlerOptions {
+    queue: DelegationTaskQueue;
+    delegate: CoderDelegate;
+    /** Override the duration hint. */
+    estimateDurationMs?: (args: DelegateCodeArgs) => number;
+}
+/** @experimental */
+declare function createDelegateCodeHandler(options: DelegateCodeHandlerOptions): (raw: unknown) => Promise<DelegateCodeResult>;
+
+/**
+ * @experimental
+ *
+ * `delegate_feedback` MCP tool — synchronous record of agent / user /
+ * downstream-judge feedback on a delegation, artifact, or outcome.
+ *
+ * The store is append-only. Every rating is its own event; no dedupe.
+ * When `refersTo.kind === 'delegation'`, the snapshot is also attached
+ * to the matching queue record so `delegation_history` surfaces it
+ * inline without a join.
+ */
+
+/** @experimental */
+declare const DELEGATE_FEEDBACK_TOOL_NAME = "delegate_feedback";
+/** @experimental */
+declare const DELEGATE_FEEDBACK_DESCRIPTION: string;
+/** @experimental */
+declare const DELEGATE_FEEDBACK_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly refersTo: {
+            readonly type: "object";
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly enum: readonly ["delegation", "artifact", "outcome"];
+                };
+                readonly ref: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["kind", "ref"];
+            readonly additionalProperties: false;
+        };
+        readonly rating: {
+            readonly type: "object";
+            readonly properties: {
+                readonly score: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 1;
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly enum: readonly ["good", "bad", "neutral", "mixed"];
+                };
+                readonly notes: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["score", "notes"];
+            readonly additionalProperties: false;
+        };
+        readonly by: {
+            readonly type: "string";
+            readonly enum: readonly ["agent", "user", "downstream-judge"];
+        };
+        readonly capturedAt: {
+            readonly type: "string";
+        };
+        readonly namespace: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["refersTo", "rating", "by"];
+    readonly additionalProperties: false;
+};
+/** @experimental */
+declare function validateDelegateFeedbackArgs(raw: unknown): DelegateFeedbackArgs;
+/** @experimental */
+interface DelegateFeedbackHandlerOptions {
+    queue: DelegationTaskQueue;
+    store: FeedbackStore;
+    generateId?: () => string;
+    now?: () => string;
+}
+/** @experimental */
+declare function createDelegateFeedbackHandler(options: DelegateFeedbackHandlerOptions): (raw: unknown) => Promise<DelegateFeedbackResult>;
+
+/**
+ * @experimental
+ *
+ * `delegate_research` MCP tool — async kickoff for source-grounded
+ * research tasks. Same async semantics as `delegate_code`: returns a
+ * taskId immediately, idempotent on canonical inputs.
+ *
+ * The handler does not import a researcher profile directly — consumers
+ * inject a `ResearcherDelegate` via `createMcpServer({ researcherDelegate })`.
+ * The substrate cannot depend on `@tangle-network/agent-knowledge`
+ * without inducing a dependency cycle.
+ */
+
+/** @experimental */
+declare const DELEGATE_RESEARCH_TOOL_NAME = "delegate_research";
+/** @experimental */
+declare const DELEGATE_RESEARCH_DESCRIPTION: string;
+/** @experimental */
+declare const DELEGATE_RESEARCH_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly question: {
+            readonly type: "string";
+            readonly description: "The research question to answer.";
+        };
+        readonly namespace: {
+            readonly type: "string";
+            readonly description: "Multi-tenant scope (customer-id, workspace-id). REQUIRED.";
+        };
+        readonly scope: {
+            readonly type: "string";
+            readonly description: "Bound, e.g. \"audience for cpg-founder ICP\".";
+        };
+        readonly sources: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ResearchSource[];
+            };
+        };
+        readonly variants: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 8;
+        };
+        readonly config: {
+            readonly type: "object";
+            readonly properties: {
+                readonly recencyWindow: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly since: {
+                            readonly type: "string";
+                            readonly description: "ISO datetime";
+                        };
+                        readonly until: {
+                            readonly type: "string";
+                            readonly description: "ISO datetime";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+                readonly maxItems: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly minConfidence: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 1;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+    readonly required: readonly ["question", "namespace"];
+    readonly additionalProperties: false;
+};
+/** @experimental */
+declare function validateDelegateResearchArgs(raw: unknown): DelegateResearchArgs;
+/** @experimental */
+interface DelegateResearchHandlerOptions {
+    queue: DelegationTaskQueue;
+    delegate: ResearcherDelegate;
+    estimateDurationMs?: (args: DelegateResearchArgs) => number;
+}
+/** @experimental */
+declare function createDelegateResearchHandler(options: DelegateResearchHandlerOptions): (raw: unknown) => Promise<DelegateResearchResult>;
+
+/**
+ * @experimental
+ *
+ * `delegation_history` MCP tool — synchronous read of past delegations.
+ * The agent uses this for self-introspection — "have I delegated this
+ * kind of task before? did it work?" — and calibration.
+ */
+
+/** @experimental */
+declare const DELEGATION_HISTORY_TOOL_NAME = "delegation_history";
+/** @experimental */
+declare const DELEGATION_HISTORY_DESCRIPTION: string;
+/** @experimental */
+declare const DELEGATION_HISTORY_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly namespace: {
+            readonly type: "string";
+        };
+        readonly profile: {
+            readonly type: "string";
+            readonly enum: readonly ["coder", "researcher"];
+        };
+        readonly since: {
+            readonly type: "string";
+            readonly description: "ISO datetime — earliest startedAt to include.";
+        };
+        readonly limit: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 500;
+        };
+    };
+    readonly additionalProperties: false;
+};
+/** @experimental */
+declare function validateDelegationHistoryArgs(raw: unknown): DelegationHistoryArgs;
+/** @experimental */
+interface DelegationHistoryHandlerOptions {
+    queue: DelegationTaskQueue;
+}
+/** @experimental */
+declare function createDelegationHistoryHandler(options: DelegationHistoryHandlerOptions): (raw: unknown) => Promise<DelegationHistoryResult>;
+
+/**
+ * @experimental
+ *
+ * `delegation_status` MCP tool — synchronous poll. Returns the current
+ * state machine + optional progress + final result (when terminal).
+ */
+
+/** @experimental */
+declare const DELEGATION_STATUS_TOOL_NAME = "delegation_status";
+/** @experimental */
+declare const DELEGATION_STATUS_DESCRIPTION: string;
+/** @experimental */
+declare const DELEGATION_STATUS_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly taskId: {
+            readonly type: "string";
+            readonly description: "Returned by delegate_code / delegate_research.";
+        };
+    };
+    readonly required: readonly ["taskId"];
+    readonly additionalProperties: false;
+};
+/** @experimental */
+declare function validateDelegationStatusArgs(raw: unknown): DelegationStatusArgs;
+/** @experimental */
+interface DelegationStatusHandlerOptions {
+    queue: DelegationTaskQueue;
+}
+/** @experimental */
+declare function createDelegationStatusHandler(options: DelegationStatusHandlerOptions): (raw: unknown) => Promise<DelegationStatusResult>;
+
+export { type CoderDelegate, type CreateDefaultCoderDelegateOptions, DELEGATE_CODE_DESCRIPTION, DELEGATE_CODE_INPUT_SCHEMA, DELEGATE_CODE_TOOL_NAME, DELEGATE_FEEDBACK_DESCRIPTION, DELEGATE_FEEDBACK_INPUT_SCHEMA, DELEGATE_FEEDBACK_TOOL_NAME, DELEGATE_RESEARCH_DESCRIPTION, DELEGATE_RESEARCH_INPUT_SCHEMA, DELEGATE_RESEARCH_TOOL_NAME, DELEGATION_HISTORY_DESCRIPTION, DELEGATION_HISTORY_INPUT_SCHEMA, DELEGATION_HISTORY_TOOL_NAME, DELEGATION_STATUS_DESCRIPTION, DELEGATION_STATUS_INPUT_SCHEMA, DELEGATION_STATUS_TOOL_NAME, type DelegateCodeArgs, type DelegateCodeConfig, type DelegateCodeResult, type DelegateFeedbackArgs, type DelegateFeedbackResult, type DelegateResearchArgs, type DelegateResearchConfig, type DelegateResearchResult, type DelegateRunCtx, type DelegationError, type DelegationFeedbackSnapshot, type DelegationHistoryArgs, type DelegationHistoryEntry, type DelegationHistoryResult, type DelegationProfile, type DelegationProgress, type DelegationRecord, type DelegationResultPayload, type DelegationStatus, type DelegationStatusArgs, type DelegationStatusResult, DelegationTaskQueue, type DelegationTaskQueueOptions, type FeedbackEvent, type FeedbackRating, type FeedbackRefersTo, type FeedbackStore, InMemoryFeedbackStore, type JsonRpcMessage, type JsonRpcResponse, type McpServer, type McpServerOptions, type McpToolDescriptor, type McpTransport, type ResearchOutputShape, type ResearchSource, type ResearcherDelegate, type SubmitInput, type SubmitOutput, createDefaultCoderDelegate, createDelegateCodeHandler, createDelegateFeedbackHandler, createDelegateResearchHandler, createDelegationHistoryHandler, createDelegationStatusHandler, createInProcessTransport, createMcpServer, eventToSnapshot, hashIdempotencyInput, validateDelegateCodeArgs, validateDelegateFeedbackArgs, validateDelegateResearchArgs, validateDelegationHistoryArgs, validateDelegationStatusArgs };