@tangle-network/agent-runtime 0.53.0 → 0.55.0

package/dist/{coder-LKm3Mczw.d.ts → coder-CEkUFv8h.d.ts}

@@ -1,5 +1,5 @@
 import { AgentProfile } from '@tangle-network/sandbox';
-import { O as OutputAdapter, V as Validator, A as AgentRunSpec, D as Driver } from './types-CklkW4Eh.js';
+import { O as OutputAdapter, V as Validator, A as AgentRunSpec, D as Driver } from './types-C8rNlxfV.js';
 
 /**
  * @experimental

package/dist/{types-CNDJCL_0.d.ts → coordination-BMzskrUR.d.ts}

@@ -1,7 +1,8 @@
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile, BackendType } from '@tangle-network/sandbox';
 import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
-import { d as LoopTokenUsage } from './types-CklkW4Eh.js';
+import { d as LoopTokenUsage } from './types-C8rNlxfV.js';
+import { b as DelegateFeedbackArgs, c as DelegationFeedbackSnapshot, d as DelegationTaskQueue, e as CoderDelegate, R as ResearcherDelegate, U as UiAuditorDelegate, T as TraceContext } from './delegates-BPLIl8EC.js';
 
 /**
  * @experimental
@@ -435,4 +436,269 @@ interface WidenGate<Out> {
     readonly judgeExempt?: boolean;
 }
 
-export type { Agent as A, Budget as B, ExecutorRegistry as E, Handle as H, NodeId as N, ResultBlobStore as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, SpawnJournal as a, SpawnEvent as b, Settled as c, AgentSpec as d, RootHandle as e, SupervisedResult as f, Spend as g, ExecutorFactory as h, Supervisor as i, Executor as j, ExecutorContext as k, ExecutorResult as l, NodeSnapshot as m, NodeStatus as n, Restart as o, RootSignal as p, Runtime as q, SpawnOpts as r, SupervisorOpts as s };
+/**
+ * @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
+ *
+ * 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;
+    /**
+     * Required to enable delegate_ui_audit. Wire one that closes over your
+     * `runLoop` + `uiAuditorProfile` + a `SandboxClient` (the
+     * canonical in-process choice is `createInProcessUiAuditClient` from
+     * `@tangle-network/agent-runtime/profiles`) + your vision judge.
+     */
+    uiAuditorDelegate?: UiAuditorDelegate;
+    /** Override the default in-memory feedback store. */
+    feedbackStore?: FeedbackStore;
+    /** Override the default in-memory task queue. */
+    queue?: DelegationTaskQueue;
+    /**
+     * Record deterministic detached-session resume keys on single-variant
+     * coder/researcher submissions so a durable queue can resume them after a
+     * restart. Enable only when the wired delegates dispatch via sandbox
+     * sessions (`driveTurn`) AND `queue` persists records — the keys are inert
+     * otherwise. The bin turns this on alongside the durable store for
+     * session-backed (sibling/fleet) placements.
+     */
+    detachedDispatch?: boolean;
+    /**
+     * Extra tools to serve alongside the delegation tools, for example
+     * `createCoordinationTools(...).tools`. Registered after the built-ins; a
+     * duplicate name throws so delegation tools cannot be shadowed silently.
+     */
+    extraTools?: McpToolDescriptor[];
+    /**
+     * Inherited trace identity (`readTraceContextFromEnv()`) stamped on every
+     * record the DEFAULT queue creates. Ignored when `queue` is supplied —
+     * pass `traceContext` to that queue's constructor instead.
+     */
+    traceContext?: TraceContext;
+    /** 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
+ *
+ * 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.
+ */
+
+/** A worker the driver has drained via `await_next`. */
+interface SettledWorker {
+    readonly id: string;
+    readonly status: 'done' | 'down';
+    readonly score?: number;
+    readonly valid?: boolean;
+    readonly outRef?: string;
+    readonly reason?: string;
+}
+type QuestionLevel = 'worker' | 'driver' | 'loop';
+type QuestionUrgency = 'continue-without' | 'blocks-step' | 'blocks-run';
+interface QuestionOption {
+    readonly label: string;
+    readonly tradeoff: string;
+}
+interface Question {
+    readonly id: string;
+    readonly from: string;
+    readonly level: QuestionLevel;
+    readonly question: string;
+    readonly reason: string;
+    readonly urgency: QuestionUrgency;
+    readonly options?: ReadonlyArray<QuestionOption>;
+}
+type QuestionDecision = {
+    readonly kind: 'answer';
+    readonly answer: string;
+    readonly by: string;
+} | {
+    readonly kind: 'defer';
+    readonly reason: string;
+} | {
+    readonly kind: 'escalate';
+    readonly to: 'parent' | 'user' | string;
+    readonly reason: string;
+};
+interface QuestionRecord extends Question {
+    readonly status: 'open' | 'answered' | 'deferred' | 'escalated';
+    readonly decision?: QuestionDecision;
+    readonly openedAt: number;
+}
+type QuestionPolicy = 'auto' | 'mustDecide' | 'bubble' | 'failClosed';
+interface AnalystRegistry {
+    readonly kinds: ReadonlyArray<{
+        id: string;
+        description: string;
+        area: string;
+    }>;
+    readonly run: (kindId: string, trace: unknown) => Promise<unknown>;
+}
+type CoordinationEvent = {
+    readonly type: 'question';
+    readonly question: QuestionRecord;
+};
+type MakeWorkerAgent = (profile: unknown) => Agent<unknown, unknown>;
+interface CoordinationToolsOptions {
+    readonly scope: Scope<unknown>;
+    readonly blobs: ResultBlobStore;
+    readonly makeWorkerAgent: MakeWorkerAgent;
+    readonly perWorker: Budget;
+    readonly analysts?: AnalystRegistry;
+    readonly onEvent?: (event: CoordinationEvent) => void | Promise<void>;
+    readonly questionPolicy?: QuestionPolicy;
+}
+interface CoordinationTools {
+    readonly tools: McpToolDescriptor[];
+    isStopped(): boolean;
+    stopReason(): string | undefined;
+    settled(): ReadonlyArray<SettledWorker>;
+    questions(): ReadonlyArray<QuestionRecord>;
+}
+/** Build the driver's MCP tools over a live scope. */
+declare function createCoordinationTools(opts: CoordinationToolsOptions): CoordinationTools;
+
+export { type AnalystRegistry as A, type Budget as B, type CoordinationEvent as C, type Supervisor as D, type ExecutorRegistry as E, type FeedbackStore as F, type ExecutorContext as G, type ExecutorResult as H, InMemoryFeedbackStore as I, type JsonRpcMessage as J, type Handle as K, type NodeSnapshot as L, type MakeWorkerAgent as M, type NodeId as N, type NodeStatus as O, type Restart as P, type Question as Q, type ResultBlobStore as R, type SettledWorker as S, type TreeView as T, type UsageEvent as U, type RootSignal as V, type Runtime as W, type SpawnOpts as X, type SupervisorOpts as Y, type WidenGate as Z, type CoordinationTools as a, type CoordinationToolsOptions as b, type FeedbackEvent as c, type JsonRpcResponse as d, type McpServer as e, type McpServerOptions as f, type McpToolDescriptor as g, type McpTransport as h, type QuestionDecision as i, type QuestionPolicy as j, type QuestionRecord as k, createCoordinationTools as l, createInProcessTransport as m, createMcpServer as n, eventToSnapshot as o, type SpawnJournal as p, type SpawnEvent as q, type Settled as r, type AgentSpec as s, type Agent as t, type RootHandle as u, type SupervisedResult as v, type Spend as w, type Scope as x, type ExecutorFactory as y, type Executor as z };