@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
@@ -0,0 +1,329 @@
1
+ // Adapted from TanStack AI (MIT), session/turn-parts.ts: joinSteers and steering.
2
+ // See THIRD_PARTY_NOTICES.md. Journal before acknowledgement; only the conversation owner polls.
3
+ import { conversationOf, readContent } from "./input.ts";
4
+ import {
5
+ copyData,
6
+ equalData,
7
+ immutableCopy,
8
+ inlineBytes,
9
+ isId,
10
+ isRecord,
11
+ modelId,
12
+ } from "./snapshot.ts";
13
+ import { emitEvent, fail, snapshots, untilAbort, type ExecutionScope } from "./tree.ts";
14
+ import type { AgentRef, RunOptions, RunSnapshot, UserContent } from "./types.ts";
15
+
16
+ /** Fixed ceilings per logical run, including all its handoffs. Bytes are UTF-8 JSON bytes of
17
+ * normalized { id, content } records, not decoded attachment bytes. Hosts must bound enqueue too. */
18
+ export const INPUT_LIMITS = Object.freeze({ pending: 32, count: 128, bytes: 5_000_000 });
19
+
20
+ /** New user content only. An id names one immutable payload within the logical root run. */
21
+ export interface QueuedInput {
22
+ id: string;
23
+ content: UserContent;
24
+ }
25
+
26
+ /** Private journal entry. Insert after this many settled model/tool rounds. */
27
+ export interface RunInput extends QueuedInput {
28
+ beforeModel: number;
29
+ }
30
+
31
+ /** A completed call proves consumption here, not that the model followed the message. A
32
+ * running or interrupted call may have seen it, but remains accepted with consumption unknown. */
33
+ export interface InputReceipt {
34
+ id: string;
35
+ rootRunId: string;
36
+ runId: string;
37
+ beforeModel: number;
38
+ modelId: string;
39
+ status: "accepted" | "consumed";
40
+ /** Present only for the completed model attempt that first included this input. */
41
+ attemptId?: string;
42
+ }
43
+
44
+ export interface InputScope {
45
+ /** Stable logical identity, not a background segment id or a session id. */
46
+ rootRunId: string;
47
+ /** Current conversation owner. Never infer a route by parsing these ids. */
48
+ runId: string;
49
+ agent: AgentRef;
50
+ }
51
+
52
+ /** Trusted host storage. Authenticate enqueue, poll and acknowledgement against the logical
53
+ * run's owner and fence writes under its lease. These functions never grant tool authority. */
54
+ export interface InputInbox {
55
+ /** Non-destructive, ordered prefix. Return at most limit.count records fitting limit.bytes.
56
+ * Keep an offered record immutable and available until acknowledge accepts it. No long poll. */
57
+ poll(
58
+ request: InputScope & {
59
+ limit: { count: number; bytes: number };
60
+ signal: AbortSignal;
61
+ },
62
+ ): readonly QueuedInput[] | Promise<readonly QueuedInput[]>;
63
+ /** Called only after checkpoint. Idempotent and monotonic: accepted may become consumed,
64
+ * never the reverse. Keep accepted-but-unconsumed content for recall after the run settles.
65
+ * A crash after this write must allow the same receipt again. Do not start another run. */
66
+ acknowledge(
67
+ receipts: readonly InputReceipt[],
68
+ options: { signal: AbortSignal },
69
+ ): void | Promise<void>;
70
+ }
71
+
72
+ export interface InboxEntry extends QueuedInput {
73
+ status: "queued" | "accepted" | "consumed";
74
+ receipt?: InputReceipt;
75
+ }
76
+
77
+ export class InputConflictError extends Error {
78
+ constructor() {
79
+ super(
80
+ "This input id already has different content or a different delivery position. Use its original content, or a new id for a new message.",
81
+ );
82
+ this.name = "InputConflictError";
83
+ }
84
+ }
85
+
86
+ export function readQueuedInput(value: unknown): QueuedInput {
87
+ if (
88
+ !isRecord(value) ||
89
+ !isId(value.id) ||
90
+ value.id.length > 256 ||
91
+ Object.keys(value).some((key) => key !== "id" && key !== "content")
92
+ )
93
+ throw new TypeError("An input needs an id of 1 to 256 characters and user content only.");
94
+ return { id: value.id, content: readContent(value.content, "The queued input") };
95
+ }
96
+
97
+ export function inputBytes(input: QueuedInput): number {
98
+ return new TextEncoder().encode(JSON.stringify({ id: input.id, content: input.content })).length;
99
+ }
100
+
101
+ /** Reference host for one process, not durable storage or authentication. All records, including
102
+ * consumed ones, stay for deduplication until this inbox is discarded. No automatic follow-up. */
103
+ export function createMemoryInbox(rootRunId: string): InputInbox & {
104
+ enqueue(input: QueuedInput): InboxEntry;
105
+ list(): InboxEntry[];
106
+ } {
107
+ if (!isId(rootRunId)) throw new TypeError("An inbox needs its logical root run id.");
108
+ const entries = new Map<string, InboxEntry>();
109
+ let bytes = 0;
110
+ return {
111
+ enqueue(value) {
112
+ const input = readQueuedInput(value);
113
+ const previous = entries.get(input.id);
114
+ if (previous) {
115
+ if (!equalData(previous.content, input.content)) throw new InputConflictError();
116
+ return copyData(previous);
117
+ }
118
+ const size = inputBytes(input);
119
+ if (
120
+ entries.size >= INPUT_LIMITS.count ||
121
+ bytes + size > INPUT_LIMITS.bytes ||
122
+ [...entries.values()].filter((entry) => entry.status === "queued").length >=
123
+ INPUT_LIMITS.pending
124
+ )
125
+ throw new TypeError(
126
+ "The inbox is full. Recall unconsumed messages after this run ends instead of sending more.",
127
+ );
128
+ const entry: InboxEntry = { ...input, status: "queued" };
129
+ entries.set(input.id, entry);
130
+ bytes += size;
131
+ return copyData(entry);
132
+ },
133
+ list: () => copyData([...entries.values()]),
134
+ poll({ rootRunId: requested, limit, signal }) {
135
+ signal.throwIfAborted();
136
+ if (requested !== rootRunId) throw new TypeError("This inbox belongs to another run.");
137
+ const result: QueuedInput[] = [];
138
+ let size = 0;
139
+ for (const entry of entries.values()) {
140
+ if (entry.status !== "queued") continue;
141
+ size += inputBytes(entry);
142
+ if (result.length >= limit.count || size > limit.bytes) break;
143
+ result.push({ id: entry.id, content: copyData(entry.content) });
144
+ }
145
+ return result;
146
+ },
147
+ acknowledge(receipts, { signal }) {
148
+ signal.throwIfAborted();
149
+ // Check the whole batch before changing it, so a bad later receipt writes nothing.
150
+ const checked = new Map<string, InputReceipt>();
151
+ for (const receipt of receipts) {
152
+ const entry = entries.get(receipt.id);
153
+ if (
154
+ receipt.rootRunId !== rootRunId ||
155
+ !entry ||
156
+ !isId(receipt.runId) ||
157
+ !Number.isSafeInteger(receipt.beforeModel) ||
158
+ receipt.beforeModel < 0 ||
159
+ receipt.modelId !== modelId(receipt.runId, receipt.beforeModel) ||
160
+ (receipt.status !== "accepted" && receipt.status !== "consumed") ||
161
+ (receipt.status === "consumed"
162
+ ? !isId(receipt.attemptId)
163
+ : receipt.attemptId !== undefined)
164
+ )
165
+ throw new TypeError("The input receipt does not belong to this inbox or model call.");
166
+ const previous = checked.get(receipt.id) ?? entry.receipt;
167
+ if (
168
+ previous &&
169
+ (previous.runId !== receipt.runId ||
170
+ previous.beforeModel !== receipt.beforeModel ||
171
+ (previous.status === "consumed" &&
172
+ receipt.status === "consumed" &&
173
+ previous.attemptId !== receipt.attemptId))
174
+ )
175
+ throw new InputConflictError();
176
+ checked.set(receipt.id, previous?.status === "consumed" ? previous : receipt);
177
+ }
178
+ for (const receipt of receipts) {
179
+ const entry = entries.get(receipt.id);
180
+ if (!entry || entry.status === "consumed") continue;
181
+ entry.receipt = copyData(receipt);
182
+ entry.status = receipt.status;
183
+ }
184
+ },
185
+ };
186
+ }
187
+
188
+ export function inputReceipts(root: RunSnapshot): InputReceipt[] {
189
+ return [...snapshots(root)].flatMap((snapshot) =>
190
+ snapshot.kind !== "agent"
191
+ ? []
192
+ : snapshot.inputs.map((input): InputReceipt => {
193
+ const model = snapshot.models[input.beforeModel];
194
+ return {
195
+ id: input.id,
196
+ rootRunId: snapshot.tree.runId,
197
+ runId: snapshot.runId,
198
+ beforeModel: input.beforeModel,
199
+ modelId: modelId(snapshot.runId, input.beforeModel),
200
+ status: model?.status === "completed" ? "consumed" : "accepted",
201
+ ...(model?.status === "completed" ? { attemptId: model.attemptId } : {}),
202
+ };
203
+ }),
204
+ );
205
+ }
206
+
207
+ export async function acknowledgeInputs(
208
+ snapshot: RunSnapshot,
209
+ options: RunOptions,
210
+ signal: AbortSignal,
211
+ ): Promise<void> {
212
+ const receipts = inputReceipts(snapshot);
213
+ if (!receipts.length) return;
214
+ const inbox = options.host?.inbox;
215
+ if (!inbox)
216
+ fail(
217
+ "input_host_missing",
218
+ "Restore this run's host inbox before continuing its recorded inputs.",
219
+ );
220
+ try {
221
+ await untilAbort(
222
+ Promise.resolve(inbox.acknowledge(immutableCopy(receipts), { signal })),
223
+ signal,
224
+ );
225
+ } catch {
226
+ signal.throwIfAborted();
227
+ fail(
228
+ "input_acknowledge_failed",
229
+ "The inbox did not confirm delivery. Reconcile its receipts with the saved run before recalling or resuming these messages.",
230
+ );
231
+ }
232
+ }
233
+
234
+ /** Only the root's handoff chain owns conversation input. A delegated child's own handoffs
235
+ * cannot opt it into the parent's inbox. No parsed ids, broadcast or mutable owner pointer. */
236
+ function conversationOwner(root: RunSnapshot): RunSnapshot {
237
+ let owner = root;
238
+ for (;;) {
239
+ const next = owner.delegations.find(
240
+ (entry) => entry.kind === "handoff" && entry.children.length,
241
+ )?.children[0]?.snapshot;
242
+ if (!next) return owner;
243
+ if (next.kind !== "agent") throw new TypeError("A handoff target must be an agent.");
244
+ owner = next;
245
+ }
246
+ }
247
+
248
+ export async function acceptInputs(
249
+ snapshot: RunSnapshot,
250
+ scope: ExecutionScope,
251
+ options: RunOptions,
252
+ signal: AbortSignal,
253
+ ): Promise<void> {
254
+ const inbox = options.host?.inbox;
255
+ if (
256
+ !inbox ||
257
+ scope.tree.root.kind !== "agent" ||
258
+ conversationOwner(scope.tree.root).runId !== snapshot.runId
259
+ )
260
+ return;
261
+ const recorded = [...snapshots(scope.tree.root)].flatMap((node) =>
262
+ node.kind === "agent" ? node.inputs : [],
263
+ );
264
+ const limit = {
265
+ count: Math.min(INPUT_LIMITS.pending, INPUT_LIMITS.count - recorded.length),
266
+ bytes: INPUT_LIMITS.bytes - recorded.reduce((total, input) => total + inputBytes(input), 0),
267
+ };
268
+ if (limit.count <= 0 || limit.bytes <= 0) return;
269
+ let offered: unknown;
270
+ try {
271
+ offered = await untilAbort(
272
+ Promise.resolve(
273
+ inbox.poll({
274
+ ...immutableCopy({
275
+ rootRunId: snapshot.tree.runId,
276
+ runId: snapshot.runId,
277
+ agent: { id: snapshot.agentId, version: snapshot.version },
278
+ limit,
279
+ }),
280
+ signal,
281
+ }),
282
+ ),
283
+ signal,
284
+ );
285
+ } catch {
286
+ signal.throwIfAborted();
287
+ fail(
288
+ "input_poll_failed",
289
+ "The run could not read its inbox. Check the host inbox before continuing.",
290
+ );
291
+ }
292
+ signal.throwIfAborted();
293
+ scope.tree.active();
294
+ if (!Array.isArray(offered) || offered.length > limit.count)
295
+ fail("invalid_inbox", "The host inbox returned more messages than the requested limit.");
296
+ const accepted: RunInput[] = [];
297
+ let bytes = 0;
298
+ for (const raw of offered) {
299
+ const input = readQueuedInput(raw);
300
+ const previous = [...recorded, ...accepted].find((entry) => entry.id === input.id);
301
+ if (previous) {
302
+ if (!equalData(previous.content, input.content))
303
+ fail("input_conflict", new InputConflictError().message);
304
+ continue;
305
+ }
306
+ bytes += inputBytes(input);
307
+ if (bytes > limit.bytes)
308
+ fail("invalid_inbox", "The host inbox returned more bytes than the requested limit.");
309
+ accepted.push({ ...input, beforeModel: snapshot.models.length });
310
+ }
311
+ if (!accepted.length) return;
312
+ const history = [
313
+ ...conversationOf(snapshot),
314
+ ...accepted.map((input) => ({ role: "user" as const, content: input.content })),
315
+ ];
316
+ if (inlineBytes(history, "") > snapshot.limits.inlineBytes)
317
+ fail(
318
+ "input_media_limit",
319
+ "The queued images and files exceed this agent's inline byte limit. Recall them after this run ends and use media references.",
320
+ );
321
+ // No mutation until the whole offered prefix passes. A failed save leaves host delivery queued.
322
+ snapshot.inputs.push(...accepted);
323
+ await scope.tree.save();
324
+ for (const receipt of inputReceipts(snapshot).filter((receipt) =>
325
+ accepted.some((input) => input.id === receipt.id),
326
+ ))
327
+ emitEvent(options, { type: "input", receipt });
328
+ await acknowledgeInputs(snapshot, options, signal);
329
+ }