@tangle-network/agent-runtime 0.72.0 → 0.73.0

package/dist/{types-K8-xkiw1.d.ts → types-JufmXF2a.d.ts}

@@ -763,9 +763,15 @@ interface AgentRunSpec<Task> {
      * files, or seed datasets. The hook is part of the runtime surface so loop
      * consumers do not hand-roll Sandbox SDK orchestration just to prepare a
      * workspace before the agent sees it.
+     *
+     * `ctx.recordMount` records what was placed into the box so the run carries a
+     * provenance manifest (`LoopResult.provenance.mounts`). It is optional and
+     * provenance-only — the kernel never reads box contents and attaches no
+     * meaning to the entries; not calling it simply leaves the manifest empty.
      */
     prepareBox?: (box: SandboxInstance, ctx: {
         signal: AbortSignal;
+        recordMount: MountRecorder;
     }) => Promise<void> | void;
     /**
      * Per-spec stable name. Surfaced in trace events and the default winner
@@ -801,6 +807,75 @@ interface LoopTokenUsage {
     input: number;
     output: number;
 }
+/**
+ * One mounted resource recorded during box preparation — a pure provenance
+ * record of what the caller placed into a box before the agent saw it. The
+ * kernel never reads box contents itself (it does not know what was mounted);
+ * the caller, which owns the bytes inside `prepareBox`, supplies each entry via
+ * `recordMount`. Carries no domain semantics — just where the resource landed,
+ * its content fingerprint, its size, and where it came from — so a run is
+ * auditable after the fact ("what exactly was this agent given?").
+ *
+ * @experimental
+ */
+interface MountManifestEntry {
+    /** Destination path inside the box where the resource was placed. */
+    path: string;
+    /** Hex SHA-256 of the mounted bytes. The caller computes it from the bytes
+     *  it wrote — the kernel does not hash box contents. */
+    sha256: string;
+    /** Size of the mounted resource in bytes. */
+    bytes: number;
+    /** Free-form origin of the resource (e.g. a repo ref, a corpus id, a local
+     *  path, a URL). Provenance only — the kernel attaches no meaning to it. */
+    source: string;
+}
+/**
+ * A record of one candidate-selection decision: which iteration the selector
+ * picked (or rejected) and why. Pure audit trail of the SELECTOR role — it
+ * carries the selector's identity, the candidate's score, and an optional
+ * human-readable reason, with no domain semantics. The kernel emits one receipt
+ * per scored candidate at finalize so a run answers "why did THIS one win?".
+ *
+ * @experimental
+ */
+interface SelectionReceipt {
+    /** Iteration index this receipt is about. */
+    candidateIndex: number;
+    /** True for the iteration the selector chose as winner; false otherwise. */
+    selected: boolean;
+    /** The candidate's verdict score, when it has one. */
+    score?: number;
+    /** Why this candidate was (or was not) selected, when the selector states it. */
+    reason?: string;
+    /** Identity of the selector that produced this receipt — `'caller'` (an
+     *  explicit `selectWinner`), `'driver'` (a driver-authored winner), or
+     *  `'default'` (the kernel's best-valid-score argmax). */
+    selector: 'caller' | 'driver' | 'default';
+}
+/**
+ * Domain-free run provenance: a manifest of what was mounted into the run's
+ * boxes and the receipts for how the winner was selected. Surfaced on
+ * `LoopResult` purely for run auditability — nothing in the kernel branches on
+ * it. Empty arrays when the caller recorded no mounts and there was no
+ * candidate to select.
+ *
+ * @experimental
+ */
+interface RunProvenance {
+    /** Every resource recorded via `prepareBox`'s `recordMount`, in record order. */
+    mounts: MountManifestEntry[];
+    /** One receipt per scored candidate at finalize, in iteration order. */
+    selectionReceipts: SelectionReceipt[];
+}
+/**
+ * Records a mounted resource into the run's provenance manifest. Passed to
+ * `prepareBox` so the caller — which owns the bytes it writes into the box —
+ * declares what it mounted without the kernel having to inspect box contents.
+ *
+ * @experimental
+ */
+type MountRecorder = (entry: MountManifestEntry) => void;
 /** @experimental */
 interface Iteration<Task, Output> {
     /** 0-based iteration index assigned by the kernel. */
@@ -892,6 +967,10 @@ interface LoopResult<Task, Output, Decision> {
      *  `ctx.cost.observeTokens` in a `runProfileMatrix` dispatch so the
      *  integrity guard sees real LLM activity. */
     tokenUsage: LoopTokenUsage;
+    /** Domain-free run provenance for auditability: the mount manifest recorded
+     *  during `prepareBox` and the selection receipts for how the winner was
+     *  chosen. Always present; empty arrays when nothing was recorded. */
+    provenance: RunProvenance;
 }
 /**
  * Minimal sandbox client surface the kernel calls. Satisfied structurally by
@@ -1178,4 +1257,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export { type LoopIterationDispatchPayload as $, type AgentRunSpec as A, type BackendErrorDetail as B, type RuntimeHookEvent as C, type RuntimeHookPhase as D, type ExecCtx as E, type RuntimeHookTarget as F, type RuntimeRunHandle as G, type RuntimeRunPersistenceAdapter as H, type Iteration as I, type RuntimeRunRow as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, composeRuntimeHooks as M, defineRuntimeHooks as N, type OpenAIChatTool as O, notifyRuntimeDecisionPoint as P, notifyRuntimeHookEvent as Q, type RuntimeStreamEvent as R, type SandboxClient as S, startRuntimeRun as T, type Driver as U, type Validator as V, type LoopWinner as W, type LoopLineageOptions as X, type LoopResult as Y, type LoopDecisionPayload as Z, type LoopEndedPayload as _, type OutputAdapter as a, type LoopIterationEndedPayload as a0, type LoopIterationStartedPayload as a1, type LoopPlanDescription as a2, type LoopPlanPayload as a3, type LoopStartedPayload as a4, type LoopTeardownFailedPayload as a5, type ValidationCtx as a6, type RuntimeHooks as b, type LoopTraceEvent as c, type LoopSandboxPlacement as d, type LoopTraceEmitter as e, type AgentBackendInput as f, type AgentExecutionBackend as g, type OpenAIChatToolChoice as h, type AgentBackendContext as i, type RunAgentTaskOptions as j, type AgentTaskRunResult as k, type RunAgentTaskStreamOptions as l, type AgentRuntimeEvent as m, type AgentTaskStatus as n, type RuntimeSessionStore as o, type RuntimeSession as p, type AgentAdapter as q, type AgentKnowledgeProvider as r, type AgentRuntimeEventSink as s, type AgentTaskContext as t, type AgentTaskSpec as u, type RuntimeDecisionEvidenceRef as v, type RuntimeDecisionKind as w, type RuntimeDecisionPoint as x, type RuntimeHookContext as y, type RuntimeHookErrorContext as z };
+export { type LoopEndedPayload as $, type AgentRunSpec as A, type BackendErrorDetail as B, type RuntimeHookEvent as C, type RuntimeHookPhase as D, type ExecCtx as E, type RuntimeHookTarget as F, type RuntimeRunHandle as G, type RuntimeRunPersistenceAdapter as H, type Iteration as I, type RuntimeRunRow as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, composeRuntimeHooks as M, defineRuntimeHooks as N, type OpenAIChatTool as O, notifyRuntimeDecisionPoint as P, notifyRuntimeHookEvent as Q, type RuntimeStreamEvent as R, type SandboxClient as S, startRuntimeRun as T, type Driver as U, type Validator as V, type LoopWinner as W, type LoopLineageOptions as X, type LoopResult as Y, type MountRecorder as Z, type LoopDecisionPayload as _, type OutputAdapter as a, type LoopIterationDispatchPayload as a0, type LoopIterationEndedPayload as a1, type LoopIterationStartedPayload as a2, type LoopPlanDescription as a3, type LoopPlanPayload as a4, type LoopStartedPayload as a5, type LoopTeardownFailedPayload as a6, type MountManifestEntry as a7, type RunProvenance as a8, type SelectionReceipt as a9, type ValidationCtx as aa, type RuntimeHooks as b, type LoopTraceEvent as c, type LoopSandboxPlacement as d, type LoopTraceEmitter as e, type AgentBackendInput as f, type AgentExecutionBackend as g, type OpenAIChatToolChoice as h, type AgentBackendContext as i, type RunAgentTaskOptions as j, type AgentTaskRunResult as k, type RunAgentTaskStreamOptions as l, type AgentRuntimeEvent as m, type AgentTaskStatus as n, type RuntimeSessionStore as o, type RuntimeSession as p, type AgentAdapter as q, type AgentKnowledgeProvider as r, type AgentRuntimeEventSink as s, type AgentTaskContext as t, type AgentTaskSpec as u, type RuntimeDecisionEvidenceRef as v, type RuntimeDecisionKind as w, type RuntimeDecisionPoint as x, type RuntimeHookContext as y, type RuntimeHookErrorContext as z };

package/dist/{worktree-JXGJ1MxQ.d.ts → worktree-DaxOvw-C.d.ts}

@@ -2,7 +2,7 @@ import { ChildProcess } from 'node:child_process';
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { BackendType } from '@tangle-network/sandbox';
-import { L as LoopTokenUsage, b as RuntimeHooks } from './types-K8-xkiw1.js';
+import { L as LoopTokenUsage, b as RuntimeHooks } from './types-JufmXF2a.js';
 
 /**
  * @experimental

package/dist/{worktree-fanout-DJHQy7Ux.d.ts → worktree-fanout-DIffZohV.d.ts}

@@ -1,7 +1,7 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { A as AgentSpec, E as ExecutorRegistry, B as Budget, g as Agent, S as SpawnJournal, h as ResultBlobStore, i as RootHandle, j as SupervisedResult, N as NodeId, k as Settled, l as Spend, m as Scope, L as LocalHarness, G as GitRunner, r as runLocalHarness, n as Executor, o as DeliverableSpec } from './worktree-JXGJ1MxQ.js';
-import { b as RuntimeHooks, I as Iteration } from './types-K8-xkiw1.js';
+import { A as AgentSpec, E as ExecutorRegistry, B as Budget, g as Agent, S as SpawnJournal, h as ResultBlobStore, i as RootHandle, j as SupervisedResult, N as NodeId, k as Settled, l as Spend, m as Scope, L as LocalHarness, G as GitRunner, r as runLocalHarness, n as Executor, o as DeliverableSpec } from './worktree-DaxOvw-C.js';
+import { b as RuntimeHooks, I as Iteration } from './types-JufmXF2a.js';
 import { BackendType } from '@tangle-network/sandbox';
 
 /**
@@ -869,9 +869,12 @@ type WorktreeCheckRunner = (opts: {
  * result onto the `Executor` port (artifact + spend) and owns the teardown point. The §1.5 payload
  * (authored systemPrompt + model) reaches the harness inside the core, not here.
  *
- * Token accounting: a harness CLI does not surface usage, so this executor is `budgetExempt: true`
- * — its spend is NOT metered against the conserved pool and its iterations are EXCLUDED from the
- * equal-k arms by construction (mirrors `cliExecutor`).
+ * Token accounting: a harness CLI does not surface usage, so this executor defaults to
+ * `budgetExempt: true` — its spend is NOT metered against the conserved pool and its iterations are
+ * EXCLUDED from the equal-k arms by construction (mirrors `cliExecutor`). The exemption is an
+ * explicit, documented `budgetExempt` option rather than a buried hardcode: set it `false` ONLY for
+ * a harness that genuinely surfaces real token/usd usage to meter into the pool — otherwise the
+ * executor would meter a fabricated zero, which the no-silent-zeros rule forbids.
  */
 
 /** Terminal artifact of one worktree-CLI run — the canonical worktree-harness result (the captured
@@ -909,6 +912,13 @@ interface WorktreeCliExecutorOptions {
     /** Test seam — inject the verification-command runner so unit tests script test/typecheck
      *  outcomes without spawning a real shell. Defaults to a `/bin/sh -c` spawn in the worktree. */
     runCommand?: WorktreeCheckRunner;
+    /**
+     * Exclude this leaf's spend from the conserved pool + equal-k arms. Defaults to `true` because a
+     * coding-harness CLI does not surface token usage, so metering it would record a fabricated zero
+     * (the no-silent-zeros rule forbids that). Set `false` ONLY for a harness that surfaces real
+     * token/usd usage worth metering — the executor would then debit the (real) spend it captures.
+     */
+    budgetExempt?: boolean;
 }
 /**
  * Build a worktree-CLI leaf `Executor`. Per-spawn (a fresh worktree + abort + teardown each), so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -39,6 +39,11 @@
       "import": "./dist/analyst-loop.js",
       "default": "./dist/analyst-loop.js"
     },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.ts",
+      "import": "./dist/lifecycle.js",
+      "default": "./dist/lifecycle.js"
+    },
     "./profiles": {
       "types": "./dist/profiles.d.ts",
       "import": "./dist/profiles.js",