@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,214 @@
1
+ // Adapted from TanStack AI (MIT), ai-harness/src/log.ts: adjacent delta folding,
2
+ // one timed buffer and one writer. The host owns sequence allocation and write reconciliation.
3
+ import type { BackgroundWorker } from "./runs.ts";
4
+ import { copyData, equalData } from "./snapshot.ts";
5
+ import type { AgentEvent } from "./types.ts";
6
+
7
+ export type EventDurability = "best-effort" | "awaited";
8
+
9
+ /** Counts original events, before folding. A rejected append may already be stored. */
10
+ export interface ProgressGap {
11
+ dropped: number;
12
+ unconfirmed: number;
13
+ }
14
+
15
+ const WAIT_MS = 100;
16
+ const MAX_RECORDS = 64;
17
+ const MAX_BYTES = 256 * 1024;
18
+ const encoder = new TextEncoder();
19
+ type ChunkEvent = Extract<AgentEvent, { type: "model_chunk" }>;
20
+ type RecordEntry = { type: string; data: unknown; count: number };
21
+
22
+ function textField(event: AgentEvent): "content" | "reasoning" | undefined {
23
+ if (event.type !== "model_chunk" || event.chunk.type !== "delta") return undefined;
24
+ for (const field of ["content", "reasoning"] as const)
25
+ if (
26
+ typeof event.chunk[field] === "string" &&
27
+ Object.keys(event.chunk).every((key) => key === "type" || key === field || key === "source")
28
+ )
29
+ return field;
30
+ return undefined;
31
+ }
32
+
33
+ /** Internal, bounded storage sink. Raw onEvent observers never pass through this buffer. */
34
+ export function createProgress(
35
+ run: Pick<BackgroundWorker, "emit" | "signal" | "append">,
36
+ mode: EventDurability,
37
+ ) {
38
+ const append = run.append?.bind(run);
39
+ if (mode === "awaited" && !append)
40
+ throw new TypeError(
41
+ 'events: "awaited" needs Run.append from @gusnips/server 0.21 or later. Upgrade the host or use best-effort events.',
42
+ );
43
+ const broken = new AbortController();
44
+ let queue: RecordEntry[] = [];
45
+ let bytes = 0;
46
+ let dropped = 0;
47
+ let pushed = 0;
48
+ let kept = 0;
49
+ let last: ChunkEvent | undefined;
50
+ let timer: ReturnType<typeof setTimeout> | undefined;
51
+ let writing: Promise<void> | undefined;
52
+ let failure: { cause: unknown } | undefined;
53
+ let closed = false;
54
+
55
+ function clearTimer() {
56
+ clearTimeout(timer);
57
+ timer = undefined;
58
+ }
59
+
60
+ async function store(batch: RecordEntry[], omitted: number) {
61
+ const events = batch.map(({ type, data }) => ({ type, data }));
62
+ const gap: ProgressGap = { dropped: omitted, unconfirmed: 0 };
63
+ if (mode === "best-effort") {
64
+ for (const event of events) run.emit(event.type, event.data);
65
+ if (omitted) run.emit("agent.gap", gap);
66
+ return;
67
+ }
68
+ if (!append) throw new TypeError("Missing Run.append.");
69
+ try {
70
+ if (events.length) await append(events);
71
+ } catch (error) {
72
+ run.signal.throwIfAborted();
73
+ // A host control exception is never a storage gap, even if a custom host has not
74
+ // aborted its signal yet. Older server copies have their own RunStopped class.
75
+ if (error instanceof Error && error.name === "RunStopped") throw error;
76
+ gap.unconfirmed = batch.reduce((count, event) => count + event.count, 0);
77
+ }
78
+ if (gap.dropped || gap.unconfirmed) {
79
+ run.signal.throwIfAborted();
80
+ // Never replay the rejected batch. append reconciles its own uncertain range before
81
+ // assigning positions to this NEW record. No durable marker means no successful barrier.
82
+ try {
83
+ await append([{ type: "agent.gap", data: gap }]);
84
+ } catch (cause) {
85
+ run.signal.throwIfAborted();
86
+ if (cause instanceof Error && cause.name === "RunStopped") throw cause;
87
+ throw new Error(
88
+ "Progress could not be saved or marked incomplete. Reconcile stored state before resuming.",
89
+ { cause },
90
+ );
91
+ }
92
+ }
93
+ }
94
+
95
+ function start(): void {
96
+ if (writing || closed || failure || run.signal.aborted || (!queue.length && !dropped)) return;
97
+ clearTimer();
98
+ const batch = queue;
99
+ const omitted = dropped;
100
+ const through = pushed;
101
+ queue = [];
102
+ bytes = 0;
103
+ dropped = 0;
104
+ last = undefined;
105
+ // The chain always settles. Failure is retained explicitly, not as a rejected tail that
106
+ // skips later cleanup or causes an unhandled rejection from a timer.
107
+ writing = store(batch, omitted)
108
+ .then(
109
+ () => {
110
+ kept = through;
111
+ },
112
+ (cause: unknown) => {
113
+ failure = { cause };
114
+ broken.abort(cause);
115
+ },
116
+ )
117
+ .finally(() => {
118
+ writing = undefined;
119
+ start();
120
+ });
121
+ }
122
+
123
+ function schedule(): void {
124
+ if (timer === undefined && !writing) timer = setTimeout(start, WAIT_MS);
125
+ }
126
+
127
+ function push(event: AgentEvent): void {
128
+ if (closed || run.signal.aborted || failure) return;
129
+ const data = copyData(event);
130
+ const size = encoder.encode(JSON.stringify(data)).byteLength;
131
+ const field = textField(data);
132
+ const previous = queue.at(-1);
133
+ pushed++;
134
+ // Once a prefix overflows, keep dropping until that gap is detached for writing. This
135
+ // avoids moving later events in front of the missing ones, including boundary events.
136
+ if (dropped || size > MAX_BYTES || bytes + size > MAX_BYTES) {
137
+ dropped++;
138
+ last = undefined;
139
+ start();
140
+ return;
141
+ }
142
+ if (
143
+ field &&
144
+ last &&
145
+ data.type === "model_chunk" &&
146
+ previous &&
147
+ textField(last) === field &&
148
+ last.runId === data.runId &&
149
+ last.operationId === data.operationId &&
150
+ last.attemptId === data.attemptId &&
151
+ equalData(last.chunk.source, data.chunk.source)
152
+ ) {
153
+ last.chunk[field] = (last.chunk[field] ?? "") + data.chunk[field];
154
+ previous.count++;
155
+ bytes += size;
156
+ } else {
157
+ if (queue.length === MAX_RECORDS) {
158
+ dropped++;
159
+ last = undefined;
160
+ start();
161
+ return;
162
+ }
163
+ queue.push({ type: "agent", data, count: 1 });
164
+ bytes += size;
165
+ last = field && data.type === "model_chunk" ? data : undefined;
166
+ }
167
+ if (!field || queue.length === MAX_RECORDS || bytes === MAX_BYTES) start();
168
+ else schedule();
169
+ }
170
+
171
+ async function flush(): Promise<void> {
172
+ const through = pushed;
173
+ // A journal boundary also seals the last delta, even while an older append is pending.
174
+ last = undefined;
175
+ clearTimer();
176
+ if (closed && kept < through && !run.signal.aborted && !failure)
177
+ throw new Error("The progress buffer was disposed before it was flushed.");
178
+ while (kept < through && !failure && !run.signal.aborted) {
179
+ start();
180
+ await writing;
181
+ }
182
+ run.signal.throwIfAborted();
183
+ if (failure) throw failure.cause;
184
+ }
185
+
186
+ function stopTimer() {
187
+ clearTimer();
188
+ }
189
+ run.signal.addEventListener("abort", stopTimer, { once: true });
190
+ return {
191
+ push,
192
+ flush,
193
+ signal: broken.signal,
194
+ async resync(crashes: number) {
195
+ await flush();
196
+ if (mode === "awaited") {
197
+ if (!append) throw new TypeError("Missing Run.append.");
198
+ // Before agent.resume, so no producer can overtake this marker.
199
+ await append([{ type: "agent.resync", data: { crashes } }]);
200
+ }
201
+ },
202
+ async dispose() {
203
+ closed = true;
204
+ clearTimer();
205
+ run.signal.removeEventListener("abort", stopTimer);
206
+ // Do not abandon an append on Stop or lease loss. It may still be committing.
207
+ await writing;
208
+ queue = [];
209
+ bytes = 0;
210
+ dropped = 0;
211
+ last = undefined;
212
+ },
213
+ };
214
+ }