@providerkit/agents 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (291) hide show
  1. package/LICENSE-APACHE-2.0 +202 -0
  2. package/README.md +2108 -52
  3. package/THIRD_PARTY_NOTICES.md +521 -0
  4. package/dist/a2a/auth.d.ts +10 -0
  5. package/dist/a2a/auth.d.ts.map +1 -0
  6. package/dist/a2a/auth.js +52 -0
  7. package/dist/a2a/auth.js.map +1 -0
  8. package/dist/a2a/client.d.ts +74 -0
  9. package/dist/a2a/client.d.ts.map +1 -0
  10. package/dist/a2a/client.js +601 -0
  11. package/dist/a2a/client.js.map +1 -0
  12. package/dist/a2a/index.d.ts +22 -0
  13. package/dist/a2a/index.d.ts.map +1 -0
  14. package/dist/a2a/index.js +11 -0
  15. package/dist/a2a/index.js.map +1 -0
  16. package/dist/a2a/memory-runs.d.ts +62 -0
  17. package/dist/a2a/memory-runs.d.ts.map +1 -0
  18. package/dist/a2a/memory-runs.js +349 -0
  19. package/dist/a2a/memory-runs.js.map +1 -0
  20. package/dist/a2a/policy.d.ts +15 -0
  21. package/dist/a2a/policy.d.ts.map +1 -0
  22. package/dist/a2a/policy.js +114 -0
  23. package/dist/a2a/policy.js.map +1 -0
  24. package/dist/a2a/push.d.ts +34 -0
  25. package/dist/a2a/push.d.ts.map +1 -0
  26. package/dist/a2a/push.js +180 -0
  27. package/dist/a2a/push.js.map +1 -0
  28. package/dist/a2a/remote.d.ts +155 -0
  29. package/dist/a2a/remote.d.ts.map +1 -0
  30. package/dist/a2a/remote.js +1196 -0
  31. package/dist/a2a/remote.js.map +1 -0
  32. package/dist/a2a/server.d.ts +110 -0
  33. package/dist/a2a/server.d.ts.map +1 -0
  34. package/dist/a2a/server.js +1139 -0
  35. package/dist/a2a/server.js.map +1 -0
  36. package/dist/a2a/signing.d.ts +21 -0
  37. package/dist/a2a/signing.d.ts.map +1 -0
  38. package/dist/a2a/signing.js +305 -0
  39. package/dist/a2a/signing.js.map +1 -0
  40. package/dist/a2a/tasks.d.ts +88 -0
  41. package/dist/a2a/tasks.d.ts.map +1 -0
  42. package/dist/a2a/tasks.js +170 -0
  43. package/dist/a2a/tasks.js.map +1 -0
  44. package/dist/a2a/wire.d.ts +267 -0
  45. package/dist/a2a/wire.d.ts.map +1 -0
  46. package/dist/a2a/wire.js +1202 -0
  47. package/dist/a2a/wire.js.map +1 -0
  48. package/dist/background-types.d.ts +76 -0
  49. package/dist/background-types.d.ts.map +1 -0
  50. package/dist/background-types.js +2 -0
  51. package/dist/background-types.js.map +1 -0
  52. package/dist/child.d.ts +25 -0
  53. package/dist/child.d.ts.map +1 -0
  54. package/dist/child.js +129 -0
  55. package/dist/child.js.map +1 -0
  56. package/dist/code-driver.d.ts +40 -0
  57. package/dist/code-driver.d.ts.map +1 -0
  58. package/dist/code-driver.js +2 -0
  59. package/dist/code-driver.js.map +1 -0
  60. package/dist/code-mode.d.ts +3 -0
  61. package/dist/code-mode.d.ts.map +1 -0
  62. package/dist/code-mode.js +2 -0
  63. package/dist/code-mode.js.map +1 -0
  64. package/dist/code-script.d.ts +3 -0
  65. package/dist/code-script.d.ts.map +1 -0
  66. package/dist/code-script.js +149 -0
  67. package/dist/code-script.js.map +1 -0
  68. package/dist/code.d.ts +75 -0
  69. package/dist/code.d.ts.map +1 -0
  70. package/dist/code.js +326 -0
  71. package/dist/code.js.map +1 -0
  72. package/dist/compaction.d.ts +15 -0
  73. package/dist/compaction.d.ts.map +1 -0
  74. package/dist/compaction.js +168 -0
  75. package/dist/compaction.js.map +1 -0
  76. package/dist/delegation.d.ts +85 -16
  77. package/dist/delegation.d.ts.map +1 -1
  78. package/dist/delegation.js +240 -106
  79. package/dist/delegation.js.map +1 -1
  80. package/dist/evals/driver.d.ts +10 -0
  81. package/dist/evals/driver.d.ts.map +1 -0
  82. package/dist/evals/driver.js +192 -0
  83. package/dist/evals/driver.js.map +1 -0
  84. package/dist/evals/journal.d.ts +26 -0
  85. package/dist/evals/journal.d.ts.map +1 -0
  86. package/dist/evals/journal.js +483 -0
  87. package/dist/evals/journal.js.map +1 -0
  88. package/dist/evals/judge.d.ts +31 -0
  89. package/dist/evals/judge.d.ts.map +1 -0
  90. package/dist/evals/judge.js +142 -0
  91. package/dist/evals/judge.js.map +1 -0
  92. package/dist/evals/report.d.ts +38 -0
  93. package/dist/evals/report.d.ts.map +1 -0
  94. package/dist/evals/report.js +241 -0
  95. package/dist/evals/report.js.map +1 -0
  96. package/dist/evals/runner.d.ts +24 -0
  97. package/dist/evals/runner.d.ts.map +1 -0
  98. package/dist/evals/runner.js +655 -0
  99. package/dist/evals/runner.js.map +1 -0
  100. package/dist/evals/scorers.d.ts +36 -0
  101. package/dist/evals/scorers.d.ts.map +1 -0
  102. package/dist/evals/scorers.js +259 -0
  103. package/dist/evals/scorers.js.map +1 -0
  104. package/dist/evals/simulation.d.ts +7 -0
  105. package/dist/evals/simulation.d.ts.map +1 -0
  106. package/dist/evals/simulation.js +38 -0
  107. package/dist/evals/simulation.js.map +1 -0
  108. package/dist/evals/testing.d.ts +36 -0
  109. package/dist/evals/testing.d.ts.map +1 -0
  110. package/dist/evals/testing.js +87 -0
  111. package/dist/evals/testing.js.map +1 -0
  112. package/dist/evals/trajectory.d.ts +11 -0
  113. package/dist/evals/trajectory.d.ts.map +1 -0
  114. package/dist/evals/trajectory.js +180 -0
  115. package/dist/evals/trajectory.js.map +1 -0
  116. package/dist/evals/types.d.ts +431 -0
  117. package/dist/evals/types.d.ts.map +1 -0
  118. package/dist/evals/types.js +4 -0
  119. package/dist/evals/types.js.map +1 -0
  120. package/dist/evals.d.ts +14 -0
  121. package/dist/evals.d.ts.map +1 -0
  122. package/dist/evals.js +9 -0
  123. package/dist/evals.js.map +1 -0
  124. package/dist/extensions.d.ts +33 -0
  125. package/dist/extensions.d.ts.map +1 -0
  126. package/dist/extensions.js +188 -0
  127. package/dist/extensions.js.map +1 -0
  128. package/dist/handoff.d.ts +58 -0
  129. package/dist/handoff.d.ts.map +1 -0
  130. package/dist/handoff.js +160 -0
  131. package/dist/handoff.js.map +1 -0
  132. package/dist/index.d.ts +14 -0
  133. package/dist/index.d.ts.map +1 -1
  134. package/dist/index.js +8 -0
  135. package/dist/index.js.map +1 -1
  136. package/dist/input.d.ts +42 -0
  137. package/dist/input.d.ts.map +1 -0
  138. package/dist/input.js +266 -0
  139. package/dist/input.js.map +1 -0
  140. package/dist/mcp.d.ts +77 -0
  141. package/dist/mcp.d.ts.map +1 -0
  142. package/dist/mcp.js +505 -0
  143. package/dist/mcp.js.map +1 -0
  144. package/dist/memory-store.d.ts +11 -0
  145. package/dist/memory-store.d.ts.map +1 -0
  146. package/dist/memory-store.js +272 -0
  147. package/dist/memory-store.js.map +1 -0
  148. package/dist/memory.d.ts +212 -0
  149. package/dist/memory.d.ts.map +1 -0
  150. package/dist/memory.js +613 -0
  151. package/dist/memory.js.map +1 -0
  152. package/dist/otel.d.ts +74 -0
  153. package/dist/otel.d.ts.map +1 -0
  154. package/dist/otel.js +427 -0
  155. package/dist/otel.js.map +1 -0
  156. package/dist/progress.d.ts +17 -0
  157. package/dist/progress.d.ts.map +1 -0
  158. package/dist/progress.js +193 -0
  159. package/dist/progress.js.map +1 -0
  160. package/dist/quickjs.d.ts +19 -0
  161. package/dist/quickjs.d.ts.map +1 -0
  162. package/dist/quickjs.js +519 -0
  163. package/dist/quickjs.js.map +1 -0
  164. package/dist/recovery.d.ts +10 -0
  165. package/dist/recovery.d.ts.map +1 -0
  166. package/dist/recovery.js +62 -0
  167. package/dist/recovery.js.map +1 -0
  168. package/dist/request.d.ts +88 -0
  169. package/dist/request.d.ts.map +1 -0
  170. package/dist/request.js +422 -0
  171. package/dist/request.js.map +1 -0
  172. package/dist/run.d.ts +16 -4
  173. package/dist/run.d.ts.map +1 -1
  174. package/dist/run.js +2016 -245
  175. package/dist/run.js.map +1 -1
  176. package/dist/runs.d.ts +77 -34
  177. package/dist/runs.d.ts.map +1 -1
  178. package/dist/runs.js +267 -85
  179. package/dist/runs.js.map +1 -1
  180. package/dist/schema-to-ts.d.ts +4 -0
  181. package/dist/schema-to-ts.d.ts.map +1 -0
  182. package/dist/schema-to-ts.js +191 -0
  183. package/dist/schema-to-ts.js.map +1 -0
  184. package/dist/session.d.ts +23 -0
  185. package/dist/session.d.ts.map +1 -0
  186. package/dist/session.js +137 -0
  187. package/dist/session.js.map +1 -0
  188. package/dist/snapshot.d.ts +57 -8
  189. package/dist/snapshot.d.ts.map +1 -1
  190. package/dist/snapshot.js +1206 -109
  191. package/dist/snapshot.js.map +1 -1
  192. package/dist/steering.d.ts +75 -0
  193. package/dist/steering.d.ts.map +1 -0
  194. package/dist/steering.js +214 -0
  195. package/dist/steering.js.map +1 -0
  196. package/dist/subagents.d.ts +141 -0
  197. package/dist/subagents.d.ts.map +1 -0
  198. package/dist/subagents.js +746 -0
  199. package/dist/subagents.js.map +1 -0
  200. package/dist/tool-retry.d.ts +12 -0
  201. package/dist/tool-retry.d.ts.map +1 -0
  202. package/dist/tool-retry.js +53 -0
  203. package/dist/tool-retry.js.map +1 -0
  204. package/dist/tree.d.ts +62 -6
  205. package/dist/tree.d.ts.map +1 -1
  206. package/dist/tree.js +192 -23
  207. package/dist/tree.js.map +1 -1
  208. package/dist/types.d.ts +767 -52
  209. package/dist/types.d.ts.map +1 -1
  210. package/dist/workflow-snapshot.d.ts +8 -0
  211. package/dist/workflow-snapshot.d.ts.map +1 -0
  212. package/dist/workflow-snapshot.js +276 -0
  213. package/dist/workflow-snapshot.js.map +1 -0
  214. package/dist/workflow-types.d.ts +171 -0
  215. package/dist/workflow-types.d.ts.map +1 -0
  216. package/dist/workflow-types.js +2 -0
  217. package/dist/workflow-types.js.map +1 -0
  218. package/dist/workflow.d.ts +19 -0
  219. package/dist/workflow.d.ts.map +1 -0
  220. package/dist/workflow.js +1053 -0
  221. package/dist/workflow.js.map +1 -0
  222. package/examples/a2a-remote.ts +85 -0
  223. package/examples/a2a-server.ts +100 -0
  224. package/examples/background.ts +18 -4
  225. package/examples/code-mode.ts +76 -0
  226. package/examples/conversation.ts +57 -0
  227. package/examples/evals.ts +79 -0
  228. package/examples/guardrails.ts +56 -0
  229. package/examples/handoff.ts +79 -0
  230. package/examples/memory.ts +44 -0
  231. package/examples/otel.ts +99 -0
  232. package/examples/steering.ts +69 -0
  233. package/examples/structured-handoff.ts +92 -0
  234. package/examples/subagents.ts +127 -0
  235. package/examples/workflow.ts +74 -0
  236. package/package.json +58 -6
  237. package/src/a2a/auth.ts +62 -0
  238. package/src/a2a/client.ts +733 -0
  239. package/src/a2a/index.ts +74 -0
  240. package/src/a2a/memory-runs.ts +448 -0
  241. package/src/a2a/policy.ts +148 -0
  242. package/src/a2a/push.ts +251 -0
  243. package/src/a2a/remote.ts +1652 -0
  244. package/src/a2a/server.ts +1390 -0
  245. package/src/a2a/signing.ts +348 -0
  246. package/src/a2a/tasks.ts +260 -0
  247. package/src/a2a/wire.ts +1443 -0
  248. package/src/background-types.ts +86 -0
  249. package/src/child.ts +181 -0
  250. package/src/code-driver.ts +48 -0
  251. package/src/code-mode.ts +12 -0
  252. package/src/code-script.ts +149 -0
  253. package/src/code.ts +424 -0
  254. package/src/compaction.ts +212 -0
  255. package/src/delegation.ts +444 -155
  256. package/src/evals/driver.ts +222 -0
  257. package/src/evals/journal.ts +605 -0
  258. package/src/evals/judge.ts +188 -0
  259. package/src/evals/report.ts +295 -0
  260. package/src/evals/runner.ts +826 -0
  261. package/src/evals/scorers.ts +339 -0
  262. package/src/evals/simulation.ts +46 -0
  263. package/src/evals/testing.ts +126 -0
  264. package/src/evals/trajectory.ts +223 -0
  265. package/src/evals/types.ts +463 -0
  266. package/src/evals.ts +72 -0
  267. package/src/extensions.ts +247 -0
  268. package/src/handoff.ts +214 -0
  269. package/src/index.ts +51 -0
  270. package/src/input.ts +319 -0
  271. package/src/mcp.ts +690 -0
  272. package/src/memory-store.ts +366 -0
  273. package/src/memory.ts +893 -0
  274. package/src/otel.ts +568 -0
  275. package/src/progress.ts +214 -0
  276. package/src/quickjs.ts +524 -0
  277. package/src/recovery.ts +90 -0
  278. package/src/request.ts +513 -0
  279. package/src/run.ts +2678 -313
  280. package/src/runs.ts +464 -133
  281. package/src/schema-to-ts.ts +194 -0
  282. package/src/session.ts +178 -0
  283. package/src/snapshot.ts +1595 -124
  284. package/src/steering.ts +329 -0
  285. package/src/subagents.ts +1084 -0
  286. package/src/tool-retry.ts +86 -0
  287. package/src/tree.ts +223 -27
  288. package/src/types.ts +711 -52
  289. package/src/workflow-snapshot.ts +366 -0
  290. package/src/workflow-types.ts +213 -0
  291. package/src/workflow.ts +1316 -0
package/src/quickjs.ts ADDED
@@ -0,0 +1,524 @@
1
+ // Lifecycle adapted from Mastra's code-mode/quickjs/src/transport.ts (Apache-2.0),
2
+ // Copyright (c) 2025 Kepler Software, Inc. Error classification and deferred bridges
3
+ // also draw on TanStack AI's ai-isolate-quickjs (MIT), Copyright (c) 2025 Tanner Linsley.
4
+ // Changes: one-job string contract, cumulative CPU budget, bounded job pumping,
5
+ // cancellable admission, no host promise-result handles, lazy sync-only loading.
6
+ // See THIRD_PARTY_NOTICES.md and LICENSE-APACHE-2.0.
7
+ import { createGate } from "@providerkit/core";
8
+ import type {
9
+ QuickJSContext,
10
+ QuickJSDeferredPromise,
11
+ QuickJSHandle,
12
+ QuickJSRuntime,
13
+ QuickJSWASMModule,
14
+ } from "quickjs-emscripten-core";
15
+ import type { CodeDriver, CodeJob, CodeJobResult } from "./code-driver.ts";
16
+
17
+ export interface QuickJsDriverOptions {
18
+ /** A precompiled release-sync module for Workers that cannot compile fetched Wasm. */
19
+ wasmModule?: WebAssembly.Module;
20
+ /** Host-owned Wasm URL or path for browsers and extensions. Never take this from a program. */
21
+ wasmLocation?: string;
22
+ /** Jobs admitted at once by this driver. Share the driver across runs. Default: 4. */
23
+ maxActive?: number;
24
+ }
25
+
26
+ type Failure = Extract<CodeJobResult, { ok: false }>;
27
+ const fail = (name: Failure["error"]["name"], message: string): Failure => ({
28
+ ok: false,
29
+ error: { name, message },
30
+ });
31
+ const engineFailure = () =>
32
+ fail(
33
+ "EngineError",
34
+ "The JavaScript engine failed. Check which tool calls finished before running more code.",
35
+ );
36
+ const memoryFailure = () => fail("MemoryLimitError", "The program exceeded its memory limit.");
37
+ const stackFailure = () => fail("StackLimitError", "The program exceeded its stack limit.");
38
+ const MAX_STACK_BYTES = 256 * 1024;
39
+ const MAX_WASM_BYTES = 0x7fff_ffff;
40
+ const JOBS_PER_PUMP = 64;
41
+
42
+ // Capture these before guest code can change builtins. Never dump a guest object on
43
+ // the host: getters, toJSON and coercion can execute more guest code, even on errors.
44
+ const ERROR_READER = `(() => {
45
+ const stringify = JSON.stringify;
46
+ const create = Object.create;
47
+ const slice = Function.prototype.call.bind(String.prototype.slice);
48
+ return (error) => {
49
+ const result = create(null);
50
+ for (const key of ["name", "message", "stack"]) {
51
+ try {
52
+ const value = error == null ? undefined : error[key];
53
+ result[key] = typeof value === "string" ? slice(value, 0, 2048) : "";
54
+ } catch {
55
+ result[key] = "";
56
+ }
57
+ }
58
+ return stringify(result);
59
+ };
60
+ })()`;
61
+
62
+ /**
63
+ * An in-process, sync-Wasm driver with no guest network, files, imports or timers.
64
+ * ponytail: a synchronous guest blocks this thread until an interrupt check. Use
65
+ * a worker-backed CodeDriver if the host must stay responsive during that time.
66
+ * Synchronous host callbacks and Wasm string copies cannot be preempted. Their
67
+ * elapsed time is charged, but hosts must keep callbacks short and cap payloads.
68
+ * The Wasm module keeps its peak allocation even after each runtime is freed.
69
+ */
70
+ export function createQuickJsDriver(options: QuickJsDriverOptions = {}): CodeDriver {
71
+ const { wasmModule, wasmLocation, maxActive = 4 } = options;
72
+ if (!Number.isSafeInteger(maxActive) || maxActive < 1) {
73
+ throw new TypeError("maxActive must be a positive whole number.");
74
+ }
75
+ if (wasmModule !== undefined && wasmLocation !== undefined) {
76
+ throw new TypeError("Set wasmModule or wasmLocation, not both.");
77
+ }
78
+ const gate = createGate(maxActive);
79
+ let cached: { promise: Promise<QuickJSWASMModule>; broken: AbortController } | undefined;
80
+ const load = () => {
81
+ if (!cached) {
82
+ const entry = {
83
+ broken: new AbortController(),
84
+ promise: (async () => {
85
+ const [core, variant] = await Promise.all([
86
+ import("quickjs-emscripten-core"),
87
+ import("@jitl/quickjs-wasmfile-release-sync"),
88
+ ]);
89
+ return core.newQuickJSWASMModuleFromVariant(
90
+ core.newVariant(variant.default, { wasmModule, wasmLocation }),
91
+ );
92
+ })(),
93
+ };
94
+ cached = entry;
95
+ void entry.promise.catch(() => {
96
+ if (cached === entry) cached = undefined;
97
+ });
98
+ }
99
+ return cached;
100
+ };
101
+
102
+ return {
103
+ async run(job) {
104
+ if (job.signal.aborted) return fail("AbortError", "The program was stopped.");
105
+ if (
106
+ !Number.isSafeInteger(job.memoryBytes) ||
107
+ job.memoryBytes < 1 ||
108
+ job.memoryBytes > MAX_WASM_BYTES ||
109
+ !Number.isSafeInteger(job.stackBytes) ||
110
+ job.stackBytes < 1 ||
111
+ job.stackBytes > MAX_STACK_BYTES ||
112
+ !Number.isFinite(job.cpuMs) ||
113
+ job.cpuMs <= 0 ||
114
+ !Number.isSafeInteger(job.deadline)
115
+ ) {
116
+ return fail(
117
+ "EngineError",
118
+ "Set finite positive limits: memory up to 2147483647 bytes, stack up to 262144 bytes, CPU milliseconds and an epoch-millisecond deadline.",
119
+ );
120
+ }
121
+
122
+ let failure: Failure | undefined;
123
+ let wake = () => {};
124
+ let waitingForSlot = true;
125
+ const admission = new AbortController();
126
+ const stop = (reason: Failure) => {
127
+ failure ??= reason;
128
+ if (waitingForSlot) admission.abort();
129
+ wake();
130
+ };
131
+ const check = () => {
132
+ if (job.signal.aborted) stop(fail("AbortError", "The program was stopped."));
133
+ else if (Date.now() >= job.deadline) {
134
+ stop(fail("TimeoutError", "The program reached its wall-time deadline."));
135
+ }
136
+ return failure;
137
+ };
138
+ const onAbort = () => check();
139
+ let timer: ReturnType<typeof setTimeout> | undefined;
140
+ const armDeadline = () => {
141
+ if (!check()) {
142
+ timer = setTimeout(armDeadline, Math.min(MAX_WASM_BYTES, job.deadline - Date.now()));
143
+ }
144
+ };
145
+ job.signal.addEventListener("abort", onAbort, { once: true });
146
+ armDeadline();
147
+ let release: (() => void) | undefined;
148
+ try {
149
+ release = await gate.acquire(admission.signal);
150
+ // The gate's signal releases held slots on abort. Stop using that signal
151
+ // after admission, so another runtime cannot start before this one is freed.
152
+ waitingForSlot = false;
153
+ if (check()) return failure!;
154
+ const entry = load();
155
+ const onBroken = () => stop(engineFailure());
156
+ entry.broken.signal.addEventListener("abort", onBroken, { once: true });
157
+ try {
158
+ const ended = new Promise<undefined>((resolve) => {
159
+ wake = () => resolve(undefined);
160
+ });
161
+ const wasm = await Promise.race([entry.promise, ended]);
162
+ if (check()) return failure!;
163
+ if (!wasm) return engineFailure();
164
+ return await execute(
165
+ job,
166
+ wasm,
167
+ check,
168
+ stop,
169
+ (listener) => (wake = listener),
170
+ () => {
171
+ if (cached === entry) cached = undefined;
172
+ entry.broken.abort();
173
+ },
174
+ );
175
+ } finally {
176
+ entry.broken.signal.removeEventListener("abort", onBroken);
177
+ }
178
+ } catch {
179
+ return failure ?? engineFailure();
180
+ } finally {
181
+ release?.();
182
+ clearTimeout(timer);
183
+ job.signal.removeEventListener("abort", onAbort);
184
+ }
185
+ },
186
+ };
187
+ }
188
+
189
+ async function execute(
190
+ job: CodeJob,
191
+ wasm: QuickJSWASMModule,
192
+ checkWall: () => Failure | undefined,
193
+ stop: (failure: Failure) => void,
194
+ onWake: (listener: () => void) => void,
195
+ breakModule: () => void,
196
+ ): Promise<CodeJobResult> {
197
+ let runtime: QuickJSRuntime | undefined;
198
+ let context: QuickJSContext | undefined;
199
+ const owned: QuickJSHandle[] = [];
200
+ const pending = new Set<QuickJSDeferredPromise>();
201
+ const replies: Array<{ deferred: QuickJSDeferredPromise; text: string }> = [];
202
+ let finished = false;
203
+ let notify = () => {};
204
+ let cpuUsed = 0;
205
+ let sliceStart: number | undefined;
206
+ let result: CodeJobResult = engineFailure();
207
+ let cleanupFailed = false;
208
+ const check = () => {
209
+ const stopped = checkWall();
210
+ if (stopped) return stopped;
211
+ if (cpuUsed + (sliceStart === undefined ? 0 : performance.now() - sliceStart) >= job.cpuMs) {
212
+ const limit = fail("CpuLimitError", "The program exceeded its CPU time limit.");
213
+ stop(limit);
214
+ return limit;
215
+ }
216
+ return undefined;
217
+ };
218
+ const timed = <T>(action: () => T): T => {
219
+ sliceStart = performance.now();
220
+ try {
221
+ return action();
222
+ } finally {
223
+ cpuUsed += performance.now() - sliceStart;
224
+ sliceStart = undefined;
225
+ }
226
+ };
227
+ const failEngine = () => {
228
+ stop(engineFailure());
229
+ breakModule();
230
+ };
231
+ onWake(() => notify());
232
+
233
+ try {
234
+ runtime = wasm.newRuntime();
235
+ const rt = runtime;
236
+ // Initialize only trusted builtins before applying tiny memory/stack limits.
237
+ // QuickJS 0.32 does not check a null context pointer when initialization OOMs.
238
+ context = rt.newContext();
239
+ const vm = context;
240
+ const initialize = (source: string) => {
241
+ const value = vm.evalCode(source, "driver.js", { type: "global" });
242
+ if (value.error) {
243
+ value.dispose();
244
+ throw new Error("Could not initialize the driver");
245
+ }
246
+ owned.push(value.value);
247
+ return value.value;
248
+ };
249
+ const reader = initialize(ERROR_READER);
250
+ const messageKey = initialize('"message"');
251
+ const stackOverflow = initialize('"stack overflow"');
252
+ const outOfMemory = initialize('"out of memory"');
253
+ const encode = initialize("JSON.stringify");
254
+ const decode = initialize("JSON.parse");
255
+
256
+ // QuickJS 0.32's C-string API truncates at NUL and loses lone surrogates.
257
+ // Encode primitive strings inside the guest, then copy only their JSON text.
258
+ // The caller times this whole conversion and the guest keeps its heap cap.
259
+ const readString = (handle: QuickJSHandle): string | undefined => {
260
+ const encoded = vm.callFunction(encode, vm.undefined, handle);
261
+ try {
262
+ if (encoded.error) {
263
+ stop(check() ?? memoryFailure());
264
+ return undefined;
265
+ }
266
+ const text: unknown = JSON.parse(vm.getString(encoded.value));
267
+ if (typeof text === "string") return text;
268
+ stop(engineFailure());
269
+ return undefined;
270
+ } finally {
271
+ encoded.dispose();
272
+ }
273
+ };
274
+
275
+ const readError = (handle: QuickJSHandle): Failure => {
276
+ // A terminal error's getters may run code, but must not start more host work.
277
+ finished = true;
278
+ const stopped = check();
279
+ if (stopped) return stopped;
280
+ const detail = timed(() => vm.callFunction(reader, vm.undefined, handle));
281
+ try {
282
+ const interrupted = check();
283
+ if (interrupted) return interrupted;
284
+ // Keep both ceilings while formatting: a hostile getter still runs guest code.
285
+ const diagnosticError = detail.error;
286
+ if (diagnosticError) {
287
+ // QuickJS throws null when it cannot allocate its own OOM error.
288
+ if (vm.eq(diagnosticError, vm.null)) return memoryFailure();
289
+ // The reader can itself overflow a tiny stack. Compare native error text
290
+ // without another guest function call or copying arbitrary strings out.
291
+ const message = timed(() => vm.getProp(diagnosticError, messageKey));
292
+ try {
293
+ const stopped = check();
294
+ if (stopped) return stopped;
295
+ if (vm.eq(message, stackOverflow)) return stackFailure();
296
+ if (vm.eq(message, outOfMemory)) return memoryFailure();
297
+ return engineFailure();
298
+ } finally {
299
+ message.dispose();
300
+ }
301
+ }
302
+ const raw: unknown = timed(() => JSON.parse(vm.getString(detail.value)));
303
+ const expired = check();
304
+ if (expired) return expired;
305
+ if (typeof raw !== "object" || raw === null) return engineFailure();
306
+ const name = "name" in raw && typeof raw.name === "string" ? raw.name : "";
307
+ const message =
308
+ "message" in raw && typeof raw.message === "string" && raw.message
309
+ ? raw.message
310
+ : "The program threw an error.";
311
+ const stack = "stack" in raw && typeof raw.stack === "string" ? raw.stack : "";
312
+ if (name === "InternalError" && /out of memory|memory alloc/i.test(message)) {
313
+ return memoryFailure();
314
+ }
315
+ if (name === "InternalError" && /stack overflow/i.test(message)) {
316
+ return stackFailure();
317
+ }
318
+ const error = fail(name === "SyntaxError" ? "SyntaxError" : "ProgramError", message);
319
+ const line = /program\.js:(\d+)/.exec(stack)?.[1];
320
+ if (line) error.error.line = Number(line);
321
+ return error;
322
+ } finally {
323
+ detail.dispose();
324
+ }
325
+ };
326
+
327
+ const hostCall = vm.newFunction("__pk_call", (nameHandle, inputHandle) => {
328
+ if (finished || check()) return vm.undefined;
329
+ if (
330
+ !nameHandle ||
331
+ !inputHandle ||
332
+ vm.typeof(nameHandle) !== "string" ||
333
+ vm.typeof(inputHandle) !== "string"
334
+ ) {
335
+ stop(fail("ProgramError", "The call bridge needs a tool name and JSON input as strings."));
336
+ return vm.undefined;
337
+ }
338
+ const name = readString(nameHandle);
339
+ const input = readString(inputHandle);
340
+ if (check() || name === undefined || input === undefined) return vm.undefined;
341
+ const deferred = vm.newPromise();
342
+ pending.add(deferred);
343
+ // A callback only queues strings. No late completion can touch a VM handle
344
+ // or pump jobs after cleanup, and a host failure never repeats a call.
345
+ try {
346
+ void Promise.resolve(job.call(name, input)).then(
347
+ (text) => {
348
+ if (finished || check()) return;
349
+ if (typeof text !== "string") {
350
+ stop(engineFailure());
351
+ return;
352
+ }
353
+ replies.push({ deferred, text });
354
+ notify();
355
+ },
356
+ () => {
357
+ if (!finished) stop(engineFailure());
358
+ },
359
+ );
360
+ } catch {
361
+ stop(engineFailure());
362
+ }
363
+ return deferred.handle;
364
+ });
365
+ try {
366
+ vm.setProp(vm.global, "__pk_call", hostCall);
367
+ } finally {
368
+ hostCall.dispose();
369
+ }
370
+ const hostLog = vm.newFunction("__pk_log", (text) => {
371
+ if (finished || check()) return;
372
+ if (!text || vm.typeof(text) !== "string") {
373
+ stop(fail("ProgramError", "The log bridge needs a string."));
374
+ return;
375
+ }
376
+ const message = readString(text);
377
+ if (!check() && message !== undefined) {
378
+ try {
379
+ job.log(message);
380
+ } catch {
381
+ stop(engineFailure());
382
+ }
383
+ }
384
+ });
385
+ try {
386
+ vm.setProp(vm.global, "__pk_log", hostLog);
387
+ } finally {
388
+ hostLog.dispose();
389
+ }
390
+
391
+ rt.setMemoryLimit(job.memoryBytes);
392
+ rt.setMaxStackSize(job.stackBytes);
393
+ rt.setInterruptHandler(() => Boolean(check()));
394
+ const evaluated = timed(() => vm.evalCode(job.script, "program.js", { type: "global" }));
395
+ if (evaluated.error) {
396
+ try {
397
+ result = readError(evaluated.error);
398
+ } finally {
399
+ evaluated.dispose();
400
+ }
401
+ } else {
402
+ owned.push(evaluated.value);
403
+ let jobsSinceYield = 0;
404
+ while (true) {
405
+ const stopped = check();
406
+ if (stopped) {
407
+ result = stopped;
408
+ break;
409
+ }
410
+ // Inspect the real promise directly, rather than installing host result
411
+ // callbacks which can retain a result handle when cancellation wins.
412
+ const state = timed(() => vm.getPromiseState(evaluated.value));
413
+ if (state.type !== "pending") {
414
+ finished = true;
415
+ try {
416
+ if (state.type === "rejected") result = readError(state.error);
417
+ else if (vm.typeof(state.value) !== "string") {
418
+ result = fail("ProgramError", "The SDK script must return a JSON envelope string.");
419
+ } else {
420
+ const envelope = timed(() => readString(state.value));
421
+ result =
422
+ check() ?? (envelope === undefined ? engineFailure() : { ok: true, envelope });
423
+ }
424
+ } finally {
425
+ // For non-promises getPromiseState returns the original handle.
426
+ if (state.type === "rejected") state.error.dispose();
427
+ else if (!state.notAPromise) state.value.dispose();
428
+ }
429
+ break;
430
+ }
431
+ // Check settlement before yielding, too: detached jobs cannot change a
432
+ // completed result or start host work during the cleanup drain.
433
+ if (jobsSinceYield === JOBS_PER_PUMP) {
434
+ jobsSinceYield = 0;
435
+ // Short jobs may never reach the VM interrupt counter. Give host aborts
436
+ // and deadline timers a turn after each bounded batch.
437
+ await new Promise<void>((resolve) => setTimeout(resolve, 0));
438
+ continue;
439
+ }
440
+ const awakened = new Promise<void>((resolve) => (notify = resolve));
441
+ const ready = replies.splice(0);
442
+ for (const { deferred, text } of ready) {
443
+ if (check()) break;
444
+ timed(() => {
445
+ const encoded = vm.newString(JSON.stringify(text));
446
+ try {
447
+ if (vm.typeof(encoded) !== "string") {
448
+ stop(memoryFailure());
449
+ return;
450
+ }
451
+ const value = vm.callFunction(decode, vm.undefined, encoded);
452
+ try {
453
+ if (value.error) {
454
+ stop(check() ?? memoryFailure());
455
+ return;
456
+ }
457
+ deferred.resolve(value.value);
458
+ } finally {
459
+ value.dispose();
460
+ }
461
+ } finally {
462
+ encoded.dispose();
463
+ }
464
+ deferred.dispose();
465
+ pending.delete(deferred);
466
+ });
467
+ }
468
+ if (check() || ready.length) continue;
469
+ if (rt.hasPendingJob()) {
470
+ // A single job can settle the root and leave detached work behind it.
471
+ const jobs = timed(() => rt.executePendingJobs(1));
472
+ jobsSinceYield++;
473
+ try {
474
+ if (jobs.error) {
475
+ result = readError(jobs.error);
476
+ break;
477
+ }
478
+ } finally {
479
+ jobs.dispose();
480
+ }
481
+ } else {
482
+ await awakened;
483
+ }
484
+ }
485
+ }
486
+ } catch {
487
+ failEngine();
488
+ result = checkWall() ?? engineFailure();
489
+ } finally {
490
+ finished = true;
491
+ onWake(() => {});
492
+ replies.length = 0;
493
+ const free = (action: () => void) => {
494
+ try {
495
+ action();
496
+ } catch {
497
+ cleanupFailed = true;
498
+ breakModule();
499
+ }
500
+ };
501
+ for (const deferred of pending) free(() => deferred.dispose());
502
+ pending.clear();
503
+ for (const handle of owned.reverse()) free(() => handle.dispose());
504
+ owned.length = 0;
505
+ if (runtime) {
506
+ const rt = runtime;
507
+ free(() => {
508
+ const deadline = performance.now() + 50;
509
+ rt.setInterruptHandler(() => performance.now() >= deadline);
510
+ for (let pass = 0; pass < 10 && performance.now() < deadline; pass++) {
511
+ const jobs = rt.executePendingJobs(JOBS_PER_PUMP);
512
+ const empty = !jobs.error && jobs.value === 0;
513
+ jobs.dispose();
514
+ if (empty) break;
515
+ }
516
+ });
517
+ // No guest code runs after this point. Freeing an OOM heap may allocate.
518
+ free(() => rt.setMemoryLimit(-1));
519
+ free(() => context?.dispose());
520
+ free(() => rt.dispose());
521
+ }
522
+ }
523
+ return cleanupFailed ? engineFailure() : result;
524
+ }
@@ -0,0 +1,90 @@
1
+ import { EMPTY_USAGE, addUsage, type TokenUsage, type Tool } from "@providerkit/core";
2
+ import { requestHash } from "./request.ts";
3
+ import { copyData, isId, isNames, isRecord } from "./snapshot.ts";
4
+ import { fail } from "./tree.ts";
5
+ import type { ModelExecution, RecoveryDefinition, RecoveryPolicy } from "./types.ts";
6
+
7
+ export function isRecoveryPolicy(value: unknown): value is RecoveryPolicy {
8
+ return (
9
+ isRecord(value) &&
10
+ Object.keys(value).every((key) =>
11
+ ["identity", "maxAttempts", "inferenceOnly", "readOnlyTools"].includes(key),
12
+ ) &&
13
+ isId(value.identity) &&
14
+ typeof value.maxAttempts === "number" &&
15
+ Number.isSafeInteger(value.maxAttempts) &&
16
+ value.maxAttempts > 0 &&
17
+ (value.inferenceOnly === undefined || typeof value.inferenceOnly === "boolean") &&
18
+ (value.readOnlyTools === undefined || isNames(value.readOnlyTools))
19
+ );
20
+ }
21
+
22
+ export function readRecoveryPolicy(value: unknown): RecoveryPolicy | null {
23
+ if (value === undefined) return null;
24
+ if (!isRecoveryPolicy(value))
25
+ throw new TypeError(
26
+ "Recovery needs an identity, a positive maxAttempts and explicit inference-only or read-only permissions.",
27
+ );
28
+ return copyData(value);
29
+ }
30
+
31
+ export function isRecoveryDefinition(value: unknown): value is RecoveryDefinition | null {
32
+ if (value === null) return true;
33
+ if (!isRecord(value)) return false;
34
+ const { policy, provider, toolHashes } = value;
35
+ return (
36
+ isRecoveryPolicy(policy) &&
37
+ isRecord(provider) &&
38
+ isId(provider.id) &&
39
+ isId(provider.model) &&
40
+ typeof value.modelToolsHash === "string" &&
41
+ /^sha256:[a-f0-9]{64}$/.test(value.modelToolsHash) &&
42
+ isRecord(toolHashes) &&
43
+ Object.entries(toolHashes).every(
44
+ ([name, hash]) =>
45
+ policy.readOnlyTools?.includes(name) &&
46
+ typeof hash === "string" &&
47
+ /^sha256:[a-f0-9]{64}$/.test(hash),
48
+ ) &&
49
+ (policy.readOnlyTools ?? []).every((name) => Object.hasOwn(toolHashes, name))
50
+ );
51
+ }
52
+
53
+ export function recoveryToolHash(tool: Tool): Promise<string> {
54
+ return requestHash({
55
+ definition: tool.definition(),
56
+ isReadOnly: tool.isReadOnly,
57
+ needsApproval: tool.needsApproval,
58
+ isTerminal: tool.isTerminal,
59
+ isConcurrencySafe: tool.isConcurrencySafe,
60
+ timeoutMs: tool.timeoutMs,
61
+ });
62
+ }
63
+
64
+ export function requireRecovery(
65
+ allowed: boolean,
66
+ previous: number,
67
+ definition: RecoveryDefinition | null,
68
+ operationId: string,
69
+ ): void {
70
+ if (!allowed || !definition)
71
+ fail(
72
+ "interrupted_operation",
73
+ "This operation started but has no saved result. Reconcile it with the host; its recovery policy does not allow replay.",
74
+ operationId,
75
+ );
76
+ if (previous + 1 >= definition.policy.maxAttempts)
77
+ fail(
78
+ "recovery_exhausted",
79
+ "This operation reached its recovery attempt limit. Reconcile the saved attempts with the host.",
80
+ operationId,
81
+ );
82
+ }
83
+
84
+ export function modelUsage(model: ModelExecution): TokenUsage {
85
+ return model.interrupted.reduce((total, attempt) => addUsage(total, attempt.usage), model.usage);
86
+ }
87
+
88
+ export function modelsUsage(models: readonly ModelExecution[]): TokenUsage {
89
+ return models.reduce((total, model) => addUsage(total, modelUsage(model)), { ...EMPTY_USAGE });
90
+ }