@tangle-network/agent-runtime 0.81.1 → 0.83.0

package/dist/{coordination-BI9tpcmF.d.ts → coordination-CuDLO8wj.d.ts}

@@ -1,18 +1,17 @@
-import { E as ExecutorFactory, b as ExecutorRegistry, h as Spend, c as Agent, i as Scope, d as ResultBlobStore, B as Budget } from './types-By9LXllv.js';
+import { E as ExecutorFactory, b as ExecutorRegistry, h as Spend, c as Agent, i as Scope, d as ResultBlobStore, B as Budget } from './types-Driepl87.js';
 import { AgentProfile } from '@tangle-network/agent-interface';
-import { U as UiLens, a as UiFinding, C as CoderTask } from './substrate-rNj6TDc3.js';
-import { e as LoopTraceEmitter, c as LoopTraceEvent, S as SandboxClient, A as AgentRunSpec, E as ExecCtx } from './types-BF-MEsQB.js';
+import { U as UiLens, a as UiFinding, C as CoderTask } from './substrate-DO2GHNg2.js';
+import { e as LoopTraceEmitter, c as LoopTraceEvent, S as SandboxClient, A as AgentRunSpec, E as ExecCtx } from './types-ESeMOj94.js';
 import { SandboxEvent, SandboxInstance, BackendType } from '@tangle-network/sandbox';
 import { AgentEvalError } from '@tangle-network/agent-eval';
 import { O as OtelExporter } from './otel-export-BKmNwiCb.js';
-import { T as ToolSpec, R as RouterConfig } from './router-client-D6Ocf4jG.js';
-import { G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './worktree-harness-Dx8XULW3.js';
-import { L as LocalHarness } from './local-harness-DU7yV6mG.js';
+import { T as ToolSpec, R as RouterConfig } from './router-client-r8y_VFVM.js';
+import { G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './worktree-harness-CX_McRLp.js';
+import { L as LocalHarness } from './local-harness-sI0S_XNA.js';
 import { ProviderExecutorOptions, AgentEnvironmentProviderRegistry } from './environment-provider.js';
 import { AgentEnvironmentProvider } from '@tangle-network/agent-interface/environment-provider';
 
 /**
- * @experimental
  *
  * The child→parent message bus: the ONE pipe carrying every message a worker, sub-driver, or
  * analyst sends up to the driver — settled outputs, questions, and trace-analyst findings. It
@@ -33,6 +32,8 @@ import { AgentEnvironmentProvider } from '@tangle-network/agent-interface/enviro
  * the SAME publish/pull/subscribe surface backed by a durable mailbox on the parent's box (children
  * POST events with at-least-once retry; payloads are blob refs so the event stays small). Consumers
  * depend only on this interface, so distribution is a transport swap, never an architecture change.
+ *
+ * @experimental
  */
 /** Every bus event is a discriminated union member keyed by `type`. */
 interface BusEvent {
@@ -78,10 +79,10 @@ interface EventBus<E extends BusEvent> {
     /** Throughput counters for observability dashboards. */
     stats(): BusStats;
 }
+/** Create the child→parent coordination bus: one typed pipe for settled outputs, questions, and analyst findings, with a priority-ordered pull queue and a pass-through subscribe lane. */
 declare function createEventBus<E extends BusEvent>(now?: () => number): EventBus<E>;
 
 /**
- * @experimental
  *
  * Sandbox-session coder decode layer. The sandbox-session delegate (`./delegates`) and the
  * cross-restart resume driver run the in-box harness over a `SandboxClient` and need to
@@ -96,6 +97,8 @@ declare function createEventBus<E extends BusEvent>(now?: () => number): EventBu
  *      projected onto `CoderOutput`; and
  *   2. an LLM-emitted JSON block (`{ branch, patch, testResult, typecheckResult, diffStats }`),
  *      lifted onto `data.result` or scanned out of the assistant transcript (any harness shape).
+ *
+ * @experimental
  */
 
 /** @experimental The structured coder result the sandbox-session path decodes + gates. */
@@ -122,7 +125,6 @@ interface CoderOutput {
 }
 
 /**
- * @experimental
  *
  * Persistence port for the MCP delegation queue.
  *
@@ -135,6 +137,8 @@ interface CoderOutput {
  * 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
  */
 
 /** @experimental */
@@ -186,7 +190,7 @@ declare class DelegationPersistenceError extends AgentEvalError {
         cause?: unknown;
     });
 }
-/** @experimental */
+/** In-memory `DelegationStore` — suitable for single-process use and tests. @experimental */
 declare class InMemoryDelegationStore implements DelegationStore {
     private readonly records;
     loadAll(): Promise<DelegationRecord[]>;
@@ -236,7 +240,6 @@ declare class FileDelegationStore implements DelegationStore {
 }
 
 /**
- * @experimental
  *
  * Compact loop-trace tee for the delegation journal.
  *
@@ -251,6 +254,8 @@ declare class FileDelegationStore implements DelegationStore {
  * 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.
+ *
+ * @experimental
  */
 
 /**
@@ -325,7 +330,7 @@ interface DelegationTraceCollector {
     /** Flush buffered events of runs that never reached `loop.ended`. */
     settle(): void;
 }
-/** @experimental */
+/** Build a `DelegationTraceCollector` that buffers loop-trace events and converts them to spans on settle. @experimental */
 declare function createDelegationTraceCollector(onSpans: (spans: DelegationTraceSpan[]) => void): DelegationTraceCollector;
 /**
  * Fan one `LoopTraceEvent` stream into several emitters — e.g. the
@@ -338,7 +343,6 @@ declare function createDelegationTraceCollector(onSpans: (spans: DelegationTrace
 declare function composeLoopTraceEmitters(...emitters: ReadonlyArray<LoopTraceEmitter | undefined>): LoopTraceEmitter | undefined;
 
 /**
- * @experimental
  *
  * Trace context propagation for MCP subprocess.
  *
@@ -354,6 +358,8 @@ declare function composeLoopTraceEmitters(...emitters: ReadonlyArray<LoopTraceEm
  *
  * When these env vars are absent, the MCP generates a fresh trace root —
  * the server operates standalone without trace joining.
+ *
+ * @experimental
  */
 
 interface TraceContext {
@@ -386,7 +392,6 @@ declare function createPropagatingTraceEmitter(ctx: TraceContext): {
 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
@@ -397,6 +402,8 @@ declare function traceContextToEnv(ctx: TraceContext): Record<string, string>;
  * `completed` | `failed` | `cancelled`. `delegate_feedback` +
  * `delegation_history` are synchronous reads / writes against the local
  * task queue + feedback store.
+ *
+ * @experimental
  */
 
 /** @experimental */
@@ -674,7 +681,6 @@ interface DelegationHistoryResult {
 }
 
 /**
- * @experimental
  *
  * State machine for async MCP delegations:
  *
@@ -698,6 +704,8 @@ interface DelegationHistoryResult {
  * 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.
+ *
+ * @experimental
  */
 
 type AnyDelegateArgs = DelegateCodeArgs | DelegateResearchArgs | DelegateUiAuditArgs;
@@ -881,7 +889,7 @@ interface DelegationTaskQueueOptions {
      */
     traceContext?: TraceContext;
 }
-/** @experimental */
+/** In-process queue for async delegation tasks — submit, cancel, poll status, and read history. @experimental */
 declare class DelegationTaskQueue {
     private readonly records;
     private readonly controllers;
@@ -982,7 +990,6 @@ declare class DelegationTaskQueue {
 declare function hashIdempotencyInput(value: unknown): string;
 
 /**
- * @experimental
  *
  * Detached delegation turns over the sandbox SDK's `driveTurn` primitive.
  *
@@ -1014,6 +1021,8 @@ declare function hashIdempotencyInput(value: unknown): string;
  * 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.
+ *
+ * @experimental
  */
 
 /**
@@ -1072,7 +1081,7 @@ interface DetachedSessionRefParts {
  * @experimental
  */
 declare function formatDetachedSessionRef(parts: DetachedSessionRefParts): string;
-/** @experimental Inverse of {@link formatDetachedSessionRef}; throws `ValidationError` on malformed input. */
+/** Parse a `detachedSessionRef` string back to parts; throws `ValidationError` on malformed input. @experimental */
 declare function parseDetachedSessionRef(raw: string): DetachedSessionRefParts;
 /** @experimental The terminal payload of a finished detached turn. */
 interface DetachedTurn {
@@ -1187,7 +1196,6 @@ interface DetachedTurnResumeDriverOptions {
 declare function createDetachedTurnResumeDriver(options: DetachedTurnResumeDriverOptions): DelegationResumeDriver;
 
 /**
- * @experimental
  *
  * Delegation executors — the layer between MCP delegates and the sandbox
  * substrate. Each executor exposes a {@link SandboxClient} the kernel
@@ -1204,6 +1212,8 @@ declare function createDetachedTurnResumeDriver(options: DetachedTurnResumeDrive
  *   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
  */
 
 /** @experimental */
@@ -1280,7 +1290,6 @@ interface FleetWorkspaceExecutorOptions {
 declare function createFleetWorkspaceExecutor(options: FleetWorkspaceExecutorOptions): DelegationExecutor;
 
 /**
- * @experimental
  *
  * `detachedSessionDelegate` — the sandbox-session coder delegate: a closure that drives `runLoop`
  * against a `SandboxClient` + a caller-supplied (or minimal model-only default) worker profile, to a
@@ -1297,6 +1306,8 @@ declare function createFleetWorkspaceExecutor(options: FleetWorkspaceExecutorOpt
  * none is passed, a minimal model-only default profile is materialized in `./detached-coder` — no
  * hardcoded skills or tools. For NEW local-repo coding use `worktreeFanout` / `worktreeLoopRunner`
  * (author one `AgentProfile` per harness → `createWorktreeCliExecutor` leaves → `gateOnDeliverable`).
+ *
+ * @experimental
  */
 
 /** @experimental */
@@ -1345,13 +1356,14 @@ interface CoderReview {
     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`.
+ *
+ * @experimental
  */
 type CoderReviewer = (output: CoderOutput, task: CoderTask, ctx: {
     signal: AbortSignal;
@@ -1484,7 +1496,6 @@ interface SettleDetachedCoderTurnOptions {
 declare function settleDetachedCoderTurn(turn: DetachedTurn, options: SettleDetachedCoderTurnOptions): Promise<CoderOutput>;
 
 /**
- * @experimental
  *
  * Feedback persistence surface for the MCP layer.
  *
@@ -1497,6 +1508,8 @@ declare function settleDetachedCoderTurn(turn: DetachedTurn, options: SettleDeta
  * 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
  */
 
 /** @experimental */
@@ -1521,7 +1534,7 @@ interface FeedbackStore {
         refersToRef?: string;
     }): Promise<FeedbackEvent[]>;
 }
-/** @experimental */
+/** In-memory `FeedbackStore` — suitable for single-process use and tests. @experimental */
 declare class InMemoryFeedbackStore implements FeedbackStore {
     private readonly events;
     put(event: FeedbackEvent): Promise<void>;
@@ -1539,7 +1552,6 @@ declare class InMemoryFeedbackStore implements FeedbackStore {
 declare function eventToSnapshot(event: FeedbackEvent): DelegationFeedbackSnapshot;
 
 /**
- * @experimental
  *
  * The leaf runtime — the built-in `Executor` IMPLEMENTATIONS behind the ONE
  * open interface frozen in `./types`, plus the open resolver/registry that maps
@@ -1561,6 +1573,8 @@ declare function eventToSnapshot(event: FeedbackEvent): DelegationFeedbackSnapsh
  * Layering: `estimateCost`/`isModelPriced` are substrate primitives from
  * `@tangle-network/agent-eval`; `runLoop`/`acquireSandbox` are runtime kernels
  * from this package. No per-vendor adapters live here.
+ *
+ * @experimental
  */
 
 /**
@@ -1757,7 +1771,6 @@ declare function createExecutor(config: ExecutorConfig): ExecutorFactory<unknown
 declare function createExecutorRegistry(): ExecutorRegistry;
 
 /**
- * @experimental
  *
  * `delegate` MCP tool — the ONE generic delegation verb, the agent-facing front door to
  * `delegate()` / `supervise()`. The agent hands it an INTENT (what it wants done); a default
@@ -1771,13 +1784,15 @@ declare function createExecutorRegistry(): ExecutorRegistry;
  * The supervisor's substrate (its brain `router`, the worker `backend`, the completion `deliverable`)
  * is INJECTED at server construction — never an agent-supplied arg. The agent supplies only the
  * intent (+ an optional per-call `model` / `runId`).
+ *
+ * @experimental
  */
 
-/** @experimental */
+/** MCP tool name for the `delegate` generic-delegation tool. @experimental */
 declare const DELEGATE_TOOL_NAME = "delegate";
-/** @experimental */
+/** Human-readable description of the `delegate` MCP tool, injected into the tool manifest. @experimental */
 declare const DELEGATE_DESCRIPTION: string;
-/** @experimental */
+/** JSON Schema for `delegate` tool arguments (`intent` + optional `model` and `runId`). @experimental */
 declare const DELEGATE_INPUT_SCHEMA: {
     readonly type: "object";
     readonly properties: {
@@ -1803,7 +1818,7 @@ interface DelegateArgs {
     model?: string;
     runId?: string;
 }
-/** @experimental */
+/** Parse and validate raw MCP tool input into typed `DelegateArgs`; throws `TypeError` on bad input. @experimental */
 declare function validateDelegateArgs(raw: unknown): DelegateArgs;
 /** The synchronous result the `delegate` tool returns to the calling agent: the delivered output (or
  *  the no-winner reason) PLUS the conserved spend of the whole delegation. */
@@ -1838,7 +1853,6 @@ interface DelegateHandlerOptions {
 declare function createDelegateHandler(options: DelegateHandlerOptions): (raw: unknown) => Promise<DelegateResult>;
 
 /**
- * @experimental
  *
  * Stdio JSON-RPC MCP server exposing the delegation tools to sandbox
  * coding-harness agents (claude-code, codex, opencode, ...): the generic
@@ -1856,6 +1870,8 @@ declare function createDelegateHandler(options: DelegateHandlerOptions): (raw: u
  * 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
  */
 
 /** @experimental */
@@ -1940,7 +1956,11 @@ interface JsonRpcResponse {
         data?: unknown;
     };
 }
-/** @experimental */
+/**
+ * Stdio JSON-RPC MCP server exposing the delegation tools (`delegate`, `delegate_feedback`, `delegation_status`, `delegation_history`, optional `delegate_ui_audit`) to sandbox coding-harness agents.
+ *
+ * @experimental
+ */
 declare function createMcpServer(options?: McpServerOptions): McpServer;
 /**
  * In-process pair of `Readable` + `Writable` streams suitable for driving
@@ -1957,12 +1977,13 @@ declare function createInProcessTransport(): {
 };
 
 /**
- * @experimental
  *
  * MCP binding for a live `Scope`. A sandbox driver gets the same small verbs
  * the in-process driver has: spawn, observe, await, steer, ask/answer, analyze,
  * and stop. Settled outputs remain Scope artifacts; product code can project
  * them into any UI/report envelope it needs.
+ *
+ * @experimental
  */
 
 /** A worker the driver has drained via `await_event`. */

package/dist/environment-provider.d.ts

@@ -2,8 +2,8 @@ import { AgentProfile, AgentProfileValidationResult } from '@tangle-network/agen
 import { AgentEnvironmentProvider, AgentEnvironmentCapabilities, CreateAgentEnvironmentInput, AgentTurnInput, AgentProfileRef } from '@tangle-network/agent-interface/environment-provider';
 export { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentEvent, AgentEnvironmentProvider, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSession, AgentSessionRef, AgentSessionStatus, AgentTurnInput, AgentTurnResult, CheckpointRef, CheckpointRequest, CreateAgentEnvironmentInput, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from '@tangle-network/agent-interface/environment-provider';
 import { CreateSandboxOptions, BackendType } from '@tangle-network/sandbox';
-import { R as Runtime, E as ExecutorFactory } from './types-By9LXllv.js';
-import { S as SandboxClient } from './types-BF-MEsQB.js';
+import { R as Runtime, E as ExecutorFactory } from './types-Driepl87.js';
+import { S as SandboxClient } from './types-ESeMOj94.js';
 import '@tangle-network/agent-eval';
 
 /** Provider object or registry name accepted by runtime provider adapters.

package/dist/environment-provider.js

@@ -4,7 +4,7 @@ import {
   providerAsSandboxClient,
   resolveAgentEnvironmentProvider,
   sandboxClientAsProvider
-} from "./chunk-H7IBHAFT.js";
+} from "./chunk-BZF3KQ6G.js";
 import "./chunk-DGUM43GV.js";
 export {
   createAgentEnvironmentProviderRegistry,

package/dist/{improvement-adapter-CioiEE2z.d.ts → improvement-adapter-CDR8QNVM.d.ts}

@@ -94,7 +94,9 @@ interface SurfaceValidationIssue {
     path: string;
     reason: 'missing' | 'not-directory' | 'not-file';
 }
+/** Validate an `AgentSurfaces` map on disk — missing paths fail loud at `defineAgent` time instead of silently skipping self-improvement edits. */
 declare function validateSurfaces(surfaces: AgentSurfaces, repoRoot: string): ReadonlyArray<SurfaceValidationIssue>;
+/** Format a list of surface validation issues into a human-readable error string. */
 declare function renderSurfaceIssues(issues: ReadonlyArray<SurfaceValidationIssue>, repoRoot: string): string;
 
 /**
@@ -202,6 +204,7 @@ interface DraftPatchOutput {
     /** Multi-line rationale for the PR body. */
     rationale: string;
 }
+/** The substrate-default `ImprovementAdapter`: resolve each finding's subject to a real surface path, LLM-draft a unified-diff patch, then auto-apply or open a PR. */
 declare function createSurfaceImprovementAdapter(opts: CreateSurfaceImprovementAdapterOpts): ImprovementAdapter<SurfaceImprovementEdit>;
 
 export { type AgentSurfaces as A, type CreateSurfaceImprovementAdapterOpts as C, type DraftPatchInput as D, type ResolvedSurface as R, type SurfaceImprovementEdit as S, type DraftPatchOutput as a, type SurfaceValidationIssue as b, createSurfaceImprovementAdapter as c, resolveSubjectPath as d, renderSurfaceIssues as r, validateSurfaces as v };