experimental-ash 0.58.1 → 0.59.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 (58) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/dist/docs/public/tools.mdx +51 -0
  3. package/dist/skills/v0-ash-onboarding/SKILL.md +308 -0
  4. package/dist/src/cli/dev/tui/markdown.js +1 -1
  5. package/dist/src/compiled/.vendor-stamp.json +2 -2
  6. package/dist/src/compiled/experimental-ai-sdk-code-mode/approval-continuation.d.ts +71 -0
  7. package/dist/src/compiled/experimental-ai-sdk-code-mode/approval.d.ts +32 -0
  8. package/dist/src/compiled/experimental-ai-sdk-code-mode/code-mode-tool.d.ts +16 -0
  9. package/dist/src/compiled/experimental-ai-sdk-code-mode/continuation-capability.d.ts +33 -0
  10. package/dist/src/compiled/experimental-ai-sdk-code-mode/errors.d.ts +114 -0
  11. package/dist/src/compiled/experimental-ai-sdk-code-mode/fetch-policy.d.ts +21 -0
  12. package/dist/src/compiled/experimental-ai-sdk-code-mode/host-interrupt.d.ts +25 -0
  13. package/dist/src/compiled/experimental-ai-sdk-code-mode/index.d.ts +11 -144
  14. package/dist/src/compiled/experimental-ai-sdk-code-mode/index.js +10 -73
  15. package/dist/src/compiled/experimental-ai-sdk-code-mode/interrupt-continuation.d.ts +32 -0
  16. package/dist/src/compiled/experimental-ai-sdk-code-mode/options.d.ts +3 -0
  17. package/dist/src/compiled/experimental-ai-sdk-code-mode/run-code-mode.d.ts +12 -0
  18. package/dist/src/compiled/experimental-ai-sdk-code-mode/runtime/guest-sources.d.ts +3 -0
  19. package/dist/src/compiled/experimental-ai-sdk-code-mode/runtime/manager.d.ts +22 -0
  20. package/dist/src/compiled/experimental-ai-sdk-code-mode/runtime/max-workers.d.ts +20 -0
  21. package/dist/src/compiled/experimental-ai-sdk-code-mode/runtime/protocol.d.ts +49 -0
  22. package/dist/src/compiled/experimental-ai-sdk-code-mode/runtime/worker-source.d.ts +11 -0
  23. package/dist/src/compiled/experimental-ai-sdk-code-mode/serialization.d.ts +5 -0
  24. package/dist/src/compiled/experimental-ai-sdk-code-mode/source-cache.d.ts +11 -0
  25. package/dist/src/compiled/experimental-ai-sdk-code-mode/telemetry.d.ts +20 -0
  26. package/dist/src/compiled/experimental-ai-sdk-code-mode/tool-invocation.d.ts +24 -0
  27. package/dist/src/compiled/experimental-ai-sdk-code-mode/tool-prompt.d.ts +3 -0
  28. package/dist/src/compiled/experimental-ai-sdk-code-mode/types.d.ts +802 -0
  29. package/dist/src/execution/node-step.js +1 -1
  30. package/dist/src/execution/tool-auth.d.ts +42 -0
  31. package/dist/src/execution/tool-auth.js +1 -0
  32. package/dist/src/harness/action-result-helpers.d.ts +17 -0
  33. package/dist/src/harness/action-result-helpers.js +1 -1
  34. package/dist/src/harness/code-mode-interrupt-state.d.ts +26 -0
  35. package/dist/src/harness/code-mode-interrupt-state.js +1 -0
  36. package/dist/src/harness/code-mode-lifecycle.js +1 -1
  37. package/dist/src/harness/code-mode.js +1 -1
  38. package/dist/src/harness/tool-loop.js +1 -1
  39. package/dist/src/internal/application/package.js +1 -1
  40. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  41. package/dist/src/packages/ash-scaffold/src/channels.js +2 -2
  42. package/dist/src/packages/ash-scaffold/src/steps/run-add-to-agent.js +1 -1
  43. package/dist/src/packages/ash-scaffold/src/web-template.js +2 -14
  44. package/dist/src/public/connections/index.js +1 -1
  45. package/dist/src/public/definitions/tool.d.ts +61 -1
  46. package/dist/src/public/definitions/tool.js +1 -1
  47. package/dist/src/public/next/server.js +1 -1
  48. package/dist/src/runtime/connections/mcp-client.js +1 -1
  49. package/dist/src/runtime/connections/scoped-authorization.d.ts +61 -0
  50. package/dist/src/runtime/connections/scoped-authorization.js +1 -0
  51. package/dist/src/runtime/framework-tools/connection-search-dynamic.js +1 -1
  52. package/dist/src/runtime/resolve-tool.js +1 -1
  53. package/dist/src/runtime/types.d.ts +10 -0
  54. package/package.json +2 -2
  55. package/dist/src/harness/code-mode-approval.d.ts +0 -22
  56. package/dist/src/harness/code-mode-approval.js +0 -1
  57. package/dist/src/harness/code-mode-connection-auth-state.d.ts +0 -15
  58. package/dist/src/harness/code-mode-connection-auth-state.js +0 -1
@@ -0,0 +1,802 @@
1
+ import type { ModelMessage, Tool } from "ai";
2
+ /**
3
+ * Host tools made available to sandboxed code through the global `tools` object.
4
+ *
5
+ * Each key becomes a callable async function at `tools[key](input)`.
6
+ */
7
+ export type CodeModeToolSet = Record<string, Tool<any, any>>;
8
+ /**
9
+ * Tool execution metadata forwarded to nested host tool calls.
10
+ *
11
+ * AI SDK 6 uses `experimental_context`; AI SDK 7 beta uses `context`. Code mode
12
+ * accepts both and forwards both when either one is provided.
13
+ */
14
+ export interface CodeModeToolExecutionOptions {
15
+ /**
16
+ * AI SDK tool call id for the outer code-mode invocation.
17
+ */
18
+ toolCallId: string;
19
+ /**
20
+ * Model messages that led to the outer code-mode invocation.
21
+ */
22
+ messages: ModelMessage[];
23
+ /**
24
+ * Abort signal for the outer code-mode invocation.
25
+ */
26
+ abortSignal?: AbortSignal;
27
+ /**
28
+ * AI SDK 6 experimental context.
29
+ */
30
+ experimental_context?: unknown;
31
+ /**
32
+ * AI SDK 7 beta tool context.
33
+ */
34
+ context?: unknown;
35
+ /**
36
+ * Generic code-mode interruption context for a host tool that is being
37
+ * re-executed during continuation.
38
+ */
39
+ codeModeInterrupt?: CodeModeInterruptExecutionContext;
40
+ }
41
+ /**
42
+ * Input schema for the generated code-mode AI SDK tool.
43
+ */
44
+ export interface CodeModeToolInput {
45
+ /**
46
+ * JavaScript or type-stripped TypeScript source to execute.
47
+ *
48
+ * The source is wrapped in an async function, so top-level `await` and
49
+ * `return` are supported.
50
+ */
51
+ js: string;
52
+ }
53
+ /**
54
+ * Result returned by an approval callback.
55
+ */
56
+ export type ApprovalDecision = "approved" | "denied" | {
57
+ approved: boolean;
58
+ reason?: string;
59
+ };
60
+ /**
61
+ * Approval request passed to `approval.onApprovalRequired`.
62
+ */
63
+ export interface CodeModeApprovalRequest {
64
+ /**
65
+ * Name of the host tool being requested.
66
+ */
67
+ toolName: string;
68
+ /**
69
+ * Validated tool input requested by sandboxed code.
70
+ */
71
+ input: unknown;
72
+ /**
73
+ * Tool call id derived from the outer AI SDK tool call id.
74
+ */
75
+ toolCallId: string;
76
+ }
77
+ /**
78
+ * Approval response used to continue a code-mode invocation that previously
79
+ * interrupted for a nested host tool approval.
80
+ */
81
+ export interface CodeModeApprovalResponse {
82
+ /**
83
+ * Approval id from the `CodeModeApprovalInterrupt`. This is the interrupt id
84
+ * of the underlying generic interruption.
85
+ */
86
+ approvalId: string;
87
+ /**
88
+ * Whether the nested tool call was approved.
89
+ */
90
+ approved: boolean;
91
+ /**
92
+ * Optional reason for approval or denial.
93
+ */
94
+ reason?: string;
95
+ }
96
+ /**
97
+ * Interrupt resolution applied to a built-in nested tool approval interruption.
98
+ *
99
+ * A `CodeModeApprovalInterrupt` is a `CodeModeInterrupt` whose payload kind is
100
+ * the reserved approval kind. Resuming it with `continueCodeModeInterrupt`
101
+ * requires a resolution of this shape; `continueCodeModeApproval` builds it from
102
+ * a `CodeModeApprovalResponse`.
103
+ */
104
+ export interface CodeModeApprovalResolution {
105
+ /**
106
+ * Whether the nested tool call was approved.
107
+ */
108
+ approved: boolean;
109
+ /**
110
+ * Optional reason for approval or denial.
111
+ */
112
+ reason?: string;
113
+ }
114
+ /**
115
+ * JSON-serializable host interruption payload.
116
+ */
117
+ export interface CodeModeInterruptPayload {
118
+ /**
119
+ * Stable interruption kind, such as `"connection-auth"`.
120
+ */
121
+ kind: string;
122
+ [key: string]: unknown;
123
+ }
124
+ /**
125
+ * Generic interruption resolution passed to the host tool during continuation.
126
+ */
127
+ export interface CodeModeInterruptResolution<TResolution = unknown> {
128
+ /**
129
+ * Interruption id from the pending code-mode interruption.
130
+ */
131
+ interruptId: string;
132
+ /**
133
+ * Host-provided resolution for the interruption.
134
+ */
135
+ resolution: TResolution;
136
+ }
137
+ /**
138
+ * Interruption context forwarded to the nested host tool when a continuation
139
+ * resumes the tool call that originally interrupted.
140
+ */
141
+ export interface CodeModeInterruptExecutionContext<TPayload extends CodeModeInterruptPayload = CodeModeInterruptPayload, TResolution = unknown> {
142
+ /**
143
+ * Interruption id being resolved.
144
+ */
145
+ interruptId: string;
146
+ /**
147
+ * Original interruption payload.
148
+ */
149
+ payload: TPayload;
150
+ /**
151
+ * Host-provided resolution.
152
+ */
153
+ resolution: TResolution;
154
+ }
155
+ /**
156
+ * Serializable record of one completed or interrupted sandbox-to-host bridge
157
+ * request. Continuations replay this ledger so previously completed bridge
158
+ * calls are not repeated.
159
+ */
160
+ export type CodeModeContinuationLedgerEntry = {
161
+ kind: "tool";
162
+ name: string;
163
+ inputJson: string;
164
+ toolCallId: string;
165
+ status: "fulfilled";
166
+ dateNowMs: number;
167
+ valueJson: string;
168
+ } | {
169
+ kind: "tool";
170
+ name: string;
171
+ inputJson: string;
172
+ toolCallId: string;
173
+ status: "rejected";
174
+ dateNowMs: number;
175
+ error: SerializableError;
176
+ } | {
177
+ kind: "tool";
178
+ name: string;
179
+ inputJson: string;
180
+ toolCallId: string;
181
+ interruptId: string;
182
+ interruptPayload: CodeModeInterruptPayload;
183
+ status: "interrupted";
184
+ } | {
185
+ kind: "fetch";
186
+ name: string;
187
+ inputJson: string;
188
+ status: "fulfilled";
189
+ dateNowMs: number;
190
+ valueJson: string;
191
+ } | {
192
+ kind: "fetch";
193
+ name: string;
194
+ inputJson: string;
195
+ status: "rejected";
196
+ dateNowMs: number;
197
+ error: SerializableError;
198
+ };
199
+ /**
200
+ * Deterministic guest API state used when replaying an interrupted invocation.
201
+ *
202
+ * Code mode uses this state to make no-argument `Date`, `Date.now()`, and
203
+ * `Math.random()` deterministic across approval continuations.
204
+ */
205
+ export interface CodeModeDeterminismState {
206
+ /**
207
+ * Initial timestamp, in Unix epoch milliseconds, for deterministic date APIs.
208
+ */
209
+ dateNowMs: number;
210
+ /**
211
+ * Initial 128-bit seed for deterministic `Math.random()`, encoded as 32
212
+ * hexadecimal characters.
213
+ */
214
+ randomSeed: string;
215
+ }
216
+ /**
217
+ * Host-authenticated bearer capability metadata for an interrupted invocation.
218
+ */
219
+ export interface CodeModeContinuationAuth {
220
+ /**
221
+ * Signature algorithm.
222
+ */
223
+ alg: "HMAC-SHA256";
224
+ /**
225
+ * Random nonce generated when the continuation was issued.
226
+ */
227
+ nonce: string;
228
+ /**
229
+ * Issuance time in Unix epoch milliseconds.
230
+ */
231
+ issuedAtMs: number;
232
+ /**
233
+ * Expiration time in Unix epoch milliseconds.
234
+ */
235
+ expiresAtMs: number;
236
+ /**
237
+ * HMAC over the canonical continuation payload, excluding this field.
238
+ */
239
+ signature: string;
240
+ }
241
+ /**
242
+ * Opaque continuation state for a code-mode invocation interrupted by nested
243
+ * tool approval.
244
+ */
245
+ export interface CodeModeContinuation {
246
+ version: 1;
247
+ js: string;
248
+ outerToolCallId: string;
249
+ determinism: CodeModeDeterminismState;
250
+ ledger: CodeModeContinuationLedgerEntry[];
251
+ auth: CodeModeContinuationAuth;
252
+ }
253
+ /**
254
+ * Continuation payload before the host signs it.
255
+ *
256
+ * @internal
257
+ */
258
+ export type UnsignedCodeModeContinuation = Omit<CodeModeContinuation, "auth">;
259
+ /**
260
+ * Result produced when a nested host tool triggers a generic interruption.
261
+ *
262
+ * The whole value is JSON-serializable: persist it in session state and pass it
263
+ * back to `continueCodeModeInterrupt` to resume. Every field except
264
+ * `continuation` is convenience metadata describing the paused nested call.
265
+ * `continuation` is the opaque, host-signed replay capability and the only
266
+ * authenticated part of the interruption.
267
+ */
268
+ export interface CodeModeInterrupt<TPayload extends CodeModeInterruptPayload = CodeModeInterruptPayload> {
269
+ type: "code-mode-interrupt";
270
+ /**
271
+ * Stable id for this interruption, equal to `<toolCallId>:interrupt`. Pass it
272
+ * back as `CodeModeInterruptResolution.interruptId` when resuming.
273
+ */
274
+ interruptId: string;
275
+ /**
276
+ * Name of the nested host tool that interrupted.
277
+ */
278
+ toolName: string;
279
+ /**
280
+ * Derived tool call id of the interrupted nested call.
281
+ */
282
+ toolCallId: string;
283
+ /**
284
+ * AI SDK tool call id of the outer `code_mode` invocation.
285
+ */
286
+ outerToolCallId: string;
287
+ /**
288
+ * Input the nested host tool was called with.
289
+ */
290
+ input: unknown;
291
+ /**
292
+ * Interruption payload. `payload.kind` identifies the interruption type.
293
+ */
294
+ payload: TPayload;
295
+ /**
296
+ * Opaque, host-signed replay capability. Treat it as an opaque token.
297
+ */
298
+ continuation: CodeModeContinuation;
299
+ }
300
+ /**
301
+ * Normalized result returned by `unwrapCodeModeResult`.
302
+ */
303
+ export type CodeModeUnwrappedResult = {
304
+ status: "completed";
305
+ output: unknown;
306
+ } | {
307
+ status: "interrupted";
308
+ interrupt: CodeModeInterrupt;
309
+ };
310
+ /**
311
+ * Reserved interruption payload for a built-in nested tool approval.
312
+ *
313
+ * Approval is implemented as a generic code-mode interruption with this payload
314
+ * kind, so every `CodeModeApprovalInterrupt` is also a `CodeModeInterrupt`.
315
+ */
316
+ export interface CodeModeApprovalInterruptPayload extends CodeModeInterruptPayload {
317
+ kind: "ai-sdk-code-mode/tool-approval";
318
+ }
319
+ /**
320
+ * Interruption produced when code mode is configured to interrupt for nested
321
+ * tool approvals and sandboxed code requests an approval-required host tool.
322
+ *
323
+ * This is a `CodeModeInterrupt` whose payload kind is the reserved approval
324
+ * kind. The approval-specific helpers project the inner tool name, input, and
325
+ * approval id (the interrupt id) from it and adapt it to AI SDK approval
326
+ * messages.
327
+ */
328
+ export type CodeModeApprovalInterrupt = CodeModeInterrupt<CodeModeApprovalInterruptPayload>;
329
+ /**
330
+ * Summary of one nested host bridge request.
331
+ */
332
+ export type CodeModeTraceEntry = {
333
+ kind: "tool";
334
+ bridgeIndex: number;
335
+ toolName: string;
336
+ toolCallId: string;
337
+ status: "fulfilled" | "rejected" | "interrupted";
338
+ replayed: boolean;
339
+ startedAtMs: number;
340
+ completedAtMs: number;
341
+ durationMs: number;
342
+ inputBytes: number;
343
+ outputBytes?: number;
344
+ error?: SerializableError;
345
+ interruptType?: CodeModeInterrupt["type"];
346
+ } | {
347
+ kind: "fetch";
348
+ bridgeIndex: number;
349
+ url: string;
350
+ method: string;
351
+ status: "fulfilled" | "rejected";
352
+ replayed: boolean;
353
+ startedAtMs: number;
354
+ completedAtMs: number;
355
+ durationMs: number;
356
+ inputBytes: number;
357
+ outputBytes?: number;
358
+ error?: SerializableError;
359
+ };
360
+ /**
361
+ * Per-invocation trace that summarizes nested tool and fetch activity.
362
+ */
363
+ export interface CodeModeTrace {
364
+ invocationId: string;
365
+ outerToolCallId: string;
366
+ status: "completed" | "failed" | "interrupted";
367
+ startedAtMs: number;
368
+ completedAtMs: number;
369
+ durationMs: number;
370
+ bridgeRequests: CodeModeTraceEntry[];
371
+ interruptedBy?: CodeModeInterrupt["type"];
372
+ error?: SerializableError;
373
+ }
374
+ /**
375
+ * Compact nested bridge summary that can optionally be included in the
376
+ * model-visible `code_mode` output.
377
+ */
378
+ export type CodeModeModelVisibleBridgeSummary = {
379
+ kind: "tool";
380
+ toolName: string;
381
+ toolCallId: string;
382
+ status: CodeModeTraceEntry["status"];
383
+ replayed: boolean;
384
+ /**
385
+ * AI SDK ToolResultOutput for the nested tool result. Present only when
386
+ * `modelOutput.includeNestedToolOutputs` is enabled and the nested tool
387
+ * fulfilled.
388
+ */
389
+ output?: unknown;
390
+ } | {
391
+ kind: "fetch";
392
+ url: string;
393
+ method: string;
394
+ status: "fulfilled" | "rejected";
395
+ replayed: boolean;
396
+ };
397
+ /**
398
+ * Optional model-visible wrapper used by `createCodeModeTool`.
399
+ */
400
+ export interface CodeModeModelOutputOptions {
401
+ /**
402
+ * Include a compact list of nested tool calls in the outer `code_mode`
403
+ * result. Inputs are never included. Outputs are included only when
404
+ * `includeNestedToolOutputs` is enabled.
405
+ *
406
+ * @defaultValue `false`
407
+ */
408
+ includeNestedToolSummary?: boolean;
409
+ /**
410
+ * Include AI SDK model-visible outputs for fulfilled nested tool calls.
411
+ *
412
+ * When a nested tool defines `toModelOutput`, that mapper is used. Otherwise
413
+ * code mode uses AI SDK's default text/json tool-output mapping. This option
414
+ * implies `includeNestedToolSummary`.
415
+ *
416
+ * @defaultValue `false`
417
+ */
418
+ includeNestedToolOutputs?: boolean;
419
+ /**
420
+ * Include sandbox fetch calls in the compact bridge summary.
421
+ *
422
+ * @defaultValue `false`
423
+ */
424
+ includeFetchSummary?: boolean;
425
+ /**
426
+ * Maximum bridge summary entries included in the model-visible output.
427
+ *
428
+ * @defaultValue `32`
429
+ */
430
+ maxSummaryEntries?: number;
431
+ }
432
+ /**
433
+ * Output shape returned by `createCodeModeTool` when model-visible bridge
434
+ * summaries are enabled.
435
+ */
436
+ export interface CodeModeModelOutput {
437
+ result: unknown;
438
+ nestedTools: CodeModeModelVisibleBridgeSummary[];
439
+ }
440
+ /**
441
+ * OpenTelemetry-compatible settings for code-mode spans.
442
+ */
443
+ export interface CodeModeTelemetryOptions {
444
+ /**
445
+ * Enables code-mode telemetry spans.
446
+ *
447
+ * @defaultValue `false`
448
+ */
449
+ isEnabled?: boolean;
450
+ /**
451
+ * Custom OpenTelemetry tracer.
452
+ */
453
+ tracer?: unknown;
454
+ /**
455
+ * Whether span attributes may include input sizes and source size.
456
+ *
457
+ * Raw inputs and source are never recorded by code mode.
458
+ *
459
+ * @defaultValue `true`
460
+ */
461
+ recordInputs?: boolean;
462
+ /**
463
+ * Whether span attributes may include output sizes.
464
+ *
465
+ * Raw outputs are never recorded by code mode.
466
+ *
467
+ * @defaultValue `true`
468
+ */
469
+ recordOutputs?: boolean;
470
+ /**
471
+ * Function identifier attached to code-mode spans.
472
+ */
473
+ functionId?: string;
474
+ /**
475
+ * Additional attributes attached to code-mode spans.
476
+ */
477
+ metadata?: Record<string, unknown>;
478
+ }
479
+ /**
480
+ * Event emitted before a nested host tool is executed.
481
+ */
482
+ export interface CodeModeNestedToolCallEvent {
483
+ invocationId: string;
484
+ outerToolCallId: string;
485
+ bridgeIndex: number;
486
+ toolName: string;
487
+ input: unknown;
488
+ inputBytes: number;
489
+ toolCallId: string;
490
+ replayed: boolean;
491
+ startedAtMs: number;
492
+ }
493
+ /**
494
+ * Event emitted after a nested host tool produces a sandbox-visible result.
495
+ */
496
+ export type CodeModeNestedToolResultEvent = (CodeModeNestedToolCallEvent & {
497
+ status: "fulfilled";
498
+ completedAtMs: number;
499
+ durationMs: number;
500
+ outputBytes: number;
501
+ output: unknown;
502
+ }) | (CodeModeNestedToolCallEvent & {
503
+ status: "rejected";
504
+ completedAtMs: number;
505
+ durationMs: number;
506
+ error: unknown;
507
+ }) | (CodeModeNestedToolCallEvent & {
508
+ status: "interrupted";
509
+ completedAtMs: number;
510
+ durationMs: number;
511
+ interrupt: CodeModeInterrupt;
512
+ });
513
+ /**
514
+ * Event emitted before a sandbox `fetch` request is handled by the host.
515
+ */
516
+ export interface CodeModeFetchRequestEvent {
517
+ invocationId: string;
518
+ outerToolCallId: string;
519
+ bridgeIndex: number;
520
+ url: string;
521
+ method: string;
522
+ inputBytes: number;
523
+ replayed: boolean;
524
+ startedAtMs: number;
525
+ }
526
+ /**
527
+ * Event emitted after a sandbox `fetch` request resolves or rejects.
528
+ */
529
+ export type CodeModeFetchResultEvent = (CodeModeFetchRequestEvent & {
530
+ status: "fulfilled";
531
+ completedAtMs: number;
532
+ durationMs: number;
533
+ outputBytes: number;
534
+ }) | (CodeModeFetchRequestEvent & {
535
+ status: "rejected";
536
+ completedAtMs: number;
537
+ durationMs: number;
538
+ error: unknown;
539
+ });
540
+ /**
541
+ * Event emitted when code mode returns an interruption.
542
+ */
543
+ export interface CodeModeInterruptEvent {
544
+ invocationId: string;
545
+ outerToolCallId: string;
546
+ interrupt: CodeModeInterrupt;
547
+ }
548
+ /**
549
+ * Lifecycle hook failure event.
550
+ */
551
+ export interface CodeModeLifecycleHookErrorEvent {
552
+ hook: "onNestedToolCall" | "onNestedToolResult" | "onFetchRequest" | "onFetchResult" | "onInterrupt" | "onTrace";
553
+ event: CodeModeNestedToolCallEvent | CodeModeNestedToolResultEvent | CodeModeFetchRequestEvent | CodeModeFetchResultEvent | CodeModeInterruptEvent | CodeModeTrace;
554
+ }
555
+ /**
556
+ * Policy for enabling and restricting `fetch` inside the sandbox.
557
+ *
558
+ * `fetch` is disabled unless `CodeModeOptions.fetchPolicy` is provided. When a
559
+ * policy is present, every requested URL, redirect URL, method, and response
560
+ * body must satisfy this policy before data enters the sandbox.
561
+ */
562
+ export interface CodeModeFetchPolicy {
563
+ /**
564
+ * Host fetch implementation to use.
565
+ *
566
+ * Defaults to `globalThis.fetch` when available.
567
+ */
568
+ fetch?: typeof globalThis.fetch;
569
+ /**
570
+ * Exact origins that sandboxed code may fetch.
571
+ *
572
+ * Example: `["https://api.example.com"]`.
573
+ */
574
+ allowedOrigins?: string[];
575
+ /**
576
+ * Origin plus path prefixes that sandboxed code may fetch.
577
+ *
578
+ * Prefixes must not include query strings or fragments.
579
+ */
580
+ allowedUrlPrefixes?: string[];
581
+ /**
582
+ * HTTP methods allowed by the fetch policy.
583
+ *
584
+ * @defaultValue `["GET", "HEAD"]`
585
+ */
586
+ allowedMethods?: string[];
587
+ /**
588
+ * Maximum response body size in bytes.
589
+ *
590
+ * @defaultValue `1024 * 1024`
591
+ */
592
+ maxResponseBytes?: number;
593
+ /**
594
+ * Whether redirects should be followed by the host.
595
+ *
596
+ * Redirect targets are checked against the same fetch policy.
597
+ *
598
+ * @defaultValue `false`
599
+ */
600
+ allowRedirects?: boolean;
601
+ /**
602
+ * Maximum number of redirects to follow when redirects are enabled.
603
+ *
604
+ * @defaultValue `10`
605
+ */
606
+ maxRedirects?: number;
607
+ }
608
+ /**
609
+ * Execution limits applied to each sandbox invocation.
610
+ */
611
+ export interface CodeModeExecutionPolicy {
612
+ /**
613
+ * Wall-clock timeout for one invocation, in milliseconds.
614
+ *
615
+ * @defaultValue `30_000`
616
+ */
617
+ timeoutMs?: number;
618
+ /**
619
+ * QuickJS runtime memory limit, in bytes.
620
+ *
621
+ * @defaultValue `64 * 1024 * 1024`
622
+ */
623
+ memoryLimitBytes?: number;
624
+ /**
625
+ * QuickJS stack limit, in bytes.
626
+ *
627
+ * @defaultValue `2 * 1024 * 1024`
628
+ */
629
+ maxStackSizeBytes?: number;
630
+ /**
631
+ * Maximum serialized sandbox result size, in bytes.
632
+ *
633
+ * @defaultValue `1024 * 1024`
634
+ */
635
+ maxResultBytes?: number;
636
+ /**
637
+ * Maximum input source size, in bytes.
638
+ *
639
+ * @defaultValue `256 * 1024`
640
+ */
641
+ maxSourceBytes?: number;
642
+ /**
643
+ * Maximum serialized input size for one host tool call, in bytes.
644
+ *
645
+ * @defaultValue `1024 * 1024`
646
+ */
647
+ maxToolInputBytes?: number;
648
+ /**
649
+ * Maximum serialized output size for one host tool call, in bytes.
650
+ *
651
+ * @defaultValue `4 * 1024 * 1024`
652
+ */
653
+ maxToolOutputBytes?: number;
654
+ /**
655
+ * Maximum total host bridge requests per invocation.
656
+ *
657
+ * Host bridge requests include tool calls and fetch calls.
658
+ *
659
+ * @defaultValue `256`
660
+ */
661
+ maxBridgeRequests?: number;
662
+ /**
663
+ * Maximum in-flight host bridge requests per invocation.
664
+ *
665
+ * @defaultValue `32`
666
+ */
667
+ maxInFlightBridgeRequests?: number;
668
+ }
669
+ /**
670
+ * Options used by `createCodeModeTool` and `runCodeMode`.
671
+ */
672
+ export interface CodeModeOptions {
673
+ /**
674
+ * Per-invocation execution limits.
675
+ */
676
+ executionPolicy?: CodeModeExecutionPolicy;
677
+ /**
678
+ * Fetch policy for sandboxed `fetch`.
679
+ *
680
+ * Omit this or set it to `false` to keep `fetch` unavailable in the sandbox.
681
+ */
682
+ fetchPolicy?: false | CodeModeFetchPolicy;
683
+ /**
684
+ * Approval hooks for host tools that require approval.
685
+ */
686
+ approval?: {
687
+ /**
688
+ * Approval handling mode.
689
+ *
690
+ * - `callback`: use `onApprovalRequired` and fail when no callback approves.
691
+ * - `interrupt`: return a `CodeModeApprovalInterrupt` continuation instead
692
+ * of executing or failing the nested tool call.
693
+ *
694
+ * @defaultValue `"callback"`
695
+ */
696
+ mode?: "callback" | "interrupt";
697
+ /**
698
+ * Called when sandboxed code requests a host tool that requires approval.
699
+ *
700
+ * Ignored when `mode` is `"interrupt"`.
701
+ */
702
+ onApprovalRequired?: (request: CodeModeApprovalRequest) => Promise<ApprovalDecision> | ApprovalDecision;
703
+ };
704
+ /**
705
+ * Optional observability hooks for nested host tool activity.
706
+ *
707
+ * Hook errors are reported to `onHookError` when provided and otherwise
708
+ * ignored so telemetry cannot change sandbox behavior.
709
+ */
710
+ lifecycle?: {
711
+ onNestedToolCall?: (event: CodeModeNestedToolCallEvent) => Promise<void> | void;
712
+ onNestedToolResult?: (event: CodeModeNestedToolResultEvent) => Promise<void> | void;
713
+ onFetchRequest?: (event: CodeModeFetchRequestEvent) => Promise<void> | void;
714
+ onFetchResult?: (event: CodeModeFetchResultEvent) => Promise<void> | void;
715
+ onInterrupt?: (event: CodeModeInterruptEvent) => Promise<void> | void;
716
+ onTrace?: (trace: CodeModeTrace) => Promise<void> | void;
717
+ onHookError?: (error: unknown, event: CodeModeLifecycleHookErrorEvent) => Promise<void> | void;
718
+ };
719
+ /**
720
+ * OpenTelemetry-compatible spans for code-mode execution.
721
+ *
722
+ * Disabled by default.
723
+ */
724
+ telemetry?: CodeModeTelemetryOptions;
725
+ /**
726
+ * Optional model-visible output wrapper for the generated AI SDK tool.
727
+ *
728
+ * Only `createCodeModeTool` uses this option. `runCodeMode` always returns
729
+ * the sandbox output directly.
730
+ */
731
+ modelOutput?: CodeModeModelOutputOptions;
732
+ }
733
+ /**
734
+ * Input for `runCodeMode`.
735
+ */
736
+ export interface RunCodeModeInput {
737
+ /**
738
+ * JavaScript or type-stripped TypeScript source to execute.
739
+ */
740
+ js: string;
741
+ /**
742
+ * Host tools available to sandboxed code.
743
+ */
744
+ tools: CodeModeToolSet;
745
+ /**
746
+ * AI SDK tool execution options forwarded to nested host tool calls.
747
+ */
748
+ toolExecutionOptions?: Partial<CodeModeToolExecutionOptions>;
749
+ /**
750
+ * Code-mode runtime options.
751
+ */
752
+ options?: CodeModeOptions;
753
+ /**
754
+ * Continuation ledger from a previous `CodeModeInterrupt`.
755
+ */
756
+ continuation?: CodeModeContinuation;
757
+ /**
758
+ * Generic interruption resolution used with `continuation` to resume the
759
+ * interrupted nested host tool call. Approval continuations pass a
760
+ * `CodeModeApprovalResolution` here.
761
+ */
762
+ interruptResolution?: CodeModeInterruptResolution;
763
+ }
764
+ /**
765
+ * Worker script location used by the process-global code-mode worker pool.
766
+ *
767
+ * URL strings such as values returned by `import.meta.resolve(...)` are accepted
768
+ * and normalized to `URL` objects before spawning a Node.js worker.
769
+ */
770
+ export type CodeModeWorkerUrl = string | URL;
771
+ /**
772
+ * Fully normalized runtime options.
773
+ *
774
+ * @internal
775
+ */
776
+ export interface NormalizedCodeModeOptions {
777
+ timeoutMs: number;
778
+ memoryLimitBytes: number;
779
+ maxStackSizeBytes: number;
780
+ maxResultBytes: number;
781
+ maxSourceBytes: number;
782
+ maxToolInputBytes: number;
783
+ maxToolOutputBytes: number;
784
+ maxBridgeRequests: number;
785
+ maxInFlightBridgeRequests: number;
786
+ fetch: typeof globalThis.fetch | undefined;
787
+ fetchEnabled: boolean;
788
+ fetchPolicy: Required<Pick<CodeModeFetchPolicy, "maxResponseBytes" | "allowRedirects" | "maxRedirects">> & Omit<CodeModeFetchPolicy, "fetch" | "maxResponseBytes" | "allowRedirects" | "maxRedirects">;
789
+ }
790
+ /**
791
+ * Serializable representation of an error crossing the worker boundary.
792
+ *
793
+ * @internal
794
+ */
795
+ export interface SerializableError {
796
+ name: string;
797
+ message: string;
798
+ stack?: string;
799
+ code?: string;
800
+ details?: unknown;
801
+ }
802
+ //# sourceMappingURL=types.d.ts.map