@providerkit/agents 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (296) hide show
  1. package/LICENSE +21 -0
  2. package/LICENSE-APACHE-2.0 +202 -0
  3. package/README.md +2328 -2
  4. package/THIRD_PARTY_NOTICES.md +521 -0
  5. package/dist/a2a/auth.d.ts +10 -0
  6. package/dist/a2a/auth.d.ts.map +1 -0
  7. package/dist/a2a/auth.js +52 -0
  8. package/dist/a2a/auth.js.map +1 -0
  9. package/dist/a2a/client.d.ts +74 -0
  10. package/dist/a2a/client.d.ts.map +1 -0
  11. package/dist/a2a/client.js +601 -0
  12. package/dist/a2a/client.js.map +1 -0
  13. package/dist/a2a/index.d.ts +22 -0
  14. package/dist/a2a/index.d.ts.map +1 -0
  15. package/dist/a2a/index.js +11 -0
  16. package/dist/a2a/index.js.map +1 -0
  17. package/dist/a2a/memory-runs.d.ts +62 -0
  18. package/dist/a2a/memory-runs.d.ts.map +1 -0
  19. package/dist/a2a/memory-runs.js +349 -0
  20. package/dist/a2a/memory-runs.js.map +1 -0
  21. package/dist/a2a/policy.d.ts +15 -0
  22. package/dist/a2a/policy.d.ts.map +1 -0
  23. package/dist/a2a/policy.js +114 -0
  24. package/dist/a2a/policy.js.map +1 -0
  25. package/dist/a2a/push.d.ts +34 -0
  26. package/dist/a2a/push.d.ts.map +1 -0
  27. package/dist/a2a/push.js +180 -0
  28. package/dist/a2a/push.js.map +1 -0
  29. package/dist/a2a/remote.d.ts +155 -0
  30. package/dist/a2a/remote.d.ts.map +1 -0
  31. package/dist/a2a/remote.js +1196 -0
  32. package/dist/a2a/remote.js.map +1 -0
  33. package/dist/a2a/server.d.ts +110 -0
  34. package/dist/a2a/server.d.ts.map +1 -0
  35. package/dist/a2a/server.js +1139 -0
  36. package/dist/a2a/server.js.map +1 -0
  37. package/dist/a2a/signing.d.ts +21 -0
  38. package/dist/a2a/signing.d.ts.map +1 -0
  39. package/dist/a2a/signing.js +305 -0
  40. package/dist/a2a/signing.js.map +1 -0
  41. package/dist/a2a/tasks.d.ts +88 -0
  42. package/dist/a2a/tasks.d.ts.map +1 -0
  43. package/dist/a2a/tasks.js +170 -0
  44. package/dist/a2a/tasks.js.map +1 -0
  45. package/dist/a2a/wire.d.ts +267 -0
  46. package/dist/a2a/wire.d.ts.map +1 -0
  47. package/dist/a2a/wire.js +1202 -0
  48. package/dist/a2a/wire.js.map +1 -0
  49. package/dist/background-types.d.ts +76 -0
  50. package/dist/background-types.d.ts.map +1 -0
  51. package/dist/background-types.js +2 -0
  52. package/dist/background-types.js.map +1 -0
  53. package/dist/child.d.ts +25 -0
  54. package/dist/child.d.ts.map +1 -0
  55. package/dist/child.js +129 -0
  56. package/dist/child.js.map +1 -0
  57. package/dist/code-driver.d.ts +40 -0
  58. package/dist/code-driver.d.ts.map +1 -0
  59. package/dist/code-driver.js +2 -0
  60. package/dist/code-driver.js.map +1 -0
  61. package/dist/code-mode.d.ts +3 -0
  62. package/dist/code-mode.d.ts.map +1 -0
  63. package/dist/code-mode.js +2 -0
  64. package/dist/code-mode.js.map +1 -0
  65. package/dist/code-script.d.ts +3 -0
  66. package/dist/code-script.d.ts.map +1 -0
  67. package/dist/code-script.js +149 -0
  68. package/dist/code-script.js.map +1 -0
  69. package/dist/code.d.ts +75 -0
  70. package/dist/code.d.ts.map +1 -0
  71. package/dist/code.js +326 -0
  72. package/dist/code.js.map +1 -0
  73. package/dist/compaction.d.ts +15 -0
  74. package/dist/compaction.d.ts.map +1 -0
  75. package/dist/compaction.js +168 -0
  76. package/dist/compaction.js.map +1 -0
  77. package/dist/delegation.d.ts +135 -0
  78. package/dist/delegation.d.ts.map +1 -0
  79. package/dist/delegation.js +401 -0
  80. package/dist/delegation.js.map +1 -0
  81. package/dist/evals/driver.d.ts +10 -0
  82. package/dist/evals/driver.d.ts.map +1 -0
  83. package/dist/evals/driver.js +192 -0
  84. package/dist/evals/driver.js.map +1 -0
  85. package/dist/evals/journal.d.ts +26 -0
  86. package/dist/evals/journal.d.ts.map +1 -0
  87. package/dist/evals/journal.js +483 -0
  88. package/dist/evals/journal.js.map +1 -0
  89. package/dist/evals/judge.d.ts +31 -0
  90. package/dist/evals/judge.d.ts.map +1 -0
  91. package/dist/evals/judge.js +142 -0
  92. package/dist/evals/judge.js.map +1 -0
  93. package/dist/evals/report.d.ts +38 -0
  94. package/dist/evals/report.d.ts.map +1 -0
  95. package/dist/evals/report.js +241 -0
  96. package/dist/evals/report.js.map +1 -0
  97. package/dist/evals/runner.d.ts +24 -0
  98. package/dist/evals/runner.d.ts.map +1 -0
  99. package/dist/evals/runner.js +655 -0
  100. package/dist/evals/runner.js.map +1 -0
  101. package/dist/evals/scorers.d.ts +36 -0
  102. package/dist/evals/scorers.d.ts.map +1 -0
  103. package/dist/evals/scorers.js +259 -0
  104. package/dist/evals/scorers.js.map +1 -0
  105. package/dist/evals/simulation.d.ts +7 -0
  106. package/dist/evals/simulation.d.ts.map +1 -0
  107. package/dist/evals/simulation.js +38 -0
  108. package/dist/evals/simulation.js.map +1 -0
  109. package/dist/evals/testing.d.ts +36 -0
  110. package/dist/evals/testing.d.ts.map +1 -0
  111. package/dist/evals/testing.js +87 -0
  112. package/dist/evals/testing.js.map +1 -0
  113. package/dist/evals/trajectory.d.ts +11 -0
  114. package/dist/evals/trajectory.d.ts.map +1 -0
  115. package/dist/evals/trajectory.js +180 -0
  116. package/dist/evals/trajectory.js.map +1 -0
  117. package/dist/evals/types.d.ts +431 -0
  118. package/dist/evals/types.d.ts.map +1 -0
  119. package/dist/evals/types.js +4 -0
  120. package/dist/evals/types.js.map +1 -0
  121. package/dist/evals.d.ts +14 -0
  122. package/dist/evals.d.ts.map +1 -0
  123. package/dist/evals.js +9 -0
  124. package/dist/evals.js.map +1 -0
  125. package/dist/extensions.d.ts +33 -0
  126. package/dist/extensions.d.ts.map +1 -0
  127. package/dist/extensions.js +188 -0
  128. package/dist/extensions.js.map +1 -0
  129. package/dist/handoff.d.ts +58 -0
  130. package/dist/handoff.d.ts.map +1 -0
  131. package/dist/handoff.js +160 -0
  132. package/dist/handoff.js.map +1 -0
  133. package/dist/index.d.ts +19 -0
  134. package/dist/index.d.ts.map +1 -0
  135. package/dist/index.js +11 -0
  136. package/dist/index.js.map +1 -0
  137. package/dist/input.d.ts +42 -0
  138. package/dist/input.d.ts.map +1 -0
  139. package/dist/input.js +266 -0
  140. package/dist/input.js.map +1 -0
  141. package/dist/mcp.d.ts +77 -0
  142. package/dist/mcp.d.ts.map +1 -0
  143. package/dist/mcp.js +505 -0
  144. package/dist/mcp.js.map +1 -0
  145. package/dist/memory-store.d.ts +11 -0
  146. package/dist/memory-store.d.ts.map +1 -0
  147. package/dist/memory-store.js +272 -0
  148. package/dist/memory-store.js.map +1 -0
  149. package/dist/memory.d.ts +212 -0
  150. package/dist/memory.d.ts.map +1 -0
  151. package/dist/memory.js +613 -0
  152. package/dist/memory.js.map +1 -0
  153. package/dist/otel.d.ts +74 -0
  154. package/dist/otel.d.ts.map +1 -0
  155. package/dist/otel.js +427 -0
  156. package/dist/otel.js.map +1 -0
  157. package/dist/progress.d.ts +17 -0
  158. package/dist/progress.d.ts.map +1 -0
  159. package/dist/progress.js +193 -0
  160. package/dist/progress.js.map +1 -0
  161. package/dist/quickjs.d.ts +19 -0
  162. package/dist/quickjs.d.ts.map +1 -0
  163. package/dist/quickjs.js +519 -0
  164. package/dist/quickjs.js.map +1 -0
  165. package/dist/recovery.d.ts +10 -0
  166. package/dist/recovery.d.ts.map +1 -0
  167. package/dist/recovery.js +62 -0
  168. package/dist/recovery.js.map +1 -0
  169. package/dist/request.d.ts +88 -0
  170. package/dist/request.d.ts.map +1 -0
  171. package/dist/request.js +422 -0
  172. package/dist/request.js.map +1 -0
  173. package/dist/run.d.ts +20 -0
  174. package/dist/run.d.ts.map +1 -0
  175. package/dist/run.js +2407 -0
  176. package/dist/run.js.map +1 -0
  177. package/dist/runs.d.ts +110 -0
  178. package/dist/runs.d.ts.map +1 -0
  179. package/dist/runs.js +438 -0
  180. package/dist/runs.js.map +1 -0
  181. package/dist/schema-to-ts.d.ts +4 -0
  182. package/dist/schema-to-ts.d.ts.map +1 -0
  183. package/dist/schema-to-ts.js +191 -0
  184. package/dist/schema-to-ts.js.map +1 -0
  185. package/dist/session.d.ts +23 -0
  186. package/dist/session.d.ts.map +1 -0
  187. package/dist/session.js +137 -0
  188. package/dist/session.js.map +1 -0
  189. package/dist/snapshot.d.ts +75 -0
  190. package/dist/snapshot.d.ts.map +1 -0
  191. package/dist/snapshot.js +1607 -0
  192. package/dist/snapshot.js.map +1 -0
  193. package/dist/steering.d.ts +75 -0
  194. package/dist/steering.d.ts.map +1 -0
  195. package/dist/steering.js +214 -0
  196. package/dist/steering.js.map +1 -0
  197. package/dist/subagents.d.ts +141 -0
  198. package/dist/subagents.d.ts.map +1 -0
  199. package/dist/subagents.js +746 -0
  200. package/dist/subagents.js.map +1 -0
  201. package/dist/tool-retry.d.ts +12 -0
  202. package/dist/tool-retry.d.ts.map +1 -0
  203. package/dist/tool-retry.js +53 -0
  204. package/dist/tool-retry.js.map +1 -0
  205. package/dist/tree.d.ts +98 -0
  206. package/dist/tree.d.ts.map +1 -0
  207. package/dist/tree.js +320 -0
  208. package/dist/tree.js.map +1 -0
  209. package/dist/types.d.ts +1007 -0
  210. package/dist/types.d.ts.map +1 -0
  211. package/dist/types.js +2 -0
  212. package/dist/types.js.map +1 -0
  213. package/dist/workflow-snapshot.d.ts +8 -0
  214. package/dist/workflow-snapshot.d.ts.map +1 -0
  215. package/dist/workflow-snapshot.js +276 -0
  216. package/dist/workflow-snapshot.js.map +1 -0
  217. package/dist/workflow-types.d.ts +171 -0
  218. package/dist/workflow-types.d.ts.map +1 -0
  219. package/dist/workflow-types.js +2 -0
  220. package/dist/workflow-types.js.map +1 -0
  221. package/dist/workflow.d.ts +19 -0
  222. package/dist/workflow.d.ts.map +1 -0
  223. package/dist/workflow.js +1053 -0
  224. package/dist/workflow.js.map +1 -0
  225. package/examples/a2a-remote.ts +85 -0
  226. package/examples/a2a-server.ts +100 -0
  227. package/examples/background.ts +59 -0
  228. package/examples/basic.ts +44 -0
  229. package/examples/code-mode.ts +76 -0
  230. package/examples/conversation.ts +57 -0
  231. package/examples/evals.ts +79 -0
  232. package/examples/guardrails.ts +56 -0
  233. package/examples/handoff.ts +79 -0
  234. package/examples/memory.ts +44 -0
  235. package/examples/otel.ts +99 -0
  236. package/examples/specialists.ts +99 -0
  237. package/examples/steering.ts +69 -0
  238. package/examples/structured-handoff.ts +92 -0
  239. package/examples/subagents.ts +127 -0
  240. package/examples/workflow.ts +74 -0
  241. package/package.json +114 -4
  242. package/src/a2a/auth.ts +62 -0
  243. package/src/a2a/client.ts +733 -0
  244. package/src/a2a/index.ts +74 -0
  245. package/src/a2a/memory-runs.ts +448 -0
  246. package/src/a2a/policy.ts +148 -0
  247. package/src/a2a/push.ts +251 -0
  248. package/src/a2a/remote.ts +1652 -0
  249. package/src/a2a/server.ts +1390 -0
  250. package/src/a2a/signing.ts +348 -0
  251. package/src/a2a/tasks.ts +260 -0
  252. package/src/a2a/wire.ts +1443 -0
  253. package/src/background-types.ts +86 -0
  254. package/src/child.ts +181 -0
  255. package/src/code-driver.ts +48 -0
  256. package/src/code-mode.ts +12 -0
  257. package/src/code-script.ts +149 -0
  258. package/src/code.ts +424 -0
  259. package/src/compaction.ts +212 -0
  260. package/src/delegation.ts +694 -0
  261. package/src/evals/driver.ts +222 -0
  262. package/src/evals/journal.ts +605 -0
  263. package/src/evals/judge.ts +188 -0
  264. package/src/evals/report.ts +295 -0
  265. package/src/evals/runner.ts +826 -0
  266. package/src/evals/scorers.ts +339 -0
  267. package/src/evals/simulation.ts +46 -0
  268. package/src/evals/testing.ts +126 -0
  269. package/src/evals/trajectory.ts +223 -0
  270. package/src/evals/types.ts +463 -0
  271. package/src/evals.ts +72 -0
  272. package/src/extensions.ts +247 -0
  273. package/src/handoff.ts +214 -0
  274. package/src/index.ts +62 -0
  275. package/src/input.ts +319 -0
  276. package/src/mcp.ts +690 -0
  277. package/src/memory-store.ts +366 -0
  278. package/src/memory.ts +893 -0
  279. package/src/otel.ts +568 -0
  280. package/src/progress.ts +214 -0
  281. package/src/quickjs.ts +524 -0
  282. package/src/recovery.ts +90 -0
  283. package/src/request.ts +513 -0
  284. package/src/run.ts +3199 -0
  285. package/src/runs.ts +696 -0
  286. package/src/schema-to-ts.ts +194 -0
  287. package/src/session.ts +178 -0
  288. package/src/snapshot.ts +2099 -0
  289. package/src/steering.ts +329 -0
  290. package/src/subagents.ts +1084 -0
  291. package/src/tool-retry.ts +86 -0
  292. package/src/tree.ts +366 -0
  293. package/src/types.ts +944 -0
  294. package/src/workflow-snapshot.ts +366 -0
  295. package/src/workflow-types.ts +213 -0
  296. package/src/workflow.ts +1316 -0
package/README.md CHANGED
@@ -1,3 +1,2329 @@
1
- # Temporary Holding Version
1
+ # @providerkit/agents
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An agent calls a model, runs the tools it requests and returns an answer.
4
+ Keep its instructions, provider and tools in one place:
5
+
6
+ ```ts
7
+ const result = await writer.run("Explain why a database index speeds up a search.");
8
+ ```
9
+
10
+ A completed result has `status: "completed"` and an `output` value. Other results say whether the
11
+ run failed, was cancelled, reached a limit or is waiting for input. Check the status before
12
+ using the output.
13
+
14
+ The API may change before 1.0. This package uses `@providerkit/core` for model calls. Its main
15
+ entry has no database, queue or vendor SDK dependency and sends no traces to an external service.
16
+
17
+ ## Set up an agent
18
+
19
+ Install the agent package and core:
20
+
21
+ ```sh
22
+ bun add @providerkit/agents @providerkit/core
23
+ ```
24
+
25
+ Pass a provider you already configured with core:
26
+
27
+ ```ts
28
+ import { defineAgent } from "@providerkit/agents";
29
+ import type { Provider } from "@providerkit/core";
30
+
31
+ export function createWriter(provider: Provider) {
32
+ return defineAgent({
33
+ id: "writer",
34
+ version: "1",
35
+ instructions: "Explain technical topics in short sentences.",
36
+ provider,
37
+ });
38
+ }
39
+ ```
40
+
41
+ Set up routing, fallback models, provider deadlines and retry policy in core. The agent uses that
42
+ provider as supplied; it does not retry a failed live call. Opt-in crash recovery is separate,
43
+ as described under checkpoints and recovery.
44
+
45
+ Change the agent's version when its instructions, tools or result contract change. A saved run
46
+ from another version is refused rather than resumed under different rules.
47
+
48
+ ## Model settings
49
+
50
+ Give the agent an output ceiling, especially on services that reserve the whole context window
51
+ when no ceiling is set:
52
+
53
+ ```ts
54
+ const writer = defineAgent({
55
+ id: "writer",
56
+ version: "1",
57
+ instructions: "Explain technical topics in short sentences.",
58
+ provider,
59
+ modelSettings: { maxTokens: 2_048 },
60
+ });
61
+ ```
62
+
63
+ Override settings for one run:
64
+
65
+ ```ts
66
+ await writer.run("Explain database indexes.", { modelSettings: { maxTokens: 512 } });
67
+ ```
68
+
69
+ `ModelSettings` is core's `StreamOptions` without `signal`, `sessionId` or `json`. The SDK owns
70
+ those three: use `RunOptions.signal` to stop, and `output` for checked results. Provider defaults
71
+ apply first, agent settings override them, and run settings win last. Unset or `undefined` fields
72
+ inherit; `0` and `false` do not. All settings go to every model call. Support still depends on the
73
+ provider, which may refuse a setting.
74
+
75
+ The resolved settings are saved in `snapshot.definition.modelSettings`. Resume cannot change
76
+ them. The two observers, `onActivity` and `onRateLimit`, are functions, so they stay in memory
77
+ rather than in JSON. After a restart, only observers from the rebuilt agent apply; reattach
78
+ progress through `onEvent`.
79
+
80
+ `toolChoice` accepts `"auto"`, `"none"`, `"required"` or `{ name: "lookup" }`. A named tool must
81
+ be enabled. After a tool call, a forced choice becomes `"auto"` for the rest of that run,
82
+ including after resume. `"none"` stays `"none"`: calls a provider returns anyway are refused.
83
+ A checked-output agent refuses `"none"` at creation because it needs `submit_result` to finish.
84
+
85
+ ## Instructions and tools per run
86
+
87
+ Build instructions from trusted host context:
88
+
89
+ ```ts
90
+ const writer = defineAgent({
91
+ id: "writer",
92
+ version: "1",
93
+ instructions: (run) => `Reply in ${run.context.locale ?? "en"}.`,
94
+ provider,
95
+ });
96
+ await writer.run("Explain database indexes.", { context: { locale: "es" } });
97
+ ```
98
+
99
+ The callback receives a `RunContext`: the agent id and version, run id, prepared history, new
100
+ input, host `context` and cancellation `signal`. History and input are frozen copies. Host
101
+ services in `context`, such as a database handle, stay in memory and are not saved.
102
+
103
+ `enabledTools` takes registered tool names or a function that returns them:
104
+
105
+ ```ts
106
+ const reader = defineAgent({
107
+ id: "reader",
108
+ version: "1",
109
+ instructions: "Read the records you need, then answer.",
110
+ provider,
111
+ tools: [lookup, update],
112
+ enabledTools: (run) => (run.context.canWrite ? ["lookup", "update"] : ["lookup"]),
113
+ });
114
+ await reader.run("Find this record.", { enabledTools: ["lookup"] });
115
+ ```
116
+
117
+ An empty list disables ordinary tools. The reserved `submit_result` stays enabled when there
118
+ is an output contract. A run may narrow the agent's list, never enable a tool its policy disabled.
119
+ Tools keep their definition order, which is part of the provider's cached prompt. Disabled tools
120
+ are hidden from the model and refused if it calls them anyway, before approval or invocation.
121
+ `beforeTool` must still check current access: a saved allow-list is not authorization.
122
+
123
+ Instructions and tool selection resolve once, after history preparation and before the first
124
+ checkpoint. They are saved in `snapshot.definition`, alongside the model settings and stopping
125
+ tools. A resumed run uses that record, even if host context changed. It never calls these
126
+ functions again. If a function throws, creation throws before any model call or checkpoint.
127
+ Keep paid work and effects out of these callbacks: a process that dies before the first save
128
+ can call them again.
129
+
130
+ A specialist resolves its own definition using the shared host context, but never inherits its
131
+ parent's run-level model settings or tool selection. Reusing a saved child never resolves it
132
+ again.
133
+
134
+ ## Results and progress
135
+
136
+ ```ts
137
+ const result = await writer.run("Explain database indexes.", {
138
+ signal: controller.signal,
139
+ onEvent(event) {
140
+ if (event.type === "model_chunk") {
141
+ render(event.chunk.content ?? "");
142
+ }
143
+ },
144
+ });
145
+
146
+ if (result.status === "completed") {
147
+ console.log(result.output);
148
+ }
149
+ ```
150
+
151
+ The same reader collects the answer and reports progress. An observer failure does not stop the
152
+ work. Tool results and provider metadata stay in the recorded history.
153
+
154
+ When an agent hands work to a specialist (see below), a `child` event arrives before that
155
+ specialist's own events. It holds the parent's run ID as `parentRunId`, the delegation's
156
+ `operationId`, the child `key`, the specialist's `runId`, and its `agentId` and `version`. Use it
157
+ to show a specialist's work under the agent that called it. It carries no status: read that from
158
+ the specialist's `state` events or from the snapshot. Like any progress event, it can be missed.
159
+ A specialist that resumes after an approval or an interruption sends it again with the same
160
+ values, so update the entry you keep for that `runId` and do not add another. A specialist that
161
+ already finished is reused and sends nothing.
162
+
163
+ | Status | Meaning |
164
+ | ----------- | -------------------------------------------------------------------------- |
165
+ | `completed` | The answer passed the configured result validator. |
166
+ | `suspended` | An approval, question or client tool needs a reply. |
167
+ | `cancelled` | The caller stopped the run. Cancellation does not undo an external action. |
168
+ | `limited` | A turn, tool-call, time or provider output limit stopped the run. |
169
+ | `failed` | Execution could not continue. Read `error.code` and `error.message`. |
170
+
171
+ Reasoning without an answer is not success. A provider's length-limited answer is not accepted as
172
+ a complete result. Increase the provider's output allowance when appropriate rather than blindly
173
+ repeating a paid request.
174
+
175
+ ## Lifecycle hooks and guards
176
+
177
+ Use a guard to refuse work or output. Use a hook to observe it. A hook is not permission.
178
+
179
+ ```ts
180
+ const reader = defineAgent({
181
+ id: "reader",
182
+ version: "1",
183
+ instructions: "Read the records and answer.",
184
+ provider,
185
+ tools: [lookup],
186
+ guardrails: {
187
+ identity: "reader-policy-1",
188
+ modelInput: ({ messages }) => ({ allow: messages.length <= 100 }),
189
+ modelOutput: (turn) => ({ allow: !turn.message.content.includes("private") }),
190
+ toolOutput: ({ result }) => ({ allow: result.ok }),
191
+ },
192
+ });
193
+ ```
194
+
195
+ These checks are examples, not a privacy policy. Supply your own checks for your data. Each
196
+ callback returns `{ allow: true }` or `{ allow: false }`. Guards never rewrite arguments, replace
197
+ results or approve requests. A rejection ends the run with `guard_rejected`; a thrown exception
198
+ or malformed verdict ends it with `guard_failed`. The SDK saves no exception text from a guard
199
+ and does not ask the model to retry that operation.
200
+
201
+ | Guard | Checked value | Boundary |
202
+ | ------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
203
+ | `modelInput` | `{ messages, tools, settings }` | Every model attempt, after new inbox input and media loading, before the provider call. |
204
+ | `modelOutput` | Core `Turn`, including reasoning, tool arguments and hosted results | After collection, before progress, recorded model history or local tool dispatch. |
205
+ | `toolInput` | `ToolRequest` with the effective, approved `arguments` | Before ordinary tools, delegation, handoff or a client request. Core validation and host authorization still follow. |
206
+ | `toolOutput` | `{ request, result }` with the SDK `ToolResult` | Before a settled result enters history, progress or terminal state. Includes failed and denied results. |
207
+
208
+ `modelOutput` checks every turn, not just the final answer. It also checks the arguments of
209
+ `submit_result`. `toolOutput` checks tool-produced content and a stopping tool's recorded
210
+ `final.candidate`. It does not recall the model's earlier words or arguments. Use both when
211
+ both model and tool output need checks. Result validators still run; a validator's transformed
212
+ application object remains the host's responsibility, not a new model response.
213
+
214
+ With `modelOutput`, no model chunk is published until the verdict passes and its completed
215
+ receipt is saved. It then publishes one `model_chunk` containing that checked turn, not the raw
216
+ chunks: earlier metadata replaced during collection was not part of the verdict. The SDK collects
217
+ at most 4,096 chunks and 1,000,000 UTF-8 JSON bytes per model
218
+ attempt. Reasoning, tool arguments and provider metadata count too. Set `maxOutputBytes` to a
219
+ positive whole number to change the byte bound. With `toolOutput`, the same byte bound applies
220
+ to one normalized result. Exceeding either bound ends with `guard_output_limit`, without a
221
+ retry or partial disclosure. Usage reports still checkpoint while output is withheld. This
222
+ bounds retained SDK output, not allocations inside a provider or callback.
223
+
224
+ `toolOutput` also withholds raw `decision` progress events, which can contain an unchecked
225
+ client result or answer. The private request journal still records decisions before work.
226
+ Read that journal for decision status; use the later checked `tool_result` for output. Requests
227
+ and question prompts are a separate host-controlled surface: `prepareRequest` and your display
228
+ projector must check what they expose. No guard makes raw snapshots safe for a browser.
229
+
230
+ Guards are local to one agent. Set them on every specialist and handoff target whose output
231
+ needs protection. A parent's tool guard does not intercept a child's own progress. Hosted
232
+ provider tools may already have acted before a model output guard runs; use the input guard
233
+ and provider configuration to prevent their dispatch. Tools with guards run serially within
234
+ that agent, so a rejected result cannot start the next tool in its batch. Other already-running
235
+ children and external effects cannot be recalled.
236
+
237
+ Guard identity, configured stages and bounds live in `snapshot.definition.guardrails`.
238
+ `snapshot.guards` records operation/attempt ids, input hashes and verdicts. Change `identity`
239
+ when policy code changes. Resume refuses a changed policy or missing verdicts. A completed
240
+ receipt reuses its verdict. A guard interrupted before saving a verdict fails closed, even if
241
+ the callback would be safe to rerun. If a call returned but its guarded receipt was not saved,
242
+ resume refuses to repeat it with `guarded_output_unsettled`. Reconcile it on the host. An
243
+ interrupted inference-only stream can still use the existing recovery policy if no output
244
+ check started; the replacement attempt gets its own guards.
245
+
246
+ ### Observe execution
247
+
248
+ Set `onLifecycle(event, context)` on the agent or in `RunOptions`. At each boundary, the agent
249
+ hook runs first, then the run hook. Run hooks reach descendants too; completed cached children
250
+ and completed resumed runs do not re-emit lifecycle hooks.
251
+
252
+ The event types are `run_start`, `run_end`, `model_start`, `model_end`, `model_error`,
253
+ `tool_start`, `tool_end` and `tool_error`. For each live model call the order is input guard,
254
+ start hook, dispatch, end hook, output guard, checkpoint, then progress. A tool follows the
255
+ same order, with the host's `beforeTool` and request freshness checks after its start hook.
256
+ A tool end hook also sees settled refusals that never dispatched. `model_error` reports a stream
257
+ failure; `tool_error` reports an error escaping the tool phase, including guard failure. An output
258
+ guard can fail after an end hook. `run_end`
259
+ receives the attempt's final state, including suspension or failure. A tool that pauses with
260
+ `InputRequired` has no settled result yet, so its start hook has no matching end hook on that
261
+ attempt. Use `run_end` to close any unfinished observation; resuming starts a new attempt.
262
+
263
+ Hooks are awaited to preserve order, but their return values and exceptions are ignored.
264
+ They cannot change frozen callback data or waive host checks. End hooks see **unchecked raw
265
+ output** for privileged server inspection. Do not forward them to a browser or log their
266
+ payloads without a policy. `onEvent` remains the non-awaited progress observer, not a hook.
267
+
268
+ All new callbacks receive a frozen `LifecycleContext`: `agentId`, `version`, `runId`,
269
+ `attemptId`, host `context` and `signal`. Cancellation stops waiting and prevents later SDK
270
+ work. Hooks are skipped when that signal is already aborted, including end hooks. It cannot
271
+ stop callback code that ignores the signal, undo an external effect or count hidden calls
272
+ inside a callback against tree budgets. Keep guards free of effects; hooks are not exactly-once
273
+ notifications and can repeat after a crash. For background runs, configure hooks on the agent;
274
+ `policy.context` supplies worker-only host services. No callbacks are serialized.
275
+
276
+ See [the offline guard example](examples/guardrails.ts). It makes no network calls.
277
+
278
+ ## Trace a run
279
+
280
+ Add OpenTelemetry tracing to your existing run options:
281
+
282
+ ```ts
283
+ const options = tracing.options(runOptions);
284
+ ```
285
+
286
+ This keeps your current options, including authorization hooks, and adds tracing callbacks.
287
+ Import the adapter only where you use it:
288
+
289
+ ```ts
290
+ import { createAgentTracing } from "@providerkit/agents/otel";
291
+
292
+ const tracing = createAgentTracing();
293
+ try {
294
+ await agent.run("Summarize the changes.", tracing.options());
295
+ } finally {
296
+ tracing.close();
297
+ }
298
+ ```
299
+
300
+ Install the optional `@opentelemetry/api` peer. Your app must register its tracer and exporter,
301
+ which sends trace records to your chosen service. The package installs neither and makes no
302
+ telemetry request by itself. You can pass an existing `tracer` and `parentContext` instead.
303
+ Normal SDK imports do not load this adapter.
304
+
305
+ A span is a timed record of an operation. Agents records runs, tool calls and workflow steps.
306
+ Core records the provider stream and its reported usage. The SDK's internal model-operation span
307
+ only connects SDK identities to the Core span; it does not duplicate provider usage. Missing or
308
+ partial usage is not a zero charge, and traces are not audited bills. A resumed run starts a new
309
+ span; time between attempts is not included.
310
+
311
+ `tracing.options(existingOptions)` composes existing observers and provider instrumentation.
312
+ For manual wiring, attach `onLifecycle`, `onEvent` and `bindModelProvider` once. Apply the provider
313
+ binding last, outside other provider decorators. A directly wrapped Core provider can be rebound;
314
+ a tracing wrapper hidden inside another decorator cannot be deduplicated.
315
+
316
+ ### Context and privacy
317
+
318
+ Explicit parent contexts work without installing a context manager. Core activates context
319
+ around provider iterator calls. Tool and workflow-step hooks only observe execution: they do
320
+ not activate async context for HTTP calls inside your code. Use your app's instrumentation and
321
+ context manager for those child spans.
322
+
323
+ Prompts, results and raw errors are not captured. Code, tool inputs and remote payloads stay
324
+ private too. Node, run and operation IDs are recorded, so do not use secrets or personal text as
325
+ IDs. `AgentSpanInfo` distinguishes `nodeKind` and `nodeId` for agents, workflows and remote nodes.
326
+ The optional `attributes(info)` callback accepts host-approved scalar values under
327
+ `providerkit.host.*`: at most 32 attributes, 64-character keys and 256-character strings.
328
+
329
+ Remote spans cover local observation, not the peer's full task lifetime. The last remote state
330
+ is separate from the local run state, and billing stays unknown. Explicit `remote.cancel()` has
331
+ no separate SDK operation span; its receipt still records the request. Host HTTP instrumentation
332
+ may observe that call. A status update is not proof that a send or cancellation happened.
333
+
334
+ ### End an observation
335
+
336
+ `close()` stops Agents observations, not execution. It does not cancel work, replay a request or
337
+ flush an exporter. Core streams already bound by the adapter remain observed until they end or
338
+ the caller aborts. If a stream is abandoned without ending or being aborted, this adapter cannot
339
+ close its Core span.
340
+
341
+ Defaults are 128 run observations, 1,024 operation/relationship records per run and a 30-minute
342
+ observation lifetime. `maxRuns`, `maxSpansPerRun` and `maxRunMs` change those bounds. Reaching a
343
+ bound ends or skips observations only; it never changes execution permissions or limits.
344
+
345
+ ## Conversations
346
+
347
+ Pass the thread's messages. The last one is the new user turn:
348
+
349
+ ```ts
350
+ const result = await writer.run({
351
+ messages: [
352
+ { role: "user", content: "Explain database indexes." },
353
+ { role: "assistant", content: "An index is a sorted copy of one column." },
354
+ { role: "user", content: "When does an index slow things down?" },
355
+ ],
356
+ });
357
+ ```
358
+
359
+ The agent's `instructions` are its system prompt, so a conversation never carries a system
360
+ message: one is refused. So is an empty list, or one whose last message is not a user turn. A tool
361
+ call in the history never runs. The run answers it as interrupted and runs only the calls the
362
+ model makes now.
363
+
364
+ `result.history` holds the earlier messages, the new turn and every settled round, without the
365
+ system prompt. Send it back next time with the next turn added. `result.newMessages` holds only
366
+ what this run added. Invalid input throws a `TypeError` before anything is saved or loaded.
367
+
368
+ A browser can forge the history it sends. The run keeps only the fields a model reads: it drops
369
+ `reasoningDetails`, `reasoningItems` and each call's `thoughtSignature`, which belong to the
370
+ provider, and it refuses a tool result that answers no call. The model still reads every word
371
+ of that history, so `beforeTool` must check each action, as it already does.
372
+
373
+ ### Images and files
374
+
375
+ A user turn can be a list of parts:
376
+
377
+ ```ts
378
+ await writer.run([
379
+ { type: "text", text: "What does this chart show?" },
380
+ { type: "image", mimeType: "image/png", data: chartBase64 },
381
+ ]);
382
+ ```
383
+
384
+ An image must be JPEG, PNG, WebP or GIF. A file part (`type: "file"`) takes an `application/`,
385
+ `audio/`, `video/` or `text/` type. Core sends files only to Gemini; the other adapters refuse
386
+ them, and the run fails. Bytes are padded base64 text. A blank text part beside an attachment is
387
+ dropped.
388
+
389
+ A run accepts 5 MB of inline images and files across its history and new turn
390
+ (`limits.inlineBytes`). The snapshot keeps them, and every checkpoint writes the whole snapshot
391
+ again, so larger files belong behind a reference.
392
+
393
+ ### Media references
394
+
395
+ Keep the bytes on your server and send a reference:
396
+
397
+ ```ts
398
+ await writer.run(
399
+ [
400
+ { type: "text", text: "Summarize this report." },
401
+ { type: "media", id: "upload-81", mimeType: "application/pdf" },
402
+ ],
403
+ { host: { loadMedia: (ref, run) => readUpload(ref.id, run.signal) } },
404
+ );
405
+ ```
406
+
407
+ The run stores only the id. Right before a model call it asks `host.loadMedia` for the bytes as
408
+ base64, once per id per attempt. The bytes go into the provider request and nowhere else: not the
409
+ snapshot, the outcome, the session or an event. With no loader, or one that fails, the run fails
410
+ with `media_unavailable` before the model call starts.
411
+
412
+ `loadMedia` must check that the run's owner may read that id. The bytes behind an id must never
413
+ change: one earlier byte that changes makes the provider bill its whole prompt cache again. Set
414
+ `limits.inlineBytes: 0` to accept references only.
415
+
416
+ ### Sessions
417
+
418
+ A session keeps the conversation on your server, so each request sends only the new turn:
419
+
420
+ ```ts
421
+ import { createMemorySession } from "@providerkit/agents";
422
+
423
+ const thread = createMemorySession();
424
+ await writer.run("Explain database indexes.", { session: thread });
425
+ const next = await writer.run("When do they slow down writes?", { session: thread });
426
+ ```
427
+
428
+ The run loads the history once, before it saves anything, and freezes it in the snapshot. When
429
+ the run ends (completed, failed, cancelled or limited) and its last checkpoint is saved, it
430
+ appends the new turn and its settled rounds once, keyed by its run ID. A run waiting for approval
431
+ appends when it finishes. A run the person stops still saves the turn they sent. The background
432
+ binding is the exception: cancelling a background run stops all of its writes, the session's
433
+ included.
434
+
435
+ `historyLimit` loads only the newest messages. A window that starts inside a tool round is
436
+ repaired before it is sent. `prepareHistory` runs once on the history, before the run is saved,
437
+ to trim or summarize it. It runs before the first checkpoint, so a paid summary can run again if
438
+ the process dies before that save.
439
+
440
+ `next.session` says what happened to the turn:
441
+
442
+ | Status | Meaning |
443
+ | --------- | -------------------------------------------------------------------------------------- |
444
+ | `saved` | The session has it, at `revision`. |
445
+ | `pending` | Not appended yet: the run waits, its last checkpoint failed, or no session was passed. |
446
+ | `unsaved` | The append failed. Read `error.code` and `error.message`. |
447
+
448
+ `session_conflict` means another turn landed after this run loaded the history, say from a
449
+ second tab while this run waited for approval. Load the conversation again before you continue
450
+ it. An append that fails never changes the run's own status.
451
+
452
+ Resume never loads a session again. Pass the run's own session to `resume` so the turn is
453
+ appended when the run settles; another session is refused. A specialist never gets its parent's
454
+ session.
455
+
456
+ `createMemorySession` keeps everything in this process and loses it when the process ends. For
457
+ your own store, implement `Session` (`load` and `append`) and check it with
458
+ `await checkSession(() => createTestSession())`. It writes to fresh sessions, so point it at a
459
+ test database.
460
+
461
+ ### Trim context while a run works
462
+
463
+ Configure `compaction` to shorten only what the next model call reads:
464
+
465
+ ```ts
466
+ const reader = defineAgent({
467
+ id: "reader",
468
+ version: "1",
469
+ instructions: "Read the records and answer.",
470
+ provider,
471
+ compaction: { identity: "reader-context-1", contextWindow: 128_000 },
472
+ });
473
+ ```
474
+
475
+ Supply the actual context window for this provider and model. The SDK does not guess it from a
476
+ model name. Core's `needsCompaction` decides when to trim, using the last reported input usage
477
+ plus an estimate of new messages. Before any usage report, it estimates text. Images and files
478
+ have provider-specific costs that this estimate cannot count. Core's `pickCut` keeps recent
479
+ messages without splitting tool calls from results. `keepTokens` overrides core's default tail
480
+ budget, `historyBudgetTokens(contextWindow)`. The newest message and unread inbox messages stay
481
+ verbatim even when they exceed that budget. Trimming cannot guarantee that a request fits.
482
+
483
+ Without `summarize`, trimming costs no extra call. It inserts a note saying that earlier messages
484
+ were omitted. The system prompt stays unchanged. `snapshot.history`, model/tool journals,
485
+ `result.history`, `newMessages` and the session append keep the full conversation. Input positions
486
+ and accepted/consumed receipts do not move. A delegated child or handoff still receives its normal
487
+ history policy, not the shortened model view.
488
+
489
+ For a paid summary, explicitly add `compaction.summarize` with `provider`, `instructions` and a
490
+ positive `maxTokens`. That provider must perform inference only. The SDK sends the removed
491
+ messages with those instructions, no tools, `hostedTools: []`, `toolChoice: "none"` and
492
+ `maxAttempts: 1`. Configure wrappers to honor that limit; hidden provider retries remain outside
493
+ the SDK's control. The same model guards, lifecycle hooks, usage checkpoints, shared model-call
494
+ budget and deadlines apply. Summary text never streams as the agent's answer. Its model receipt
495
+ has `purpose: "compaction"`; its usage counts in `usage` and `treeUsage`.
496
+
497
+ `snapshot.compactions` saves the cut and summary before the next model call. Resume reuses them,
498
+ including when recovering that model call. A summary left running fails with
499
+ `interrupted_compaction`, even under inference recovery: it may already have been billed. There
500
+ is no automatic second summary or fallback to untrimmed history. Reconcile the saved operation
501
+ on the host. A rejected or incomplete summary stops the run without dispatching tools. As with
502
+ other journals, persistence requires `host.checkpoint`; without it the record lives in memory.
503
+
504
+ Change `compaction.identity` when the prompt or hidden provider configuration changes. Resume
505
+ refuses a different recorded policy or summary provider identity. Unlike `prepareHistory`, this
506
+ feature runs inside the journal and never rewrites the session's stored transcript.
507
+
508
+ ### Send messages while a run works
509
+
510
+ Add a correction or more context without interrupting the current call:
511
+
512
+ ```ts
513
+ inbox.enqueue({ id: "correction-1", content: "Use short sentences." });
514
+ ```
515
+
516
+ For a process-local run, create its inbox before starting:
517
+
518
+ ```ts
519
+ import { createMemoryInbox } from "@providerkit/agents";
520
+
521
+ const runId = crypto.randomUUID();
522
+ const inbox = createMemoryInbox(runId);
523
+ const work = writer.run("Explain database indexes.", { runId, host: { inbox } });
524
+
525
+ inbox.enqueue({ id: "correction-1", content: "Use short sentences." });
526
+ const result = await work;
527
+ const deliveries = inbox.list();
528
+ ```
529
+
530
+ The host must authenticate the person sending the message. `createMemoryInbox` does not check
531
+ access and loses everything when the process ends. It is a reference helper, not a background
532
+ queue. Keep it on the server; never put the agent or a provider key in the browser.
533
+
534
+ New input joins before the next model call, after the previous model and all its tools finish.
535
+ It cannot replace history, instructions, tools, permissions or the conversation owner. It uses
536
+ the same text and media validation as a new user turn. Inline attachments count toward the
537
+ agent's existing `inlineBytes` limit; media references still use `host.loadMedia`.
538
+
539
+ The root receives these messages until a handoff admits its target. Then that target receives
540
+ them. Delegated specialists, including their own handoff targets, never poll the root's inbox.
541
+ The callback gets explicit root and owner identities; it does not parse ids to find an owner.
542
+
543
+ An executing model or tool keeps working with its original input. The SDK does not cancel or
544
+ replay it to insert a correction. A waiting approval, question or client tool still needs its
545
+ explicit request-keyed answer. Writing "approve", "deny" or "stop" in a message does none of
546
+ those things. Waiting does not extend the run's original time or call budgets.
547
+
548
+ Delivery has three states:
549
+
550
+ | State | Meaning |
551
+ | ---------- | ------------------------------------------------------------------------------------------------------ |
552
+ | `queued` | The host has it. The run has not saved it yet. |
553
+ | `accepted` | The run saved the content and its position before a model call. Consumption is not confirmed. |
554
+ | `consumed` | A model call containing the message completed and was saved. This does not mean the model followed it. |
555
+
556
+ A running or interrupted call may already have read an accepted message and incurred a charge.
557
+ The SDK cannot prove that until it saves the completed call. `result.inputs` contains delivery
558
+ receipts for recorded inputs, with their root run, receiving run, model position and completed
559
+ attempt when known. Best-effort `input` events report the same receipts without content. Missed
560
+ events do not change the journal. Without `host.checkpoint`, these states describe only the
561
+ in-memory journal, not durable storage. `snapshot.inputs` holds the private content and its position
562
+ on each receiving node. `history` and `newMessages` include it in order, without splitting tool
563
+ calls from results. Session append keeps its original run id and revision, including on resume
564
+ and through handoffs, so a message is not appended twice.
565
+
566
+ A final answer can win the race with enqueue. Messages arriving after the last poll stay
567
+ `queued`; accepted messages whose call never completed stay unconfirmed. Keep both kinds for
568
+ explicit recall or a new run. Do not display them as read, discard them on completion or start
569
+ another paid run automatically. After the run settles, `inbox.list()` lets the host offer their
570
+ content back to the person. Reconcile any interrupted call before sending it again. An accepted
571
+ message may already be in the session: use the saved history rather than appending that same
572
+ message a second time.
573
+
574
+ ### Implement a durable inbox
575
+
576
+ Supply `AgentHost.inbox`, an `InputInbox`, from trusted server code:
577
+
578
+ - `poll({ rootRunId, runId, agent, limit, signal })` returns a non-destructive, oldest-first
579
+ prefix of `{ id, content }` records. Return promptly, without waiting for new messages. Respect
580
+ the requested count and UTF-8 JSON byte limit. Keep offered records available and immutable
581
+ until acknowledgement. Never silently truncate or rewrite a message to make it fit.
582
+ - `acknowledge(receipts, { signal })` records delivery idempotently. Repeating a receipt succeeds
583
+ without another effect. An accepted receipt can become consumed, never the reverse. A known id
584
+ with a different receiving run or model position is a conflict. Keep unconsumed content.
585
+
586
+ Persist an input before acknowledging enqueue to the app. The id is stable within its logical
587
+ root run, at most 256 characters. Use opaque ids, not message text; progress events include them.
588
+ Repeating the same normalized content returns its existing
589
+ status; changed content under that id must fail. Use a new id for a new message. The memory
590
+ helper throws `InputConflictError` for these conflicts.
591
+
592
+ The SDK checkpoints accepted content and its model position **before** acknowledging delivery,
593
+ then starts the model call. A crash before that save leaves it queued. A crash after save but
594
+ before acknowledgement repeats the acknowledgement from the journal. Resume uses the saved
595
+ content, not a new value from the inbox. Consumed acknowledgement follows the completed model
596
+ checkpoint. Host poll or acknowledgement errors stop execution, without an automatic resend.
597
+ Reconcile the inbox with authoritative saved state before recalling messages after such an error.
598
+
599
+ `INPUT_LIMITS` bounds a logical run and its handoff chain: 32 pending messages per poll, 128
600
+ accepted messages in total and 5,000,000 UTF-8 JSON bytes across normalized `{ id, content }`
601
+ records. Hosts must also bound pending storage at enqueue. The memory helper enforces those
602
+ ceilings and retains all entries, including consumed ones, for deduplication. When the run has
603
+ no remaining input budget, further messages stay with the host. Large attachments belong behind
604
+ media references. These bounds do not grant extra model turns.
605
+
606
+ For `createBackgroundAgent`, supply the durable inbox through `policy(...).inbox`. Bind it to
607
+ the authenticated owner and stored logical `snapshot.runId`, not the physical worker segment:
608
+ an approval continuation has a new segment but the same logical input ids. Poll includes that
609
+ logical id and the active receiving agent. Check access and fence writes under the host's run
610
+ lease. The SDK does not supply an enqueue HTTP route, inbox tables or a queue service. The
611
+ existing injected `runs.create` and commit-before-enqueue boundary are unchanged; enqueuing a
612
+ message must not call `start` or `resume`. An app's delivery endpoint and UI must distinguish
613
+ queued, accepted and consumed messages, and expose recall without automatic resend.
614
+
615
+ ### Edit or regenerate a turn
616
+
617
+ Send the conversation up to the user turn whose answer you want again:
618
+
619
+ ```ts
620
+ await writer.run({ messages: messages.slice(0, userTurnIndex + 1) });
621
+ ```
622
+
623
+ To edit that turn, replace it and leave out everything after it:
624
+
625
+ ```ts
626
+ await writer.run({
627
+ messages: [
628
+ ...messages.slice(0, userTurnIndex),
629
+ { role: "user", content: "Explain indexes with one short SQL query." },
630
+ ],
631
+ });
632
+ ```
633
+
634
+ Both calls start a new run; `resume` continues an existing one. A session only appends, so start
635
+ another one from the earlier messages, for example
636
+ `createMemorySession({ messages: messages.slice(0, userTurnIndex) })`, then send the edited turn
637
+ with that session. Things the agent already did, like a sent email, stay done.
638
+
639
+ ### What a browser may see
640
+
641
+ Snapshots, receipts, raw progress events and session revisions are for your server. They hold
642
+ prompts, tool arguments and results, and the fields a provider owns, which `model_chunk` events
643
+ carry too. Send a browser the display data your server builds. When it needs the messages, send
644
+ `toClientMessages(result.history)`, which leaves out the provider-owned fields. Replace inline
645
+ bytes with references, and serve the bytes from a route that checks access.
646
+
647
+ ## Remember facts across conversations
648
+
649
+ A session keeps one conversation. Memory keeps facts for later conversations with the same
650
+ person. Start with the process-local reference store:
651
+
652
+ ```ts
653
+ const store = createMemoryStore();
654
+ ```
655
+
656
+ It loses everything when the process ends. For production, implement `MemoryStore` over your
657
+ own storage. The SDK adds no database, vector index, embedding calls or paid extraction.
658
+
659
+ ```ts
660
+ import { createMemoryStore, defineAgent, memoryTools } from "@providerkit/agents";
661
+
662
+ const store = createMemoryStore();
663
+ const notes = memoryTools();
664
+ const helper = defineAgent({
665
+ id: "helper",
666
+ version: "1",
667
+ instructions: "Use saved facts only when they help answer the person.",
668
+ provider,
669
+ memory: true,
670
+ tools: [notes.search, notes.save, notes.forget],
671
+ });
672
+
673
+ // Get these ids from authentication, never from model arguments or unchecked request data.
674
+ const scope = await store.access({ tenantId: workspace.id, userId: person.id }, { signal });
675
+ await helper.run("How do I take my coffee?", { memory: { store, scope }, signal, host });
676
+ ```
677
+
678
+ `memory: true` enables recall only. Register the tools you want; none is added automatically.
679
+ Reuse the **same tool objects** on a creator and its helper template when allowing generated
680
+ helpers to use memory. The helper's admitted tool list still applies. A host template can enable
681
+ recall independently, but a model cannot choose another store, scope or retention period.
682
+
683
+ ### Scope and versions
684
+
685
+ Every scope names a `tenantId`, even in a single-tenant app. Optional `userId`, `sessionId` and
686
+ `namespace` match exactly; omitting one never widens a read. Ids are nonempty, at most 200 characters
687
+ and contain no control characters. The store's `access` returns the scope with an erasure
688
+ `revision`. That revision prevents work started before an erasure from putting the data back.
689
+ It is not permission: your host must check ownership and current access.
690
+
691
+ `MemoryBinding.scope` is the only writable scope and must name a person. `shared` holds exact,
692
+ read-only scopes in the same tenant. There may be at most eight scopes altogether. The binding
693
+ is frozen into `snapshot.tree.memory` and inherited by specialists. Resume must supply the same
694
+ scopes, revisions and `keepForMs`, before authorization callbacks run. The store itself stays in
695
+ memory, not in the snapshot. `keepForMs` sets expiry on tool-created notes; the host owns cleanup.
696
+
697
+ The three tools use the normal journal, guards, approvals, limits and host `beforeTool` check:
698
+
699
+ - `memory_search({ query, limit? })` reads up to ten notes. Its result includes note keys and
700
+ versions in at most 4,000 characters. Large notes return a preview marked `truncated: true`,
701
+ with their key and version intact. If some matches do not fit, search with a smaller `limit`.
702
+ Queries contain 1 to 500 characters.
703
+ - `memory_save({ notes: [{ text, version: null }] })` creates a note with an operation-derived key.
704
+ Supply `key` and `version: null` to create a named note. To replace one, supply its current
705
+ version from search. A call saves at most five notes, atomically. Each accepts 1,000 characters
706
+ by default; `memoryTools({ maxNoteChars })` raises that up to 16,000.
707
+ - `memory_forget({ notes: [{ key, version }] })` deletes up to ten notes, atomically. A stale
708
+ version refuses the whole call. It never erases a conversation or another person's notes.
709
+
710
+ Only one writer can win a note-version race. Search again after a conflict. The store must never
711
+ reuse versions, even after delete/recreate. Interrupted writes are **not replayed**. A timeout or
712
+ lost reply needs host reconciliation, not another write. Search can use the existing explicit
713
+ read-only recovery policy. `memoryTools({ needsApproval: true })` requires approval for save and
714
+ forget; the host can require it through `needsApproval` too. Store exception text is not shown
715
+ to the model or saved in the journal.
716
+
717
+ ### Recall and resume
718
+
719
+ Recall runs once per agent run, before its first model call. It searches using the first 2,000
720
+ characters of the new input. A handoff keeps the source's latest user input across further
721
+ transfers, including accepted messages sent while it ran. Transfer notices never become recall
722
+ queries. An ordinary delegated task uses its own input.
723
+ `memory: { limit, maxChars, onError }` changes the defaults of five matches and 4,000 characters.
724
+ The ceilings are 20 matches and 16,000 characters, including the complete block's framing.
725
+ Notes that do not fit are omitted whole. Search results from another scope always fail closed.
726
+
727
+ Recall is stored in `snapshot.recall` and passes the existing checkpoint/progress barrier before
728
+ any model sees it. Resume reuses that record without searching again, including a recorded read
729
+ failure. `onError: "continue"` is the default; `"fail"` stops before the model when the store is
730
+ unavailable. Neither mode permits another scope's data or an erased access revision.
731
+
732
+ The block is user-role data, not system instructions or authorization. JSON quoting and escaped
733
+ opening brackets prevent stored tags from closing the block. This is not a prompt-injection
734
+ security boundary: host tool checks and guards still matter. Recall stays separate from the full
735
+ conversation, session append and steering positions. Compaction reattaches the same recorded
736
+ block without changing those records. An already-running model may still quote a recalled fact.
737
+
738
+ ### Save facts after a run
739
+
740
+ Ingestion is an explicit host action. No observer hook writes memory or makes an extraction call:
741
+
742
+ ```ts
743
+ const saved = await ingestMemory(result, {
744
+ memory: { store, scope },
745
+ notes: [{ key: "answer-style", text: "Prefers short answers", version: null }],
746
+ });
747
+ ```
748
+
749
+ Import `ingestMemory` from the main entry. Pass a completed root outcome from authoritative
750
+ server state, after its final checkpoint and session append. Choose and authorize the facts in
751
+ host code. The SDK removes memory tool rounds from the ingestion transcript, but answers may
752
+ still quote earlier notes. The original conversation remains unchanged. An ingestion request
753
+ accepts at most 20 notes and 1,000,000 UTF-8 JSON bytes, transcript included.
754
+
755
+ The store must implement `ingest` and `receipt` together. It must atomically check note versions
756
+ and the erasure revision, write the notes and commit a receipt keyed by the exact access and
757
+ logical run id. It computes a fingerprint of the complete request. The same request returns the
758
+ original receipt, even after later edits; different content for that run must conflict. A string
759
+ id or an in-process flag without that transaction is not idempotency.
760
+
761
+ `status: "saved"` carries the store's receipt. `"refused"` means a version conflict or erasure.
762
+ `"unknown"` means the write may have committed. The SDK never retries it. Query
763
+ `store.receipt({ access: scope, runId: result.runId }, { signal })` and reconcile with the original
764
+ request on the host. A missing receipt while an old call can still finish is not proof of no write.
765
+ Keep paid extraction outside these methods and under its own explicit execution policy.
766
+
767
+ ### Erase a person's memory
768
+
769
+ ```ts
770
+ await store.erase({ tenantId: workspace.id, userId: person.id }, { signal });
771
+ ```
772
+
773
+ This operation covers exactly that tenant and person, across their sessions and namespaces.
774
+ The store must remove notes, ingestion receipts and derived data, then invalidate every old
775
+ access revision atomically. A late write or ingestion using an old revision must throw
776
+ `MemoryErasedError`, even if that namespace had no notes when erasure ran.
777
+
778
+ **The host must also cancel active runs and erase their snapshots, checkpoints, event logs,
779
+ session messages and any other copies.** Those records can contain recalled notes and quoted
780
+ answers. Deleting store records cannot withdraw data already sent to a model. Apply your own
781
+ access rules and retention schedule to every copy. Resume authorization must reject erased runs;
782
+ reusing an old binding alone cannot recall information already sent.
783
+
784
+ The reference store uses a linear word search with Unicode and accent handling. It has no vector
785
+ ranking, automatic consolidation or notebook merge. Run
786
+ `await checkMemoryStore({ disposable: createMemoryStore() })` to check the contract. The helper
787
+ writes and erases test records, so supply a disposable store only. A passing check cannot prove
788
+ that a production adapter enforces your authorization or transaction boundaries.
789
+
790
+ For background jobs, set `createBackgroundAgent({ ..., memory: owner => openMemory(owner) })`.
791
+ The factory checks the authenticated owner at start and the stored owner in the worker. Start
792
+ freezes scopes without recalling; the worker recalls under the existing lease. A changed scope
793
+ or erasure revision is refused before continuation claims. Ingestion stays a separate explicit
794
+ host action, never a worker completion hook.
795
+
796
+ See [the offline memory example](examples/memory.ts). It uses no live provider or store.
797
+
798
+ ## Tools and checked output
799
+
800
+ Pass core `Tool` instances in `tools`. Their input validation, timeouts and error outcomes remain
801
+ core's responsibility. Unmarked tools run serially. Parallel tool execution requires both the
802
+ core tool's `isConcurrencySafe` flag and the host's permission to batch it. Host tools run in your
803
+ process. Optional code mode isolates model-written programs, not your tool implementations.
804
+
805
+ For a checked result, supply `output.schema` and `output.validate`. The schema tells the model what
806
+ to submit; the validator checks the actual value. Return the desired TypeScript value or throw a
807
+ message explaining what to correct. The SDK reserves the `submit_result` tool name for this path.
808
+ A validator should be pure: it can run again when a completed result is restored.
809
+
810
+ ### Text, JSON and image results
811
+
812
+ Return a JSON value from an ordinary core tool. Its existing `summarize` function controls the
813
+ text the next model reads; core defaults to JSON text. The successful SDK receipt also keeps
814
+ that JSON value in `result.output`. It is private host data, not automatic browser content.
815
+ A non-JSON typed value with a text summary still works, but only the summary is saved.
816
+
817
+ To return text with an image, return core content parts from the same tool's `run` function:
818
+
819
+ ```ts
820
+ return [
821
+ { type: "text", text: "The front of the package." },
822
+ { type: "image", mimeType: "image/png", data: pictureBase64 },
823
+ ];
824
+ ```
825
+
826
+ The SDK recognizes nonempty arrays of content parts. It joins text with newlines and puts
827
+ images in core's tool-message `images` field. No second tool wrapper is needed. Empty arrays
828
+ stay JSON. JPEG, PNG, WebP and GIF use the same padded-base64 checks as user attachments.
829
+ Files and media references are not supported in tool results: return text and inline images.
830
+ Tool images count toward the run's total `limits.inlineBytes`, including earlier tool results
831
+ and user attachments. Too many bytes stops the run with `tool_media_limit`, without repeating
832
+ the tool. Results retain images across checkpoints, sessions and resume. Client tools and
833
+ pure delegations use the same normalization. Display projectors must still opt in to tool
834
+ content and replace inline bytes with authorized references.
835
+
836
+ ### End on a tool result
837
+
838
+ When a tool already has the answer, avoid paying the model to rewrite it:
839
+
840
+ ```ts
841
+ const finder = defineAgent({
842
+ id: "finder",
843
+ version: "1",
844
+ instructions: "Use lookup to find matching records.",
845
+ provider,
846
+ tools: [lookup],
847
+ stopAtTools: ["lookup"],
848
+ });
849
+ ```
850
+
851
+ The run ends after that tool succeeds, without another model call. A text agent returns the
852
+ summary the tool supplies. With an `output` contract, the tool's raw output must pass its validator;
853
+ the summary still goes into history. A failure or rejected result goes back to the model to
854
+ correct. An invalid result does not undo the tool's effects.
855
+
856
+ `stopAtTools` names ordinary host tools, not delegations or `submit_result`. If a turn calls
857
+ several tools, all of them settle before the run ends. The first successful stopping tool in the
858
+ model's call order supplies the answer, regardless of which one finishes first.
859
+
860
+ Core tools marked `isTerminal: true` also stop the run this way, but must be called alone. For
861
+ these host tools the final answer comes from the tool's result, not its input. `submit_result`
862
+ still validates its input. Stopping results are recorded in the tool receipt, so resume never
863
+ repeats a finished effect or asks the model to rephrase it.
864
+
865
+ ## Code mode
866
+
867
+ Let the model write a short program that calls several tools before returning an answer:
868
+
869
+ ```ts
870
+ await reader.run("Add up the prices of the matching records.");
871
+ ```
872
+
873
+ Install the optional QuickJS engine, then bind only the tools the program needs:
874
+
875
+ ```sh
876
+ bun add quickjs-emscripten-core@^0.32.0 @jitl/quickjs-wasmfile-release-sync@^0.32.0
877
+ ```
878
+
879
+ ```ts
880
+ import { defineAgent } from "@providerkit/agents";
881
+ import { codeMode } from "@providerkit/agents/code-mode";
882
+ import { createQuickJsDriver } from "@providerkit/agents/code-mode/quickjs";
883
+
884
+ const program = codeMode({ tools: [lookup], driver: createQuickJsDriver() });
885
+ const reader = defineAgent({
886
+ id: "reader",
887
+ version: "1",
888
+ instructions: "Look up the records and calculate the total. Return only what the person needs.",
889
+ provider,
890
+ tools: [program],
891
+ limits: { toolCalls: 64 },
892
+ });
893
+ ```
894
+
895
+ The model calls `run_code` with `{ code: string }`. The code is an async function body, for
896
+ example `const rows = await tools.lookup({}); return rows.length;`. Every program starts in a
897
+ fresh sandbox. It has no network, files, process, imports or timers. It can pass JSON between
898
+ bound tools without sending every intermediate value back to the model. The host tools still
899
+ have their normal powers: authorize each action in `host.beforeTool`.
900
+
901
+ The description includes `toolTypings(tools)`, built from input schemas and core's optional
902
+ `outputSchema`. Without an output schema, that tool's return type is `unknown`. These types
903
+ help the model write code; they do not replace input validation or authorization.
904
+
905
+ ### Keep control actions direct
906
+
907
+ Bindings accept ordinary core tools only. Approval-required, asking, client, terminal, delegation,
908
+ handoff, nested code and helper-creation tools are refused. A tool listed both directly and in
909
+ code must be the same object. A bound-only tool cannot be called directly by the model.
910
+
911
+ `enabledTools` narrows both the advertised code bindings and execution. Include `run_code` and
912
+ each bound name you want to permit; selecting `run_code` alone grants no inner tool. A
913
+ model-created helper needs the same explicit grants from its creator and host template.
914
+
915
+ For a dynamic `host.needsApproval` requirement, `prepareRequest`, `answerNow` and `beforeTool`
916
+ must supply a current, authoritative decision immediately. Otherwise the call returns a refusal
917
+ that code can catch; it never suspends inside the sandbox. Approved replacement arguments still
918
+ pass the tool input guard and current authorization. A stale or expired decision permits no effect.
919
+ Set `needsApproval: true` on `codeMode` to ask before the whole program starts instead.
920
+
921
+ ### Limits and receipts
922
+
923
+ `codeMode({ limits })` overrides these defaults. KiB is 1,024 bytes; MiB is 1,024 KiB.
924
+
925
+ | Setting | Default | What it bounds |
926
+ | ----------------- | ------: | ----------------------------------------------------------- |
927
+ | `calls` | 32 | Inner call attempts per program attempt, including retries |
928
+ | `timeoutMs` | 30,000 | Wall time, including tool waits |
929
+ | `cpuMs` | 2,000 | Guest JavaScript time, excluding tool waits |
930
+ | `memoryBytes` | 32 MiB | Guest heap |
931
+ | `stackBytes` | 256 KiB | Guest stack |
932
+ | `sourceBytes` | 64 KiB | UTF-8 program source |
933
+ | `resultBytes` | 32 KiB | JSON value returned by the program |
934
+ | `logBytes` | 8 KiB | Captured console text; excess bytes are counted and dropped |
935
+ | `callInputBytes` | 256 KiB | One inner call's JSON arguments |
936
+ | `callOutputBytes` | 1 MiB | One tool's JSON reply to the program |
937
+
938
+ The enclosing run's `parallelTools` bounds concurrent calls. Only tools marked concurrency-safe
939
+ and allowed by the host may overlap. Other calls share the tree's serial effect boundary, even
940
+ across specialists. Run and tree deadlines can end the program sooner. The driver admits at most
941
+ four programs at once by default (`maxActive`). QuickJS runs on the host thread; a busy program
942
+ can block that thread up to its CPU allowance. These guest limits do not bound allocations inside
943
+ host tools.
944
+
945
+ The program call and its inner attempts spend the run's `toolCalls` budget. Inner calls leave one
946
+ slot for a final direct tool such as `submit_result`. Raise the run budget when needed, not just
947
+ `codeMode.limits.calls`.
948
+
949
+ A successful program returns JSON text containing `result` (when defined), `logs`, `toolCalls`
950
+ and `toolCallsLeft`. A failure also includes `error` and up to 20 call summaries. Tool failures
951
+ throw a catchable `ToolError` with `tool` and `kind`. An oversized or non-JSON tool reply is refused
952
+ without erasing its effect receipt. Returning, throwing or reaching a program limit aborts
953
+ queued and running calls; their recorded outcomes settle before the program result. Queued calls
954
+ never start. Cancellation cannot undo an effect or stop a host tool that ignores its signal.
955
+
956
+ `ToolExecution.calls` holds private `ProgramCall` records. Each has a stable `id`, an `attemptId`,
957
+ the owning `programAttemptId`, tool name, original arguments and `pending`, `running` or `completed`
958
+ status. `started: false` means it never reached dispatch. Completed results retain at most 1 KiB
959
+ of text, not the full JSON output; `bytes` records the current attempt's original output size.
960
+ Retries keep their failed attempt receipts. Write starts and completions pass the existing
961
+ checkpoint barrier. Durability still requires `host.checkpoint`.
962
+
963
+ Inner `tool_start`, `tool_result` and retry `operation_restart` events carry `parentOperationId`
964
+ through their request or event. Tool receipts carry it too. Group by that field, not by parsing
965
+ ids; key attempts by `(operationId, attemptId)`. Raw events, code, arguments, logs and returned
966
+ values remain server data. Expose them only through an explicit display policy.
967
+
968
+ ### After a restart
969
+
970
+ The SDK never resumes a half-run sandbox or replays a recorded write. An unfinished write fails
971
+ closed with `interrupted_operation` naming its inner operation. Reconcile it with the service
972
+ before continuing. Known completed changes stay recorded; the program closes as `interrupted`
973
+ and the model can continue without repeating those changes. Pending calls did not run.
974
+
975
+ An explicit `recovery.readOnlyTools` entry naming the code tool can restart from the beginning
976
+ only when every recorded inner call was read-only and neither program nor calls have request
977
+ history. It requires `host.beforeTool`, unchanged definitions and remaining attempt/call budgets.
978
+ The new attempt retains old receipts and continues call ids. Read-only calls may still cost money.
979
+ Provider-hosted effects keep their existing no-replay rules.
980
+
981
+ ### TypeScript and Workers
982
+
983
+ No TypeScript compiler is bundled. Supply a host compiler if you want TypeScript source:
984
+
985
+ ```ts
986
+ import { transform } from "sucrase"; // Install separately if you choose this compiler.
987
+
988
+ const program = codeMode({
989
+ tools: [lookup],
990
+ driver: createQuickJsDriver(),
991
+ transpile: (source) => transform(source, { transforms: ["typescript"] }).code,
992
+ });
993
+ ```
994
+
995
+ The hook receives an async function expression, not a raw body. Return JavaScript for that
996
+ expression; a trailing semicolon is allowed. Custom transpilers own their source mapping.
997
+
998
+ On Workers, pass an already compiled module instead of fetching and compiling WebAssembly:
999
+
1000
+ ```ts
1001
+ import wasmModule from "@jitl/quickjs-wasmfile-release-sync/wasm";
1002
+
1003
+ const driver = createQuickJsDriver({ wasmModule });
1004
+ ```
1005
+
1006
+ Browsers and extensions can set `wasmLocation` to their packaged asset. Neither the main agent
1007
+ entry nor `/code-mode` imports QuickJS. A custom `CodeDriver` must honor the same fresh-sandbox,
1008
+ string-bridge, limit and cleanup contract; it must never invoke host tools itself.
1009
+
1010
+ Run [the offline code-mode example](examples/code-mode.ts) with `bun agents/examples/code-mode.ts`.
1011
+ It uses the real QuickJS driver and two local tools, with no provider key or network request.
1012
+
1013
+ ## Specialists and parallel work
1014
+
1015
+ An orchestrator can call another configured agent as a tool:
1016
+
1017
+ ```ts
1018
+ const editor = defineAgent({
1019
+ id: "editor",
1020
+ version: "1",
1021
+ instructions: "Ask the reviewer for feedback, then write the final answer.",
1022
+ provider,
1023
+ tools: [
1024
+ reviewer.asTool({
1025
+ name: "review",
1026
+ description: "Review a draft and identify changes it needs.",
1027
+ }),
1028
+ ],
1029
+ });
1030
+ ```
1031
+
1032
+ The specialist gets only the input sent to it, not the parent's conversation. Its result returns
1033
+ to the orchestrator; this is not a conversation handoff. Use `defineHandoff`, below, when the target
1034
+ should answer the person directly. Each agent can use a different core provider.
1035
+ `asTool` returns a failed tool result for a specialist's own turn, tool-call, time or output
1036
+ limit, or a known model/result failure. The parent can answer using its other results. Core
1037
+ `ProviderError` failures and the SDK's `model_failed`, `invalid_model_output`, `content_filtered`,
1038
+ `incomplete_turn`, `missing_result` and `empty_output` codes are local failures. An unclassified
1039
+ exception is not: custom providers should throw core's `ProviderError` for provider failures.
1040
+
1041
+ Suspension still reaches the host. Cancellation, shared tree limits and host or journal failures
1042
+ still stop the parent. Every admitted child settles, and its usage and completed receipts remain.
1043
+ Use `defineDelegation` when your code needs to combine explicit child outcomes or share the
1044
+ conversation. Its coordinator cannot waive cancellation, tree limits or integrity failures.
1045
+
1046
+ A delegation declares its fixed `specialists` list, input schema and validator. Inside its `run`
1047
+ callback, start children before joining them:
1048
+
1049
+ ```ts
1050
+ const draft = context.child("draft", writer, input);
1051
+ const review = context.child("review", reviewer, input);
1052
+ const [draftResult, reviewResult] = await context.join([draft, review]);
1053
+ ```
1054
+
1055
+ Children start immediately, subject to the shared limit. Joining returns outcomes in the order you
1056
+ requested, not the order they finish. Check their statuses and return only what the parent needs,
1057
+ not their full snapshots. A suspended child pauses the parent instead of becoming a success string.
1058
+
1059
+ A child takes the same input as `run`: text, parts or `{ messages }`. To let a child read what came
1060
+ before, forward `context.conversation`, the parent's messages before this tool call, without the
1061
+ system prompt or the unfinished round:
1062
+
1063
+ ```ts
1064
+ const review = context.child("review", reviewer, {
1065
+ messages: [...context.conversation, { role: "user", content: input }],
1066
+ });
1067
+ ```
1068
+
1069
+ Your coordinator is trusted code, so provider-owned fields in the forwarded messages are kept.
1070
+ Media references stay references, and the child reads them through the same `host.loadMedia`.
1071
+
1072
+ Coordination callbacks must be pure: use `child`, `join` and `ask` for work. The callback can run again
1073
+ after an interruption, but completed children are reused. Reusing a child key with a different
1074
+ input, history or agent is refused. Every admitted child settles before the delegation ends.
1075
+
1076
+ A child key becomes part of the child's run ID and of every operation ID under it. Progress events
1077
+ carry those IDs, and a screen that shows the run may send them to a browser. So key children by
1078
+ position or by a fixed name, such as `topic-1`, and never by their input.
1079
+
1080
+ ## Serve tasks over A2A
1081
+
1082
+ A2A lets another app send tasks to your agent or workflow. Pass each HTTP request to the handler:
1083
+
1084
+ ```ts
1085
+ const response = await server.fetch(request);
1086
+ ```
1087
+
1088
+ It returns a standard `Response`. The complete [offline server example](examples/a2a-server.ts)
1089
+ uses real workflow execution and an in-process client, with no socket or paid model:
1090
+
1091
+ ```sh
1092
+ bun agents/examples/a2a-server.ts
1093
+ ```
1094
+
1095
+ It prints `Hello`. The public functions live on `@providerkit/agents/a2a`:
1096
+
1097
+ - `createA2AServer` serves A2A 1.0 and 0.3 through JSON-RPC or HTTP+JSON.
1098
+ - `createMemoryRuns` runs local agents or workflows in this process. Use your existing durable
1099
+ run service for work that must survive a restart.
1100
+ - `createMemoryTaskStore` keeps owner-scoped task and message receipts. Full stores refuse new
1101
+ data rather than discard receipts that prevent duplicate work. Supply a persistent task store
1102
+ in production.
1103
+
1104
+ Authentication runs before body parsing. `authenticate` returns the owner and caller as
1105
+ `{ owner, actorId }`; your server configuration selects the tenant. Every task, context, stream
1106
+ and callback stays in that partition. `authorize` can check current access on each operation.
1107
+ `bearerToken` is available for a host-owned shared secret. There is no automatic sign-in flow.
1108
+
1109
+ By default, even the discovery card requires authentication. `publicCard: true` opens only that
1110
+ card. `allowAnonymous: true` is for development and puts callers in one shared anonymous
1111
+ partition. Failed authentication never falls back to anonymous access.
1112
+
1113
+ Write the card's name, description and skills yourself. Prompts and private tools are not
1114
+ published as skills. Supply security declarations separately in `card.security["1.0"]` and
1115
+ `card.security["0.3"]`; the two formats are not interchangeable. A workflow with custom input
1116
+ needs `prepare` to validate and map the incoming message. Context IDs only group tasks unless
1117
+ `sessions: true` is set with an owner-checked session factory. An ID does not grant session access.
1118
+
1119
+ ### Choose what the peer can see
1120
+
1121
+ No final result or transient model text leaves the process by default. `projectOutput` selects
1122
+ final parts; `projectText` selects root text. Neither exposes reasoning, tool data or child
1123
+ transcripts automatically. Current projection policy also applies when reading stored history.
1124
+ `exposeRequest` can narrow which requests a peer sees. Remote approvals and client actions need
1125
+ separate opt-ins and still use your authenticated request policy.
1126
+
1127
+ `a2aPolicy` checks reserved A2A evidence, then delegates to your real claim and decision handlers.
1128
+ It does not turn peer text into permission. Install `a2aSegments` in workers to track continuations
1129
+ started outside the HTTP handler. Its `scope(owner, runId)` must recover the original authenticated
1130
+ partition from your storage. Use `server.refresh(principal, taskId)` after authoritative checkpoints
1131
+ to update the task and deliver permitted notifications.
1132
+
1133
+ Cancellation returns `{ id, requested }`. Follow the returned physical segment; acceptance is
1134
+ not proof that the task stopped. Canceling a paused durable run needs the background binding's
1135
+ `createContinuation` capability. Closing an observer only detaches it. No browser timer or SDK
1136
+ scheduler resumes a task automatically.
1137
+
1138
+ ### Sign cards and send notifications
1139
+
1140
+ `signAgentCard` and `verifyAgentCard` use host-selected keys with ES256, EdDSA or RS256. A2A 1.0
1141
+ signs normalized, known protobuf fields; unknown fields and removed empty values are not covered.
1142
+ Version 0.3 signs the raw public card without its signatures. A valid signature does not authorize
1143
+ an endpoint or an application action.
1144
+
1145
+ Push delivery requires current authorization and a host egress policy. Attempts are recorded
1146
+ before sending; an uncertain delivery is never resent automatically. URL checks do not prove
1147
+ where DNS resolves: your egress layer must check and pin the destination. Timestamped HMAC helpers
1148
+ are an optional providerkit extension, not an A2A standard, and need host replay storage.
1149
+
1150
+ ## Remote specialists over A2A
1151
+
1152
+ Run the [offline remote example](examples/a2a-remote.ts):
1153
+
1154
+ ```sh
1155
+ bun agents/examples/a2a-remote.ts
1156
+ ```
1157
+
1158
+ It prints `Done`. The peer is an in-process fetch fixture, not a live service.
1159
+
1160
+ `defineRemoteAgent` on `@providerkit/agents/a2a` creates a `kind: "remote"` specialist.
1161
+ It has `run`, `resume`, `cancel` and `asTool`. Register it in a delegation's `specialists`
1162
+ or a workflow's `agents`. Local agents, workflows and remote children use the same child
1163
+ admission, host binding, checkpoints and tree limits. Remote agents are not handoff targets.
1164
+ Their snapshots have a remote message journal, not made-up local models or model turns.
1165
+
1166
+ Configure the host-owned `id`, `agentVersion`, `card`, `version` (`"1.0"` or `"0.3"`),
1167
+ `binding` (`"JSONRPC"` or `"HTTP+JSON"`) and `policy.allow`. Use `updates: "poll"` (default)
1168
+ or `"stream"`; streaming requires a card that supports it. The SDK refuses missing required
1169
+ extensions and options it cannot represent. No production dependency on the official A2A SDK
1170
+ is needed. Credentials, headers, fetch and verification callbacks stay with the host, unsaved.
1171
+ Bump `agentVersion` when hidden endpoint, authorization or output policy changes.
1172
+
1173
+ `run` accepts one user turn, including host-authorized media, but not a local conversation
1174
+ history, session, memory binding or model settings. Children take `{ input }`.
1175
+ `host.beforeTool` must authorize every send and explicit cancellation. Its `remote_send`
1176
+ request includes the actual outbound message. Card text and model-written helper instructions
1177
+ never grant an endpoint or tool. `asTool` uses only the description your code supplies.
1178
+
1179
+ Every send and follow-up saves its exact message and identity before dispatch. Cancellation
1180
+ has its own receipt. None is resent after a timeout, lost reply, worker restart or model retry.
1181
+ A known task can be observed with `GetTask` or a subscription; observing an old task does not
1182
+ prove an uncertain follow-up arrived. Repeated read failures suspend with a `wakeAt` time.
1183
+ The background binding uses the same due-wake continuation as workflows to reattach; your
1184
+ existing host queue schedules it. No message is sent again and no SDK scheduler is added.
1185
+ A completed result is reused only from a validated journal. Keep authoritative snapshots private and compare them in `host.authorizeResume`.
1186
+
1187
+ `inputRequired: "ask"` maps remote questions to local request IDs. Answers go through
1188
+ `prepareRequest`, `resolveRequest` and current `beforeTool` checks. Partial or refused answers
1189
+ stay pending. Remote approval and client-tool requests are refused, not converted into grants.
1190
+ An authenticated `cancel` decision can request remote cancellation; `stop` ends local work only.
1191
+ `inputRequired: "parent"` returns `{ kind: "input_required", handle, question }` to the parent.
1192
+ Pass that handle with the next child's `{ input, continue }`. It is valid once in that root and
1193
+ specialist scope, never as an arbitrary task ID. This mode accepts one free-text question;
1194
+ use `"ask"` for multiple questions, choices or forms. `"fail"` declines input routing.
1195
+
1196
+ The default output is text from artifacts, or the final reply when there are no artifacts.
1197
+ An `output` contract validates the first data part, or parsed JSON text. Peer metadata, private
1198
+ error text and history are not copied into the result. Files become labels and peer URLs are
1199
+ never fetched. `includeImages: true` requires an output validator and gives it
1200
+ `{ content: [text and inline image parts] }`. Return those content parts to let `asTool` forward
1201
+ images through the existing rich tool-result path. Input media references use `host.loadMedia`.
1202
+
1203
+ Defaults are 12 outbound messages, 5 minutes, 5,000,000 inline bytes and 1,048,576 result bytes.
1204
+ Parent-continuation messages share the message budget. Remote work holds a tree slot and counts
1205
+ as a child, not a model call. Every remote receipt has `billing: "unknown"`; `treeUsage` counts
1206
+ only local reported model usage. A zero local token count does not mean a free remote task.
1207
+
1208
+ An aborted signal, lost worker lease or closed observation stops local work only. It does not
1209
+ send `CancelTask` or undo external effects. Use `remote.cancel(snapshot, { host })` for an explicit
1210
+ host-authorized request. `snapshot.remote.cancel.state === "canceled"` confirms the peer's reply;
1211
+ an accepted command or an unknown reply is not cancellation proof. Repeated cancellation never
1212
+ resends an uncertain request. Reconcile it with the remote operator instead.
1213
+
1214
+ ## Workflows
1215
+
1216
+ A workflow is an ordinary async function with saved steps. Its input and result are typed:
1217
+
1218
+ ```ts
1219
+ const result = await totals.run({ count: 2 }); // A completed result has output: 4.
1220
+ ```
1221
+
1222
+ This small workflow needs no host because it has no effects:
1223
+
1224
+ ```ts
1225
+ import { defineWorkflow } from "@providerkit/agents/workflow";
1226
+
1227
+ const totals = defineWorkflow({
1228
+ id: "totals",
1229
+ version: "1",
1230
+ input: {
1231
+ schema: { type: "object", properties: { count: { type: "number" } }, required: ["count"] },
1232
+ validate(raw) {
1233
+ if (
1234
+ typeof raw !== "object" ||
1235
+ raw === null ||
1236
+ !("count" in raw) ||
1237
+ typeof raw.count !== "number"
1238
+ )
1239
+ throw new TypeError("Provide a count.");
1240
+ return { count: raw.count };
1241
+ },
1242
+ },
1243
+ async run({ count }) {
1244
+ return count * 2;
1245
+ },
1246
+ });
1247
+ ```
1248
+
1249
+ For work outside that function, use its context:
1250
+
1251
+ - `ctx.step(key, callback, options?)` saves a host callback's result.
1252
+ - `ctx.agent(key, agent, input)` runs a registered agent under the same tree budgets.
1253
+ - `ctx.workflow(key, workflow, input)` runs a registered workflow under those budgets.
1254
+ - `ctx.ask(question, validate)` saves a question and reads its authenticated answer.
1255
+ - `ctx.sleep(key, ms)` saves a wake time and returns control while it waits.
1256
+
1257
+ Register children in `agents` and `workflows`. A child receives explicit input only. Agent children
1258
+ keep their own guards, memory policy, tool journals and helper limits. Memory access stays bound to
1259
+ this root's host-supplied scopes. A workflow has no model, transcript, session or inbox of its own.
1260
+ `workflow.asTool({ name, description })` makes it a typed specialist. `defineDelegation` also accepts
1261
+ workflow children. Known local failures return as tool feedback; cancellation, shared limits and
1262
+ host or journal failures stop the parent.
1263
+
1264
+ ### Put effects in steps
1265
+
1266
+ Supply `host.beforeStep` on every run that uses effects, children or answers. It must check current
1267
+ ownership and any execution lease. The callback runs again immediately before dispatch, including
1268
+ after the running marker is saved. A saved approval does not waive that check.
1269
+
1270
+ ```ts
1271
+ await ctx.step(
1272
+ "save",
1273
+ ({ input, signal, idempotencyKey }) =>
1274
+ posts.insert(input, {
1275
+ signal,
1276
+ idempotencyKey,
1277
+ }),
1278
+ { input: draft, needsApproval: true },
1279
+ );
1280
+ ```
1281
+
1282
+ `posts` is your authorized host service. Step callbacks also receive `context`, `key`, `attempt`
1283
+ and `report(data)`. Context stays in memory. Reported data and raw step results are server data,
1284
+ not automatic display content. Use opaque fixed keys such as `save` or `review-2`, never private
1285
+ input: keys appear in operation ids and progress.
1286
+
1287
+ Input and results must be plain JSON within `limits.resultBytes`. The first run returns the same
1288
+ JSON copy as replay. Optional `validate` checks results on both paths. Approval edits require
1289
+ `validateInput`; the host must explicitly allow editing. Questions and approvals use the existing
1290
+ `prepareRequest`, `resolveRequest` and `answers` contracts. Workflow requests have `step`, not
1291
+ `call`. Text that says "approve" and client-supplied flags grant no permission.
1292
+
1293
+ ### Replay and parallel work
1294
+
1295
+ The function runs from its start after interruption. Completed effects are read from the journal,
1296
+ not called again. Only context calls are recorded. Keep all other code pure: clock reads, random
1297
+ values, new ids and external reads belong inside a step. Declare every value the callback uses
1298
+ in `options.input`. Do not start an agent directly inside a callback or call context methods from
1299
+ inside another step; that bypasses accounting or can deadlock the step gate.
1300
+
1301
+ Use ordinary promises for parallel branches:
1302
+
1303
+ ```ts
1304
+ const [draft, review] = await Promise.all([
1305
+ ctx.agent("draft", writer, task),
1306
+ ctx.agent("review", reviewer, task),
1307
+ ]);
1308
+ ```
1309
+
1310
+ A sequence uses `await`. A branch uses `if`. A map includes its position in each key; a bounded
1311
+ loop includes its iteration. An evaluator loop is the same pattern: await the worker, await the
1312
+ reviewer, then stop or advance the iteration. Check child statuses before using their outputs.
1313
+ The barrier waits for every admitted step, even after `Promise.all` rejects or the function
1314
+ returns early. A pending question or sleep still suspends a function that caught its pause.
1315
+ Catch `StepFailedError` only; its `key`, `reason` and `error` describe a saved failure. A caught
1316
+ failure takes the same fallback branch on replay. Do not use `Promise.race` to select a branch:
1317
+ its winner is not recorded. Await every context call.
1318
+
1319
+ Duplicate keys in one attempt, changed step kind/input/definition and skipped recorded steps are
1320
+ refused before new effects. Final output must reach every recorded step. Change `version` when
1321
+ callback implementations, keys, inputs or result meaning change. Old unreleased snapshots without
1322
+ the new node discriminator are refused, not converted. Keep old definitions until their runs settle.
1323
+ `checkReplay(workflow, snapshot)` checks saved coordination without a host or effects; it also
1324
+ compares the result of a completed journal. It cannot prove that hidden code kept the same meaning.
1325
+
1326
+ Defaults are 100 saved steps, four concurrent host callbacks, 262,144 UTF-8 JSON bytes per input
1327
+ or result and no in-process wait. `limits.inlineWaitMs` opts into short waits in the worker.
1328
+ An effect's default timeout is 60 seconds. Each step allows at most 100 recorded reservations.
1329
+ Tree limits still bound children, depth, model calls and elapsed time. Workflows hold no agent
1330
+ slot, so a workflow can wait on children with `maxParallel: 1`. An infinite loop without a context
1331
+ call cannot be stopped by this SDK.
1332
+
1333
+ ### Retry only repeatable work
1334
+
1335
+ No retry is automatic. A step left running after a crash has an unknown result and fails with
1336
+ `interrupted_operation`. A timeout cannot stop code that ignores its signal. An idempotency string
1337
+ or `idempotent: true` is not accepted as proof that a write can be repeated.
1338
+
1339
+ For a callback you know is read-only, set `retry: { maxAttempts: 2, replay: "read-only" }`.
1340
+ It can still cost money or return newer data. For a write, use `replay: "reconcile"` and supply
1341
+ `host.reconcileStep`. Return `{ outcome: "not_run", receipt }` only after authoritative checks
1342
+ prove the entire attempt did not run **and cannot still complete**. Otherwise return
1343
+ `{ outcome: "unknown" }`. The SDK saves the receipt before reserving another attempt.
1344
+ Retries retain errors and every attempt id. Approval-gated steps cannot retry an old decision.
1345
+
1346
+ Retries default to core's full-jitter backoff with a 1-second base and 30-second cap.
1347
+ `baseDelayMs`, `maxDelayMs` and a pure `retryOn` can narrow this policy. Aborts, non-transient
1348
+ provider failures, quota errors and HTTP 400–407 or 409 do not retry by default. Invalid results,
1349
+ failed authorization, cancellation, checkpoint failure and tree limits never become retries.
1350
+ Delayed retries save their wake time before returning control.
1351
+
1352
+ Agent and workflow steps also accept `{ retry: { maxAttempts, replay, retryOn? } }`.
1353
+ This repeats a whole child, not only its last operation. The read-only assertion must cover
1354
+ **every** effect in that child. Reconciliation must cover them all too. Children with requests
1355
+ or configured hosted effects cannot use whole-child retries. Each attempt gets another child
1356
+ run and consumes the existing child and model-call budgets. Local limits are not retried; every
1357
+ previous child and its usage remain recorded.
1358
+
1359
+ ### Resume a wake in the background
1360
+
1361
+ `createBackgroundAgent({ workflow, kind, runs, enqueue, policy })` uses the same binding as agents.
1362
+ It keeps injected `runs.create`'s commit-before-enqueue boundary. Set `policy.beforeStep` and use
1363
+ one `kind` per workflow version. `read().wakeAt` and suspended outcomes report the earliest wake.
1364
+ At that time, your existing delayed queue or scheduled job calls `resume(owner, id, {})`. An early
1365
+ call is refused with the wake time. The SDK supplies no scheduler.
1366
+
1367
+ An empty-answer continuation has `kind: "answers"` and includes `continuation.wakeAt`.
1368
+ A `kind: "cancel"` continuation has empty answers and no wake time; it cannot approve a tool
1369
+ or skip ahead to a scheduled step. For a wake, your `claimContinuation` must
1370
+ atomically reserve `(snapshot.runId, wakeAt)` for that claim and physical segment, even though
1371
+ there are no answers. Repeating the same claim in recovery may succeed; another segment must
1372
+ fail. Otherwise two delayed jobs could repeat future effects. Authentication, claims and fencing
1373
+ remain host responsibilities. A wake does not refresh the tree deadline; one beyond it is a limit,
1374
+ not a successful sleep. Worker cancellation and lease loss return control to the run service.
1375
+
1376
+ See [the offline workflow example](examples/workflow.ts). Run it with
1377
+ `bun agents/examples/workflow.ts`. It asks a question, restores JSON state and reuses the completed
1378
+ agent child without a live provider or application store.
1379
+
1380
+ ## Helpers the model creates
1381
+
1382
+ Let an agent split a task among helpers:
1383
+
1384
+ ```ts
1385
+ await explainer.run("When does a database index help?");
1386
+ ```
1387
+
1388
+ The host supplies a template. The model writes each helper's task and optional instructions,
1389
+ then selects tools and a model alias from the host's menu. It cannot add code, credentials,
1390
+ permissions, hosted capabilities or higher run limits.
1391
+
1392
+ ```ts
1393
+ import { defineAgent, subagentTool } from "@providerkit/agents";
1394
+
1395
+ const helper = defineAgent({
1396
+ id: "helper",
1397
+ version: "1",
1398
+ instructions: "Answer only the task you receive.",
1399
+ provider,
1400
+ tools: [lookup],
1401
+ });
1402
+ const explainer = defineAgent({
1403
+ id: "explainer",
1404
+ version: "1",
1405
+ instructions: "Ask helpers about separate parts of the question, then combine their answers.",
1406
+ provider,
1407
+ tools: [
1408
+ lookup,
1409
+ subagentTool({
1410
+ name: "create_helpers",
1411
+ description: "Start helpers for separate parts of the question.",
1412
+ agent: helper,
1413
+ }),
1414
+ ],
1415
+ });
1416
+ ```
1417
+
1418
+ A model call to `create_helpers` takes `{ agents: [{ name, task, instructions?, tools?, model? }] }`.
1419
+ `name` is private text: 1 to 64 letters, digits, `_` or `-`, unique among newly created helpers
1420
+ admitted by this creation tool in this run. A new helper needs a new name. A follow-up uses its
1421
+ helper's existing name and returned `helperId`, as described below. `tools` contains registered tool names. Omitted tools means
1422
+ none; `defaultTools: "all"` grants the currently available set. A tool must be the **same object**
1423
+ on both the creator and the template, and enabled on the creator. Two tools with the same name
1424
+ are not interchangeable. The template's own tool-selection policy still applies.
1425
+
1426
+ Handoffs and ordinary delegations cannot be granted. The checked-output tool `submit_result`
1427
+ stays available when the template needs it. Several helpers in one call run in parallel under
1428
+ the existing tree limit. Their results return in declaration order. Separate creation calls
1429
+ in one turn still run one after another, like other delegations.
1430
+
1431
+ Use `agent: "self"` to reuse the creator's recorded instructions and model settings. Its
1432
+ instruction callbacks do not run again. Explicit templates resolve their own callbacks once.
1433
+ The helper gets no parent history by default, and never gets the parent's session or inbox.
1434
+ Its host instructions come first, followed by the model-written instructions. These instructions
1435
+ are not permission to use a tool.
1436
+
1437
+ ### Share approved history with a helper
1438
+
1439
+ A model may request `fork: true` only when the host configures `fork`:
1440
+
1441
+ ```ts
1442
+ subagentTool({
1443
+ name: "create_helpers",
1444
+ description: "Start helpers for separate parts of the question.",
1445
+ agent: helper,
1446
+ fork: {
1447
+ identity: "public-history-1",
1448
+ maxMessages: 4,
1449
+ maxBytes: 8_000,
1450
+ select: (messages) =>
1451
+ messages.flatMap((message, index) => (isApprovedForHelpers(message) ? [index] : [])),
1452
+ },
1453
+ });
1454
+ ```
1455
+
1456
+ `isApprovedForHelpers` is your host's data policy, not a model judgment. `select` receives a frozen
1457
+ copy of `conversationOnly` from before the creation call. System instructions, tool calls,
1458
+ tool results, private reasoning and provider-owned fields have already been removed. User text,
1459
+ attachments and assistant text can still be private; select only messages this helper may read.
1460
+ Return their indices in increasing order. The model cannot supply indices or a filter.
1461
+
1462
+ Both bounds are required: up to 1,024 messages and 1,000,000 UTF-8 JSON bytes of selected history.
1463
+ Too much data fails closed; it is not silently cut. The SDK saves the selected indices and exact
1464
+ history before the helper runs. Replay uses that record without calling `select` again and
1465
+ refuses changed source messages or history. Change `identity` when your filter changes.
1466
+ The template supplies the system instructions, just as for a task-only helper. A fork never
1467
+ adds tools, copies an approval or changes memory scope. References still use `host.loadMedia`.
1468
+
1469
+ ### Send a follow-up to the same helper
1470
+
1471
+ Set `followUp: true` on the creation tool. A completed result includes an opaque `helperId`.
1472
+ The model can then call the same tool with:
1473
+
1474
+ ```ts
1475
+ {
1476
+ agents: [{ name: "reads", continues: helperId, task: "Give one search example." }];
1477
+ }
1478
+ ```
1479
+
1480
+ `helperId` comes from the earlier result. A guessed name, a run id or an id from another root,
1481
+ creator or creation tool is refused. Only a completed helper with settled operations can receive
1482
+ a follow-up. A suspended helper needs its explicit request answers through `resume`; a failed,
1483
+ cancelled or interrupted helper cannot be restarted through `continues`.
1484
+
1485
+ Pass only `name`, `task` and `continues`. Instructions, tools, model settings and limits stay as
1486
+ admitted. `prepare` may rewrite the new task or refuse it, not change that definition. The new
1487
+ child reads the latest completed conversation, including settled tool rounds, without invoking
1488
+ those tools again. Its provider session id stays the original helper's run id. It never loads
1489
+ or appends an application session, and does not carry prior approvals into new operations.
1490
+ Each follow-up has its own run and operation ids, so accounting does not count earlier work twice.
1491
+
1492
+ Forks and follow-ups require `host.beforeTool`. Check the authenticated owner, current access
1493
+ and the root's execution lease there. The SDK rechecks current tool-selection policy and memory
1494
+ access revisions before using earlier history. A revoked grant, changed template or inaccessible
1495
+ memory fails closed. Model-written prose cannot approve these checks or choose another scope.
1496
+ For stored runs, keep the existing `authorizeResume` check and exclude concurrent root attempts.
1497
+ A stored helper id is a reference, not permission to run arbitrary saved work.
1498
+
1499
+ Two follow-ups to one helper in a batch are refused before admission. Separate calls execute
1500
+ serially and use the latest settled turn. There is no second conversation store or background
1501
+ scheduler. Each new follow-up consumes another child slot and `maxPerRun` admission, uses the
1502
+ same local limits, and shares the root's model-call, tool serialization and time boundaries.
1503
+ Neither a new turn nor an approval wait resets the root deadline.
1504
+
1505
+ ### Bound helper creation
1506
+
1507
+ Defaults are `maxPerCall: 4`, `maxPerRun: 8` and `maxLevels: 1`. Set `maxPerRun: 0` to refuse
1508
+ creation. Counts must be whole numbers up to 1,024. Only `maxPerRun` accepts zero. The entire
1509
+ model-supplied batch must fit in 65,536 UTF-8 JSON bytes (`SUBAGENT_SPEC_BYTES`). Unknown fields,
1510
+ unknown aliases, repeated names and oversized batches are refused before any child starts.
1511
+
1512
+ Recursive creation needs `maxLevels` greater than one, and the helper must receive this same
1513
+ creation tool in its `tools` list. Every ancestor's creation ceiling still applies. Root
1514
+ `treeLimits` always bound depth, total children, model calls, parallel work and elapsed time.
1515
+ A preflight shortage of child slots returns tool feedback. A racing admission can still reach
1516
+ the tree's hard limit. Waiting or resuming never refreshes a budget.
1517
+
1518
+ `models` maps aliases to `{ description, settings }`. The host writes these settings; the model
1519
+ only selects a key. Choices cannot set `hostedTools`, `toolChoice` or observer callbacks. The
1520
+ template owns its provider and hosted capabilities. Hidden provider changes require a version
1521
+ change, as with other agents. Hosted calls still cannot replay after an interruption.
1522
+
1523
+ Optional `prepare(draft, context)` is trusted, pure admission policy. It may rewrite the task
1524
+ or instructions, remove requested tools, lower `limits`, or return `{ refuse: "Reason" }`.
1525
+ It cannot change the name or model alias, add tools the model did not request or raise the
1526
+ template's limits. Invalid or thrown policy results fail closed. The context contains the
1527
+ private `call`, child `depth`, created-helper `level`, `grantable` names and cancellation `signal`.
1528
+ One prepared definition must also fit in 65,536 UTF-8 JSON bytes.
1529
+
1530
+ ### Saved work and permissions
1531
+
1532
+ The admitted definition, template configuration, model choice and task are saved in the ordinary
1533
+ child journal before execution. Resume uses that record, never another model call to recreate
1534
+ the helper. It refuses changed definitions, revoked tools or model aliases, and changed approved
1535
+ arguments after admission. Completed children are reused. `prepare` never runs again for an
1536
+ admitted child; it can run again for a helper that was refused or not yet saved. Keep effects
1537
+ out of it. Bump the relevant agent version when callback code or hidden provider behavior changes.
1538
+
1539
+ All template guards, lifecycle hooks, result checks, tool serialization and usage accounting
1540
+ still apply. `needsApproval: true` on `subagentTool` gates the creation call only. Each helper's
1541
+ own approvals, questions and client results stay in its own request journal. They reach the
1542
+ host through the normal request paths. `ToolRequest.subagent` carries the private model-written
1543
+ name so host policy can recognize created helpers; it is not an authorization claim.
1544
+ `beforeTool` must still check current access immediately before every action, including after
1545
+ resume. A saved allowlist is not current permission.
1546
+
1547
+ A helper's own model/result failure or local limit becomes a `failed` result for the parent.
1548
+ Suspension, cancellation, tree-wide limits, guard failures and host/journal failures keep their
1549
+ existing stopping behavior. Results are `{ name, helperId, runId, status: "completed", output }`,
1550
+ `{ name, helperId, runId, status: "failed", error }` or `{ name, status: "refused", error }`.
1551
+ `output` is the template's checked, JSON-serializable candidate, not a validator's transformed
1552
+ application object. `summarize(results)` is an optional pure callback; by default, the parent
1553
+ gets JSON in declaration order. The tool succeeds when at least one helper completes.
1554
+
1555
+ The private record lives at `delegations[].children[].snapshot.subagent`. Its `identity` binds the
1556
+ opaque id to the root, creator and original helper run. A follow-up records `previousRunId`;
1557
+ a fork records its selected indices. Earlier helper records without these identity and policy
1558
+ fields are refused, not converted. The existing `child`
1559
+ event adds only `subagent: true`; its key is positional (`helper-1`, for example), and its agent
1560
+ id belongs to the host template. It carries no model-written name, instructions or task. Display
1561
+ helpers under a host-written label. Only expose a model-written name or output after your own
1562
+ explicit display check. Raw tool events, snapshots and request records still contain private
1563
+ prompts and must stay on the server.
1564
+
1565
+ See [the offline helper example](examples/subagents.ts). It creates two helpers, shares approved
1566
+ history with one and sends it a follow-up. It needs no API key.
1567
+
1568
+ ## Hand off a conversation
1569
+
1570
+ A handoff lets another agent answer the person. The source makes no further model call after the
1571
+ target starts. For example, a help agent can transfer an invoice question to a billing agent:
1572
+
1573
+ ```ts
1574
+ const result = await help.run("Why was I charged twice?");
1575
+ ```
1576
+
1577
+ Register one fixed target per handoff tool:
1578
+
1579
+ ```ts
1580
+ import { defineAgent, defineHandoff } from "@providerkit/agents";
1581
+
1582
+ const help = defineAgent({
1583
+ id: "help",
1584
+ version: "1",
1585
+ instructions: "For billing questions, call transfer_to_billing alone and stop.",
1586
+ provider,
1587
+ tools: [
1588
+ defineHandoff({
1589
+ name: "transfer_to_billing",
1590
+ description: "Let billing answer a question about an invoice or charge.",
1591
+ to: billing,
1592
+ }),
1593
+ ],
1594
+ });
1595
+ ```
1596
+
1597
+ The model can pass `{ note: "Background for billing" }` or `{}`. It cannot choose an agent name,
1598
+ add tools or grant access. The note is quoted background in a user-role transfer message, never
1599
+ a system instruction or permission. `beforeTool` and the request journal still control actions.
1600
+ The target resolves its own instructions, provider settings and enabled tools once. It does not
1601
+ inherit source overrides. Either agent may use text or a checked `output` contract. The target
1602
+ validates its own result, including after resume. The source never checks that result against
1603
+ its own schema or asks a model to rewrite it.
1604
+
1605
+ `defineAgent` infers the union of its own output and every registered handoff target's output,
1606
+ including further handoffs. A text agent that can transfer to an `Agent<{ count: number }>` returns
1607
+ `RunOutcome<string | { count: number }>`. Two checked agents with different schemas return the
1608
+ union of those two types, without adding `string`. An agent without handoffs keeps its original
1609
+ output type. Ordinary delegations do not widen their parent's output.
1610
+
1611
+ Check `status`, then narrow the output by its value or by a tag your validators return:
1612
+
1613
+ ```ts
1614
+ const result = await help.run("Count open invoices.");
1615
+ if (result.status === "completed") {
1616
+ if (typeof result.output === "string") console.log(result.output);
1617
+ else console.log(result.output.count);
1618
+ }
1619
+ ```
1620
+
1621
+ This example assumes `help` has text output and a counter target. `activeAgent` names the owner;
1622
+ its id does not narrow the output's TypeScript type. Keep a tag such as `kind` in distinct object
1623
+ outputs when you need that distinction. See [the offline typed example](examples/structured-handoff.ts)
1624
+ for two different checked schemas and resume, with no casts.
1625
+
1626
+ `Handoff<T>` and `HandoffSpec<T>` retain their target's output type. Keep that generic in helpers
1627
+ instead of annotating a descriptor as bare `Handoff`, which forgets the output type. Let
1628
+ `defineAgent` infer its tools. For a cyclic graph, annotate one agent with the full output union,
1629
+ for example `Agent<InvoiceCount | Summary>`. If you annotate a definition, `AgentDefinition<T, H>`
1630
+ separates its own output `T` from the handoff output union `H` (default `never`). A definition whose
1631
+ `output` is optional also allows text results.
1632
+
1633
+ A handoff must be the only call in its model turn. Mixed calls, two transfers, a self target,
1634
+ a missing target or conflicting definitions for one target id produce tool feedback. Other
1635
+ calls in a mixed turn still settle or ask for approval. The model can then request a lone
1636
+ handoff. Each admitted target uses the existing child host hook, shared leases and limits. Each
1637
+ hop consumes one child and one depth level, so cycles stop at the configured tree limit. Waiting
1638
+ for replies does not reset any deadline or model budget.
1639
+
1640
+ ### Choose what the target reads
1641
+
1642
+ `history` on `defineHandoff` controls transfer:
1643
+
1644
+ - `"conversation"` (default) keeps user messages and non-empty assistant text. It removes tool
1645
+ calls, results, private reasoning and provider-owned fields.
1646
+ - `"full"` keeps the settled conversation, including tool rounds and provider-private fields.
1647
+ Use it only with trusted history and compatible providers.
1648
+ - A pure function receives `{ from, to, messages, note? }` and returns the messages to transfer.
1649
+ Its input is frozen. It cannot insert a system message. The SDK validates its result like a
1650
+ trusted child input, then saves it with that child.
1651
+
1652
+ Every mode excludes the source system prompt and the current unfinished handoff round. The
1653
+ SDK appends its transfer message after the selected history. Media references remain references;
1654
+ `host.loadMedia` still checks access. The filter is not called again for a saved child. As with
1655
+ other creation callbacks, a crash before the first child checkpoint can call it again.
1656
+
1657
+ `conversationOnly(messages)` exports the default filter for host-directed routing. It is a
1658
+ model-input filter, not a browser display policy.
1659
+
1660
+ ### Continue or resume
1661
+
1662
+ Every outcome returns `activeAgent: { id, version }` and ordered `handoffs` receipts. The last
1663
+ admitted target owns the next turn, even when it failed or is waiting for replies. A handoff
1664
+ inside a delegated specialist changes that child's owner only, not the root's owner.
1665
+
1666
+ For a **new turn**, the host picks the registered agent by both identity fields:
1667
+
1668
+ ```ts
1669
+ const nextAgent = agents.find(
1670
+ (agent) => agent.id === result.activeAgent.id && agent.version === result.activeAgent.version,
1671
+ );
1672
+ if (!nextAgent) {
1673
+ throw new Error("Restore the saved agent version before continuing this conversation.");
1674
+ }
1675
+ await nextAgent.run({
1676
+ messages: [...result.history, { role: "user", content: "Which invoice was that?" }],
1677
+ });
1678
+ ```
1679
+
1680
+ `history` is the active agent's settled conversation, including the SDK's transfer message. It
1681
+ is server data, not a display transcript. `newMessages` retains the original new turn and settled
1682
+ rounds along the handoff chain, without copied history or synthetic transfer inputs. A session
1683
+ appends those messages under the original run id and revision, once. Sessions do not store the
1684
+ active agent: save that identity in your host. When routing a new session turn to another agent,
1685
+ choose a history policy explicitly, such as `prepareHistory: conversationOnly`.
1686
+
1687
+ For a **waiting or interrupted run**, resume the agent that started it, using its original
1688
+ snapshot and the normal `answers` map. Requests from every target retain their exact call and
1689
+ child path. Partial replies preserve the remaining requests and completed work. An approved
1690
+ transfer does not approve any target tool. A host may allow edits to the note before the target
1691
+ starts. Changing it after admission fails with `handoff_input_changed`; reconcile the saved run
1692
+ before starting different work. Denying a renewed transfer approval after its target
1693
+ started stops that conversation; it cannot undo completed actions or return to a source model
1694
+ turn. A saved completed target is reused, never called again. Its raw candidate stays in its child
1695
+ snapshot and in the source's completed state; only the owning target's pure validator rebuilds
1696
+ the returned value. A failed target validation returns tool feedback to that target's loop. It
1697
+ cannot become source-schema success; if the target cannot finish, the source returns its failure
1698
+ or limit. Safe recovery remains opt-in; configured hosted tools still block interrupted model replay.
1699
+
1700
+ For cycles, `to: () => billing` lets two definitions reference each other. Keep this function
1701
+ pure. It resolves once per handoff descriptor. After a restart, a different target id or version
1702
+ is refused, including while the transfer itself waits for approval. Bump the source version when
1703
+ its registered handoffs or history policy change.
1704
+
1705
+ Each journal entry has `kind: "delegation" | "handoff"`; a handoff also records `target` and its
1706
+ optional note. Child snapshots stay at `delegations[].children[].snapshot`. Saved delegation
1707
+ entries without `kind` are refused. Operation receipts also distinguish `"handoff"`. A
1708
+ `handoff` event names `runId`, `operationId`, `childRunId`, `from` and `to` before target progress;
1709
+ it also carries `attemptId` and the optional note. It repeats on target resume, so upsert by
1710
+ operation id. Snapshots and receipts remain authoritative if an event is missed. Do not forward
1711
+ raw histories, notes or events to a browser. Project only approved identities, labels and content.
1712
+
1713
+ ## Limits and usage
1714
+
1715
+ Per-run defaults are 12 model turns, 32 tool calls, 5 minutes, at most 3 approved concurrent
1716
+ ordinary tools and 5 MB (`inlineBytes: 5_000_000`) of inline images and files. Change these
1717
+ through `limits` when configuring an agent. Once a text agent uses all its model turns, it gets
1718
+ one final call with no tools to answer from what it found. That call still counts against the
1719
+ tree's model-call and time budgets. Any tool calls it returns are refused. Checked-output agents
1720
+ keep the hard turn cap because a tool-free call cannot submit their result.
1721
+
1722
+ The root's `treeLimits` apply across all descendants:
1723
+
1724
+ | Setting | Default | Counts |
1725
+ | ------------- | ------- | --------------------------------------------------------------------------------- |
1726
+ | `maxParallel` | 4 | Active agents, including the root. A parent waiting on children lends its slot. |
1727
+ | `maxChildren` | 32 | Children in total, not per parent. |
1728
+ | `maxDepth` | 4 | Descendant levels; the root is depth 0. |
1729
+ | `modelCalls` | 128 | Calls from agent loops to core. Provider-internal retries can send more requests. |
1730
+ | `elapsedMs` | 300000 | Wall time, including queueing and waiting for approval, across attempts. |
1731
+
1732
+ A child's local limits still apply. Set enough time for a human decision when using approval.
1733
+ Resuming does not reset the deadline or give the tree a fresh call budget.
1734
+
1735
+ `usage` describes the current agent's model calls. `treeUsage` includes registered descendants
1736
+ without counting recorded work twice. Only model usage reported by providers is known; an
1737
+ interrupted call may have cost more than its last report. Ordinary tools' external service charges
1738
+ are not included. Prices and billing stay with the host, and these counters are not an exact
1739
+ spending cap. Use SDK delegation rather than calling another model directly inside an ordinary
1740
+ tool when that work must share the tree's limits and usage.
1741
+
1742
+ ## Asking the person
1743
+
1744
+ A suspended run returns `requests`, including requests from its specialists. Each has a stable
1745
+ `id`, the exact call and child `path`, the tool definition's hash, and a host-supplied actor,
1746
+ resource version and expiry. Approvals, questions and client tools use the same tool journal.
1747
+ The SDK saves a request before reporting it. It saves each accepted decision before any effect.
1748
+
1749
+ Reply by request id, using the snapshot your server stored:
1750
+
1751
+ ```ts
1752
+ await writer.resume(savedSnapshot, {
1753
+ host,
1754
+ answers: { [requestId]: authenticatedEvidence },
1755
+ });
1756
+ ```
1757
+
1758
+ `answers` is evidence, not permission. Never accept a browser's snapshot as authority.
1759
+ `host.authorizeResume` must load authoritative state, check ownership and exclude concurrent
1760
+ attempts. It runs for every node, including specialists. Unknown, closed and already-decided
1761
+ request ids are refused before host callbacks. HTTP hosts must also reject duplicate keys in
1762
+ raw JSON before parsing an answer map.
1763
+
1764
+ The host supplies these callbacks:
1765
+
1766
+ - `prepareRequest(draft)` returns `{ scope }`: the actor id, resource id and version, and a future
1767
+ `expiresAt` in milliseconds. For approvals it can also return `ask` to set the message,
1768
+ `editable`, `approveSchema` or `denySchema`. Editing is off by default.
1769
+ - `resolveRequest(request, evidence)` authenticates and consumes evidence for that exact request.
1770
+ It returns a `Decision`, or `{ type: "pending", problem? }` when the request is still open.
1771
+ Validate any form data against the host's schema here, before accepting it.
1772
+ - `beforeTool(call, decided?)` checks current access and resource version immediately before
1773
+ execution. `call.arguments` holds the arguments that will run. `decided` holds `{ request,
1774
+ decision }`; a saved decision cannot bypass this check. The callback is required when using
1775
+ an answer and before exposing a client-tool request.
1776
+ - Optional `needsApproval(call)` requires approval even for an unmarked tool. It cannot waive
1777
+ a tool's own `needsApproval` flag. Optional `answerNow(request)` returns a standing policy
1778
+ decision, or `undefined` to ask the person. This is trusted policy, not model output.
1779
+
1780
+ A `Decision` is one of:
1781
+
1782
+ | Type | Value and result |
1783
+ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
1784
+ | `approve` | Runs the approved call. Optional `arguments` replace all model arguments, only when `editable` is true. The tool's validator still checks them. |
1785
+ | `deny` | Does not run the call. Its optional `message` becomes the tool result. |
1786
+ | `answer` | Supplies `{ answer: { choices?, text?, data? } }` to a question. |
1787
+ | `result` | Supplies `{ value }` for a registered client tool. Its result validator must accept it. |
1788
+ | `cancel` | Dismisses the request and returns a cancelled tool result. Does not undo an action already taken. |
1789
+ | `stop` | Cancels the run tree and closes its open requests. Does not undo past effects. |
1790
+
1791
+ Each decision may carry an opaque `receipt`. An approval or denial may carry `data` only when
1792
+ its corresponding schema was declared. Form schemas describe what to show; the SDK does not
1793
+ ship a JSON Schema evaluator. Your host must validate their data. Wrong kinds, forbidden edits,
1794
+ unknown or repeated choices, disallowed text and blank answers stay pending with a `problem`.
1795
+ Invalid edited arguments become a failed tool result without executing the tool.
1796
+
1797
+ You may answer a subset. All approval-required calls remaining in a turn open together, within
1798
+ the tool budget. A later call waits behind an earlier open request. Specialists can wait on
1799
+ several requests at once; answering one keeps the other requests and completed work intact.
1800
+ Usage and admissions do not reset. Cancelling a coordinator's question also stops its unfinished
1801
+ children; settled children remain. Progress includes `request` and `decision` events, but these
1802
+ can be missed: the journal is the durable record.
1803
+
1804
+ An expired approval or question is replaced under a new id and fresh host scope. A changed tool
1805
+ definition does the same. Old evidence never answers the replacement. Replacements need a fresh
1806
+ answer through `resolveRequest`, not another automatic `answerNow` decision. Access and expiry are
1807
+ checked again before an effect, including after the tool-start observer.
1808
+
1809
+ ### Questions and forms
1810
+
1811
+ Give the model `questionTool()` to ask for text or choices:
1812
+
1813
+ ```ts
1814
+ import { questionTool } from "@providerkit/agents";
1815
+
1816
+ const questions = questionTool();
1817
+ ```
1818
+
1819
+ Put `questions` in the agent's `tools`. Its `ask_question` call takes `message`, optional
1820
+ `choices` (`id`, `label`, optional `description`), `multiple` and `freeText`. An answer chooses
1821
+ only offered ids, with no duplicates, and one at most unless `multiple` is true. The answer
1822
+ becomes the tool result, not an instruction with tool authority.
1823
+
1824
+ Pure coordinators can call `context.ask(question, validate)`:
1825
+
1826
+ ```ts
1827
+ const count = await context.ask(
1828
+ { key: "count", message: "How many copies?", schema: countSchema },
1829
+ (answer) => validateCount(answer.data),
1830
+ );
1831
+ ```
1832
+
1833
+ `validateCount` is your pure runtime validator. It returns the typed value or throws. A rejected
1834
+ form opens a new request with the problem. Parallel asks use distinct keys. The coordinator runs
1835
+ again from its start and reads recorded answers by key; its JavaScript stack is not saved. Do not
1836
+ put external effects in it. Catching or ignoring an unanswered `ask` still suspends the run.
1837
+
1838
+ An ordinary core tool may throw `new InputRequired({ key, message, ... })` only at a replay-safe
1839
+ boundary **before every external effect**. On resume the entire tool runs again; use
1840
+ `answerOf(context, key)` to read its saved answer. The SDK supplies frozen `context.answers` and
1841
+ `context.decision`, overriding values with those names in host context. A second question can
1842
+ use another key. Throwing again for an answered key rejects that answer and opens a new request.
1843
+ Never write, send, or make a paid call before throwing: the SDK cannot prove your code was safe.
1844
+
1845
+ ### Client tools
1846
+
1847
+ Register a deferred tool with `defineClientTool({ name, description, inputSchema, validate,
1848
+ result: { schema, validate }, summarize? })` in trusted server code. Its arguments are validated
1849
+ before the request opens. The host exposes only the allowed client request; the client cannot
1850
+ choose a new tool definition or grant itself authority. Return a `result` decision through the
1851
+ same authenticated channel. The registered result validator runs before it is recorded.
1852
+ Validators and summaries must be pure: recovery can call them again. Dispatch with
1853
+ `request.call.arguments`, which includes approved edits. `request.call.call` keeps the original
1854
+ model call for identity checks, not the arguments to execute.
1855
+
1856
+ There is no local `run` callback and no local duplicate execution. A pending client request keeps
1857
+ its id on reconnect, and a resolved one is never sent again. The host must deduplicate client
1858
+ dispatch by request id and recheck access before dispatch. A browser event is not permission.
1859
+ An expired or changed client request fails with `client_result_unknown`, rather than issuing
1860
+ another potentially repeated effect. Reconcile it with the host. An idempotency key alone does
1861
+ not prove that the receiver enforces it.
1862
+
1863
+ ### Checkpoints and recovery
1864
+
1865
+ `host.checkpoint` persists the entire journal before returning. Completed results can be reused.
1866
+ An operation recorded as running has an unknown outcome after a crash. The default is refusal,
1867
+ with `interrupted_operation`, not replay. A model may have run provider-hosted tools even if no
1868
+ tool call appeared in its stream. A tool may have acted before it could report `InputRequired`.
1869
+ Neither an empty stream nor an idempotency key proves that repeating it is safe.
1870
+
1871
+ #### Opt in to safe replay
1872
+
1873
+ For a provider profile you know performs inference only, configure recovery before starting:
1874
+
1875
+ ```ts
1876
+ const reader = defineAgent({
1877
+ id: "reader",
1878
+ version: "1",
1879
+ instructions: "Read the records you need, then answer.",
1880
+ provider,
1881
+ tools: [lookup],
1882
+ recovery: {
1883
+ identity: "inference-and-lookup-v1",
1884
+ maxAttempts: 3,
1885
+ inferenceOnly: true,
1886
+ readOnlyTools: ["lookup"],
1887
+ },
1888
+ });
1889
+ ```
1890
+
1891
+ `inferenceOnly: true` is your host's assertion about the configured provider, including its
1892
+ wrappers and defaults. Never set it for provider-hosted search, code execution or any other
1893
+ remote tool. An interrupted call with a non-empty recorded `modelSettings.hostedTools` list is
1894
+ refused even if this flag is set. Leave it out to refuse interrupted model calls. `readOnlyTools`
1895
+ is an explicit allow-list, not a tool hint: each named tool must also have `isReadOnly: true`. A replay requires
1896
+ `host.beforeTool`, which checks access again before invocation. Read-only does not mean free:
1897
+ a repeated request can incur another charge or return newer data.
1898
+
1899
+ Calls with any approval, question or client-request history cannot replay under this policy.
1900
+ A decision for a previous attempt is never permission to repeat an unknown effect. Client tools,
1901
+ writes and hosted effects require authoritative host reconciliation. There is no force-replay
1902
+ switch. Do not restart the whole run as a substitute: that repeats completed work too.
1903
+
1904
+ The policy is saved in `snapshot.definition.recovery`, together with the provider id/model and
1905
+ hashes of advertised tools and permitted read-only definitions. Resume checks the same policy
1906
+ and provider identity; replay checks the tool definitions. Resolved instructions, model settings
1907
+ and enabled tools stay frozen. Change `identity` when hidden provider defaults, hosted
1908
+ capabilities or tool implementations change. The SDK cannot inspect code inside a provider
1909
+ wrapper or prove that a receiver enforces an idempotency key.
1910
+
1911
+ Recovery repeats only the interrupted operation. It keeps that operation's `id` and changes its
1912
+ `attemptId`. Completed siblings and tools are reused. `maxAttempts` includes the first attempt;
1913
+ when used up, the run fails with `recovery_exhausted`. A reserved attempt counts even if the
1914
+ worker died before sending it. Each new model attempt consumes a tree `modelCalls` admission.
1915
+ Each new tool attempt consumes a local `toolCalls` admission. Neither retries nor observation
1916
+ reset counters, local deadlines or the tree deadline. Retries replace the same logical turn;
1917
+ they do not grant another tool-capable turn. Settled failures and cancelled runs are not retried.
1918
+
1919
+ Each model/tool journal entry has an `interrupted` array. Model entries retain the last measured
1920
+ usage for every interrupted attempt, and usage updates are checkpointed before reading more
1921
+ chunks. `usage` and `treeUsage` include every attempt once. Outcome `receipts` contains one entry
1922
+ per attempt: key billing by `(id, attemptId)`, not just `id`. Model receipts have
1923
+ `billing: "unknown"` while running or interrupted, and `"reported"` once a stream with a usage
1924
+ report completes. A completed stream without usage stays `"unknown"`. Reported is not an audited
1925
+ bill. A process can die before saving a new usage report, and an
1926
+ interrupted request may cost more than its saved usage. Ordinary tool charges remain unknown.
1927
+
1928
+ Before replacement output, `operation_restart` reports `kind`, `runId`, `operationId`,
1929
+ `previousAttemptId` and `attemptId`. A display projector must clear the interrupted attempt's
1930
+ partial text before applying the replacement, not append to it. Keep the operation's row.
1931
+ `model_chunk.attemptId` and the snapshot's current attempt also identify the replacement if the
1932
+ best-effort restart event is missed. Reading or reconnecting an observer never starts a retry;
1933
+ only an authorized executor holding the host's lease may resume. Partial text is not durable in
1934
+ the execution journal. This policy does not add event batching or awaited event storage.
1935
+
1936
+ The host's decision store must insert requests once, move pending requests to one decision,
1937
+ and reserve a submitted batch atomically. A crash can occur after evidence is consumed but before
1938
+ the decision checkpoint. Resolving the same authorized claim must return the same decision;
1939
+ another claim, segment, actor or resource version must be refused. No in-memory boolean can
1940
+ provide that guarantee across a restart.
1941
+
1942
+ Snapshots and raw events hold private prompts, arguments and answers. Keep them on the server
1943
+ and build an allowlisted display view. Question text and choices may come from the model: treat
1944
+ them as untrusted display content. Snapshot format 3 includes resolved recovery policy and
1945
+ per-operation attempt histories, an `inputs` journal, a `guards` journal and a `compactions` journal
1946
+ on every node. Each tool entry requires `retries`, including an empty list when unused.
1947
+ Its definition includes `guardrails`, `compaction` and `toolRetries` (null when unused). Checked `submit_result` receipts keep
1948
+ `final.candidate`, just as stopping tools do, rather than reconstructing it from model arguments.
1949
+ Older formats, earlier format-3 shapes without those fields and the old single-approval state are
1950
+ refused, not converted.
1951
+
1952
+ ### Retry a failed tool call
1953
+
1954
+ Ordinary tool failures still return to the model as data. There is no automatic retry by default.
1955
+ To allow bounded retries of one registered read-only tool:
1956
+
1957
+ ```ts
1958
+ const reader = defineAgent({
1959
+ id: "reader",
1960
+ version: "1",
1961
+ instructions: "Read the records and answer.",
1962
+ provider,
1963
+ tools: [lookup],
1964
+ toolRetries: {
1965
+ identity: "lookup-retries-1",
1966
+ tools: { lookup: { maxAttempts: 2, replay: "read-only" } },
1967
+ },
1968
+ });
1969
+ ```
1970
+
1971
+ `lookup` must have `isReadOnly: true`, and the run must supply `host.beforeTool`. A retry checks
1972
+ current access again, after its input guard and start hook. Read-only is not free: each attempt
1973
+ may incur another charge or return newer data. Attempts consume `limits.toolCalls`, share the
1974
+ tree's tool serialization and keep the original deadlines. They do not buy another model turn.
1975
+
1976
+ `maxAttempts` includes the first attempt and crash recovery attempts for that operation. Only
1977
+ `failed` and `timeout` tool outcomes qualify. Invalid arguments or output need correction, not
1978
+ another identical call. When the budget ends, the last failure returns to the model. A new model
1979
+ call to the same tool is a new operation, still bounded by the run's tool and model limits.
1980
+
1981
+ For a write, use `replay: "reconcile"` and supply `host.reconcileToolRetry(attempt, context)`.
1982
+ The callback receives the exact failed `request` and `result`. It must query authoritative host
1983
+ or service state, not dispatch work. Return `{ outcome: "not_run", receipt }` only after confirming
1984
+ that this attempt did not run **and cannot still complete**. Return `{ outcome: "unknown" }`
1985
+ otherwise. Missing or uncertain reconciliation stops the run with `tool_retry_unsafe`. A timeout,
1986
+ an error string saying "nothing happened" or an idempotency key does not prove safety.
1987
+ For background runs, supply the same callback as `policy.reconcileToolRetry`;
1988
+ it runs under the existing worker signal and checkpoint barriers.
1989
+
1990
+ Retries keep the same operation and arguments but get a distinct `attemptId`. Every failed attempt
1991
+ stays in `tools[].retries`, with its arguments, result and any reconciliation receipt. Outcome
1992
+ `receipts` retains each attempt. The failed result is saved before reconciliation, and its receipt
1993
+ is saved before another attempt is admitted. Resume checks current authorization again without
1994
+ repeating a saved reconciliation. A running retry still has an unknown outcome after a crash:
1995
+ only the existing read-only recovery policy can replay it. Interrupted writes remain refused.
1996
+
1997
+ Client tools, delegations, handoffs, stopping tools and tools requiring approval cannot be named
1998
+ in this policy. A call with any approval or question history never uses it, including a call with
1999
+ edited arguments. A new approval requirement, Stop, guard rejection, lease loss or failed progress
2000
+ write cannot become a retry. Calls configured for retry run serially within their agent. Change
2001
+ `toolRetries.identity` when the implementation or hidden effect policy changes; definitions and
2002
+ policy are checked against the saved run.
2003
+
2004
+ ## Background runs
2005
+
2006
+ `@providerkit/agents/runs` binds an agent to `@gusnips/server/runs` 0.19, 0.20 or 0.21.
2007
+ Awaited progress needs 0.21. Install that optional peer only when using this entry. Supply your
2008
+ existing run service, durable queue callback and trusted policy factory:
2009
+
2010
+ ```ts
2011
+ import { createBackgroundAgent } from "@providerkit/agents/runs";
2012
+
2013
+ const jobs = createBackgroundAgent({
2014
+ agent: writer,
2015
+ kind: "writer-v1",
2016
+ runs,
2017
+ enqueue,
2018
+ policy,
2019
+ });
2020
+
2021
+ const { id } = await jobs.start(authenticatedOwner, "Write a release note.");
2022
+ const saved = await jobs.wait(authenticatedOwner, id);
2023
+ ```
2024
+
2025
+ The owner must come from your authentication code, not an unchecked request field. Reads,
2026
+ observation, waiting, cancellation and resume all require it. A worker calls
2027
+ `runs.drive(id, jobs.handlers)`. Run `runs.sweep` on boot and periodically to queue unfinished work,
2028
+ and call `runs.drain` before shutting down. See [the background example](examples/background.ts)
2029
+ for these connections. A stored job without a worker and recovery sweep does not run itself.
2030
+
2031
+ `start` saves the input before returning an ID. If queueing fails, `BackgroundEnqueueError.id`
2032
+ identifies the saved run. Requeue that ID or let the sweep find it; do not create another run.
2033
+
2034
+ You can inject `runs.create` to save the run and your own records in one transaction. It must
2035
+ resolve only after commit, not from inside an uncommitted outer transaction. The SDK calls
2036
+ `enqueue` afterward. A rollback must reject creation, so nothing is queued. Never keep that
2037
+ transaction open through model or tool execution. The host owns its transaction client and
2038
+ must reconcile an unknown commit before trying creation again.
2039
+
2040
+ `start` takes the same input as `run`. For a conversation, pass a session factory and the
2041
+ conversation's id:
2042
+
2043
+ ```ts
2044
+ const jobs = createBackgroundAgent({
2045
+ agent: writer,
2046
+ kind: "writer-v1",
2047
+ runs,
2048
+ enqueue,
2049
+ policy,
2050
+ session: openConversation,
2051
+ });
2052
+ const { id } = await jobs.start(authenticatedOwner, "Add a section on costs.", { sessionId });
2053
+ ```
2054
+
2055
+ `openConversation(owner, id)` is your trusted code, and returns a `Session`. It must check that
2056
+ the owner may use that conversation: an id from a request is not authorization. `start` reads the history inside the authenticated
2057
+ request and freezes it in the saved run. The worker gets the session again from the factory, with
2058
+ the stored owner, and appends the turn when the run settles; `saved.outcome.session` says whether
2059
+ that worked. `historyLimit` and `prepareHistory` on `createBackgroundAgent` apply in `start`.
2060
+ Media references are read in the worker through `policy.loadMedia`.
2061
+
2062
+ `start` also takes `context`, `modelSettings` and `enabledTools`. Build these in trusted server
2063
+ code. Context is available to the definition callbacks while `start` runs, but is not stored.
2064
+ Only the resolved definition is saved. The worker's tools get fresh context from `policy.context`.
2065
+ Background `start` refuses model-setting observers because functions cannot survive the queue.
2066
+ Put them on the agent instead.
2067
+
2068
+ `read` and `wait` return two statuses. `saved.status` describes the host worker run;
2069
+ `saved.outcome?.status` describes the agent. A successful worker run can contain a suspended or
2070
+ failed agent outcome. Read the latter before treating the answer as complete. `saved.snapshot`
2071
+ holds the whole conversation: keep it, and every raw event `observe` yields, on the server.
2072
+
2073
+ Pass an observer signal to `observe` or `wait` to stop listening. That does not cancel the work.
2074
+ `cancel(owner, id)` returns `{ id, requested }`. Follow that physical ID: `requested: true`
2075
+ means the command was accepted, not that execution stopped. Children run in-process under the
2076
+ root's lease. Local cancellation never sends a remote A2A `CancelTask`.
2077
+
2078
+ A successful host row can hold a suspended logical run. To cancel it, supply the optional
2079
+ `createContinuation` callback. It receives `BackgroundContinuationInput`:
2080
+ `{ kind, owner, restart: "resume", input: { format: 1, snapshot, continuation } }` and returns
2081
+ `BackgroundContinuationResult`, `{ id }`. In one transaction, authenticate the owner, check the
2082
+ current source and create or reconcile `(owner, continuation.sourceId, continuation.id)`.
2083
+ Store the exact input and commit before returning the same physical ID. Refuse a changed input
2084
+ or competing claim. The cancellation claim is stable; the worker still checks and claims it
2085
+ under its lease. Do not replace this transaction with a process-local cache or an idempotency flag.
2086
+
2087
+ Without this capability, suspended cancellation refuses before creating or queueing anything.
2088
+ Running-row cancellation and users who do not cancel suspensions need no extra setup. When
2089
+ supplied, the callback also admits answer/wake continuations. An uncertain callback response
2090
+ must reconcile the same claim; do not create a second row. An enqueue failure exposes the saved
2091
+ ID through `BackgroundEnqueueError`. A second Stop on the cancellation segment follows it
2092
+ without aborting the worker that must save the cancelled outcome.
2093
+
2094
+ `start` can take a logical `runId`. The policy context contains that ID and the physical
2095
+ `segmentId`. `onSegment` is awaited at start and after the SDK journal settles, with the owner,
2096
+ physical ID, logical ID, state, private snapshot and live worker signal. It may repeat after
2097
+ worker loss. End is not proof that the host committed its row. A cancellation continuation
2098
+ keeps that worker signal live and passes a separate aborted signal to SDK execution.
2099
+
2100
+ ### Stored progress
2101
+
2102
+ Background storage merges adjacent text or reasoning deltas from the same run, operation and
2103
+ attempt. Only single-field text deltas with the same provider source merge. Tool calls, usage,
2104
+ signatures, other payloads and boundary events stay separate. Raw `onEvent` callbacks on portable
2105
+ runs still receive every original event, without waiting for storage.
2106
+
2107
+ By default, `events: "best-effort"` sends these records through `Run.emit`. The SDK flushes its
2108
+ buffer after 100 ms, at a boundary event, at a checkpoint and before returning an outcome.
2109
+ This does not await database writes: storage failures still go to the host's `onError`. Older
2110
+ server minors remain valid, and this mode cannot bound the host's own unacknowledged emit queue.
2111
+
2112
+ To await storage, set the option when binding the agent:
2113
+
2114
+ ```ts
2115
+ const jobs = createBackgroundAgent({
2116
+ agent: writer,
2117
+ kind: "writer-v1",
2118
+ runs,
2119
+ enqueue,
2120
+ policy,
2121
+ events: "awaited",
2122
+ });
2123
+ ```
2124
+
2125
+ The worker requires `Run.append` before any model or tool work. Events are stored in order, with
2126
+ one append in flight. Every journal save waits for earlier progress, and every outcome waits for
2127
+ its final state event, including child outcomes. Input acknowledgement still follows the saved
2128
+ journal. This is not one atomic event-and-checkpoint transaction. A crash between writes can
2129
+ leave events ahead of a checkpoint, or omit a state event emitted after its checkpoint.
2130
+
2131
+ `observe` still yields raw host `RunEvent` rows. Their types are:
2132
+
2133
+ - `agent`: the existing `AgentEvent`, possibly with merged text.
2134
+ - `agent.gap`: `{ dropped, unconfirmed }`. Counts refer to original events before merging.
2135
+ `dropped` means the buffer refused them. `unconfirmed` means an append rejected and may already
2136
+ have stored them. It does not mean they are definitely missing.
2137
+ - `agent.resync`: `{ crashes }`, stored before a recovered worker resumes the agent in awaited mode.
2138
+ - `end`: the host's terminal record, after its handler finishes.
2139
+
2140
+ On a gap or resync, read the saved run and rebuild the display from its journal before applying
2141
+ later events. A gap is not proof that work failed, and an event is not proof that a checkpoint
2142
+ committed. The execution journal remains authoritative. Continue strictly after the last `seq`;
2143
+ the cursor belongs to that physical run id. A request continuation returns a new id and cursor.
2144
+ Observation never replays an effect or starts a model attempt.
2145
+
2146
+ Each buffer holds at most 64 records and 256 KiB of UTF-8 event JSON, counted before merging.
2147
+ There is one waiting buffer and one in-flight batch. Overflow drops a suffix, never reorders it;
2148
+ a new gap record follows that prefix. An oversized event is dropped too. In awaited mode, a
2149
+ rejected append is never resent by the SDK. It tries to append a new uncertainty marker instead.
2150
+ Execution continues only after that marker is stored. If even the marker fails, the worker stops
2151
+ and reports the storage failure. Stop and lease loss also stop writes, without undoing effects.
2152
+ An in-flight append is allowed to settle before cleanup; it is not abandoned or replayed.
2153
+
2154
+ A killed worker can lose the still-buffered tail. The next worker's resync marker tells readers
2155
+ to reload; it cannot count those lost events. A final checkpoint can recover settled output, not
2156
+ every partial token. Raw logs contain private reasoning, tool arguments and results: keep them
2157
+ server-side, apply the host's access and retention rules, and project only safe display data.
2158
+
2159
+ Custom portable hosts can implement `AgentHost.progress` with synchronous `push` and awaited
2160
+ `flush`. `push` accepts a frozen event into bounded storage; `flush` must surface write failures.
2161
+ Unlike `onEvent`, these failures are not ignored. The SDK awaits this hook at every journal-save
2162
+ boundary and final outcome. It supplies no lease or storage of its own.
2163
+
2164
+ ### Background request policy
2165
+
2166
+ The required `policy` factory receives the authoritative owner and host run ID. It provides the
2167
+ same resume and tool checks described above, plus `claimContinuation`. Keep these rules in trusted
2168
+ server code:
2169
+
2170
+ - `authorizeResume` checks stored state and ownership on every attempt.
2171
+ - `prepareRequest` supplies the actor, resource version and request expiry.
2172
+ - `claimContinuation(snapshot, continuation)` checks its required `kind`. For `"answers"`,
2173
+ authenticate `continuation.answers` and atomically reserve every named request for
2174
+ `continuation.id` and this host segment. For `"cancel"`, claim the current source under the
2175
+ owner without granting any pending request. Repeating the exact claim during recovery must
2176
+ succeed; a different claim, segment or resource version must fail.
2177
+ - `resolveRequest` returns each decision only for that claim. `beforeTool` checks current access
2178
+ and resource version again immediately before the action.
2179
+
2180
+ Return database handles or other worker-only tool values through `policy.context`. They are not
2181
+ serialized. Do not put secrets or handles in a saved snapshot.
2182
+
2183
+ `resume(owner, id, answers)` saves a new host run with the same logical agent history. Answer
2184
+ all or some requests by id. It queues evidence, not permission. The worker claims the batch under
2185
+ its lease after the row exists; read or wait on the returned ID to learn whether it was accepted.
2186
+ Recovery skips decisions already in the journal and resolves only still-open ids from that exact
2187
+ batch. It never applies old evidence to a new request. Completed children, usage and pending
2188
+ session state survive partial resolution. The host must store claims durably.
2189
+
2190
+ Expired submissions are refused before queueing. Renew approvals or questions through a trusted
2191
+ portable resume after reconciling stored state; do not submit a new snapshot from the browser.
2192
+
2193
+ This binding stores token-usage receipts, not money. It does not call the run service's additive
2194
+ `spend()` method or claim atomic billing with checkpoints. Account for recorded operations using
2195
+ operation and attempt IDs in your own billing system. Configure `recovery` on each agent that
2196
+ may replay interrupted work; `runs.sweep` and the same leased worker handler resume it without
2197
+ starting another logical run.
2198
+
2199
+ ## Check your agent
2200
+
2201
+ Run a set of checks and get a report:
2202
+
2203
+ ```ts
2204
+ const report = await runEvals(checks);
2205
+ ```
2206
+
2207
+ Import evaluation helpers from `@providerkit/agents/evals`. They run the same agent loop and
2208
+ score its saved journal; they do not replay stored effects.
2209
+
2210
+ This setup uses an offline provider. It sends no network requests:
2211
+
2212
+ ```ts
2213
+ import { defineAgent } from "@providerkit/agents";
2214
+ import { assertReport, exact, runEvals, scriptedProvider } from "@providerkit/agents/evals";
2215
+
2216
+ const checks = {
2217
+ agent: () =>
2218
+ defineAgent({
2219
+ id: "greeting",
2220
+ version: "1",
2221
+ instructions: "Say hello.",
2222
+ provider: scriptedProvider(["Hello"]),
2223
+ }),
2224
+ cases: [{ id: "hello", input: "Hi", expected: "Hello" }],
2225
+ scorers: [exact()],
2226
+ };
2227
+
2228
+ const report = await runEvals(checks);
2229
+ assertReport(report); // Throws if the checks did not pass.
2230
+ ```
2231
+
2232
+ Use `contains`, `schema`, `similarity`, `trajectory`, `toolArguments`, `answeredBy` and the
2233
+ `max*` budget scorers, or supply a custom scorer. `formatReport` returns text;
2234
+ `reportJson` returns JSON, and `compareReports` compares matching cases. Repeats are grouped by
2235
+ source case so a case with more measured repeats does not outweigh another. Failed, skipped,
2236
+ unscored and cancelled work remains counted; missing scores do not become passes.
2237
+
2238
+ A case supplies exactly one of `input`, `turns` or `user`. Multiple turns share a fresh SDK
2239
+ memory session. Supply `resolveAgent` when a handoff changes which registered agent owns the
2240
+ next turn. The [offline example](examples/evals.ts) shows multiple turns, tool mocks and scripted
2241
+ approval answers. From this repository, run it with `bun run agents/examples/evals.ts`.
2242
+
2243
+ Keep scripted answers and tool mocks in `drivers`, separate from stored case data. Answers
2244
+ match the actual request. Select its agent/tool or workflow/step; question keys, original input
2245
+ and child paths can narrow the match. They do not turn model-written text into permission.
2246
+ `stub` replaces both tool execution paths and
2247
+ backend validation; it does not prove that the replaced backend checks work.
2248
+
2249
+ Simulated users need an explicit provider and `allowSimulation: true`. Model judges, including
2250
+ `grounded`, need an explicit provider/rubric and `allowJudge: true`. These make extra provider
2251
+ calls and may cost money. A judge's score is an assessment, not proof that an answer is true.
2252
+ Pass current model and hosted-tool rates yourself. Spending thresholds stop more work from
2253
+ starting; they are not hard financial caps on calls already in flight or on external work that
2254
+ ignores cancellation. Configure SDK limits and use test data for tools that can change records.
2255
+
2256
+ Reports omit inputs, outputs, snapshots, reasons and exception messages by default. Use
2257
+ non-sensitive case IDs: those remain in reports. `includePrivateData` opts the omitted fields
2258
+ in; store and share the result accordingly. Unknown charges stay unknown. `caseFromRun` extracts
2259
+ supported completed runs without executing them, and refuses input timing it cannot reproduce.
2260
+ The resulting golden case contains private run data and needs review before sharing. `createLiveScorer` scores only runs
2261
+ the host explicitly submits; it adds no queue or telemetry. The host owns sampling deduplication,
2262
+ storage and retention.
2263
+
2264
+ `remoteAttempts` contains only remote operation identities, send/cancel actions, status and
2265
+ unknown billing. Remote requests are not counted as local model or tool calls, and unknown
2266
+ charges are not treated as free. Peer endpoints, callbacks and task/context handles stay out of
2267
+ these report records. An accepted cancellation request is not proof that the peer stopped.
2268
+
2269
+ ## Upgrade from 0.1
2270
+
2271
+ Version 0.2 requires `@providerkit/core` 0.33.1 or newer within 0.33. Finish outstanding 0.1 runs
2272
+ before upgrading: stored format-2 snapshots are not accepted by the format-3 runtime.
2273
+
2274
+ The request API replaces the single approval decision with request-keyed answers and host
2275
+ claims. Update your authorization and continuation handlers using [the request contract](#asking-the-person);
2276
+ model or browser data cannot supply those grants. Execution trees now contain `agent`, `workflow`
2277
+ and `remote` nodes. Check `kind` before reading model journals or workflow steps.
2278
+
2279
+ ## Development
2280
+
2281
+ From the repository root, run `bun install` and `bun run build`. Then, from `agents/`:
2282
+
2283
+ ```sh
2284
+ bun run lint
2285
+ bun run typecheck
2286
+ bun run test test/request.test.ts
2287
+ bun run test test/recovery.test.ts
2288
+ bun run test test/lifecycle.test.ts
2289
+ bunx vitest run test/definition.test.ts
2290
+ bunx vitest run test/delegation.test.ts
2291
+ bunx vitest run test/subagents.test.ts
2292
+ bunx vitest run test/memory.test.ts
2293
+ bunx vitest run test/handoff.test.ts
2294
+ bunx vitest run test/structured-handoff.test.ts
2295
+ bunx vitest run test/steering.test.ts
2296
+ bunx vitest run test/input.test.ts
2297
+ bunx vitest run test/session.test.ts
2298
+ bunx vitest run test/extensions.test.ts
2299
+ bunx vitest run test/compaction.test.ts
2300
+ bunx vitest run test/tool-retry.test.ts
2301
+ bun examples/guardrails.ts
2302
+ bun examples/basic.ts
2303
+ bun examples/specialists.ts
2304
+ bun examples/subagents.ts
2305
+ bun examples/memory.ts
2306
+ bun examples/conversation.ts
2307
+ bun examples/handoff.ts
2308
+ bun examples/structured-handoff.ts
2309
+ bun examples/steering.ts
2310
+ ```
2311
+
2312
+ These checks and examples use fake providers and tools. They do not call a live model or any app.
2313
+ The basic example runs a model/tool round. The specialist example runs a manager with two children
2314
+ and returns their notes in order. The conversation example runs two turns on a session, one with
2315
+ a picture sent by reference. The handoff example transfers an invoice question, then routes the
2316
+ next turn to the returned active agent. The structured-handoff example transfers between two
2317
+ checked schemas and restores the target's typed result. The steering example adds a message while a tool works
2318
+ and retains a message sent too late for the model to read. None needs an API key.
2319
+
2320
+ The background integration file needs a disposable local PostgreSQL database named
2321
+ `providerkit_agents`. It creates and drops its own schema and starts worker processes that it
2322
+ kills deliberately to check recovery. It refuses non-loopback database URLs:
2323
+
2324
+ ```sh
2325
+ AGENTS_TEST_DATABASE_URL=postgresql://postgres@127.0.0.1:5432/providerkit_agents \
2326
+ bunx vitest run test/runs.test.ts
2327
+ ```
2328
+
2329
+ Use a throwaway database, not an app database. These checks never call a live model.