@providerkit/agents 0.1.0 → 0.2.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 (291) hide show
  1. package/LICENSE-APACHE-2.0 +202 -0
  2. package/README.md +2108 -52
  3. package/THIRD_PARTY_NOTICES.md +521 -0
  4. package/dist/a2a/auth.d.ts +10 -0
  5. package/dist/a2a/auth.d.ts.map +1 -0
  6. package/dist/a2a/auth.js +52 -0
  7. package/dist/a2a/auth.js.map +1 -0
  8. package/dist/a2a/client.d.ts +74 -0
  9. package/dist/a2a/client.d.ts.map +1 -0
  10. package/dist/a2a/client.js +601 -0
  11. package/dist/a2a/client.js.map +1 -0
  12. package/dist/a2a/index.d.ts +22 -0
  13. package/dist/a2a/index.d.ts.map +1 -0
  14. package/dist/a2a/index.js +11 -0
  15. package/dist/a2a/index.js.map +1 -0
  16. package/dist/a2a/memory-runs.d.ts +62 -0
  17. package/dist/a2a/memory-runs.d.ts.map +1 -0
  18. package/dist/a2a/memory-runs.js +349 -0
  19. package/dist/a2a/memory-runs.js.map +1 -0
  20. package/dist/a2a/policy.d.ts +15 -0
  21. package/dist/a2a/policy.d.ts.map +1 -0
  22. package/dist/a2a/policy.js +114 -0
  23. package/dist/a2a/policy.js.map +1 -0
  24. package/dist/a2a/push.d.ts +34 -0
  25. package/dist/a2a/push.d.ts.map +1 -0
  26. package/dist/a2a/push.js +180 -0
  27. package/dist/a2a/push.js.map +1 -0
  28. package/dist/a2a/remote.d.ts +155 -0
  29. package/dist/a2a/remote.d.ts.map +1 -0
  30. package/dist/a2a/remote.js +1196 -0
  31. package/dist/a2a/remote.js.map +1 -0
  32. package/dist/a2a/server.d.ts +110 -0
  33. package/dist/a2a/server.d.ts.map +1 -0
  34. package/dist/a2a/server.js +1139 -0
  35. package/dist/a2a/server.js.map +1 -0
  36. package/dist/a2a/signing.d.ts +21 -0
  37. package/dist/a2a/signing.d.ts.map +1 -0
  38. package/dist/a2a/signing.js +305 -0
  39. package/dist/a2a/signing.js.map +1 -0
  40. package/dist/a2a/tasks.d.ts +88 -0
  41. package/dist/a2a/tasks.d.ts.map +1 -0
  42. package/dist/a2a/tasks.js +170 -0
  43. package/dist/a2a/tasks.js.map +1 -0
  44. package/dist/a2a/wire.d.ts +267 -0
  45. package/dist/a2a/wire.d.ts.map +1 -0
  46. package/dist/a2a/wire.js +1202 -0
  47. package/dist/a2a/wire.js.map +1 -0
  48. package/dist/background-types.d.ts +76 -0
  49. package/dist/background-types.d.ts.map +1 -0
  50. package/dist/background-types.js +2 -0
  51. package/dist/background-types.js.map +1 -0
  52. package/dist/child.d.ts +25 -0
  53. package/dist/child.d.ts.map +1 -0
  54. package/dist/child.js +129 -0
  55. package/dist/child.js.map +1 -0
  56. package/dist/code-driver.d.ts +40 -0
  57. package/dist/code-driver.d.ts.map +1 -0
  58. package/dist/code-driver.js +2 -0
  59. package/dist/code-driver.js.map +1 -0
  60. package/dist/code-mode.d.ts +3 -0
  61. package/dist/code-mode.d.ts.map +1 -0
  62. package/dist/code-mode.js +2 -0
  63. package/dist/code-mode.js.map +1 -0
  64. package/dist/code-script.d.ts +3 -0
  65. package/dist/code-script.d.ts.map +1 -0
  66. package/dist/code-script.js +149 -0
  67. package/dist/code-script.js.map +1 -0
  68. package/dist/code.d.ts +75 -0
  69. package/dist/code.d.ts.map +1 -0
  70. package/dist/code.js +326 -0
  71. package/dist/code.js.map +1 -0
  72. package/dist/compaction.d.ts +15 -0
  73. package/dist/compaction.d.ts.map +1 -0
  74. package/dist/compaction.js +168 -0
  75. package/dist/compaction.js.map +1 -0
  76. package/dist/delegation.d.ts +85 -16
  77. package/dist/delegation.d.ts.map +1 -1
  78. package/dist/delegation.js +240 -106
  79. package/dist/delegation.js.map +1 -1
  80. package/dist/evals/driver.d.ts +10 -0
  81. package/dist/evals/driver.d.ts.map +1 -0
  82. package/dist/evals/driver.js +192 -0
  83. package/dist/evals/driver.js.map +1 -0
  84. package/dist/evals/journal.d.ts +26 -0
  85. package/dist/evals/journal.d.ts.map +1 -0
  86. package/dist/evals/journal.js +483 -0
  87. package/dist/evals/journal.js.map +1 -0
  88. package/dist/evals/judge.d.ts +31 -0
  89. package/dist/evals/judge.d.ts.map +1 -0
  90. package/dist/evals/judge.js +142 -0
  91. package/dist/evals/judge.js.map +1 -0
  92. package/dist/evals/report.d.ts +38 -0
  93. package/dist/evals/report.d.ts.map +1 -0
  94. package/dist/evals/report.js +241 -0
  95. package/dist/evals/report.js.map +1 -0
  96. package/dist/evals/runner.d.ts +24 -0
  97. package/dist/evals/runner.d.ts.map +1 -0
  98. package/dist/evals/runner.js +655 -0
  99. package/dist/evals/runner.js.map +1 -0
  100. package/dist/evals/scorers.d.ts +36 -0
  101. package/dist/evals/scorers.d.ts.map +1 -0
  102. package/dist/evals/scorers.js +259 -0
  103. package/dist/evals/scorers.js.map +1 -0
  104. package/dist/evals/simulation.d.ts +7 -0
  105. package/dist/evals/simulation.d.ts.map +1 -0
  106. package/dist/evals/simulation.js +38 -0
  107. package/dist/evals/simulation.js.map +1 -0
  108. package/dist/evals/testing.d.ts +36 -0
  109. package/dist/evals/testing.d.ts.map +1 -0
  110. package/dist/evals/testing.js +87 -0
  111. package/dist/evals/testing.js.map +1 -0
  112. package/dist/evals/trajectory.d.ts +11 -0
  113. package/dist/evals/trajectory.d.ts.map +1 -0
  114. package/dist/evals/trajectory.js +180 -0
  115. package/dist/evals/trajectory.js.map +1 -0
  116. package/dist/evals/types.d.ts +431 -0
  117. package/dist/evals/types.d.ts.map +1 -0
  118. package/dist/evals/types.js +4 -0
  119. package/dist/evals/types.js.map +1 -0
  120. package/dist/evals.d.ts +14 -0
  121. package/dist/evals.d.ts.map +1 -0
  122. package/dist/evals.js +9 -0
  123. package/dist/evals.js.map +1 -0
  124. package/dist/extensions.d.ts +33 -0
  125. package/dist/extensions.d.ts.map +1 -0
  126. package/dist/extensions.js +188 -0
  127. package/dist/extensions.js.map +1 -0
  128. package/dist/handoff.d.ts +58 -0
  129. package/dist/handoff.d.ts.map +1 -0
  130. package/dist/handoff.js +160 -0
  131. package/dist/handoff.js.map +1 -0
  132. package/dist/index.d.ts +14 -0
  133. package/dist/index.d.ts.map +1 -1
  134. package/dist/index.js +8 -0
  135. package/dist/index.js.map +1 -1
  136. package/dist/input.d.ts +42 -0
  137. package/dist/input.d.ts.map +1 -0
  138. package/dist/input.js +266 -0
  139. package/dist/input.js.map +1 -0
  140. package/dist/mcp.d.ts +77 -0
  141. package/dist/mcp.d.ts.map +1 -0
  142. package/dist/mcp.js +505 -0
  143. package/dist/mcp.js.map +1 -0
  144. package/dist/memory-store.d.ts +11 -0
  145. package/dist/memory-store.d.ts.map +1 -0
  146. package/dist/memory-store.js +272 -0
  147. package/dist/memory-store.js.map +1 -0
  148. package/dist/memory.d.ts +212 -0
  149. package/dist/memory.d.ts.map +1 -0
  150. package/dist/memory.js +613 -0
  151. package/dist/memory.js.map +1 -0
  152. package/dist/otel.d.ts +74 -0
  153. package/dist/otel.d.ts.map +1 -0
  154. package/dist/otel.js +427 -0
  155. package/dist/otel.js.map +1 -0
  156. package/dist/progress.d.ts +17 -0
  157. package/dist/progress.d.ts.map +1 -0
  158. package/dist/progress.js +193 -0
  159. package/dist/progress.js.map +1 -0
  160. package/dist/quickjs.d.ts +19 -0
  161. package/dist/quickjs.d.ts.map +1 -0
  162. package/dist/quickjs.js +519 -0
  163. package/dist/quickjs.js.map +1 -0
  164. package/dist/recovery.d.ts +10 -0
  165. package/dist/recovery.d.ts.map +1 -0
  166. package/dist/recovery.js +62 -0
  167. package/dist/recovery.js.map +1 -0
  168. package/dist/request.d.ts +88 -0
  169. package/dist/request.d.ts.map +1 -0
  170. package/dist/request.js +422 -0
  171. package/dist/request.js.map +1 -0
  172. package/dist/run.d.ts +16 -4
  173. package/dist/run.d.ts.map +1 -1
  174. package/dist/run.js +2016 -245
  175. package/dist/run.js.map +1 -1
  176. package/dist/runs.d.ts +77 -34
  177. package/dist/runs.d.ts.map +1 -1
  178. package/dist/runs.js +267 -85
  179. package/dist/runs.js.map +1 -1
  180. package/dist/schema-to-ts.d.ts +4 -0
  181. package/dist/schema-to-ts.d.ts.map +1 -0
  182. package/dist/schema-to-ts.js +191 -0
  183. package/dist/schema-to-ts.js.map +1 -0
  184. package/dist/session.d.ts +23 -0
  185. package/dist/session.d.ts.map +1 -0
  186. package/dist/session.js +137 -0
  187. package/dist/session.js.map +1 -0
  188. package/dist/snapshot.d.ts +57 -8
  189. package/dist/snapshot.d.ts.map +1 -1
  190. package/dist/snapshot.js +1206 -109
  191. package/dist/snapshot.js.map +1 -1
  192. package/dist/steering.d.ts +75 -0
  193. package/dist/steering.d.ts.map +1 -0
  194. package/dist/steering.js +214 -0
  195. package/dist/steering.js.map +1 -0
  196. package/dist/subagents.d.ts +141 -0
  197. package/dist/subagents.d.ts.map +1 -0
  198. package/dist/subagents.js +746 -0
  199. package/dist/subagents.js.map +1 -0
  200. package/dist/tool-retry.d.ts +12 -0
  201. package/dist/tool-retry.d.ts.map +1 -0
  202. package/dist/tool-retry.js +53 -0
  203. package/dist/tool-retry.js.map +1 -0
  204. package/dist/tree.d.ts +62 -6
  205. package/dist/tree.d.ts.map +1 -1
  206. package/dist/tree.js +192 -23
  207. package/dist/tree.js.map +1 -1
  208. package/dist/types.d.ts +767 -52
  209. package/dist/types.d.ts.map +1 -1
  210. package/dist/workflow-snapshot.d.ts +8 -0
  211. package/dist/workflow-snapshot.d.ts.map +1 -0
  212. package/dist/workflow-snapshot.js +276 -0
  213. package/dist/workflow-snapshot.js.map +1 -0
  214. package/dist/workflow-types.d.ts +171 -0
  215. package/dist/workflow-types.d.ts.map +1 -0
  216. package/dist/workflow-types.js +2 -0
  217. package/dist/workflow-types.js.map +1 -0
  218. package/dist/workflow.d.ts +19 -0
  219. package/dist/workflow.d.ts.map +1 -0
  220. package/dist/workflow.js +1053 -0
  221. package/dist/workflow.js.map +1 -0
  222. package/examples/a2a-remote.ts +85 -0
  223. package/examples/a2a-server.ts +100 -0
  224. package/examples/background.ts +18 -4
  225. package/examples/code-mode.ts +76 -0
  226. package/examples/conversation.ts +57 -0
  227. package/examples/evals.ts +79 -0
  228. package/examples/guardrails.ts +56 -0
  229. package/examples/handoff.ts +79 -0
  230. package/examples/memory.ts +44 -0
  231. package/examples/otel.ts +99 -0
  232. package/examples/steering.ts +69 -0
  233. package/examples/structured-handoff.ts +92 -0
  234. package/examples/subagents.ts +127 -0
  235. package/examples/workflow.ts +74 -0
  236. package/package.json +58 -6
  237. package/src/a2a/auth.ts +62 -0
  238. package/src/a2a/client.ts +733 -0
  239. package/src/a2a/index.ts +74 -0
  240. package/src/a2a/memory-runs.ts +448 -0
  241. package/src/a2a/policy.ts +148 -0
  242. package/src/a2a/push.ts +251 -0
  243. package/src/a2a/remote.ts +1652 -0
  244. package/src/a2a/server.ts +1390 -0
  245. package/src/a2a/signing.ts +348 -0
  246. package/src/a2a/tasks.ts +260 -0
  247. package/src/a2a/wire.ts +1443 -0
  248. package/src/background-types.ts +86 -0
  249. package/src/child.ts +181 -0
  250. package/src/code-driver.ts +48 -0
  251. package/src/code-mode.ts +12 -0
  252. package/src/code-script.ts +149 -0
  253. package/src/code.ts +424 -0
  254. package/src/compaction.ts +212 -0
  255. package/src/delegation.ts +444 -155
  256. package/src/evals/driver.ts +222 -0
  257. package/src/evals/journal.ts +605 -0
  258. package/src/evals/judge.ts +188 -0
  259. package/src/evals/report.ts +295 -0
  260. package/src/evals/runner.ts +826 -0
  261. package/src/evals/scorers.ts +339 -0
  262. package/src/evals/simulation.ts +46 -0
  263. package/src/evals/testing.ts +126 -0
  264. package/src/evals/trajectory.ts +223 -0
  265. package/src/evals/types.ts +463 -0
  266. package/src/evals.ts +72 -0
  267. package/src/extensions.ts +247 -0
  268. package/src/handoff.ts +214 -0
  269. package/src/index.ts +51 -0
  270. package/src/input.ts +319 -0
  271. package/src/mcp.ts +690 -0
  272. package/src/memory-store.ts +366 -0
  273. package/src/memory.ts +893 -0
  274. package/src/otel.ts +568 -0
  275. package/src/progress.ts +214 -0
  276. package/src/quickjs.ts +524 -0
  277. package/src/recovery.ts +90 -0
  278. package/src/request.ts +513 -0
  279. package/src/run.ts +2678 -313
  280. package/src/runs.ts +464 -133
  281. package/src/schema-to-ts.ts +194 -0
  282. package/src/session.ts +178 -0
  283. package/src/snapshot.ts +1595 -124
  284. package/src/steering.ts +329 -0
  285. package/src/subagents.ts +1084 -0
  286. package/src/tool-retry.ts +86 -0
  287. package/src/tree.ts +223 -27
  288. package/src/types.ts +711 -52
  289. package/src/workflow-snapshot.ts +366 -0
  290. package/src/workflow-types.ts +213 -0
  291. package/src/workflow.ts +1316 -0
package/dist/run.js CHANGED
@@ -1,44 +1,42 @@
1
- import { EMPTY_USAGE, ToolRegistry, addUsage, collectTurn, defineTool, messageOf, parseToolArgs, } from "@providerkit/core";
2
- import { AGENT_RUNTIME, executeDelegation, isDelegation, specialistTool, } from "./delegation.js";
3
- import { ExecutionTree, Halt, authorizeTree, fail, treeUsage, untilAbort, } from "./tree.js";
4
- import { checkOptions, completeArguments, copyData, equalData, immutableCopy, isId, isRecord, isScope, isUsage, modelId, readLimits, readTreeLimits, readSnapshot, readTurn, toolId, } from "./snapshot.js";
1
+ import { EMPTY_USAGE, ProviderError, ToolRegistry, collectTurn, createGate, defineTool, messageOf, parseToolArgs, } from "@providerkit/core";
2
+ import { bindMemoryTool, checkMemoryBinding, isMemoryTool, memoryPolicy, memoryScopes, MEMORY_TOOL_NAMES, readMemoryBinding, recallMemory, withMemoryRecall, } from "./memory.js";
3
+ import { allModels, compactionDefinition, compactionId, compactionPlan, modelConversation, } from "./compaction.js";
4
+ import { bindSubagentTool, checkSubagentChildren, subagentInstructions, subagentLimits, } from "./subagents.js";
5
+ import { isCodeTool, programJson, programReceipt, programReply, textBytes, } from "./code.js";
6
+ import { checkRetryTool, readToolRetryPolicy, retryBudget, toolAttempts } from "./tool-retry.js";
7
+ import { GuardChecks, GUARDED_CHUNK_LIMIT, guardDefinition, guardedChunk, jsonBytes, observeLifecycle, refuseGuardedReplay, requireGuardVerdicts, successfulToolResult, toolResultOf, } from "./extensions.js";
8
+ import { AGENT_RUNTIME, executeDelegation, isDelegation, specialistTool, runtimeOf, } from "./delegation.js";
9
+ import { checkHandoffTargets, handoffDelegation, handoffNote, handoffRecord, handoffRef, isHandoff, } from "./handoff.js";
10
+ import { RequestJournal, isClientTool, isInputRequired, requestHash, } from "./request.js";
11
+ import { acknowledgeInputs, acceptInputs, inputReceipts } from "./steering.js";
12
+ import { modelsUsage, readRecoveryPolicy, recoveryToolHash, requireRecovery } from "./recovery.js";
13
+ import { readInput, readStored, repairConversation, requestOf } from "./input.js";
14
+ import { ExecutionTree, Halt, authorizeTree, emitEvent, fail, treeUsage, nodeId, wakeAt, openRequests, readAnswers, requestRecords, stopRequests, untilAbort, } from "./tree.js";
15
+ import { checkOptions, agentSnapshot, completeArguments, copyData, equalData, finalToolResult, finalHandoffResult, immutableCopy, inlineBytes, isBase64, isEnabledTools, isId, isNames, isRecord, isRevision, isUsage, jsonArguments, modelId, recordCodeTools, readLimits, readModelSettings, readTreeLimits, readSnapshot, readTurn, snapshotInlineBytes, toolId, } from "./snapshot.js";
5
16
  /** Reserved for the output contract supplied to defineAgent. */
6
17
  export const RESULT_TOOL_NAME = "submit_result";
7
- function historyOf(snapshot, instructions) {
8
- const history = [
9
- { role: "system", content: instructions },
10
- { role: "user", content: snapshot.input },
11
- ];
12
- for (const model of snapshot.models) {
13
- // Never give a provider half a tool round. The journal retains unfinished work.
14
- if (model.status !== "completed" || model.tools.some((tool) => tool.status !== "completed"))
15
- break;
16
- history.push(model.turn.message);
17
- for (const [index, tool] of model.tools.entries()) {
18
- const call = model.turn.message.toolCalls?.[index];
19
- if (call && tool.status === "completed") {
20
- history.push({
21
- role: "tool",
22
- toolCallId: call.id,
23
- name: call.name,
24
- content: tool.result.content,
25
- });
26
- }
27
- }
28
- }
29
- return copyData(history);
30
- }
31
- function recordOf(snapshot, instructions) {
18
+ function recordOf(snapshot) {
32
19
  const saved = copyData(snapshot);
33
20
  const receipts = [];
34
- let usage = { ...EMPTY_USAGE };
35
- for (const model of saved.models) {
36
- usage = addUsage(usage, model.usage);
21
+ const usage = modelsUsage(allModels(saved));
22
+ for (const model of allModels(saved)) {
23
+ for (const attempt of model.interrupted)
24
+ receipts.push({
25
+ kind: "model",
26
+ id: model.id,
27
+ ...attempt,
28
+ status: "interrupted",
29
+ billing: "unknown",
30
+ });
37
31
  receipts.push({
38
32
  kind: "model",
33
+ ...(saved.compactions.some((entry) => entry.id === model.id)
34
+ ? { purpose: "compaction" }
35
+ : {}),
39
36
  id: model.id,
40
37
  attemptId: model.attemptId,
41
38
  status: model.status,
39
+ billing: model.billing,
42
40
  usage: model.usage,
43
41
  ...(model.status === "completed" && model.turn.source ? { source: model.turn.source } : {}),
44
42
  });
@@ -46,12 +44,51 @@ function recordOf(snapshot, instructions) {
46
44
  continue;
47
45
  for (const [index, tool] of model.tools.entries()) {
48
46
  const call = model.turn.message.toolCalls?.[index];
49
- if (!call || tool.status === "pending")
47
+ if (!call)
48
+ continue;
49
+ for (const attempt of tool.interrupted)
50
+ receipts.push({
51
+ kind: "tool",
52
+ id: tool.id,
53
+ callId: call.id,
54
+ ...attempt,
55
+ status: "interrupted",
56
+ });
57
+ for (const attempt of tool.retries)
58
+ receipts.push({
59
+ kind: "tool",
60
+ id: tool.id,
61
+ callId: call.id,
62
+ attemptId: attempt.attemptId,
63
+ result: attempt.result,
64
+ status: "completed",
65
+ });
66
+ for (const inner of tool.calls ?? []) {
67
+ for (const attempt of inner.retries)
68
+ receipts.push({
69
+ kind: "tool",
70
+ id: inner.id,
71
+ parentOperationId: tool.id,
72
+ callId: inner.id,
73
+ attemptId: attempt.attemptId,
74
+ status: "completed",
75
+ result: attempt.result,
76
+ });
77
+ if (inner.status !== "pending")
78
+ receipts.push({
79
+ kind: "tool",
80
+ id: inner.id,
81
+ parentOperationId: tool.id,
82
+ callId: inner.id,
83
+ attemptId: inner.attemptId,
84
+ status: inner.status,
85
+ ...(inner.status === "completed" ? { result: inner.result } : {}),
86
+ });
87
+ }
88
+ if (tool.status === "pending")
50
89
  continue;
51
90
  receipts.push({
52
- kind: saved.delegations.some((journal) => journal.operationId === tool.id)
53
- ? "delegation"
54
- : "tool",
91
+ kind: saved.delegations.find((journal) => journal.operationId === tool.id)?.kind ?? "tool",
55
92
  id: tool.id,
56
93
  callId: call.id,
57
94
  attemptId: tool.attemptId,
@@ -60,25 +97,51 @@ function recordOf(snapshot, instructions) {
60
97
  });
61
98
  }
62
99
  }
100
+ // A root run replaces this with what its append did. Read from a snapshot alone, whether the
101
+ // session has the turn is not known.
102
+ const session = saved.session && {
103
+ id: saved.session.id,
104
+ status: "pending",
105
+ };
63
106
  return {
64
107
  runId: saved.runId,
65
108
  attemptId: saved.attemptId,
66
109
  usage,
67
110
  treeUsage: treeUsage(saved),
68
111
  receipts,
69
- history: historyOf(saved, instructions),
112
+ inputs: inputReceipts(saved),
113
+ ...handoffRecord(saved),
70
114
  snapshot: saved,
115
+ ...(session ? { session } : {}),
71
116
  };
72
117
  }
73
118
  export function defineAgent(definition) {
74
119
  const { id, version, instructions, provider } = definition;
75
120
  if (!isId(id) ||
76
121
  !isId(version) ||
77
- typeof instructions !== "string" ||
122
+ (typeof instructions !== "string" && typeof instructions !== "function") ||
78
123
  !provider ||
79
124
  typeof provider.createStream !== "function") {
80
125
  throw new TypeError("An agent needs an id, version, instructions and provider.");
81
126
  }
127
+ const settings = readModelSettings(definition.modelSettings);
128
+ const memory = memoryPolicy(definition.memory);
129
+ const compaction = compactionDefinition(definition.compaction);
130
+ const summarizer = definition.compaction?.summarize?.provider;
131
+ const toolRetries = readToolRetryPolicy(definition.toolRetries);
132
+ const guardPolicy = guardDefinition(definition.guardrails);
133
+ const guardrails = definition.guardrails && Object.freeze({ ...definition.guardrails });
134
+ const onLifecycle = definition.onLifecycle;
135
+ if (onLifecycle !== undefined && typeof onLifecycle !== "function")
136
+ throw new TypeError("onLifecycle must be a function.");
137
+ const recovery = readRecoveryPolicy(definition.recovery);
138
+ if (recovery && (!isId(provider.id) || !isId(provider.model)))
139
+ throw new TypeError("A recovery profile needs a stable provider id and model.");
140
+ if (definition.enabledTools !== undefined && !isEnabledTools(definition.enabledTools))
141
+ throw new TypeError("enabledTools must be an allow-list or a function returning one.");
142
+ const enabledTools = Array.isArray(definition.enabledTools)
143
+ ? [...definition.enabledTools]
144
+ : definition.enabledTools;
82
145
  const limits = readLimits(definition.limits);
83
146
  const treeLimits = readTreeLimits(definition.treeLimits);
84
147
  const output = definition.output && {
@@ -91,13 +154,40 @@ export function defineAgent(definition) {
91
154
  typeof output.validate !== "function")) {
92
155
  throw new TypeError("An output contract needs an object schema and a runtime validator.");
93
156
  }
94
- const tools = [...(definition.tools ?? [])];
157
+ const registeredTools = [...(definition.tools ?? [])];
158
+ const codeTools = new Map(registeredTools.filter(isCodeTool).map((tool) => [tool.name, tool]));
159
+ // Keep capability identity for helper grants; approval/dispatch use the bound tools below.
160
+ const capabilities = new Map(registeredTools.map((tool) => [tool.name, tool]));
161
+ for (const code of codeTools.values())
162
+ for (const tool of code.tools) {
163
+ if (capabilities.has(tool.name) && capabilities.get(tool.name) !== tool)
164
+ throw new TypeError(`The name ${tool.name} must refer to the same tool object directly and in every code binding.`);
165
+ capabilities.set(tool.name, tool);
166
+ }
167
+ const needsMemory = !!memory || [...capabilities.values()].some(isMemoryTool);
168
+ if ([...capabilities.values()].some((tool) => MEMORY_TOOL_NAMES.includes(tool.name) && !isMemoryTool(tool)))
169
+ throw new TypeError("memory_search, memory_save and memory_forget are reserved. Register tools from memoryTools().");
170
+ const tools = registeredTools.map((tool) => isDelegation(tool) ? bindSubagentTool(tool, () => agent) : tool);
95
171
  if (new Set(tools.map((tool) => tool.name)).size !== tools.length ||
96
- tools.some((tool) => !isId(tool.name) ||
97
- tool.name === RESULT_TOOL_NAME ||
98
- (!isDelegation(tool) && tool.isTerminal))) {
99
- throw new TypeError(`Use unique tool names and the output contract for terminal results. ${RESULT_TOOL_NAME} is reserved.`);
172
+ [...capabilities.values()].some((tool) => !isId(tool.name) || tool.name === RESULT_TOOL_NAME)) {
173
+ throw new TypeError(`Use unique tool names. ${RESULT_TOOL_NAME} is reserved for the output contract.`);
100
174
  }
175
+ if (definition.stopAtTools !== undefined && !isNames(definition.stopAtTools))
176
+ throw new TypeError("stopAtTools must be a list of unique tool names.");
177
+ const stopAtTools = [...(definition.stopAtTools ?? [])];
178
+ for (const name of stopAtTools) {
179
+ const tool = tools.find((tool) => tool.name === name);
180
+ if (!tool || isDelegation(tool) || isHandoff(tool) || isClientTool(tool) || isCodeTool(tool))
181
+ throw new TypeError("stopAtTools must name ordinary tools registered on this agent.");
182
+ }
183
+ for (const tool of tools)
184
+ if (!isDelegation(tool) &&
185
+ !isHandoff(tool) &&
186
+ !isClientTool(tool) &&
187
+ !isCodeTool(tool) &&
188
+ tool.isTerminal &&
189
+ !stopAtTools.includes(tool.name))
190
+ stopAtTools.push(tool.name);
101
191
  if (output) {
102
192
  tools.push(defineTool({
103
193
  name: RESULT_TOOL_NAME,
@@ -110,17 +200,279 @@ export function defineAgent(definition) {
110
200
  isReadOnly: true,
111
201
  }));
112
202
  }
113
- const registry = new ToolRegistry(tools.filter((tool) => !isDelegation(tool)));
203
+ if ([...codeTools.values()].some((code) => code.tools.some((tool) => stopAtTools.includes(tool.name))))
204
+ throw new TypeError("Stopping tools must stay direct, outside code mode.");
205
+ const registry = new ToolRegistry([...new Set([...tools, ...capabilities.values()])].filter((tool) => !isDelegation(tool) && !isHandoff(tool) && !isClientTool(tool) && !isCodeTool(tool)));
206
+ for (const name of recovery?.readOnlyTools ?? [])
207
+ if ((!registry.get(name)?.isReadOnly && !codeTools.has(name)) || name === RESULT_TOOL_NAME)
208
+ throw new TypeError("Recovery readOnlyTools must name ordinary isReadOnly tools registered on this agent.");
209
+ for (const [name, policy] of Object.entries(toolRetries?.tools ?? {})) {
210
+ const tool = registry.get(name);
211
+ if (!tool ||
212
+ tool.isTerminal ||
213
+ tool.needsApproval ||
214
+ stopAtTools.includes(name) ||
215
+ (policy.replay === "read-only" && !tool.isReadOnly))
216
+ throw new TypeError("toolRetries must name ordinary non-stopping tools without required approval. Read-only retries need isReadOnly.");
217
+ }
114
218
  const delegations = new Map(tools.filter(isDelegation).map((tool) => [tool.name, tool]));
219
+ const handoffs = new Map(tools.filter(isHandoff).map((tool) => [tool.name, tool]));
220
+ function descriptorFor(name, snapshot, operationId) {
221
+ const handoff = handoffs.get(name);
222
+ if (!handoff)
223
+ return delegations.get(name);
224
+ const journal = snapshot.delegations.find((entry) => entry.operationId === operationId);
225
+ if (!journal || journal.kind !== "handoff")
226
+ return undefined;
227
+ if (!equalData(journal.target, handoffRef(handoff.target())))
228
+ throw new TypeError("The saved handoff target or version changed. Restore the registered target.");
229
+ return handoffDelegation(handoff, snapshot, journal);
230
+ }
231
+ const clients = new Map(tools.filter(isClientTool).map((tool) => [tool.name, tool]));
232
+ const names = [...new Set([...capabilities.keys(), ...tools.map((tool) => tool.name)])];
233
+ const directNames = tools.map((tool) => tool.name);
234
+ const definitionsFor = (enabled) => tools
235
+ .filter((tool) => enabled.includes(tool.name))
236
+ .map((tool) => (isCodeTool(tool) ? tool.definition(enabled) : tool.definition()));
237
+ async function toolHash(name) {
238
+ const code = codeTools.get(name);
239
+ if (code)
240
+ return requestHash({
241
+ definition: code.definition(),
242
+ limits: code.limits,
243
+ tools: await Promise.all(code.tools.map(recoveryToolHash)),
244
+ });
245
+ const tool = registry.get(name);
246
+ if (!tool)
247
+ throw new TypeError("Missing recovery tool.");
248
+ return recoveryToolHash(tool);
249
+ }
250
+ function checkNames(value) {
251
+ if (!isNames(value) || value.some((name) => !names.includes(name)))
252
+ throw new TypeError("enabledTools must name each registered tool at most once.");
253
+ return [...value];
254
+ }
255
+ if (Array.isArray(enabledTools))
256
+ checkNames(enabledTools);
257
+ // Adapted from OpenAI Agents JS (MIT), agent.ts and tool.ts. Unlike its per-turn
258
+ // callbacks, these resolve once: a restarted worker must see the same prompt and tools.
259
+ async function resolveDefinition(start, options, runId, source) {
260
+ const signal = options.signal ?? new AbortController().signal;
261
+ const run = Object.freeze({
262
+ agentId: id,
263
+ version,
264
+ runId,
265
+ ...immutableCopy({ history: start.history, input: start.input }),
266
+ context: Object.freeze({ ...options.context }),
267
+ signal,
268
+ });
269
+ const text = source
270
+ ? source.instructions
271
+ : typeof instructions === "function"
272
+ ? await untilAbort(Promise.resolve(instructions(run)), signal)
273
+ : instructions;
274
+ if (typeof text !== "string")
275
+ throw new TypeError("instructions must return a string.");
276
+ async function select(selection) {
277
+ return selection === undefined
278
+ ? [...names]
279
+ : checkNames(typeof selection === "function"
280
+ ? await untilAbort(Promise.resolve(selection(run)), signal)
281
+ : selection);
282
+ }
283
+ const allowed = source ? source.enabledTools : await select(enabledTools);
284
+ const selected = options.enabledTools === undefined ? allowed : await select(options.enabledTools);
285
+ if (selected.some((name) => name !== RESULT_TOOL_NAME && !allowed.includes(name)))
286
+ throw new TypeError("Run enabledTools may narrow the agent's tools, not enable a disabled tool.");
287
+ // The definition's order is part of the provider's cached prefix, not the allow-list's.
288
+ const enabled = names.filter((name) => selected.includes(name) || (output && name === RESULT_TOOL_NAME));
289
+ // Ported from PydanticAI (MIT), settings.py, merge_model_settings: the run wins.
290
+ // Provider defaults remain in core; passing only set values preserves that first layer.
291
+ const { onActivity: _onActivity, onRateLimit: _onRateLimit, ...modelSettings } = {
292
+ ...(source ? source.modelSettings : settings),
293
+ ...readModelSettings(options.modelSettings),
294
+ };
295
+ const choice = modelSettings.toolChoice;
296
+ if (output && choice === "none")
297
+ throw new TypeError("toolChoice none disables submit_result, which a checked-output run needs to finish.");
298
+ if ((choice === "required" && enabled.length === 0) ||
299
+ (typeof choice === "object" && !enabled.includes(choice.name)))
300
+ throw new TypeError("toolChoice must name an enabled tool; required needs at least one.");
301
+ const toolHashes = Object.fromEntries(await Promise.all((recovery?.readOnlyTools ?? []).map(async (name) => {
302
+ return [name, await toolHash(name)];
303
+ })));
304
+ const retryHashes = Object.fromEntries(await Promise.all(Object.keys(toolRetries?.tools ?? {}).map(async (name) => {
305
+ const tool = registry.get(name);
306
+ if (!tool)
307
+ throw new TypeError("Missing retry tool.");
308
+ return [name, await recoveryToolHash(tool)];
309
+ })));
310
+ return {
311
+ instructions: text,
312
+ ...(memory ? { memory: copyData(memory) } : {}),
313
+ modelSettings,
314
+ enabledTools: enabled,
315
+ stopAtTools: [...stopAtTools],
316
+ ...(codeTools.size ? { codeTools: recordCodeTools(codeTools) } : {}),
317
+ guardrails: copyData(guardPolicy),
318
+ compaction: copyData(compaction),
319
+ toolRetries: toolRetries ? { policy: copyData(toolRetries), toolHashes: retryHashes } : null,
320
+ recovery: recovery
321
+ ? {
322
+ policy: copyData(recovery),
323
+ provider: { id: provider.id, model: provider.model },
324
+ toolHashes,
325
+ modelToolsHash: await requestHash(definitionsFor(enabled)),
326
+ }
327
+ : null,
328
+ };
329
+ }
115
330
  function validateResult(candidate) {
331
+ // copyData permits absent optional values, but a result must survive a JSON checkpoint.
332
+ if (candidate === undefined)
333
+ throw new TypeError("The result must be a JSON value. Return null instead of undefined.");
116
334
  if (output)
117
335
  return output.validate(copyData(candidate));
118
336
  if (typeof candidate !== "string" || !candidate.trim())
119
337
  throw new TypeError("The model returned no answer.");
120
338
  return candidate;
121
339
  }
122
- async function execute(snapshot, options, scope, evidence) {
340
+ // Adapted from OpenAI Agents JS (MIT), result.ts: the active agent processes its own
341
+ // final output. Follow our saved child instead of casting it to the source's output type.
342
+ function completedOutput(snapshot) {
343
+ if (snapshot.state.status !== "completed")
344
+ throw new TypeError("The run has no completed result.");
345
+ const last = snapshot.models.at(-1);
346
+ const transfer = last?.status === "completed" && finalHandoffResult(snapshot, last);
347
+ if (!transfer)
348
+ return validateResult(snapshot.state.candidate);
349
+ const name = last.turn.message.toolCalls?.[0]?.name;
350
+ const target = name && handoffs.get(name)?.target();
351
+ if (!target || !equalData(handoffRef(target), handoffRef(transfer.child)))
352
+ throw new TypeError("The completed handoff does not match its registered target.");
353
+ const result = target[AGENT_RUNTIME].hydrate(transfer.child);
354
+ if (result.status !== "completed")
355
+ throw new TypeError("The handoff target has no completed result.");
356
+ return result.output;
357
+ }
358
+ function requestFor(snapshot, model, index) {
359
+ const call = model.turn.message.toolCalls?.[index];
360
+ const tool = model.tools[index];
361
+ if (!call || !tool)
362
+ fail("invalid_journal", "The tool call is missing from its journal.");
363
+ return {
364
+ agentId: id,
365
+ version,
366
+ runId: snapshot.runId,
367
+ attemptId: tool.status === "running" || tool.status === "completed"
368
+ ? tool.attemptId
369
+ : tool.retries.length
370
+ ? `${snapshot.attemptId}/tool-attempt/${tool.retries.length + tool.interrupted.length + 1}`
371
+ : snapshot.attemptId,
372
+ operationId: tool.id,
373
+ ...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
374
+ call,
375
+ arguments: codeTools.has(call.name)
376
+ ? (jsonArguments(call.arguments) ?? {})
377
+ : parseToolArgs(call.arguments),
378
+ };
379
+ }
380
+ async function needsApproval(call, options, signal) {
381
+ if (call.call.name === RESULT_TOOL_NAME)
382
+ return false;
383
+ const tool = tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
384
+ return (tool?.needsApproval === true ||
385
+ (await untilAbort(Promise.resolve(options.host?.needsApproval?.(immutableCopy(call))), signal)) === true);
386
+ }
387
+ function journalFor(snapshot, model, index, options, scope, signal, effectiveCall) {
388
+ const call = requestFor(snapshot, model, index);
389
+ const execution = model.tools[index];
390
+ if (!execution)
391
+ throw new TypeError("Missing tool journal.");
392
+ return requestsFor(call, execution, options, scope, signal, effectiveCall);
393
+ }
394
+ function requestsFor(call, execution, options, scope, signal, effectiveCall) {
395
+ const tool = tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
396
+ return new RequestJournal(execution, effectiveCall ?? call, options, scope, signal,
397
+ // The policy hash follows the original model call even when dispatch arguments were edited.
398
+ async () => requestHash({
399
+ definition: tool?.definition() ?? null,
400
+ needsApproval: await needsApproval(call, options, signal),
401
+ kind: tool && isHandoff(tool)
402
+ ? "handoff"
403
+ : tool && isDelegation(tool)
404
+ ? "delegation"
405
+ : tool && isClientTool(tool)
406
+ ? "client"
407
+ : "tool",
408
+ ...(tool && isHandoff(tool) ? { target: handoffRef(tool.target()) } : {}),
409
+ ...(tool && isClientTool(tool) ? { resultSchema: tool.resultSchema } : {}),
410
+ }), (decision) => {
411
+ if (decision.type === "result") {
412
+ const client = clients.get(call.call.name);
413
+ if (!client)
414
+ throw new TypeError("This call is not a registered client tool.");
415
+ client.result(decision.value);
416
+ }
417
+ }, !!guardrails?.toolOutput);
418
+ }
419
+ // Intake is a tree-wide pre-effect barrier. A saved child receives its decisions in its
420
+ // snapshot before the host may reuse a segment. No browser-supplied route is consulted.
421
+ async function answerRequests(snapshot, options, scope, answers, signal) {
422
+ if (snapshot.state.status !== "running" && snapshot.state.status !== "suspended")
423
+ return;
424
+ signal.throwIfAborted();
425
+ for (const model of snapshot.models) {
426
+ if (model.status !== "completed")
427
+ continue;
428
+ for (const [index, execution] of model.tools.entries()) {
429
+ if (execution.status === "completed")
430
+ continue;
431
+ const journal = journalFor(snapshot, model, index, options, scope, signal);
432
+ for (const record of [...(execution.asks ?? [])]) {
433
+ if (record.closed)
434
+ continue;
435
+ scope.tree.active();
436
+ signal.throwIfAborted();
437
+ if (!record.decision && Object.hasOwn(answers, record.request.id))
438
+ await journal.resolve(record, answers[record.request.id]);
439
+ else
440
+ await journal.refresh(record);
441
+ }
442
+ }
443
+ }
444
+ for (const entry of snapshot.delegations) {
445
+ const model = snapshot.models.find((model) => model.status === "completed" && model.tools.some((tool) => tool.id === entry.operationId));
446
+ const position = model?.status === "completed"
447
+ ? model.tools.findIndex((tool) => tool.id === entry.operationId)
448
+ : -1;
449
+ const name = model?.status === "completed" ? model.turn.message.toolCalls?.[position]?.name : undefined;
450
+ const descriptor = name && descriptorFor(name, snapshot, entry.operationId);
451
+ if (!descriptor)
452
+ continue;
453
+ for (const child of entry.children) {
454
+ if (child.snapshot.state.status !== "running" &&
455
+ child.snapshot.state.status !== "suspended")
456
+ continue;
457
+ const specialist = descriptor.specialists.find((agent) => agent.kind === child.snapshot.kind &&
458
+ agent.id === nodeId(child.snapshot) &&
459
+ agent.version === child.snapshot.version);
460
+ if (!specialist)
461
+ throw new TypeError("Unregistered specialist.");
462
+ await runtimeOf(specialist).answerRequests(child.snapshot, options, {
463
+ tree: scope.tree,
464
+ depth: scope.depth + 1,
465
+ path: [
466
+ ...scope.path,
467
+ { operationId: entry.operationId, key: child.key, runId: child.snapshot.runId },
468
+ ],
469
+ }, answers, signal);
470
+ }
471
+ }
472
+ }
473
+ async function execute(snapshot, options, scope, answers) {
123
474
  const host = options.host;
475
+ const limits = snapshot.limits;
124
476
  const deadline = snapshot.startedAt + limits.elapsedMs;
125
477
  const timeout = new AbortController();
126
478
  const signal = AbortSignal.any([
@@ -130,8 +482,8 @@ export function defineAgent(definition) {
130
482
  ]);
131
483
  const timer = setTimeout(() => timeout.abort(new Error("The run reached its time limit.")), Math.max(0, deadline - Date.now()));
132
484
  let release = () => { };
133
- let approved;
134
485
  let completed;
486
+ let started = false;
135
487
  function active() {
136
488
  scope.tree.active();
137
489
  if (options.signal?.aborted)
@@ -140,47 +492,303 @@ export function defineAgent(definition) {
140
492
  throw new Halt({ status: "limited", limit: "elapsedMs" });
141
493
  }
142
494
  function emit(event) {
495
+ emitEvent(options, event);
496
+ }
497
+ const save = () => scope.tree.save();
498
+ const callbackContext = Object.freeze({
499
+ agentId: id,
500
+ version,
501
+ runId: snapshot.runId,
502
+ attemptId: snapshot.attemptId,
503
+ context: Object.freeze({ ...options.context }),
504
+ signal,
505
+ });
506
+ const observe = (event, callSignal = signal) => observeLifecycle([onLifecycle, options.onLifecycle], event, callSignal === signal ? callbackContext : { ...callbackContext, signal: callSignal });
507
+ const guards = new GuardChecks(snapshot, guardrails, callbackContext, save, active);
508
+ function slotFor(model, index) {
509
+ return {
510
+ model,
511
+ get() {
512
+ const execution = model.tools[index];
513
+ if (!execution)
514
+ fail("invalid_journal", "The tool call is missing from its journal.");
515
+ return execution;
516
+ },
517
+ set(execution) {
518
+ model.tools[index] = execution;
519
+ },
520
+ request: () => requestFor(snapshot, model, index),
521
+ };
522
+ }
523
+ function invocationActive(slot) {
524
+ active();
525
+ slot.inner?.signal.throwIfAborted();
526
+ }
527
+ function toolChecks(callSignal) {
528
+ return callSignal === signal
529
+ ? guards
530
+ : new GuardChecks(snapshot, guardrails, { ...callbackContext, signal: callSignal }, save, () => {
531
+ active();
532
+ callSignal.throwIfAborted();
533
+ });
534
+ }
535
+ async function beforeTool(request, callSignal = signal) {
536
+ await toolChecks(callSignal).check("toolInput", request.operationId, request.attemptId, request);
537
+ active();
538
+ callSignal.throwIfAborted();
539
+ await observe({ type: "tool_start", request }, callSignal);
540
+ active();
541
+ callSignal.throwIfAborted();
542
+ }
543
+ async function withToolError(request, work, callSignal = signal) {
143
544
  try {
144
- void Promise.resolve(options.onEvent?.(immutableCopy(event))).catch(() => { });
545
+ await work();
145
546
  }
146
- catch {
147
- // Progress is not the durable journal, and an observer cannot stop execution.
547
+ catch (error) {
548
+ await observe({ type: "tool_error", request }, callSignal);
549
+ throw error;
550
+ }
551
+ }
552
+ function restart(kind, operationId, previousAttemptId, attemptId = snapshot.attemptId) {
553
+ // Adapted from Vercel AI SDK (Apache-2.0), workflow/do-stream-step.ts: reset the
554
+ // current display before replacement output. Unlike reset-step, identity stays explicit.
555
+ emit({
556
+ type: "operation_restart",
557
+ kind,
558
+ runId: snapshot.runId,
559
+ operationId,
560
+ previousAttemptId,
561
+ attemptId,
562
+ });
563
+ }
564
+ async function checkToolRecovery(model, index, previous) {
565
+ const execution = model.tools[index];
566
+ if (!execution)
567
+ fail("invalid_journal", "The tool call is missing from its journal.");
568
+ const request = requestFor(snapshot, model, index);
569
+ const tool = registry.get(request.call.name);
570
+ const recorded = snapshot.definition.recovery;
571
+ const budget = retryBudget(snapshot.definition.toolRetries, request.call.name);
572
+ if (budget && previous + 1 >= budget.maxAttempts)
573
+ fail("tool_retry_exhausted", "This call reached its tool attempt limit. Reconcile the saved attempts with the host.", execution.id);
574
+ requireRecovery(!!tool?.isReadOnly &&
575
+ recorded?.policy.readOnlyTools?.includes(request.call.name) === true &&
576
+ !execution.asks?.length &&
577
+ !!host?.beforeTool, previous, recorded, execution.id);
578
+ if (!tool || (await recoveryToolHash(tool)) !== recorded?.toolHashes[tool.name])
579
+ fail("recovery_definition_changed", "The interrupted tool's definition changed. Reconcile it with the host before continuing.", execution.id);
580
+ active();
581
+ }
582
+ async function recoverTools(model) {
583
+ for (const [index, execution] of model.tools.entries()) {
584
+ if (execution.status !== "running")
585
+ continue;
586
+ const code = codeTools.get(model.turn.message.toolCalls?.[index]?.name ?? "");
587
+ if (code) {
588
+ const calls = execution.calls ?? [];
589
+ const unknown = calls.find((call) => call.status === "running" && !registry.get(call.name)?.isReadOnly);
590
+ if (unknown)
591
+ fail("interrupted_operation", "This inner call started but has no saved result. Reconcile its effect with the host; the program will not replay it.", unknown.id);
592
+ refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
593
+ const restartable = calls.every((call) => registry.get(call.name)?.isReadOnly && !call.asks?.length) &&
594
+ !execution.asks?.length &&
595
+ snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) &&
596
+ !!host?.beforeTool &&
597
+ toolAttempts(execution) < (snapshot.definition.recovery?.policy.maxAttempts ?? 0);
598
+ for (const [position, call] of calls.entries()) {
599
+ if (call.status === "completed")
600
+ continue;
601
+ calls[position] = {
602
+ ...call,
603
+ status: "completed",
604
+ result: {
605
+ ok: false,
606
+ kind: "interrupted",
607
+ content: call.started
608
+ ? "This read stopped before its result was saved. It changed nothing."
609
+ : "This call did not start. It changed nothing.",
610
+ },
611
+ };
612
+ }
613
+ if (restartable) {
614
+ if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
615
+ fail("recovery_definition_changed", "The code tool's bindings or limits changed. Restore the saved definition before restarting.", execution.id);
616
+ model.tools[index] = {
617
+ id: execution.id,
618
+ status: "pending",
619
+ previousAttemptId: execution.attemptId,
620
+ interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
621
+ retries: execution.retries,
622
+ calls,
623
+ };
624
+ await save();
625
+ }
626
+ else
627
+ await finishTool(model, index, requestFor(snapshot, model, index), code.close(calls));
628
+ continue;
629
+ }
630
+ refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
631
+ await checkToolRecovery(model, index, execution.interrupted.length + execution.retries.length);
632
+ model.tools[index] = {
633
+ id: execution.id,
634
+ status: "pending",
635
+ previousAttemptId: execution.attemptId,
636
+ retries: execution.retries,
637
+ interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
638
+ };
148
639
  }
149
640
  }
150
- const save = () => scope.tree.save();
151
641
  function usedTools() {
152
642
  return snapshot.models.reduce((count, model) => count +
153
643
  (model.status === "completed"
154
- ? model.tools.filter((tool) => tool.status !== "pending").length
644
+ ? model.tools.reduce((total, tool) => total +
645
+ toolAttempts(tool) +
646
+ (tool.calls ?? []).reduce((innerTotal, call) => innerTotal + 1 + call.retries.length, 0), 0)
155
647
  : 0), 0);
156
648
  }
157
- function requestFor(model, index) {
158
- const call = model.turn.message.toolCalls?.[index];
159
- const tool = model.tools[index];
160
- if (!call || !tool)
161
- fail("invalid_journal", "The tool call is missing from its journal.");
162
- return {
163
- agentId: id,
164
- version,
165
- runId: snapshot.runId,
166
- attemptId: snapshot.attemptId,
167
- operationId: tool.id,
168
- call,
169
- arguments: parseToolArgs(call.arguments),
170
- };
649
+ async function checkToolRetry(slot) {
650
+ const execution = slot.get();
651
+ const recorded = snapshot.definition.toolRetries;
652
+ if (!recorded)
653
+ fail("invalid_journal", "Missing tool retry policy.");
654
+ const request = slot.request();
655
+ await checkRetryTool(registry.get(request.call.name), recorded, execution);
656
+ if (!host?.beforeTool ||
657
+ (await needsApproval(request, options, slot.inner?.signal ?? signal)))
658
+ fail("tool_retry_unsafe", "A retry needs current host authorization and cannot reuse or open an approval.", execution.id);
659
+ invocationActive(slot);
660
+ }
661
+ async function retryTool(slot) {
662
+ const execution = slot.get();
663
+ if (execution.status !== "completed" ||
664
+ execution.result.ok ||
665
+ execution.asks?.length ||
666
+ !["failed", "timeout"].includes(execution.result.kind))
667
+ return false;
668
+ const request = slot.request();
669
+ const policy = retryBudget(snapshot.definition.toolRetries, request.call.name);
670
+ const recoveryCeiling = execution.interrupted.length
671
+ ? snapshot.definition.recovery?.policy.maxAttempts
672
+ : undefined;
673
+ if (!policy ||
674
+ toolAttempts(execution) >=
675
+ Math.min(policy.maxAttempts, recoveryCeiling ?? policy.maxAttempts))
676
+ return false;
677
+ invocationActive(slot);
678
+ if (slot.inner && slot.inner.callsLeft() <= 0)
679
+ return false;
680
+ if (usedTools() >= limits.toolCalls) {
681
+ throw new Halt({ status: "limited", limit: "toolCalls" });
682
+ }
683
+ await checkToolRetry(slot);
684
+ let reconciliation;
685
+ if (policy.replay === "reconcile") {
686
+ const reconcile = host?.reconcileToolRetry;
687
+ if (!reconcile)
688
+ fail("tool_retry_unsafe", "This failed call needs host reconciliation before it can be repeated.", execution.id);
689
+ const verdict = await untilAbort(Promise.resolve(reconcile(immutableCopy({ request, result: execution.result }), callbackContext)), slot.inner?.signal ?? signal);
690
+ invocationActive(slot);
691
+ if (verdict?.outcome !== "not_run" || !isId(verdict.receipt))
692
+ fail("tool_retry_unsafe", "The host could not confirm that the failed call did not run. Reconcile its effect before continuing.", execution.id);
693
+ reconciliation = verdict.receipt;
694
+ }
695
+ // Guest calls can reserve the remaining budget while host reconciliation is awaited.
696
+ invocationActive(slot);
697
+ if (slot.inner && slot.inner.callsLeft() <= 0)
698
+ return false;
699
+ slot.set({
700
+ id: execution.id,
701
+ status: "pending",
702
+ previousAttemptId: execution.attemptId,
703
+ interrupted: execution.interrupted,
704
+ retries: [
705
+ ...execution.retries,
706
+ {
707
+ attemptId: execution.attemptId,
708
+ arguments: copyData(request.arguments),
709
+ result: execution.result,
710
+ ...(reconciliation ? { reconciliation } : {}),
711
+ },
712
+ ],
713
+ });
714
+ // Retain the failure and reconciliation before reserving another attempt.
715
+ await save();
716
+ return true;
171
717
  }
172
718
  async function finishTool(model, index, request, result) {
173
- model.tools[index] = {
719
+ return finishExecution(slotFor(model, index), request, result);
720
+ }
721
+ async function finishExecution(slot, request, result) {
722
+ if (!result.ok && (result.kind === "cancelled" || result.kind === "denied")) {
723
+ for (const record of slot.get().asks ?? [])
724
+ if (!record.decision && !record.closed)
725
+ record.closed = "stopped";
726
+ // A cancelled coordination call cannot leave suspended children under a completed
727
+ // tool receipt. Already settled children and their usage remain untouched.
728
+ const delegation = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
729
+ for (const child of delegation?.children ?? [])
730
+ stopRequests(child.snapshot);
731
+ // Once a target was admitted, it owns this conversation. Denying a renewed transfer
732
+ // stops that conversation; it cannot buy a new source turn after target effects.
733
+ if (delegation?.kind === "handoff" && delegation.children.length > 0)
734
+ snapshot.state = { status: "cancelled" };
735
+ }
736
+ const edited = slot
737
+ .get()
738
+ .asks?.some((record) => !record.closed &&
739
+ record.decision?.type === "approve" &&
740
+ record.decision.arguments !== undefined);
741
+ if (edited && !codeTools.has(request.call.name))
742
+ result = {
743
+ ...result,
744
+ content: `${result.content}\nThe reviewer replaced the tool arguments before this call.`,
745
+ };
746
+ const callSignal = slot.inner?.signal ?? signal;
747
+ const checks = toolChecks(callSignal);
748
+ await observe({ type: "tool_end", request, result }, callSignal);
749
+ invocationActive(slot);
750
+ if (guardPolicy?.stages.includes("toolOutput") &&
751
+ jsonBytes(result) > guardPolicy.maxOutputBytes)
752
+ await checks.overflow("toolOutput", request.operationId, request.attemptId);
753
+ await checks.check("toolOutput", request.operationId, request.attemptId, {
754
+ request,
755
+ result,
756
+ });
757
+ invocationActive(slot);
758
+ // Check after callbacks: another concurrent result may have consumed the remaining bytes.
759
+ if (result.ok &&
760
+ result.images &&
761
+ snapshotInlineBytes(snapshot) +
762
+ inlineBytes([
763
+ {
764
+ role: "tool",
765
+ name: request.call.name,
766
+ toolCallId: request.call.id,
767
+ content: result.content,
768
+ images: result.images,
769
+ },
770
+ ], "") >
771
+ limits.inlineBytes)
772
+ fail("tool_media_limit", "Tool images exceed this run's inline byte limit. Return fewer or smaller images before starting new work.", request.operationId);
773
+ if (slot.inner)
774
+ result = slot.inner.record(result);
775
+ const previous = slot.get();
776
+ slot.set({
777
+ interrupted: previous.interrupted,
778
+ retries: previous.retries,
779
+ asks: previous.asks,
780
+ calls: previous.calls,
174
781
  id: request.operationId,
175
- attemptId: snapshot.attemptId,
782
+ attemptId: request.attemptId,
176
783
  status: "completed",
177
784
  result,
178
- };
785
+ });
179
786
  await save();
180
787
  emit({ type: "tool_result", request, result });
181
788
  }
182
- async function runTool(model, index, request, tool, parallel) {
183
- active();
789
+ async function runTool(slot, request, tool, parallel) {
790
+ invocationActive(slot);
791
+ const callSignal = slot.inner?.signal ?? signal;
184
792
  let result;
185
793
  if (!tool) {
186
794
  result = {
@@ -196,59 +804,512 @@ export function defineAgent(definition) {
196
804
  content: "Tool arguments must be one complete JSON object. Send the full object again.",
197
805
  };
198
806
  }
199
- else if (tool.isTerminal && model.tools.length !== 1) {
807
+ else if (tool.isTerminal && slot.model?.tools.length !== 1) {
200
808
  result = {
201
809
  ok: false,
202
810
  kind: "invalid_input",
203
- content: `Call ${RESULT_TOOL_NAME} alone, after the other tool results arrive.`,
811
+ content: `Call ${tool.name} alone, after the other tool results arrive.`,
204
812
  };
205
813
  }
206
814
  else {
207
- const outcome = await scope.tree.invokeTool(parallel, signal, async () => {
208
- active();
209
- const approval = approved?.request.operationId === request.operationId ? approved : undefined;
210
- if (tool.needsApproval && !approval)
211
- fail("approval_required", "This tool needs a host-approved decision.", request.operationId);
212
- function checkExpiry() {
213
- if (approval && approval.scope.expiresAt <= Date.now())
214
- fail("approval_expired", "The approval expired. Request a new decision before running this tool.", request.operationId);
815
+ // The barrier can return on abort before its callback unwinds. Retain that callback
816
+ // so a program cannot finish while a late guard or tool can still write a receipt.
817
+ let dispatch;
818
+ async function invoke() {
819
+ invocationActive(slot);
820
+ const journal = requestsFor(slot.request(), slot.get(), options, scope, callSignal);
821
+ try {
822
+ await beforeTool(request, callSignal);
823
+ if (slot.get().retries.length)
824
+ await checkToolRetry(slot);
825
+ await journal.recheck(request);
826
+ invocationActive(slot);
827
+ if (slot.inner) {
828
+ slot.inner.start();
829
+ if (!tool?.isReadOnly)
830
+ await save();
831
+ invocationActive(slot);
832
+ await journal.recheck(request);
833
+ invocationActive(slot);
834
+ }
835
+ emit({ type: "tool_start", request });
836
+ invocationActive(slot);
837
+ // Observers and checkpoints can expire an approval or revoke ownership.
838
+ // Reauthorize after them, with no further callback before the actual invocation.
839
+ await journal.recheck(request);
840
+ await journal.assertFresh();
841
+ invocationActive(slot);
215
842
  }
216
- checkExpiry();
217
- await untilAbort(Promise.resolve(host?.beforeTool?.(immutableCopy(request), immutableCopy(approval))), signal);
218
- active();
219
- checkExpiry();
220
- emit({ type: "tool_start", request });
221
- active();
222
- // A synchronous observer can delay invocation past the approval's expiry.
223
- checkExpiry();
224
- return tool.invoke(copyData(request.arguments), {
843
+ catch (error) {
844
+ if (!slot.inner && error instanceof Halt && error.state.status === "suspended")
845
+ slot.set({
846
+ id: request.operationId,
847
+ status: "pending",
848
+ interrupted: slot.get().interrupted,
849
+ retries: slot.get().retries,
850
+ asks: slot.get().asks,
851
+ });
852
+ throw error;
853
+ }
854
+ const records = slot.get().asks ?? [];
855
+ const answers = Object.fromEntries(records
856
+ .filter((record) => !record.closed &&
857
+ record.request.ask.type === "question" &&
858
+ record.decision?.type === "answer")
859
+ .map((record) => [
860
+ record.request.ask.type === "question" ? record.request.ask.key : "",
861
+ record.decision?.type === "answer" ? record.decision.answer : undefined,
862
+ ]));
863
+ const decision = [...records]
864
+ .reverse()
865
+ .find((record) => !record.closed && record.decision)?.decision;
866
+ if (!tool)
867
+ throw new TypeError("Missing dispatched tool.");
868
+ return untilAbort(bindMemoryTool(tool, options.memory, snapshot, request).invoke(copyData(request.arguments), {
225
869
  ...options.context,
870
+ answers: immutableCopy(answers),
871
+ decision: immutableCopy(decision),
226
872
  runId: snapshot.runId,
227
- attemptId: snapshot.attemptId,
873
+ attemptId: request.attemptId,
228
874
  operationId: request.operationId,
875
+ parentOperationId: request.parentOperationId,
229
876
  callId: request.call.id,
230
- signal,
877
+ signal: callSignal,
878
+ }), callSignal);
879
+ }
880
+ let outcome;
881
+ try {
882
+ outcome = await scope.tree.invokeTool(parallel, callSignal, () => {
883
+ dispatch = invoke();
884
+ return dispatch;
231
885
  });
232
- });
233
- // Core reports an aborted invocation as data. It must not buy another model turn.
886
+ }
887
+ catch (error) {
888
+ if (slot.inner && dispatch)
889
+ await dispatch.catch(() => { });
890
+ throw error;
891
+ }
892
+ // Run/tree stops never buy another model turn. Program-only abort is settled below.
234
893
  if (!outcome.ok)
235
894
  active();
236
- result = outcome.ok
237
- ? { ok: true, content: outcome.summary }
238
- : { ok: false, content: outcome.error, kind: outcome.kind };
895
+ if (!outcome.ok &&
896
+ isMemoryTool(tool) &&
897
+ outcome.cause instanceof Error &&
898
+ outcome.cause.name === "MemoryScopeError")
899
+ fail("memory_scope_violation", "Memory returned another scope's data. Fix the store before continuing.", request.operationId);
900
+ if (!outcome.ok && outcome.kind === "failed" && isInputRequired(outcome.cause)) {
901
+ if (slot.inner) {
902
+ result = {
903
+ ok: false,
904
+ kind: "denied",
905
+ content: `This call needs a person's answer, and code cannot wait for one.${directNames.includes(tool.name) ? ` Call ${tool.name} directly.` : " Ask the host to provide a direct tool."}`,
906
+ };
907
+ await finishExecution(slot, request, result);
908
+ return;
909
+ }
910
+ if (slot.get().retries.length)
911
+ fail("tool_retry_unsafe", "A retried call requested input. Reconcile it with the host; retries cannot create request replay paths.", request.operationId);
912
+ slot.set({
913
+ id: request.operationId,
914
+ status: "pending",
915
+ asks: slot.get().asks,
916
+ retries: slot.get().retries,
917
+ interrupted: slot.get().interrupted,
918
+ });
919
+ const journal = requestsFor(request, slot.get(), options, scope, signal);
920
+ const previous = journal.latest(outcome.cause.ask);
921
+ if (previous?.decision)
922
+ previous.closed = "invalid";
923
+ await journal.open(outcome.cause.ask, outcome.cause.problem
924
+ ? { code: "invalid_answer", message: outcome.cause.problem }
925
+ : undefined);
926
+ return;
927
+ }
928
+ try {
929
+ if (slot.inner && outcome.ok) {
930
+ try {
931
+ if (outcome.output !== undefined)
932
+ programJson(outcome.output);
933
+ result = { ok: true, content: outcome.summary, output: outcome.output };
934
+ }
935
+ catch {
936
+ slot.inner.outputError =
937
+ "The call ran but returned a non-JSON value. Check its effect before calling it again.";
938
+ result = { ok: true, content: slot.inner.outputError };
939
+ }
940
+ }
941
+ else
942
+ result =
943
+ tool.name === RESULT_TOOL_NAME && outcome.ok
944
+ ? { ok: true, content: outcome.summary }
945
+ : toolResultOf(outcome);
946
+ }
947
+ catch {
948
+ fail("invalid_tool_output", "The tool returned unsavable data or unsupported content. Return JSON or core text/image parts.", request.operationId);
949
+ }
950
+ if (outcome.ok && tool.name === RESULT_TOOL_NAME && result.ok)
951
+ result.final = { candidate: copyData(request.arguments) };
952
+ if (outcome.ok && snapshot.definition.stopAtTools.includes(tool.name)) {
953
+ try {
954
+ const candidate = output ? copyData(outcome.output) : outcome.summary;
955
+ validateResult(candidate);
956
+ result = { ...result, ok: true, final: { candidate } };
957
+ }
958
+ catch (error) {
959
+ result = {
960
+ ok: false,
961
+ kind: "invalid_output",
962
+ content: `The tool result did not pass the output check: ${messageOf(error)}`,
963
+ };
964
+ }
965
+ }
239
966
  }
240
- await finishTool(model, index, request, result);
967
+ await finishExecution(slot, request, result);
968
+ active();
969
+ }
970
+ function canParallel(request, tool, execution) {
971
+ return (!guardrails?.toolInput &&
972
+ !guardrails?.toolOutput &&
973
+ !retryBudget(snapshot.definition.toolRetries, request.call.name) &&
974
+ tool?.isConcurrencySafe === true &&
975
+ snapshot.definition.enabledTools.includes(tool.name) &&
976
+ (request.parentOperationId !== undefined || directNames.includes(tool.name)) &&
977
+ !tool.needsApproval &&
978
+ !host?.needsApproval &&
979
+ !execution.asks?.length &&
980
+ !tool.isTerminal &&
981
+ host?.canRunConcurrently?.(immutableCopy(request)) === true);
982
+ }
983
+ async function runProgram(model, index, request, code) {
984
+ const slot = slotFor(model, index);
985
+ const previous = slot.get();
986
+ if (previous.interrupted.length) {
987
+ requireRecovery(snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) === true &&
988
+ !!host?.beforeTool &&
989
+ !previous.asks?.length &&
990
+ (previous.calls ?? []).every((call) => call.status === "completed" &&
991
+ registry.get(call.name)?.isReadOnly &&
992
+ !call.asks?.length), previous.interrupted.length - 1, snapshot.definition.recovery, previous.id);
993
+ if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
994
+ fail("recovery_definition_changed", "The code bindings changed. Restore the saved definition before restarting.", previous.id);
995
+ }
996
+ const calls = previous.calls ?? [];
997
+ slot.set({
998
+ id: request.operationId,
999
+ attemptId: request.attemptId,
1000
+ status: "running",
1001
+ calls,
1002
+ asks: previous.asks,
1003
+ interrupted: previous.interrupted,
1004
+ retries: previous.retries,
1005
+ });
1006
+ await save();
1007
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
1008
+ try {
1009
+ await beforeTool(request);
1010
+ await requests.recheck(request);
1011
+ active();
1012
+ if (previous.status === "pending" && previous.previousAttemptId)
1013
+ restart("tool", request.operationId, previous.previousAttemptId, request.attemptId);
1014
+ emit({ type: "tool_start", request });
1015
+ await requests.recheck(request);
1016
+ await requests.assertFresh();
1017
+ active();
1018
+ }
1019
+ catch (error) {
1020
+ if (error instanceof Halt && error.state.status === "suspended")
1021
+ slot.set({ ...previous, asks: slot.get().asks });
1022
+ throw error;
1023
+ }
1024
+ const end = new AbortController();
1025
+ const programSignal = AbortSignal.any([signal, end.signal]);
1026
+ const programDeadline = Math.min(Date.now() + code.limits.timeoutMs, deadline, snapshot.tree.startedAt + snapshot.tree.limits.elapsedMs);
1027
+ const timer = setTimeout(() => end.abort(new Error("The program reached its time limit.")), Math.max(0, programDeadline - Date.now()));
1028
+ const enabled = code.tools.filter((tool) => snapshot.definition.enabledTools.includes(tool.name));
1029
+ const gate = createGate(limits.parallelTools);
1030
+ const jobs = [];
1031
+ let barrier = Promise.resolve();
1032
+ let settled = Promise.resolve();
1033
+ let fatal;
1034
+ let closed = false;
1035
+ const reject = (kind, message) => JSON.stringify({ ok: false, error: { kind, message } });
1036
+ const stopped = (call) => ({
1037
+ ok: false,
1038
+ kind: "aborted",
1039
+ content: call.started
1040
+ ? "The program stopped. This call may have partly run. Check its effect before repeating it."
1041
+ : "The program stopped before this call started. It did not run.",
1042
+ });
1043
+ const count = () => calls
1044
+ .filter((call) => call.programAttemptId === request.attemptId)
1045
+ .reduce((total, call) => total + 1 + call.retries.length, 0);
1046
+ const bridge = {
1047
+ tools: enabled,
1048
+ signal: programSignal,
1049
+ deadline: programDeadline,
1050
+ calls,
1051
+ toolCallsLeft: () => Math.max(0, Math.min(code.limits.calls - count(), limits.toolCalls - usedTools() - 1)),
1052
+ call(name, input) {
1053
+ if (closed || programSignal.aborted)
1054
+ return Promise.resolve(reject("aborted", "The program has finished. No more calls can start."));
1055
+ const tool = enabled.find((tool) => tool.name === name);
1056
+ if (!tool)
1057
+ return Promise.resolve(reject("disabled_tool", "This tool is not bound and enabled for this program."));
1058
+ if (tool.needsApproval || tool.isTerminal)
1059
+ return Promise.resolve(reject("denied", "This control tool must be called directly, outside code."));
1060
+ const arguments_ = typeof input === "string" && textBytes(input) <= code.limits.callInputBytes
1061
+ ? jsonArguments(input)
1062
+ : undefined;
1063
+ if (!arguments_)
1064
+ return Promise.resolve(reject("invalid_input", `Pass one JSON object within ${code.limits.callInputBytes} bytes.`));
1065
+ if (bridge.toolCallsLeft() === 0)
1066
+ return Promise.resolve(reject("denied", "The program has no tool calls left. Return what you have; the final direct call is reserved."));
1067
+ // Admission and budget reservation are synchronous. Promise.all cannot overspend.
1068
+ const position = calls.length;
1069
+ const operationId = `${request.operationId}/call/${position + 1}`;
1070
+ let call = {
1071
+ id: operationId,
1072
+ attemptId: request.attemptId,
1073
+ programAttemptId: request.attemptId,
1074
+ name,
1075
+ arguments: arguments_,
1076
+ status: "pending",
1077
+ started: false,
1078
+ interrupted: [],
1079
+ retries: [],
1080
+ };
1081
+ calls.push(call);
1082
+ let reply = reject("aborted", "The call did not finish.");
1083
+ const inner = {
1084
+ get: () => call,
1085
+ set(execution) {
1086
+ if (execution.status === "delegating" || execution.calls !== undefined)
1087
+ throw new TypeError("A program may only call ordinary tools.");
1088
+ call = {
1089
+ ...execution,
1090
+ name,
1091
+ arguments: arguments_,
1092
+ programAttemptId: request.attemptId,
1093
+ attemptId: execution.status === "pending"
1094
+ ? `${request.attemptId}/call/${position + 1}/attempt/${execution.retries.length + 1}`
1095
+ : execution.attemptId,
1096
+ started: call.started,
1097
+ bytes: execution.status === "pending" ? undefined : call.bytes,
1098
+ };
1099
+ calls[position] = call;
1100
+ },
1101
+ request: () => ({
1102
+ agentId: id,
1103
+ version,
1104
+ runId: snapshot.runId,
1105
+ attemptId: call.status === "pending" && call.retries.length
1106
+ ? `${request.attemptId}/call/${position + 1}/attempt/${call.retries.length + 1}`
1107
+ : call.attemptId,
1108
+ operationId,
1109
+ parentOperationId: request.operationId,
1110
+ ...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
1111
+ call: { id: operationId, name, arguments: input },
1112
+ arguments: copyData(arguments_),
1113
+ }),
1114
+ inner: {
1115
+ signal: programSignal,
1116
+ code,
1117
+ callsLeft: () => bridge.toolCallsLeft(),
1118
+ start() {
1119
+ call = {
1120
+ id: call.id,
1121
+ name,
1122
+ arguments: arguments_,
1123
+ programAttemptId: request.attemptId,
1124
+ interrupted: call.interrupted,
1125
+ retries: call.retries,
1126
+ asks: call.asks,
1127
+ status: "running",
1128
+ attemptId: inner.request().attemptId,
1129
+ started: true,
1130
+ };
1131
+ calls[position] = call;
1132
+ },
1133
+ record(result) {
1134
+ const receipt = programReceipt(result);
1135
+ call.bytes = receipt.bytes;
1136
+ reply = inner.inner?.outputError
1137
+ ? reject("invalid_output", inner.inner.outputError)
1138
+ : programReply(result, code.limits.callOutputBytes);
1139
+ return receipt.result;
1140
+ },
1141
+ },
1142
+ };
1143
+ let concurrent = false;
1144
+ const work = (async () => {
1145
+ let releaseCall = () => { };
1146
+ try {
1147
+ // Synchronous admission is host work too: a throw must settle its pending call.
1148
+ concurrent = canParallel(inner.request(), tool, call);
1149
+ await (concurrent ? barrier : settled);
1150
+ releaseCall = await gate.acquire(programSignal);
1151
+ do {
1152
+ invocationActive(inner);
1153
+ let effective = inner.request();
1154
+ const journal = requestsFor(effective, call, options, scope, programSignal);
1155
+ if (await needsApproval(effective, options, programSignal)) {
1156
+ let refusal;
1157
+ if (!host?.prepareRequest || !host.beforeTool)
1158
+ refusal = {
1159
+ ok: false,
1160
+ kind: "denied",
1161
+ content: "This call needs a person's approval, and code cannot wait for one.",
1162
+ };
1163
+ else {
1164
+ const record = await journal.ensure({ type: "approval" });
1165
+ const decision = record.decision;
1166
+ if (decision?.type === "approve") {
1167
+ if (decision.arguments !== undefined)
1168
+ effective = { ...effective, arguments: copyData(decision.arguments) };
1169
+ }
1170
+ else {
1171
+ if (!record.decision)
1172
+ record.closed = "stopped";
1173
+ refusal = {
1174
+ ok: false,
1175
+ kind: decision?.type === "cancel" ? "cancelled" : "denied",
1176
+ content: decision?.type === "deny"
1177
+ ? (decision.message ?? "The person denied this call.")
1178
+ : "This call needs a person's approval, and code cannot wait for one.",
1179
+ };
1180
+ }
1181
+ }
1182
+ if (refusal) {
1183
+ if (directNames.includes(name))
1184
+ refusal.content += ` Call ${name} directly.`;
1185
+ await finishExecution(inner, effective, refusal);
1186
+ break;
1187
+ }
1188
+ }
1189
+ if (textBytes(programJson(effective.arguments)) > code.limits.callInputBytes) {
1190
+ await finishExecution(inner, effective, {
1191
+ ok: false,
1192
+ kind: "invalid_input",
1193
+ content: `The approved arguments exceed ${code.limits.callInputBytes} bytes. Send less data.`,
1194
+ });
1195
+ break;
1196
+ }
1197
+ if (call.status === "pending" && call.previousAttemptId) {
1198
+ emit({
1199
+ type: "operation_restart",
1200
+ kind: "tool",
1201
+ runId: snapshot.runId,
1202
+ operationId,
1203
+ parentOperationId: request.operationId,
1204
+ previousAttemptId: call.previousAttemptId,
1205
+ attemptId: effective.attemptId,
1206
+ });
1207
+ }
1208
+ await withToolError(effective, () => runTool(inner, effective, tool, concurrent), programSignal);
1209
+ if (count() >= code.limits.calls || programSignal.aborted)
1210
+ break;
1211
+ } while (await retryTool(inner));
1212
+ return reply;
1213
+ }
1214
+ catch (error) {
1215
+ // A host/guard/checkpoint error stops the run, not merely one guest call.
1216
+ if (!programSignal.aborted &&
1217
+ !(error instanceof Halt && error.state.status === "suspended")) {
1218
+ fatal ??= error;
1219
+ end.abort(error);
1220
+ }
1221
+ for (const ask of call.asks ?? [])
1222
+ if (!ask.closed && !ask.decision)
1223
+ ask.closed = "stopped";
1224
+ if (!programSignal.aborted &&
1225
+ error instanceof Halt &&
1226
+ error.state.status === "suspended") {
1227
+ const result = {
1228
+ ok: false,
1229
+ kind: "denied",
1230
+ content: "The approval expired. Code cannot wait for a new decision. Call this tool directly.",
1231
+ };
1232
+ await finishExecution(inner, inner.request(), result);
1233
+ return programReply(result, code.limits.callOutputBytes);
1234
+ }
1235
+ if (inner.get().status !== "completed") {
1236
+ const result = stopped(call);
1237
+ inner.set({
1238
+ id: operationId,
1239
+ attemptId: call.attemptId,
1240
+ status: "completed",
1241
+ interrupted: call.interrupted,
1242
+ retries: call.retries,
1243
+ asks: call.asks,
1244
+ result: programReceipt(result).result,
1245
+ });
1246
+ await save();
1247
+ if (!guardPolicy?.stages.includes("toolOutput"))
1248
+ emit({ type: "tool_result", request: inner.request(), result });
1249
+ }
1250
+ return reject("aborted", "The call stopped. Check its saved receipt before repeating it.");
1251
+ }
1252
+ finally {
1253
+ releaseCall();
1254
+ }
1255
+ })();
1256
+ const done = work.then(() => { }, () => { });
1257
+ settled = Promise.all([settled, done]).then(() => { });
1258
+ if (!concurrent)
1259
+ barrier = settled;
1260
+ jobs.push(work);
1261
+ return work.catch((error) => {
1262
+ fatal ??= error;
1263
+ end.abort(error);
1264
+ return reject("aborted", "The host could not record the call. Stop and reconcile its effect.");
1265
+ });
1266
+ },
1267
+ async settle() {
1268
+ closed = true;
1269
+ end.abort(new Error("The program has finished."));
1270
+ await Promise.allSettled(jobs);
1271
+ clearTimeout(timer);
1272
+ if (fatal)
1273
+ throw fatal;
1274
+ // A deadline may interrupt a guard after an effect returned. Never turn its
1275
+ // unfinished verdict into a successful program or buy another model turn.
1276
+ requireGuardVerdicts(snapshot);
1277
+ },
1278
+ };
1279
+ const outcome = await code.execute(completeArguments(request.call.arguments) ? request.arguments : undefined, bridge);
1280
+ await finishTool(model, index, request, outcome.result);
241
1281
  active();
242
1282
  }
243
1283
  async function runDelegation(model, index, request, descriptor) {
244
1284
  let journal = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
245
1285
  if (!journal) {
246
- journal = { operationId: request.operationId, children: [] };
1286
+ journal = { kind: "delegation", operationId: request.operationId, children: [] };
247
1287
  snapshot.delegations.push(journal);
248
1288
  }
1289
+ if (journal.kind === "handoff") {
1290
+ try {
1291
+ const note = handoffNote(request.arguments);
1292
+ if (journal.children.length > 0 && note !== journal.note)
1293
+ throw new TypeError("The transfer note changed after the target started.");
1294
+ journal.note = note;
1295
+ }
1296
+ catch (error) {
1297
+ if (journal.children.length > 0)
1298
+ fail("handoff_input_changed", "The target already started. Its transfer arguments cannot change. Reconcile the saved run before starting different work.", request.operationId);
1299
+ await finishTool(model, index, request, {
1300
+ ok: false,
1301
+ kind: "invalid_input",
1302
+ content: messageOf(error),
1303
+ });
1304
+ return;
1305
+ }
1306
+ }
249
1307
  model.tools[index] = {
1308
+ interrupted: model.tools[index]?.interrupted ?? [],
1309
+ retries: model.tools[index]?.retries ?? [],
1310
+ asks: model.tools[index]?.asks,
250
1311
  id: request.operationId,
251
- attemptId: snapshot.attemptId,
1312
+ attemptId: request.attemptId,
252
1313
  status: "delegating",
253
1314
  };
254
1315
  await save();
@@ -261,16 +1322,22 @@ export function defineAgent(definition) {
261
1322
  });
262
1323
  return;
263
1324
  }
264
- await untilAbort(Promise.resolve(host?.beforeTool?.(immutableCopy(request))), signal);
1325
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
1326
+ refuseGuardedReplay(snapshot, request.operationId);
1327
+ await beforeTool(request);
1328
+ await requests.recheck(request);
265
1329
  active();
266
1330
  emit({ type: "tool_start", request });
267
1331
  active();
1332
+ await requests.recheck(request);
1333
+ await requests.assertFresh();
1334
+ active();
268
1335
  // Coordination is pure and is the only place children can start. Lend once
269
1336
  // for this entire barrier, including ignored children and overlapping joins.
270
1337
  release();
271
1338
  let result;
272
1339
  try {
273
- result = await executeDelegation(descriptor, journal, snapshot, request.arguments, options, scope, signal, active, evidence);
1340
+ result = await executeDelegation(descriptor, journal, snapshot, request.arguments, options, scope, signal, active, requests);
274
1341
  }
275
1342
  finally {
276
1343
  release = await scope.tree.gate.acquire(signal);
@@ -278,6 +1345,76 @@ export function defineAgent(definition) {
278
1345
  active();
279
1346
  await finishTool(model, index, request, result);
280
1347
  }
1348
+ async function openApprovals(model, from) {
1349
+ for (let index = from; index < model.tools.length; index++) {
1350
+ const execution = model.tools[index];
1351
+ if (!execution || execution.status === "completed")
1352
+ continue;
1353
+ if (usedTools() >= limits.toolCalls && !execution.asks?.length)
1354
+ break;
1355
+ const request = requestFor(snapshot, model, index);
1356
+ const tool = tools.find((tool) => tool.name === request.call.name);
1357
+ if (!tool ||
1358
+ request.call.name === RESULT_TOOL_NAME ||
1359
+ !snapshot.definition.enabledTools.includes(tool.name) ||
1360
+ snapshot.definition.modelSettings.toolChoice === "none" ||
1361
+ !completeArguments(request.call.arguments) ||
1362
+ (isHandoff(tool) && model.tools.length !== 1) ||
1363
+ (!isDelegation(tool) &&
1364
+ !isHandoff(tool) &&
1365
+ !isClientTool(tool) &&
1366
+ !isCodeTool(tool) &&
1367
+ tool.isTerminal &&
1368
+ model.tools.length !== 1))
1369
+ continue;
1370
+ if (await needsApproval(request, options, signal))
1371
+ await journalFor(snapshot, model, index, options, scope, signal).ensure({
1372
+ type: "approval",
1373
+ });
1374
+ }
1375
+ }
1376
+ async function runClient(model, index, request, client) {
1377
+ try {
1378
+ if (!completeArguments(request.call.arguments))
1379
+ throw new TypeError("Send one complete JSON object.");
1380
+ client.validateArguments(request.arguments);
1381
+ }
1382
+ catch (error) {
1383
+ await finishTool(model, index, request, {
1384
+ ok: false,
1385
+ kind: "invalid_input",
1386
+ content: messageOf(error),
1387
+ });
1388
+ return;
1389
+ }
1390
+ if (!host?.beforeTool)
1391
+ fail("request_host_missing", "Provide host.beforeTool before dispatching a client tool.");
1392
+ const requests = journalFor(snapshot, model, index, options, scope, signal, request);
1393
+ refuseGuardedReplay(snapshot, request.operationId);
1394
+ await beforeTool(request);
1395
+ await requests.recheck(request);
1396
+ const record = await requests.ensure({ type: "client", resultSchema: client.resultSchema });
1397
+ if (!record.decision)
1398
+ return;
1399
+ if (record.decision.type === "stop") {
1400
+ scope.tree.stop();
1401
+ throw new Halt({ status: "cancelled" });
1402
+ }
1403
+ if (record.decision.type === "cancel") {
1404
+ await finishTool(model, index, request, {
1405
+ ok: false,
1406
+ kind: "cancelled",
1407
+ content: "The person cancelled this client request. This does not undo an action already taken.",
1408
+ });
1409
+ return;
1410
+ }
1411
+ if (record.decision.type !== "result")
1412
+ throw new TypeError("A client request needs a result.");
1413
+ await requests.recheck(request);
1414
+ active();
1415
+ const result = client.result(record.decision.value);
1416
+ await finishTool(model, index, request, successfulToolResult(result));
1417
+ }
281
1418
  async function handleTurn(model) {
282
1419
  active();
283
1420
  const { message, finishReason } = model.turn;
@@ -296,99 +1433,432 @@ export function defineAgent(definition) {
296
1433
  snapshot.state = { status: "completed", candidate: message.content };
297
1434
  return;
298
1435
  }
1436
+ // The one extra call at the local turn limit has no tools, even if a provider ignores
1437
+ // toolChoice. Never execute calls it returns. The shared tree limit remains a hard cap.
1438
+ if (snapshot.models.indexOf(model) >= limits.turns)
1439
+ throw new Halt({ status: "limited", limit: "turns" });
299
1440
  for (let index = 0; index < calls.length;) {
300
- if (model.tools[index]?.status === "completed") {
1441
+ if (model.tools[index]?.status === "completed" &&
1442
+ !(await retryTool(slotFor(model, index)))) {
301
1443
  index++;
302
1444
  continue;
303
1445
  }
304
1446
  active();
305
1447
  const capacity = limits.toolCalls - usedTools();
306
- if (capacity <= 0 && model.tools[index]?.status === "pending")
1448
+ if (capacity <= 0 &&
1449
+ model.tools[index]?.status === "pending" &&
1450
+ !model.tools[index]?.asks?.length)
307
1451
  throw new Halt({ status: "limited", limit: "toolCalls" });
308
- const request = requestFor(model, index);
309
- const descriptor = delegations.get(request.call.name);
310
- if (descriptor) {
311
- await runDelegation(model, index, request, descriptor);
1452
+ let request = requestFor(snapshot, model, index);
1453
+ if (model.tools[index]?.retries.length)
1454
+ await checkToolRetry(slotFor(model, index));
1455
+ if (!directNames.includes(request.call.name) ||
1456
+ !snapshot.definition.enabledTools.includes(request.call.name) ||
1457
+ snapshot.definition.modelSettings.toolChoice === "none") {
1458
+ await finishTool(model, index, request, {
1459
+ ok: false,
1460
+ kind: names.includes(request.call.name) ? "disabled_tool" : "unknown_tool",
1461
+ content: "This tool is not available in this run. Choose one of the provided tools.",
1462
+ });
312
1463
  index++;
313
1464
  continue;
314
1465
  }
1466
+ const handoff = handoffs.get(request.call.name);
1467
+ if (handoff &&
1468
+ !snapshot.delegations.some((entry) => entry.operationId === request.operationId)) {
1469
+ let target;
1470
+ let note;
1471
+ try {
1472
+ if (calls.length !== 1)
1473
+ throw new TypeError(`Call ${handoff.name} alone, after the other tool results arrive.`);
1474
+ if (!completeArguments(request.call.arguments))
1475
+ throw new TypeError("Tool arguments must be one complete JSON object. Send the full object again.");
1476
+ note = handoffNote(request.arguments);
1477
+ target = handoff.target();
1478
+ if (target.id === id)
1479
+ throw new TypeError("This agent already owns the conversation. Choose a different target.");
1480
+ checkHandoffTargets(agent);
1481
+ }
1482
+ catch (error) {
1483
+ await finishTool(model, index, request, {
1484
+ ok: false,
1485
+ kind: "invalid_input",
1486
+ content: messageOf(error),
1487
+ });
1488
+ index++;
1489
+ continue;
1490
+ }
1491
+ // Pin identity before asking for permission. A resumed lazy reference cannot turn
1492
+ // an approval for one target into a transfer to another.
1493
+ snapshot.delegations.push({
1494
+ kind: "handoff",
1495
+ operationId: request.operationId,
1496
+ target: handoffRef(target),
1497
+ ...(note !== undefined ? { note } : {}),
1498
+ children: [],
1499
+ });
1500
+ model.tools[index] = {
1501
+ id: request.operationId,
1502
+ status: "delegating",
1503
+ attemptId: snapshot.attemptId,
1504
+ interrupted: [],
1505
+ retries: [],
1506
+ };
1507
+ await save();
1508
+ active();
1509
+ }
1510
+ const descriptor = descriptorFor(request.call.name, snapshot, request.operationId);
315
1511
  const tool = registry.get(request.call.name);
316
- if (tool?.needsApproval &&
1512
+ const client = clients.get(request.call.name);
1513
+ const code = codeTools.get(request.call.name);
1514
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
1515
+ if ((tool || descriptor || client || code) &&
317
1516
  completeArguments(request.call.arguments) &&
318
- approved?.request.operationId !== request.operationId) {
319
- if (!host?.approvalContext)
320
- fail("approval_host_missing", "Provide host.approvalContext to request approval for this tool.", request.operationId);
321
- const scope = copyData(await untilAbort(Promise.resolve(host.approvalContext(immutableCopy(request))), signal));
322
- active();
323
- if (!isScope(scope) || scope.expiresAt <= Date.now())
324
- fail("invalid_approval_scope", "The host must supply an actor, resource version and future approval expiry.", request.operationId);
325
- snapshot.state = {
326
- status: "suspended",
327
- approval: { request: copyData(request), scope },
328
- path: [],
329
- };
1517
+ (!tool?.isTerminal || model.tools.length === 1) &&
1518
+ (await needsApproval(request, options, signal)))
1519
+ await requests.ensure({ type: "approval" });
1520
+ const records = model.tools[index]?.asks ?? [];
1521
+ if (records.some((record) => !record.closed && record.decision?.type === "stop")) {
1522
+ scope.tree.stop();
1523
+ throw new Halt({ status: "cancelled" });
1524
+ }
1525
+ const decline = records.find((record) => !record.closed &&
1526
+ (record.decision?.type === "deny" || record.decision?.type === "cancel"));
1527
+ if (decline?.decision) {
1528
+ await finishTool(model, index, request, decline.decision.type === "deny"
1529
+ ? {
1530
+ ok: false,
1531
+ kind: "denied",
1532
+ content: decline.decision.message ??
1533
+ "The person denied this call. Continue without this action.",
1534
+ }
1535
+ : {
1536
+ ok: false,
1537
+ kind: "cancelled",
1538
+ content: "The person cancelled this request. Continue without this action.",
1539
+ });
1540
+ index++;
1541
+ continue;
1542
+ }
1543
+ if (records.some((record) => !record.closed && !record.decision)) {
1544
+ await openApprovals(model, index + 1);
1545
+ snapshot.state = { status: "suspended" };
330
1546
  return;
331
1547
  }
332
- const batch = [{ index, request, tool }];
333
- const parallel = (request, tool) => tool?.isConcurrencySafe === true &&
334
- !tool.needsApproval &&
335
- !tool.isTerminal &&
336
- host?.canRunConcurrently?.(immutableCopy(request)) === true;
1548
+ const approval = requests.latest({ type: "approval" })?.decision;
1549
+ if (approval?.type === "approve" && approval.arguments !== undefined)
1550
+ request = { ...request, arguments: copyData(approval.arguments) };
1551
+ if (code) {
1552
+ await withToolError(request, () => runProgram(model, index, request, code));
1553
+ index++;
1554
+ continue;
1555
+ }
1556
+ if (descriptor) {
1557
+ await withToolError(request, () => runDelegation(model, index, request, descriptor));
1558
+ index++;
1559
+ continue;
1560
+ }
1561
+ if (client) {
1562
+ await withToolError(request, () => runClient(model, index, request, client));
1563
+ if (model.tools[index]?.status !== "completed") {
1564
+ await openApprovals(model, index + 1);
1565
+ snapshot.state = { status: "suspended" };
1566
+ return;
1567
+ }
1568
+ index++;
1569
+ continue;
1570
+ }
1571
+ const execution = model.tools[index];
1572
+ const batch = [
1573
+ {
1574
+ index,
1575
+ request,
1576
+ tool,
1577
+ previousAttemptId: execution?.status === "pending" ? execution.previousAttemptId : undefined,
1578
+ },
1579
+ ];
1580
+ const parallel = (request, tool) => canParallel(request, tool, slotFor(model, model.tools.findIndex((entry) => entry.id === request.operationId)).get());
337
1581
  const concurrent = parallel(request, tool);
338
1582
  if (concurrent) {
339
1583
  for (let next = index + 1; next < calls.length && batch.length < Math.min(limits.parallelTools, capacity); next++) {
340
- if (model.tools[next]?.status !== "pending")
1584
+ const execution = model.tools[next];
1585
+ if (execution?.status !== "pending")
341
1586
  break;
342
- const nextRequest = requestFor(model, next);
1587
+ const nextRequest = requestFor(snapshot, model, next);
343
1588
  const nextTool = registry.get(nextRequest.call.name);
344
1589
  if (!parallel(nextRequest, nextTool))
345
1590
  break;
346
- batch.push({ index: next, request: nextRequest, tool: nextTool });
1591
+ batch.push({
1592
+ index: next,
1593
+ request: nextRequest,
1594
+ tool: nextTool,
1595
+ previousAttemptId: execution.previousAttemptId,
1596
+ });
347
1597
  }
348
1598
  }
1599
+ // A checkpoint can capture the pending retry while another child saves. Check its
1600
+ // identity again before admission, even if this worker did not perform the reset.
1601
+ for (const job of batch) {
1602
+ const execution = model.tools[job.index];
1603
+ if (execution?.interrupted.length && !execution.asks?.length)
1604
+ await checkToolRecovery(model, job.index, execution.interrupted.length + execution.retries.length - 1);
1605
+ }
349
1606
  active();
350
1607
  // Reserve the whole admitted batch before any invocation, including its tool-call budget.
351
1608
  for (const job of batch)
352
1609
  model.tools[job.index] = {
1610
+ interrupted: model.tools[job.index]?.interrupted ?? [],
1611
+ retries: model.tools[job.index]?.retries ?? [],
1612
+ asks: model.tools[job.index]?.asks,
353
1613
  id: job.request.operationId,
354
- attemptId: snapshot.attemptId,
1614
+ attemptId: job.request.attemptId,
355
1615
  status: "running",
356
1616
  };
357
1617
  await save();
358
- const settled = await Promise.allSettled(batch.map((job) => runTool(model, job.index, job.request, job.tool, concurrent)));
1618
+ const settled = await Promise.allSettled(batch.map((job) => {
1619
+ // Retry and recovery histories can interleave. Use the predecessor saved when
1620
+ // this replacement was scheduled, not the tail of either history alone.
1621
+ if (job.previousAttemptId)
1622
+ restart("tool", job.request.operationId, job.previousAttemptId, job.request.attemptId);
1623
+ return withToolError(job.request, () => runTool(slotFor(model, job.index), job.request, job.tool, concurrent));
1624
+ }));
359
1625
  const rejected = settled.find((result) => result.status === "rejected");
360
1626
  if (rejected?.status === "rejected")
361
1627
  throw rejected.reason;
362
- approved = undefined;
363
- index += batch.length;
1628
+ if (batch.some((job) => model.tools[job.index]?.status === "pending")) {
1629
+ if (batch.some((job) => model.tools[job.index]?.asks?.some((record) => !record.closed && !record.decision))) {
1630
+ await openApprovals(model, index + batch.length);
1631
+ snapshot.state = { status: "suspended" };
1632
+ return;
1633
+ }
1634
+ continue;
1635
+ }
1636
+ // Retrying tools run serially. Revisit their settled failure through the same
1637
+ // admission path; ordinary batches advance as before.
1638
+ if (!retryBudget(snapshot.definition.toolRetries, request.call.name))
1639
+ index += batch.length;
1640
+ }
1641
+ // Adapted from OpenAI Agents JS (MIT), runner/toolExecution.ts: settle this batch,
1642
+ // then select the first stopping tool in model order, not completion order.
1643
+ const final = finalHandoffResult(snapshot, model) ??
1644
+ finalToolResult(model, snapshot.definition.stopAtTools, output ? RESULT_TOOL_NAME : undefined);
1645
+ if (final)
1646
+ snapshot.state = { status: "completed", candidate: final.candidate };
1647
+ }
1648
+ // One load per media id per attempt. The bytes live only in the requests built from it,
1649
+ // never in the journal, the outcome or an event. The per-run cache of pending loads is
1650
+ // adapted from TanStack AI (MIT), packages/ai-harness/src/media.ts.
1651
+ const media = new Map();
1652
+ function loadMedia(ref) {
1653
+ let loaded = media.get(ref.id);
1654
+ if (!loaded) {
1655
+ loaded = readMedia(ref);
1656
+ media.set(ref.id, loaded);
364
1657
  }
365
- const terminal = model.tools[0];
366
- if (output &&
367
- calls.length === 1 &&
368
- calls[0]?.name === RESULT_TOOL_NAME &&
369
- terminal?.status === "completed" &&
370
- terminal.result.ok) {
371
- snapshot.state = { status: "completed", candidate: parseToolArgs(calls[0].arguments) };
1658
+ return loaded;
1659
+ }
1660
+ async function readMedia(ref) {
1661
+ const load = host?.loadMedia;
1662
+ if (!load)
1663
+ fail("media_unavailable", "This run has media references. Provide host.loadMedia to read their bytes.");
1664
+ let data;
1665
+ try {
1666
+ data = await untilAbort(Promise.resolve(load(immutableCopy(ref), { runId: snapshot.runId, signal })), signal);
1667
+ }
1668
+ catch {
1669
+ active();
1670
+ // Loader errors can quote credentials from a header or request. Never persist them.
1671
+ fail("media_unavailable", "The media could not be loaded. Check file access before trying again.");
372
1672
  }
1673
+ if (!isBase64(data))
1674
+ fail("media_unavailable", `host.loadMedia returned no base64 bytes for media ${ref.id}. Return the bytes as padded base64 text.`);
1675
+ return data;
373
1676
  }
374
- async function nextTurn() {
1677
+ async function compact() {
1678
+ const last = snapshot.compactions.at(-1);
1679
+ if (last?.status === "running")
1680
+ fail("interrupted_compaction", "The summary has no saved result and may have been billed. Reconcile it with the host before continuing.", last.id);
1681
+ const plan = compactionPlan(snapshot);
1682
+ if (!plan)
1683
+ return;
1684
+ const { removed, ...position } = plan;
1685
+ const index = snapshot.compactions.length;
1686
+ const entry = {
1687
+ id: compactionId(snapshot.runId, index),
1688
+ beforeModel: snapshot.models.length,
1689
+ ...position,
1690
+ status: "running",
1691
+ };
1692
+ const summary = snapshot.definition.compaction?.summarize;
1693
+ if (!summary) {
1694
+ snapshot.compactions.push({
1695
+ ...entry,
1696
+ status: "completed",
1697
+ summary: "Earlier messages were omitted. No summary was generated.",
1698
+ });
1699
+ await save();
1700
+ return;
1701
+ }
1702
+ if (!summarizer)
1703
+ fail("invalid_journal", "The recorded summary provider is missing.");
1704
+ // A separate receipt freezes this cut before any paid work. A crash, even before
1705
+ // dispatch, fails closed instead of silently purchasing the same summary twice.
1706
+ snapshot.compactions.push(entry);
1707
+ await save();
375
1708
  active();
376
- if (snapshot.models.length >= limits.turns)
1709
+ const messages = await requestOf(summary.instructions, removed, loadMedia);
1710
+ await callModel(entry.id, {
1711
+ messages,
1712
+ tools: [],
1713
+ settings: {
1714
+ maxTokens: summary.maxTokens,
1715
+ maxAttempts: 1,
1716
+ toolChoice: "none",
1717
+ hostedTools: [],
1718
+ },
1719
+ }, summarizer, (model) => {
1720
+ if (model.status === "completed") {
1721
+ if (model.turn.finishReason !== "stop" ||
1722
+ !model.turn.message.content.trim() ||
1723
+ model.tools.length ||
1724
+ model.turn.message.hostedCalls?.length ||
1725
+ model.turn.message.hostedItems)
1726
+ fail("invalid_compaction", "The summary must be complete text without tool calls. Check the summary provider before starting new work.", entry.id);
1727
+ snapshot.compactions[index] = {
1728
+ ...entry,
1729
+ model,
1730
+ status: "completed",
1731
+ summary: model.turn.message.content,
1732
+ };
1733
+ }
1734
+ else
1735
+ entry.model = model;
1736
+ }, undefined, true);
1737
+ }
1738
+ async function nextTurn(previous) {
1739
+ active();
1740
+ // Hosted actions may run before any local tool call appears. Their explicit presence
1741
+ // overrides a profile's inference-only claim when an interrupted call is recovered.
1742
+ if (previous) {
1743
+ refuseGuardedReplay(snapshot, previous.id);
1744
+ requireRecovery(snapshot.definition.recovery?.policy.inferenceOnly === true &&
1745
+ !snapshot.definition.modelSettings.hostedTools?.length, previous.interrupted.length, snapshot.definition.recovery, previous.id);
1746
+ }
1747
+ const position = previous ? snapshot.models.indexOf(previous) : snapshot.models.length;
1748
+ const selected = definitionsFor(snapshot.definition.enabledTools);
1749
+ if (previous &&
1750
+ (await requestHash(selected)) !== snapshot.definition.recovery?.modelToolsHash)
1751
+ fail("recovery_definition_changed", "The interrupted model call's tool definitions changed. Restore the same definitions or reconcile the run.", previous.id);
1752
+ // Ported from Microsoft Agent Framework (MIT), _tools.py: after the iteration
1753
+ // allowance, ask once for a tool-free answer. Checked output needs submit_result,
1754
+ // so that mode retains the hard local turn cap instead of buying an unusable call.
1755
+ const finalTurn = position === limits.turns;
1756
+ if (position > limits.turns || (finalTurn && output))
377
1757
  throw new Halt({ status: "limited", limit: "turns" });
1758
+ // A steer never changes the input of an already admitted call, including safe replay.
1759
+ // Check capacity before polling so a spent budget leaves delivery queued in the host.
1760
+ scope.tree.reserveModel();
1761
+ if (!previous) {
1762
+ await acceptInputs(snapshot, scope, options, signal);
1763
+ await compact();
1764
+ }
1765
+ active();
1766
+ // Media is read before the receipt below exists, so a missing loader or file fails the
1767
+ // run with no model operation left running and nothing to reconcile.
1768
+ const request = await requestOf(snapshot.definition.instructions, withMemoryRecall(snapshot, modelConversation(snapshot)), loadMedia);
1769
+ active();
1770
+ const modelSettings = copyData(snapshot.definition.modelSettings);
1771
+ // Ported from OpenAI Agents JS (MIT), runner/modelSettings.ts, maybeResetToolChoice.
1772
+ // Derive usage from the journal so resume cannot force the first tool a second time.
1773
+ const choice = modelSettings.toolChoice;
1774
+ if ((choice === "required" || typeof choice === "object") &&
1775
+ snapshot.models.some((model) => model.status === "completed" && model.tools.length > 0))
1776
+ modelSettings.toolChoice = "auto";
1777
+ if (finalTurn)
1778
+ modelSettings.toolChoice = "none";
1779
+ const operationId = modelId(snapshot.runId, position);
1780
+ const modelInput = {
1781
+ messages: request,
1782
+ tools: finalTurn ? [] : copyData(selected),
1783
+ settings: modelSettings,
1784
+ };
1785
+ const done = await callModel(operationId, modelInput, provider, (model) => {
1786
+ snapshot.models[position] = model;
1787
+ }, previous);
1788
+ for (const receipt of inputReceipts(snapshot).filter((receipt) => receipt.modelId === done.id))
1789
+ emit({ type: "input", receipt });
1790
+ await acknowledgeInputs(snapshot, options, signal);
1791
+ return done;
1792
+ }
1793
+ // Both ordinary turns and explicit summaries use the same admission, guards, usage
1794
+ // checkpoints and collection path. Summaries stay private and never dispatch tools.
1795
+ async function callModel(operationId, modelInput, selectedProvider, record, previous, summary = false) {
1796
+ const { messages: request, settings: modelSettings } = modelInput;
1797
+ await guards.check("modelInput", operationId, snapshot.attemptId, modelInput);
1798
+ await observe({
1799
+ type: "model_start",
1800
+ operationId,
1801
+ attemptId: snapshot.attemptId,
1802
+ input: modelInput,
1803
+ });
1804
+ active();
1805
+ // The tree check and the receipt stay together, with no await between them, so two
1806
+ // children racing for the tree's last model call cannot both take it.
378
1807
  scope.tree.reserveModel();
379
1808
  const model = {
380
- id: modelId(snapshot.runId, snapshot.models.length),
1809
+ id: operationId,
381
1810
  attemptId: snapshot.attemptId,
382
1811
  status: "running",
1812
+ billing: "unknown",
383
1813
  usage: { ...EMPTY_USAGE },
1814
+ interrupted: previous
1815
+ ? [
1816
+ ...previous.interrupted,
1817
+ { attemptId: previous.attemptId, usage: copyData(previous.usage) },
1818
+ ]
1819
+ : [],
384
1820
  };
385
- snapshot.models.push(model);
1821
+ record(model);
386
1822
  await save();
1823
+ if (previous)
1824
+ restart("model", model.id, previous.attemptId);
387
1825
  active();
1826
+ let reportedUsage = false;
1827
+ let bufferedChunks = 0;
1828
+ let bufferedBytes = 0;
1829
+ const guarded = !!guardrails?.modelOutput;
388
1830
  async function* observed() {
389
- const stream = provider.createStream(historyOf(snapshot, instructions), copyData(tools.map((tool) => tool.definition())), {
1831
+ let dispatchProvider = selectedProvider;
1832
+ if (options.bindModelProvider) {
1833
+ try {
1834
+ const bound = options.bindModelProvider(selectedProvider, Object.freeze({
1835
+ run: callbackContext,
1836
+ operationId: model.id,
1837
+ operationAttemptId: model.attemptId,
1838
+ purpose: summary ? "compaction" : "turn",
1839
+ }));
1840
+ if (bound && typeof bound.createStream === "function")
1841
+ dispatchProvider = bound;
1842
+ }
1843
+ catch {
1844
+ // Instrumentation can fail before dispatch. Never catch/replay the provider call.
1845
+ }
1846
+ }
1847
+ active();
1848
+ const stream = dispatchProvider.createStream(request, modelInput.tools, {
1849
+ ...modelSettings,
1850
+ ...(settings.onActivity ? { onActivity: settings.onActivity } : {}),
1851
+ ...(settings.onRateLimit ? { onRateLimit: settings.onRateLimit } : {}),
1852
+ ...(options.modelSettings?.onActivity
1853
+ ? { onActivity: options.modelSettings.onActivity }
1854
+ : {}),
1855
+ ...(options.modelSettings?.onRateLimit
1856
+ ? { onRateLimit: options.modelSettings.onRateLimit }
1857
+ : {}),
390
1858
  signal,
391
- sessionId: snapshot.runId,
1859
+ sessionId: summary
1860
+ ? operationId
1861
+ : (snapshot.subagent?.identity.originRunId ?? snapshot.runId),
392
1862
  });
393
1863
  for await (const chunk of stream) {
394
1864
  active();
@@ -396,92 +1866,143 @@ export function defineAgent(definition) {
396
1866
  if (!isUsage(chunk.usage))
397
1867
  fail("invalid_usage", "The provider returned invalid token usage.", model.id);
398
1868
  model.usage = copyData(chunk.usage);
1869
+ reportedUsage = true;
1870
+ // Preserve measurements before another pull can hang or the worker can disappear.
1871
+ // This saves usage, not partial text, and does not claim final billing is known.
1872
+ await save();
1873
+ active();
1874
+ }
1875
+ if (guarded) {
1876
+ // Bound collection before yielding. Only the checked assembled turn is published.
1877
+ // All fields count, including reasoning, signatures, tool args and hosted payloads.
1878
+ bufferedBytes += jsonBytes(chunk);
1879
+ bufferedChunks++;
1880
+ if (bufferedBytes > (guardPolicy?.maxOutputBytes ?? 0) ||
1881
+ bufferedChunks > GUARDED_CHUNK_LIMIT)
1882
+ await guards.overflow("modelOutput", model.id);
1883
+ }
1884
+ else if (!summary) {
1885
+ emit({
1886
+ type: "model_chunk",
1887
+ runId: snapshot.runId,
1888
+ attemptId: snapshot.attemptId,
1889
+ operationId: model.id,
1890
+ chunk,
1891
+ });
399
1892
  }
400
- emit({
401
- type: "model_chunk",
402
- runId: snapshot.runId,
403
- attemptId: snapshot.attemptId,
404
- operationId: model.id,
405
- chunk,
406
- });
407
1893
  active();
408
1894
  yield chunk;
409
1895
  }
410
1896
  }
411
- const turn = readTurn(await untilAbort(collectTurn(observed()), signal));
1897
+ let collected;
1898
+ try {
1899
+ collected = await untilAbort(collectTurn(observed()), signal);
1900
+ }
1901
+ catch (error) {
1902
+ await observe({ type: "model_error", operationId: model.id, attemptId: model.attemptId });
1903
+ active();
1904
+ // Only core's classified provider failures are local model failures. Host/checkpoint
1905
+ // errors and unclassified programming errors must not become benign tool strings.
1906
+ if (!(error instanceof ProviderError)) {
1907
+ if (guarded && !(error instanceof Halt))
1908
+ fail("guarded_model_failed", "The guarded model call failed before its output could be checked. Inspect the provider on the server before starting new work.", model.id);
1909
+ throw error;
1910
+ }
1911
+ if (error.kind === "aborted") {
1912
+ scope.tree.stop();
1913
+ throw new Halt({ status: "cancelled" });
1914
+ }
1915
+ fail("model_failed", guarded
1916
+ ? `The model call failed (${error.kind}). Check the provider before starting new work.`
1917
+ : `The model call failed (${error.kind}): ${error.message}`, model.id);
1918
+ }
1919
+ let turn;
1920
+ try {
1921
+ turn = readTurn(collected);
1922
+ }
1923
+ catch (error) {
1924
+ fail("invalid_model_output", guarded
1925
+ ? "The provider returned an invalid guarded turn. Check the provider before starting new work."
1926
+ : messageOf(error), model.id);
1927
+ }
1928
+ await observe({ type: "model_end", operationId: model.id, attemptId: model.attemptId, turn });
1929
+ active();
1930
+ await guards.check("modelOutput", model.id, model.attemptId, turn);
1931
+ active();
412
1932
  const done = {
413
1933
  ...model,
414
1934
  status: "completed",
1935
+ billing: reportedUsage ? "reported" : "unknown",
415
1936
  usage: turn.usage,
416
1937
  turn,
417
1938
  tools: (turn.message.toolCalls ?? []).map((_call, index) => ({
418
1939
  id: toolId(model.id, index),
419
1940
  status: "pending",
1941
+ interrupted: [],
1942
+ retries: [],
420
1943
  })),
421
1944
  };
422
- snapshot.models[snapshot.models.length - 1] = done;
1945
+ record(done);
423
1946
  await save();
1947
+ if (guarded && !summary) {
1948
+ active();
1949
+ emit({
1950
+ type: "model_chunk",
1951
+ runId: snapshot.runId,
1952
+ attemptId: model.attemptId,
1953
+ operationId: model.id,
1954
+ chunk: guardedChunk(turn),
1955
+ });
1956
+ }
424
1957
  return done;
425
1958
  }
426
1959
  try {
1960
+ // Repair a lost acknowledgement from the saved journal without rereading its payload.
1961
+ // Terminal snapshots synchronize too; this never starts a follow-up model call.
1962
+ if (scope.depth === 0)
1963
+ await acknowledgeInputs(snapshot, options, signal);
1964
+ if (scope.depth === 0 && answers) {
1965
+ await answerRequests(snapshot, options, scope, answers, signal);
1966
+ if ([...requestRecords(snapshot)].some(({ record }) => !record.closed && record.decision?.type === "stop"))
1967
+ scope.tree.stop();
1968
+ await save();
1969
+ }
427
1970
  if (snapshot.state.status === "running" || snapshot.state.status === "suspended") {
428
1971
  release = await scope.tree.gate.acquire(signal);
429
1972
  active();
430
- for (const model of snapshot.models) {
431
- const interrupted = model.status === "running"
432
- ? model
433
- : model.tools.find((tool) => tool.status === "running");
434
- if (interrupted)
435
- fail("interrupted_operation", "This operation started but has no saved result. Reconcile it with the host; it will not be replayed.", interrupted.id);
436
- }
437
- if (snapshot.state.status === "suspended" && snapshot.state.path.length > 0) {
438
- // Replay only pure coordination. Evidence follows its exact path to one leaf.
439
- snapshot.state = { status: "running" };
440
- }
441
- if (snapshot.state.status === "suspended" && evidence) {
442
- active();
443
- const approval = snapshot.state.approval;
444
- if (approval.scope.expiresAt <= Date.now())
445
- fail("approval_expired", "The approval expired. Request a new decision before resuming.", approval.request.operationId);
446
- if (!registry.get(approval.request.call.name)?.needsApproval)
447
- fail("invalid_approval", "The pending approval does not belong to an approval-required tool.");
448
- if (!host?.resolveApproval || !host.beforeTool)
449
- fail("approval_host_missing", "Provide host.resolveApproval and host.beforeTool to authenticate a decision and recheck access.");
1973
+ requireGuardVerdicts(snapshot);
1974
+ started = true;
1975
+ await observe({ type: "run_start" });
1976
+ active();
1977
+ const last = snapshot.models.at(-1);
1978
+ snapshot.state = { status: "running" };
1979
+ checkMemoryBinding(snapshot, options.memory);
1980
+ if (needsMemory && !options.memory)
1981
+ fail("memory_missing", "Supply authenticated memory access before starting this agent.");
1982
+ if (!options.memory?.scope &&
1983
+ [...capabilities.values()].some((tool) => isMemoryTool(tool) &&
1984
+ !tool.isReadOnly &&
1985
+ snapshot.definition.enabledTools.includes(tool.name)))
1986
+ fail("memory_missing", "Memory writes need an authenticated person's writable scope. Disable save and forget for shared-only access.");
1987
+ if (memory && options.memory && !snapshot.recall) {
1988
+ snapshot.recall = await recallMemory(snapshot, options.memory, signal, scope.handoffInput);
1989
+ // No model sees recall until the existing progress/checkpoint barrier confirms it.
450
1990
  await save();
451
1991
  active();
452
- const answer = await untilAbort(Promise.resolve(host.resolveApproval(immutableCopy(approval), immutableCopy(evidence.decision))), signal);
453
- active();
454
- if (answer !== "pending") {
455
- if (answer !== "approved" && answer !== "denied")
456
- fail("invalid_approval_decision", "The host must return approved, denied or pending.");
457
- snapshot.state = { status: "running" };
458
- if (answer === "approved")
459
- approved = approval;
460
- else {
461
- const model = snapshot.models.at(-1);
462
- if (model?.status !== "completed")
463
- fail("invalid_journal", "The pending tool turn is missing.");
464
- const index = model.tools.findIndex((tool) => tool.id === approval.request.operationId);
465
- if (usedTools() >= limits.toolCalls)
466
- throw new Halt({ status: "limited", limit: "toolCalls" });
467
- await finishTool(model, index, requestFor(model, index), {
468
- ok: false,
469
- kind: "denied",
470
- content: "The host denied this tool call. Continue without this action.",
471
- });
472
- }
473
- }
474
1992
  }
475
- if (snapshot.state.status === "running") {
476
- const last = snapshot.models.at(-1);
477
- if (last?.status === "completed")
478
- await handleTurn(last);
479
- while (snapshot.state.status === "running")
480
- await handleTurn(await nextTurn());
1993
+ if (snapshot.recall?.status === "failed" && memory?.onError === "fail")
1994
+ fail("memory_unavailable", "Memory could not be read. Check the store before starting a new run.");
1995
+ if (last?.status === "running")
1996
+ await handleTurn(await nextTurn(last));
1997
+ else if (last?.status === "completed") {
1998
+ await recoverTools(last);
1999
+ await handleTurn(last);
481
2000
  }
2001
+ while (snapshot.state.status === "running")
2002
+ await handleTurn(await nextTurn());
482
2003
  }
483
2004
  if (snapshot.state.status === "completed")
484
- completed = { output: validateResult(snapshot.state.candidate) };
2005
+ completed = { output: completedOutput(snapshot) };
485
2006
  await save();
486
2007
  }
487
2008
  catch (error) {
@@ -514,6 +2035,8 @@ export function defineAgent(definition) {
514
2035
  }
515
2036
  finally {
516
2037
  release();
2038
+ if (started)
2039
+ await observe({ type: "run_end", state: snapshot.state });
517
2040
  clearTimeout(timer);
518
2041
  }
519
2042
  emit({
@@ -522,36 +2045,229 @@ export function defineAgent(definition) {
522
2045
  attemptId: snapshot.attemptId,
523
2046
  state: snapshot.state,
524
2047
  });
525
- const record = recordOf(snapshot, instructions);
2048
+ // Includes the final state event, before a child host receipt or session append can land.
2049
+ await host?.progress?.flush();
2050
+ const record = recordOf(snapshot);
526
2051
  const state = snapshot.state;
527
2052
  if (state.status === "completed") {
528
2053
  if (!completed)
529
2054
  throw new Error("The agent completed without validating its result.");
530
2055
  return { ...record, status: "completed", output: completed.output };
531
2056
  }
532
- return { ...record, ...state };
2057
+ return state.status === "suspended"
2058
+ ? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
2059
+ : { ...record, ...state };
2060
+ }
2061
+ function checkInline(start) {
2062
+ const bytes = inlineBytes(start.history, start.input);
2063
+ if (bytes > limits.inlineBytes)
2064
+ throw new TypeError(`The inline images and files come to ${bytes} bytes, and this agent accepts ${limits.inlineBytes}. Send large files as media references, or raise limits.inlineBytes.`);
2065
+ }
2066
+ function freeze(start) {
2067
+ // Once, here: adapters repair every request again, and repair is idempotent, so the
2068
+ // bytes a provider caches never change between turns or across a resume.
2069
+ const history = repairConversation(start.history, (name) => (registry.get(name) ?? codeTools.get(name))?.isReadOnly === true);
2070
+ checkInline({ history, input: start.input });
2071
+ return { ...start, history };
2072
+ }
2073
+ async function create(start, runId, tree, options = {}, subagent) {
2074
+ const frozen = freeze(start);
2075
+ const spec = subagent?.record.spec;
2076
+ const resolved = await resolveDefinition(frozen, spec
2077
+ ? {
2078
+ ...options,
2079
+ enabledTools: spec.tools,
2080
+ modelSettings: subagent.record.policy.models[spec.model ?? ""]?.settings,
2081
+ }
2082
+ : options, runId, subagent?.source);
2083
+ const record = subagent
2084
+ ? { ...copyData(subagent.record), base: copyData(resolved) }
2085
+ : undefined;
2086
+ if (subagent?.record.previousRunId && !equalData(resolved, subagent.source))
2087
+ throw new TypeError("The helper's admitted definition changed. Restore its original configuration before continuing.");
2088
+ if (spec)
2089
+ resolved.instructions = subagentInstructions(resolved.instructions, spec.instructions);
2090
+ const childLimits = spec ? subagentLimits(limits, spec.limits) : limits;
2091
+ if (inlineBytes(frozen.history, frozen.input) > childLimits.inlineBytes)
2092
+ throw new TypeError("The helper input exceeds its admitted inline byte limit.");
2093
+ const { history, input, session } = frozen;
2094
+ const startedAt = Date.now();
2095
+ return {
2096
+ kind: "agent",
2097
+ format: 3,
2098
+ agentId: id,
2099
+ version,
2100
+ runId,
2101
+ attemptId: crypto.randomUUID(),
2102
+ startedAt,
2103
+ definition: resolved,
2104
+ ...(record ? { subagent: record } : {}),
2105
+ history: copyData(history),
2106
+ input: copyData(input),
2107
+ inputs: [],
2108
+ guards: [],
2109
+ compactions: [],
2110
+ ...(session ? { session: copyData(session) } : {}),
2111
+ limits: copyData(childLimits),
2112
+ models: [],
2113
+ delegations: [],
2114
+ state: { status: "running" },
2115
+ tree: tree
2116
+ ? copyData(tree)
2117
+ : {
2118
+ runId,
2119
+ startedAt,
2120
+ limits: copyData(treeLimits),
2121
+ ...(options.memory ? { memory: memoryScopes(options.memory) } : {}),
2122
+ },
2123
+ };
533
2124
  }
534
2125
  const runtime = {
535
- execute,
536
- create(input, runId, tree) {
537
- const startedAt = Date.now();
538
- return {
539
- format: 2,
540
- agentId: id,
2126
+ node: {
2127
+ restore: (raw, tree, subagent) => runtime.restore(raw, tree, subagent),
2128
+ hydrate: (node) => runtime.hydrate(agentSnapshot(node)),
2129
+ answerRequests: (node, options, scope, answers, signal) => answerRequests(agentSnapshot(node), options, scope, answers, signal),
2130
+ execute: (node, options, scope, answers) => execute(agentSnapshot(node), options, scope, answers),
2131
+ },
2132
+ handoffs: [...handoffs.values()],
2133
+ tools: Object.freeze([...capabilities.values()]),
2134
+ enabledTools: Array.isArray(enabledTools) ? Object.freeze([...enabledTools]) : undefined,
2135
+ limits: immutableCopy(limits),
2136
+ async checkTools(snapshot, options) {
2137
+ const signal = options.signal ?? new AbortController().signal;
2138
+ const current = checkNames(typeof enabledTools === "function"
2139
+ ? await untilAbort(Promise.resolve(enabledTools(Object.freeze({
2140
+ agentId: id,
2141
+ version,
2142
+ runId: snapshot.runId,
2143
+ ...immutableCopy({ history: snapshot.history, input: snapshot.input }),
2144
+ context: Object.freeze({ ...options.context }),
2145
+ signal,
2146
+ }))), signal)
2147
+ : (enabledTools ?? names));
2148
+ if (snapshot.definition.enabledTools.some((name) => name !== RESULT_TOOL_NAME && !current.includes(name)))
2149
+ fail("subagent_grant_changed", "The host revoked a helper capability. Obtain fresh authorization before starting different work.");
2150
+ },
2151
+ configuration() {
2152
+ const { onActivity: _activity, onRateLimit: _rateLimit, ...modelSettings } = settings;
2153
+ return immutableCopy({
2154
+ id,
541
2155
  version,
542
- runId,
543
- attemptId: crypto.randomUUID(),
544
- startedAt,
545
- input,
546
- limits: copyData(limits),
547
- models: [],
548
- delegations: [],
549
- state: { status: "running" },
550
- tree: tree ? copyData(tree) : { runId, startedAt, limits: copyData(treeLimits) },
551
- };
2156
+ provider: { id: provider.id, model: provider.model },
2157
+ instructions: typeof instructions === "string" ? instructions : null,
2158
+ enabledTools: Array.isArray(enabledTools) ? enabledTools : null,
2159
+ modelSettings,
2160
+ limits,
2161
+ output: output?.schema ?? null,
2162
+ stopAtTools,
2163
+ recovery,
2164
+ guardrails: guardPolicy,
2165
+ compaction,
2166
+ toolRetries,
2167
+ ...(memory ? { memory } : {}),
2168
+ tools: tools.map((tool) => ({
2169
+ definition: tool.definition(),
2170
+ needsApproval: tool.needsApproval === true,
2171
+ ...(isDelegation(tool)
2172
+ ? {
2173
+ kind: "delegation",
2174
+ specialists: tool.specialists.map(({ id, version }) => ({ id, version })),
2175
+ }
2176
+ : isHandoff(tool)
2177
+ ? { kind: "handoff", target: handoffRef(tool.target()) }
2178
+ : isCodeTool(tool)
2179
+ ? {
2180
+ kind: "code",
2181
+ limits: tool.limits,
2182
+ bindings: tool.tools.map((bound) => ({
2183
+ definition: bound.definition(),
2184
+ outputSchema: bound.outputSchema,
2185
+ isReadOnly: bound.isReadOnly,
2186
+ needsApproval: bound.needsApproval,
2187
+ isConcurrencySafe: bound.isConcurrencySafe,
2188
+ timeoutMs: bound.timeoutMs,
2189
+ })),
2190
+ }
2191
+ : isClientTool(tool)
2192
+ ? { kind: "client", resultSchema: tool.resultSchema }
2193
+ : {
2194
+ kind: "tool",
2195
+ isReadOnly: tool.isReadOnly === true,
2196
+ isConcurrencySafe: tool.isConcurrencySafe === true,
2197
+ isTerminal: tool.isTerminal === true,
2198
+ }),
2199
+ })),
2200
+ });
552
2201
  },
553
- restore(raw, tree) {
554
- const snapshot = readSnapshot(raw, id, version, limits, output ? RESULT_TOOL_NAME : undefined);
2202
+ execute,
2203
+ answerRequests,
2204
+ freeze,
2205
+ create,
2206
+ async open(input, options, runId) {
2207
+ options = { ...options, memory: readMemoryBinding(options.memory) };
2208
+ if (needsMemory && !options.memory)
2209
+ throw new TypeError("This agent needs authenticated memory access in RunOptions.memory.");
2210
+ // Everything before the snapshot exists runs outside the journal: a paid summarizer in
2211
+ // prepareHistory can run again if the process dies before the first checkpoint.
2212
+ const signal = options.signal ?? new AbortController().signal;
2213
+ const session = options.session;
2214
+ let start;
2215
+ if (session) {
2216
+ if (isRecord(input) && "messages" in input)
2217
+ throw new TypeError("With a session, pass only the new turn. The session holds the history.");
2218
+ // Checked before the load, so a turn that would be refused costs no read.
2219
+ const turn = readInput(input, "caller").input;
2220
+ checkInline({ history: [], input: turn });
2221
+ const loaded = await untilAbort(Promise.resolve(session.load({
2222
+ ...(options.historyLimit !== undefined ? { limit: options.historyLimit } : {}),
2223
+ signal,
2224
+ })), signal);
2225
+ if (!isRecord(loaded) || !isRevision(loaded.revision))
2226
+ throw new TypeError("session.load must return { messages, revision }.");
2227
+ start = {
2228
+ history: readStored(loaded.messages, "session.load"),
2229
+ input: turn,
2230
+ session: { id: session.id, revision: loaded.revision },
2231
+ };
2232
+ }
2233
+ else {
2234
+ if (options.historyLimit !== undefined)
2235
+ throw new TypeError("historyLimit applies to a session. Trim the messages you pass in yourself.");
2236
+ start = readInput(input, "caller");
2237
+ }
2238
+ if (options.prepareHistory) {
2239
+ const prepared = await untilAbort(Promise.resolve(options.prepareHistory(copyData(start.history))), signal);
2240
+ start = { ...start, history: readStored(prepared, "prepareHistory") };
2241
+ }
2242
+ return create(start, runId, undefined, options);
2243
+ },
2244
+ restore(raw, tree, subagent) {
2245
+ if (isRecord(raw) && (!equalData(raw.subagent, subagent) || (subagent && !tree)))
2246
+ throw new TypeError("Restore a model-created helper through its owning creation tool.");
2247
+ const snapshot = readSnapshot(raw, id, version, subagent ? subagentLimits(limits, subagent.spec.limits) : limits, output ? RESULT_TOOL_NAME : undefined, codeTools);
2248
+ checkNames(snapshot.definition.enabledTools);
2249
+ if (!equalData(snapshot.definition.memory, memory))
2250
+ throw new TypeError("Restore the same memory recall policy before resuming.");
2251
+ if (!equalData(snapshot.definition.compaction, compaction) ||
2252
+ !equalData(snapshot.definition.toolRetries?.policy ?? null, toolRetries))
2253
+ throw new TypeError("The recorded compaction or tool retry policy changed. Restore the same definition before resuming.");
2254
+ if (!equalData(snapshot.definition.guardrails, guardPolicy))
2255
+ throw new TypeError("The recorded guard policy changed. Restore the same guard identity, stages and limits.");
2256
+ if (!equalData(snapshot.definition.recovery?.policy ?? null, recovery) ||
2257
+ (snapshot.definition.recovery &&
2258
+ !equalData(snapshot.definition.recovery.provider, {
2259
+ id: provider.id,
2260
+ model: provider.model,
2261
+ })))
2262
+ throw new TypeError("The recorded recovery policy or provider identity changed. Restore the same profile or reconcile the run.");
2263
+ if (!equalData(snapshot.definition.stopAtTools, stopAtTools) ||
2264
+ (output && !snapshot.definition.enabledTools.includes(RESULT_TOOL_NAME)))
2265
+ throw new TypeError("The recorded tool behavior does not match this agent version.");
2266
+ const choice = snapshot.definition.modelSettings.toolChoice;
2267
+ if ((output && choice === "none") ||
2268
+ (choice === "required" && snapshot.definition.enabledTools.length === 0) ||
2269
+ (typeof choice === "object" && !snapshot.definition.enabledTools.includes(choice.name)))
2270
+ throw new TypeError("The recorded tool choice does not name an enabled tool.");
555
2271
  if (tree
556
2272
  ? !equalData(snapshot.tree, tree)
557
2273
  : snapshot.tree.runId !== snapshot.runId || !equalData(snapshot.tree.limits, treeLimits))
@@ -561,7 +2277,10 @@ export function defineAgent(definition) {
561
2277
  continue;
562
2278
  for (const [index, tool] of model.tools.entries()) {
563
2279
  const call = model.turn.message.toolCalls?.[index];
564
- const descriptor = call && delegations.get(call.name);
2280
+ const descriptor = call &&
2281
+ snapshot.definition.enabledTools.includes(call.name) &&
2282
+ snapshot.definition.modelSettings.toolChoice !== "none" &&
2283
+ descriptorFor(call.name, snapshot, tool.id);
565
2284
  const journal = snapshot.delegations.find((entry) => entry.operationId === tool.id);
566
2285
  if (descriptor && tool.status !== "pending") {
567
2286
  if (!journal || tool.status === "running")
@@ -571,38 +2290,92 @@ export function defineAgent(definition) {
571
2290
  throw new TypeError("The saved delegation is not in this agent definition.");
572
2291
  if (!journal || !descriptor)
573
2292
  continue;
2293
+ if (journal.kind !== (call && handoffs.has(call.name) ? "handoff" : "delegation"))
2294
+ throw new TypeError("The saved delegation kind does not match its registered tool.");
2295
+ if (journal.kind === "handoff")
2296
+ checkHandoffTargets(agent);
2297
+ checkSubagentChildren(descriptor, snapshot, journal);
574
2298
  for (const entry of journal.children) {
575
- const agent = descriptor.specialists.find((agent) => agent.id === entry.snapshot.agentId && agent.version === entry.snapshot.version);
2299
+ const agent = descriptor.specialists.find((agent) => agent.kind === entry.snapshot.kind &&
2300
+ agent.id === nodeId(entry.snapshot) &&
2301
+ agent.version === entry.snapshot.version);
576
2302
  if (!agent)
577
2303
  throw new TypeError("The saved child is not a registered specialist version.");
578
- entry.snapshot = agent[AGENT_RUNTIME].restore(entry.snapshot, snapshot.tree);
2304
+ entry.snapshot = runtimeOf(agent).restore(entry.snapshot, snapshot.tree, entry.snapshot.kind === "agent" ? entry.snapshot.subagent : undefined);
579
2305
  }
580
2306
  }
581
2307
  }
582
2308
  if (snapshot.state.status === "completed")
583
- validateResult(snapshot.state.candidate);
2309
+ completedOutput(snapshot);
584
2310
  return snapshot;
585
2311
  },
586
2312
  hydrate(snapshot) {
587
- const record = recordOf(snapshot, instructions);
2313
+ const record = recordOf(snapshot);
588
2314
  const state = record.snapshot.state;
589
2315
  if (state.status === "running")
590
2316
  throw new Error("A child has not settled yet.");
591
2317
  return state.status === "completed"
592
- ? { ...record, status: "completed", output: validateResult(state.candidate) }
593
- : { ...record, ...state };
2318
+ ? { ...record, status: "completed", output: completedOutput(record.snapshot) }
2319
+ : state.status === "suspended"
2320
+ ? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
2321
+ : { ...record, ...state };
594
2322
  },
595
2323
  };
596
- async function root(snapshot, options, evidence) {
2324
+ /** Once per root, after its final checkpoint. Never changes the run's own status. */
2325
+ async function appendTurn(outcome, options, tree) {
2326
+ const ref = outcome.snapshot.session;
2327
+ if (!ref)
2328
+ return undefined;
2329
+ const session = options.session;
2330
+ // A waiting run has no settled turn yet. After a failed checkpoint the host's journal is
2331
+ // behind this outcome: resuming what it saved settles again and appends then.
2332
+ if (!session || outcome.status === "suspended" || tree.checkpointFailed)
2333
+ return { id: ref.id, status: "pending" };
2334
+ // A Stop ends the run, not the record of it: the turn the person sent is still saved.
2335
+ const signal = options.signal && !options.signal.aborted ? options.signal : new AbortController().signal;
2336
+ try {
2337
+ const saved = await untilAbort(Promise.resolve(session.append(immutableCopy({
2338
+ runId: outcome.runId,
2339
+ after: ref.revision,
2340
+ messages: outcome.newMessages,
2341
+ }), { signal })), signal);
2342
+ if (!isRecord(saved) || !isId(saved.revision))
2343
+ throw new TypeError("session.append returned no revision.");
2344
+ return { id: ref.id, status: "saved", revision: saved.revision };
2345
+ }
2346
+ catch (error) {
2347
+ // By name, not instanceof: a store built against another copy of this package throws
2348
+ // its own SessionConflictError class.
2349
+ const conflict = error instanceof Error && error.name === "SessionConflictError";
2350
+ return {
2351
+ id: ref.id,
2352
+ status: "unsaved",
2353
+ error: conflict
2354
+ ? {
2355
+ code: "session_conflict",
2356
+ message: "The conversation changed after this run loaded it. Load it again before you continue it.",
2357
+ }
2358
+ : {
2359
+ code: "session_failed",
2360
+ message: `The session did not save this turn: ${messageOf(error)}`,
2361
+ },
2362
+ };
2363
+ }
2364
+ }
2365
+ async function root(snapshot, options, answers) {
597
2366
  const tree = new ExecutionTree(snapshot, options);
2367
+ let outcome;
598
2368
  try {
599
- return await execute(snapshot, options, { tree, depth: 0 }, evidence);
2369
+ outcome = await execute(snapshot, options, { tree, depth: 0, path: [] }, answers);
600
2370
  }
601
2371
  finally {
602
2372
  tree.close();
603
2373
  }
2374
+ const session = await appendTurn(outcome, options, tree);
2375
+ return session ? { ...outcome, session } : outcome;
604
2376
  }
605
2377
  const agent = {
2378
+ kind: "agent",
606
2379
  id,
607
2380
  version,
608
2381
  [AGENT_RUNTIME]: runtime,
@@ -610,25 +2383,23 @@ export function defineAgent(definition) {
610
2383
  return specialistTool(agent, options);
611
2384
  },
612
2385
  async run(input, options = {}) {
613
- if (!isId(input))
614
- throw new TypeError("Give the agent a non-empty text input.");
615
2386
  checkOptions(options);
616
- return root(runtime.create(input, options.runId ?? crypto.randomUUID()), options);
2387
+ options = { ...options, memory: readMemoryBinding(options.memory) };
2388
+ return root(await runtime.open(input, options, options.runId ?? crypto.randomUUID()), options);
617
2389
  },
618
2390
  async resume(raw, options) {
619
- checkOptions(options);
2391
+ checkOptions(options, "resume");
2392
+ options = { ...options, memory: readMemoryBinding(options.memory) };
620
2393
  const snapshot = runtime.restore(raw);
621
- let evidence;
622
- if (options.decision !== undefined || options.approvalPath !== undefined) {
623
- if (snapshot.state.status !== "suspended" ||
624
- !equalData(options.approvalPath ?? [], snapshot.state.path))
625
- throw new TypeError("The decision path must match the exposed pending approval.");
626
- if (options.decision !== undefined)
627
- evidence = copyData({ path: snapshot.state.path, decision: options.decision });
628
- }
2394
+ checkMemoryBinding(snapshot, options.memory);
2395
+ if (options.session && options.session.id !== snapshot.session?.id)
2396
+ throw new TypeError(snapshot.session
2397
+ ? "This run belongs to another session."
2398
+ : "This run has no session. Resume it without one.");
2399
+ const answers = readAnswers(snapshot, options.answers ?? {});
629
2400
  await authorizeTree(snapshot, options.host);
630
2401
  snapshot.attemptId = crypto.randomUUID();
631
- return root(snapshot, options, evidence);
2402
+ return root(snapshot, options, answers);
632
2403
  },
633
2404
  };
634
2405
  return Object.freeze(agent);