@tangle-network/agent-runtime 0.104.0 → 0.105.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +176 -42
  2. package/dist/agent.js +4 -4
  3. package/dist/candidate-execution/index.d.ts +2 -2
  4. package/dist/candidate-execution/index.js +4 -4
  5. package/dist/{chunk-2QJSNOGK.js → chunk-C5RTIBNZ.js} +2 -2
  6. package/dist/{chunk-SNSMRT6H.js → chunk-CTRA64LY.js} +3 -3
  7. package/dist/{chunk-ZXICDSAK.js → chunk-H5QPIZNX.js} +2 -2
  8. package/dist/{chunk-2X65HYMI.js → chunk-HLKC4UYB.js} +1 -13
  9. package/dist/chunk-HLKC4UYB.js.map +1 -0
  10. package/dist/{chunk-3PPVCS75.js → chunk-HNP72PNU.js} +3 -10
  11. package/dist/chunk-HNP72PNU.js.map +1 -0
  12. package/dist/chunk-OPVWXJ2H.js +75 -0
  13. package/dist/chunk-OPVWXJ2H.js.map +1 -0
  14. package/dist/{chunk-B7K7V22Y.js → chunk-RDOAVVHY.js} +2 -2
  15. package/dist/{chunk-L5DST3QC.js → chunk-SMQXZGLZ.js} +1 -1
  16. package/dist/chunk-SMQXZGLZ.js.map +1 -0
  17. package/dist/{chunk-FJI3EXU3.js → chunk-UHEZW5BU.js} +1104 -588
  18. package/dist/chunk-UHEZW5BU.js.map +1 -0
  19. package/dist/{chunk-HAO4CXHP.js → chunk-VISA6CI3.js} +3 -3
  20. package/dist/{chunk-2UABGGUB.js → chunk-WMTCUOQL.js} +5 -5
  21. package/dist/{chunk-ATDFUJYI.js → chunk-WRTOVNN4.js} +4 -4
  22. package/dist/{chunk-ATDFUJYI.js.map → chunk-WRTOVNN4.js.map} +1 -1
  23. package/dist/{chunk-SBTWKPVR.js → chunk-WSTRQZYQ.js} +1 -1
  24. package/dist/chunk-WSTRQZYQ.js.map +1 -0
  25. package/dist/{chunk-5HNDYWUT.js → chunk-XBG2W2VW.js} +13 -3
  26. package/dist/chunk-XBG2W2VW.js.map +1 -0
  27. package/dist/{chunk-STJEHM5F.js → chunk-YJZA2BIK.js} +2 -2
  28. package/dist/{chunk-STJEHM5F.js.map → chunk-YJZA2BIK.js.map} +1 -1
  29. package/dist/{completion-gate-Bv47cOnn.d.ts → completion-gate-BMy5LGoP.d.ts} +1 -1
  30. package/dist/{coordination-CxtzMxSM.d.ts → coordination-BZZSVYpZ.d.ts} +2 -2
  31. package/dist/index.d.ts +101 -177
  32. package/dist/index.js +373 -235
  33. package/dist/index.js.map +1 -1
  34. package/dist/intelligence.d.ts +49 -40
  35. package/dist/intelligence.js +14 -57
  36. package/dist/intelligence.js.map +1 -1
  37. package/dist/knowledge.d.ts +4 -4
  38. package/dist/knowledge.js +8 -8
  39. package/dist/{local-harness-CtK9dSny.d.ts → local-harness-BDNcl6jI.d.ts} +1 -1
  40. package/dist/{loop-runner-bin-DUOGtvOl.d.ts → loop-runner-bin-68aoM9-7.d.ts} +3 -11
  41. package/dist/loop-runner-bin.d.ts +4 -6
  42. package/dist/loop-runner-bin.js +5 -5
  43. package/dist/loops.d.ts +11 -11
  44. package/dist/loops.js +5 -5
  45. package/dist/mcp/bin.js +2 -2
  46. package/dist/mcp/index.d.ts +7 -8
  47. package/dist/mcp/index.js +6 -6
  48. package/dist/mcp/memory-bin.js +1 -1
  49. package/dist/primeintellect/index.d.ts +2 -3
  50. package/dist/primeintellect/index.js +5 -6
  51. package/dist/primeintellect/index.js.map +1 -1
  52. package/dist/{protected-model-port-DzkUY3HQ.d.ts → protected-model-port-B4t-OQjL.d.ts} +1 -1
  53. package/dist/{improve--2A0gK1-.d.ts → redact-BuFjxBUJ.d.ts} +201 -160
  54. package/dist/{structural-rollout-C4mabf87.d.ts → structural-rollout-DEh6CEsa.d.ts} +2 -2
  55. package/dist/{supervise-7q9F5brx.d.ts → supervise-4_48wwvy.d.ts} +2 -2
  56. package/dist/testing.js +9 -9
  57. package/dist/testing.js.map +1 -1
  58. package/dist/{worktree-fanout-WsOzt8qu.d.ts → worktree-fanout-DxhAWr5Z.d.ts} +2 -2
  59. package/package.json +6 -5
  60. package/skills/build-with-agent-runtime/SKILL.md +15 -9
  61. package/skills/loop-writer/SKILL.md +1 -1
  62. package/dist/chunk-2X65HYMI.js.map +0 -1
  63. package/dist/chunk-3PPVCS75.js.map +0 -1
  64. package/dist/chunk-5HNDYWUT.js.map +0 -1
  65. package/dist/chunk-FJI3EXU3.js.map +0 -1
  66. package/dist/chunk-L5DST3QC.js.map +0 -1
  67. package/dist/chunk-SBTWKPVR.js.map +0 -1
  68. /package/dist/{chunk-2QJSNOGK.js.map → chunk-C5RTIBNZ.js.map} +0 -0
  69. /package/dist/{chunk-SNSMRT6H.js.map → chunk-CTRA64LY.js.map} +0 -0
  70. /package/dist/{chunk-ZXICDSAK.js.map → chunk-H5QPIZNX.js.map} +0 -0
  71. /package/dist/{chunk-B7K7V22Y.js.map → chunk-RDOAVVHY.js.map} +0 -0
  72. /package/dist/{chunk-HAO4CXHP.js.map → chunk-VISA6CI3.js.map} +0 -0
  73. /package/dist/{chunk-2UABGGUB.js.map → chunk-WMTCUOQL.js.map} +0 -0
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # @tangle-network/agent-runtime
2
2
 
3
- A TypeScript runtime for running AI agents — as a **chat turn**, a **one-shot task**, or a **team of agents** working toward a goal — that records every run and uses those records to **measure and improve** agents against real pass/fail checks. It is the engine Tangle's own production agents run on.
3
+ A TypeScript runtime for chat agents, one-shot tasks, and agent teams.
4
+ It records each run so you can measure changes against real pass/fail checks and improve the agent without changing your product integration.
4
5
 
5
6
  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).
6
7
 
@@ -24,12 +25,15 @@ pnpm add @tangle-network/agent-runtime @tangle-network/agent-eval @tangle-networ
24
25
 
25
26
  ## Quickstart (offline, no API keys)
26
27
 
27
- The core move everything else builds on: a driver runs a worker, reads the worker's real output, and writes the next prompt from it until a check passes. This is the full working loop from [`examples/quickstart/quickstart.ts`](./examples/quickstart/quickstart.ts) (the worker is a scripted stand-in so it runs with zero credentials; swap it for a real sandbox, CLI-harness, or router backend without changing the driver):
28
+ A driver runs a worker, reads its output, and writes the next prompt until a check passes.
29
+ This excerpt shows the driver from the runnable [`examples/quickstart/quickstart.ts`](./examples/quickstart/quickstart.ts).
30
+ That file defines the scripted `worker`, `output`, and `validator` used below so it runs without credentials.
31
+ Replace the scripted worker with a sandbox, CLI bridge, or router backend without changing the driver.
28
32
 
29
33
  ```ts
30
- import { inProcessSandboxClient, runLoop } from '@tangle-network/agent-runtime/loops'
34
+ import { inProcessSandboxClient, runAgentRounds } from '@tangle-network/agent-runtime/loops'
31
35
 
32
- const result = await runLoop<Task, Note, 'refine' | 'pick-winner' | 'fail'>({
36
+ const result = await runAgentRounds<Task, Note, 'refine' | 'pick-winner' | 'fail'>({
33
37
  task: { prompt: 'Write a one-line release note for one-click restore.' },
34
38
  driver: {
35
39
  name: 'refine',
@@ -56,12 +60,12 @@ Run it from a clone of this repo and you get exactly this:
56
60
  ```bash
57
61
  $ pnpm i && pnpm build
58
62
  $ pnpm tsx examples/quickstart/quickstart.ts
59
- shot 0: reject "Shipped one-click restore."
60
- shot 1: PASS "Shipped one-click restore with an instant rollback path."
61
- decision: pick-winner winner: shot 1
63
+ shot 0: reject: "Shipped one-click restore."
64
+ shot 1: PASS: "Shipped one-click restore with an instant rollback path."
65
+ decision: pick-winner: winner: shot 1
62
66
  ```
63
67
 
64
- The fully annotated version of this loop, with every seam explained, is [`examples/driver-loop`](./examples/driver-loop).
68
+ The annotated version is [`examples/driver-loop`](./examples/driver-loop).
65
69
 
66
70
  ## What you do with it
67
71
 
@@ -69,7 +73,7 @@ The fully annotated version of this loop, with every seam explained, is [`exampl
69
73
  |---|---|
70
74
  | Run a **chat turn** for a production product agent | `handleChatTurn(...)` |
71
75
  | Have one agent **supervise a team of agents** toward a goal | `supervise(profile, task, opts)` |
72
- | **Improve** an agent and prove the gain on fresh tasks | `improve(profile, findings, opts)` |
76
+ | **Improve** an agent and prove the gain on fresh tasks | `improve(profile, opts)` |
73
77
  | Produce a measured knowledge-base candidate with agents and checks | `runKnowledgeImprovementJob(...)` |
74
78
  | Evaluate or train the same agent on **PrimeIntellect** | `createPrimeIntellectPackage(...)` |
75
79
 
@@ -107,38 +111,150 @@ const result = await supervise(
107
111
 
108
112
  ### Improve an agent
109
113
 
110
- `improve` optimizes one part of an agent and returns a detached winner plus a decision. The decision is `ship` only when the candidate beats the current agent on tasks it never practiced on.
111
- It accepts prompt, skill document, curated memory, tool, MCP, hook, subagent, whole-profile, and code surfaces through one call.
112
- Prompt, skill-document, and memory optimization have built-in generators; structured profile surfaces take an explicit generator, and code runs from isolated incumbent and candidate checkouts.
113
- Workflow and rollout-policy files use the code surface so the measured winner is an exact patch that can be sealed and executed; JSON parameter sweeps use agent-eval's `parameterSweepProposer` instead of a runtime-specific optimizer.
114
+ `improve` runs one complete `OptimizationMethod` against one profile field.
115
+ The method owns candidate generation and selection.
116
+ Runtime keeps the final test set out of the method, scores the baseline and selected candidate on it, and returns `ship` only when the paired confidence interval clears `minimumLift`.
117
+ The profile is never changed.
114
118
 
115
119
  ```ts
116
- import { improve } from '@tangle-network/agent-runtime'
120
+ import { improve, officialGepa } from '@tangle-network/agent-runtime'
121
+ import { canonicalCandidateDigest } from '@tangle-network/agent-interface'
117
122
 
118
- const { candidate, decision, lift } = await improve(baseProfile, findings, {
123
+ const executionRef = canonicalCandidateDigest({
124
+ deployment: process.env.AGENT_DEPLOYMENT_SHA!,
125
+ model: process.env.AGENT_MODEL!,
126
+ tools: process.env.AGENT_TOOLSET_SHA!,
127
+ })
128
+
129
+ const optimizer = {
130
+ model: process.env.OPTIMIZER_MODEL!,
131
+ baseUrl: process.env.OPTIMIZER_BASE_URL!,
132
+ apiKey: process.env.OPTIMIZER_API_KEY!,
133
+ budget: {
134
+ maxCostUsd: 10,
135
+ maxRequests: 50,
136
+ maxRequestBytes: 2_000_000,
137
+ maxResponseBytes: 2_000_000,
138
+ maxOutputTokensPerRequest: 16_384,
139
+ pricing: {
140
+ inputUsdPerMillion: Number(process.env.OPTIMIZER_INPUT_USD_PER_MILLION),
141
+ outputUsdPerMillion: Number(process.env.OPTIMIZER_OUTPUT_USD_PER_MILLION),
142
+ },
143
+ },
144
+ }
145
+
146
+ const result = await improve(baseProfile, {
119
147
  surface: 'prompt',
120
- gate: 'holdout',
121
- scenarios,
122
- judge,
123
- agent,
148
+ executionRef,
149
+ method: officialGepa({
150
+ objective: 'Improve the complete support-agent prompt.',
151
+ recipe: {
152
+ kind: 'engine',
153
+ run: {
154
+ engine: 'gepa',
155
+ maxEvaluations: 40,
156
+ maxProposerCostUsd: 10,
157
+ },
158
+ },
159
+ optimizer,
160
+ resume: 'if-compatible',
161
+ trustResumeState: true,
162
+ describeScenario: ({ input }) => ({ input }),
163
+ }),
164
+ findings,
165
+ trainScenarios,
166
+ selectionScenarios,
167
+ testScenarios,
168
+ judges: [judge],
169
+ agent: (candidateProfile, scenario, ctx) =>
170
+ runProfile(candidateProfile, scenario, ctx),
171
+ runDir: '.runs/support-prompt',
172
+ costCeiling: 25,
124
173
  })
125
174
 
126
- if (decision === 'ship') console.log({ candidate, lift })
175
+ if (result.decision === 'ship') {
176
+ console.log(result.candidate.profile, result.liftInterval)
177
+ }
178
+ ```
179
+
180
+ `officialGepa(...)` delegates the complete search to GEPA's upstream Optimize Anything API through agent-eval.
181
+ Pass one explicit `engine`, `sequential`, `adaptive-sequential`, `best-of`, `vote`, or `omni` recipe.
182
+ Runtime derives the upstream resume identity from `executionRef`, the complete baseline profile, and the selected surface.
183
+ With `resume: 'if-compatible'`, agent-eval resumes only when the saved run identity matches the candidate, recipe, data, optimizer settings, runner, and derived execution identity.
184
+ Set `trustResumeState: true` only when that run directory is private to the current operator.
185
+ Use `resume: 'required'` to fail when no matching run exists.
186
+ `result.provenance` reports the upstream package, run ID, resume status, evaluation count, and artifact directory.
187
+ There is no local fallback.
188
+ Install its optional Python process before using it:
189
+
190
+ ```bash
191
+ python -m pip install "agent-eval-rpc==0.126.6"
192
+ python -m pip install "gepa[full]==0.1.4"
193
+ ```
194
+
195
+ The published GEPA 0.1.4 wheel supports the direct `gepa` engine.
196
+ Sequential, adaptive, best-of, vote, Omni, AutoResearch, Meta Harness, and Best-of-N require the tested official source revision:
197
+
198
+ ```bash
199
+ python -m pip install "gepa[full] @ git+https://github.com/gepa-ai/gepa.git@f919db0a622e2e9f9204779b81fe00cc1b2d808f"
127
200
  ```
128
201
 
129
- When the host runs complete profiles rather than mutable fields, use `profileDispatch(profile, scenario, ctx)` in place of `agent`.
130
- It is agent-eval's `ProfileDispatchFn`: Runtime gives it a frozen baseline or candidate profile and the same cost, trace, and cancellation context used for every measured cell.
131
- `profileDispatch` is unavailable for `surface: 'code'`, because code candidates require isolated worktrees.
202
+ Use `officialSkillOpt(...)` for Microsoft's SkillOpt:
203
+
204
+ ```bash
205
+ python -m pip install "agent-eval-rpc==0.126.6"
206
+ python -m pip install "skillopt @ git+https://github.com/microsoft/SkillOpt.git@61735e3922efc2b90c6d6cab561e62e98452ca90"
207
+ ```
132
208
 
133
- Skill and curated-memory candidates are exact profile changes, not free-floating text.
134
- Name one inline skill through `skills.resourceName`; curated memory uses `profile.resources.instructions`.
135
- Both require `profile.resources.failOnError: true` so an unsupported resource cannot silently disappear.
209
+ SkillOpt 0.2.0's published wheel omits prompt files required by `ReflACTTrainer`, so the tested SkillOpt source revision remains necessary.
210
+ SkillOpt and GEPA's standard reflection engine require `optimizer: { model, baseUrl, apiKey, budget }`.
211
+ Agent-based GEPA engines may own their model connection instead.
212
+ Agent Eval proxies those model calls, enforces the nested budget, and records their cost.
213
+ `costCeiling` is the total limit for optimizer calls, candidate runs, judges, and final scoring.
214
+ Runtime returns `hold` when any part of that cost is unknown.
215
+ Runtime rejects a reported total above the limit.
216
+
217
+ SkillOpt accepts one text surface.
218
+ GEPA accepts text or named components.
219
+ Any complete method from `@tangle-network/agent-eval` uses the same call.
220
+ The `agent` callback receives the complete immutable candidate profile, not a raw prompt or component fragment.
221
+ Runtime uses that exact profile for every candidate run and returns the same measured profile in `result.candidate.profile`.
222
+ `executionRef` is a content digest of the agent callback, profile component mapping, model, tools, and closure settings.
223
+ Runtime combines it with the complete baseline profile and selected surface for saved work.
224
+ Changing any of them runs the affected work again.
225
+ For a skill, set `surface: 'skills'` and `skills.resourceName`.
226
+ For the complete profile, set `surface: 'agent-profile'`.
227
+ To optimize several named profile fields together, also provide `profileComponents.read` and `profileComponents.apply`.
228
+ Tools, MCP, hooks, subagents, curated instructions, and rollout policy are also exact profile coordinates.
229
+ Runtime does not choose an optimizer for them.
230
+
231
+ Without `describeScenario`, the external optimizer receives only each development case ID.
232
+ Without `describeArtifact`, evaluation feedback contains no artifact body.
233
+ When either descriptor is present, its result passes through `redact` together with findings, background text, profile name, and judge notes.
234
+ The built-in redactor removes common credentials and email addresses.
235
+ Supply a domain redactor for customer names, account IDs, or other private data the built-in rules cannot identify.
236
+ Runtime applies that hook first and then still applies its built-in scrubber.
237
+ Set `redact: false` only when every outbound value is public and already reviewed.
238
+
239
+ The selected profile surface is the optimizer's candidate and cannot be redacted without changing the measured candidate.
240
+ Runtime always rejects recognized credentials in those bytes.
241
+ It also rejects structurally sensitive fields such as MCP env, headers, URLs, metadata, and extensions.
242
+ For `tools`, `mcp`, `hooks`, `subagents`, and `agent-profile`, Runtime treats the entire selected coordinate as execution-capable.
243
+ Use `authorizeSensitiveCandidate` to inspect and accept each exact immutable profile containing public values or safe references.
244
+ The callback runs for the baseline and every distinct candidate before either reaches your agent.
245
+ Its `sensitivePaths` includes `$` when the whole coordinate requires review.
246
+
247
+ Code is the exception.
248
+ It uses Runtime's isolated git worktrees and coding-agent candidate execution:
136
249
 
137
250
  ```ts
138
- const skillResult = await improve(baseProfile, findings, {
139
- surface: 'skills',
140
- skills: { resourceName: 'incident-response' },
141
- scenarios, judge, agent,
251
+ const result = await improve({
252
+ surface: 'code',
253
+ code: { repoRoot, baseRef, generator },
254
+ scenarios,
255
+ judge,
256
+ agent,
257
+ budget,
142
258
  })
143
259
  ```
144
260
 
@@ -159,7 +275,16 @@ const result = await proposeAgentImprovement({
159
275
  runId,
160
276
  profile: liveProfile,
161
277
  analysis,
162
- improvement: { surface: 'prompt', scenarios, judge, agent },
278
+ improvement: {
279
+ surface: 'prompt',
280
+ executionRef,
281
+ method,
282
+ trainScenarios,
283
+ selectionScenarios,
284
+ testScenarios,
285
+ judges: [judge],
286
+ agent,
287
+ },
163
288
  buildExperiment: ({ improvement }) =>
164
289
  buildExperimentMaterial({
165
290
  baseline,
@@ -191,10 +316,16 @@ const outcome = await executeAgentImprovementActivation(
191
316
  `buildExperimentMaterial`, `placeCell`, and the transaction functions are application ports because storage and compute differ by product.
192
317
  The builder returns only baseline, candidate, tasks, and policy; Runtime adds the search ancestry and seals the final experiment.
193
318
  Runtime owns candidate identity, measurement, review binding, expiry, retry identity, and result validation; the application owns its atomic write.
319
+ Official optimizer proposals carry the observed package versions, optimizer model, evaluation and token usage, separate optimization and final-test costs, and resumed-run identity.
320
+ `createOptimizationActivationReceipt(result)` exposes the same detached record for callers that need to inspect an `improve()` result before building a proposal.
194
321
 
195
322
  ### Improve a knowledge base
196
323
 
197
- `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`, and returns frozen baseline and candidate snapshots with spend and timing. It never changes the live knowledge base. Use `improve(..., { surface: 'memory' })` for the agent's curated lesson document; use this job for source, retrieval, and knowledge-store changes.
324
+ `runKnowledgeImprovementJob` runs KB, wiki, memory-backed, and RAG improvement jobs.
325
+ It creates a candidate copy, runs agents against it, checks it through `@tangle-network/agent-knowledge`, and returns frozen baseline and candidate snapshots with spend and timing.
326
+ It never changes the live knowledge base.
327
+ Use `improve(profile, { surface: 'memory', ... })` for the agent's curated lesson document.
328
+ Use this job for source, retrieval, and knowledge-store changes.
198
329
 
199
330
  ```ts
200
331
  import { runKnowledgeImprovementJob } from '@tangle-network/agent-runtime/knowledge'
@@ -202,6 +333,7 @@ import { runKnowledgeImprovementJob } from '@tangle-network/agent-runtime/knowle
202
333
  const result = await runKnowledgeImprovementJob({
203
334
  root: './kb',
204
335
  goal: 'Improve support refund-policy knowledge',
336
+ implementationRef: 'git:0123456789abcdef0123456789abcdef01234567',
205
337
  readinessSpecs,
206
338
  budget: { maxIterations: 8, maxTokens: 120_000, maxUsd: 10 },
207
339
  backend,
@@ -211,11 +343,13 @@ console.log(result.knowledge?.reference.candidateHash, result.measurement.superv
211
343
  ```
212
344
 
213
345
  Use it when the product needs one knob for "make this knowledge base better" instead of wiring `improveKnowledgeBase`, a runtime supervisor, candidate workspaces, and readiness checks by hand.
346
+ Set `implementationRef` to the deployed `git:<40 hex>` revision or a `sha256:<64 hex>` digest covering every callback, model, index, and external setting that can change the result.
347
+ The same run ID resumes only when this identity still matches.
214
348
  Measure the returned bundle pair, record the review, then activate through `executeAgentImprovementActivation`; activation is the only write path.
215
349
 
216
350
  ### Run on PrimeIntellect
217
351
 
218
- `@tangle-network/agent-runtime/primeintellect` packages typed train and eval tasks as a Verifiers v1 environment.
352
+ `@tangle-network/agent-runtime/primeintellect` packages typed train and eval tasks as a PrimeIntellect Verifiers environment.
219
353
  Prime launches your actual runtime program against an intercepted model endpoint, so `runPersonified`, `runAgentic`, product agents, tool calls, and multiple rounds stay intact.
220
354
  Reference answers remain in Prime's task process and never enter the agent workspace.
221
355
  The runner file must be one executable bundle containing the app and its runtime dependencies.
@@ -229,7 +363,7 @@ import {
229
363
 
230
364
  const bundledRunner = await readFile('./dist/prime-runner.mjs', 'utf8')
231
365
  const bundle = createPrimeIntellectPackage({
232
- name: 'support-agent-v1',
366
+ name: 'support-agent',
233
367
  version: '1.0.0',
234
368
  tasks: [
235
369
  {
@@ -253,7 +387,7 @@ const bundle = createPrimeIntellectPackage({
253
387
  },
254
388
  })
255
389
 
256
- await writePrimeIntellectPackage(bundle, './prime/support-agent-v1')
390
+ await writePrimeIntellectPackage(bundle, './prime/support-agent')
257
391
  ```
258
392
 
259
393
  The runner reads the episode and uses the normal runtime APIs:
@@ -276,20 +410,20 @@ Use `importPrimeIntellectTraces(...)` to convert them to agent-eval `RunRecord`s
276
410
 
277
411
  ## How it works (the short version)
278
412
 
279
- - **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.
280
- - **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.
281
- - **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.
282
- - **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.
413
+ - **Roles are configuration.** Driver, worker, and coordinator describe what an agent does in a run. They are not separate agent types.
414
+ - **Runs are recorded.** A run can report tokens, dollars, time, outputs, and scores.
415
+ - **Candidates face fresh tasks.** The optimizer uses train and selection tasks. Promotion uses a separate final set.
416
+ - **Scores come from executed attempts.** Runtime recomputes results from the recorded cells and rejects incomplete cost or source evidence.
283
417
 
284
418
  ## Primitives
285
419
 
286
- The general-purpose pieces, by import path. Every export with its one-line summary lives in the generated [`docs/api/primitive-catalog.md`](./docs/api/primitive-catalog.md) check it before building anything new.
420
+ The general-purpose pieces, by import path. Every export with its one-line summary lives in the generated [`docs/api/primitive-catalog.md`](./docs/api/primitive-catalog.md): check it before building anything new.
287
421
 
288
422
  | Primitive | What it does | Import |
289
423
  |---|---|---|
290
424
  | Chat-turn runtime | Stream, trace, and persist one production chat turn (`handleChatTurn`); normalize any backend's stream into one event shape (`streamAgentTurn`) | root · `/loops` |
291
425
  | Supervision | One agent spawns, budgets, and steers workers toward a goal (`supervise`, `delegate`), on an in-process loop or a sandboxed coding harness | `/loops` · `/mcp` |
292
- | Loop kernel + combinators | Write a driver (`plan`/`decide`) and run it (`runLoop`), or compose fixed shapes: refine (`loopUntil`), best-of-N (`fanout`), chain (`pipeline`), multi-judge (`panel`) | `/loops` |
426
+ | Loop kernel + combinators | Write a driver (`plan`/`decide`) and run it (`runAgentRounds`), or compose fixed shapes: refine (`loopUntil`), best-of-N (`fanout`), chain (`pipeline`), multi-judge (`panel`) | `/loops` |
293
427
  | Improvement driver | Optimize one part of an agent and ship only if it wins on tasks it never practiced on (`improve`); production proposal/review/activation flow | root · `/intelligence` |
294
428
  | Benchmarks + leaderboards | Compare strategies with significance stats (`runBenchmark`), stand up a harness×model leaderboard (`defineLeaderboard`, `leaderboard`) | `/loops` |
295
429
  | Knowledge improvement | Produce a measured candidate copy of a KB/wiki/RAG corpus without touching the live one (`runKnowledgeImprovementJob`) | `/knowledge` |
@@ -324,7 +458,7 @@ All 29 live in [`examples/`](./examples).
324
458
  - New here? [`docs/concepts.md`](./docs/concepts.md), the mental model in plain terms.
325
459
  - [`docs/canonical-api.md`](./docs/canonical-api.md), find the primitive: "I want to ___ → use ___".
326
460
  - [`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.
327
- - [`docs/design.md`](./docs/design.md), the design philosophy and the internal research docs behind it background reading, not required to use the package.
461
+ - [`docs/design.md`](./docs/design.md), the design philosophy and the internal research docs behind it: background reading, not required to use the package.
328
462
  - [`bench/HARNESS.md`](./bench/HARNESS.md), the experiment harness and how to run a benchmark.
329
463
 
330
464
  **Contributing:** `pnpm i && pnpm build && pnpm test` gets you running; the full local gate is the [`package.json`](./package.json) scripts (`lint`, `typecheck`, `docs:check`).
package/dist/agent.js CHANGED
@@ -1,13 +1,13 @@
1
- import "./chunk-ATDFUJYI.js";
1
+ import "./chunk-WRTOVNN4.js";
2
2
  import "./chunk-Q2JSAVQ3.js";
3
3
  import {
4
4
  createSandboxForSpec
5
- } from "./chunk-5HNDYWUT.js";
5
+ } from "./chunk-XBG2W2VW.js";
6
6
  import "./chunk-DPEUKJRO.js";
7
- import "./chunk-STJEHM5F.js";
7
+ import "./chunk-YJZA2BIK.js";
8
8
  import "./chunk-UPWGXKXB.js";
9
9
  import "./chunk-2VZYRB55.js";
10
- import "./chunk-2X65HYMI.js";
10
+ import "./chunk-HLKC4UYB.js";
11
11
  import "./chunk-ISPWRSEC.js";
12
12
  import "./chunk-KRBFHMV6.js";
13
13
  import "./chunk-3MDZX7YU.js";
@@ -1,8 +1,8 @@
1
1
  import { CodeSurface } from '@tangle-network/agent-eval/campaign';
2
2
  import { AgentCandidateBundle, AgentCandidateCodeDisabled, AgentCandidateCodeNoOp, AgentCandidateGitHubRepository, AgentProfile, AgentProfileDiff, AgentCandidateProfile, AgentCandidateExecution, AgentCandidateKnowledge, AgentCandidateMemoryPolicy, AgentCandidateArtifactRef, Sha256Digest, AgentCandidateWorkspaceSnapshotEvidence } from '@tangle-network/agent-interface';
3
3
  export { AgentCandidateBenchmarkGraderIdentity } from '@tangle-network/agent-interface';
4
- import { c as AgentCandidateExecutionClaim, A as AgentCandidateExecutionClaimStore, d as AgentCandidateExecutionClaimResult, b as AgentCandidateExecutionAttemptRef, a as AgentCandidateExecutionAttemptRecord, h as AgentCandidateExecutionLease, j as AgentCandidateExecutionPhaseResult, n as AgentCandidateExecutionTerminalResult, l as AgentCandidateExecutionStageResult, g as AgentCandidateExecutionFinishResult, k as AgentCandidateExecutionRecoveryEvidence } from '../protected-model-port-DzkUY3HQ.js';
5
- export { e as AgentCandidateExecutionCleanupHandles, f as AgentCandidateExecutionFailureClass, i as AgentCandidateExecutionPhase, m as AgentCandidateExecutionTerminalRecord, o as AgentCandidateModelGrantActivateInput, q as AgentCandidateModelGrantClient, r as AgentCandidateModelGrantReservation, s as AgentCandidateModelGrantReserveInput, t as AgentCandidateModelGrantSettleInput, u as AgentCandidatePreparationEvidence, v as AgentCandidateRetryRejection, C as CreateProtectedAgentCandidateModelPortOptions, E as ExecutePreparedAgentCandidateOptions, I as InMemoryAgentCandidateExecutionClaimStore, P as PrepareAgentCandidateExecutionOptions, w as applyExactAgentProfileDiff, x as assertCandidateProfileBinding, y as createProtectedAgentCandidateModelPort, z as executePreparedAgentCandidate, B as parseExactAgentProfile, D as parseExactAgentProfileDiff, F as prepareAgentCandidateExecution } from '../protected-model-port-DzkUY3HQ.js';
4
+ import { c as AgentCandidateExecutionClaim, A as AgentCandidateExecutionClaimStore, d as AgentCandidateExecutionClaimResult, b as AgentCandidateExecutionAttemptRef, a as AgentCandidateExecutionAttemptRecord, h as AgentCandidateExecutionLease, j as AgentCandidateExecutionPhaseResult, n as AgentCandidateExecutionTerminalResult, l as AgentCandidateExecutionStageResult, g as AgentCandidateExecutionFinishResult, k as AgentCandidateExecutionRecoveryEvidence } from '../protected-model-port-B4t-OQjL.js';
5
+ export { e as AgentCandidateExecutionCleanupHandles, f as AgentCandidateExecutionFailureClass, i as AgentCandidateExecutionPhase, m as AgentCandidateExecutionTerminalRecord, o as AgentCandidateModelGrantActivateInput, q as AgentCandidateModelGrantClient, r as AgentCandidateModelGrantReservation, s as AgentCandidateModelGrantReserveInput, t as AgentCandidateModelGrantSettleInput, u as AgentCandidatePreparationEvidence, v as AgentCandidateRetryRejection, C as CreateProtectedAgentCandidateModelPortOptions, E as ExecutePreparedAgentCandidateOptions, I as InMemoryAgentCandidateExecutionClaimStore, P as PrepareAgentCandidateExecutionOptions, w as applyExactAgentProfileDiff, x as assertCandidateProfileBinding, y as createProtectedAgentCandidateModelPort, z as executePreparedAgentCandidate, B as parseExactAgentProfile, D as parseExactAgentProfileDiff, F as prepareAgentCandidateExecution } from '../protected-model-port-B4t-OQjL.js';
6
6
  import { P as PreparedAgentCandidateExecution, A as AgentCandidateExecutorPort, b as AgentCandidateOutputArtifactPort, w as AgentCandidateOutputPurpose, e as AgentCandidateExecutionPorts, z as AgentCandidateVerificationPorts, V as VerifiedAgentCandidate, r as AgentCandidateExecutorWorkspaceFile, B as AgentCandidateWorkspacePort } from '../types-Cbp72qyu.js';
7
7
  export { j as AgentCandidateArtifactPort, a as AgentCandidateBenchmarkGraderPort, k as AgentCandidateContainerPort, l as AgentCandidateExecutorFinalCapture, m as AgentCandidateExecutorMemoryCapture, n as AgentCandidateExecutorProfileFile, o as AgentCandidateExecutorRequest, p as AgentCandidateExecutorStopRequest, q as AgentCandidateExecutorTaskOutcomeCapture, s as AgentCandidateExecutorWorkspaceInput, t as AgentCandidateMemoryPort, u as AgentCandidateMemoryResetResult, v as AgentCandidateModelLimits, f as AgentCandidateModelPort, h as AgentCandidateProtectedModelActivation, g as AgentCandidateProtectedModelReservation, i as AgentCandidateProtectedModelSettlement, x as AgentCandidateProtectedRunCapture, y as AgentCandidateRepositoryPort, c as AgentCandidateRunFinalization, d as AgentCandidateTaskExecution, C as CANDIDATE_TRACE_ENV, D as CANDIDATE_TRACE_TAGS, E as CanonicalCandidateDocument, F as PreparedAgentCandidateInstruction, G as PreparedAgentCandidateKnowledge, H as PreparedAgentCandidateLaunch, I as PreparedAgentCandidateTrace, R as ResolvedAgentCandidateContainer, J as VerifiedAgentCandidateTaskOutcome } from '../types-Cbp72qyu.js';
8
8
  import { AgentEnvironmentProvider, AgentExactProcessResources } from '@tangle-network/agent-interface/environment-provider';
@@ -3,17 +3,17 @@ import {
3
3
  buildAgentCandidateBundle,
4
4
  disposePreparedAgentCandidateExecution,
5
5
  recoverExpiredAgentCandidateExecution
6
- } from "../chunk-SNSMRT6H.js";
6
+ } from "../chunk-CTRA64LY.js";
7
7
  import {
8
8
  createProtectedAgentCandidateModelPort,
9
9
  exactProcessProviderAsCandidateExecutor
10
- } from "../chunk-ZXICDSAK.js";
10
+ } from "../chunk-H5QPIZNX.js";
11
11
  import {
12
12
  captureAgentCandidateWorkspace,
13
13
  captureAgentCandidateWorkspaceFiles,
14
14
  createAgentCandidateWorkspacePort,
15
15
  sealAgentCandidateBundle
16
- } from "../chunk-B7K7V22Y.js";
16
+ } from "../chunk-RDOAVVHY.js";
17
17
  import {
18
18
  AGENT_CANDIDATE_EXECUTION_SUPPORT,
19
19
  CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV,
@@ -31,7 +31,7 @@ import {
31
31
  persistCandidateOutputArtifact,
32
32
  prepareAgentCandidateExecution,
33
33
  verifyAgentCandidateBundle
34
- } from "../chunk-SBTWKPVR.js";
34
+ } from "../chunk-WSTRQZYQ.js";
35
35
  import "../chunk-UPWGXKXB.js";
36
36
  import "../chunk-ISPWRSEC.js";
37
37
  import "../chunk-3MDZX7YU.js";
@@ -8,7 +8,7 @@ import {
8
8
  DELEGATION_STATUS_DESCRIPTION,
9
9
  DELEGATION_STATUS_INPUT_SCHEMA,
10
10
  DELEGATION_STATUS_TOOL_NAME
11
- } from "./chunk-5HNDYWUT.js";
11
+ } from "./chunk-XBG2W2VW.js";
12
12
 
13
13
  // src/mcp/openai-tools.ts
14
14
  function buildTool(name, description, parameters) {
@@ -45,4 +45,4 @@ export {
45
45
  mcpToolsForRuntimeMcp,
46
46
  mcpToolsForRuntimeMcpSubset
47
47
  };
48
- //# sourceMappingURL=chunk-2QJSNOGK.js.map
48
+ //# sourceMappingURL=chunk-C5RTIBNZ.js.map
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  sealAgentCandidateBundle
3
- } from "./chunk-B7K7V22Y.js";
3
+ } from "./chunk-RDOAVVHY.js";
4
4
  import {
5
5
  RecoveryAgentCandidateTraceStore,
6
6
  applyExactAgentProfileDiff,
@@ -32,7 +32,7 @@ import {
32
32
  sealTerminalDigest,
33
33
  terminalRecord,
34
34
  withinCandidateCleanupDeadline
35
- } from "./chunk-SBTWKPVR.js";
35
+ } from "./chunk-WSTRQZYQ.js";
36
36
 
37
37
  // src/candidate-execution/builder.ts
38
38
  import { verifyCodeSurface } from "@tangle-network/agent-eval/campaign";
@@ -677,4 +677,4 @@ export {
677
677
  disposePreparedAgentCandidateExecution,
678
678
  recoverExpiredAgentCandidateExecution
679
679
  };
680
- //# sourceMappingURL=chunk-SNSMRT6H.js.map
680
+ //# sourceMappingURL=chunk-CTRA64LY.js.map
@@ -9,7 +9,7 @@ import {
9
9
  sealAgentCandidateModelSettlement,
10
10
  sha256Bytes,
11
11
  usdToNanos
12
- } from "./chunk-SBTWKPVR.js";
12
+ } from "./chunk-WSTRQZYQ.js";
13
13
 
14
14
  // src/candidate-execution/exact-process-executor.ts
15
15
  import { posix } from "path";
@@ -904,4 +904,4 @@ export {
904
904
  exactProcessProviderAsCandidateExecutor,
905
905
  createProtectedAgentCandidateModelPort
906
906
  };
907
- //# sourceMappingURL=chunk-ZXICDSAK.js.map
907
+ //# sourceMappingURL=chunk-H5QPIZNX.js.map
@@ -9,7 +9,6 @@ import {
9
9
  zeroTokenUsage
10
10
  } from "./chunk-3MDZX7YU.js";
11
11
  import {
12
- ConfigError,
13
12
  RuntimeRunStateError,
14
13
  ValidationError
15
14
  } from "./chunk-YEJR7IXO.js";
@@ -1371,16 +1370,6 @@ async function removeWorktree(options) {
1371
1370
  if (branchError) throw branchError;
1372
1371
  }
1373
1372
 
1374
- // src/runtime/supervise/model-policy.ts
1375
- function assertModelAllowed(model, allowed) {
1376
- if (!allowed || model === void 0) return;
1377
- if (!allowed.includes(model)) {
1378
- throw new ConfigError(
1379
- `model ${JSON.stringify(model)} is not in the allowed set ${JSON.stringify([...allowed])}`
1380
- );
1381
- }
1382
- }
1383
-
1384
1373
  // src/runtime/router-client.ts
1385
1374
  import { estimateCost, isModelPriced } from "@tangle-network/agent-eval";
1386
1375
 
@@ -3498,7 +3487,6 @@ export {
3498
3487
  runWorktreeChecks,
3499
3488
  runSettledCommand,
3500
3489
  runBrainLoop,
3501
- assertModelAllowed,
3502
3490
  routerChatWithUsage,
3503
3491
  routerChatWithTools,
3504
3492
  routerToolLoop,
@@ -3523,4 +3511,4 @@ export {
3523
3511
  createBudgetPool,
3524
3512
  createSupervisor
3525
3513
  };
3526
- //# sourceMappingURL=chunk-2X65HYMI.js.map
3514
+ //# sourceMappingURL=chunk-HLKC4UYB.js.map