@tangle-network/agent-runtime 0.18.0 → 0.19.0

package/dist/types-EKcAHfxI.d.ts

@@ -0,0 +1,225 @@
+import { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
+import { R as RuntimeRunHandle } from './runtime-run-4pbY3Jq5.js';
+
+/**
+ * @experimental
+ *
+ * Driven-loop substrate — type surface.
+ *
+ * The loop kernel orchestrates around the sandbox SDK; it does not invent
+ * its own notion of "what an agent is". Each iteration is a sandbox-SDK
+ * `streamPrompt` call against an `AgentProfile`. The kernel owns iteration
+ * accounting, concurrency, abort propagation, cost aggregation, and trace
+ * emission; the driver owns topology (plan + decide); the validator owns
+ * output scoring; the output adapter owns event-stream → typed-output decode.
+ */
+
+/** @experimental */
+interface DefaultVerdict {
+    /** Whether the output meets the validator's pass criteria. */
+    valid: boolean;
+    /** Aggregate score in [0, 1]. Drivers use this for winner selection. */
+    score: number;
+    /** Per-dimension scores. Free-form; weighted into `score` by the validator. */
+    scores?: Record<string, number>;
+    /** Human-readable rationale; surfaces in trace + final-result `winner.verdict`. */
+    notes?: string;
+}
+/** @experimental */
+interface ValidationCtx {
+    /** Iteration index this output came from (0-based). */
+    iteration: number;
+    /** Cooperative cancellation channel. */
+    signal: AbortSignal;
+}
+/** @experimental */
+interface Validator<Output, Verdict = DefaultVerdict> {
+    validate(output: Output, ctx: ValidationCtx): Promise<Verdict>;
+}
+/**
+ * Sandbox-SDK-shaped agent specification.
+ *
+ * The kernel uses `profile` to instantiate a sandbox per iteration, formats
+ * `task` into a prompt via `taskToPrompt`, and merges `sandboxOverrides` into
+ * the `CreateSandboxOptions` it passes to `client.create`. Heterogeneous
+ * fanout supplies multiple `AgentRunSpec`s and the kernel round-robins
+ * through them when the driver plans N tasks.
+ *
+ * @experimental
+ */
+interface AgentRunSpec<Task> {
+    /** Sandbox SDK profile — what kind of agent runs the task. */
+    profile: AgentProfile;
+    /** Task → prompt formatter. Pure and deterministic. */
+    taskToPrompt: (task: Task) => string;
+    /**
+     * Per-spec stable name. Surfaced in trace events and the default winner
+     * selector tiebreak. Falls back to `profile.name ?? 'agent'`.
+     */
+    name?: string;
+    /**
+     * Optional sandbox-SDK `CreateSandboxOptions` overrides merged on top of
+     * the kernel's defaults. `backend.profile` is set to `profile` by the
+     * kernel and cannot be overridden here — use `profile` itself for that.
+     */
+    sandboxOverrides?: Partial<Omit<CreateSandboxOptions, 'backend'>> & {
+        backend?: Omit<NonNullable<CreateSandboxOptions['backend']>, 'profile'>;
+    };
+}
+/**
+ * Stream of `SandboxEvent`s → typed `Output`.
+ *
+ * Adapters are pure functions over the already-collected event array; they
+ * do not receive the live AsyncIterable so they can be replayed against
+ * persisted streams during tests / replays.
+ *
+ * @experimental
+ */
+interface OutputAdapter<Output> {
+    parse(events: SandboxEvent[]): Output;
+}
+/** @experimental */
+interface Iteration<Task, Output> {
+    /** 0-based iteration index assigned by the kernel. */
+    index: number;
+    task: Task;
+    /** Stable name of the `AgentRunSpec` that produced this iteration. */
+    agentRunName: string;
+    output?: Output;
+    verdict?: DefaultVerdict;
+    error?: Error;
+    /** Raw sandbox event stream collected for this iteration. */
+    events: SandboxEvent[];
+    startedAt: number;
+    endedAt: number;
+    costUsd: number;
+}
+/** @experimental */
+interface Driver<Task, Output, Decision> {
+    /**
+     * Stable identifier surfaced in trace events. Default `'driver'`.
+     */
+    readonly name?: string;
+    /**
+     * Tasks to issue this iteration. `[task]` → refine; N copies → fanout;
+     * `[]` → no more work this round (kernel proceeds to `decide`).
+     */
+    plan(task: Task, history: ReadonlyArray<Iteration<Task, Output>>): Promise<Task[]>;
+    /**
+     * Inspect history and return the next state. The kernel terminates the
+     * loop when `decide` returns a value listed in `isTerminalDecision`
+     * (`'stop' | 'pick-winner' | 'fail' | 'done'`), when `maxIterations`
+     * is hit, or when the abort signal fires.
+     */
+    decide(history: ReadonlyArray<Iteration<Task, Output>>): Decision | Promise<Decision>;
+}
+/** @experimental */
+interface LoopWinner<Task, Output> {
+    task: Task;
+    output: Output;
+    verdict?: DefaultVerdict;
+    iterationIndex: number;
+    agentRunName: string;
+}
+/** @experimental */
+interface LoopResult<Task, Output, Decision> {
+    decision: Decision;
+    iterations: Iteration<Task, Output>[];
+    winner?: LoopWinner<Task, Output>;
+    durationMs: number;
+    /** Sum of every iteration's `costUsd`. */
+    costUsd: number;
+}
+/**
+ * Minimal sandbox client surface the kernel calls. Satisfied structurally by
+ * `new Sandbox({ apiKey, baseUrl })` — declared as a structural type so
+ * tests can pass a stub without instantiating the SDK.
+ *
+ * @experimental
+ */
+interface LoopSandboxClient {
+    create(options?: CreateSandboxOptions): Promise<SandboxInstance>;
+}
+/** @experimental */
+interface LoopTraceEmitter {
+    emit(event: LoopTraceEvent): void | Promise<void>;
+}
+/** @experimental */
+type LoopTraceEvent = {
+    kind: 'loop.started';
+    runId: string;
+    timestamp: number;
+    payload: LoopStartedPayload;
+} | {
+    kind: 'loop.iteration.started';
+    runId: string;
+    timestamp: number;
+    payload: LoopIterationStartedPayload;
+} | {
+    kind: 'loop.iteration.ended';
+    runId: string;
+    timestamp: number;
+    payload: LoopIterationEndedPayload;
+} | {
+    kind: 'loop.decision';
+    runId: string;
+    timestamp: number;
+    payload: LoopDecisionPayload;
+} | {
+    kind: 'loop.ended';
+    runId: string;
+    timestamp: number;
+    payload: LoopEndedPayload;
+};
+/** @experimental */
+interface LoopStartedPayload {
+    driver: string;
+    agentRunNames: string[];
+    maxIterations: number;
+    maxConcurrency: number;
+}
+/** @experimental */
+interface LoopIterationStartedPayload {
+    iterationIndex: number;
+    agentRunName: string;
+    taskHash: string;
+}
+/** @experimental */
+interface LoopIterationEndedPayload {
+    iterationIndex: number;
+    agentRunName: string;
+    outputHash?: string;
+    verdict?: DefaultVerdict;
+    error?: string;
+    costUsd: number;
+    durationMs: number;
+}
+/** @experimental */
+interface LoopDecisionPayload {
+    decision: string;
+    historyLength: number;
+}
+/** @experimental */
+interface LoopEndedPayload {
+    winnerIterationIndex?: number;
+    totalCostUsd: number;
+    durationMs: number;
+    iterations: number;
+}
+/** @experimental */
+interface ExecCtx {
+    /** Sandbox SDK client — the kernel calls `.create()` per iteration. */
+    sandboxClient: LoopSandboxClient;
+    /** Optional trace emitter. When set, the kernel emits `loop.*` events. */
+    traceEmitter?: LoopTraceEmitter;
+    /**
+     * Optional production-run handle. When set, every synthesized `llm_call`
+     * the kernel infers from a sandbox event stream is forwarded via
+     * `runHandle.observe` so per-run cost aggregates pick up loop spend.
+     */
+    runHandle?: RuntimeRunHandle;
+    /** Cooperative cancellation signal. */
+    signal?: AbortSignal;
+}
+
+export type { AgentRunSpec as A, DefaultVerdict as D, ExecCtx as E, Iteration as I, LoopWinner as L, OutputAdapter as O, Validator as V, Driver as a, LoopResult as b, LoopDecisionPayload as c, LoopEndedPayload as d, LoopIterationEndedPayload as e, LoopIterationStartedPayload as f, LoopSandboxClient as g, LoopStartedPayload as h, LoopTraceEmitter as i, LoopTraceEvent as j, ValidationCtx as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Reusable runtime lifecycle for domain-specific agents.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -33,6 +33,16 @@
       "types": "./dist/agent.d.ts",
       "import": "./dist/agent.js",
       "default": "./dist/agent.js"
+    },
+    "./loops": {
+      "types": "./dist/loops.d.ts",
+      "import": "./dist/loops.js",
+      "default": "./dist/loops.js"
+    },
+    "./profiles": {
+      "types": "./dist/profiles.d.ts",
+      "import": "./dist/profiles.js",
+      "default": "./dist/profiles.js"
     }
   },
   "files": [