@providerkit/agents 0.0.0-stage → 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 (296) hide show
  1. package/LICENSE +21 -0
  2. package/LICENSE-APACHE-2.0 +202 -0
  3. package/README.md +2328 -2
  4. package/THIRD_PARTY_NOTICES.md +521 -0
  5. package/dist/a2a/auth.d.ts +10 -0
  6. package/dist/a2a/auth.d.ts.map +1 -0
  7. package/dist/a2a/auth.js +52 -0
  8. package/dist/a2a/auth.js.map +1 -0
  9. package/dist/a2a/client.d.ts +74 -0
  10. package/dist/a2a/client.d.ts.map +1 -0
  11. package/dist/a2a/client.js +601 -0
  12. package/dist/a2a/client.js.map +1 -0
  13. package/dist/a2a/index.d.ts +22 -0
  14. package/dist/a2a/index.d.ts.map +1 -0
  15. package/dist/a2a/index.js +11 -0
  16. package/dist/a2a/index.js.map +1 -0
  17. package/dist/a2a/memory-runs.d.ts +62 -0
  18. package/dist/a2a/memory-runs.d.ts.map +1 -0
  19. package/dist/a2a/memory-runs.js +349 -0
  20. package/dist/a2a/memory-runs.js.map +1 -0
  21. package/dist/a2a/policy.d.ts +15 -0
  22. package/dist/a2a/policy.d.ts.map +1 -0
  23. package/dist/a2a/policy.js +114 -0
  24. package/dist/a2a/policy.js.map +1 -0
  25. package/dist/a2a/push.d.ts +34 -0
  26. package/dist/a2a/push.d.ts.map +1 -0
  27. package/dist/a2a/push.js +180 -0
  28. package/dist/a2a/push.js.map +1 -0
  29. package/dist/a2a/remote.d.ts +155 -0
  30. package/dist/a2a/remote.d.ts.map +1 -0
  31. package/dist/a2a/remote.js +1196 -0
  32. package/dist/a2a/remote.js.map +1 -0
  33. package/dist/a2a/server.d.ts +110 -0
  34. package/dist/a2a/server.d.ts.map +1 -0
  35. package/dist/a2a/server.js +1139 -0
  36. package/dist/a2a/server.js.map +1 -0
  37. package/dist/a2a/signing.d.ts +21 -0
  38. package/dist/a2a/signing.d.ts.map +1 -0
  39. package/dist/a2a/signing.js +305 -0
  40. package/dist/a2a/signing.js.map +1 -0
  41. package/dist/a2a/tasks.d.ts +88 -0
  42. package/dist/a2a/tasks.d.ts.map +1 -0
  43. package/dist/a2a/tasks.js +170 -0
  44. package/dist/a2a/tasks.js.map +1 -0
  45. package/dist/a2a/wire.d.ts +267 -0
  46. package/dist/a2a/wire.d.ts.map +1 -0
  47. package/dist/a2a/wire.js +1202 -0
  48. package/dist/a2a/wire.js.map +1 -0
  49. package/dist/background-types.d.ts +76 -0
  50. package/dist/background-types.d.ts.map +1 -0
  51. package/dist/background-types.js +2 -0
  52. package/dist/background-types.js.map +1 -0
  53. package/dist/child.d.ts +25 -0
  54. package/dist/child.d.ts.map +1 -0
  55. package/dist/child.js +129 -0
  56. package/dist/child.js.map +1 -0
  57. package/dist/code-driver.d.ts +40 -0
  58. package/dist/code-driver.d.ts.map +1 -0
  59. package/dist/code-driver.js +2 -0
  60. package/dist/code-driver.js.map +1 -0
  61. package/dist/code-mode.d.ts +3 -0
  62. package/dist/code-mode.d.ts.map +1 -0
  63. package/dist/code-mode.js +2 -0
  64. package/dist/code-mode.js.map +1 -0
  65. package/dist/code-script.d.ts +3 -0
  66. package/dist/code-script.d.ts.map +1 -0
  67. package/dist/code-script.js +149 -0
  68. package/dist/code-script.js.map +1 -0
  69. package/dist/code.d.ts +75 -0
  70. package/dist/code.d.ts.map +1 -0
  71. package/dist/code.js +326 -0
  72. package/dist/code.js.map +1 -0
  73. package/dist/compaction.d.ts +15 -0
  74. package/dist/compaction.d.ts.map +1 -0
  75. package/dist/compaction.js +168 -0
  76. package/dist/compaction.js.map +1 -0
  77. package/dist/delegation.d.ts +135 -0
  78. package/dist/delegation.d.ts.map +1 -0
  79. package/dist/delegation.js +401 -0
  80. package/dist/delegation.js.map +1 -0
  81. package/dist/evals/driver.d.ts +10 -0
  82. package/dist/evals/driver.d.ts.map +1 -0
  83. package/dist/evals/driver.js +192 -0
  84. package/dist/evals/driver.js.map +1 -0
  85. package/dist/evals/journal.d.ts +26 -0
  86. package/dist/evals/journal.d.ts.map +1 -0
  87. package/dist/evals/journal.js +483 -0
  88. package/dist/evals/journal.js.map +1 -0
  89. package/dist/evals/judge.d.ts +31 -0
  90. package/dist/evals/judge.d.ts.map +1 -0
  91. package/dist/evals/judge.js +142 -0
  92. package/dist/evals/judge.js.map +1 -0
  93. package/dist/evals/report.d.ts +38 -0
  94. package/dist/evals/report.d.ts.map +1 -0
  95. package/dist/evals/report.js +241 -0
  96. package/dist/evals/report.js.map +1 -0
  97. package/dist/evals/runner.d.ts +24 -0
  98. package/dist/evals/runner.d.ts.map +1 -0
  99. package/dist/evals/runner.js +655 -0
  100. package/dist/evals/runner.js.map +1 -0
  101. package/dist/evals/scorers.d.ts +36 -0
  102. package/dist/evals/scorers.d.ts.map +1 -0
  103. package/dist/evals/scorers.js +259 -0
  104. package/dist/evals/scorers.js.map +1 -0
  105. package/dist/evals/simulation.d.ts +7 -0
  106. package/dist/evals/simulation.d.ts.map +1 -0
  107. package/dist/evals/simulation.js +38 -0
  108. package/dist/evals/simulation.js.map +1 -0
  109. package/dist/evals/testing.d.ts +36 -0
  110. package/dist/evals/testing.d.ts.map +1 -0
  111. package/dist/evals/testing.js +87 -0
  112. package/dist/evals/testing.js.map +1 -0
  113. package/dist/evals/trajectory.d.ts +11 -0
  114. package/dist/evals/trajectory.d.ts.map +1 -0
  115. package/dist/evals/trajectory.js +180 -0
  116. package/dist/evals/trajectory.js.map +1 -0
  117. package/dist/evals/types.d.ts +431 -0
  118. package/dist/evals/types.d.ts.map +1 -0
  119. package/dist/evals/types.js +4 -0
  120. package/dist/evals/types.js.map +1 -0
  121. package/dist/evals.d.ts +14 -0
  122. package/dist/evals.d.ts.map +1 -0
  123. package/dist/evals.js +9 -0
  124. package/dist/evals.js.map +1 -0
  125. package/dist/extensions.d.ts +33 -0
  126. package/dist/extensions.d.ts.map +1 -0
  127. package/dist/extensions.js +188 -0
  128. package/dist/extensions.js.map +1 -0
  129. package/dist/handoff.d.ts +58 -0
  130. package/dist/handoff.d.ts.map +1 -0
  131. package/dist/handoff.js +160 -0
  132. package/dist/handoff.js.map +1 -0
  133. package/dist/index.d.ts +19 -0
  134. package/dist/index.d.ts.map +1 -0
  135. package/dist/index.js +11 -0
  136. package/dist/index.js.map +1 -0
  137. package/dist/input.d.ts +42 -0
  138. package/dist/input.d.ts.map +1 -0
  139. package/dist/input.js +266 -0
  140. package/dist/input.js.map +1 -0
  141. package/dist/mcp.d.ts +77 -0
  142. package/dist/mcp.d.ts.map +1 -0
  143. package/dist/mcp.js +505 -0
  144. package/dist/mcp.js.map +1 -0
  145. package/dist/memory-store.d.ts +11 -0
  146. package/dist/memory-store.d.ts.map +1 -0
  147. package/dist/memory-store.js +272 -0
  148. package/dist/memory-store.js.map +1 -0
  149. package/dist/memory.d.ts +212 -0
  150. package/dist/memory.d.ts.map +1 -0
  151. package/dist/memory.js +613 -0
  152. package/dist/memory.js.map +1 -0
  153. package/dist/otel.d.ts +74 -0
  154. package/dist/otel.d.ts.map +1 -0
  155. package/dist/otel.js +427 -0
  156. package/dist/otel.js.map +1 -0
  157. package/dist/progress.d.ts +17 -0
  158. package/dist/progress.d.ts.map +1 -0
  159. package/dist/progress.js +193 -0
  160. package/dist/progress.js.map +1 -0
  161. package/dist/quickjs.d.ts +19 -0
  162. package/dist/quickjs.d.ts.map +1 -0
  163. package/dist/quickjs.js +519 -0
  164. package/dist/quickjs.js.map +1 -0
  165. package/dist/recovery.d.ts +10 -0
  166. package/dist/recovery.d.ts.map +1 -0
  167. package/dist/recovery.js +62 -0
  168. package/dist/recovery.js.map +1 -0
  169. package/dist/request.d.ts +88 -0
  170. package/dist/request.d.ts.map +1 -0
  171. package/dist/request.js +422 -0
  172. package/dist/request.js.map +1 -0
  173. package/dist/run.d.ts +20 -0
  174. package/dist/run.d.ts.map +1 -0
  175. package/dist/run.js +2407 -0
  176. package/dist/run.js.map +1 -0
  177. package/dist/runs.d.ts +110 -0
  178. package/dist/runs.d.ts.map +1 -0
  179. package/dist/runs.js +438 -0
  180. package/dist/runs.js.map +1 -0
  181. package/dist/schema-to-ts.d.ts +4 -0
  182. package/dist/schema-to-ts.d.ts.map +1 -0
  183. package/dist/schema-to-ts.js +191 -0
  184. package/dist/schema-to-ts.js.map +1 -0
  185. package/dist/session.d.ts +23 -0
  186. package/dist/session.d.ts.map +1 -0
  187. package/dist/session.js +137 -0
  188. package/dist/session.js.map +1 -0
  189. package/dist/snapshot.d.ts +75 -0
  190. package/dist/snapshot.d.ts.map +1 -0
  191. package/dist/snapshot.js +1607 -0
  192. package/dist/snapshot.js.map +1 -0
  193. package/dist/steering.d.ts +75 -0
  194. package/dist/steering.d.ts.map +1 -0
  195. package/dist/steering.js +214 -0
  196. package/dist/steering.js.map +1 -0
  197. package/dist/subagents.d.ts +141 -0
  198. package/dist/subagents.d.ts.map +1 -0
  199. package/dist/subagents.js +746 -0
  200. package/dist/subagents.js.map +1 -0
  201. package/dist/tool-retry.d.ts +12 -0
  202. package/dist/tool-retry.d.ts.map +1 -0
  203. package/dist/tool-retry.js +53 -0
  204. package/dist/tool-retry.js.map +1 -0
  205. package/dist/tree.d.ts +98 -0
  206. package/dist/tree.d.ts.map +1 -0
  207. package/dist/tree.js +320 -0
  208. package/dist/tree.js.map +1 -0
  209. package/dist/types.d.ts +1007 -0
  210. package/dist/types.d.ts.map +1 -0
  211. package/dist/types.js +2 -0
  212. package/dist/types.js.map +1 -0
  213. package/dist/workflow-snapshot.d.ts +8 -0
  214. package/dist/workflow-snapshot.d.ts.map +1 -0
  215. package/dist/workflow-snapshot.js +276 -0
  216. package/dist/workflow-snapshot.js.map +1 -0
  217. package/dist/workflow-types.d.ts +171 -0
  218. package/dist/workflow-types.d.ts.map +1 -0
  219. package/dist/workflow-types.js +2 -0
  220. package/dist/workflow-types.js.map +1 -0
  221. package/dist/workflow.d.ts +19 -0
  222. package/dist/workflow.d.ts.map +1 -0
  223. package/dist/workflow.js +1053 -0
  224. package/dist/workflow.js.map +1 -0
  225. package/examples/a2a-remote.ts +85 -0
  226. package/examples/a2a-server.ts +100 -0
  227. package/examples/background.ts +59 -0
  228. package/examples/basic.ts +44 -0
  229. package/examples/code-mode.ts +76 -0
  230. package/examples/conversation.ts +57 -0
  231. package/examples/evals.ts +79 -0
  232. package/examples/guardrails.ts +56 -0
  233. package/examples/handoff.ts +79 -0
  234. package/examples/memory.ts +44 -0
  235. package/examples/otel.ts +99 -0
  236. package/examples/specialists.ts +99 -0
  237. package/examples/steering.ts +69 -0
  238. package/examples/structured-handoff.ts +92 -0
  239. package/examples/subagents.ts +127 -0
  240. package/examples/workflow.ts +74 -0
  241. package/package.json +114 -4
  242. package/src/a2a/auth.ts +62 -0
  243. package/src/a2a/client.ts +733 -0
  244. package/src/a2a/index.ts +74 -0
  245. package/src/a2a/memory-runs.ts +448 -0
  246. package/src/a2a/policy.ts +148 -0
  247. package/src/a2a/push.ts +251 -0
  248. package/src/a2a/remote.ts +1652 -0
  249. package/src/a2a/server.ts +1390 -0
  250. package/src/a2a/signing.ts +348 -0
  251. package/src/a2a/tasks.ts +260 -0
  252. package/src/a2a/wire.ts +1443 -0
  253. package/src/background-types.ts +86 -0
  254. package/src/child.ts +181 -0
  255. package/src/code-driver.ts +48 -0
  256. package/src/code-mode.ts +12 -0
  257. package/src/code-script.ts +149 -0
  258. package/src/code.ts +424 -0
  259. package/src/compaction.ts +212 -0
  260. package/src/delegation.ts +694 -0
  261. package/src/evals/driver.ts +222 -0
  262. package/src/evals/journal.ts +605 -0
  263. package/src/evals/judge.ts +188 -0
  264. package/src/evals/report.ts +295 -0
  265. package/src/evals/runner.ts +826 -0
  266. package/src/evals/scorers.ts +339 -0
  267. package/src/evals/simulation.ts +46 -0
  268. package/src/evals/testing.ts +126 -0
  269. package/src/evals/trajectory.ts +223 -0
  270. package/src/evals/types.ts +463 -0
  271. package/src/evals.ts +72 -0
  272. package/src/extensions.ts +247 -0
  273. package/src/handoff.ts +214 -0
  274. package/src/index.ts +62 -0
  275. package/src/input.ts +319 -0
  276. package/src/mcp.ts +690 -0
  277. package/src/memory-store.ts +366 -0
  278. package/src/memory.ts +893 -0
  279. package/src/otel.ts +568 -0
  280. package/src/progress.ts +214 -0
  281. package/src/quickjs.ts +524 -0
  282. package/src/recovery.ts +90 -0
  283. package/src/request.ts +513 -0
  284. package/src/run.ts +3199 -0
  285. package/src/runs.ts +696 -0
  286. package/src/schema-to-ts.ts +194 -0
  287. package/src/session.ts +178 -0
  288. package/src/snapshot.ts +2099 -0
  289. package/src/steering.ts +329 -0
  290. package/src/subagents.ts +1084 -0
  291. package/src/tool-retry.ts +86 -0
  292. package/src/tree.ts +366 -0
  293. package/src/types.ts +944 -0
  294. package/src/workflow-snapshot.ts +366 -0
  295. package/src/workflow-types.ts +213 -0
  296. package/src/workflow.ts +1316 -0
package/src/run.ts ADDED
@@ -0,0 +1,3199 @@
1
+ import {
2
+ EMPTY_USAGE,
3
+ ProviderError,
4
+ ToolRegistry,
5
+ collectTurn,
6
+ createGate,
7
+ defineTool,
8
+ messageOf,
9
+ parseToolArgs,
10
+ type Provider,
11
+ type ProviderChunk,
12
+ type Tool,
13
+ } from "@providerkit/core";
14
+ import {
15
+ bindMemoryTool,
16
+ checkMemoryBinding,
17
+ isMemoryTool,
18
+ memoryPolicy,
19
+ memoryScopes,
20
+ MEMORY_TOOL_NAMES,
21
+ readMemoryBinding,
22
+ recallMemory,
23
+ withMemoryRecall,
24
+ } from "./memory.ts";
25
+ import {
26
+ allModels,
27
+ compactionDefinition,
28
+ compactionId,
29
+ compactionPlan,
30
+ modelConversation,
31
+ } from "./compaction.ts";
32
+ import {
33
+ bindSubagentTool,
34
+ checkSubagentChildren,
35
+ subagentInstructions,
36
+ subagentLimits,
37
+ type SubagentCreation,
38
+ } from "./subagents.ts";
39
+ import {
40
+ isCodeTool,
41
+ programJson,
42
+ programReceipt,
43
+ programReply,
44
+ textBytes,
45
+ type CodeTool,
46
+ } from "./code.ts";
47
+ import { checkRetryTool, readToolRetryPolicy, retryBudget, toolAttempts } from "./tool-retry.ts";
48
+ import {
49
+ GuardChecks,
50
+ GUARDED_CHUNK_LIMIT,
51
+ guardDefinition,
52
+ guardedChunk,
53
+ jsonBytes,
54
+ observeLifecycle,
55
+ refuseGuardedReplay,
56
+ requireGuardVerdicts,
57
+ successfulToolResult,
58
+ toolResultOf,
59
+ } from "./extensions.ts";
60
+ import {
61
+ AGENT_RUNTIME,
62
+ executeDelegation,
63
+ isDelegation,
64
+ specialistTool,
65
+ runtimeOf,
66
+ type AgentRuntime,
67
+ type Delegation,
68
+ type RunStart,
69
+ } from "./delegation.ts";
70
+ import {
71
+ checkHandoffTargets,
72
+ handoffDelegation,
73
+ handoffNote,
74
+ handoffRecord,
75
+ handoffRef,
76
+ isHandoff,
77
+ type Handoff,
78
+ } from "./handoff.ts";
79
+ import {
80
+ RequestJournal,
81
+ isClientTool,
82
+ isInputRequired,
83
+ requestHash,
84
+ type ClientTool,
85
+ } from "./request.ts";
86
+ import { acknowledgeInputs, acceptInputs, inputReceipts } from "./steering.ts";
87
+ import { modelsUsage, readRecoveryPolicy, recoveryToolHash, requireRecovery } from "./recovery.ts";
88
+ import { readInput, readStored, repairConversation, requestOf } from "./input.ts";
89
+ import {
90
+ ExecutionTree,
91
+ Halt,
92
+ authorizeTree,
93
+ emitEvent,
94
+ fail,
95
+ treeUsage,
96
+ nodeId,
97
+ wakeAt,
98
+ openRequests,
99
+ readAnswers,
100
+ requestRecords,
101
+ stopRequests,
102
+ untilAbort,
103
+ type ExecutionScope,
104
+ } from "./tree.ts";
105
+ import {
106
+ checkOptions,
107
+ agentSnapshot,
108
+ completeArguments,
109
+ copyData,
110
+ equalData,
111
+ finalToolResult,
112
+ finalHandoffResult,
113
+ immutableCopy,
114
+ inlineBytes,
115
+ isBase64,
116
+ isEnabledTools,
117
+ isId,
118
+ isNames,
119
+ isRecord,
120
+ isRevision,
121
+ isUsage,
122
+ jsonArguments,
123
+ modelId,
124
+ recordCodeTools,
125
+ readLimits,
126
+ readModelSettings,
127
+ readTreeLimits,
128
+ readSnapshot,
129
+ readTurn,
130
+ snapshotInlineBytes,
131
+ toolId,
132
+ } from "./snapshot.ts";
133
+ import type {
134
+ Agent,
135
+ AgentConfig,
136
+ AgentDefinition,
137
+ AgentEvent,
138
+ CompactionExecution,
139
+ EnabledTools,
140
+ LifecycleContext,
141
+ LifecycleEvent,
142
+ ModelInput,
143
+ MediaRef,
144
+ ModelExecution,
145
+ OperationReceipt,
146
+ ProgramCall,
147
+ ToolExecution,
148
+ ResultSchema,
149
+ RunContext,
150
+ RunDefinition,
151
+ RunOptions,
152
+ RunOutcome,
153
+ RunSnapshot,
154
+ SessionStatus,
155
+ ToolRequest,
156
+ ToolResult,
157
+ } from "./types.ts";
158
+
159
+ /** Reserved for the output contract supplied to defineAgent. */
160
+ export const RESULT_TOOL_NAME = "submit_result";
161
+
162
+ type CompletedModel = Extract<ModelExecution, { status: "completed" }>;
163
+
164
+ /** The same dispatcher writes either a model tool slot or an inner program call. */
165
+ interface ToolSlot {
166
+ get(): ToolExecution;
167
+ set(execution: ToolExecution): void;
168
+ request(): ToolRequest;
169
+ model?: CompletedModel;
170
+ inner?: {
171
+ signal: AbortSignal;
172
+ code: CodeTool;
173
+ start(): void;
174
+ record(result: ToolResult): ToolResult;
175
+ callsLeft(): number;
176
+ outputError?: string;
177
+ };
178
+ }
179
+
180
+ function recordOf(snapshot: RunSnapshot) {
181
+ const saved = copyData(snapshot);
182
+ const receipts: OperationReceipt[] = [];
183
+ const usage = modelsUsage(allModels(saved));
184
+ for (const model of allModels(saved)) {
185
+ for (const attempt of model.interrupted)
186
+ receipts.push({
187
+ kind: "model",
188
+ id: model.id,
189
+ ...attempt,
190
+ status: "interrupted",
191
+ billing: "unknown",
192
+ });
193
+ receipts.push({
194
+ kind: "model",
195
+ ...(saved.compactions.some((entry) => entry.id === model.id)
196
+ ? { purpose: "compaction" as const }
197
+ : {}),
198
+ id: model.id,
199
+ attemptId: model.attemptId,
200
+ status: model.status,
201
+ billing: model.billing,
202
+ usage: model.usage,
203
+ ...(model.status === "completed" && model.turn.source ? { source: model.turn.source } : {}),
204
+ });
205
+ if (model.status !== "completed") continue;
206
+ for (const [index, tool] of model.tools.entries()) {
207
+ const call = model.turn.message.toolCalls?.[index];
208
+ if (!call) continue;
209
+ for (const attempt of tool.interrupted)
210
+ receipts.push({
211
+ kind: "tool",
212
+ id: tool.id,
213
+ callId: call.id,
214
+ ...attempt,
215
+ status: "interrupted",
216
+ });
217
+ for (const attempt of tool.retries)
218
+ receipts.push({
219
+ kind: "tool",
220
+ id: tool.id,
221
+ callId: call.id,
222
+ attemptId: attempt.attemptId,
223
+ result: attempt.result,
224
+ status: "completed",
225
+ });
226
+ for (const inner of tool.calls ?? []) {
227
+ for (const attempt of inner.retries)
228
+ receipts.push({
229
+ kind: "tool",
230
+ id: inner.id,
231
+ parentOperationId: tool.id,
232
+ callId: inner.id,
233
+ attemptId: attempt.attemptId,
234
+ status: "completed",
235
+ result: attempt.result,
236
+ });
237
+ if (inner.status !== "pending")
238
+ receipts.push({
239
+ kind: "tool",
240
+ id: inner.id,
241
+ parentOperationId: tool.id,
242
+ callId: inner.id,
243
+ attemptId: inner.attemptId,
244
+ status: inner.status,
245
+ ...(inner.status === "completed" ? { result: inner.result } : {}),
246
+ });
247
+ }
248
+ if (tool.status === "pending") continue;
249
+ receipts.push({
250
+ kind: saved.delegations.find((journal) => journal.operationId === tool.id)?.kind ?? "tool",
251
+ id: tool.id,
252
+ callId: call.id,
253
+ attemptId: tool.attemptId,
254
+ status: tool.status === "delegating" ? "running" : tool.status,
255
+ ...(tool.status === "completed" ? { result: tool.result } : {}),
256
+ });
257
+ }
258
+ }
259
+ // A root run replaces this with what its append did. Read from a snapshot alone, whether the
260
+ // session has the turn is not known.
261
+ const session: SessionStatus | undefined = saved.session && {
262
+ id: saved.session.id,
263
+ status: "pending",
264
+ };
265
+ return {
266
+ runId: saved.runId,
267
+ attemptId: saved.attemptId,
268
+ usage,
269
+ treeUsage: treeUsage(saved),
270
+ receipts,
271
+ inputs: inputReceipts(saved),
272
+ ...handoffRecord(saved),
273
+ snapshot: saved,
274
+ ...(session ? { session } : {}),
275
+ };
276
+ }
277
+
278
+ // Adapted from OpenAI Agents JS (MIT), agent.ts: infer every registered handoff's output.
279
+ // Ordinary tools contribute nothing; each runtime still validates only its own contract.
280
+ type RegisteredTools = NonNullable<AgentConfig["tools"]>;
281
+ type HandoffOutput<Tool> = Tool extends Handoff<infer Output> ? Output : never;
282
+ type ConfigWithTools<Tools extends RegisteredTools> = Omit<AgentConfig, "tools"> & {
283
+ tools?: Tools;
284
+ };
285
+
286
+ export function defineAgent<T, const Tools extends RegisteredTools = []>(
287
+ definition: ConfigWithTools<Tools> & { output: ResultSchema<T> },
288
+ ): Agent<T | HandoffOutput<Tools[number]>>;
289
+ export function defineAgent<const Tools extends RegisteredTools = []>(
290
+ definition: ConfigWithTools<Tools> & { output?: undefined },
291
+ ): Agent<string | HandoffOutput<Tools[number]>>;
292
+ export function defineAgent<T, const Tools extends RegisteredTools = []>(
293
+ definition: ConfigWithTools<Tools> & { output?: ResultSchema<T> },
294
+ ): Agent<T | string | HandoffOutput<Tools[number]>>;
295
+ export function defineAgent<T, H>(definition: AgentDefinition<T, H>): Agent<T | string | H> {
296
+ const { id, version, instructions, provider } = definition;
297
+ if (
298
+ !isId(id) ||
299
+ !isId(version) ||
300
+ (typeof instructions !== "string" && typeof instructions !== "function") ||
301
+ !provider ||
302
+ typeof provider.createStream !== "function"
303
+ ) {
304
+ throw new TypeError("An agent needs an id, version, instructions and provider.");
305
+ }
306
+ const settings = readModelSettings(definition.modelSettings);
307
+ const memory = memoryPolicy(definition.memory);
308
+ const compaction = compactionDefinition(definition.compaction);
309
+ const summarizer = definition.compaction?.summarize?.provider;
310
+ const toolRetries = readToolRetryPolicy(definition.toolRetries);
311
+ const guardPolicy = guardDefinition(definition.guardrails);
312
+ const guardrails = definition.guardrails && Object.freeze({ ...definition.guardrails });
313
+ const onLifecycle = definition.onLifecycle;
314
+ if (onLifecycle !== undefined && typeof onLifecycle !== "function")
315
+ throw new TypeError("onLifecycle must be a function.");
316
+ const recovery = readRecoveryPolicy(definition.recovery);
317
+ if (recovery && (!isId(provider.id) || !isId(provider.model)))
318
+ throw new TypeError("A recovery profile needs a stable provider id and model.");
319
+ if (definition.enabledTools !== undefined && !isEnabledTools(definition.enabledTools))
320
+ throw new TypeError("enabledTools must be an allow-list or a function returning one.");
321
+ const enabledTools = Array.isArray(definition.enabledTools)
322
+ ? [...definition.enabledTools]
323
+ : definition.enabledTools;
324
+ const limits = readLimits(definition.limits);
325
+ const treeLimits = readTreeLimits(definition.treeLimits);
326
+ const output = definition.output && {
327
+ schema: copyData(definition.output.schema),
328
+ validate: definition.output.validate,
329
+ };
330
+ if (
331
+ output &&
332
+ (!isRecord(output.schema) ||
333
+ output.schema.type !== "object" ||
334
+ typeof output.validate !== "function")
335
+ ) {
336
+ throw new TypeError("An output contract needs an object schema and a runtime validator.");
337
+ }
338
+ const registeredTools = [...(definition.tools ?? [])];
339
+ const codeTools = new Map(registeredTools.filter(isCodeTool).map((tool) => [tool.name, tool]));
340
+ // Keep capability identity for helper grants; approval/dispatch use the bound tools below.
341
+ const capabilities = new Map(registeredTools.map((tool) => [tool.name, tool]));
342
+ for (const code of codeTools.values())
343
+ for (const tool of code.tools) {
344
+ if (capabilities.has(tool.name) && capabilities.get(tool.name) !== tool)
345
+ throw new TypeError(
346
+ `The name ${tool.name} must refer to the same tool object directly and in every code binding.`,
347
+ );
348
+ capabilities.set(tool.name, tool);
349
+ }
350
+ const needsMemory = !!memory || [...capabilities.values()].some(isMemoryTool);
351
+ if (
352
+ [...capabilities.values()].some(
353
+ (tool) => MEMORY_TOOL_NAMES.includes(tool.name) && !isMemoryTool(tool),
354
+ )
355
+ )
356
+ throw new TypeError(
357
+ "memory_search, memory_save and memory_forget are reserved. Register tools from memoryTools().",
358
+ );
359
+ const tools = registeredTools.map((tool) =>
360
+ isDelegation(tool) ? bindSubagentTool(tool, () => agent) : tool,
361
+ );
362
+ if (
363
+ new Set(tools.map((tool) => tool.name)).size !== tools.length ||
364
+ [...capabilities.values()].some((tool) => !isId(tool.name) || tool.name === RESULT_TOOL_NAME)
365
+ ) {
366
+ throw new TypeError(
367
+ `Use unique tool names. ${RESULT_TOOL_NAME} is reserved for the output contract.`,
368
+ );
369
+ }
370
+ if (definition.stopAtTools !== undefined && !isNames(definition.stopAtTools))
371
+ throw new TypeError("stopAtTools must be a list of unique tool names.");
372
+ const stopAtTools = [...(definition.stopAtTools ?? [])];
373
+ for (const name of stopAtTools) {
374
+ const tool = tools.find((tool) => tool.name === name);
375
+ if (!tool || isDelegation(tool) || isHandoff(tool) || isClientTool(tool) || isCodeTool(tool))
376
+ throw new TypeError("stopAtTools must name ordinary tools registered on this agent.");
377
+ }
378
+ for (const tool of tools)
379
+ if (
380
+ !isDelegation(tool) &&
381
+ !isHandoff(tool) &&
382
+ !isClientTool(tool) &&
383
+ !isCodeTool(tool) &&
384
+ tool.isTerminal &&
385
+ !stopAtTools.includes(tool.name)
386
+ )
387
+ stopAtTools.push(tool.name);
388
+ if (output) {
389
+ tools.push(
390
+ defineTool({
391
+ name: RESULT_TOOL_NAME,
392
+ description:
393
+ "Submit the final result. Call this tool alone, after all other work is finished.",
394
+ inputSchema: output.schema,
395
+ validate: output.validate,
396
+ run: async (value) => value,
397
+ summarize: () => "Result accepted.",
398
+ isTerminal: true,
399
+ isReadOnly: true,
400
+ }),
401
+ );
402
+ }
403
+ if (
404
+ [...codeTools.values()].some((code) =>
405
+ code.tools.some((tool) => stopAtTools.includes(tool.name)),
406
+ )
407
+ )
408
+ throw new TypeError("Stopping tools must stay direct, outside code mode.");
409
+ const registry = new ToolRegistry(
410
+ [...new Set([...tools, ...capabilities.values()])].filter(
411
+ (tool): tool is Tool =>
412
+ !isDelegation(tool) && !isHandoff(tool) && !isClientTool(tool) && !isCodeTool(tool),
413
+ ),
414
+ );
415
+ for (const name of recovery?.readOnlyTools ?? [])
416
+ if ((!registry.get(name)?.isReadOnly && !codeTools.has(name)) || name === RESULT_TOOL_NAME)
417
+ throw new TypeError(
418
+ "Recovery readOnlyTools must name ordinary isReadOnly tools registered on this agent.",
419
+ );
420
+ for (const [name, policy] of Object.entries(toolRetries?.tools ?? {})) {
421
+ const tool = registry.get(name);
422
+ if (
423
+ !tool ||
424
+ tool.isTerminal ||
425
+ tool.needsApproval ||
426
+ stopAtTools.includes(name) ||
427
+ (policy.replay === "read-only" && !tool.isReadOnly)
428
+ )
429
+ throw new TypeError(
430
+ "toolRetries must name ordinary non-stopping tools without required approval. Read-only retries need isReadOnly.",
431
+ );
432
+ }
433
+ const delegations = new Map(tools.filter(isDelegation).map((tool) => [tool.name, tool]));
434
+ const handoffs = new Map(tools.filter(isHandoff<H>).map((tool) => [tool.name, tool]));
435
+
436
+ function descriptorFor(
437
+ name: string,
438
+ snapshot: RunSnapshot,
439
+ operationId: string,
440
+ ): Delegation | undefined {
441
+ const handoff = handoffs.get(name);
442
+ if (!handoff) return delegations.get(name);
443
+ const journal = snapshot.delegations.find((entry) => entry.operationId === operationId);
444
+ if (!journal || journal.kind !== "handoff") return undefined;
445
+ if (!equalData(journal.target, handoffRef(handoff.target())))
446
+ throw new TypeError(
447
+ "The saved handoff target or version changed. Restore the registered target.",
448
+ );
449
+ return handoffDelegation(handoff, snapshot, journal);
450
+ }
451
+ const clients = new Map(tools.filter(isClientTool).map((tool) => [tool.name, tool]));
452
+ const names = [...new Set([...capabilities.keys(), ...tools.map((tool) => tool.name)])];
453
+ const directNames = tools.map((tool) => tool.name);
454
+ const definitionsFor = (enabled: readonly string[]) =>
455
+ tools
456
+ .filter((tool) => enabled.includes(tool.name))
457
+ .map((tool) => (isCodeTool(tool) ? tool.definition(enabled) : tool.definition()));
458
+ async function toolHash(name: string): Promise<string> {
459
+ const code = codeTools.get(name);
460
+ if (code)
461
+ return requestHash({
462
+ definition: code.definition(),
463
+ limits: code.limits,
464
+ tools: await Promise.all(code.tools.map(recoveryToolHash)),
465
+ });
466
+ const tool = registry.get(name);
467
+ if (!tool) throw new TypeError("Missing recovery tool.");
468
+ return recoveryToolHash(tool);
469
+ }
470
+ function checkNames(value: unknown): string[] {
471
+ if (!isNames(value) || value.some((name) => !names.includes(name)))
472
+ throw new TypeError("enabledTools must name each registered tool at most once.");
473
+ return [...value];
474
+ }
475
+ if (Array.isArray(enabledTools)) checkNames(enabledTools);
476
+
477
+ // Adapted from OpenAI Agents JS (MIT), agent.ts and tool.ts. Unlike its per-turn
478
+ // callbacks, these resolve once: a restarted worker must see the same prompt and tools.
479
+ async function resolveDefinition(
480
+ start: RunStart,
481
+ options: RunOptions,
482
+ runId: string,
483
+ source?: RunDefinition,
484
+ ): Promise<RunDefinition> {
485
+ const signal = options.signal ?? new AbortController().signal;
486
+ const run: RunContext = Object.freeze({
487
+ agentId: id,
488
+ version,
489
+ runId,
490
+ ...immutableCopy({ history: start.history, input: start.input }),
491
+ context: Object.freeze({ ...options.context }),
492
+ signal,
493
+ });
494
+ const text: unknown = source
495
+ ? source.instructions
496
+ : typeof instructions === "function"
497
+ ? await untilAbort(Promise.resolve(instructions(run)), signal)
498
+ : instructions;
499
+ if (typeof text !== "string") throw new TypeError("instructions must return a string.");
500
+ async function select(selection: EnabledTools | undefined): Promise<string[]> {
501
+ return selection === undefined
502
+ ? [...names]
503
+ : checkNames(
504
+ typeof selection === "function"
505
+ ? await untilAbort(Promise.resolve(selection(run)), signal)
506
+ : selection,
507
+ );
508
+ }
509
+ const allowed = source ? source.enabledTools : await select(enabledTools);
510
+ const selected =
511
+ options.enabledTools === undefined ? allowed : await select(options.enabledTools);
512
+ if (selected.some((name) => name !== RESULT_TOOL_NAME && !allowed.includes(name)))
513
+ throw new TypeError(
514
+ "Run enabledTools may narrow the agent's tools, not enable a disabled tool.",
515
+ );
516
+ // The definition's order is part of the provider's cached prefix, not the allow-list's.
517
+ const enabled = names.filter(
518
+ (name) => selected.includes(name) || (output && name === RESULT_TOOL_NAME),
519
+ );
520
+ // Ported from PydanticAI (MIT), settings.py, merge_model_settings: the run wins.
521
+ // Provider defaults remain in core; passing only set values preserves that first layer.
522
+ const {
523
+ onActivity: _onActivity,
524
+ onRateLimit: _onRateLimit,
525
+ ...modelSettings
526
+ } = {
527
+ ...(source ? source.modelSettings : settings),
528
+ ...readModelSettings(options.modelSettings),
529
+ };
530
+ const choice = modelSettings.toolChoice;
531
+ if (output && choice === "none")
532
+ throw new TypeError(
533
+ "toolChoice none disables submit_result, which a checked-output run needs to finish.",
534
+ );
535
+ if (
536
+ (choice === "required" && enabled.length === 0) ||
537
+ (typeof choice === "object" && !enabled.includes(choice.name))
538
+ )
539
+ throw new TypeError("toolChoice must name an enabled tool; required needs at least one.");
540
+ const toolHashes = Object.fromEntries(
541
+ await Promise.all(
542
+ (recovery?.readOnlyTools ?? []).map(async (name) => {
543
+ return [name, await toolHash(name)] as const;
544
+ }),
545
+ ),
546
+ );
547
+ const retryHashes = Object.fromEntries(
548
+ await Promise.all(
549
+ Object.keys(toolRetries?.tools ?? {}).map(async (name) => {
550
+ const tool = registry.get(name);
551
+ if (!tool) throw new TypeError("Missing retry tool.");
552
+ return [name, await recoveryToolHash(tool)] as const;
553
+ }),
554
+ ),
555
+ );
556
+ return {
557
+ instructions: text,
558
+ ...(memory ? { memory: copyData(memory) } : {}),
559
+ modelSettings,
560
+ enabledTools: enabled,
561
+ stopAtTools: [...stopAtTools],
562
+ ...(codeTools.size ? { codeTools: recordCodeTools(codeTools) } : {}),
563
+ guardrails: copyData(guardPolicy),
564
+ compaction: copyData(compaction),
565
+ toolRetries: toolRetries ? { policy: copyData(toolRetries), toolHashes: retryHashes } : null,
566
+ recovery: recovery
567
+ ? {
568
+ policy: copyData(recovery),
569
+ provider: { id: provider.id, model: provider.model },
570
+ toolHashes,
571
+ modelToolsHash: await requestHash(definitionsFor(enabled)),
572
+ }
573
+ : null,
574
+ };
575
+ }
576
+
577
+ function validateResult(candidate: unknown): T | string {
578
+ // copyData permits absent optional values, but a result must survive a JSON checkpoint.
579
+ if (candidate === undefined)
580
+ throw new TypeError("The result must be a JSON value. Return null instead of undefined.");
581
+ if (output) return output.validate(copyData(candidate));
582
+ if (typeof candidate !== "string" || !candidate.trim())
583
+ throw new TypeError("The model returned no answer.");
584
+ return candidate;
585
+ }
586
+
587
+ // Adapted from OpenAI Agents JS (MIT), result.ts: the active agent processes its own
588
+ // final output. Follow our saved child instead of casting it to the source's output type.
589
+ function completedOutput(snapshot: RunSnapshot): T | string | H {
590
+ if (snapshot.state.status !== "completed")
591
+ throw new TypeError("The run has no completed result.");
592
+ const last = snapshot.models.at(-1);
593
+ const transfer = last?.status === "completed" && finalHandoffResult(snapshot, last);
594
+ if (!transfer) return validateResult(snapshot.state.candidate);
595
+ const name = last.turn.message.toolCalls?.[0]?.name;
596
+ const target = name && handoffs.get(name)?.target();
597
+ if (!target || !equalData(handoffRef(target), handoffRef(transfer.child)))
598
+ throw new TypeError("The completed handoff does not match its registered target.");
599
+ const result = target[AGENT_RUNTIME].hydrate(transfer.child);
600
+ if (result.status !== "completed")
601
+ throw new TypeError("The handoff target has no completed result.");
602
+ return result.output;
603
+ }
604
+
605
+ function requestFor(snapshot: RunSnapshot, model: CompletedModel, index: number): ToolRequest {
606
+ const call = model.turn.message.toolCalls?.[index];
607
+ const tool = model.tools[index];
608
+ if (!call || !tool) fail("invalid_journal", "The tool call is missing from its journal.");
609
+ return {
610
+ agentId: id,
611
+ version,
612
+ runId: snapshot.runId,
613
+ attemptId:
614
+ tool.status === "running" || tool.status === "completed"
615
+ ? tool.attemptId
616
+ : tool.retries.length
617
+ ? `${snapshot.attemptId}/tool-attempt/${tool.retries.length + tool.interrupted.length + 1}`
618
+ : snapshot.attemptId,
619
+ operationId: tool.id,
620
+ ...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
621
+ call,
622
+ arguments: codeTools.has(call.name)
623
+ ? (jsonArguments(call.arguments) ?? {})
624
+ : parseToolArgs(call.arguments),
625
+ };
626
+ }
627
+
628
+ async function needsApproval(
629
+ call: ToolRequest,
630
+ options: RunOptions,
631
+ signal: AbortSignal,
632
+ ): Promise<boolean> {
633
+ if (call.call.name === RESULT_TOOL_NAME) return false;
634
+ const tool =
635
+ tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
636
+ return (
637
+ tool?.needsApproval === true ||
638
+ (await untilAbort(
639
+ Promise.resolve(options.host?.needsApproval?.(immutableCopy(call))),
640
+ signal,
641
+ )) === true
642
+ );
643
+ }
644
+
645
+ function journalFor(
646
+ snapshot: RunSnapshot,
647
+ model: CompletedModel,
648
+ index: number,
649
+ options: RunOptions,
650
+ scope: ExecutionScope,
651
+ signal: AbortSignal,
652
+ effectiveCall?: ToolRequest,
653
+ ): RequestJournal {
654
+ const call = requestFor(snapshot, model, index);
655
+ const execution = model.tools[index];
656
+ if (!execution) throw new TypeError("Missing tool journal.");
657
+ return requestsFor(call, execution, options, scope, signal, effectiveCall);
658
+ }
659
+
660
+ function requestsFor(
661
+ call: ToolRequest,
662
+ execution: ToolExecution,
663
+ options: RunOptions,
664
+ scope: ExecutionScope,
665
+ signal: AbortSignal,
666
+ effectiveCall?: ToolRequest,
667
+ ): RequestJournal {
668
+ const tool =
669
+ tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
670
+ return new RequestJournal(
671
+ execution,
672
+ effectiveCall ?? call,
673
+ options,
674
+ scope,
675
+ signal,
676
+ // The policy hash follows the original model call even when dispatch arguments were edited.
677
+ async () =>
678
+ requestHash({
679
+ definition: tool?.definition() ?? null,
680
+ needsApproval: await needsApproval(call, options, signal),
681
+ kind:
682
+ tool && isHandoff(tool)
683
+ ? "handoff"
684
+ : tool && isDelegation(tool)
685
+ ? "delegation"
686
+ : tool && isClientTool(tool)
687
+ ? "client"
688
+ : "tool",
689
+ ...(tool && isHandoff(tool) ? { target: handoffRef(tool.target()) } : {}),
690
+ ...(tool && isClientTool(tool) ? { resultSchema: tool.resultSchema } : {}),
691
+ }),
692
+ (decision) => {
693
+ if (decision.type === "result") {
694
+ const client = clients.get(call.call.name);
695
+ if (!client) throw new TypeError("This call is not a registered client tool.");
696
+ client.result(decision.value);
697
+ }
698
+ },
699
+ !!guardrails?.toolOutput,
700
+ );
701
+ }
702
+
703
+ // Intake is a tree-wide pre-effect barrier. A saved child receives its decisions in its
704
+ // snapshot before the host may reuse a segment. No browser-supplied route is consulted.
705
+ async function answerRequests(
706
+ snapshot: RunSnapshot,
707
+ options: RunOptions,
708
+ scope: ExecutionScope,
709
+ answers: Readonly<Record<string, unknown>>,
710
+ signal: AbortSignal,
711
+ ): Promise<void> {
712
+ if (snapshot.state.status !== "running" && snapshot.state.status !== "suspended") return;
713
+ signal.throwIfAborted();
714
+ for (const model of snapshot.models) {
715
+ if (model.status !== "completed") continue;
716
+ for (const [index, execution] of model.tools.entries()) {
717
+ if (execution.status === "completed") continue;
718
+ const journal = journalFor(snapshot, model, index, options, scope, signal);
719
+ for (const record of [...(execution.asks ?? [])]) {
720
+ if (record.closed) continue;
721
+ scope.tree.active();
722
+ signal.throwIfAborted();
723
+ if (!record.decision && Object.hasOwn(answers, record.request.id))
724
+ await journal.resolve(record, answers[record.request.id]);
725
+ else await journal.refresh(record);
726
+ }
727
+ }
728
+ }
729
+ for (const entry of snapshot.delegations) {
730
+ const model = snapshot.models.find(
731
+ (model) =>
732
+ model.status === "completed" && model.tools.some((tool) => tool.id === entry.operationId),
733
+ );
734
+ const position =
735
+ model?.status === "completed"
736
+ ? model.tools.findIndex((tool) => tool.id === entry.operationId)
737
+ : -1;
738
+ const name =
739
+ model?.status === "completed" ? model.turn.message.toolCalls?.[position]?.name : undefined;
740
+ const descriptor = name && descriptorFor(name, snapshot, entry.operationId);
741
+ if (!descriptor) continue;
742
+ for (const child of entry.children) {
743
+ if (
744
+ child.snapshot.state.status !== "running" &&
745
+ child.snapshot.state.status !== "suspended"
746
+ )
747
+ continue;
748
+ const specialist = descriptor.specialists.find(
749
+ (agent) =>
750
+ agent.kind === child.snapshot.kind &&
751
+ agent.id === nodeId(child.snapshot) &&
752
+ agent.version === child.snapshot.version,
753
+ );
754
+ if (!specialist) throw new TypeError("Unregistered specialist.");
755
+ await runtimeOf(specialist).answerRequests(
756
+ child.snapshot,
757
+ options,
758
+ {
759
+ tree: scope.tree,
760
+ depth: scope.depth + 1,
761
+ path: [
762
+ ...scope.path,
763
+ { operationId: entry.operationId, key: child.key, runId: child.snapshot.runId },
764
+ ],
765
+ },
766
+ answers,
767
+ signal,
768
+ );
769
+ }
770
+ }
771
+ }
772
+
773
+ async function execute(
774
+ snapshot: RunSnapshot,
775
+ options: RunOptions,
776
+ scope: ExecutionScope,
777
+ answers?: Readonly<Record<string, unknown>>,
778
+ ): Promise<RunOutcome<T | string | H>> {
779
+ const host = options.host;
780
+ const limits = snapshot.limits;
781
+ const deadline = snapshot.startedAt + limits.elapsedMs;
782
+ const timeout = new AbortController();
783
+ const signal = AbortSignal.any([
784
+ scope.tree.signal,
785
+ timeout.signal,
786
+ ...(options.signal ? [options.signal] : []),
787
+ ]);
788
+ const timer = setTimeout(
789
+ () => timeout.abort(new Error("The run reached its time limit.")),
790
+ Math.max(0, deadline - Date.now()),
791
+ );
792
+ let release = () => {};
793
+ let completed: { output: T | string | H } | undefined;
794
+ let started = false;
795
+
796
+ function active(): void {
797
+ scope.tree.active();
798
+ if (options.signal?.aborted) throw new Halt({ status: "cancelled" });
799
+ if (timeout.signal.aborted || Date.now() >= deadline)
800
+ throw new Halt({ status: "limited", limit: "elapsedMs" });
801
+ }
802
+
803
+ function emit(event: AgentEvent): void {
804
+ emitEvent(options, event);
805
+ }
806
+
807
+ const save = () => scope.tree.save();
808
+ const callbackContext: LifecycleContext = Object.freeze({
809
+ agentId: id,
810
+ version,
811
+ runId: snapshot.runId,
812
+ attemptId: snapshot.attemptId,
813
+ context: Object.freeze({ ...options.context }),
814
+ signal,
815
+ });
816
+ const observe = (event: LifecycleEvent, callSignal = signal) =>
817
+ observeLifecycle(
818
+ [onLifecycle, options.onLifecycle],
819
+ event,
820
+ callSignal === signal ? callbackContext : { ...callbackContext, signal: callSignal },
821
+ );
822
+ const guards = new GuardChecks(snapshot, guardrails, callbackContext, save, active);
823
+
824
+ function slotFor(model: CompletedModel, index: number): ToolSlot {
825
+ return {
826
+ model,
827
+ get() {
828
+ const execution = model.tools[index];
829
+ if (!execution) fail("invalid_journal", "The tool call is missing from its journal.");
830
+ return execution;
831
+ },
832
+ set(execution) {
833
+ model.tools[index] = execution;
834
+ },
835
+ request: () => requestFor(snapshot, model, index),
836
+ };
837
+ }
838
+
839
+ function invocationActive(slot: ToolSlot): void {
840
+ active();
841
+ slot.inner?.signal.throwIfAborted();
842
+ }
843
+
844
+ function toolChecks(callSignal: AbortSignal): GuardChecks {
845
+ return callSignal === signal
846
+ ? guards
847
+ : new GuardChecks(
848
+ snapshot,
849
+ guardrails,
850
+ { ...callbackContext, signal: callSignal },
851
+ save,
852
+ () => {
853
+ active();
854
+ callSignal.throwIfAborted();
855
+ },
856
+ );
857
+ }
858
+
859
+ async function beforeTool(request: ToolRequest, callSignal = signal): Promise<void> {
860
+ await toolChecks(callSignal).check(
861
+ "toolInput",
862
+ request.operationId,
863
+ request.attemptId,
864
+ request,
865
+ );
866
+ active();
867
+ callSignal.throwIfAborted();
868
+ await observe({ type: "tool_start", request }, callSignal);
869
+ active();
870
+ callSignal.throwIfAborted();
871
+ }
872
+
873
+ async function withToolError(
874
+ request: ToolRequest,
875
+ work: () => Promise<void>,
876
+ callSignal = signal,
877
+ ): Promise<void> {
878
+ try {
879
+ await work();
880
+ } catch (error) {
881
+ await observe({ type: "tool_error", request }, callSignal);
882
+ throw error;
883
+ }
884
+ }
885
+
886
+ function restart(
887
+ kind: "model" | "tool",
888
+ operationId: string,
889
+ previousAttemptId: string,
890
+ attemptId = snapshot.attemptId,
891
+ ): void {
892
+ // Adapted from Vercel AI SDK (Apache-2.0), workflow/do-stream-step.ts: reset the
893
+ // current display before replacement output. Unlike reset-step, identity stays explicit.
894
+ emit({
895
+ type: "operation_restart",
896
+ kind,
897
+ runId: snapshot.runId,
898
+ operationId,
899
+ previousAttemptId,
900
+ attemptId,
901
+ });
902
+ }
903
+
904
+ async function checkToolRecovery(
905
+ model: CompletedModel,
906
+ index: number,
907
+ previous: number,
908
+ ): Promise<void> {
909
+ const execution = model.tools[index];
910
+ if (!execution) fail("invalid_journal", "The tool call is missing from its journal.");
911
+ const request = requestFor(snapshot, model, index);
912
+ const tool = registry.get(request.call.name);
913
+ const recorded = snapshot.definition.recovery;
914
+ const budget = retryBudget(snapshot.definition.toolRetries, request.call.name);
915
+ if (budget && previous + 1 >= budget.maxAttempts)
916
+ fail(
917
+ "tool_retry_exhausted",
918
+ "This call reached its tool attempt limit. Reconcile the saved attempts with the host.",
919
+ execution.id,
920
+ );
921
+ requireRecovery(
922
+ !!tool?.isReadOnly &&
923
+ recorded?.policy.readOnlyTools?.includes(request.call.name) === true &&
924
+ !execution.asks?.length &&
925
+ !!host?.beforeTool,
926
+ previous,
927
+ recorded,
928
+ execution.id,
929
+ );
930
+ if (!tool || (await recoveryToolHash(tool)) !== recorded?.toolHashes[tool.name])
931
+ fail(
932
+ "recovery_definition_changed",
933
+ "The interrupted tool's definition changed. Reconcile it with the host before continuing.",
934
+ execution.id,
935
+ );
936
+ active();
937
+ }
938
+
939
+ async function recoverTools(model: CompletedModel): Promise<void> {
940
+ for (const [index, execution] of model.tools.entries()) {
941
+ if (execution.status !== "running") continue;
942
+ const code = codeTools.get(model.turn.message.toolCalls?.[index]?.name ?? "");
943
+ if (code) {
944
+ const calls = execution.calls ?? [];
945
+ const unknown = calls.find(
946
+ (call) => call.status === "running" && !registry.get(call.name)?.isReadOnly,
947
+ );
948
+ if (unknown)
949
+ fail(
950
+ "interrupted_operation",
951
+ "This inner call started but has no saved result. Reconcile its effect with the host; the program will not replay it.",
952
+ unknown.id,
953
+ );
954
+ refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
955
+ const restartable =
956
+ calls.every((call) => registry.get(call.name)?.isReadOnly && !call.asks?.length) &&
957
+ !execution.asks?.length &&
958
+ snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) &&
959
+ !!host?.beforeTool &&
960
+ toolAttempts(execution) < (snapshot.definition.recovery?.policy.maxAttempts ?? 0);
961
+ for (const [position, call] of calls.entries()) {
962
+ if (call.status === "completed") continue;
963
+ calls[position] = {
964
+ ...call,
965
+ status: "completed",
966
+ result: {
967
+ ok: false,
968
+ kind: "interrupted",
969
+ content: call.started
970
+ ? "This read stopped before its result was saved. It changed nothing."
971
+ : "This call did not start. It changed nothing.",
972
+ },
973
+ };
974
+ }
975
+ if (restartable) {
976
+ if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
977
+ fail(
978
+ "recovery_definition_changed",
979
+ "The code tool's bindings or limits changed. Restore the saved definition before restarting.",
980
+ execution.id,
981
+ );
982
+ model.tools[index] = {
983
+ id: execution.id,
984
+ status: "pending",
985
+ previousAttemptId: execution.attemptId,
986
+ interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
987
+ retries: execution.retries,
988
+ calls,
989
+ };
990
+ await save();
991
+ } else
992
+ await finishTool(model, index, requestFor(snapshot, model, index), code.close(calls));
993
+ continue;
994
+ }
995
+ refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
996
+ await checkToolRecovery(
997
+ model,
998
+ index,
999
+ execution.interrupted.length + execution.retries.length,
1000
+ );
1001
+ model.tools[index] = {
1002
+ id: execution.id,
1003
+ status: "pending",
1004
+ previousAttemptId: execution.attemptId,
1005
+ retries: execution.retries,
1006
+ interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
1007
+ };
1008
+ }
1009
+ }
1010
+
1011
+ function usedTools(): number {
1012
+ return snapshot.models.reduce(
1013
+ (count, model) =>
1014
+ count +
1015
+ (model.status === "completed"
1016
+ ? model.tools.reduce(
1017
+ (total, tool) =>
1018
+ total +
1019
+ toolAttempts(tool) +
1020
+ (tool.calls ?? []).reduce(
1021
+ (innerTotal, call) => innerTotal + 1 + call.retries.length,
1022
+ 0,
1023
+ ),
1024
+ 0,
1025
+ )
1026
+ : 0),
1027
+ 0,
1028
+ );
1029
+ }
1030
+
1031
+ async function checkToolRetry(slot: ToolSlot): Promise<void> {
1032
+ const execution = slot.get();
1033
+ const recorded = snapshot.definition.toolRetries;
1034
+ if (!recorded) fail("invalid_journal", "Missing tool retry policy.");
1035
+ const request = slot.request();
1036
+ await checkRetryTool(registry.get(request.call.name), recorded, execution);
1037
+ if (
1038
+ !host?.beforeTool ||
1039
+ (await needsApproval(request, options, slot.inner?.signal ?? signal))
1040
+ )
1041
+ fail(
1042
+ "tool_retry_unsafe",
1043
+ "A retry needs current host authorization and cannot reuse or open an approval.",
1044
+ execution.id,
1045
+ );
1046
+ invocationActive(slot);
1047
+ }
1048
+
1049
+ async function retryTool(slot: ToolSlot): Promise<boolean> {
1050
+ const execution = slot.get();
1051
+ if (
1052
+ execution.status !== "completed" ||
1053
+ execution.result.ok ||
1054
+ execution.asks?.length ||
1055
+ !["failed", "timeout"].includes(execution.result.kind)
1056
+ )
1057
+ return false;
1058
+ const request = slot.request();
1059
+ const policy = retryBudget(snapshot.definition.toolRetries, request.call.name);
1060
+ const recoveryCeiling = execution.interrupted.length
1061
+ ? snapshot.definition.recovery?.policy.maxAttempts
1062
+ : undefined;
1063
+ if (
1064
+ !policy ||
1065
+ toolAttempts(execution) >=
1066
+ Math.min(policy.maxAttempts, recoveryCeiling ?? policy.maxAttempts)
1067
+ )
1068
+ return false;
1069
+ invocationActive(slot);
1070
+ if (slot.inner && slot.inner.callsLeft() <= 0) return false;
1071
+ if (usedTools() >= limits.toolCalls) {
1072
+ throw new Halt({ status: "limited", limit: "toolCalls" });
1073
+ }
1074
+ await checkToolRetry(slot);
1075
+ let reconciliation: string | undefined;
1076
+ if (policy.replay === "reconcile") {
1077
+ const reconcile = host?.reconcileToolRetry;
1078
+ if (!reconcile)
1079
+ fail(
1080
+ "tool_retry_unsafe",
1081
+ "This failed call needs host reconciliation before it can be repeated.",
1082
+ execution.id,
1083
+ );
1084
+ const verdict = await untilAbort(
1085
+ Promise.resolve(
1086
+ reconcile(immutableCopy({ request, result: execution.result }), callbackContext),
1087
+ ),
1088
+ slot.inner?.signal ?? signal,
1089
+ );
1090
+ invocationActive(slot);
1091
+ if (verdict?.outcome !== "not_run" || !isId(verdict.receipt))
1092
+ fail(
1093
+ "tool_retry_unsafe",
1094
+ "The host could not confirm that the failed call did not run. Reconcile its effect before continuing.",
1095
+ execution.id,
1096
+ );
1097
+ reconciliation = verdict.receipt;
1098
+ }
1099
+ // Guest calls can reserve the remaining budget while host reconciliation is awaited.
1100
+ invocationActive(slot);
1101
+ if (slot.inner && slot.inner.callsLeft() <= 0) return false;
1102
+ slot.set({
1103
+ id: execution.id,
1104
+ status: "pending",
1105
+ previousAttemptId: execution.attemptId,
1106
+ interrupted: execution.interrupted,
1107
+ retries: [
1108
+ ...execution.retries,
1109
+ {
1110
+ attemptId: execution.attemptId,
1111
+ arguments: copyData(request.arguments),
1112
+ result: execution.result,
1113
+ ...(reconciliation ? { reconciliation } : {}),
1114
+ },
1115
+ ],
1116
+ });
1117
+ // Retain the failure and reconciliation before reserving another attempt.
1118
+ await save();
1119
+ return true;
1120
+ }
1121
+
1122
+ async function finishTool(
1123
+ model: CompletedModel,
1124
+ index: number,
1125
+ request: ToolRequest,
1126
+ result: ToolResult,
1127
+ ): Promise<void> {
1128
+ return finishExecution(slotFor(model, index), request, result);
1129
+ }
1130
+
1131
+ async function finishExecution(
1132
+ slot: ToolSlot,
1133
+ request: ToolRequest,
1134
+ result: ToolResult,
1135
+ ): Promise<void> {
1136
+ if (!result.ok && (result.kind === "cancelled" || result.kind === "denied")) {
1137
+ for (const record of slot.get().asks ?? [])
1138
+ if (!record.decision && !record.closed) record.closed = "stopped";
1139
+ // A cancelled coordination call cannot leave suspended children under a completed
1140
+ // tool receipt. Already settled children and their usage remain untouched.
1141
+ const delegation = snapshot.delegations.find(
1142
+ (entry) => entry.operationId === request.operationId,
1143
+ );
1144
+ for (const child of delegation?.children ?? []) stopRequests(child.snapshot);
1145
+ // Once a target was admitted, it owns this conversation. Denying a renewed transfer
1146
+ // stops that conversation; it cannot buy a new source turn after target effects.
1147
+ if (delegation?.kind === "handoff" && delegation.children.length > 0)
1148
+ snapshot.state = { status: "cancelled" };
1149
+ }
1150
+ const edited = slot
1151
+ .get()
1152
+ .asks?.some(
1153
+ (record) =>
1154
+ !record.closed &&
1155
+ record.decision?.type === "approve" &&
1156
+ record.decision.arguments !== undefined,
1157
+ );
1158
+ if (edited && !codeTools.has(request.call.name))
1159
+ result = {
1160
+ ...result,
1161
+ content: `${result.content}\nThe reviewer replaced the tool arguments before this call.`,
1162
+ };
1163
+ const callSignal = slot.inner?.signal ?? signal;
1164
+ const checks = toolChecks(callSignal);
1165
+ await observe({ type: "tool_end", request, result }, callSignal);
1166
+ invocationActive(slot);
1167
+ if (
1168
+ guardPolicy?.stages.includes("toolOutput") &&
1169
+ jsonBytes(result) > guardPolicy.maxOutputBytes
1170
+ )
1171
+ await checks.overflow("toolOutput", request.operationId, request.attemptId);
1172
+ await checks.check("toolOutput", request.operationId, request.attemptId, {
1173
+ request,
1174
+ result,
1175
+ });
1176
+ invocationActive(slot);
1177
+ // Check after callbacks: another concurrent result may have consumed the remaining bytes.
1178
+ if (
1179
+ result.ok &&
1180
+ result.images &&
1181
+ snapshotInlineBytes(snapshot) +
1182
+ inlineBytes(
1183
+ [
1184
+ {
1185
+ role: "tool",
1186
+ name: request.call.name,
1187
+ toolCallId: request.call.id,
1188
+ content: result.content,
1189
+ images: result.images,
1190
+ },
1191
+ ],
1192
+ "",
1193
+ ) >
1194
+ limits.inlineBytes
1195
+ )
1196
+ fail(
1197
+ "tool_media_limit",
1198
+ "Tool images exceed this run's inline byte limit. Return fewer or smaller images before starting new work.",
1199
+ request.operationId,
1200
+ );
1201
+ if (slot.inner) result = slot.inner.record(result);
1202
+ const previous = slot.get();
1203
+ slot.set({
1204
+ interrupted: previous.interrupted,
1205
+ retries: previous.retries,
1206
+ asks: previous.asks,
1207
+ calls: previous.calls,
1208
+ id: request.operationId,
1209
+ attemptId: request.attemptId,
1210
+ status: "completed",
1211
+ result,
1212
+ });
1213
+ await save();
1214
+ emit({ type: "tool_result", request, result });
1215
+ }
1216
+
1217
+ async function runTool(
1218
+ slot: ToolSlot,
1219
+ request: ToolRequest,
1220
+ tool: Tool | undefined,
1221
+ parallel: boolean,
1222
+ ): Promise<void> {
1223
+ invocationActive(slot);
1224
+ const callSignal = slot.inner?.signal ?? signal;
1225
+ let result: ToolResult;
1226
+ if (!tool) {
1227
+ result = {
1228
+ ok: false,
1229
+ kind: "unknown_tool",
1230
+ content: `Unknown tool "${request.call.name}". Choose one of the provided tools.`,
1231
+ };
1232
+ } else if (!completeArguments(request.call.arguments)) {
1233
+ result = {
1234
+ ok: false,
1235
+ kind: "invalid_input",
1236
+ content: "Tool arguments must be one complete JSON object. Send the full object again.",
1237
+ };
1238
+ } else if (tool.isTerminal && slot.model?.tools.length !== 1) {
1239
+ result = {
1240
+ ok: false,
1241
+ kind: "invalid_input",
1242
+ content: `Call ${tool.name} alone, after the other tool results arrive.`,
1243
+ };
1244
+ } else {
1245
+ // The barrier can return on abort before its callback unwinds. Retain that callback
1246
+ // so a program cannot finish while a late guard or tool can still write a receipt.
1247
+ let dispatch: Promise<Awaited<ReturnType<Tool["invoke"]>>> | undefined;
1248
+ async function invoke() {
1249
+ invocationActive(slot);
1250
+ const journal = requestsFor(slot.request(), slot.get(), options, scope, callSignal);
1251
+ try {
1252
+ await beforeTool(request, callSignal);
1253
+ if (slot.get().retries.length) await checkToolRetry(slot);
1254
+ await journal.recheck(request);
1255
+ invocationActive(slot);
1256
+ if (slot.inner) {
1257
+ slot.inner.start();
1258
+ if (!tool?.isReadOnly) await save();
1259
+ invocationActive(slot);
1260
+ await journal.recheck(request);
1261
+ invocationActive(slot);
1262
+ }
1263
+ emit({ type: "tool_start", request });
1264
+ invocationActive(slot);
1265
+ // Observers and checkpoints can expire an approval or revoke ownership.
1266
+ // Reauthorize after them, with no further callback before the actual invocation.
1267
+ await journal.recheck(request);
1268
+ await journal.assertFresh();
1269
+ invocationActive(slot);
1270
+ } catch (error) {
1271
+ if (!slot.inner && error instanceof Halt && error.state.status === "suspended")
1272
+ slot.set({
1273
+ id: request.operationId,
1274
+ status: "pending",
1275
+ interrupted: slot.get().interrupted,
1276
+ retries: slot.get().retries,
1277
+ asks: slot.get().asks,
1278
+ });
1279
+ throw error;
1280
+ }
1281
+ const records = slot.get().asks ?? [];
1282
+ const answers = Object.fromEntries(
1283
+ records
1284
+ .filter(
1285
+ (record) =>
1286
+ !record.closed &&
1287
+ record.request.ask.type === "question" &&
1288
+ record.decision?.type === "answer",
1289
+ )
1290
+ .map((record) => [
1291
+ record.request.ask.type === "question" ? record.request.ask.key : "",
1292
+ record.decision?.type === "answer" ? record.decision.answer : undefined,
1293
+ ]),
1294
+ );
1295
+ const decision = [...records]
1296
+ .reverse()
1297
+ .find((record) => !record.closed && record.decision)?.decision;
1298
+ if (!tool) throw new TypeError("Missing dispatched tool.");
1299
+ return untilAbort(
1300
+ bindMemoryTool(tool, options.memory, snapshot, request).invoke(
1301
+ copyData(request.arguments),
1302
+ {
1303
+ ...options.context,
1304
+ answers: immutableCopy(answers),
1305
+ decision: immutableCopy(decision),
1306
+ runId: snapshot.runId,
1307
+ attemptId: request.attemptId,
1308
+ operationId: request.operationId,
1309
+ parentOperationId: request.parentOperationId,
1310
+ callId: request.call.id,
1311
+ signal: callSignal,
1312
+ },
1313
+ ),
1314
+ callSignal,
1315
+ );
1316
+ }
1317
+ let outcome;
1318
+ try {
1319
+ outcome = await scope.tree.invokeTool(parallel, callSignal, () => {
1320
+ dispatch = invoke();
1321
+ return dispatch;
1322
+ });
1323
+ } catch (error) {
1324
+ if (slot.inner && dispatch) await dispatch.catch(() => {});
1325
+ throw error;
1326
+ }
1327
+ // Run/tree stops never buy another model turn. Program-only abort is settled below.
1328
+ if (!outcome.ok) active();
1329
+ if (
1330
+ !outcome.ok &&
1331
+ isMemoryTool(tool) &&
1332
+ outcome.cause instanceof Error &&
1333
+ outcome.cause.name === "MemoryScopeError"
1334
+ )
1335
+ fail(
1336
+ "memory_scope_violation",
1337
+ "Memory returned another scope's data. Fix the store before continuing.",
1338
+ request.operationId,
1339
+ );
1340
+ if (!outcome.ok && outcome.kind === "failed" && isInputRequired(outcome.cause)) {
1341
+ if (slot.inner) {
1342
+ result = {
1343
+ ok: false,
1344
+ kind: "denied",
1345
+ 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."}`,
1346
+ };
1347
+ await finishExecution(slot, request, result);
1348
+ return;
1349
+ }
1350
+ if (slot.get().retries.length)
1351
+ fail(
1352
+ "tool_retry_unsafe",
1353
+ "A retried call requested input. Reconcile it with the host; retries cannot create request replay paths.",
1354
+ request.operationId,
1355
+ );
1356
+ slot.set({
1357
+ id: request.operationId,
1358
+ status: "pending",
1359
+ asks: slot.get().asks,
1360
+ retries: slot.get().retries,
1361
+ interrupted: slot.get().interrupted,
1362
+ });
1363
+ const journal = requestsFor(request, slot.get(), options, scope, signal);
1364
+ const previous = journal.latest(outcome.cause.ask);
1365
+ if (previous?.decision) previous.closed = "invalid";
1366
+ await journal.open(
1367
+ outcome.cause.ask,
1368
+ outcome.cause.problem
1369
+ ? { code: "invalid_answer", message: outcome.cause.problem }
1370
+ : undefined,
1371
+ );
1372
+ return;
1373
+ }
1374
+ try {
1375
+ if (slot.inner && outcome.ok) {
1376
+ try {
1377
+ if (outcome.output !== undefined) programJson(outcome.output);
1378
+ result = { ok: true, content: outcome.summary, output: outcome.output };
1379
+ } catch {
1380
+ slot.inner.outputError =
1381
+ "The call ran but returned a non-JSON value. Check its effect before calling it again.";
1382
+ result = { ok: true, content: slot.inner.outputError };
1383
+ }
1384
+ } else
1385
+ result =
1386
+ tool.name === RESULT_TOOL_NAME && outcome.ok
1387
+ ? { ok: true, content: outcome.summary }
1388
+ : toolResultOf(outcome);
1389
+ } catch {
1390
+ fail(
1391
+ "invalid_tool_output",
1392
+ "The tool returned unsavable data or unsupported content. Return JSON or core text/image parts.",
1393
+ request.operationId,
1394
+ );
1395
+ }
1396
+ if (outcome.ok && tool.name === RESULT_TOOL_NAME && result.ok)
1397
+ result.final = { candidate: copyData(request.arguments) };
1398
+ if (outcome.ok && snapshot.definition.stopAtTools.includes(tool.name)) {
1399
+ try {
1400
+ const candidate = output ? copyData(outcome.output) : outcome.summary;
1401
+ validateResult(candidate);
1402
+ result = { ...result, ok: true, final: { candidate } };
1403
+ } catch (error) {
1404
+ result = {
1405
+ ok: false,
1406
+ kind: "invalid_output",
1407
+ content: `The tool result did not pass the output check: ${messageOf(error)}`,
1408
+ };
1409
+ }
1410
+ }
1411
+ }
1412
+ await finishExecution(slot, request, result);
1413
+ active();
1414
+ }
1415
+
1416
+ function canParallel(
1417
+ request: ToolRequest,
1418
+ tool: Tool | undefined,
1419
+ execution: ToolExecution,
1420
+ ): boolean {
1421
+ return (
1422
+ !guardrails?.toolInput &&
1423
+ !guardrails?.toolOutput &&
1424
+ !retryBudget(snapshot.definition.toolRetries, request.call.name) &&
1425
+ tool?.isConcurrencySafe === true &&
1426
+ snapshot.definition.enabledTools.includes(tool.name) &&
1427
+ (request.parentOperationId !== undefined || directNames.includes(tool.name)) &&
1428
+ !tool.needsApproval &&
1429
+ !host?.needsApproval &&
1430
+ !execution.asks?.length &&
1431
+ !tool.isTerminal &&
1432
+ host?.canRunConcurrently?.(immutableCopy(request)) === true
1433
+ );
1434
+ }
1435
+
1436
+ async function runProgram(
1437
+ model: CompletedModel,
1438
+ index: number,
1439
+ request: ToolRequest,
1440
+ code: CodeTool,
1441
+ ): Promise<void> {
1442
+ const slot = slotFor(model, index);
1443
+ const previous = slot.get();
1444
+ if (previous.interrupted.length) {
1445
+ requireRecovery(
1446
+ snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) === true &&
1447
+ !!host?.beforeTool &&
1448
+ !previous.asks?.length &&
1449
+ (previous.calls ?? []).every(
1450
+ (call) =>
1451
+ call.status === "completed" &&
1452
+ registry.get(call.name)?.isReadOnly &&
1453
+ !call.asks?.length,
1454
+ ),
1455
+ previous.interrupted.length - 1,
1456
+ snapshot.definition.recovery,
1457
+ previous.id,
1458
+ );
1459
+ if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
1460
+ fail(
1461
+ "recovery_definition_changed",
1462
+ "The code bindings changed. Restore the saved definition before restarting.",
1463
+ previous.id,
1464
+ );
1465
+ }
1466
+ const calls = previous.calls ?? [];
1467
+ slot.set({
1468
+ id: request.operationId,
1469
+ attemptId: request.attemptId,
1470
+ status: "running",
1471
+ calls,
1472
+ asks: previous.asks,
1473
+ interrupted: previous.interrupted,
1474
+ retries: previous.retries,
1475
+ });
1476
+ await save();
1477
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
1478
+ try {
1479
+ await beforeTool(request);
1480
+ await requests.recheck(request);
1481
+ active();
1482
+ if (previous.status === "pending" && previous.previousAttemptId)
1483
+ restart("tool", request.operationId, previous.previousAttemptId, request.attemptId);
1484
+ emit({ type: "tool_start", request });
1485
+ await requests.recheck(request);
1486
+ await requests.assertFresh();
1487
+ active();
1488
+ } catch (error) {
1489
+ if (error instanceof Halt && error.state.status === "suspended")
1490
+ slot.set({ ...previous, asks: slot.get().asks });
1491
+ throw error;
1492
+ }
1493
+ const end = new AbortController();
1494
+ const programSignal = AbortSignal.any([signal, end.signal]);
1495
+ const programDeadline = Math.min(
1496
+ Date.now() + code.limits.timeoutMs,
1497
+ deadline,
1498
+ snapshot.tree.startedAt + snapshot.tree.limits.elapsedMs,
1499
+ );
1500
+ const timer = setTimeout(
1501
+ () => end.abort(new Error("The program reached its time limit.")),
1502
+ Math.max(0, programDeadline - Date.now()),
1503
+ );
1504
+ const enabled = code.tools.filter((tool) =>
1505
+ snapshot.definition.enabledTools.includes(tool.name),
1506
+ );
1507
+ const gate = createGate(limits.parallelTools);
1508
+ const jobs: Promise<string>[] = [];
1509
+ let barrier = Promise.resolve();
1510
+ let settled = Promise.resolve();
1511
+ let fatal: unknown;
1512
+ let closed = false;
1513
+ const reject = (kind: string, message: string) =>
1514
+ JSON.stringify({ ok: false, error: { kind, message } });
1515
+ const stopped = (call: ProgramCall): ToolResult => ({
1516
+ ok: false,
1517
+ kind: "aborted",
1518
+ content: call.started
1519
+ ? "The program stopped. This call may have partly run. Check its effect before repeating it."
1520
+ : "The program stopped before this call started. It did not run.",
1521
+ });
1522
+ const count = () =>
1523
+ calls
1524
+ .filter((call) => call.programAttemptId === request.attemptId)
1525
+ .reduce((total, call) => total + 1 + call.retries.length, 0);
1526
+ const bridge = {
1527
+ tools: enabled,
1528
+ signal: programSignal,
1529
+ deadline: programDeadline,
1530
+ calls,
1531
+ toolCallsLeft: () =>
1532
+ Math.max(0, Math.min(code.limits.calls - count(), limits.toolCalls - usedTools() - 1)),
1533
+ call(name: string, input: string): Promise<string> {
1534
+ if (closed || programSignal.aborted)
1535
+ return Promise.resolve(
1536
+ reject("aborted", "The program has finished. No more calls can start."),
1537
+ );
1538
+ const tool = enabled.find((tool) => tool.name === name);
1539
+ if (!tool)
1540
+ return Promise.resolve(
1541
+ reject("disabled_tool", "This tool is not bound and enabled for this program."),
1542
+ );
1543
+ if (tool.needsApproval || tool.isTerminal)
1544
+ return Promise.resolve(
1545
+ reject("denied", "This control tool must be called directly, outside code."),
1546
+ );
1547
+ const arguments_ =
1548
+ typeof input === "string" && textBytes(input) <= code.limits.callInputBytes
1549
+ ? jsonArguments(input)
1550
+ : undefined;
1551
+ if (!arguments_)
1552
+ return Promise.resolve(
1553
+ reject(
1554
+ "invalid_input",
1555
+ `Pass one JSON object within ${code.limits.callInputBytes} bytes.`,
1556
+ ),
1557
+ );
1558
+ if (bridge.toolCallsLeft() === 0)
1559
+ return Promise.resolve(
1560
+ reject(
1561
+ "denied",
1562
+ "The program has no tool calls left. Return what you have; the final direct call is reserved.",
1563
+ ),
1564
+ );
1565
+ // Admission and budget reservation are synchronous. Promise.all cannot overspend.
1566
+ const position = calls.length;
1567
+ const operationId = `${request.operationId}/call/${position + 1}`;
1568
+ let call: ProgramCall = {
1569
+ id: operationId,
1570
+ attemptId: request.attemptId,
1571
+ programAttemptId: request.attemptId,
1572
+ name,
1573
+ arguments: arguments_,
1574
+ status: "pending",
1575
+ started: false,
1576
+ interrupted: [],
1577
+ retries: [],
1578
+ };
1579
+ calls.push(call);
1580
+ let reply = reject("aborted", "The call did not finish.");
1581
+ const inner: ToolSlot = {
1582
+ get: () => call,
1583
+ set(execution) {
1584
+ if (execution.status === "delegating" || execution.calls !== undefined)
1585
+ throw new TypeError("A program may only call ordinary tools.");
1586
+ call = {
1587
+ ...execution,
1588
+ name,
1589
+ arguments: arguments_,
1590
+ programAttemptId: request.attemptId,
1591
+ attemptId:
1592
+ execution.status === "pending"
1593
+ ? `${request.attemptId}/call/${position + 1}/attempt/${execution.retries.length + 1}`
1594
+ : execution.attemptId,
1595
+ started: call.started,
1596
+ bytes: execution.status === "pending" ? undefined : call.bytes,
1597
+ };
1598
+ calls[position] = call;
1599
+ },
1600
+ request: () => ({
1601
+ agentId: id,
1602
+ version,
1603
+ runId: snapshot.runId,
1604
+ attemptId:
1605
+ call.status === "pending" && call.retries.length
1606
+ ? `${request.attemptId}/call/${position + 1}/attempt/${call.retries.length + 1}`
1607
+ : call.attemptId,
1608
+ operationId,
1609
+ parentOperationId: request.operationId,
1610
+ ...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
1611
+ call: { id: operationId, name, arguments: input },
1612
+ arguments: copyData(arguments_),
1613
+ }),
1614
+ inner: {
1615
+ signal: programSignal,
1616
+ code,
1617
+ callsLeft: () => bridge.toolCallsLeft(),
1618
+ start() {
1619
+ call = {
1620
+ id: call.id,
1621
+ name,
1622
+ arguments: arguments_,
1623
+ programAttemptId: request.attemptId,
1624
+ interrupted: call.interrupted,
1625
+ retries: call.retries,
1626
+ asks: call.asks,
1627
+ status: "running",
1628
+ attemptId: inner.request().attemptId,
1629
+ started: true,
1630
+ };
1631
+ calls[position] = call;
1632
+ },
1633
+ record(result) {
1634
+ const receipt = programReceipt(result);
1635
+ call.bytes = receipt.bytes;
1636
+ reply = inner.inner?.outputError
1637
+ ? reject("invalid_output", inner.inner.outputError)
1638
+ : programReply(result, code.limits.callOutputBytes);
1639
+ return receipt.result;
1640
+ },
1641
+ },
1642
+ };
1643
+ let concurrent = false;
1644
+ const work = (async () => {
1645
+ let releaseCall = () => {};
1646
+ try {
1647
+ // Synchronous admission is host work too: a throw must settle its pending call.
1648
+ concurrent = canParallel(inner.request(), tool, call);
1649
+ await (concurrent ? barrier : settled);
1650
+ releaseCall = await gate.acquire(programSignal);
1651
+ do {
1652
+ invocationActive(inner);
1653
+ let effective = inner.request();
1654
+ const journal = requestsFor(effective, call, options, scope, programSignal);
1655
+ if (await needsApproval(effective, options, programSignal)) {
1656
+ let refusal: ToolResult | undefined;
1657
+ if (!host?.prepareRequest || !host.beforeTool)
1658
+ refusal = {
1659
+ ok: false,
1660
+ kind: "denied",
1661
+ content: "This call needs a person's approval, and code cannot wait for one.",
1662
+ };
1663
+ else {
1664
+ const record = await journal.ensure({ type: "approval" });
1665
+ const decision = record.decision;
1666
+ if (decision?.type === "approve") {
1667
+ if (decision.arguments !== undefined)
1668
+ effective = { ...effective, arguments: copyData(decision.arguments) };
1669
+ } else {
1670
+ if (!record.decision) record.closed = "stopped";
1671
+ refusal = {
1672
+ ok: false,
1673
+ kind: decision?.type === "cancel" ? "cancelled" : "denied",
1674
+ content:
1675
+ decision?.type === "deny"
1676
+ ? (decision.message ?? "The person denied this call.")
1677
+ : "This call needs a person's approval, and code cannot wait for one.",
1678
+ };
1679
+ }
1680
+ }
1681
+ if (refusal) {
1682
+ if (directNames.includes(name)) refusal.content += ` Call ${name} directly.`;
1683
+ await finishExecution(inner, effective, refusal);
1684
+ break;
1685
+ }
1686
+ }
1687
+ if (textBytes(programJson(effective.arguments)) > code.limits.callInputBytes) {
1688
+ await finishExecution(inner, effective, {
1689
+ ok: false,
1690
+ kind: "invalid_input",
1691
+ content: `The approved arguments exceed ${code.limits.callInputBytes} bytes. Send less data.`,
1692
+ });
1693
+ break;
1694
+ }
1695
+ if (call.status === "pending" && call.previousAttemptId) {
1696
+ emit({
1697
+ type: "operation_restart",
1698
+ kind: "tool",
1699
+ runId: snapshot.runId,
1700
+ operationId,
1701
+ parentOperationId: request.operationId,
1702
+ previousAttemptId: call.previousAttemptId,
1703
+ attemptId: effective.attemptId,
1704
+ });
1705
+ }
1706
+ await withToolError(
1707
+ effective,
1708
+ () => runTool(inner, effective, tool, concurrent),
1709
+ programSignal,
1710
+ );
1711
+ if (count() >= code.limits.calls || programSignal.aborted) break;
1712
+ } while (await retryTool(inner));
1713
+ return reply;
1714
+ } catch (error) {
1715
+ // A host/guard/checkpoint error stops the run, not merely one guest call.
1716
+ if (
1717
+ !programSignal.aborted &&
1718
+ !(error instanceof Halt && error.state.status === "suspended")
1719
+ ) {
1720
+ fatal ??= error;
1721
+ end.abort(error);
1722
+ }
1723
+ for (const ask of call.asks ?? [])
1724
+ if (!ask.closed && !ask.decision) ask.closed = "stopped";
1725
+ if (
1726
+ !programSignal.aborted &&
1727
+ error instanceof Halt &&
1728
+ error.state.status === "suspended"
1729
+ ) {
1730
+ const result: ToolResult = {
1731
+ ok: false,
1732
+ kind: "denied",
1733
+ content:
1734
+ "The approval expired. Code cannot wait for a new decision. Call this tool directly.",
1735
+ };
1736
+ await finishExecution(inner, inner.request(), result);
1737
+ return programReply(result, code.limits.callOutputBytes);
1738
+ }
1739
+ if (inner.get().status !== "completed") {
1740
+ const result = stopped(call);
1741
+ inner.set({
1742
+ id: operationId,
1743
+ attemptId: call.attemptId,
1744
+ status: "completed",
1745
+ interrupted: call.interrupted,
1746
+ retries: call.retries,
1747
+ asks: call.asks,
1748
+ result: programReceipt(result).result,
1749
+ });
1750
+ await save();
1751
+ if (!guardPolicy?.stages.includes("toolOutput"))
1752
+ emit({ type: "tool_result", request: inner.request(), result });
1753
+ }
1754
+ return reject(
1755
+ "aborted",
1756
+ "The call stopped. Check its saved receipt before repeating it.",
1757
+ );
1758
+ } finally {
1759
+ releaseCall();
1760
+ }
1761
+ })();
1762
+ const done = work.then(
1763
+ () => {},
1764
+ () => {},
1765
+ );
1766
+ settled = Promise.all([settled, done]).then(() => {});
1767
+ if (!concurrent) barrier = settled;
1768
+ jobs.push(work);
1769
+ return work.catch((error) => {
1770
+ fatal ??= error;
1771
+ end.abort(error);
1772
+ return reject(
1773
+ "aborted",
1774
+ "The host could not record the call. Stop and reconcile its effect.",
1775
+ );
1776
+ });
1777
+ },
1778
+ async settle() {
1779
+ closed = true;
1780
+ end.abort(new Error("The program has finished."));
1781
+ await Promise.allSettled(jobs);
1782
+ clearTimeout(timer);
1783
+ if (fatal) throw fatal;
1784
+ // A deadline may interrupt a guard after an effect returned. Never turn its
1785
+ // unfinished verdict into a successful program or buy another model turn.
1786
+ requireGuardVerdicts(snapshot);
1787
+ },
1788
+ };
1789
+ const outcome = await code.execute(
1790
+ completeArguments(request.call.arguments) ? request.arguments : undefined,
1791
+ bridge,
1792
+ );
1793
+ await finishTool(model, index, request, outcome.result);
1794
+ active();
1795
+ }
1796
+
1797
+ async function runDelegation(
1798
+ model: CompletedModel,
1799
+ index: number,
1800
+ request: ToolRequest,
1801
+ descriptor: Delegation,
1802
+ ): Promise<void> {
1803
+ let journal = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
1804
+ if (!journal) {
1805
+ journal = { kind: "delegation", operationId: request.operationId, children: [] };
1806
+ snapshot.delegations.push(journal);
1807
+ }
1808
+ if (journal.kind === "handoff") {
1809
+ try {
1810
+ const note = handoffNote(request.arguments);
1811
+ if (journal.children.length > 0 && note !== journal.note)
1812
+ throw new TypeError("The transfer note changed after the target started.");
1813
+ journal.note = note;
1814
+ } catch (error) {
1815
+ if (journal.children.length > 0)
1816
+ fail(
1817
+ "handoff_input_changed",
1818
+ "The target already started. Its transfer arguments cannot change. Reconcile the saved run before starting different work.",
1819
+ request.operationId,
1820
+ );
1821
+ await finishTool(model, index, request, {
1822
+ ok: false,
1823
+ kind: "invalid_input",
1824
+ content: messageOf(error),
1825
+ });
1826
+ return;
1827
+ }
1828
+ }
1829
+ model.tools[index] = {
1830
+ interrupted: model.tools[index]?.interrupted ?? [],
1831
+ retries: model.tools[index]?.retries ?? [],
1832
+ asks: model.tools[index]?.asks,
1833
+ id: request.operationId,
1834
+ attemptId: request.attemptId,
1835
+ status: "delegating",
1836
+ };
1837
+ await save();
1838
+ active();
1839
+ if (!completeArguments(request.call.arguments)) {
1840
+ await finishTool(model, index, request, {
1841
+ ok: false,
1842
+ kind: "invalid_input",
1843
+ content: "Tool arguments must be one complete JSON object. Send the full object again.",
1844
+ });
1845
+ return;
1846
+ }
1847
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
1848
+ refuseGuardedReplay(snapshot, request.operationId);
1849
+ await beforeTool(request);
1850
+ await requests.recheck(request);
1851
+ active();
1852
+ emit({ type: "tool_start", request });
1853
+ active();
1854
+ await requests.recheck(request);
1855
+ await requests.assertFresh();
1856
+ active();
1857
+ // Coordination is pure and is the only place children can start. Lend once
1858
+ // for this entire barrier, including ignored children and overlapping joins.
1859
+ release();
1860
+ let result: ToolResult;
1861
+ try {
1862
+ result = await executeDelegation(
1863
+ descriptor,
1864
+ journal,
1865
+ snapshot,
1866
+ request.arguments,
1867
+ options,
1868
+ scope,
1869
+ signal,
1870
+ active,
1871
+ requests,
1872
+ );
1873
+ } finally {
1874
+ release = await scope.tree.gate.acquire(signal);
1875
+ }
1876
+ active();
1877
+ await finishTool(model, index, request, result);
1878
+ }
1879
+
1880
+ async function openApprovals(model: CompletedModel, from: number): Promise<void> {
1881
+ for (let index = from; index < model.tools.length; index++) {
1882
+ const execution = model.tools[index];
1883
+ if (!execution || execution.status === "completed") continue;
1884
+ if (usedTools() >= limits.toolCalls && !execution.asks?.length) break;
1885
+ const request = requestFor(snapshot, model, index);
1886
+ const tool = tools.find((tool) => tool.name === request.call.name);
1887
+ if (
1888
+ !tool ||
1889
+ request.call.name === RESULT_TOOL_NAME ||
1890
+ !snapshot.definition.enabledTools.includes(tool.name) ||
1891
+ snapshot.definition.modelSettings.toolChoice === "none" ||
1892
+ !completeArguments(request.call.arguments) ||
1893
+ (isHandoff(tool) && model.tools.length !== 1) ||
1894
+ (!isDelegation(tool) &&
1895
+ !isHandoff(tool) &&
1896
+ !isClientTool(tool) &&
1897
+ !isCodeTool(tool) &&
1898
+ tool.isTerminal &&
1899
+ model.tools.length !== 1)
1900
+ )
1901
+ continue;
1902
+ if (await needsApproval(request, options, signal))
1903
+ await journalFor(snapshot, model, index, options, scope, signal).ensure({
1904
+ type: "approval",
1905
+ });
1906
+ }
1907
+ }
1908
+
1909
+ async function runClient(
1910
+ model: CompletedModel,
1911
+ index: number,
1912
+ request: ToolRequest,
1913
+ client: ClientTool,
1914
+ ): Promise<void> {
1915
+ try {
1916
+ if (!completeArguments(request.call.arguments))
1917
+ throw new TypeError("Send one complete JSON object.");
1918
+ client.validateArguments(request.arguments);
1919
+ } catch (error) {
1920
+ await finishTool(model, index, request, {
1921
+ ok: false,
1922
+ kind: "invalid_input",
1923
+ content: messageOf(error),
1924
+ });
1925
+ return;
1926
+ }
1927
+ if (!host?.beforeTool)
1928
+ fail("request_host_missing", "Provide host.beforeTool before dispatching a client tool.");
1929
+ const requests = journalFor(snapshot, model, index, options, scope, signal, request);
1930
+ refuseGuardedReplay(snapshot, request.operationId);
1931
+ await beforeTool(request);
1932
+ await requests.recheck(request);
1933
+ const record = await requests.ensure({ type: "client", resultSchema: client.resultSchema });
1934
+ if (!record.decision) return;
1935
+ if (record.decision.type === "stop") {
1936
+ scope.tree.stop();
1937
+ throw new Halt({ status: "cancelled" });
1938
+ }
1939
+ if (record.decision.type === "cancel") {
1940
+ await finishTool(model, index, request, {
1941
+ ok: false,
1942
+ kind: "cancelled",
1943
+ content:
1944
+ "The person cancelled this client request. This does not undo an action already taken.",
1945
+ });
1946
+ return;
1947
+ }
1948
+ if (record.decision.type !== "result")
1949
+ throw new TypeError("A client request needs a result.");
1950
+ await requests.recheck(request);
1951
+ active();
1952
+ const result = client.result(record.decision.value);
1953
+ await finishTool(model, index, request, successfulToolResult(result));
1954
+ }
1955
+
1956
+ async function handleTurn(model: CompletedModel): Promise<void> {
1957
+ active();
1958
+ const { message, finishReason } = model.turn;
1959
+ if (finishReason === "length") throw new Halt({ status: "limited", limit: "outputTokens" });
1960
+ if (finishReason === "content_filter")
1961
+ fail(
1962
+ "content_filtered",
1963
+ "The provider blocked this answer. Revise the request before trying again.",
1964
+ model.id,
1965
+ );
1966
+ if (finishReason === null)
1967
+ fail(
1968
+ "incomplete_turn",
1969
+ "The model turn ended without a finish reason. Check the provider before trying again.",
1970
+ model.id,
1971
+ );
1972
+ const calls = message.toolCalls ?? [];
1973
+ if (calls.length === 0) {
1974
+ if (output)
1975
+ fail(
1976
+ "missing_result",
1977
+ `The model did not submit a result through ${RESULT_TOOL_NAME}.`,
1978
+ model.id,
1979
+ );
1980
+ if (!message.content.trim())
1981
+ fail(
1982
+ "empty_output",
1983
+ "The model returned no answer, only reasoning or an empty turn.",
1984
+ model.id,
1985
+ );
1986
+ snapshot.state = { status: "completed", candidate: message.content };
1987
+ return;
1988
+ }
1989
+
1990
+ // The one extra call at the local turn limit has no tools, even if a provider ignores
1991
+ // toolChoice. Never execute calls it returns. The shared tree limit remains a hard cap.
1992
+ if (snapshot.models.indexOf(model) >= limits.turns)
1993
+ throw new Halt({ status: "limited", limit: "turns" });
1994
+
1995
+ for (let index = 0; index < calls.length;) {
1996
+ if (
1997
+ model.tools[index]?.status === "completed" &&
1998
+ !(await retryTool(slotFor(model, index)))
1999
+ ) {
2000
+ index++;
2001
+ continue;
2002
+ }
2003
+ active();
2004
+ const capacity = limits.toolCalls - usedTools();
2005
+ if (
2006
+ capacity <= 0 &&
2007
+ model.tools[index]?.status === "pending" &&
2008
+ !model.tools[index]?.asks?.length
2009
+ )
2010
+ throw new Halt({ status: "limited", limit: "toolCalls" });
2011
+ let request = requestFor(snapshot, model, index);
2012
+ if (model.tools[index]?.retries.length) await checkToolRetry(slotFor(model, index));
2013
+ if (
2014
+ !directNames.includes(request.call.name) ||
2015
+ !snapshot.definition.enabledTools.includes(request.call.name) ||
2016
+ snapshot.definition.modelSettings.toolChoice === "none"
2017
+ ) {
2018
+ await finishTool(model, index, request, {
2019
+ ok: false,
2020
+ kind: names.includes(request.call.name) ? "disabled_tool" : "unknown_tool",
2021
+ content: "This tool is not available in this run. Choose one of the provided tools.",
2022
+ });
2023
+ index++;
2024
+ continue;
2025
+ }
2026
+ const handoff = handoffs.get(request.call.name);
2027
+ if (
2028
+ handoff &&
2029
+ !snapshot.delegations.some((entry) => entry.operationId === request.operationId)
2030
+ ) {
2031
+ let target;
2032
+ let note;
2033
+ try {
2034
+ if (calls.length !== 1)
2035
+ throw new TypeError(
2036
+ `Call ${handoff.name} alone, after the other tool results arrive.`,
2037
+ );
2038
+ if (!completeArguments(request.call.arguments))
2039
+ throw new TypeError(
2040
+ "Tool arguments must be one complete JSON object. Send the full object again.",
2041
+ );
2042
+ note = handoffNote(request.arguments);
2043
+ target = handoff.target();
2044
+ if (target.id === id)
2045
+ throw new TypeError(
2046
+ "This agent already owns the conversation. Choose a different target.",
2047
+ );
2048
+ checkHandoffTargets(agent);
2049
+ } catch (error) {
2050
+ await finishTool(model, index, request, {
2051
+ ok: false,
2052
+ kind: "invalid_input",
2053
+ content: messageOf(error),
2054
+ });
2055
+ index++;
2056
+ continue;
2057
+ }
2058
+ // Pin identity before asking for permission. A resumed lazy reference cannot turn
2059
+ // an approval for one target into a transfer to another.
2060
+ snapshot.delegations.push({
2061
+ kind: "handoff",
2062
+ operationId: request.operationId,
2063
+ target: handoffRef(target),
2064
+ ...(note !== undefined ? { note } : {}),
2065
+ children: [],
2066
+ });
2067
+ model.tools[index] = {
2068
+ id: request.operationId,
2069
+ status: "delegating",
2070
+ attemptId: snapshot.attemptId,
2071
+ interrupted: [],
2072
+ retries: [],
2073
+ };
2074
+ await save();
2075
+ active();
2076
+ }
2077
+ const descriptor = descriptorFor(request.call.name, snapshot, request.operationId);
2078
+ const tool = registry.get(request.call.name);
2079
+ const client = clients.get(request.call.name);
2080
+ const code = codeTools.get(request.call.name);
2081
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
2082
+ if (
2083
+ (tool || descriptor || client || code) &&
2084
+ completeArguments(request.call.arguments) &&
2085
+ (!tool?.isTerminal || model.tools.length === 1) &&
2086
+ (await needsApproval(request, options, signal))
2087
+ )
2088
+ await requests.ensure({ type: "approval" });
2089
+ const records = model.tools[index]?.asks ?? [];
2090
+ if (records.some((record) => !record.closed && record.decision?.type === "stop")) {
2091
+ scope.tree.stop();
2092
+ throw new Halt({ status: "cancelled" });
2093
+ }
2094
+ const decline = records.find(
2095
+ (record) =>
2096
+ !record.closed &&
2097
+ (record.decision?.type === "deny" || record.decision?.type === "cancel"),
2098
+ );
2099
+ if (decline?.decision) {
2100
+ await finishTool(
2101
+ model,
2102
+ index,
2103
+ request,
2104
+ decline.decision.type === "deny"
2105
+ ? {
2106
+ ok: false,
2107
+ kind: "denied",
2108
+ content:
2109
+ decline.decision.message ??
2110
+ "The person denied this call. Continue without this action.",
2111
+ }
2112
+ : {
2113
+ ok: false,
2114
+ kind: "cancelled",
2115
+ content: "The person cancelled this request. Continue without this action.",
2116
+ },
2117
+ );
2118
+ index++;
2119
+ continue;
2120
+ }
2121
+ if (records.some((record) => !record.closed && !record.decision)) {
2122
+ await openApprovals(model, index + 1);
2123
+ snapshot.state = { status: "suspended" };
2124
+ return;
2125
+ }
2126
+ const approval = requests.latest({ type: "approval" })?.decision;
2127
+ if (approval?.type === "approve" && approval.arguments !== undefined)
2128
+ request = { ...request, arguments: copyData(approval.arguments) };
2129
+ if (code) {
2130
+ await withToolError(request, () => runProgram(model, index, request, code));
2131
+ index++;
2132
+ continue;
2133
+ }
2134
+ if (descriptor) {
2135
+ await withToolError(request, () => runDelegation(model, index, request, descriptor));
2136
+ index++;
2137
+ continue;
2138
+ }
2139
+ if (client) {
2140
+ await withToolError(request, () => runClient(model, index, request, client));
2141
+ if (model.tools[index]?.status !== "completed") {
2142
+ await openApprovals(model, index + 1);
2143
+ snapshot.state = { status: "suspended" };
2144
+ return;
2145
+ }
2146
+ index++;
2147
+ continue;
2148
+ }
2149
+
2150
+ const execution = model.tools[index];
2151
+ const batch = [
2152
+ {
2153
+ index,
2154
+ request,
2155
+ tool,
2156
+ previousAttemptId:
2157
+ execution?.status === "pending" ? execution.previousAttemptId : undefined,
2158
+ },
2159
+ ];
2160
+ const parallel = (request: ToolRequest, tool?: Tool) =>
2161
+ canParallel(
2162
+ request,
2163
+ tool,
2164
+ slotFor(
2165
+ model,
2166
+ model.tools.findIndex((entry) => entry.id === request.operationId),
2167
+ ).get(),
2168
+ );
2169
+ const concurrent = parallel(request, tool);
2170
+ if (concurrent) {
2171
+ for (
2172
+ let next = index + 1;
2173
+ next < calls.length && batch.length < Math.min(limits.parallelTools, capacity);
2174
+ next++
2175
+ ) {
2176
+ const execution = model.tools[next];
2177
+ if (execution?.status !== "pending") break;
2178
+ const nextRequest = requestFor(snapshot, model, next);
2179
+ const nextTool = registry.get(nextRequest.call.name);
2180
+ if (!parallel(nextRequest, nextTool)) break;
2181
+ batch.push({
2182
+ index: next,
2183
+ request: nextRequest,
2184
+ tool: nextTool,
2185
+ previousAttemptId: execution.previousAttemptId,
2186
+ });
2187
+ }
2188
+ }
2189
+ // A checkpoint can capture the pending retry while another child saves. Check its
2190
+ // identity again before admission, even if this worker did not perform the reset.
2191
+ for (const job of batch) {
2192
+ const execution = model.tools[job.index];
2193
+ if (execution?.interrupted.length && !execution.asks?.length)
2194
+ await checkToolRecovery(
2195
+ model,
2196
+ job.index,
2197
+ execution.interrupted.length + execution.retries.length - 1,
2198
+ );
2199
+ }
2200
+ active();
2201
+ // Reserve the whole admitted batch before any invocation, including its tool-call budget.
2202
+ for (const job of batch)
2203
+ model.tools[job.index] = {
2204
+ interrupted: model.tools[job.index]?.interrupted ?? [],
2205
+ retries: model.tools[job.index]?.retries ?? [],
2206
+ asks: model.tools[job.index]?.asks,
2207
+ id: job.request.operationId,
2208
+ attemptId: job.request.attemptId,
2209
+ status: "running",
2210
+ };
2211
+ await save();
2212
+ const settled = await Promise.allSettled(
2213
+ batch.map((job) => {
2214
+ // Retry and recovery histories can interleave. Use the predecessor saved when
2215
+ // this replacement was scheduled, not the tail of either history alone.
2216
+ if (job.previousAttemptId)
2217
+ restart(
2218
+ "tool",
2219
+ job.request.operationId,
2220
+ job.previousAttemptId,
2221
+ job.request.attemptId,
2222
+ );
2223
+ return withToolError(job.request, () =>
2224
+ runTool(slotFor(model, job.index), job.request, job.tool, concurrent),
2225
+ );
2226
+ }),
2227
+ );
2228
+ const rejected = settled.find((result) => result.status === "rejected");
2229
+ if (rejected?.status === "rejected") throw rejected.reason;
2230
+ if (batch.some((job) => model.tools[job.index]?.status === "pending")) {
2231
+ if (
2232
+ batch.some((job) =>
2233
+ model.tools[job.index]?.asks?.some((record) => !record.closed && !record.decision),
2234
+ )
2235
+ ) {
2236
+ await openApprovals(model, index + batch.length);
2237
+ snapshot.state = { status: "suspended" };
2238
+ return;
2239
+ }
2240
+ continue;
2241
+ }
2242
+ // Retrying tools run serially. Revisit their settled failure through the same
2243
+ // admission path; ordinary batches advance as before.
2244
+ if (!retryBudget(snapshot.definition.toolRetries, request.call.name)) index += batch.length;
2245
+ }
2246
+ // Adapted from OpenAI Agents JS (MIT), runner/toolExecution.ts: settle this batch,
2247
+ // then select the first stopping tool in model order, not completion order.
2248
+ const final =
2249
+ finalHandoffResult(snapshot, model) ??
2250
+ finalToolResult(
2251
+ model,
2252
+ snapshot.definition.stopAtTools,
2253
+ output ? RESULT_TOOL_NAME : undefined,
2254
+ );
2255
+ if (final) snapshot.state = { status: "completed", candidate: final.candidate };
2256
+ }
2257
+
2258
+ // One load per media id per attempt. The bytes live only in the requests built from it,
2259
+ // never in the journal, the outcome or an event. The per-run cache of pending loads is
2260
+ // adapted from TanStack AI (MIT), packages/ai-harness/src/media.ts.
2261
+ const media = new Map<string, Promise<string>>();
2262
+ function loadMedia(ref: MediaRef): Promise<string> {
2263
+ let loaded = media.get(ref.id);
2264
+ if (!loaded) {
2265
+ loaded = readMedia(ref);
2266
+ media.set(ref.id, loaded);
2267
+ }
2268
+ return loaded;
2269
+ }
2270
+ async function readMedia(ref: MediaRef): Promise<string> {
2271
+ const load = host?.loadMedia;
2272
+ if (!load)
2273
+ fail(
2274
+ "media_unavailable",
2275
+ "This run has media references. Provide host.loadMedia to read their bytes.",
2276
+ );
2277
+ let data: unknown;
2278
+ try {
2279
+ data = await untilAbort(
2280
+ Promise.resolve(load(immutableCopy(ref), { runId: snapshot.runId, signal })),
2281
+ signal,
2282
+ );
2283
+ } catch {
2284
+ active();
2285
+ // Loader errors can quote credentials from a header or request. Never persist them.
2286
+ fail(
2287
+ "media_unavailable",
2288
+ "The media could not be loaded. Check file access before trying again.",
2289
+ );
2290
+ }
2291
+ if (!isBase64(data))
2292
+ fail(
2293
+ "media_unavailable",
2294
+ `host.loadMedia returned no base64 bytes for media ${ref.id}. Return the bytes as padded base64 text.`,
2295
+ );
2296
+ return data;
2297
+ }
2298
+
2299
+ async function compact(): Promise<void> {
2300
+ const last = snapshot.compactions.at(-1);
2301
+ if (last?.status === "running")
2302
+ fail(
2303
+ "interrupted_compaction",
2304
+ "The summary has no saved result and may have been billed. Reconcile it with the host before continuing.",
2305
+ last.id,
2306
+ );
2307
+ const plan = compactionPlan(snapshot);
2308
+ if (!plan) return;
2309
+ const { removed, ...position } = plan;
2310
+ const index = snapshot.compactions.length;
2311
+ const entry: CompactionExecution = {
2312
+ id: compactionId(snapshot.runId, index),
2313
+ beforeModel: snapshot.models.length,
2314
+ ...position,
2315
+ status: "running",
2316
+ };
2317
+ const summary = snapshot.definition.compaction?.summarize;
2318
+ if (!summary) {
2319
+ snapshot.compactions.push({
2320
+ ...entry,
2321
+ status: "completed",
2322
+ summary: "Earlier messages were omitted. No summary was generated.",
2323
+ });
2324
+ await save();
2325
+ return;
2326
+ }
2327
+ if (!summarizer) fail("invalid_journal", "The recorded summary provider is missing.");
2328
+ // A separate receipt freezes this cut before any paid work. A crash, even before
2329
+ // dispatch, fails closed instead of silently purchasing the same summary twice.
2330
+ snapshot.compactions.push(entry);
2331
+ await save();
2332
+ active();
2333
+ const messages = await requestOf(summary.instructions, removed, loadMedia);
2334
+ await callModel(
2335
+ entry.id,
2336
+ {
2337
+ messages,
2338
+ tools: [],
2339
+ settings: {
2340
+ maxTokens: summary.maxTokens,
2341
+ maxAttempts: 1,
2342
+ toolChoice: "none",
2343
+ hostedTools: [],
2344
+ },
2345
+ },
2346
+ summarizer,
2347
+ (model) => {
2348
+ if (model.status === "completed") {
2349
+ if (
2350
+ model.turn.finishReason !== "stop" ||
2351
+ !model.turn.message.content.trim() ||
2352
+ model.tools.length ||
2353
+ model.turn.message.hostedCalls?.length ||
2354
+ model.turn.message.hostedItems
2355
+ )
2356
+ fail(
2357
+ "invalid_compaction",
2358
+ "The summary must be complete text without tool calls. Check the summary provider before starting new work.",
2359
+ entry.id,
2360
+ );
2361
+ snapshot.compactions[index] = {
2362
+ ...entry,
2363
+ model,
2364
+ status: "completed",
2365
+ summary: model.turn.message.content,
2366
+ };
2367
+ } else entry.model = model;
2368
+ },
2369
+ undefined,
2370
+ true,
2371
+ );
2372
+ }
2373
+
2374
+ async function nextTurn(
2375
+ previous?: Extract<ModelExecution, { status: "running" }>,
2376
+ ): Promise<CompletedModel> {
2377
+ active();
2378
+ // Hosted actions may run before any local tool call appears. Their explicit presence
2379
+ // overrides a profile's inference-only claim when an interrupted call is recovered.
2380
+ if (previous) {
2381
+ refuseGuardedReplay(snapshot, previous.id);
2382
+ requireRecovery(
2383
+ snapshot.definition.recovery?.policy.inferenceOnly === true &&
2384
+ !snapshot.definition.modelSettings.hostedTools?.length,
2385
+ previous.interrupted.length,
2386
+ snapshot.definition.recovery,
2387
+ previous.id,
2388
+ );
2389
+ }
2390
+ const position = previous ? snapshot.models.indexOf(previous) : snapshot.models.length;
2391
+ const selected = definitionsFor(snapshot.definition.enabledTools);
2392
+ if (
2393
+ previous &&
2394
+ (await requestHash(selected)) !== snapshot.definition.recovery?.modelToolsHash
2395
+ )
2396
+ fail(
2397
+ "recovery_definition_changed",
2398
+ "The interrupted model call's tool definitions changed. Restore the same definitions or reconcile the run.",
2399
+ previous.id,
2400
+ );
2401
+ // Ported from Microsoft Agent Framework (MIT), _tools.py: after the iteration
2402
+ // allowance, ask once for a tool-free answer. Checked output needs submit_result,
2403
+ // so that mode retains the hard local turn cap instead of buying an unusable call.
2404
+ const finalTurn = position === limits.turns;
2405
+ if (position > limits.turns || (finalTurn && output))
2406
+ throw new Halt({ status: "limited", limit: "turns" });
2407
+ // A steer never changes the input of an already admitted call, including safe replay.
2408
+ // Check capacity before polling so a spent budget leaves delivery queued in the host.
2409
+ scope.tree.reserveModel();
2410
+ if (!previous) {
2411
+ await acceptInputs(snapshot, scope, options, signal);
2412
+ await compact();
2413
+ }
2414
+ active();
2415
+ // Media is read before the receipt below exists, so a missing loader or file fails the
2416
+ // run with no model operation left running and nothing to reconcile.
2417
+ const request = await requestOf(
2418
+ snapshot.definition.instructions,
2419
+ withMemoryRecall(snapshot, modelConversation(snapshot)),
2420
+ loadMedia,
2421
+ );
2422
+ active();
2423
+ const modelSettings = copyData(snapshot.definition.modelSettings);
2424
+ // Ported from OpenAI Agents JS (MIT), runner/modelSettings.ts, maybeResetToolChoice.
2425
+ // Derive usage from the journal so resume cannot force the first tool a second time.
2426
+ const choice = modelSettings.toolChoice;
2427
+ if (
2428
+ (choice === "required" || typeof choice === "object") &&
2429
+ snapshot.models.some((model) => model.status === "completed" && model.tools.length > 0)
2430
+ )
2431
+ modelSettings.toolChoice = "auto";
2432
+ if (finalTurn) modelSettings.toolChoice = "none";
2433
+ const operationId = modelId(snapshot.runId, position);
2434
+ const modelInput: ModelInput = {
2435
+ messages: request,
2436
+ tools: finalTurn ? [] : copyData(selected),
2437
+ settings: modelSettings,
2438
+ };
2439
+ const done = await callModel(
2440
+ operationId,
2441
+ modelInput,
2442
+ provider,
2443
+ (model) => {
2444
+ snapshot.models[position] = model;
2445
+ },
2446
+ previous,
2447
+ );
2448
+ for (const receipt of inputReceipts(snapshot).filter(
2449
+ (receipt) => receipt.modelId === done.id,
2450
+ ))
2451
+ emit({ type: "input", receipt });
2452
+ await acknowledgeInputs(snapshot, options, signal);
2453
+ return done;
2454
+ }
2455
+
2456
+ // Both ordinary turns and explicit summaries use the same admission, guards, usage
2457
+ // checkpoints and collection path. Summaries stay private and never dispatch tools.
2458
+ async function callModel(
2459
+ operationId: string,
2460
+ modelInput: ModelInput,
2461
+ selectedProvider: Provider,
2462
+ record: (model: ModelExecution) => void,
2463
+ previous?: Extract<ModelExecution, { status: "running" }>,
2464
+ summary = false,
2465
+ ): Promise<CompletedModel> {
2466
+ const { messages: request, settings: modelSettings } = modelInput;
2467
+ await guards.check("modelInput", operationId, snapshot.attemptId, modelInput);
2468
+ await observe({
2469
+ type: "model_start",
2470
+ operationId,
2471
+ attemptId: snapshot.attemptId,
2472
+ input: modelInput,
2473
+ });
2474
+ active();
2475
+ // The tree check and the receipt stay together, with no await between them, so two
2476
+ // children racing for the tree's last model call cannot both take it.
2477
+ scope.tree.reserveModel();
2478
+ const model: ModelExecution = {
2479
+ id: operationId,
2480
+ attemptId: snapshot.attemptId,
2481
+ status: "running",
2482
+ billing: "unknown",
2483
+ usage: { ...EMPTY_USAGE },
2484
+ interrupted: previous
2485
+ ? [
2486
+ ...previous.interrupted,
2487
+ { attemptId: previous.attemptId, usage: copyData(previous.usage) },
2488
+ ]
2489
+ : [],
2490
+ };
2491
+ record(model);
2492
+ await save();
2493
+ if (previous) restart("model", model.id, previous.attemptId);
2494
+ active();
2495
+ let reportedUsage = false;
2496
+ let bufferedChunks = 0;
2497
+ let bufferedBytes = 0;
2498
+ const guarded = !!guardrails?.modelOutput;
2499
+ async function* observed(): AsyncIterable<ProviderChunk> {
2500
+ let dispatchProvider = selectedProvider;
2501
+ if (options.bindModelProvider) {
2502
+ try {
2503
+ const bound = options.bindModelProvider(
2504
+ selectedProvider,
2505
+ Object.freeze({
2506
+ run: callbackContext,
2507
+ operationId: model.id,
2508
+ operationAttemptId: model.attemptId,
2509
+ purpose: summary ? "compaction" : "turn",
2510
+ }),
2511
+ );
2512
+ if (bound && typeof bound.createStream === "function") dispatchProvider = bound;
2513
+ } catch {
2514
+ // Instrumentation can fail before dispatch. Never catch/replay the provider call.
2515
+ }
2516
+ }
2517
+ active();
2518
+ const stream = dispatchProvider.createStream(request, modelInput.tools, {
2519
+ ...modelSettings,
2520
+ ...(settings.onActivity ? { onActivity: settings.onActivity } : {}),
2521
+ ...(settings.onRateLimit ? { onRateLimit: settings.onRateLimit } : {}),
2522
+ ...(options.modelSettings?.onActivity
2523
+ ? { onActivity: options.modelSettings.onActivity }
2524
+ : {}),
2525
+ ...(options.modelSettings?.onRateLimit
2526
+ ? { onRateLimit: options.modelSettings.onRateLimit }
2527
+ : {}),
2528
+ signal,
2529
+ sessionId: summary
2530
+ ? operationId
2531
+ : (snapshot.subagent?.identity.originRunId ?? snapshot.runId),
2532
+ });
2533
+ for await (const chunk of stream) {
2534
+ active();
2535
+ if (chunk.usage) {
2536
+ if (!isUsage(chunk.usage))
2537
+ fail("invalid_usage", "The provider returned invalid token usage.", model.id);
2538
+ model.usage = copyData(chunk.usage);
2539
+ reportedUsage = true;
2540
+ // Preserve measurements before another pull can hang or the worker can disappear.
2541
+ // This saves usage, not partial text, and does not claim final billing is known.
2542
+ await save();
2543
+ active();
2544
+ }
2545
+ if (guarded) {
2546
+ // Bound collection before yielding. Only the checked assembled turn is published.
2547
+ // All fields count, including reasoning, signatures, tool args and hosted payloads.
2548
+ bufferedBytes += jsonBytes(chunk);
2549
+ bufferedChunks++;
2550
+ if (
2551
+ bufferedBytes > (guardPolicy?.maxOutputBytes ?? 0) ||
2552
+ bufferedChunks > GUARDED_CHUNK_LIMIT
2553
+ )
2554
+ await guards.overflow("modelOutput", model.id);
2555
+ } else if (!summary) {
2556
+ emit({
2557
+ type: "model_chunk",
2558
+ runId: snapshot.runId,
2559
+ attemptId: snapshot.attemptId,
2560
+ operationId: model.id,
2561
+ chunk,
2562
+ });
2563
+ }
2564
+ active();
2565
+ yield chunk;
2566
+ }
2567
+ }
2568
+ let collected;
2569
+ try {
2570
+ collected = await untilAbort(collectTurn(observed()), signal);
2571
+ } catch (error) {
2572
+ await observe({ type: "model_error", operationId: model.id, attemptId: model.attemptId });
2573
+ active();
2574
+ // Only core's classified provider failures are local model failures. Host/checkpoint
2575
+ // errors and unclassified programming errors must not become benign tool strings.
2576
+ if (!(error instanceof ProviderError)) {
2577
+ if (guarded && !(error instanceof Halt))
2578
+ fail(
2579
+ "guarded_model_failed",
2580
+ "The guarded model call failed before its output could be checked. Inspect the provider on the server before starting new work.",
2581
+ model.id,
2582
+ );
2583
+ throw error;
2584
+ }
2585
+ if (error.kind === "aborted") {
2586
+ scope.tree.stop();
2587
+ throw new Halt({ status: "cancelled" });
2588
+ }
2589
+ fail(
2590
+ "model_failed",
2591
+ guarded
2592
+ ? `The model call failed (${error.kind}). Check the provider before starting new work.`
2593
+ : `The model call failed (${error.kind}): ${error.message}`,
2594
+ model.id,
2595
+ );
2596
+ }
2597
+ let turn;
2598
+ try {
2599
+ turn = readTurn(collected);
2600
+ } catch (error) {
2601
+ fail(
2602
+ "invalid_model_output",
2603
+ guarded
2604
+ ? "The provider returned an invalid guarded turn. Check the provider before starting new work."
2605
+ : messageOf(error),
2606
+ model.id,
2607
+ );
2608
+ }
2609
+ await observe({ type: "model_end", operationId: model.id, attemptId: model.attemptId, turn });
2610
+ active();
2611
+ await guards.check("modelOutput", model.id, model.attemptId, turn);
2612
+ active();
2613
+ const done: CompletedModel = {
2614
+ ...model,
2615
+ status: "completed",
2616
+ billing: reportedUsage ? "reported" : "unknown",
2617
+ usage: turn.usage,
2618
+ turn,
2619
+ tools: (turn.message.toolCalls ?? []).map((_call, index) => ({
2620
+ id: toolId(model.id, index),
2621
+ status: "pending",
2622
+ interrupted: [],
2623
+ retries: [],
2624
+ })),
2625
+ };
2626
+ record(done);
2627
+ await save();
2628
+ if (guarded && !summary) {
2629
+ active();
2630
+ emit({
2631
+ type: "model_chunk",
2632
+ runId: snapshot.runId,
2633
+ attemptId: model.attemptId,
2634
+ operationId: model.id,
2635
+ chunk: guardedChunk(turn),
2636
+ });
2637
+ }
2638
+ return done;
2639
+ }
2640
+
2641
+ try {
2642
+ // Repair a lost acknowledgement from the saved journal without rereading its payload.
2643
+ // Terminal snapshots synchronize too; this never starts a follow-up model call.
2644
+ if (scope.depth === 0) await acknowledgeInputs(snapshot, options, signal);
2645
+ if (scope.depth === 0 && answers) {
2646
+ await answerRequests(snapshot, options, scope, answers, signal);
2647
+ if (
2648
+ [...requestRecords(snapshot)].some(
2649
+ ({ record }) => !record.closed && record.decision?.type === "stop",
2650
+ )
2651
+ )
2652
+ scope.tree.stop();
2653
+ await save();
2654
+ }
2655
+ if (snapshot.state.status === "running" || snapshot.state.status === "suspended") {
2656
+ release = await scope.tree.gate.acquire(signal);
2657
+ active();
2658
+ requireGuardVerdicts(snapshot);
2659
+ started = true;
2660
+ await observe({ type: "run_start" });
2661
+ active();
2662
+ const last = snapshot.models.at(-1);
2663
+ snapshot.state = { status: "running" };
2664
+ checkMemoryBinding(snapshot, options.memory);
2665
+ if (needsMemory && !options.memory)
2666
+ fail("memory_missing", "Supply authenticated memory access before starting this agent.");
2667
+ if (
2668
+ !options.memory?.scope &&
2669
+ [...capabilities.values()].some(
2670
+ (tool) =>
2671
+ isMemoryTool(tool) &&
2672
+ !tool.isReadOnly &&
2673
+ snapshot.definition.enabledTools.includes(tool.name),
2674
+ )
2675
+ )
2676
+ fail(
2677
+ "memory_missing",
2678
+ "Memory writes need an authenticated person's writable scope. Disable save and forget for shared-only access.",
2679
+ );
2680
+ if (memory && options.memory && !snapshot.recall) {
2681
+ snapshot.recall = await recallMemory(
2682
+ snapshot,
2683
+ options.memory,
2684
+ signal,
2685
+ scope.handoffInput,
2686
+ );
2687
+ // No model sees recall until the existing progress/checkpoint barrier confirms it.
2688
+ await save();
2689
+ active();
2690
+ }
2691
+ if (snapshot.recall?.status === "failed" && memory?.onError === "fail")
2692
+ fail(
2693
+ "memory_unavailable",
2694
+ "Memory could not be read. Check the store before starting a new run.",
2695
+ );
2696
+ if (last?.status === "running") await handleTurn(await nextTurn(last));
2697
+ else if (last?.status === "completed") {
2698
+ await recoverTools(last);
2699
+ await handleTurn(last);
2700
+ }
2701
+ while (snapshot.state.status === "running") await handleTurn(await nextTurn());
2702
+ }
2703
+ if (snapshot.state.status === "completed") completed = { output: completedOutput(snapshot) };
2704
+ await save();
2705
+ } catch (error) {
2706
+ let failure = error;
2707
+ try {
2708
+ active();
2709
+ } catch (stopped) {
2710
+ failure = stopped;
2711
+ }
2712
+ snapshot.state =
2713
+ failure instanceof Halt
2714
+ ? failure.state
2715
+ : {
2716
+ status: "failed",
2717
+ error: { code: "execution_failed", message: messageOf(failure) },
2718
+ };
2719
+ try {
2720
+ await save();
2721
+ } catch (saveError) {
2722
+ snapshot.state =
2723
+ saveError instanceof Halt
2724
+ ? saveError.state
2725
+ : {
2726
+ status: "failed",
2727
+ error: { code: "checkpoint_failed", message: messageOf(saveError) },
2728
+ };
2729
+ }
2730
+ } finally {
2731
+ release();
2732
+ if (started) await observe({ type: "run_end", state: snapshot.state });
2733
+ clearTimeout(timer);
2734
+ }
2735
+ emit({
2736
+ type: "state",
2737
+ runId: snapshot.runId,
2738
+ attemptId: snapshot.attemptId,
2739
+ state: snapshot.state,
2740
+ });
2741
+ // Includes the final state event, before a child host receipt or session append can land.
2742
+ await host?.progress?.flush();
2743
+ const record = recordOf(snapshot);
2744
+ const state = snapshot.state;
2745
+ if (state.status === "completed") {
2746
+ if (!completed) throw new Error("The agent completed without validating its result.");
2747
+ return { ...record, status: "completed", output: completed.output };
2748
+ }
2749
+ return state.status === "suspended"
2750
+ ? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
2751
+ : { ...record, ...state };
2752
+ }
2753
+
2754
+ function checkInline(start: Pick<RunStart, "history" | "input">): void {
2755
+ const bytes = inlineBytes(start.history, start.input);
2756
+ if (bytes > limits.inlineBytes)
2757
+ throw new TypeError(
2758
+ `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.`,
2759
+ );
2760
+ }
2761
+
2762
+ function freeze(start: RunStart): RunStart {
2763
+ // Once, here: adapters repair every request again, and repair is idempotent, so the
2764
+ // bytes a provider caches never change between turns or across a resume.
2765
+ const history = repairConversation(
2766
+ start.history,
2767
+ (name) => (registry.get(name) ?? codeTools.get(name))?.isReadOnly === true,
2768
+ );
2769
+ checkInline({ history, input: start.input });
2770
+ return { ...start, history };
2771
+ }
2772
+
2773
+ async function create(
2774
+ start: RunStart,
2775
+ runId: string,
2776
+ tree?: RunSnapshot["tree"],
2777
+ options: RunOptions = {},
2778
+ subagent?: SubagentCreation,
2779
+ ): Promise<RunSnapshot> {
2780
+ const frozen = freeze(start);
2781
+ const spec = subagent?.record.spec;
2782
+ const resolved = await resolveDefinition(
2783
+ frozen,
2784
+ spec
2785
+ ? {
2786
+ ...options,
2787
+ enabledTools: spec.tools,
2788
+ modelSettings: subagent.record.policy.models[spec.model ?? ""]?.settings,
2789
+ }
2790
+ : options,
2791
+ runId,
2792
+ subagent?.source,
2793
+ );
2794
+ const record = subagent
2795
+ ? { ...copyData(subagent.record), base: copyData(resolved) }
2796
+ : undefined;
2797
+ if (subagent?.record.previousRunId && !equalData(resolved, subagent.source))
2798
+ throw new TypeError(
2799
+ "The helper's admitted definition changed. Restore its original configuration before continuing.",
2800
+ );
2801
+ if (spec)
2802
+ resolved.instructions = subagentInstructions(resolved.instructions, spec.instructions);
2803
+ const childLimits = spec ? subagentLimits(limits, spec.limits) : limits;
2804
+ if (inlineBytes(frozen.history, frozen.input) > childLimits.inlineBytes)
2805
+ throw new TypeError("The helper input exceeds its admitted inline byte limit.");
2806
+ const { history, input, session } = frozen;
2807
+ const startedAt = Date.now();
2808
+ return {
2809
+ kind: "agent",
2810
+ format: 3,
2811
+ agentId: id,
2812
+ version,
2813
+ runId,
2814
+ attemptId: crypto.randomUUID(),
2815
+ startedAt,
2816
+ definition: resolved,
2817
+ ...(record ? { subagent: record } : {}),
2818
+ history: copyData(history),
2819
+ input: copyData(input),
2820
+ inputs: [],
2821
+ guards: [],
2822
+ compactions: [],
2823
+ ...(session ? { session: copyData(session) } : {}),
2824
+ limits: copyData(childLimits),
2825
+ models: [],
2826
+ delegations: [],
2827
+ state: { status: "running" },
2828
+ tree: tree
2829
+ ? copyData(tree)
2830
+ : {
2831
+ runId,
2832
+ startedAt,
2833
+ limits: copyData(treeLimits),
2834
+ ...(options.memory ? { memory: memoryScopes(options.memory) } : {}),
2835
+ },
2836
+ };
2837
+ }
2838
+
2839
+ const runtime: AgentRuntime<T | string | H> = {
2840
+ node: {
2841
+ restore: (raw, tree, subagent) => runtime.restore(raw, tree, subagent),
2842
+ hydrate: (node) => runtime.hydrate(agentSnapshot(node)),
2843
+ answerRequests: (node, options, scope, answers, signal) =>
2844
+ answerRequests(agentSnapshot(node), options, scope, answers, signal),
2845
+ execute: (node, options, scope, answers) =>
2846
+ execute(agentSnapshot(node), options, scope, answers),
2847
+ },
2848
+ handoffs: [...handoffs.values()],
2849
+ tools: Object.freeze([...capabilities.values()]),
2850
+ enabledTools: Array.isArray(enabledTools) ? Object.freeze([...enabledTools]) : undefined,
2851
+ limits: immutableCopy(limits),
2852
+ async checkTools(snapshot, options) {
2853
+ const signal = options.signal ?? new AbortController().signal;
2854
+ const current = checkNames(
2855
+ typeof enabledTools === "function"
2856
+ ? await untilAbort(
2857
+ Promise.resolve(
2858
+ enabledTools(
2859
+ Object.freeze({
2860
+ agentId: id,
2861
+ version,
2862
+ runId: snapshot.runId,
2863
+ ...immutableCopy({ history: snapshot.history, input: snapshot.input }),
2864
+ context: Object.freeze({ ...options.context }),
2865
+ signal,
2866
+ }),
2867
+ ),
2868
+ ),
2869
+ signal,
2870
+ )
2871
+ : (enabledTools ?? names),
2872
+ );
2873
+ if (
2874
+ snapshot.definition.enabledTools.some(
2875
+ (name) => name !== RESULT_TOOL_NAME && !current.includes(name),
2876
+ )
2877
+ )
2878
+ fail(
2879
+ "subagent_grant_changed",
2880
+ "The host revoked a helper capability. Obtain fresh authorization before starting different work.",
2881
+ );
2882
+ },
2883
+ configuration() {
2884
+ const { onActivity: _activity, onRateLimit: _rateLimit, ...modelSettings } = settings;
2885
+ return immutableCopy({
2886
+ id,
2887
+ version,
2888
+ provider: { id: provider.id, model: provider.model },
2889
+ instructions: typeof instructions === "string" ? instructions : null,
2890
+ enabledTools: Array.isArray(enabledTools) ? enabledTools : null,
2891
+ modelSettings,
2892
+ limits,
2893
+ output: output?.schema ?? null,
2894
+ stopAtTools,
2895
+ recovery,
2896
+ guardrails: guardPolicy,
2897
+ compaction,
2898
+ toolRetries,
2899
+ ...(memory ? { memory } : {}),
2900
+ tools: tools.map((tool) => ({
2901
+ definition: tool.definition(),
2902
+ needsApproval: tool.needsApproval === true,
2903
+ ...(isDelegation(tool)
2904
+ ? {
2905
+ kind: "delegation",
2906
+ specialists: tool.specialists.map(({ id, version }) => ({ id, version })),
2907
+ }
2908
+ : isHandoff(tool)
2909
+ ? { kind: "handoff", target: handoffRef(tool.target()) }
2910
+ : isCodeTool(tool)
2911
+ ? {
2912
+ kind: "code",
2913
+ limits: tool.limits,
2914
+ bindings: tool.tools.map((bound) => ({
2915
+ definition: bound.definition(),
2916
+ outputSchema: bound.outputSchema,
2917
+ isReadOnly: bound.isReadOnly,
2918
+ needsApproval: bound.needsApproval,
2919
+ isConcurrencySafe: bound.isConcurrencySafe,
2920
+ timeoutMs: bound.timeoutMs,
2921
+ })),
2922
+ }
2923
+ : isClientTool(tool)
2924
+ ? { kind: "client", resultSchema: tool.resultSchema }
2925
+ : {
2926
+ kind: "tool",
2927
+ isReadOnly: tool.isReadOnly === true,
2928
+ isConcurrencySafe: tool.isConcurrencySafe === true,
2929
+ isTerminal: tool.isTerminal === true,
2930
+ }),
2931
+ })),
2932
+ });
2933
+ },
2934
+ execute,
2935
+ answerRequests,
2936
+ freeze,
2937
+ create,
2938
+ async open(input, options, runId) {
2939
+ options = { ...options, memory: readMemoryBinding(options.memory) };
2940
+ if (needsMemory && !options.memory)
2941
+ throw new TypeError("This agent needs authenticated memory access in RunOptions.memory.");
2942
+ // Everything before the snapshot exists runs outside the journal: a paid summarizer in
2943
+ // prepareHistory can run again if the process dies before the first checkpoint.
2944
+ const signal = options.signal ?? new AbortController().signal;
2945
+ const session = options.session;
2946
+ let start: RunStart;
2947
+ if (session) {
2948
+ if (isRecord(input) && "messages" in input)
2949
+ throw new TypeError(
2950
+ "With a session, pass only the new turn. The session holds the history.",
2951
+ );
2952
+ // Checked before the load, so a turn that would be refused costs no read.
2953
+ const turn = readInput(input, "caller").input;
2954
+ checkInline({ history: [], input: turn });
2955
+ const loaded: unknown = await untilAbort(
2956
+ Promise.resolve(
2957
+ session.load({
2958
+ ...(options.historyLimit !== undefined ? { limit: options.historyLimit } : {}),
2959
+ signal,
2960
+ }),
2961
+ ),
2962
+ signal,
2963
+ );
2964
+ if (!isRecord(loaded) || !isRevision(loaded.revision))
2965
+ throw new TypeError("session.load must return { messages, revision }.");
2966
+ start = {
2967
+ history: readStored(loaded.messages, "session.load"),
2968
+ input: turn,
2969
+ session: { id: session.id, revision: loaded.revision },
2970
+ };
2971
+ } else {
2972
+ if (options.historyLimit !== undefined)
2973
+ throw new TypeError(
2974
+ "historyLimit applies to a session. Trim the messages you pass in yourself.",
2975
+ );
2976
+ start = readInput(input, "caller");
2977
+ }
2978
+ if (options.prepareHistory) {
2979
+ const prepared: unknown = await untilAbort(
2980
+ Promise.resolve(options.prepareHistory(copyData(start.history))),
2981
+ signal,
2982
+ );
2983
+ start = { ...start, history: readStored(prepared, "prepareHistory") };
2984
+ }
2985
+ return create(start, runId, undefined, options);
2986
+ },
2987
+ restore(raw, tree, subagent) {
2988
+ if (isRecord(raw) && (!equalData(raw.subagent, subagent) || (subagent && !tree)))
2989
+ throw new TypeError("Restore a model-created helper through its owning creation tool.");
2990
+ const snapshot = readSnapshot(
2991
+ raw,
2992
+ id,
2993
+ version,
2994
+ subagent ? subagentLimits(limits, subagent.spec.limits) : limits,
2995
+ output ? RESULT_TOOL_NAME : undefined,
2996
+ codeTools,
2997
+ );
2998
+ checkNames(snapshot.definition.enabledTools);
2999
+ if (!equalData(snapshot.definition.memory, memory))
3000
+ throw new TypeError("Restore the same memory recall policy before resuming.");
3001
+ if (
3002
+ !equalData(snapshot.definition.compaction, compaction) ||
3003
+ !equalData(snapshot.definition.toolRetries?.policy ?? null, toolRetries)
3004
+ )
3005
+ throw new TypeError(
3006
+ "The recorded compaction or tool retry policy changed. Restore the same definition before resuming.",
3007
+ );
3008
+ if (!equalData(snapshot.definition.guardrails, guardPolicy))
3009
+ throw new TypeError(
3010
+ "The recorded guard policy changed. Restore the same guard identity, stages and limits.",
3011
+ );
3012
+ if (
3013
+ !equalData(snapshot.definition.recovery?.policy ?? null, recovery) ||
3014
+ (snapshot.definition.recovery &&
3015
+ !equalData(snapshot.definition.recovery.provider, {
3016
+ id: provider.id,
3017
+ model: provider.model,
3018
+ }))
3019
+ )
3020
+ throw new TypeError(
3021
+ "The recorded recovery policy or provider identity changed. Restore the same profile or reconcile the run.",
3022
+ );
3023
+ if (
3024
+ !equalData(snapshot.definition.stopAtTools, stopAtTools) ||
3025
+ (output && !snapshot.definition.enabledTools.includes(RESULT_TOOL_NAME))
3026
+ )
3027
+ throw new TypeError("The recorded tool behavior does not match this agent version.");
3028
+ const choice = snapshot.definition.modelSettings.toolChoice;
3029
+ if (
3030
+ (output && choice === "none") ||
3031
+ (choice === "required" && snapshot.definition.enabledTools.length === 0) ||
3032
+ (typeof choice === "object" && !snapshot.definition.enabledTools.includes(choice.name))
3033
+ )
3034
+ throw new TypeError("The recorded tool choice does not name an enabled tool.");
3035
+ if (
3036
+ tree
3037
+ ? !equalData(snapshot.tree, tree)
3038
+ : snapshot.tree.runId !== snapshot.runId || !equalData(snapshot.tree.limits, treeLimits)
3039
+ )
3040
+ throw new TypeError("The snapshot tree does not match this root or its limits.");
3041
+ for (const model of snapshot.models) {
3042
+ if (model.status !== "completed") continue;
3043
+ for (const [index, tool] of model.tools.entries()) {
3044
+ const call = model.turn.message.toolCalls?.[index];
3045
+ const descriptor =
3046
+ call &&
3047
+ snapshot.definition.enabledTools.includes(call.name) &&
3048
+ snapshot.definition.modelSettings.toolChoice !== "none" &&
3049
+ descriptorFor(call.name, snapshot, tool.id);
3050
+ const journal = snapshot.delegations.find((entry) => entry.operationId === tool.id);
3051
+ if (descriptor && tool.status !== "pending") {
3052
+ if (!journal || tool.status === "running")
3053
+ throw new TypeError(
3054
+ "A delegation needs its own child journal, not an ordinary effect marker.",
3055
+ );
3056
+ } else if (journal)
3057
+ throw new TypeError("The saved delegation is not in this agent definition.");
3058
+ if (!journal || !descriptor) continue;
3059
+ if (journal.kind !== (call && handoffs.has(call.name) ? "handoff" : "delegation"))
3060
+ throw new TypeError("The saved delegation kind does not match its registered tool.");
3061
+ if (journal.kind === "handoff") checkHandoffTargets(agent);
3062
+ checkSubagentChildren(descriptor, snapshot, journal);
3063
+ for (const entry of journal.children) {
3064
+ const agent = descriptor.specialists.find(
3065
+ (agent) =>
3066
+ agent.kind === entry.snapshot.kind &&
3067
+ agent.id === nodeId(entry.snapshot) &&
3068
+ agent.version === entry.snapshot.version,
3069
+ );
3070
+ if (!agent)
3071
+ throw new TypeError("The saved child is not a registered specialist version.");
3072
+ entry.snapshot = runtimeOf(agent).restore(
3073
+ entry.snapshot,
3074
+ snapshot.tree,
3075
+ entry.snapshot.kind === "agent" ? entry.snapshot.subagent : undefined,
3076
+ );
3077
+ }
3078
+ }
3079
+ }
3080
+ if (snapshot.state.status === "completed") completedOutput(snapshot);
3081
+ return snapshot;
3082
+ },
3083
+ hydrate(snapshot) {
3084
+ const record = recordOf(snapshot);
3085
+ const state = record.snapshot.state;
3086
+ if (state.status === "running") throw new Error("A child has not settled yet.");
3087
+ return state.status === "completed"
3088
+ ? { ...record, status: "completed", output: completedOutput(record.snapshot) }
3089
+ : state.status === "suspended"
3090
+ ? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
3091
+ : { ...record, ...state };
3092
+ },
3093
+ };
3094
+
3095
+ /** Once per root, after its final checkpoint. Never changes the run's own status. */
3096
+ async function appendTurn(
3097
+ outcome: RunOutcome<T | string | H>,
3098
+ options: RunOptions,
3099
+ tree: ExecutionTree,
3100
+ ): Promise<SessionStatus | undefined> {
3101
+ const ref = outcome.snapshot.session;
3102
+ if (!ref) return undefined;
3103
+ const session = options.session;
3104
+ // A waiting run has no settled turn yet. After a failed checkpoint the host's journal is
3105
+ // behind this outcome: resuming what it saved settles again and appends then.
3106
+ if (!session || outcome.status === "suspended" || tree.checkpointFailed)
3107
+ return { id: ref.id, status: "pending" };
3108
+ // A Stop ends the run, not the record of it: the turn the person sent is still saved.
3109
+ const signal =
3110
+ options.signal && !options.signal.aborted ? options.signal : new AbortController().signal;
3111
+ try {
3112
+ const saved: unknown = await untilAbort(
3113
+ Promise.resolve(
3114
+ session.append(
3115
+ immutableCopy({
3116
+ runId: outcome.runId,
3117
+ after: ref.revision,
3118
+ messages: outcome.newMessages,
3119
+ }),
3120
+ { signal },
3121
+ ),
3122
+ ),
3123
+ signal,
3124
+ );
3125
+ if (!isRecord(saved) || !isId(saved.revision))
3126
+ throw new TypeError("session.append returned no revision.");
3127
+ return { id: ref.id, status: "saved", revision: saved.revision };
3128
+ } catch (error) {
3129
+ // By name, not instanceof: a store built against another copy of this package throws
3130
+ // its own SessionConflictError class.
3131
+ const conflict = error instanceof Error && error.name === "SessionConflictError";
3132
+ return {
3133
+ id: ref.id,
3134
+ status: "unsaved",
3135
+ error: conflict
3136
+ ? {
3137
+ code: "session_conflict",
3138
+ message:
3139
+ "The conversation changed after this run loaded it. Load it again before you continue it.",
3140
+ }
3141
+ : {
3142
+ code: "session_failed",
3143
+ message: `The session did not save this turn: ${messageOf(error)}`,
3144
+ },
3145
+ };
3146
+ }
3147
+ }
3148
+
3149
+ async function root(
3150
+ snapshot: RunSnapshot,
3151
+ options: RunOptions,
3152
+ answers?: Readonly<Record<string, unknown>>,
3153
+ ) {
3154
+ const tree = new ExecutionTree(snapshot, options);
3155
+ let outcome: RunOutcome<T | string | H>;
3156
+ try {
3157
+ outcome = await execute(snapshot, options, { tree, depth: 0, path: [] }, answers);
3158
+ } finally {
3159
+ tree.close();
3160
+ }
3161
+ const session = await appendTurn(outcome, options, tree);
3162
+ return session ? { ...outcome, session } : outcome;
3163
+ }
3164
+
3165
+ const agent: Agent<T | string | H> = {
3166
+ kind: "agent",
3167
+ id,
3168
+ version,
3169
+ [AGENT_RUNTIME]: runtime,
3170
+ asTool(options) {
3171
+ return specialistTool(agent, options);
3172
+ },
3173
+ async run(input, options = {}) {
3174
+ checkOptions(options);
3175
+ options = { ...options, memory: readMemoryBinding(options.memory) };
3176
+ return root(
3177
+ await runtime.open(input, options, options.runId ?? crypto.randomUUID()),
3178
+ options,
3179
+ );
3180
+ },
3181
+ async resume(raw, options) {
3182
+ checkOptions(options, "resume");
3183
+ options = { ...options, memory: readMemoryBinding(options.memory) };
3184
+ const snapshot = runtime.restore(raw);
3185
+ checkMemoryBinding(snapshot, options.memory);
3186
+ if (options.session && options.session.id !== snapshot.session?.id)
3187
+ throw new TypeError(
3188
+ snapshot.session
3189
+ ? "This run belongs to another session."
3190
+ : "This run has no session. Resume it without one.",
3191
+ );
3192
+ const answers = readAnswers(snapshot, options.answers ?? {});
3193
+ await authorizeTree(snapshot, options.host);
3194
+ snapshot.attemptId = crypto.randomUUID();
3195
+ return root(snapshot, options, answers);
3196
+ },
3197
+ };
3198
+ return Object.freeze(agent);
3199
+ }