@tangle-network/agent-runtime 0.91.0 → 0.92.0

package/dist/profiles.d.ts

@@ -1,7 +1,7 @@
 import { a as UiFinding, U as UiLens } from './substrate-DO2GHNg2.js';
 export { C as CoderTask, b as UI_FINDING_SEVERITIES, c as UI_LENSES, d as UiFindingScreenshot, e as UiFindingSeverity, f as coderTaskToPrompt } from './substrate-DO2GHNg2.js';
 import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
-import { V as Validator, A as AgentRunSpec, c as OutputAdapter, D as Driver, S as SandboxClient } from './types-SyuwunY_.js';
+import { V as Validator, e as AgentRunSpec, d as OutputAdapter, D as Driver, S as SandboxClient } from './types-B00NtbCs.js';
 import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
 import '@tangle-network/agent-eval';
 

package/dist/{router-client-DJImUDlm.d.ts → sanitize-C9go6tXj.d.ts}

@@ -1,3 +1,6 @@
+import { ControlEvalResult, KnowledgeReadinessReport, KnowledgeRequirement } from '@tangle-network/agent-eval';
+import { A as AgentRuntimeEvent, b as RuntimeStreamEvent, c as AgentTaskStatus } from './types-B00NtbCs.js';
+
 /**
  * THE canonical agentic tool-loop. One inference turn → run any requested tools → fold the
  * results back as `tool` messages → repeat, until the model answers without a tool call or the
@@ -213,4 +216,113 @@ declare function routerBrain(cfg: RouterConfig, opts?: {
     temperature?: number;
 }): ToolLoopChat;
 
-export { type RouterConfig as R, type ToolLoopChat as T, type ToolLoopCompactionOptions as a, type ToolSpec as b, type RouterChatResult as c, type RouterChatToolsResult as d, type RouterToolCall as e, type RouterToolLoopResult as f, type ToolLoopCompaction as g, routerChatWithTools as h, routerChatWithUsage as i, routerToolLoop as j, routerBrain as r };
+/**
+ *
+ * Sanitization for runtime telemetry. The rule: nothing user-controlled leaks
+ * unless the caller opts in with a `RuntimeTelemetryOptions` flag. This is the
+ * envelope that ends up in `agent_run.metadata.runtimeEvents` on every
+ * consumer, so the default must be safe.
+ *
+ * @stable
+ */
+
+/** @stable */
+interface RuntimeTelemetryOptions {
+    /**
+     * Include raw task inputs. Off by default because task inputs often contain
+     * customer facts, credentials, source text, or internal IDs.
+     */
+    includeInputs?: boolean;
+    /** Include requirement descriptions. Secret requirements are always redacted. */
+    includeRequirementDescriptions?: boolean;
+    /** Include evidence IDs. Off by default; counts are safer for shared reports. */
+    includeEvidenceIds?: boolean;
+    /** Include user answers from question preflight. Off by default. */
+    includeUserAnswers?: boolean;
+    /** Include action payloads and action results for control steps. Off by default. */
+    includeControlPayloads?: boolean;
+    /** Include task metadata. Off by default because metadata may carry IDs or policy internals. */
+    includeMetadata?: boolean;
+    /** Include eval detail/evidence strings. Off by default because validators may echo private input. */
+    includeEvalDetails?: boolean;
+}
+/** @stable */
+interface SanitizedKnowledgeRequirement {
+    id: string;
+    description?: string;
+    requiredFor: string[];
+    category: KnowledgeRequirement['category'];
+    acquisitionMode: KnowledgeRequirement['acquisitionMode'];
+    importance: KnowledgeRequirement['importance'];
+    freshness: KnowledgeRequirement['freshness'];
+    sensitivity: KnowledgeRequirement['sensitivity'];
+    confidenceNeeded: number;
+    currentConfidence: number;
+    evidenceCount: number;
+    evidenceIds?: string[];
+    fallbackPolicy: KnowledgeRequirement['fallbackPolicy'];
+}
+/** @stable */
+interface SanitizedKnowledgeReadinessReport {
+    taskId: string;
+    readinessScore: number;
+    recommendedAction: KnowledgeReadinessReport['recommendedAction'];
+    severity: KnowledgeReadinessReport['severity'];
+    reason: string;
+    blockingMissingRequirements: SanitizedKnowledgeRequirement[];
+    nonBlockingGaps: SanitizedKnowledgeRequirement[];
+    evidenceCount: number;
+    evidenceIds?: string[];
+    missingRequirementIds: string[];
+}
+/** Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. @stable */
+declare function sanitizeKnowledgeReadinessReport(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions): SanitizedKnowledgeReadinessReport;
+/** Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. @stable */
+declare function sanitizeAgentRuntimeEvent<TState, TAction, TActionResult, TEval extends ControlEvalResult>(event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>, options?: RuntimeTelemetryOptions): Record<string, unknown>;
+/** Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. @stable */
+declare function sanitizeRuntimeStreamEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions): Record<string, unknown>;
+/** @stable */
+interface RuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> {
+    onEvent: (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => void;
+    events: Array<Record<string, unknown>>;
+}
+/** @stable */
+type RuntimeStreamEventSink = (event: RuntimeStreamEvent) => void;
+/** @stable */
+interface RuntimeStreamEventSummary {
+    /** Total count of sanitized events collected. */
+    eventCount: number;
+    /** Count of events per `type`. Useful for log-line summaries. */
+    eventCountsByType: Record<string, number>;
+    /** First session id observed in a `session_created` / `session_resumed` event, if any. */
+    firstSessionId?: string;
+    /** Last `final` event's status, if a final event was observed. */
+    finalStatus?: AgentTaskStatus;
+    /** Last `final` event's reason, if a final event was observed. */
+    finalReason?: string;
+    /** Concatenated `text_delta.text` across the stream, even when payloads are redacted. */
+    finalText: string;
+}
+/** @stable */
+interface RuntimeStreamEventCollector {
+    onEvent: RuntimeStreamEventSink;
+    events: Array<Record<string, unknown>>;
+    /** Snapshot of a small streaming-flavored summary derived from collected events. */
+    summary(): RuntimeStreamEventSummary;
+}
+/** Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. @stable */
+declare function createRuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult>(options?: RuntimeTelemetryOptions): RuntimeEventCollector<TState, TAction, TActionResult, TEval>;
+/**
+ *
+ * Streaming-event counterpart of `createRuntimeEventCollector`. Pass each
+ * event yielded by `runAgentTaskStream` through `onEvent` and read the
+ * sanitized copies off `events`; the same `RuntimeTelemetryOptions` redaction
+ * flags apply. Kept distinct from `createRuntimeEventCollector` because the
+ * stream and non-stream event shapes overlap on `type` literals — dispatching
+ * on `type` alone would misroute events.
+ *
+ * @stable
+ */
+declare function createRuntimeStreamEventCollector(options?: RuntimeTelemetryOptions): RuntimeStreamEventCollector;
+
+export { type RouterConfig as R, type SanitizedKnowledgeReadinessReport as S, type ToolLoopChat as T, type ToolLoopCompactionOptions as a, type ToolSpec as b, type RuntimeTelemetryOptions as c, type RuntimeEventCollector as d, type RuntimeStreamEventCollector as e, createRuntimeEventCollector as f, createRuntimeStreamEventCollector as g, sanitizeKnowledgeReadinessReport as h, sanitizeRuntimeStreamEvent as i, type RouterChatResult as j, type RouterChatToolsResult as k, type RouterToolCall as l, type RouterToolLoopResult as m, type ToolLoopCompaction as n, routerChatWithTools as o, routerChatWithUsage as p, routerToolLoop as q, routerBrain as r, sanitizeAgentRuntimeEvent as s };

package/dist/{structural-rollout-MwlpgQ-6.d.ts → structural-rollout-DHGDbhvR.d.ts}

@@ -1,6 +1,6 @@
-import { R as RuntimeHooks, a as SelectionReceipt } from './types-SyuwunY_.js';
-import { C as Corpus, O as Outcome } from './worktree-fanout-BDFQIO-Y.js';
-import { A as Agent, B as Budget, S as Scope } from './types-eMNgWgFi.js';
+import { R as RuntimeHooks, a as SelectionReceipt } from './types-B00NtbCs.js';
+import { C as Corpus, O as Outcome } from './worktree-fanout-BUb2Ag02.js';
+import { A as Agent, B as Budget, S as Scope } from './types-DAdIm4AC.js';
 
 /**
  * The general agentic primitive — sequential (depth) and parallel (breadth) over a shared,

package/dist/{supervise-DPmYPk0j.d.ts → supervise-T2pazU3G.d.ts}

@@ -1,7 +1,7 @@
-import { S as Scope, a as ResultBlobStore, B as Budget, A as Agent, b as SupervisedResult } from './types-eMNgWgFi.js';
-import { M as MakeWorkerAgent, A as AnalystRegistry, E as ExecutorConfig } from './coordination-rRj5hjJK.js';
-import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './router-client-DJImUDlm.js';
-import { D as DeliverableSpec } from './completion-gate-DkAnUmpb.js';
+import { S as Scope, a as ResultBlobStore, B as Budget, A as Agent, b as SupervisedResult } from './types-DAdIm4AC.js';
+import { M as MakeWorkerAgent, A as AnalystRegistry, E as ExecutorConfig } from './coordination-DxJ83oZA.js';
+import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './sanitize-C9go6tXj.js';
+import { D as DeliverableSpec } from './completion-gate-BLaiN0-X.js';
 
 /** The supervisor's profile — the subset of an `AgentProfile` that selects + shapes its brain.
  *  `harness` is the backend-as-data discriminant; `systemPrompt` is the standing instruction. */

package/dist/{types-SyuwunY_.d.ts → types-B00NtbCs.d.ts}

@@ -1308,4 +1308,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export { type MountRecorder as $, type AgentRunSpec as A, type BackendErrorDetail as B, type RuntimeHookContext as C, type Driver as D, type ExecCtx as E, type RuntimeHookErrorContext as F, type RuntimeHookEvent as G, type RuntimeHookPhase as H, type Iteration as I, type RuntimeHookTarget as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, type RuntimeRunHandle as M, type RuntimeRunPersistenceAdapter as N, type OpenAIChatTool as O, type RuntimeRunRow as P, composeRuntimeHooks as Q, type RuntimeHooks as R, type SandboxClient as S, defineRuntimeHooks as T, notifyRuntimeDecisionPoint as U, type Validator as V, notifyRuntimeHookEvent as W, startRuntimeRun as X, type LoopWinner as Y, type LoopLineageOptions as Z, type LoopResult as _, type SelectionReceipt as a, type LoopDecisionPayload as a0, type LoopEndedPayload as a1, type LoopIterationDispatchPayload as a2, type LoopIterationEndedPayload as a3, type LoopIterationStartedPayload as a4, type LoopPlanDescription as a5, type LoopPlanPayload as a6, type LoopStartedPayload as a7, type LoopTeardownFailedPayload as a8, type MountManifestEntry as a9, type RunProvenance as aa, type ValidationCtx as ab, type RuntimeStreamEvent as b, type OutputAdapter as c, type LoopTraceEvent as d, type LoopSandboxPlacement as e, type LoopTraceEmitter as f, type AgentBackendInput as g, type OpenAIChatToolChoice as h, type OpenAIChatResponseFormat as i, type AgentExecutionBackend as j, type AgentBackendContext as k, type RunAgentTaskOptions as l, type AgentTaskRunResult as m, type RunAgentTaskStreamOptions as n, type AgentRuntimeEvent as o, type AgentTaskStatus as p, type RuntimeSessionStore as q, type RuntimeSession as r, type AgentAdapter as s, type AgentKnowledgeProvider as t, type AgentRuntimeEventSink as u, type AgentTaskContext as v, type AgentTaskSpec as w, type RuntimeDecisionEvidenceRef as x, type RuntimeDecisionKind as y, type RuntimeDecisionPoint as z };
+export { type MountRecorder as $, type AgentRuntimeEvent as A, type BackendErrorDetail as B, type RuntimeHookContext as C, type Driver as D, type ExecCtx as E, type RuntimeHookErrorContext as F, type RuntimeHookEvent as G, type RuntimeHookPhase as H, type Iteration as I, type RuntimeHookTarget as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, type RuntimeRunHandle as M, type RuntimeRunPersistenceAdapter as N, type OpenAIChatTool as O, type RuntimeRunRow as P, composeRuntimeHooks as Q, type RuntimeHooks as R, type SandboxClient as S, defineRuntimeHooks as T, notifyRuntimeDecisionPoint as U, type Validator as V, notifyRuntimeHookEvent as W, startRuntimeRun as X, type LoopWinner as Y, type LoopLineageOptions as Z, type LoopResult as _, type SelectionReceipt as a, type LoopDecisionPayload as a0, type LoopEndedPayload as a1, type LoopIterationDispatchPayload as a2, type LoopIterationEndedPayload as a3, type LoopIterationStartedPayload as a4, type LoopPlanDescription as a5, type LoopPlanPayload as a6, type LoopStartedPayload as a7, type LoopTeardownFailedPayload as a8, type MountManifestEntry as a9, type RunProvenance as aa, type ValidationCtx as ab, type RuntimeStreamEvent as b, type AgentTaskStatus as c, type OutputAdapter as d, type AgentRunSpec as e, type LoopSandboxPlacement as f, type LoopTraceEvent as g, type LoopTraceEmitter as h, type AgentBackendInput as i, type OpenAIChatToolChoice as j, type OpenAIChatResponseFormat as k, type AgentExecutionBackend as l, type AgentBackendContext as m, type RunAgentTaskOptions as n, type AgentTaskRunResult as o, type RunAgentTaskStreamOptions as p, type RuntimeSessionStore as q, type RuntimeSession as r, type AgentAdapter as s, type AgentKnowledgeProvider as t, type AgentRuntimeEventSink as u, type AgentTaskContext as v, type AgentTaskSpec as w, type RuntimeDecisionEvidenceRef as x, type RuntimeDecisionKind as y, type RuntimeDecisionPoint as z };

package/dist/{types-eMNgWgFi.d.ts → types-DAdIm4AC.d.ts}

@@ -1,7 +1,7 @@
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { BackendType } from '@tangle-network/sandbox';
-import { L as LoopTokenUsage, R as RuntimeHooks } from './types-SyuwunY_.js';
+import { L as LoopTokenUsage, R as RuntimeHooks } from './types-B00NtbCs.js';
 
 /**
  *

package/dist/{worktree-fanout-BDFQIO-Y.d.ts → worktree-fanout-BUb2Ag02.d.ts}

@@ -1,9 +1,9 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { N as NodeId, d as Settled, e as Spend, f as AgentSpec, S as Scope, g as SpawnJournal, a as ResultBlobStore, h as ExecutorRegistry, B as Budget, A as Agent, i as RootHandle, b as SupervisedResult, c as Executor } from './types-eMNgWgFi.js';
-import { I as Iteration, R as RuntimeHooks } from './types-SyuwunY_.js';
+import { N as NodeId, d as Settled, e as Spend, f as AgentSpec, S as Scope, g as SpawnJournal, a as ResultBlobStore, h as ExecutorRegistry, B as Budget, A as Agent, i as RootHandle, b as SupervisedResult, c as Executor } from './types-DAdIm4AC.js';
+import { I as Iteration, R as RuntimeHooks } from './types-B00NtbCs.js';
 import { BackendType } from '@tangle-network/sandbox';
-import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-DkAnUmpb.js';
+import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-BLaiN0-X.js';
 import { L as LocalHarness, r as runLocalHarness } from './local-harness-dcD5WTTr.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.91.0",
+  "version": "0.92.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": {
@@ -64,6 +64,11 @@
       "import": "./dist/platform.js",
       "default": "./dist/platform.js"
     },
+    "./candidate-execution": {
+      "types": "./dist/candidate-execution/index.d.ts",
+      "import": "./dist/candidate-execution/index.js",
+      "default": "./dist/candidate-execution/index.js"
+    },
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
       "import": "./dist/mcp/index.js",
@@ -82,25 +87,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "prepare": "(git rev-parse --git-dir > /dev/null 2>&1 && git config core.hooksPath .githooks) || true; tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "biome check src tests examples",
-    "lint:fix": "biome check --write src tests examples",
-    "typecheck": "tsc --noEmit && pnpm run typecheck:examples",
-    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
-    "verify:package": "node scripts/verify-package-exports.mjs",
-    "docs:api": "typedoc && node scripts/gen-primitive-catalog.mjs",
-    "docs:freshness": "node scripts/check-docs-freshness.mjs",
-    "docs:check": "pnpm run docs:api && git diff --exit-code -- docs/api && pnpm run docs:freshness"
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/agent-eval": "^0.108.1",
-    "@tangle-network/agent-interface": "^0.24.0",
+    "@tangle-network/agent-eval": "^0.113.0",
+    "@tangle-network/agent-interface": "^0.25.0",
     "@tangle-network/sandbox": "^0.9.7",
     "@types/node": "^25.9.3",
     "playwright": "^1.61.0",
@@ -111,26 +101,13 @@
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
-  "pnpm": {
-    "minimumReleaseAge": 4320,
-    "minimumReleaseAgeExclude": [
-      "@tangle-network/agent-eval",
-      "@tangle-network/agent-interface",
-      "@tangle-network/agent-profile-materialize",
-      "@tangle-network/sandbox"
-    ],
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  },
   "engines": {
     "node": ">=20"
   },
   "license": "MIT",
-  "packageManager": "pnpm@10.28.0",
   "peerDependencies": {
     "@tangle-network/agent-eval": ">=0.101.0 <1.0.0",
-    "@tangle-network/agent-interface": ">=0.24.0 <1.0.0",
+    "@tangle-network/agent-interface": ">=0.25.0 <1.0.0",
     "@tangle-network/sandbox": ">=0.8.0 <1.0.0",
     "playwright": "^1.40.0"
   },
@@ -143,7 +120,21 @@
     }
   },
   "dependencies": {
-    "@tangle-network/agent-knowledge": "^1.11.1",
-    "@tangle-network/agent-profile-materialize": "0.3.0"
+    "@tangle-network/agent-knowledge": "^1.11.2",
+    "@tangle-network/agent-profile-materialize": "0.3.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src tests examples",
+    "lint:fix": "biome check --write src tests examples",
+    "typecheck": "tsc --noEmit && pnpm run typecheck:examples",
+    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
+    "verify:package": "node scripts/verify-package-exports.mjs",
+    "docs:api": "typedoc && node scripts/gen-primitive-catalog.mjs",
+    "docs:freshness": "node scripts/check-docs-freshness.mjs",
+    "docs:check": "pnpm run docs:api && git diff --exit-code -- docs/api && pnpm run docs:freshness"
   }
-}
+}

package/skills/build-with-agent-runtime/SKILL.md

@@ -92,7 +92,7 @@ to its native default (`HARNESS_NATIVE_MODEL`) — never silently dropped.
 | **Spawn N coding agents on isolated git worktrees, keep the one whose patch passes checks** | `worktreeFanout` + `createWorktreeCliExecutor` + `gateOnDeliverable(DeliverableSpec)` over a raw `WorktreePatchArtifact`, winner via `selectValidWinner` — `/loops` — NOT a hand-rolled spawn-loop / "coder" role | canonical-api §3.1 / §5 |
 | **Sandbox coding rollout** (fresh box/round, or persistent+resume) | `runLoop(options)` / `openSandboxRun(client, opts, deliverable)` — `/loops` | canonical-api §3.1 |
 | **Optimize a CODE surface** in a gated loop | `improvementDriver({ worktree, generator })` — root `.` | canonical-api §3.4 |
-| **Optimize a PROMPT/config surface** (one call) — START HERE | `improve(profile, findings, { surface, gate })` — root `.` (the one pluggable RSI verb; picks the default proposer from `surface` — `gepaProposer` for prompt, `skillOptProposer` for skills — and wraps `selfImprove`; drop to `selfImprove({ agent, scenarios, judge, baselineSurface })` from `agent-eval/contract` only for the lower-level loop) | canonical-api §3.4 |
+| **Optimize any agent/code surface** (one call) — START HERE | `improve(profile, findings, { surface, gate })` — root `.`; prompt and skill-document surfaces have built-in proposers, config/whole-profile surfaces accept a proposer, rollout policy enumerates bounded variants, and code gets isolated incumbent/candidate worktrees; drop to `selfImprove({ agent, scenarios, judge, baselineSurface })` only for lower-level control | canonical-api §3.4 |
 | **Gate: ship/hold a candidate** (campaign ctx) | `defaultProductionGate` / `heldOutGate` / `composeGate` — `agent-eval/contract`; `neutralizationGate` (footprint-matched PLACEBO gate — proves a held-out lift is CONTENT, not added prompt/mount footprint) — `agent-eval/campaign` | canonical-api §3.4 |
 | **Gate: ship/hold from a `BenchmarkReport`** (per-task cells) | `promotionGate({ report, incumbent, candidate })` — `/loops` | canonical-api §3.4 |
 | **Run the full multi-generation flywheel + certify** | `runStrategyEvolution(config)` — `/loops` | canonical-api §3.4 |