@langchain/quickjs 1.0.0-alpha.0 → 1.0.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.
- package/README.md +11 -4
- package/dist/index.cjs +866 -277
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +189 -52
- package/dist/index.d.ts +189 -52
- package/dist/index.js +860 -275
- package/dist/index.js.map +1 -1
- package/package.json +11 -10
package/dist/index.d.cts
CHANGED
|
@@ -1,40 +1,23 @@
|
|
|
1
|
-
import * as langchain from "langchain";
|
|
2
1
|
import { AgentMiddleware } from "langchain";
|
|
3
2
|
import { z } from "zod/v4";
|
|
4
3
|
import { StructuredToolInterface } from "@langchain/core/tools";
|
|
5
|
-
import { AnyBackendProtocol, BackendFactory, BackendProtocolV2 } from "deepagents";
|
|
6
|
-
|
|
7
4
|
//#region src/types.d.ts
|
|
8
5
|
/**
|
|
9
|
-
* Configuration options for the
|
|
6
|
+
* Configuration options for the Code Interpreter middleware.
|
|
10
7
|
*/
|
|
11
|
-
interface
|
|
12
|
-
/**
|
|
13
|
-
* Backend for file I/O (readFile/writeFile) inside the REPL.
|
|
14
|
-
* Accepts a AnyBackendProtocol instance or a BackendFactory function.
|
|
15
|
-
* Defaults to StateBackend (reads/writes LangGraph checkpoint state).
|
|
16
|
-
* @default StateBackend
|
|
17
|
-
*/
|
|
18
|
-
backend?: AnyBackendProtocol | BackendFactory;
|
|
8
|
+
interface CodeInterpreterMiddlewareOptions {
|
|
19
9
|
/**
|
|
20
10
|
* Enable programmatic tool calling from within the REPL.
|
|
21
11
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
* - `string[]` — expose only these tools (alias for `{ include }`)
|
|
25
|
-
* - `{ include: string[] }` — expose only these tools
|
|
26
|
-
* - `{ exclude: string[] }` — expose all agent tools except these
|
|
12
|
+
* Array of tools to expose; strings are resolved from agent tools, instances
|
|
13
|
+
* are injected directly without needing to be registered on the agent.
|
|
27
14
|
*
|
|
28
|
-
*
|
|
15
|
+
* Omit to disable PTC entirely (default).
|
|
29
16
|
*/
|
|
30
|
-
ptc?:
|
|
31
|
-
include: string[];
|
|
32
|
-
} | {
|
|
33
|
-
exclude: string[];
|
|
34
|
-
};
|
|
17
|
+
ptc?: (string | StructuredToolInterface)[];
|
|
35
18
|
/**
|
|
36
19
|
* Memory limit in bytes.
|
|
37
|
-
* @default
|
|
20
|
+
* @default 67108864 (64MB)
|
|
38
21
|
*/
|
|
39
22
|
memoryLimitBytes?: number;
|
|
40
23
|
/**
|
|
@@ -45,7 +28,7 @@ interface QuickJSMiddlewareOptions {
|
|
|
45
28
|
/**
|
|
46
29
|
* Execution timeout in milliseconds per evaluation.
|
|
47
30
|
* Set to a negative value to disable the timeout entirely.
|
|
48
|
-
* @default
|
|
31
|
+
* @default 5000 (5s)
|
|
49
32
|
*/
|
|
50
33
|
executionTimeoutMs?: number;
|
|
51
34
|
/**
|
|
@@ -53,6 +36,77 @@ interface QuickJSMiddlewareOptions {
|
|
|
53
36
|
* @default null (uses built-in prompt)
|
|
54
37
|
*/
|
|
55
38
|
systemPrompt?: string | null;
|
|
39
|
+
/**
|
|
40
|
+
* Maximum number of `tools.*` bridge calls allowed per `eval()` invocation.
|
|
41
|
+
*
|
|
42
|
+
* Each call to any function in the `tools` namespace decrements the counter.
|
|
43
|
+
* Once exhausted the next call rejects with a `PTCCallBudgetExceeded` error.
|
|
44
|
+
* The budget resets to this value at the start of every new `eval()` call.
|
|
45
|
+
*
|
|
46
|
+
* Set to `null` to disable the limit entirely (unsafe — increases DoS risk).
|
|
47
|
+
* Must be >= 1 when provided as a number.
|
|
48
|
+
*
|
|
49
|
+
* @default 256
|
|
50
|
+
*/
|
|
51
|
+
maxPtcCalls?: number | null;
|
|
52
|
+
/**
|
|
53
|
+
* Maximum characters to retain from console output per evaluation.
|
|
54
|
+
* Output exceeding this limit is dropped at capture time and a
|
|
55
|
+
* `[truncated N chars]` marker is appended to the tool response.
|
|
56
|
+
* The same limit also caps result and error strings in the formatted output.
|
|
57
|
+
*
|
|
58
|
+
* @default 4000
|
|
59
|
+
*/
|
|
60
|
+
maxResultChars?: number;
|
|
61
|
+
/**
|
|
62
|
+
* Name of the tool exposed to the model.
|
|
63
|
+
* @default "eval"
|
|
64
|
+
*/
|
|
65
|
+
toolName?: string;
|
|
66
|
+
/**
|
|
67
|
+
* If true, install a `console` object that buffers `console.log/warn/error`
|
|
68
|
+
* calls and emits them alongside the result. If false, console output is
|
|
69
|
+
* silently discarded.
|
|
70
|
+
* @default true
|
|
71
|
+
*/
|
|
72
|
+
captureConsole?: boolean;
|
|
73
|
+
/**
|
|
74
|
+
* Expose the built-in `task()` global for subagent orchestration.
|
|
75
|
+
*
|
|
76
|
+
* When `true` (default) and subagent specs are available, a `task()`
|
|
77
|
+
* global is installed in the REPL that dispatches subagents
|
|
78
|
+
* programmatically with a fixed concurrency cap of 32.
|
|
79
|
+
* Set to `false` to require subagent dispatch through the normal
|
|
80
|
+
* `task` tool path.
|
|
81
|
+
*
|
|
82
|
+
* @default true
|
|
83
|
+
*/
|
|
84
|
+
subagents?: boolean;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Configuration for the built-in subagent primitive.
|
|
88
|
+
*
|
|
89
|
+
* When provided to a ReplSession, a frozen `subagent()` global is
|
|
90
|
+
* installed in the QuickJS context. Calls are gated by a concurrency
|
|
91
|
+
* queue and forwarded to the dispatch callback.
|
|
92
|
+
*/
|
|
93
|
+
interface SubagentBridgeOptions {
|
|
94
|
+
/**
|
|
95
|
+
* Callback that invokes a subagent. Receives validated input from
|
|
96
|
+
* the QuickJS guest and returns the subagent's output — a string
|
|
97
|
+
* for text responses or an object for structured (responseSchema)
|
|
98
|
+
* responses.
|
|
99
|
+
*/
|
|
100
|
+
dispatch: (input: {
|
|
101
|
+
description: string;
|
|
102
|
+
subagentType: string;
|
|
103
|
+
responseSchema?: Record<string, unknown>;
|
|
104
|
+
}) => Promise<unknown>;
|
|
105
|
+
/**
|
|
106
|
+
* Maximum number of concurrent subagent calls within a single eval.
|
|
107
|
+
* Excess calls queue and resolve as permits free up.
|
|
108
|
+
*/
|
|
109
|
+
maxConcurrency: number;
|
|
56
110
|
}
|
|
57
111
|
/**
|
|
58
112
|
* Options for creating a ReplSession.
|
|
@@ -60,8 +114,12 @@ interface QuickJSMiddlewareOptions {
|
|
|
60
114
|
interface ReplSessionOptions {
|
|
61
115
|
memoryLimitBytes?: number;
|
|
62
116
|
maxStackSizeBytes?: number;
|
|
63
|
-
backend?: AnyBackendProtocol;
|
|
64
117
|
tools?: StructuredToolInterface[];
|
|
118
|
+
maxPtcCalls?: number | null;
|
|
119
|
+
maxResultChars?: number;
|
|
120
|
+
captureConsole?: boolean;
|
|
121
|
+
sessionId?: string;
|
|
122
|
+
subagentBridge?: SubagentBridgeOptions;
|
|
65
123
|
}
|
|
66
124
|
/**
|
|
67
125
|
* Result of a single REPL evaluation.
|
|
@@ -75,34 +133,54 @@ interface ReplResult {
|
|
|
75
133
|
stack?: string;
|
|
76
134
|
};
|
|
77
135
|
logs: string[];
|
|
136
|
+
logsDroppedChars: number;
|
|
78
137
|
}
|
|
79
138
|
//#endregion
|
|
80
139
|
//#region src/middleware.d.ts
|
|
81
140
|
/**
|
|
82
|
-
*
|
|
83
|
-
* These are redundant inside the REPL since VFS helpers (readFile/writeFile)
|
|
84
|
-
* already cover file I/O against the agent's in-memory working set.
|
|
141
|
+
* Create the Code Interpreter middleware.
|
|
85
142
|
*/
|
|
86
|
-
declare
|
|
87
|
-
/**
|
|
88
|
-
* Create the QuickJS REPL middleware.
|
|
89
|
-
*/
|
|
90
|
-
declare function createQuickJSMiddleware(options?: QuickJSMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [langchain.DynamicStructuredTool<z.ZodObject<{
|
|
143
|
+
declare function createCodeInterpreterMiddleware(options?: CodeInterpreterMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
|
|
91
144
|
code: z.ZodString;
|
|
92
145
|
}, z.core.$strip>, {
|
|
93
146
|
code: string;
|
|
94
147
|
}, {
|
|
95
148
|
code: string;
|
|
96
|
-
}, string, unknown,
|
|
149
|
+
}, string, unknown, string>], readonly []>;
|
|
150
|
+
//#endregion
|
|
151
|
+
//#region src/errors.d.ts
|
|
152
|
+
/**
|
|
153
|
+
* Options for constructing a {@link PTCCallBudgetExceededError}.
|
|
154
|
+
*/
|
|
155
|
+
interface PTCCallBudgetExceededOptions {
|
|
156
|
+
/**
|
|
157
|
+
* The configured per-eval PTC call limit.
|
|
158
|
+
*/
|
|
159
|
+
limit: number;
|
|
160
|
+
/**
|
|
161
|
+
* The call number that triggered the violation (always `limit + 1`).
|
|
162
|
+
*/
|
|
163
|
+
attempted: number;
|
|
164
|
+
/**
|
|
165
|
+
* The name of the tool function that was called over budget.
|
|
166
|
+
*/
|
|
167
|
+
functionName: string;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Thrown when a single eval exhausts its configured PTC call budget.
|
|
171
|
+
*/
|
|
172
|
+
declare class PTCCallBudgetExceededError extends Error {
|
|
173
|
+
readonly limit: number;
|
|
174
|
+
readonly attempted: number;
|
|
175
|
+
readonly functionName: string;
|
|
176
|
+
constructor(options: PTCCallBudgetExceededOptions);
|
|
177
|
+
}
|
|
97
178
|
//#endregion
|
|
98
179
|
//#region src/session.d.ts
|
|
99
180
|
declare const DEFAULT_MEMORY_LIMIT: number;
|
|
100
181
|
declare const DEFAULT_MAX_STACK_SIZE: number;
|
|
101
|
-
declare const DEFAULT_EXECUTION_TIMEOUT =
|
|
102
|
-
|
|
103
|
-
path: string;
|
|
104
|
-
content: string;
|
|
105
|
-
}
|
|
182
|
+
declare const DEFAULT_EXECUTION_TIMEOUT = 5000;
|
|
183
|
+
declare const DEFAULT_MAX_PTC_CALLS = 256;
|
|
106
184
|
/**
|
|
107
185
|
* Sandboxed JavaScript REPL session backed by QuickJS WASM.
|
|
108
186
|
*
|
|
@@ -110,23 +188,39 @@ interface PendingWrite {
|
|
|
110
188
|
* The QuickJS runtime is lazily started on the first `.eval()` call
|
|
111
189
|
* and reconnected if a session with the same id already exists.
|
|
112
190
|
* This makes it safe to store in LangGraph state across interrupts.
|
|
113
|
-
*
|
|
114
|
-
* File writes are buffered during execution and flushed via
|
|
115
|
-
* `flushWrites(backend)` after eval completes.
|
|
116
191
|
*/
|
|
117
192
|
declare class ReplSession {
|
|
118
193
|
private static sessions;
|
|
119
194
|
readonly id: string;
|
|
120
|
-
readonly pendingWrites: PendingWrite[];
|
|
121
195
|
private runtime;
|
|
122
196
|
private context;
|
|
123
|
-
private
|
|
124
|
-
private
|
|
125
|
-
private
|
|
197
|
+
private consoleBuffer;
|
|
198
|
+
private options;
|
|
199
|
+
private readonly maxPtcCalls;
|
|
200
|
+
private ptcCallsRemaining;
|
|
201
|
+
private subagentQueue;
|
|
202
|
+
private bridgeDispatchRef;
|
|
203
|
+
/** Allowed keys in the subagent input object. */
|
|
204
|
+
private static readonly SUBAGENT_ALLOWED_KEYS;
|
|
205
|
+
/**
|
|
206
|
+
* Reset the shared WASM module. Forces the next session to instantiate
|
|
207
|
+
* a fresh module. Only needed in tests where module state must be
|
|
208
|
+
* isolated between test files.
|
|
209
|
+
*
|
|
210
|
+
* @internal
|
|
211
|
+
*/
|
|
212
|
+
static resetSharedModule(): void;
|
|
126
213
|
constructor(id: string, options?: ReplSessionOptions);
|
|
127
|
-
get backend(): BackendProtocolV2 | null;
|
|
128
|
-
set backend(b: AnyBackendProtocol | null);
|
|
129
214
|
private ensureStarted;
|
|
215
|
+
/**
|
|
216
|
+
* Initialise the per-eval PTC counter. Called at the top of every `eval()`.
|
|
217
|
+
*/
|
|
218
|
+
private resetPtcBudget;
|
|
219
|
+
/**
|
|
220
|
+
* Decrement the PTC call counter and throw if the budget is exhausted.
|
|
221
|
+
* `null` budget means unlimited — returns immediately without decrementing.
|
|
222
|
+
*/
|
|
223
|
+
private consumePtcBudget;
|
|
130
224
|
/**
|
|
131
225
|
* Get or create a session for the given id.
|
|
132
226
|
*
|
|
@@ -139,6 +233,16 @@ declare class ReplSession {
|
|
|
139
233
|
* Retrieve an existing session by id, or null if none exists.
|
|
140
234
|
*/
|
|
141
235
|
static get(id: string): ReplSession | null;
|
|
236
|
+
/**
|
|
237
|
+
* Returns true if any session exists whose key equals `threadId` or starts
|
|
238
|
+
* with `threadId:`. Useful for tests that need to confirm a session was
|
|
239
|
+
* created without knowing the full `threadId:middlewareId` key.
|
|
240
|
+
*/
|
|
241
|
+
static hasAnyForThread(threadId: string): boolean;
|
|
242
|
+
/**
|
|
243
|
+
* Dispose and remove the session with the given key, if it exists.
|
|
244
|
+
*/
|
|
245
|
+
static deleteSession(key: string): void;
|
|
142
246
|
/**
|
|
143
247
|
* Evaluate code in this session.
|
|
144
248
|
*
|
|
@@ -149,7 +253,6 @@ declare class ReplSession {
|
|
|
149
253
|
* async IIFE.
|
|
150
254
|
*/
|
|
151
255
|
eval(code: string, timeoutMs: number): Promise<ReplResult>;
|
|
152
|
-
flushWrites(backend: AnyBackendProtocol): Promise<void>;
|
|
153
256
|
dispose(): void;
|
|
154
257
|
toJSON(): {
|
|
155
258
|
id: string;
|
|
@@ -163,8 +266,24 @@ declare class ReplSession {
|
|
|
163
266
|
*/
|
|
164
267
|
static clearCache(): void;
|
|
165
268
|
private setupConsole;
|
|
166
|
-
private injectVfs;
|
|
167
269
|
private injectTools;
|
|
270
|
+
/**
|
|
271
|
+
* Install the `task` global on the QuickJS context.
|
|
272
|
+
*
|
|
273
|
+
* Registers the host function directly as `globalThis.task`,
|
|
274
|
+
* then freezes it via `evalCode`. Structured results (when
|
|
275
|
+
* responseSchema is provided) are marshaled into native QuickJS
|
|
276
|
+
* objects on the host side — no JS wrapper needed.
|
|
277
|
+
*/
|
|
278
|
+
/**
|
|
279
|
+
* Replace the active bridge dispatch with a fresh one.
|
|
280
|
+
*
|
|
281
|
+
* Call this before each eval so the dispatch closure carries
|
|
282
|
+
* the current invocation's config (tracing callbacks, run ID, etc.)
|
|
283
|
+
* rather than the stale config from session creation.
|
|
284
|
+
*/
|
|
285
|
+
updateBridgeDispatch(dispatch: SubagentBridgeOptions["dispatch"]): void;
|
|
286
|
+
private injectSubagentBridge;
|
|
168
287
|
}
|
|
169
288
|
//#endregion
|
|
170
289
|
//#region src/utils.d.ts
|
|
@@ -199,6 +318,24 @@ declare function formatReplResult(result: ReplResult): string;
|
|
|
199
318
|
* - Wraps in async IIFE for top-level await support
|
|
200
319
|
*/
|
|
201
320
|
declare function transformForEval(code: string): string;
|
|
321
|
+
/**
|
|
322
|
+
* Strip TypeScript type syntax from an ES-module source so QuickJS can
|
|
323
|
+
* evaluate it as a standard JS module.
|
|
324
|
+
*
|
|
325
|
+
* Unlike `transformForEval`, this keeps `import`/`export` declarations,
|
|
326
|
+
* does not hoist to `globalThis`, and does not wrap in an IIFE.
|
|
327
|
+
* On parse failure the original source is returned unchanged.
|
|
328
|
+
*/
|
|
329
|
+
declare function stripTypeSyntax(code: string): string;
|
|
330
|
+
//#endregion
|
|
331
|
+
//#region src/subagent-dispatch.d.ts
|
|
332
|
+
/**
|
|
333
|
+
* Validate that a response schema does not exceed size, depth, or
|
|
334
|
+
* property-count limits.
|
|
335
|
+
*
|
|
336
|
+
* @throws Error if any limit is exceeded.
|
|
337
|
+
*/
|
|
338
|
+
declare function validateResponseSchema(schema: Record<string, unknown>): void;
|
|
202
339
|
//#endregion
|
|
203
|
-
export {
|
|
340
|
+
export { type CodeInterpreterMiddlewareOptions, DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, PTCCallBudgetExceededError, type ReplResult, ReplSession, type ReplSessionOptions, type SubagentBridgeOptions, createCodeInterpreterMiddleware, formatReplResult, stripTypeSyntax, toCamelCase, transformForEval, validateResponseSchema };
|
|
204
341
|
//# sourceMappingURL=index.d.cts.map
|
package/dist/index.d.ts
CHANGED
|
@@ -1,40 +1,23 @@
|
|
|
1
|
-
import * as langchain from "langchain";
|
|
2
1
|
import { AgentMiddleware } from "langchain";
|
|
3
2
|
import { z } from "zod/v4";
|
|
4
|
-
import { AnyBackendProtocol, BackendFactory, BackendProtocolV2 } from "deepagents";
|
|
5
3
|
import { StructuredToolInterface } from "@langchain/core/tools";
|
|
6
|
-
|
|
7
4
|
//#region src/types.d.ts
|
|
8
5
|
/**
|
|
9
|
-
* Configuration options for the
|
|
6
|
+
* Configuration options for the Code Interpreter middleware.
|
|
10
7
|
*/
|
|
11
|
-
interface
|
|
12
|
-
/**
|
|
13
|
-
* Backend for file I/O (readFile/writeFile) inside the REPL.
|
|
14
|
-
* Accepts a AnyBackendProtocol instance or a BackendFactory function.
|
|
15
|
-
* Defaults to StateBackend (reads/writes LangGraph checkpoint state).
|
|
16
|
-
* @default StateBackend
|
|
17
|
-
*/
|
|
18
|
-
backend?: AnyBackendProtocol | BackendFactory;
|
|
8
|
+
interface CodeInterpreterMiddlewareOptions {
|
|
19
9
|
/**
|
|
20
10
|
* Enable programmatic tool calling from within the REPL.
|
|
21
11
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
* - `string[]` — expose only these tools (alias for `{ include }`)
|
|
25
|
-
* - `{ include: string[] }` — expose only these tools
|
|
26
|
-
* - `{ exclude: string[] }` — expose all agent tools except these
|
|
12
|
+
* Array of tools to expose; strings are resolved from agent tools, instances
|
|
13
|
+
* are injected directly without needing to be registered on the agent.
|
|
27
14
|
*
|
|
28
|
-
*
|
|
15
|
+
* Omit to disable PTC entirely (default).
|
|
29
16
|
*/
|
|
30
|
-
ptc?:
|
|
31
|
-
include: string[];
|
|
32
|
-
} | {
|
|
33
|
-
exclude: string[];
|
|
34
|
-
};
|
|
17
|
+
ptc?: (string | StructuredToolInterface)[];
|
|
35
18
|
/**
|
|
36
19
|
* Memory limit in bytes.
|
|
37
|
-
* @default
|
|
20
|
+
* @default 67108864 (64MB)
|
|
38
21
|
*/
|
|
39
22
|
memoryLimitBytes?: number;
|
|
40
23
|
/**
|
|
@@ -45,7 +28,7 @@ interface QuickJSMiddlewareOptions {
|
|
|
45
28
|
/**
|
|
46
29
|
* Execution timeout in milliseconds per evaluation.
|
|
47
30
|
* Set to a negative value to disable the timeout entirely.
|
|
48
|
-
* @default
|
|
31
|
+
* @default 5000 (5s)
|
|
49
32
|
*/
|
|
50
33
|
executionTimeoutMs?: number;
|
|
51
34
|
/**
|
|
@@ -53,6 +36,77 @@ interface QuickJSMiddlewareOptions {
|
|
|
53
36
|
* @default null (uses built-in prompt)
|
|
54
37
|
*/
|
|
55
38
|
systemPrompt?: string | null;
|
|
39
|
+
/**
|
|
40
|
+
* Maximum number of `tools.*` bridge calls allowed per `eval()` invocation.
|
|
41
|
+
*
|
|
42
|
+
* Each call to any function in the `tools` namespace decrements the counter.
|
|
43
|
+
* Once exhausted the next call rejects with a `PTCCallBudgetExceeded` error.
|
|
44
|
+
* The budget resets to this value at the start of every new `eval()` call.
|
|
45
|
+
*
|
|
46
|
+
* Set to `null` to disable the limit entirely (unsafe — increases DoS risk).
|
|
47
|
+
* Must be >= 1 when provided as a number.
|
|
48
|
+
*
|
|
49
|
+
* @default 256
|
|
50
|
+
*/
|
|
51
|
+
maxPtcCalls?: number | null;
|
|
52
|
+
/**
|
|
53
|
+
* Maximum characters to retain from console output per evaluation.
|
|
54
|
+
* Output exceeding this limit is dropped at capture time and a
|
|
55
|
+
* `[truncated N chars]` marker is appended to the tool response.
|
|
56
|
+
* The same limit also caps result and error strings in the formatted output.
|
|
57
|
+
*
|
|
58
|
+
* @default 4000
|
|
59
|
+
*/
|
|
60
|
+
maxResultChars?: number;
|
|
61
|
+
/**
|
|
62
|
+
* Name of the tool exposed to the model.
|
|
63
|
+
* @default "eval"
|
|
64
|
+
*/
|
|
65
|
+
toolName?: string;
|
|
66
|
+
/**
|
|
67
|
+
* If true, install a `console` object that buffers `console.log/warn/error`
|
|
68
|
+
* calls and emits them alongside the result. If false, console output is
|
|
69
|
+
* silently discarded.
|
|
70
|
+
* @default true
|
|
71
|
+
*/
|
|
72
|
+
captureConsole?: boolean;
|
|
73
|
+
/**
|
|
74
|
+
* Expose the built-in `task()` global for subagent orchestration.
|
|
75
|
+
*
|
|
76
|
+
* When `true` (default) and subagent specs are available, a `task()`
|
|
77
|
+
* global is installed in the REPL that dispatches subagents
|
|
78
|
+
* programmatically with a fixed concurrency cap of 32.
|
|
79
|
+
* Set to `false` to require subagent dispatch through the normal
|
|
80
|
+
* `task` tool path.
|
|
81
|
+
*
|
|
82
|
+
* @default true
|
|
83
|
+
*/
|
|
84
|
+
subagents?: boolean;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Configuration for the built-in subagent primitive.
|
|
88
|
+
*
|
|
89
|
+
* When provided to a ReplSession, a frozen `subagent()` global is
|
|
90
|
+
* installed in the QuickJS context. Calls are gated by a concurrency
|
|
91
|
+
* queue and forwarded to the dispatch callback.
|
|
92
|
+
*/
|
|
93
|
+
interface SubagentBridgeOptions {
|
|
94
|
+
/**
|
|
95
|
+
* Callback that invokes a subagent. Receives validated input from
|
|
96
|
+
* the QuickJS guest and returns the subagent's output — a string
|
|
97
|
+
* for text responses or an object for structured (responseSchema)
|
|
98
|
+
* responses.
|
|
99
|
+
*/
|
|
100
|
+
dispatch: (input: {
|
|
101
|
+
description: string;
|
|
102
|
+
subagentType: string;
|
|
103
|
+
responseSchema?: Record<string, unknown>;
|
|
104
|
+
}) => Promise<unknown>;
|
|
105
|
+
/**
|
|
106
|
+
* Maximum number of concurrent subagent calls within a single eval.
|
|
107
|
+
* Excess calls queue and resolve as permits free up.
|
|
108
|
+
*/
|
|
109
|
+
maxConcurrency: number;
|
|
56
110
|
}
|
|
57
111
|
/**
|
|
58
112
|
* Options for creating a ReplSession.
|
|
@@ -60,8 +114,12 @@ interface QuickJSMiddlewareOptions {
|
|
|
60
114
|
interface ReplSessionOptions {
|
|
61
115
|
memoryLimitBytes?: number;
|
|
62
116
|
maxStackSizeBytes?: number;
|
|
63
|
-
backend?: AnyBackendProtocol;
|
|
64
117
|
tools?: StructuredToolInterface[];
|
|
118
|
+
maxPtcCalls?: number | null;
|
|
119
|
+
maxResultChars?: number;
|
|
120
|
+
captureConsole?: boolean;
|
|
121
|
+
sessionId?: string;
|
|
122
|
+
subagentBridge?: SubagentBridgeOptions;
|
|
65
123
|
}
|
|
66
124
|
/**
|
|
67
125
|
* Result of a single REPL evaluation.
|
|
@@ -75,34 +133,54 @@ interface ReplResult {
|
|
|
75
133
|
stack?: string;
|
|
76
134
|
};
|
|
77
135
|
logs: string[];
|
|
136
|
+
logsDroppedChars: number;
|
|
78
137
|
}
|
|
79
138
|
//#endregion
|
|
80
139
|
//#region src/middleware.d.ts
|
|
81
140
|
/**
|
|
82
|
-
*
|
|
83
|
-
* These are redundant inside the REPL since VFS helpers (readFile/writeFile)
|
|
84
|
-
* already cover file I/O against the agent's in-memory working set.
|
|
141
|
+
* Create the Code Interpreter middleware.
|
|
85
142
|
*/
|
|
86
|
-
declare
|
|
87
|
-
/**
|
|
88
|
-
* Create the QuickJS REPL middleware.
|
|
89
|
-
*/
|
|
90
|
-
declare function createQuickJSMiddleware(options?: QuickJSMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [langchain.DynamicStructuredTool<z.ZodObject<{
|
|
143
|
+
declare function createCodeInterpreterMiddleware(options?: CodeInterpreterMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
|
|
91
144
|
code: z.ZodString;
|
|
92
145
|
}, z.core.$strip>, {
|
|
93
146
|
code: string;
|
|
94
147
|
}, {
|
|
95
148
|
code: string;
|
|
96
|
-
}, string, unknown,
|
|
149
|
+
}, string, unknown, string>], readonly []>;
|
|
150
|
+
//#endregion
|
|
151
|
+
//#region src/errors.d.ts
|
|
152
|
+
/**
|
|
153
|
+
* Options for constructing a {@link PTCCallBudgetExceededError}.
|
|
154
|
+
*/
|
|
155
|
+
interface PTCCallBudgetExceededOptions {
|
|
156
|
+
/**
|
|
157
|
+
* The configured per-eval PTC call limit.
|
|
158
|
+
*/
|
|
159
|
+
limit: number;
|
|
160
|
+
/**
|
|
161
|
+
* The call number that triggered the violation (always `limit + 1`).
|
|
162
|
+
*/
|
|
163
|
+
attempted: number;
|
|
164
|
+
/**
|
|
165
|
+
* The name of the tool function that was called over budget.
|
|
166
|
+
*/
|
|
167
|
+
functionName: string;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Thrown when a single eval exhausts its configured PTC call budget.
|
|
171
|
+
*/
|
|
172
|
+
declare class PTCCallBudgetExceededError extends Error {
|
|
173
|
+
readonly limit: number;
|
|
174
|
+
readonly attempted: number;
|
|
175
|
+
readonly functionName: string;
|
|
176
|
+
constructor(options: PTCCallBudgetExceededOptions);
|
|
177
|
+
}
|
|
97
178
|
//#endregion
|
|
98
179
|
//#region src/session.d.ts
|
|
99
180
|
declare const DEFAULT_MEMORY_LIMIT: number;
|
|
100
181
|
declare const DEFAULT_MAX_STACK_SIZE: number;
|
|
101
|
-
declare const DEFAULT_EXECUTION_TIMEOUT =
|
|
102
|
-
|
|
103
|
-
path: string;
|
|
104
|
-
content: string;
|
|
105
|
-
}
|
|
182
|
+
declare const DEFAULT_EXECUTION_TIMEOUT = 5000;
|
|
183
|
+
declare const DEFAULT_MAX_PTC_CALLS = 256;
|
|
106
184
|
/**
|
|
107
185
|
* Sandboxed JavaScript REPL session backed by QuickJS WASM.
|
|
108
186
|
*
|
|
@@ -110,23 +188,39 @@ interface PendingWrite {
|
|
|
110
188
|
* The QuickJS runtime is lazily started on the first `.eval()` call
|
|
111
189
|
* and reconnected if a session with the same id already exists.
|
|
112
190
|
* This makes it safe to store in LangGraph state across interrupts.
|
|
113
|
-
*
|
|
114
|
-
* File writes are buffered during execution and flushed via
|
|
115
|
-
* `flushWrites(backend)` after eval completes.
|
|
116
191
|
*/
|
|
117
192
|
declare class ReplSession {
|
|
118
193
|
private static sessions;
|
|
119
194
|
readonly id: string;
|
|
120
|
-
readonly pendingWrites: PendingWrite[];
|
|
121
195
|
private runtime;
|
|
122
196
|
private context;
|
|
123
|
-
private
|
|
124
|
-
private
|
|
125
|
-
private
|
|
197
|
+
private consoleBuffer;
|
|
198
|
+
private options;
|
|
199
|
+
private readonly maxPtcCalls;
|
|
200
|
+
private ptcCallsRemaining;
|
|
201
|
+
private subagentQueue;
|
|
202
|
+
private bridgeDispatchRef;
|
|
203
|
+
/** Allowed keys in the subagent input object. */
|
|
204
|
+
private static readonly SUBAGENT_ALLOWED_KEYS;
|
|
205
|
+
/**
|
|
206
|
+
* Reset the shared WASM module. Forces the next session to instantiate
|
|
207
|
+
* a fresh module. Only needed in tests where module state must be
|
|
208
|
+
* isolated between test files.
|
|
209
|
+
*
|
|
210
|
+
* @internal
|
|
211
|
+
*/
|
|
212
|
+
static resetSharedModule(): void;
|
|
126
213
|
constructor(id: string, options?: ReplSessionOptions);
|
|
127
|
-
get backend(): BackendProtocolV2 | null;
|
|
128
|
-
set backend(b: AnyBackendProtocol | null);
|
|
129
214
|
private ensureStarted;
|
|
215
|
+
/**
|
|
216
|
+
* Initialise the per-eval PTC counter. Called at the top of every `eval()`.
|
|
217
|
+
*/
|
|
218
|
+
private resetPtcBudget;
|
|
219
|
+
/**
|
|
220
|
+
* Decrement the PTC call counter and throw if the budget is exhausted.
|
|
221
|
+
* `null` budget means unlimited — returns immediately without decrementing.
|
|
222
|
+
*/
|
|
223
|
+
private consumePtcBudget;
|
|
130
224
|
/**
|
|
131
225
|
* Get or create a session for the given id.
|
|
132
226
|
*
|
|
@@ -139,6 +233,16 @@ declare class ReplSession {
|
|
|
139
233
|
* Retrieve an existing session by id, or null if none exists.
|
|
140
234
|
*/
|
|
141
235
|
static get(id: string): ReplSession | null;
|
|
236
|
+
/**
|
|
237
|
+
* Returns true if any session exists whose key equals `threadId` or starts
|
|
238
|
+
* with `threadId:`. Useful for tests that need to confirm a session was
|
|
239
|
+
* created without knowing the full `threadId:middlewareId` key.
|
|
240
|
+
*/
|
|
241
|
+
static hasAnyForThread(threadId: string): boolean;
|
|
242
|
+
/**
|
|
243
|
+
* Dispose and remove the session with the given key, if it exists.
|
|
244
|
+
*/
|
|
245
|
+
static deleteSession(key: string): void;
|
|
142
246
|
/**
|
|
143
247
|
* Evaluate code in this session.
|
|
144
248
|
*
|
|
@@ -149,7 +253,6 @@ declare class ReplSession {
|
|
|
149
253
|
* async IIFE.
|
|
150
254
|
*/
|
|
151
255
|
eval(code: string, timeoutMs: number): Promise<ReplResult>;
|
|
152
|
-
flushWrites(backend: AnyBackendProtocol): Promise<void>;
|
|
153
256
|
dispose(): void;
|
|
154
257
|
toJSON(): {
|
|
155
258
|
id: string;
|
|
@@ -163,8 +266,24 @@ declare class ReplSession {
|
|
|
163
266
|
*/
|
|
164
267
|
static clearCache(): void;
|
|
165
268
|
private setupConsole;
|
|
166
|
-
private injectVfs;
|
|
167
269
|
private injectTools;
|
|
270
|
+
/**
|
|
271
|
+
* Install the `task` global on the QuickJS context.
|
|
272
|
+
*
|
|
273
|
+
* Registers the host function directly as `globalThis.task`,
|
|
274
|
+
* then freezes it via `evalCode`. Structured results (when
|
|
275
|
+
* responseSchema is provided) are marshaled into native QuickJS
|
|
276
|
+
* objects on the host side — no JS wrapper needed.
|
|
277
|
+
*/
|
|
278
|
+
/**
|
|
279
|
+
* Replace the active bridge dispatch with a fresh one.
|
|
280
|
+
*
|
|
281
|
+
* Call this before each eval so the dispatch closure carries
|
|
282
|
+
* the current invocation's config (tracing callbacks, run ID, etc.)
|
|
283
|
+
* rather than the stale config from session creation.
|
|
284
|
+
*/
|
|
285
|
+
updateBridgeDispatch(dispatch: SubagentBridgeOptions["dispatch"]): void;
|
|
286
|
+
private injectSubagentBridge;
|
|
168
287
|
}
|
|
169
288
|
//#endregion
|
|
170
289
|
//#region src/utils.d.ts
|
|
@@ -199,6 +318,24 @@ declare function formatReplResult(result: ReplResult): string;
|
|
|
199
318
|
* - Wraps in async IIFE for top-level await support
|
|
200
319
|
*/
|
|
201
320
|
declare function transformForEval(code: string): string;
|
|
321
|
+
/**
|
|
322
|
+
* Strip TypeScript type syntax from an ES-module source so QuickJS can
|
|
323
|
+
* evaluate it as a standard JS module.
|
|
324
|
+
*
|
|
325
|
+
* Unlike `transformForEval`, this keeps `import`/`export` declarations,
|
|
326
|
+
* does not hoist to `globalThis`, and does not wrap in an IIFE.
|
|
327
|
+
* On parse failure the original source is returned unchanged.
|
|
328
|
+
*/
|
|
329
|
+
declare function stripTypeSyntax(code: string): string;
|
|
330
|
+
//#endregion
|
|
331
|
+
//#region src/subagent-dispatch.d.ts
|
|
332
|
+
/**
|
|
333
|
+
* Validate that a response schema does not exceed size, depth, or
|
|
334
|
+
* property-count limits.
|
|
335
|
+
*
|
|
336
|
+
* @throws Error if any limit is exceeded.
|
|
337
|
+
*/
|
|
338
|
+
declare function validateResponseSchema(schema: Record<string, unknown>): void;
|
|
202
339
|
//#endregion
|
|
203
|
-
export {
|
|
340
|
+
export { type CodeInterpreterMiddlewareOptions, DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, PTCCallBudgetExceededError, type ReplResult, ReplSession, type ReplSessionOptions, type SubagentBridgeOptions, createCodeInterpreterMiddleware, formatReplResult, stripTypeSyntax, toCamelCase, transformForEval, validateResponseSchema };
|
|
204
341
|
//# sourceMappingURL=index.d.ts.map
|