@providerkit/agents 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (291) hide show
  1. package/LICENSE-APACHE-2.0 +202 -0
  2. package/README.md +2108 -52
  3. package/THIRD_PARTY_NOTICES.md +521 -0
  4. package/dist/a2a/auth.d.ts +10 -0
  5. package/dist/a2a/auth.d.ts.map +1 -0
  6. package/dist/a2a/auth.js +52 -0
  7. package/dist/a2a/auth.js.map +1 -0
  8. package/dist/a2a/client.d.ts +74 -0
  9. package/dist/a2a/client.d.ts.map +1 -0
  10. package/dist/a2a/client.js +601 -0
  11. package/dist/a2a/client.js.map +1 -0
  12. package/dist/a2a/index.d.ts +22 -0
  13. package/dist/a2a/index.d.ts.map +1 -0
  14. package/dist/a2a/index.js +11 -0
  15. package/dist/a2a/index.js.map +1 -0
  16. package/dist/a2a/memory-runs.d.ts +62 -0
  17. package/dist/a2a/memory-runs.d.ts.map +1 -0
  18. package/dist/a2a/memory-runs.js +349 -0
  19. package/dist/a2a/memory-runs.js.map +1 -0
  20. package/dist/a2a/policy.d.ts +15 -0
  21. package/dist/a2a/policy.d.ts.map +1 -0
  22. package/dist/a2a/policy.js +114 -0
  23. package/dist/a2a/policy.js.map +1 -0
  24. package/dist/a2a/push.d.ts +34 -0
  25. package/dist/a2a/push.d.ts.map +1 -0
  26. package/dist/a2a/push.js +180 -0
  27. package/dist/a2a/push.js.map +1 -0
  28. package/dist/a2a/remote.d.ts +155 -0
  29. package/dist/a2a/remote.d.ts.map +1 -0
  30. package/dist/a2a/remote.js +1196 -0
  31. package/dist/a2a/remote.js.map +1 -0
  32. package/dist/a2a/server.d.ts +110 -0
  33. package/dist/a2a/server.d.ts.map +1 -0
  34. package/dist/a2a/server.js +1139 -0
  35. package/dist/a2a/server.js.map +1 -0
  36. package/dist/a2a/signing.d.ts +21 -0
  37. package/dist/a2a/signing.d.ts.map +1 -0
  38. package/dist/a2a/signing.js +305 -0
  39. package/dist/a2a/signing.js.map +1 -0
  40. package/dist/a2a/tasks.d.ts +88 -0
  41. package/dist/a2a/tasks.d.ts.map +1 -0
  42. package/dist/a2a/tasks.js +170 -0
  43. package/dist/a2a/tasks.js.map +1 -0
  44. package/dist/a2a/wire.d.ts +267 -0
  45. package/dist/a2a/wire.d.ts.map +1 -0
  46. package/dist/a2a/wire.js +1202 -0
  47. package/dist/a2a/wire.js.map +1 -0
  48. package/dist/background-types.d.ts +76 -0
  49. package/dist/background-types.d.ts.map +1 -0
  50. package/dist/background-types.js +2 -0
  51. package/dist/background-types.js.map +1 -0
  52. package/dist/child.d.ts +25 -0
  53. package/dist/child.d.ts.map +1 -0
  54. package/dist/child.js +129 -0
  55. package/dist/child.js.map +1 -0
  56. package/dist/code-driver.d.ts +40 -0
  57. package/dist/code-driver.d.ts.map +1 -0
  58. package/dist/code-driver.js +2 -0
  59. package/dist/code-driver.js.map +1 -0
  60. package/dist/code-mode.d.ts +3 -0
  61. package/dist/code-mode.d.ts.map +1 -0
  62. package/dist/code-mode.js +2 -0
  63. package/dist/code-mode.js.map +1 -0
  64. package/dist/code-script.d.ts +3 -0
  65. package/dist/code-script.d.ts.map +1 -0
  66. package/dist/code-script.js +149 -0
  67. package/dist/code-script.js.map +1 -0
  68. package/dist/code.d.ts +75 -0
  69. package/dist/code.d.ts.map +1 -0
  70. package/dist/code.js +326 -0
  71. package/dist/code.js.map +1 -0
  72. package/dist/compaction.d.ts +15 -0
  73. package/dist/compaction.d.ts.map +1 -0
  74. package/dist/compaction.js +168 -0
  75. package/dist/compaction.js.map +1 -0
  76. package/dist/delegation.d.ts +85 -16
  77. package/dist/delegation.d.ts.map +1 -1
  78. package/dist/delegation.js +240 -106
  79. package/dist/delegation.js.map +1 -1
  80. package/dist/evals/driver.d.ts +10 -0
  81. package/dist/evals/driver.d.ts.map +1 -0
  82. package/dist/evals/driver.js +192 -0
  83. package/dist/evals/driver.js.map +1 -0
  84. package/dist/evals/journal.d.ts +26 -0
  85. package/dist/evals/journal.d.ts.map +1 -0
  86. package/dist/evals/journal.js +483 -0
  87. package/dist/evals/journal.js.map +1 -0
  88. package/dist/evals/judge.d.ts +31 -0
  89. package/dist/evals/judge.d.ts.map +1 -0
  90. package/dist/evals/judge.js +142 -0
  91. package/dist/evals/judge.js.map +1 -0
  92. package/dist/evals/report.d.ts +38 -0
  93. package/dist/evals/report.d.ts.map +1 -0
  94. package/dist/evals/report.js +241 -0
  95. package/dist/evals/report.js.map +1 -0
  96. package/dist/evals/runner.d.ts +24 -0
  97. package/dist/evals/runner.d.ts.map +1 -0
  98. package/dist/evals/runner.js +655 -0
  99. package/dist/evals/runner.js.map +1 -0
  100. package/dist/evals/scorers.d.ts +36 -0
  101. package/dist/evals/scorers.d.ts.map +1 -0
  102. package/dist/evals/scorers.js +259 -0
  103. package/dist/evals/scorers.js.map +1 -0
  104. package/dist/evals/simulation.d.ts +7 -0
  105. package/dist/evals/simulation.d.ts.map +1 -0
  106. package/dist/evals/simulation.js +38 -0
  107. package/dist/evals/simulation.js.map +1 -0
  108. package/dist/evals/testing.d.ts +36 -0
  109. package/dist/evals/testing.d.ts.map +1 -0
  110. package/dist/evals/testing.js +87 -0
  111. package/dist/evals/testing.js.map +1 -0
  112. package/dist/evals/trajectory.d.ts +11 -0
  113. package/dist/evals/trajectory.d.ts.map +1 -0
  114. package/dist/evals/trajectory.js +180 -0
  115. package/dist/evals/trajectory.js.map +1 -0
  116. package/dist/evals/types.d.ts +431 -0
  117. package/dist/evals/types.d.ts.map +1 -0
  118. package/dist/evals/types.js +4 -0
  119. package/dist/evals/types.js.map +1 -0
  120. package/dist/evals.d.ts +14 -0
  121. package/dist/evals.d.ts.map +1 -0
  122. package/dist/evals.js +9 -0
  123. package/dist/evals.js.map +1 -0
  124. package/dist/extensions.d.ts +33 -0
  125. package/dist/extensions.d.ts.map +1 -0
  126. package/dist/extensions.js +188 -0
  127. package/dist/extensions.js.map +1 -0
  128. package/dist/handoff.d.ts +58 -0
  129. package/dist/handoff.d.ts.map +1 -0
  130. package/dist/handoff.js +160 -0
  131. package/dist/handoff.js.map +1 -0
  132. package/dist/index.d.ts +14 -0
  133. package/dist/index.d.ts.map +1 -1
  134. package/dist/index.js +8 -0
  135. package/dist/index.js.map +1 -1
  136. package/dist/input.d.ts +42 -0
  137. package/dist/input.d.ts.map +1 -0
  138. package/dist/input.js +266 -0
  139. package/dist/input.js.map +1 -0
  140. package/dist/mcp.d.ts +77 -0
  141. package/dist/mcp.d.ts.map +1 -0
  142. package/dist/mcp.js +505 -0
  143. package/dist/mcp.js.map +1 -0
  144. package/dist/memory-store.d.ts +11 -0
  145. package/dist/memory-store.d.ts.map +1 -0
  146. package/dist/memory-store.js +272 -0
  147. package/dist/memory-store.js.map +1 -0
  148. package/dist/memory.d.ts +212 -0
  149. package/dist/memory.d.ts.map +1 -0
  150. package/dist/memory.js +613 -0
  151. package/dist/memory.js.map +1 -0
  152. package/dist/otel.d.ts +74 -0
  153. package/dist/otel.d.ts.map +1 -0
  154. package/dist/otel.js +427 -0
  155. package/dist/otel.js.map +1 -0
  156. package/dist/progress.d.ts +17 -0
  157. package/dist/progress.d.ts.map +1 -0
  158. package/dist/progress.js +193 -0
  159. package/dist/progress.js.map +1 -0
  160. package/dist/quickjs.d.ts +19 -0
  161. package/dist/quickjs.d.ts.map +1 -0
  162. package/dist/quickjs.js +519 -0
  163. package/dist/quickjs.js.map +1 -0
  164. package/dist/recovery.d.ts +10 -0
  165. package/dist/recovery.d.ts.map +1 -0
  166. package/dist/recovery.js +62 -0
  167. package/dist/recovery.js.map +1 -0
  168. package/dist/request.d.ts +88 -0
  169. package/dist/request.d.ts.map +1 -0
  170. package/dist/request.js +422 -0
  171. package/dist/request.js.map +1 -0
  172. package/dist/run.d.ts +16 -4
  173. package/dist/run.d.ts.map +1 -1
  174. package/dist/run.js +2016 -245
  175. package/dist/run.js.map +1 -1
  176. package/dist/runs.d.ts +77 -34
  177. package/dist/runs.d.ts.map +1 -1
  178. package/dist/runs.js +267 -85
  179. package/dist/runs.js.map +1 -1
  180. package/dist/schema-to-ts.d.ts +4 -0
  181. package/dist/schema-to-ts.d.ts.map +1 -0
  182. package/dist/schema-to-ts.js +191 -0
  183. package/dist/schema-to-ts.js.map +1 -0
  184. package/dist/session.d.ts +23 -0
  185. package/dist/session.d.ts.map +1 -0
  186. package/dist/session.js +137 -0
  187. package/dist/session.js.map +1 -0
  188. package/dist/snapshot.d.ts +57 -8
  189. package/dist/snapshot.d.ts.map +1 -1
  190. package/dist/snapshot.js +1206 -109
  191. package/dist/snapshot.js.map +1 -1
  192. package/dist/steering.d.ts +75 -0
  193. package/dist/steering.d.ts.map +1 -0
  194. package/dist/steering.js +214 -0
  195. package/dist/steering.js.map +1 -0
  196. package/dist/subagents.d.ts +141 -0
  197. package/dist/subagents.d.ts.map +1 -0
  198. package/dist/subagents.js +746 -0
  199. package/dist/subagents.js.map +1 -0
  200. package/dist/tool-retry.d.ts +12 -0
  201. package/dist/tool-retry.d.ts.map +1 -0
  202. package/dist/tool-retry.js +53 -0
  203. package/dist/tool-retry.js.map +1 -0
  204. package/dist/tree.d.ts +62 -6
  205. package/dist/tree.d.ts.map +1 -1
  206. package/dist/tree.js +192 -23
  207. package/dist/tree.js.map +1 -1
  208. package/dist/types.d.ts +767 -52
  209. package/dist/types.d.ts.map +1 -1
  210. package/dist/workflow-snapshot.d.ts +8 -0
  211. package/dist/workflow-snapshot.d.ts.map +1 -0
  212. package/dist/workflow-snapshot.js +276 -0
  213. package/dist/workflow-snapshot.js.map +1 -0
  214. package/dist/workflow-types.d.ts +171 -0
  215. package/dist/workflow-types.d.ts.map +1 -0
  216. package/dist/workflow-types.js +2 -0
  217. package/dist/workflow-types.js.map +1 -0
  218. package/dist/workflow.d.ts +19 -0
  219. package/dist/workflow.d.ts.map +1 -0
  220. package/dist/workflow.js +1053 -0
  221. package/dist/workflow.js.map +1 -0
  222. package/examples/a2a-remote.ts +85 -0
  223. package/examples/a2a-server.ts +100 -0
  224. package/examples/background.ts +18 -4
  225. package/examples/code-mode.ts +76 -0
  226. package/examples/conversation.ts +57 -0
  227. package/examples/evals.ts +79 -0
  228. package/examples/guardrails.ts +56 -0
  229. package/examples/handoff.ts +79 -0
  230. package/examples/memory.ts +44 -0
  231. package/examples/otel.ts +99 -0
  232. package/examples/steering.ts +69 -0
  233. package/examples/structured-handoff.ts +92 -0
  234. package/examples/subagents.ts +127 -0
  235. package/examples/workflow.ts +74 -0
  236. package/package.json +58 -6
  237. package/src/a2a/auth.ts +62 -0
  238. package/src/a2a/client.ts +733 -0
  239. package/src/a2a/index.ts +74 -0
  240. package/src/a2a/memory-runs.ts +448 -0
  241. package/src/a2a/policy.ts +148 -0
  242. package/src/a2a/push.ts +251 -0
  243. package/src/a2a/remote.ts +1652 -0
  244. package/src/a2a/server.ts +1390 -0
  245. package/src/a2a/signing.ts +348 -0
  246. package/src/a2a/tasks.ts +260 -0
  247. package/src/a2a/wire.ts +1443 -0
  248. package/src/background-types.ts +86 -0
  249. package/src/child.ts +181 -0
  250. package/src/code-driver.ts +48 -0
  251. package/src/code-mode.ts +12 -0
  252. package/src/code-script.ts +149 -0
  253. package/src/code.ts +424 -0
  254. package/src/compaction.ts +212 -0
  255. package/src/delegation.ts +444 -155
  256. package/src/evals/driver.ts +222 -0
  257. package/src/evals/journal.ts +605 -0
  258. package/src/evals/judge.ts +188 -0
  259. package/src/evals/report.ts +295 -0
  260. package/src/evals/runner.ts +826 -0
  261. package/src/evals/scorers.ts +339 -0
  262. package/src/evals/simulation.ts +46 -0
  263. package/src/evals/testing.ts +126 -0
  264. package/src/evals/trajectory.ts +223 -0
  265. package/src/evals/types.ts +463 -0
  266. package/src/evals.ts +72 -0
  267. package/src/extensions.ts +247 -0
  268. package/src/handoff.ts +214 -0
  269. package/src/index.ts +51 -0
  270. package/src/input.ts +319 -0
  271. package/src/mcp.ts +690 -0
  272. package/src/memory-store.ts +366 -0
  273. package/src/memory.ts +893 -0
  274. package/src/otel.ts +568 -0
  275. package/src/progress.ts +214 -0
  276. package/src/quickjs.ts +524 -0
  277. package/src/recovery.ts +90 -0
  278. package/src/request.ts +513 -0
  279. package/src/run.ts +2678 -313
  280. package/src/runs.ts +464 -133
  281. package/src/schema-to-ts.ts +194 -0
  282. package/src/session.ts +178 -0
  283. package/src/snapshot.ts +1595 -124
  284. package/src/steering.ts +329 -0
  285. package/src/subagents.ts +1084 -0
  286. package/src/tool-retry.ts +86 -0
  287. package/src/tree.ts +223 -27
  288. package/src/types.ts +711 -52
  289. package/src/workflow-snapshot.ts +366 -0
  290. package/src/workflow-types.ts +213 -0
  291. package/src/workflow.ts +1316 -0
package/src/run.ts CHANGED
@@ -1,48 +1,133 @@
1
1
  import {
2
2
  EMPTY_USAGE,
3
+ ProviderError,
3
4
  ToolRegistry,
4
- addUsage,
5
5
  collectTurn,
6
+ createGate,
6
7
  defineTool,
7
8
  messageOf,
8
9
  parseToolArgs,
9
- type ChatMessage,
10
+ type Provider,
10
11
  type ProviderChunk,
11
12
  type Tool,
12
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";
13
60
  import {
14
61
  AGENT_RUNTIME,
15
62
  executeDelegation,
16
63
  isDelegation,
17
64
  specialistTool,
65
+ runtimeOf,
18
66
  type AgentRuntime,
19
- type ApprovalEvidence,
20
67
  type Delegation,
68
+ type RunStart,
21
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";
22
89
  import {
23
90
  ExecutionTree,
24
91
  Halt,
25
92
  authorizeTree,
93
+ emitEvent,
26
94
  fail,
27
95
  treeUsage,
96
+ nodeId,
97
+ wakeAt,
98
+ openRequests,
99
+ readAnswers,
100
+ requestRecords,
101
+ stopRequests,
28
102
  untilAbort,
29
103
  type ExecutionScope,
30
104
  } from "./tree.ts";
31
105
  import {
32
106
  checkOptions,
107
+ agentSnapshot,
33
108
  completeArguments,
34
109
  copyData,
35
110
  equalData,
111
+ finalToolResult,
112
+ finalHandoffResult,
36
113
  immutableCopy,
114
+ inlineBytes,
115
+ isBase64,
116
+ isEnabledTools,
37
117
  isId,
118
+ isNames,
38
119
  isRecord,
39
- isScope,
120
+ isRevision,
40
121
  isUsage,
122
+ jsonArguments,
41
123
  modelId,
124
+ recordCodeTools,
42
125
  readLimits,
126
+ readModelSettings,
43
127
  readTreeLimits,
44
128
  readSnapshot,
45
129
  readTurn,
130
+ snapshotInlineBytes,
46
131
  toolId,
47
132
  } from "./snapshot.ts";
48
133
  import type {
@@ -50,13 +135,23 @@ import type {
50
135
  AgentConfig,
51
136
  AgentDefinition,
52
137
  AgentEvent,
138
+ CompactionExecution,
139
+ EnabledTools,
140
+ LifecycleContext,
141
+ LifecycleEvent,
142
+ ModelInput,
143
+ MediaRef,
53
144
  ModelExecution,
54
145
  OperationReceipt,
55
- PendingApproval,
146
+ ProgramCall,
147
+ ToolExecution,
56
148
  ResultSchema,
149
+ RunContext,
150
+ RunDefinition,
57
151
  RunOptions,
58
152
  RunOutcome,
59
153
  RunSnapshot,
154
+ SessionStatus,
60
155
  ToolRequest,
61
156
  ToolResult,
62
157
  } from "./types.ts";
@@ -66,53 +161,93 @@ export const RESULT_TOOL_NAME = "submit_result";
66
161
 
67
162
  type CompletedModel = Extract<ModelExecution, { status: "completed" }>;
68
163
 
69
- function historyOf(snapshot: RunSnapshot, instructions: string): ChatMessage[] {
70
- const history: ChatMessage[] = [
71
- { role: "system", content: instructions },
72
- { role: "user", content: snapshot.input },
73
- ];
74
- for (const model of snapshot.models) {
75
- // Never give a provider half a tool round. The journal retains unfinished work.
76
- if (model.status !== "completed" || model.tools.some((tool) => tool.status !== "completed"))
77
- break;
78
- history.push(model.turn.message);
79
- for (const [index, tool] of model.tools.entries()) {
80
- const call = model.turn.message.toolCalls?.[index];
81
- if (call && tool.status === "completed") {
82
- history.push({
83
- role: "tool",
84
- toolCallId: call.id,
85
- name: call.name,
86
- content: tool.result.content,
87
- });
88
- }
89
- }
90
- }
91
- return copyData(history);
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
+ };
92
178
  }
93
179
 
94
- function recordOf(snapshot: RunSnapshot, instructions: string) {
180
+ function recordOf(snapshot: RunSnapshot) {
95
181
  const saved = copyData(snapshot);
96
182
  const receipts: OperationReceipt[] = [];
97
- let usage = { ...EMPTY_USAGE };
98
- for (const model of saved.models) {
99
- usage = addUsage(usage, model.usage);
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
+ });
100
193
  receipts.push({
101
194
  kind: "model",
195
+ ...(saved.compactions.some((entry) => entry.id === model.id)
196
+ ? { purpose: "compaction" as const }
197
+ : {}),
102
198
  id: model.id,
103
199
  attemptId: model.attemptId,
104
200
  status: model.status,
201
+ billing: model.billing,
105
202
  usage: model.usage,
106
203
  ...(model.status === "completed" && model.turn.source ? { source: model.turn.source } : {}),
107
204
  });
108
205
  if (model.status !== "completed") continue;
109
206
  for (const [index, tool] of model.tools.entries()) {
110
207
  const call = model.turn.message.toolCalls?.[index];
111
- if (!call || tool.status === "pending") continue;
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;
112
249
  receipts.push({
113
- kind: saved.delegations.some((journal) => journal.operationId === tool.id)
114
- ? "delegation"
115
- : "tool",
250
+ kind: saved.delegations.find((journal) => journal.operationId === tool.id)?.kind ?? "tool",
116
251
  id: tool.id,
117
252
  callId: call.id,
118
253
  attemptId: tool.attemptId,
@@ -121,30 +256,71 @@ function recordOf(snapshot: RunSnapshot, instructions: string) {
121
256
  });
122
257
  }
123
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
+ };
124
265
  return {
125
266
  runId: saved.runId,
126
267
  attemptId: saved.attemptId,
127
268
  usage,
128
269
  treeUsage: treeUsage(saved),
129
270
  receipts,
130
- history: historyOf(saved, instructions),
271
+ inputs: inputReceipts(saved),
272
+ ...handoffRecord(saved),
131
273
  snapshot: saved,
274
+ ...(session ? { session } : {}),
132
275
  };
133
276
  }
134
277
 
135
- export function defineAgent<T>(definition: AgentConfig & { output: ResultSchema<T> }): Agent<T>;
136
- export function defineAgent(definition: AgentDefinition): Agent<string>;
137
- export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string> {
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> {
138
296
  const { id, version, instructions, provider } = definition;
139
297
  if (
140
298
  !isId(id) ||
141
299
  !isId(version) ||
142
- typeof instructions !== "string" ||
300
+ (typeof instructions !== "string" && typeof instructions !== "function") ||
143
301
  !provider ||
144
302
  typeof provider.createStream !== "function"
145
303
  ) {
146
304
  throw new TypeError("An agent needs an id, version, instructions and provider.");
147
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;
148
324
  const limits = readLimits(definition.limits);
149
325
  const treeLimits = readTreeLimits(definition.treeLimits);
150
326
  const output = definition.output && {
@@ -159,20 +335,56 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
159
335
  ) {
160
336
  throw new TypeError("An output contract needs an object schema and a runtime validator.");
161
337
  }
162
- const tools = [...(definition.tools ?? [])];
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);
163
351
  if (
164
- new Set(tools.map((tool) => tool.name)).size !== tools.length ||
165
- tools.some(
166
- (tool) =>
167
- !isId(tool.name) ||
168
- tool.name === RESULT_TOOL_NAME ||
169
- (!isDelegation(tool) && tool.isTerminal),
352
+ [...capabilities.values()].some(
353
+ (tool) => MEMORY_TOOL_NAMES.includes(tool.name) && !isMemoryTool(tool),
170
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)
171
365
  ) {
172
366
  throw new TypeError(
173
- `Use unique tool names and the output contract for terminal results. ${RESULT_TOOL_NAME} is reserved.`,
367
+ `Use unique tool names. ${RESULT_TOOL_NAME} is reserved for the output contract.`,
174
368
  );
175
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);
176
388
  if (output) {
177
389
  tools.push(
178
390
  defineTool({
@@ -188,23 +400,384 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
188
400
  }),
189
401
  );
190
402
  }
191
- const registry = new ToolRegistry(tools.filter((tool): tool is Tool => !isDelegation(tool)));
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
+ }
192
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
+ }
193
576
 
194
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.");
195
581
  if (output) return output.validate(copyData(candidate));
196
582
  if (typeof candidate !== "string" || !candidate.trim())
197
583
  throw new TypeError("The model returned no answer.");
198
584
  return candidate;
199
585
  }
200
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
+
201
773
  async function execute(
202
774
  snapshot: RunSnapshot,
203
775
  options: RunOptions,
204
776
  scope: ExecutionScope,
205
- evidence?: ApprovalEvidence,
206
- ): Promise<RunOutcome<T | string>> {
777
+ answers?: Readonly<Record<string, unknown>>,
778
+ ): Promise<RunOutcome<T | string | H>> {
207
779
  const host = options.host;
780
+ const limits = snapshot.limits;
208
781
  const deadline = snapshot.startedAt + limits.elapsedMs;
209
782
  const timeout = new AbortController();
210
783
  const signal = AbortSignal.any([
@@ -217,8 +790,8 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
217
790
  Math.max(0, deadline - Date.now()),
218
791
  );
219
792
  let release = () => {};
220
- let approved: PendingApproval | undefined;
221
- let completed: { output: T | string } | undefined;
793
+ let completed: { output: T | string | H } | undefined;
794
+ let started = false;
222
795
 
223
796
  function active(): void {
224
797
  scope.tree.active();
@@ -228,39 +801,322 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
228
801
  }
229
802
 
230
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> {
231
878
  try {
232
- void Promise.resolve(options.onEvent?.(immutableCopy(event))).catch(() => {});
233
- } catch {
234
- // Progress is not the durable journal, and an observer cannot stop execution.
879
+ await work();
880
+ } catch (error) {
881
+ await observe({ type: "tool_error", request }, callSignal);
882
+ throw error;
235
883
  }
236
884
  }
237
885
 
238
- const save = () => scope.tree.save();
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
+ }
239
1010
 
240
1011
  function usedTools(): number {
241
1012
  return snapshot.models.reduce(
242
1013
  (count, model) =>
243
1014
  count +
244
1015
  (model.status === "completed"
245
- ? model.tools.filter((tool) => tool.status !== "pending").length
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
+ )
246
1026
  : 0),
247
1027
  0,
248
1028
  );
249
1029
  }
250
1030
 
251
- function requestFor(model: CompletedModel, index: number): ToolRequest {
252
- const call = model.turn.message.toolCalls?.[index];
253
- const tool = model.tools[index];
254
- if (!call || !tool) fail("invalid_journal", "The tool call is missing from its journal.");
255
- return {
256
- agentId: id,
257
- version,
258
- runId: snapshot.runId,
259
- attemptId: snapshot.attemptId,
260
- operationId: tool.id,
261
- call,
262
- arguments: parseToolArgs(call.arguments),
263
- };
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;
264
1120
  }
265
1121
 
266
1122
  async function finishTool(
@@ -269,24 +1125,103 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
269
1125
  request: ToolRequest,
270
1126
  result: ToolResult,
271
1127
  ): Promise<void> {
272
- model.tools[index] = {
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,
273
1208
  id: request.operationId,
274
- attemptId: snapshot.attemptId,
1209
+ attemptId: request.attemptId,
275
1210
  status: "completed",
276
1211
  result,
277
- };
1212
+ });
278
1213
  await save();
279
1214
  emit({ type: "tool_result", request, result });
280
1215
  }
281
1216
 
282
1217
  async function runTool(
283
- model: CompletedModel,
284
- index: number,
1218
+ slot: ToolSlot,
285
1219
  request: ToolRequest,
286
1220
  tool: Tool | undefined,
287
1221
  parallel: boolean,
288
1222
  ): Promise<void> {
289
- active();
1223
+ invocationActive(slot);
1224
+ const callSignal = slot.inner?.signal ?? signal;
290
1225
  let result: ToolResult;
291
1226
  if (!tool) {
292
1227
  result = {
@@ -300,75 +1235,603 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
300
1235
  kind: "invalid_input",
301
1236
  content: "Tool arguments must be one complete JSON object. Send the full object again.",
302
1237
  };
303
- } else if (tool.isTerminal && model.tools.length !== 1) {
1238
+ } else if (tool.isTerminal && slot.model?.tools.length !== 1) {
304
1239
  result = {
305
1240
  ok: false,
306
1241
  kind: "invalid_input",
307
- content: `Call ${RESULT_TOOL_NAME} alone, after the other tool results arrive.`,
1242
+ content: `Call ${tool.name} alone, after the other tool results arrive.`,
308
1243
  };
309
1244
  } else {
310
- const outcome = await scope.tree.invokeTool(parallel, signal, async () => {
311
- active();
312
- const approval =
313
- approved?.request.operationId === request.operationId ? approved : undefined;
314
- if (tool.needsApproval && !approval)
315
- fail(
316
- "approval_required",
317
- "This tool needs a host-approved decision.",
318
- request.operationId,
319
- );
320
- function checkExpiry(): void {
321
- if (approval && approval.scope.expiresAt <= Date.now())
322
- fail(
323
- "approval_expired",
324
- "The approval expired. Request a new decision before running this tool.",
325
- request.operationId,
326
- );
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;
327
1280
  }
328
- checkExpiry();
329
- await untilAbort(
330
- Promise.resolve(host?.beforeTool?.(immutableCopy(request), immutableCopy(approval))),
331
- signal,
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
+ ]),
332
1294
  );
333
- active();
334
- checkExpiry();
335
- emit({ type: "tool_start", request });
336
- active();
337
- // A synchronous observer can delay invocation past the approval's expiry.
338
- checkExpiry();
339
- return tool.invoke(copyData(request.arguments), {
340
- ...options.context,
341
- runId: snapshot.runId,
342
- attemptId: snapshot.attemptId,
343
- operationId: request.operationId,
344
- callId: request.call.id,
345
- signal,
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;
346
1322
  });
347
- });
348
- // Core reports an aborted invocation as data. It must not buy another model turn.
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.
349
1328
  if (!outcome.ok) active();
350
- result = outcome.ok
351
- ? { ok: true, content: outcome.summary }
352
- : { ok: false, content: outcome.error, kind: outcome.kind };
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
+ }
353
1411
  }
354
- await finishTool(model, index, request, result);
1412
+ await finishExecution(slot, request, result);
355
1413
  active();
356
1414
  }
357
1415
 
358
- async function runDelegation(
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(
359
1437
  model: CompletedModel,
360
1438
  index: number,
361
1439
  request: ToolRequest,
362
- descriptor: Delegation,
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,
363
1802
  ): Promise<void> {
364
1803
  let journal = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
365
1804
  if (!journal) {
366
- journal = { operationId: request.operationId, children: [] };
1805
+ journal = { kind: "delegation", operationId: request.operationId, children: [] };
367
1806
  snapshot.delegations.push(journal);
368
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
+ }
369
1829
  model.tools[index] = {
1830
+ interrupted: model.tools[index]?.interrupted ?? [],
1831
+ retries: model.tools[index]?.retries ?? [],
1832
+ asks: model.tools[index]?.asks,
370
1833
  id: request.operationId,
371
- attemptId: snapshot.attemptId,
1834
+ attemptId: request.attemptId,
372
1835
  status: "delegating",
373
1836
  };
374
1837
  await save();
@@ -381,10 +1844,16 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
381
1844
  });
382
1845
  return;
383
1846
  }
384
- await untilAbort(Promise.resolve(host?.beforeTool?.(immutableCopy(request))), signal);
1847
+ const requests = journalFor(snapshot, model, index, options, scope, signal);
1848
+ refuseGuardedReplay(snapshot, request.operationId);
1849
+ await beforeTool(request);
1850
+ await requests.recheck(request);
385
1851
  active();
386
1852
  emit({ type: "tool_start", request });
387
1853
  active();
1854
+ await requests.recheck(request);
1855
+ await requests.assertFresh();
1856
+ active();
388
1857
  // Coordination is pure and is the only place children can start. Lend once
389
1858
  // for this entire barrier, including ignored children and overlapping joins.
390
1859
  release();
@@ -399,7 +1868,7 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
399
1868
  scope,
400
1869
  signal,
401
1870
  active,
402
- evidence,
1871
+ requests,
403
1872
  );
404
1873
  } finally {
405
1874
  release = await scope.tree.gate.acquire(signal);
@@ -408,6 +1877,82 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
408
1877
  await finishTool(model, index, request, result);
409
1878
  }
410
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
+
411
1956
  async function handleTurn(model: CompletedModel): Promise<void> {
412
1957
  active();
413
1958
  const { message, finishReason } = model.turn;
@@ -442,58 +1987,185 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
442
1987
  return;
443
1988
  }
444
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
+
445
1995
  for (let index = 0; index < calls.length;) {
446
- if (model.tools[index]?.status === "completed") {
1996
+ if (
1997
+ model.tools[index]?.status === "completed" &&
1998
+ !(await retryTool(slotFor(model, index)))
1999
+ ) {
447
2000
  index++;
448
2001
  continue;
449
2002
  }
450
2003
  active();
451
2004
  const capacity = limits.toolCalls - usedTools();
452
- if (capacity <= 0 && model.tools[index]?.status === "pending")
2005
+ if (
2006
+ capacity <= 0 &&
2007
+ model.tools[index]?.status === "pending" &&
2008
+ !model.tools[index]?.asks?.length
2009
+ )
453
2010
  throw new Halt({ status: "limited", limit: "toolCalls" });
454
- const request = requestFor(model, index);
455
- const descriptor = delegations.get(request.call.name);
456
- if (descriptor) {
457
- await runDelegation(model, index, request, descriptor);
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
+ });
458
2023
  index++;
459
2024
  continue;
460
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);
461
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);
462
2082
  if (
463
- tool?.needsApproval &&
2083
+ (tool || descriptor || client || code) &&
464
2084
  completeArguments(request.call.arguments) &&
465
- approved?.request.operationId !== request.operationId
466
- ) {
467
- if (!host?.approvalContext)
468
- fail(
469
- "approval_host_missing",
470
- "Provide host.approvalContext to request approval for this tool.",
471
- request.operationId,
472
- );
473
- const scope = copyData(
474
- await untilAbort(Promise.resolve(host.approvalContext(immutableCopy(request))), signal),
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
+ },
475
2117
  );
476
- active();
477
- if (!isScope(scope) || scope.expiresAt <= Date.now())
478
- fail(
479
- "invalid_approval_scope",
480
- "The host must supply an actor, resource version and future approval expiry.",
481
- request.operationId,
482
- );
483
- snapshot.state = {
484
- status: "suspended",
485
- approval: { request: copyData(request), scope },
486
- path: [],
487
- };
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" };
488
2124
  return;
489
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
+ }
490
2149
 
491
- const batch = [{ index, request, tool }];
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
+ ];
492
2160
  const parallel = (request: ToolRequest, tool?: Tool) =>
493
- tool?.isConcurrencySafe === true &&
494
- !tool.needsApproval &&
495
- !tool.isTerminal &&
496
- host?.canRunConcurrently?.(immutableCopy(request)) === true;
2161
+ canParallel(
2162
+ request,
2163
+ tool,
2164
+ slotFor(
2165
+ model,
2166
+ model.tools.findIndex((entry) => entry.id === request.operationId),
2167
+ ).get(),
2168
+ );
497
2169
  const concurrent = parallel(request, tool);
498
2170
  if (concurrent) {
499
2171
  for (
@@ -501,180 +2173,534 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
501
2173
  next < calls.length && batch.length < Math.min(limits.parallelTools, capacity);
502
2174
  next++
503
2175
  ) {
504
- if (model.tools[next]?.status !== "pending") break;
505
- const nextRequest = requestFor(model, next);
2176
+ const execution = model.tools[next];
2177
+ if (execution?.status !== "pending") break;
2178
+ const nextRequest = requestFor(snapshot, model, next);
506
2179
  const nextTool = registry.get(nextRequest.call.name);
507
2180
  if (!parallel(nextRequest, nextTool)) break;
508
- batch.push({ index: next, request: nextRequest, tool: nextTool });
2181
+ batch.push({
2182
+ index: next,
2183
+ request: nextRequest,
2184
+ tool: nextTool,
2185
+ previousAttemptId: execution.previousAttemptId,
2186
+ });
509
2187
  }
510
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
+ }
511
2200
  active();
512
2201
  // Reserve the whole admitted batch before any invocation, including its tool-call budget.
513
2202
  for (const job of batch)
514
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,
515
2207
  id: job.request.operationId,
516
- attemptId: snapshot.attemptId,
2208
+ attemptId: job.request.attemptId,
517
2209
  status: "running",
518
2210
  };
519
2211
  await save();
520
2212
  const settled = await Promise.allSettled(
521
- batch.map((job) => runTool(model, job.index, job.request, job.tool, concurrent)),
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
+ }),
522
2227
  );
523
2228
  const rejected = settled.find((result) => result.status === "rejected");
524
2229
  if (rejected?.status === "rejected") throw rejected.reason;
525
- approved = undefined;
526
- index += batch.length;
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;
527
2245
  }
528
- const terminal = model.tools[0];
529
- if (
530
- output &&
531
- calls.length === 1 &&
532
- calls[0]?.name === RESULT_TOOL_NAME &&
533
- terminal?.status === "completed" &&
534
- terminal.result.ok
535
- ) {
536
- snapshot.state = { status: "completed", candidate: parseToolArgs(calls[0].arguments) };
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
+ );
537
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;
538
2297
  }
539
2298
 
540
- async function nextTurn(): Promise<CompletedModel> {
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();
541
2332
  active();
542
- if (snapshot.models.length >= limits.turns)
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))
543
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.
544
2477
  scope.tree.reserveModel();
545
2478
  const model: ModelExecution = {
546
- id: modelId(snapshot.runId, snapshot.models.length),
2479
+ id: operationId,
547
2480
  attemptId: snapshot.attemptId,
548
2481
  status: "running",
2482
+ billing: "unknown",
549
2483
  usage: { ...EMPTY_USAGE },
2484
+ interrupted: previous
2485
+ ? [
2486
+ ...previous.interrupted,
2487
+ { attemptId: previous.attemptId, usage: copyData(previous.usage) },
2488
+ ]
2489
+ : [],
550
2490
  };
551
- snapshot.models.push(model);
2491
+ record(model);
552
2492
  await save();
2493
+ if (previous) restart("model", model.id, previous.attemptId);
553
2494
  active();
2495
+ let reportedUsage = false;
2496
+ let bufferedChunks = 0;
2497
+ let bufferedBytes = 0;
2498
+ const guarded = !!guardrails?.modelOutput;
554
2499
  async function* observed(): AsyncIterable<ProviderChunk> {
555
- const stream = provider.createStream(
556
- historyOf(snapshot, instructions),
557
- copyData(tools.map((tool) => tool.definition())),
558
- {
559
- signal,
560
- sessionId: snapshot.runId,
561
- },
562
- );
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
+ });
563
2533
  for await (const chunk of stream) {
564
2534
  active();
565
2535
  if (chunk.usage) {
566
2536
  if (!isUsage(chunk.usage))
567
2537
  fail("invalid_usage", "The provider returned invalid token usage.", model.id);
568
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
+ });
569
2563
  }
570
- emit({
571
- type: "model_chunk",
572
- runId: snapshot.runId,
573
- attemptId: snapshot.attemptId,
574
- operationId: model.id,
575
- chunk,
576
- });
577
2564
  active();
578
2565
  yield chunk;
579
2566
  }
580
2567
  }
581
- const turn = readTurn(await untilAbort(collectTurn(observed()), signal));
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();
582
2613
  const done: CompletedModel = {
583
2614
  ...model,
584
2615
  status: "completed",
2616
+ billing: reportedUsage ? "reported" : "unknown",
585
2617
  usage: turn.usage,
586
2618
  turn,
587
2619
  tools: (turn.message.toolCalls ?? []).map((_call, index) => ({
588
2620
  id: toolId(model.id, index),
589
2621
  status: "pending",
2622
+ interrupted: [],
2623
+ retries: [],
590
2624
  })),
591
2625
  };
592
- snapshot.models[snapshot.models.length - 1] = done;
2626
+ record(done);
593
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
+ }
594
2638
  return done;
595
2639
  }
596
2640
 
597
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
+ }
598
2655
  if (snapshot.state.status === "running" || snapshot.state.status === "suspended") {
599
2656
  release = await scope.tree.gate.acquire(signal);
600
2657
  active();
601
- for (const model of snapshot.models) {
602
- const interrupted =
603
- model.status === "running"
604
- ? model
605
- : model.tools.find((tool) => tool.status === "running");
606
- if (interrupted)
607
- fail(
608
- "interrupted_operation",
609
- "This operation started but has no saved result. Reconcile it with the host; it will not be replayed.",
610
- interrupted.id,
611
- );
612
- }
613
- if (snapshot.state.status === "suspended" && snapshot.state.path.length > 0) {
614
- // Replay only pure coordination. Evidence follows its exact path to one leaf.
615
- snapshot.state = { status: "running" };
616
- }
617
- if (snapshot.state.status === "suspended" && evidence) {
618
- active();
619
- const approval = snapshot.state.approval;
620
- if (approval.scope.expiresAt <= Date.now())
621
- fail(
622
- "approval_expired",
623
- "The approval expired. Request a new decision before resuming.",
624
- approval.request.operationId,
625
- );
626
- if (!registry.get(approval.request.call.name)?.needsApproval)
627
- fail(
628
- "invalid_approval",
629
- "The pending approval does not belong to an approval-required tool.",
630
- );
631
- if (!host?.resolveApproval || !host.beforeTool)
632
- fail(
633
- "approval_host_missing",
634
- "Provide host.resolveApproval and host.beforeTool to authenticate a decision and recheck access.",
635
- );
636
- await save();
637
- active();
638
- const answer = await untilAbort(
639
- Promise.resolve(
640
- host.resolveApproval(immutableCopy(approval), immutableCopy(evidence.decision)),
641
- ),
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,
642
2684
  signal,
2685
+ scope.handoffInput,
643
2686
  );
2687
+ // No model sees recall until the existing progress/checkpoint barrier confirms it.
2688
+ await save();
644
2689
  active();
645
- if (answer !== "pending") {
646
- if (answer !== "approved" && answer !== "denied")
647
- fail(
648
- "invalid_approval_decision",
649
- "The host must return approved, denied or pending.",
650
- );
651
- snapshot.state = { status: "running" };
652
- if (answer === "approved") approved = approval;
653
- else {
654
- const model = snapshot.models.at(-1);
655
- if (model?.status !== "completed")
656
- fail("invalid_journal", "The pending tool turn is missing.");
657
- const index = model.tools.findIndex(
658
- (tool) => tool.id === approval.request.operationId,
659
- );
660
- if (usedTools() >= limits.toolCalls)
661
- throw new Halt({ status: "limited", limit: "toolCalls" });
662
- await finishTool(model, index, requestFor(model, index), {
663
- ok: false,
664
- kind: "denied",
665
- content: "The host denied this tool call. Continue without this action.",
666
- });
667
- }
668
- }
669
2690
  }
670
- if (snapshot.state.status === "running") {
671
- const last = snapshot.models.at(-1);
672
- if (last?.status === "completed") await handleTurn(last);
673
- while (snapshot.state.status === "running") await handleTurn(await nextTurn());
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);
674
2700
  }
2701
+ while (snapshot.state.status === "running") await handleTurn(await nextTurn());
675
2702
  }
676
- if (snapshot.state.status === "completed")
677
- completed = { output: validateResult(snapshot.state.candidate) };
2703
+ if (snapshot.state.status === "completed") completed = { output: completedOutput(snapshot) };
678
2704
  await save();
679
2705
  } catch (error) {
680
2706
  let failure = error;
@@ -703,6 +2729,7 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
703
2729
  }
704
2730
  } finally {
705
2731
  release();
2732
+ if (started) await observe({ type: "run_end", state: snapshot.state });
706
2733
  clearTimeout(timer);
707
2734
  }
708
2735
  emit({
@@ -711,42 +2738,300 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
711
2738
  attemptId: snapshot.attemptId,
712
2739
  state: snapshot.state,
713
2740
  });
714
- const record = recordOf(snapshot, instructions);
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);
715
2744
  const state = snapshot.state;
716
2745
  if (state.status === "completed") {
717
2746
  if (!completed) throw new Error("The agent completed without validating its result.");
718
2747
  return { ...record, status: "completed", output: completed.output };
719
2748
  }
720
- return { ...record, ...state };
2749
+ return state.status === "suspended"
2750
+ ? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
2751
+ : { ...record, ...state };
721
2752
  }
722
2753
 
723
- const runtime: AgentRuntime<T | string> = {
724
- execute,
725
- create(input, runId, tree) {
726
- const startedAt = Date.now();
727
- return {
728
- format: 2,
729
- agentId: id,
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,
730
2887
  version,
731
- runId,
732
- attemptId: crypto.randomUUID(),
733
- startedAt,
734
- input,
735
- limits: copyData(limits),
736
- models: [],
737
- delegations: [],
738
- state: { status: "running" },
739
- tree: tree ? copyData(tree) : { runId, startedAt, limits: copyData(treeLimits) },
740
- };
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
+ });
741
2933
  },
742
- restore(raw, tree) {
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.");
743
2990
  const snapshot = readSnapshot(
744
2991
  raw,
745
2992
  id,
746
2993
  version,
747
- limits,
2994
+ subagent ? subagentLimits(limits, subagent.spec.limits) : limits,
748
2995
  output ? RESULT_TOOL_NAME : undefined,
2996
+ codeTools,
749
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.");
750
3035
  if (
751
3036
  tree
752
3037
  ? !equalData(snapshot.tree, tree)
@@ -757,7 +3042,11 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
757
3042
  if (model.status !== "completed") continue;
758
3043
  for (const [index, tool] of model.tools.entries()) {
759
3044
  const call = model.turn.message.toolCalls?.[index];
760
- const descriptor = call && delegations.get(call.name);
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);
761
3050
  const journal = snapshot.delegations.find((entry) => entry.operationId === tool.id);
762
3051
  if (descriptor && tool.status !== "pending") {
763
3052
  if (!journal || tool.status === "running")
@@ -767,40 +3056,114 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
767
3056
  } else if (journal)
768
3057
  throw new TypeError("The saved delegation is not in this agent definition.");
769
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);
770
3063
  for (const entry of journal.children) {
771
3064
  const agent = descriptor.specialists.find(
772
3065
  (agent) =>
773
- agent.id === entry.snapshot.agentId && agent.version === entry.snapshot.version,
3066
+ agent.kind === entry.snapshot.kind &&
3067
+ agent.id === nodeId(entry.snapshot) &&
3068
+ agent.version === entry.snapshot.version,
774
3069
  );
775
3070
  if (!agent)
776
3071
  throw new TypeError("The saved child is not a registered specialist version.");
777
- entry.snapshot = agent[AGENT_RUNTIME].restore(entry.snapshot, snapshot.tree);
3072
+ entry.snapshot = runtimeOf(agent).restore(
3073
+ entry.snapshot,
3074
+ snapshot.tree,
3075
+ entry.snapshot.kind === "agent" ? entry.snapshot.subagent : undefined,
3076
+ );
778
3077
  }
779
3078
  }
780
3079
  }
781
- if (snapshot.state.status === "completed") validateResult(snapshot.state.candidate);
3080
+ if (snapshot.state.status === "completed") completedOutput(snapshot);
782
3081
  return snapshot;
783
3082
  },
784
3083
  hydrate(snapshot) {
785
- const record = recordOf(snapshot, instructions);
3084
+ const record = recordOf(snapshot);
786
3085
  const state = record.snapshot.state;
787
3086
  if (state.status === "running") throw new Error("A child has not settled yet.");
788
3087
  return state.status === "completed"
789
- ? { ...record, status: "completed", output: validateResult(state.candidate) }
790
- : { ...record, ...state };
3088
+ ? { ...record, status: "completed", output: completedOutput(record.snapshot) }
3089
+ : state.status === "suspended"
3090
+ ? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
3091
+ : { ...record, ...state };
791
3092
  },
792
3093
  };
793
3094
 
794
- async function root(snapshot: RunSnapshot, options: RunOptions, evidence?: ApprovalEvidence) {
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
+ ) {
795
3154
  const tree = new ExecutionTree(snapshot, options);
3155
+ let outcome: RunOutcome<T | string | H>;
796
3156
  try {
797
- return await execute(snapshot, options, { tree, depth: 0 }, evidence);
3157
+ outcome = await execute(snapshot, options, { tree, depth: 0, path: [] }, answers);
798
3158
  } finally {
799
3159
  tree.close();
800
3160
  }
3161
+ const session = await appendTurn(outcome, options, tree);
3162
+ return session ? { ...outcome, session } : outcome;
801
3163
  }
802
3164
 
803
- const agent: Agent<T | string> = {
3165
+ const agent: Agent<T | string | H> = {
3166
+ kind: "agent",
804
3167
  id,
805
3168
  version,
806
3169
  [AGENT_RUNTIME]: runtime,
@@ -808,26 +3171,28 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
808
3171
  return specialistTool(agent, options);
809
3172
  },
810
3173
  async run(input, options = {}) {
811
- if (!isId(input)) throw new TypeError("Give the agent a non-empty text input.");
812
3174
  checkOptions(options);
813
- return root(runtime.create(input, options.runId ?? crypto.randomUUID()), options);
3175
+ options = { ...options, memory: readMemoryBinding(options.memory) };
3176
+ return root(
3177
+ await runtime.open(input, options, options.runId ?? crypto.randomUUID()),
3178
+ options,
3179
+ );
814
3180
  },
815
3181
  async resume(raw, options) {
816
- checkOptions(options);
3182
+ checkOptions(options, "resume");
3183
+ options = { ...options, memory: readMemoryBinding(options.memory) };
817
3184
  const snapshot = runtime.restore(raw);
818
- let evidence: ApprovalEvidence | undefined;
819
- if (options.decision !== undefined || options.approvalPath !== undefined) {
820
- if (
821
- snapshot.state.status !== "suspended" ||
822
- !equalData(options.approvalPath ?? [], snapshot.state.path)
823
- )
824
- throw new TypeError("The decision path must match the exposed pending approval.");
825
- if (options.decision !== undefined)
826
- evidence = copyData({ path: snapshot.state.path, decision: options.decision });
827
- }
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 ?? {});
828
3193
  await authorizeTree(snapshot, options.host);
829
3194
  snapshot.attemptId = crypto.randomUUID();
830
- return root(snapshot, options, evidence);
3195
+ return root(snapshot, options, answers);
831
3196
  },
832
3197
  };
833
3198
  return Object.freeze(agent);