@tangle-network/agent-runtime 0.89.0 → 0.90.0

package/README.md

@@ -1,14 +1,25 @@
 # @tangle-network/agent-runtime
 
-The engine Tangle's AI agents run on. It runs an agent — a **chat turn**, a **one-shot task**, or a **team of agents** working toward a goal — records every run, and uses those records to **measure and improve** agents against real pass/fail checks.
+The engine Tangle's AI agents run on. It runs an agent as a **chat turn**, a **one-shot task**, or a **team of agents** working toward a goal, records every run, and uses those records to **measure and improve** agents against real pass/fail checks.
 
-One loop, used three ways. Domain behavior (models, tools, knowledge) plugs in as adapters; the scoring statistics and the ship decision come from [`@tangle-network/agent-eval`](https://www.npmjs.com/package/@tangle-network/agent-eval); sandboxed execution from [`@tangle-network/sandbox`](https://www.npmjs.com/package/@tangle-network/sandbox).
+One loop, used four common ways. Domain behavior (models, tools, knowledge) plugs in as adapters; the scoring statistics and the ship decision come from [`@tangle-network/agent-eval`](https://www.npmjs.com/package/@tangle-network/agent-eval); sandboxed execution from [`@tangle-network/sandbox`](https://www.npmjs.com/package/@tangle-network/sandbox).
 
 ```bash
 pnpm add @tangle-network/agent-runtime @tangle-network/agent-eval @tangle-network/sandbox
 ```
 
-**See it run in 30 seconds** (offline, no keys) — the one move everything else builds on, a driver reading a worker's output and composing the next step from it:
+## Contents
+
+- [What you do with it](#what-you-do-with-it)
+- [Run a chat turn](#run-a-chat-turn)
+- [Supervise a team of agents](#supervise-a-team-of-agents)
+- [Improve an agent](#improve-an-agent)
+- [Improve a knowledge base](#improve-a-knowledge-base)
+- [How it works](#how-it-works-the-short-version)
+- [Examples](#examples)
+- [Where to go next](#where-to-go-next)
+
+**See it run in 30 seconds** (offline, no keys): the one move everything else builds on, a driver reading a worker's output and composing the next step from it:
 
 ```bash
 pnpm tsx examples/driver-loop/driver-loop.ts
@@ -18,9 +29,10 @@ pnpm tsx examples/driver-loop/driver-loop.ts
 
 | You want to… | Call |
 |---|---|
-| Run a **chat turn** — what every product agent does in production | `handleChatTurn(...)` |
+| Run a **chat turn** for a production product agent | `handleChatTurn(...)` |
 | Have one agent **supervise a team of agents** toward a goal | `supervise(profile, task, opts)` |
 | **Improve** an agent and prove the gain on fresh tasks | `improve(profile, findings, opts)` |
+| **Improve** a knowledge base with agents, checks, and safe promotion | `runKnowledgeImprovementJob(...)` |
 
 ### Run a chat turn
 
@@ -56,7 +68,7 @@ const result = await supervise(
 
 ### Improve an agent
 
-`improve` optimizes one part of an agent (its prompt, skills, or code) and **only ships a change if it beats the current agent on tasks it never practiced on** — so registering an agent for self-improvement can never make it worse.
+`improve` optimizes one part of an agent (its prompt, skills, or code) and **only ships a change if it beats the current agent on tasks it never practiced on**. Registering an agent for self-improvement cannot ship a worse candidate unless the caller supplies a bad measurement.
 
 ```ts
 import { improve } from '@tangle-network/agent-runtime'
@@ -68,16 +80,36 @@ const { profile, shipped, lift } = await improve(baseProfile, findings, {
 })
 ```
 
+### Improve a knowledge base
+
+`runKnowledgeImprovementJob` is the runtime-owned front door for KB, wiki, memory-backed, and RAG improvement jobs. It creates a candidate copy, runs supervised agents against it, checks readiness through `@tangle-network/agent-knowledge`, measures spend and timing, and promotes only when the candidate passes.
+
+```ts
+import { runKnowledgeImprovementJob } from '@tangle-network/agent-runtime/knowledge'
+
+const result = await runKnowledgeImprovementJob({
+  root: './kb',
+  goal: 'Improve support refund-policy knowledge',
+  readinessSpecs,
+  budget: { maxIterations: 8, maxTokens: 120_000, maxUsd: 10 },
+  backend,
+})
+
+console.log(result.promoted, result.measurement.supervisedSpent)
+```
+
+Use it when the product needs one knob for "make this knowledge base better" instead of wiring `improveKnowledgeBase`, a runtime supervisor, candidate workspaces, readiness checks, and promotion tracking by hand.
+
 ## How it works (the short version)
 
-- **One agent, run two ways.** The same agent runs at "do the task" speed and at "get better at the task" speed. "Driver", "worker", and "coordinator" aren't separate types — they're roles one agent plays.
-- **Everything is measured.** Every run is a trace: tokens, dollars, time, and a pass/fail score from a real check. "Better" is a number with a denominator, not a vibe — and "equally good but cheaper" is a result you can prove.
-- **Improvement is gated.** A change ships only after it beats the current agent on fresh tasks no tuning step ever saw, with a statistical test — not a single lucky run.
-- **The grader is honest.** Whatever gives feedback never sees the answer key, and scores are recomputed from the attempts actually run — an agent can't fabricate its own win.
+- **One agent, run two ways.** The same agent runs at "do the task" speed and at "get better at the task" speed. "Driver", "worker", and "coordinator" are roles one agent plays, not separate types.
+- **Everything is measured.** Every run is a trace: tokens, dollars, time, and a pass/fail score from a real check. "Better" is a number with a denominator, not a vibe, and "equally good but cheaper" is a result you can prove.
+- **Improvement is gated.** A change ships only after it beats the current agent on fresh tasks no tuning step ever saw, with a statistical test, not a single lucky run.
+- **The grader is honest.** Whatever gives feedback never sees the answer key, and scores are recomputed from the attempts actually run. An agent cannot fabricate its own win.
 
 ## Examples
 
-Runnable, grouped by what they show — copy the one nearest your task:
+Runnable, grouped by what they show. Copy the one nearest your task:
 
 | Do this | Example |
 |---|---|
@@ -85,20 +117,21 @@ Runnable, grouped by what they show — copy the one nearest your task:
 | Drive a team of agents to a goal | [`supervise`](./examples/supervise) · [`recursive-supervisor`](./examples/recursive-supervisor) |
 | Benchmark strategies on your own domain | [`coding-benchmark`](./examples/coding-benchmark) |
 | Benchmark **harnesses × models** over a real task suite (the real WebCode dataset) | [`webcode-matrix`](./examples/webcode-matrix) |
-| Render a **multi-profile leaderboard** — ranked board + score matrix + SVG/HTML charts, any domain | `leaderboard(records)` → `renderLeaderboardMarkdown` / `Svg` / `Html` |
+| Render a **multi-profile leaderboard** with ranked board, score matrix, and SVG/HTML charts | `leaderboard(records)` → `renderLeaderboardMarkdown` / `Svg` / `Html` |
 | Trace + bill + effort-gate the WebCode benchmark (the Intelligence SDK) | [`intelligence-webcode`](./examples/intelligence-webcode) |
 | Self-improve an agent, gated on a held-out set | [`improve`](./examples/improve) · [`self-improving-coder`](./examples/self-improving-coder) |
+| Improve a KB, wiki, or RAG corpus with runtime agents | [`docs/canonical-api.md`](./docs/canonical-api.md) |
 | Study coordination vs raw compute | [`ablation-suite`](./examples/ablation-suite) |
 
-All 28 live in [`examples/`](./examples).
+All 29 live in [`examples/`](./examples).
 
 ## Where to go next
 
-- New here? [`docs/concepts.md`](./docs/concepts.md) — the mental model in plain terms.
-- [`docs/canonical-api.md`](./docs/canonical-api.md) — find the primitive: "I want to ___ → use ___".
-- [`docs/api/primitive-catalog.md`](./docs/api/primitive-catalog.md) — every export in one generated, never-stale list with its import path. Check it before building anything new.
-- Import subpaths: the root export is the product surface (`handleChatTurn`, `improve`); deeper capabilities ship as subpaths — `/loops` (multi-agent + the loop kernel), `/mcp` (tool servers), `/intelligence` (observability drop-in), `/lifecycle`, `/agent`, `/profiles`, `/platform`, `/analyst-loop`, `/environment-provider`.
-- [`docs/architecture.md`](./docs/architecture.md) — the design, end to end.
-- [`bench/HARNESS.md`](./bench/HARNESS.md) — the experiment harness and how to run a benchmark.
+- New here? [`docs/concepts.md`](./docs/concepts.md), the mental model in plain terms.
+- [`docs/canonical-api.md`](./docs/canonical-api.md), find the primitive: "I want to ___ → use ___".
+- [`docs/api/primitive-catalog.md`](./docs/api/primitive-catalog.md), every export in one generated, never-stale list with its import path. Check it before building anything new.
+- Import subpaths: the root export is the product surface (`handleChatTurn`, `improve`); deeper capabilities ship as subpaths: `/loops` (multi-agent + the loop kernel), `/knowledge` (KB improvement), `/mcp` (tool servers), `/intelligence` (observability drop-in), `/lifecycle`, `/agent`, `/profiles`, `/platform`, `/analyst-loop`, `/environment-provider`.
+- [`docs/architecture.md`](./docs/architecture.md), the design, end to end.
+- [`bench/HARNESS.md`](./bench/HARNESS.md), the experiment harness and how to run a benchmark.
 
 **Contributing:** `pnpm i && pnpm test` gets you running; the full local gate is the [`package.json`](./package.json) scripts (`lint`, `typecheck`, `docs:check`).

package/dist/agent.d.ts

@@ -1,7 +1,7 @@
 import * as _tangle_network_agent_eval from '@tangle-network/agent-eval';
 import { TraceAnalystKindSpec, AnalystFinding } from '@tangle-network/agent-eval';
 import { A as ArtifactKind, C as CandidateGenerator, P as PromotionGate } from './generator-YkAQrOoD.js';
-import { a as RuntimeStreamEvent, S as SandboxClient, b as OutputAdapter, A as AgentRunSpec } from './types-ESeMOj94.js';
+import { a as RuntimeStreamEvent, S as SandboxClient, b as OutputAdapter, A as AgentRunSpec } from './types-Dnk189QA.js';
 import { A as AgentSurfaces } from './improvement-adapter-CDR8QNVM.js';
 export { C as CreateSurfaceImprovementAdapterOpts, D as DraftPatchInput, a as DraftPatchOutput, R as ResolvedSurface, S as SurfaceImprovementEdit, b as SurfaceValidationIssue, c as createSurfaceImprovementAdapter, r as renderSurfaceIssues, d as resolveSubjectPath, v as validateSurfaces } from './improvement-adapter-CDR8QNVM.js';
 import { K as KnowledgeAdapter, a as RunAnalystLoopResult } from './types-BC3bZpH0.js';
@@ -415,6 +415,55 @@ declare function measureOutcome<TProposal, TEdit>(result: RunAnalystLoopResult<T
     outcome: OutcomeMeasurement;
 }>;
 
+/** Known AgentProfile axes a run path may or may not carry into execution. */
+declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["identity", "name", "model", "prompt", "systemPrompt", "instructions", "resources", "files", "resourceInstructions", "skills", "resourceTools", "resourceAgents", "commands", "tools", "permissions", "mcp", "mcpConnections", "connections", "subagents", "hooks", "modes", "confidential", "metadata", "extensions"];
+type KnownAgentProfileMaterializationAxis = (typeof AGENT_PROFILE_MATERIALIZATION_AXES)[number];
+/** AgentProfile axis name, with `custom:<name>` reserved for caller-owned extensions. */
+type AgentProfileMaterializationAxis = KnownAgentProfileMaterializationAxis | `custom:${string}`;
+/** Declares which AgentProfile axes a concrete run path really carries. */
+interface ProfileMaterializationContract {
+    /** Human-readable run path, e.g. `createSandboxAct` or `prompt-only-message`. */
+    name: string;
+    /** Profile axes this run path actually carries into execution. */
+    axes: readonly AgentProfileMaterializationAxis[];
+}
+/** One changed AgentProfile axis that would be dropped by a run path. */
+interface ProfileMaterializationIssue {
+    contract: string;
+    axis: AgentProfileMaterializationAxis;
+    reason: 'unsupported-axis';
+    supportedAxes: readonly AgentProfileMaterializationAxis[];
+}
+/** Input for declaring a run path's profile-axis support. */
+interface DefineProfileMaterializationContractOptions {
+    name: string;
+    axes: readonly AgentProfileMaterializationAxis[];
+}
+/** Input for checking a candidate diff against a run path. */
+interface ValidateProfileMaterializationOptions {
+    contract: ProfileMaterializationContract;
+    changedAxes: readonly AgentProfileMaterializationAxis[];
+}
+/** Input for throwing on dropped profile axes. */
+interface AssertProfileMaterializationOptions extends ValidateProfileMaterializationOptions {
+    /** Extra label included in the thrown error, usually the caller or run id. */
+    context?: string;
+}
+/** Materialization contract for `createSandboxAct`, which forwards the full AgentProfile. */
+declare const sandboxActProfileMaterialization: ProfileMaterializationContract;
+/** Materialization contract for a run path that only injects prompt text. */
+declare const promptOnlyProfileMaterialization: ProfileMaterializationContract;
+/** Materialization contract for a run path that injects prompt text plus inline resources. */
+declare const promptResourceProfileMaterialization: ProfileMaterializationContract;
+/** Define the profile axes a concrete run path actually carries into execution. */
+declare function defineProfileMaterializationContract(options: DefineProfileMaterializationContractOptions): ProfileMaterializationContract;
+/** Return every changed profile axis that the selected run path would drop. */
+declare function validateProfileMaterialization(options: ValidateProfileMaterializationOptions): readonly ProfileMaterializationIssue[];
+/** Throw when a candidate changes axes the selected run path cannot carry. */
+declare function assertProfileMaterialization(options: AssertProfileMaterializationOptions): void;
+/** Format profile-axis drop issues into a concise operator-facing error. */
+declare function renderProfileMaterializationIssues(issues: readonly ProfileMaterializationIssue[], context?: string): string;
+
 /**
  * Sandbox bridge for `AgentRuntime.act` — prod-faithful eval execution.
  *
@@ -464,6 +513,8 @@ interface CreateSandboxActOptions<TPersona, TRunOutput> {
     compose?: (persona: TPersona) => SandboxActComposeOverrides;
     /** Sandbox-SDK overrides forwarded to `createSandboxForSpec`. */
     sandboxOverrides?: AgentRunSpec<unknown>['sandboxOverrides'];
+    /** Optional changed axes the caller expects this path to carry. */
+    requiredProfileAxes?: readonly AgentProfileMaterializationAxis[];
     /** Stable run name surfaced in mapped `llm_call` events. */
     name?: string;
     /** Override the `SandboxEvent → RuntimeStreamEvent` mapper. */
@@ -479,4 +530,4 @@ interface CreateSandboxActOptions<TPersona, TRunOutput> {
  */
 declare function createSandboxAct<TPersona, TRunOutput>(options: CreateSandboxActOptions<TPersona, TRunOutput>): (persona: TPersona, ctx: AgentRunContext) => AgentRunInvocation<TRunOutput>;
 
-export { type AgentManifest, AgentManifestError, type AgentRubric, type AgentRunContext, type AgentRunInvocation, type AgentRuntime, AgentSurfaces, type AnalystConfig, type AutoApplyPolicy, type CreateSandboxActOptions, type CreateSurfaceKnowledgeAdapterOpts, type JudgeConfig, type KnowledgeAdapterDeps, type OutcomeMeasurement, type OutcomeMeasurementOpts, type RubricDimension, type SurfaceLifecycle, collectAgentRun, createSandboxAct, createSurfaceKnowledgeAdapter, defineAgent, measureOutcome, unimplementedAgentRun };
+export { AGENT_PROFILE_MATERIALIZATION_AXES, type AgentManifest, AgentManifestError, type AgentProfileMaterializationAxis, type AgentRubric, type AgentRunContext, type AgentRunInvocation, type AgentRuntime, AgentSurfaces, type AnalystConfig, type AssertProfileMaterializationOptions, type AutoApplyPolicy, type CreateSandboxActOptions, type CreateSurfaceKnowledgeAdapterOpts, type DefineProfileMaterializationContractOptions, type JudgeConfig, type KnowledgeAdapterDeps, type KnownAgentProfileMaterializationAxis, type OutcomeMeasurement, type OutcomeMeasurementOpts, type ProfileMaterializationContract, type ProfileMaterializationIssue, type RubricDimension, type SurfaceLifecycle, type ValidateProfileMaterializationOptions, assertProfileMaterialization, collectAgentRun, createSandboxAct, createSurfaceKnowledgeAdapter, defineAgent, defineProfileMaterializationContract, measureOutcome, promptOnlyProfileMaterialization, promptResourceProfileMaterialization, renderProfileMaterializationIssues, sandboxActProfileMaterialization, unimplementedAgentRun, validateProfileMaterialization };

package/dist/agent.js

@@ -1,15 +1,17 @@
-import "./chunk-PIPPLSOF.js";
+import "./chunk-4IBAMGBE.js";
 import {
   createSandboxForSpec
-} from "./chunk-N7EJV7N3.js";
+} from "./chunk-QSNSMJSZ.js";
+import "./chunk-DPEUKJRO.js";
 import "./chunk-UD4BHQMI.js";
 import "./chunk-BZF3KQ6G.js";
 import {
   mapSandboxEvent
 } from "./chunk-FVJ7M3DA.js";
 import "./chunk-7LO5GMAO.js";
-import "./chunk-YEJR7IXO.js";
-import "./chunk-DPEUKJRO.js";
+import {
+  ValidationError
+} from "./chunk-YEJR7IXO.js";
 import {
   __require
 } from "./chunk-DGUM43GV.js";
@@ -504,8 +506,160 @@ function meanComposite(rows) {
   return rows.reduce((acc, r) => acc + r.composite, 0) / rows.length;
 }
 
+// src/agent/profile-materialization.ts
+var AGENT_PROFILE_MATERIALIZATION_AXES = [
+  "identity",
+  "name",
+  "model",
+  "prompt",
+  "systemPrompt",
+  "instructions",
+  "resources",
+  "files",
+  "resourceInstructions",
+  "skills",
+  "resourceTools",
+  "resourceAgents",
+  "commands",
+  "tools",
+  "permissions",
+  "mcp",
+  "mcpConnections",
+  "connections",
+  "subagents",
+  "hooks",
+  "modes",
+  "confidential",
+  "metadata",
+  "extensions"
+];
+var KNOWN_AXIS_SET = new Set(AGENT_PROFILE_MATERIALIZATION_AXES);
+var AXIS_PARENTS = {
+  name: "identity",
+  systemPrompt: "prompt",
+  instructions: "prompt",
+  files: "resources",
+  resourceInstructions: "resources",
+  skills: "resources",
+  resourceTools: "resources",
+  resourceAgents: "resources",
+  commands: "resources",
+  mcpConnections: "mcp"
+};
+var sandboxActProfileMaterialization = defineProfileMaterializationContract({
+  name: "createSandboxAct",
+  axes: [
+    "identity",
+    "model",
+    "prompt",
+    "resources",
+    "tools",
+    "permissions",
+    "mcp",
+    "connections",
+    "subagents",
+    "hooks",
+    "modes",
+    "confidential",
+    "metadata",
+    "extensions"
+  ]
+});
+var promptOnlyProfileMaterialization = defineProfileMaterializationContract({
+  name: "prompt-only-message",
+  axes: ["prompt"]
+});
+var promptResourceProfileMaterialization = defineProfileMaterializationContract({
+  name: "prompt-resource-attachment",
+  axes: ["prompt", "resources"]
+});
+function defineProfileMaterializationContract(options) {
+  const name = options.name.trim();
+  if (!name) {
+    throw new ValidationError("defineProfileMaterializationContract: name is required");
+  }
+  return {
+    name,
+    axes: normalizeAxes(options.axes, `${name}.axes`)
+  };
+}
+function validateProfileMaterialization(options) {
+  const changedAxes = normalizeAxes(options.changedAxes, "changedAxes");
+  const supported = new Set(
+    normalizeAxes(options.contract.axes, `${options.contract.name}.axes`)
+  );
+  const issues = [];
+  for (const axis of changedAxes) {
+    if (isAxisSupported(axis, supported)) continue;
+    issues.push({
+      contract: options.contract.name,
+      axis,
+      reason: "unsupported-axis",
+      supportedAxes: [...supported]
+    });
+  }
+  return issues;
+}
+function assertProfileMaterialization(options) {
+  const issues = validateProfileMaterialization(options);
+  if (issues.length === 0) return;
+  throw new ValidationError(renderProfileMaterializationIssues(issues, options.context));
+}
+function renderProfileMaterializationIssues(issues, context) {
+  if (issues.length === 0) return "";
+  const contract = issues[0]?.contract ?? "<unknown>";
+  const prefix = context ? `${context}: ` : "";
+  const droppedAxes = issues.map((issue) => issue.axis).join(", ");
+  const supportedAxes = issues[0]?.supportedAxes.join(", ") || "<none>";
+  return [
+    `${prefix}profile materialization would drop axis changes on "${contract}": ${droppedAxes}.`,
+    `Supported axes: ${supportedAxes}.`,
+    "Use a run path that carries those AgentProfile axes, or remove them from the candidate."
+  ].join("\n");
+}
+function normalizeAxes(axes, label) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of axes) {
+    const axis = normalizeAxis(raw, label);
+    if (seen.has(axis)) continue;
+    seen.add(axis);
+    out.push(axis);
+  }
+  return out;
+}
+function normalizeAxis(raw, label) {
+  if (typeof raw !== "string") {
+    throw new ValidationError(`${label}: profile axis must be a string`);
+  }
+  const axis = raw.trim();
+  if (!axis) {
+    throw new ValidationError(`${label}: profile axis must be non-empty`);
+  }
+  if (!KNOWN_AXIS_SET.has(axis) && !axis.startsWith("custom:")) {
+    throw new ValidationError(
+      `${label}: unknown profile axis "${axis}". Use a known axis or custom:<name>.`
+    );
+  }
+  return axis;
+}
+function isAxisSupported(axis, supported) {
+  if (supported.has(axis)) return true;
+  let parent = AXIS_PARENTS[axis];
+  while (parent) {
+    if (supported.has(parent)) return true;
+    parent = AXIS_PARENTS[parent];
+  }
+  return false;
+}
+
 // src/agent/sandbox-act.ts
 function createSandboxAct(options) {
+  assertProfileMaterialization({
+    contract: sandboxActProfileMaterialization,
+    changedAxes: options.requiredProfileAxes ?? [],
+    context: "createSandboxAct"
+  });
   const mapEvent = options.mapEvent ?? mapSandboxEvent;
   return (persona, ctx) => {
     const profile = applyComposeOverrides(options.baseProfile, options.compose?.(persona));
@@ -561,16 +715,24 @@ function applyComposeOverrides(base, overrides) {
   };
 }
 export {
+  AGENT_PROFILE_MATERIALIZATION_AXES,
   AgentManifestError,
+  assertProfileMaterialization,
   collectAgentRun,
   createSandboxAct,
   createSurfaceImprovementAdapter,
   createSurfaceKnowledgeAdapter,
   defineAgent,
+  defineProfileMaterializationContract,
   measureOutcome,
+  promptOnlyProfileMaterialization,
+  promptResourceProfileMaterialization,
+  renderProfileMaterializationIssues,
   renderSurfaceIssues,
   resolveSubjectPath,
+  sandboxActProfileMaterialization,
   unimplementedAgentRun,
+  validateProfileMaterialization,
   validateSurfaces
 };
 //# sourceMappingURL=agent.js.map