experimental-ash 0.6.1 → 0.6.2
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/dist/src/chunks/{dev-authored-source-watcher-Bk-ZWzF_.js → dev-authored-source-watcher-MDHwWfTE.js} +1 -1
- package/dist/src/chunks/{host-CEiB9Ps8.js → host-CDvE1sV_.js} +2 -2
- package/dist/src/chunks/{paths-Dxh19LKr.js → paths-D1gMcyWw.js} +4 -4
- package/dist/src/chunks/{prewarm-BK_ZT4-w.js → prewarm-CCU5VjXa.js} +1 -1
- package/dist/src/cli/commands/info.js +1 -1
- package/dist/src/cli/run.js +1 -1
- package/dist/src/cli/templates/init-app/package.json +1 -1
- package/dist/src/compiled/.vendor-stamp.json +2 -2
- package/dist/src/compiled/@ai-sdk/otel/index.js +3 -3
- package/dist/src/compiled/@ai-sdk/otel/package.json +1 -1
- package/dist/src/compiled/@vercel/sandbox/index.d.ts +1 -0
- package/dist/src/evals/cli/eval.js +1 -1
- package/dist/src/execution/sandbox/bindings/local.js +32 -3
- package/dist/src/execution/sandbox/bindings/vercel.js +3 -2
- package/dist/src/execution/sandbox/session.d.ts +2 -2
- package/dist/src/execution/sandbox/session.js +2 -2
- package/dist/src/internal/application/package.js +1 -1
- package/dist/src/internal/authored-definition/sandbox.d.ts +3 -10
- package/dist/src/public/channels/slack/slackChannel.d.ts +7 -0
- package/dist/src/public/channels/slack/slackChannel.js +5 -0
- package/dist/src/public/definitions/sandbox-backend.d.ts +1 -123
- package/dist/src/public/definitions/sandbox.d.ts +6 -165
- package/dist/src/public/sandbox/index.d.ts +1 -1
- package/dist/src/runtime/types.d.ts +5 -8
- package/dist/src/shared/sandbox-backend.d.ts +124 -0
- package/dist/src/shared/sandbox-backend.js +1 -0
- package/dist/src/shared/sandbox-definition.d.ts +72 -0
- package/dist/src/shared/sandbox-definition.js +1 -0
- package/dist/src/shared/sandbox-session.d.ts +95 -0
- package/dist/src/shared/sandbox-session.js +1 -0
- package/package.json +4 -4
|
@@ -1,168 +1,9 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
export
|
|
6
|
-
|
|
7
|
-
readonly stderr: string;
|
|
8
|
-
readonly stdout: string;
|
|
9
|
-
}
|
|
10
|
-
/**
|
|
11
|
-
* Options for reading a text file from a sandbox with optional line ranges.
|
|
12
|
-
*/
|
|
13
|
-
export interface SandboxReadFileOptions {
|
|
14
|
-
/**
|
|
15
|
-
* 1-based inclusive end line. When past the file's line count, the read
|
|
16
|
-
* returns through EOF without error.
|
|
17
|
-
*/
|
|
18
|
-
readonly endLine?: number;
|
|
19
|
-
/**
|
|
20
|
-
* 1-based inclusive start line. Defaults to 1.
|
|
21
|
-
*/
|
|
22
|
-
readonly startLine?: number;
|
|
23
|
-
}
|
|
24
|
-
/**
|
|
25
|
-
* Minimal Ash-owned sandbox session exposed to authored lifecycle hooks.
|
|
26
|
-
*/
|
|
27
|
-
export interface SandboxSession {
|
|
28
|
-
/**
|
|
29
|
-
* Stable identifier for the backend session this handle wraps.
|
|
30
|
-
*
|
|
31
|
-
* Persists across reconnects to the same logical session: two calls
|
|
32
|
-
* that resume the same underlying backend sandbox observe the same
|
|
33
|
-
* `id`. Template sessions constructed during bootstrap expose the
|
|
34
|
-
* template key; live sessions expose the session key assigned by the
|
|
35
|
-
* runtime. Useful as a cache key for per-session state that must
|
|
36
|
-
* outlive individual step executions.
|
|
37
|
-
*/
|
|
38
|
-
readonly id: string;
|
|
39
|
-
/**
|
|
40
|
-
* Reads one text file from the sandbox as UTF-8.
|
|
41
|
-
*
|
|
42
|
-
* Returns `null` when the file does not exist. Throws when the file
|
|
43
|
-
* contains invalid UTF-8.
|
|
44
|
-
*
|
|
45
|
-
* Relative paths resolve from `/workspace`, the live working directory
|
|
46
|
-
* for every backend. Absolute paths pass through unchanged.
|
|
47
|
-
*
|
|
48
|
-
* Line ranges are 1-based and inclusive. When `endLine` is past EOF the
|
|
49
|
-
* read returns through EOF without error.
|
|
50
|
-
*/
|
|
51
|
-
readFile(path: string, options?: SandboxReadFileOptions): Promise<string | null>;
|
|
52
|
-
/**
|
|
53
|
-
* Reads one file from the sandbox as raw bytes.
|
|
54
|
-
*
|
|
55
|
-
* Returns `null` when the file does not exist. Unlike
|
|
56
|
-
* {@link SandboxSession.readFile}, this variant performs no UTF-8
|
|
57
|
-
* decoding and is safe for binary payloads (images, PDFs, archives,
|
|
58
|
-
* attachment bytes written by the framework at
|
|
59
|
-
* `/workspace/attachments/...`).
|
|
60
|
-
*
|
|
61
|
-
* Relative paths resolve from `/workspace`, the live working
|
|
62
|
-
* directory for every backend. Absolute paths pass through unchanged.
|
|
63
|
-
*/
|
|
64
|
-
readFileBytes(path: string): Promise<Buffer | null>;
|
|
65
|
-
/**
|
|
66
|
-
* Anchors a sandbox-relative path to `/workspace` and returns the
|
|
67
|
-
* resulting absolute path.
|
|
68
|
-
*
|
|
69
|
-
* Relative paths resolve from `/workspace`; absolute paths pass through.
|
|
70
|
-
* `readFile(...)` and `writeFile(...)` already apply this internally.
|
|
71
|
-
*/
|
|
72
|
-
resolvePath(path: string): string;
|
|
73
|
-
/**
|
|
74
|
-
* Runs one shell command inside the current sandbox session and returns the
|
|
75
|
-
* captured stdout, stderr, and exit code.
|
|
76
|
-
*
|
|
77
|
-
* Commands execute with `/workspace` as the working directory on every
|
|
78
|
-
* backend.
|
|
79
|
-
*/
|
|
80
|
-
runCommand(command: string): Promise<SandboxCommandResult>;
|
|
81
|
-
/**
|
|
82
|
-
* Writes one file to the sandbox, creating parent directories
|
|
83
|
-
* recursively and overwriting any existing file.
|
|
84
|
-
*
|
|
85
|
-
* `content` accepts a UTF-8 `string` for text files or a `Buffer` for
|
|
86
|
-
* arbitrary bytes. The framework uses the `Buffer` overload to mount
|
|
87
|
-
* binary workspace assets (images under skill `assets/` directories,
|
|
88
|
-
* fixture payloads, and so on) through the same public surface authors
|
|
89
|
-
* use.
|
|
90
|
-
*
|
|
91
|
-
* Relative paths resolve from `/workspace`. Absolute paths pass through
|
|
92
|
-
* unchanged.
|
|
93
|
-
*/
|
|
94
|
-
writeFile(path: string, content: string | Buffer): Promise<void>;
|
|
95
|
-
}
|
|
96
|
-
/**
|
|
97
|
-
* A transform applied to network requests matching a domain rule.
|
|
98
|
-
*/
|
|
99
|
-
export interface SandboxNetworkTransformer {
|
|
100
|
-
readonly headers?: Record<string, string>;
|
|
101
|
-
}
|
|
102
|
-
/**
|
|
103
|
-
* A rule applied to requests matching a domain in the network policy.
|
|
104
|
-
*/
|
|
105
|
-
export interface SandboxNetworkPolicyRule {
|
|
106
|
-
readonly transform?: SandboxNetworkTransformer[];
|
|
107
|
-
}
|
|
108
|
-
/**
|
|
109
|
-
* Network policy to define network restrictions for the sandbox.
|
|
110
|
-
*
|
|
111
|
-
* - `"allow-all"`: Full internet access (default). All traffic is allowed.
|
|
112
|
-
* - `"deny-all"`: No internet access. All traffic is denied.
|
|
113
|
-
* - Object: Custom access with explicit allow/deny lists.
|
|
114
|
-
*/
|
|
115
|
-
export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
|
|
116
|
-
readonly allow?: string[] | Readonly<Record<string, SandboxNetworkPolicyRule[]>>;
|
|
117
|
-
};
|
|
118
|
-
export interface SandboxBootstrapUseOptions {
|
|
119
|
-
readonly runtime?: string;
|
|
120
|
-
readonly ports?: number[];
|
|
121
|
-
readonly env?: Record<string, string>;
|
|
122
|
-
}
|
|
123
|
-
export interface SandboxSessionUseOptions {
|
|
124
|
-
readonly networkPolicy?: SandboxNetworkPolicy;
|
|
125
|
-
readonly resources?: {
|
|
126
|
-
vcpus?: number;
|
|
127
|
-
};
|
|
128
|
-
readonly timeout?: number;
|
|
129
|
-
readonly tags?: Record<string, string>;
|
|
130
|
-
}
|
|
131
|
-
export type SandboxBootstrapUseFn = (options?: SandboxBootstrapUseOptions) => Promise<SandboxSession>;
|
|
132
|
-
export type SandboxSessionUseFn<S extends SandboxSession = SandboxSession> = (options?: SandboxSessionUseOptions) => Promise<S>;
|
|
133
|
-
export interface SandboxBootstrapContext {
|
|
134
|
-
readonly use: SandboxBootstrapUseFn;
|
|
135
|
-
}
|
|
136
|
-
export interface SandboxSessionContext<S extends SandboxSession = SandboxSession> {
|
|
137
|
-
readonly use: SandboxSessionUseFn<S>;
|
|
138
|
-
}
|
|
139
|
-
/**
|
|
140
|
-
* Public sandbox definition authored in `agent/sandbox.ts` (shorthand)
|
|
141
|
-
* or `agent/sandbox/sandbox.ts` (folder layout, when paired with an
|
|
142
|
-
* authored `sandbox/workspace/` subtree).
|
|
143
|
-
*
|
|
144
|
-
* Each agent (and each subagent) owns exactly one sandbox. When the
|
|
145
|
-
* module file is absent the framework auto-provides a default sandbox
|
|
146
|
-
* via `defaultBackend()`. Authors override lifecycle and backend by
|
|
147
|
-
* creating `agent/sandbox.ts` (or `agent/sandbox/sandbox.ts` when they
|
|
148
|
-
* also want a workspace folder); subagents override independently via
|
|
149
|
-
* `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
|
|
150
|
-
* their parent's sandbox (skill seeds differ per agent).
|
|
151
|
-
*/
|
|
152
|
-
export interface SandboxDefinition<S extends SandboxSession = SandboxSession> {
|
|
153
|
-
/**
|
|
154
|
-
* Backend that runs this sandbox.
|
|
155
|
-
*
|
|
156
|
-
* When this field is omitted, Ash substitutes `defaultBackend()` at
|
|
157
|
-
* runtime, which delegates to `vercelBackend()` on hosted Vercel
|
|
158
|
-
* (where `process.env.VERCEL` is set) and to `localBackend()`
|
|
159
|
-
* everywhere else. Set `backend` explicitly to pin the sandbox to a
|
|
160
|
-
* specific backend regardless of environment.
|
|
161
|
-
*/
|
|
162
|
-
readonly backend?: SandboxBackend<S>;
|
|
163
|
-
bootstrap?(input: SandboxBootstrapContext): Promise<void> | void;
|
|
164
|
-
onSession?(input: SandboxSessionContext<S>): Promise<void> | void;
|
|
165
|
-
}
|
|
1
|
+
import type { Optional } from "#shared/optional.js";
|
|
2
|
+
import type { SandboxSession } from "#shared/sandbox-session.js";
|
|
3
|
+
import type { SandboxDefinition as SharedSandboxDefinition } from "#shared/sandbox-definition.js";
|
|
4
|
+
export type { SandboxCommandOptions, SandboxCommandResult, SandboxReadFileOptions, SandboxSession, } from "#shared/sandbox-session.js";
|
|
5
|
+
export type { SandboxNetworkPolicy, SandboxBootstrapUseOptions, SandboxSessionUseOptions, SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
|
|
6
|
+
export type SandboxDefinition<S extends SandboxSession = SandboxSession> = Optional<SharedSandboxDefinition<S>, "backend">;
|
|
166
7
|
/**
|
|
167
8
|
* Defines a sandbox configuration.
|
|
168
9
|
*/
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
|
|
4
4
|
*/
|
|
5
5
|
export { getSandbox } from "#context/accessors.js";
|
|
6
|
-
export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxBootstrapUseOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxNetworkPolicy, type SandboxReadFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxSessionUseOptions, } from "#public/definitions/sandbox.js";
|
|
6
|
+
export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxBootstrapUseOptions, type SandboxCommandOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxNetworkPolicy, type SandboxReadFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxSessionUseOptions, } from "#public/definitions/sandbox.js";
|
|
7
7
|
export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
|
|
8
8
|
export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
|
|
9
9
|
export { defaultBackend } from "#public/sandbox/backends/default.js";
|
|
@@ -3,8 +3,6 @@ import type { ChannelAdapter } from "#channel/adapter.js";
|
|
|
3
3
|
import type { DiscoverDiagnosticsSummary } from "#discover/diagnostics.js";
|
|
4
4
|
import type { ChannelMethod, Route, RouteContext } from "#public/definitions/channel.js";
|
|
5
5
|
import type { RouteHandler } from "#channel/routes.js";
|
|
6
|
-
import type { SandboxBootstrapContext, SandboxSessionContext } from "#public/definitions/sandbox.js";
|
|
7
|
-
import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
|
|
8
6
|
import type { LifecycleHooks, StreamEventHook } from "#public/definitions/hook.js";
|
|
9
7
|
import type { CompactionHookInput, CompactionHookResult, NeedsApprovalContext, ToolRetentionPolicy } from "#public/definitions/tool.js";
|
|
10
8
|
import type { AuthorizationDefinition, HeadersDefinition, ToolFilterDefinition } from "#runtime/connections/types.js";
|
|
@@ -16,6 +14,8 @@ import type { SourceRef, ModuleSourceRef, SkillPackageSourceRef, MarkdownSourceR
|
|
|
16
14
|
import type { InternalSkillDefinition } from "#shared/skill-definition.js";
|
|
17
15
|
import type { InternalAgentDefinition } from "#shared/agent-definition.js";
|
|
18
16
|
import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";
|
|
17
|
+
import type { SandboxDefinition } from "#shared/sandbox-definition.js";
|
|
18
|
+
import type { SandboxSession } from "#shared/sandbox-session.js";
|
|
19
19
|
/**
|
|
20
20
|
* Runtime-owned source ref describing one additive config module import.
|
|
21
21
|
*/
|
|
@@ -77,18 +77,15 @@ export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {
|
|
|
77
77
|
* map.
|
|
78
78
|
*
|
|
79
79
|
* The resolved `backend` is non-optional: every sandbox in the runtime
|
|
80
|
-
* graph carries a concrete
|
|
80
|
+
* graph carries a concrete SandboxBackend value, even when the
|
|
81
81
|
* authored definition omits `backend`. The unauthored case is filled
|
|
82
82
|
* in by `defaultBackend()` (which itself selects between
|
|
83
83
|
* `vercelBackend()` and `localBackend()` based on the current
|
|
84
84
|
* environment).
|
|
85
85
|
*/
|
|
86
|
-
export
|
|
87
|
-
readonly backend: SandboxBackend;
|
|
88
|
-
readonly bootstrap?: (input: SandboxBootstrapContext) => Promise<void> | void;
|
|
86
|
+
export type ResolvedSandboxDefinition = Readonly<SandboxDefinition<SandboxSession>> & ResolvedModuleSourceRef & {
|
|
89
87
|
readonly description?: string;
|
|
90
|
-
|
|
91
|
-
}
|
|
88
|
+
};
|
|
92
89
|
/**
|
|
93
90
|
* Runtime-owned authored tool definition resolved from a compiled module map.
|
|
94
91
|
* A tool without `execute` is surfaced to the client and never executed by Ash.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import type { SandboxBootstrapContext, SandboxSessionUseFn } from "#shared/sandbox-definition.js";
|
|
2
|
+
import type { SandboxSession } from "#shared/sandbox-session.js";
|
|
3
|
+
/**
|
|
4
|
+
* Live sandbox handle returned by a {@link SandboxBackend}.
|
|
5
|
+
*
|
|
6
|
+
* Wraps the public {@link SandboxSession} with lifecycle methods so the
|
|
7
|
+
* runtime orchestrator can persist reconnect metadata and release
|
|
8
|
+
* resources.
|
|
9
|
+
*/
|
|
10
|
+
export interface SandboxBackendHandle<S extends SandboxSession = SandboxSession> {
|
|
11
|
+
readonly session: SandboxSession;
|
|
12
|
+
readonly useSessionFn: SandboxSessionUseFn<S>;
|
|
13
|
+
captureState(): Promise<SandboxBackendSessionState>;
|
|
14
|
+
dispose(): Promise<void>;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Serializable per-sandbox reconnect record stored on the harness session.
|
|
18
|
+
*
|
|
19
|
+
* `backendName` matches the {@link SandboxBackend.name} of the backend
|
|
20
|
+
* that produced this state, and is used by the runtime to decide whether
|
|
21
|
+
* a previously persisted handle is still compatible with the current
|
|
22
|
+
* backend.
|
|
23
|
+
*/
|
|
24
|
+
export interface SandboxBackendSessionState {
|
|
25
|
+
readonly backendName: string;
|
|
26
|
+
readonly metadata: Record<string, unknown>;
|
|
27
|
+
readonly sessionKey: string;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* One file written into a sandbox template before snapshot capture.
|
|
31
|
+
*/
|
|
32
|
+
export interface SandboxSeedFile {
|
|
33
|
+
readonly path: string;
|
|
34
|
+
readonly content: string | Buffer;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Diagnostic tags attached to provider-owned sandbox resources.
|
|
38
|
+
*
|
|
39
|
+
* Built-in backends may forward these into their hosting platform's
|
|
40
|
+
* native tagging system. Ash supplies stable tags such as the active
|
|
41
|
+
* agent, channel, and session id so sandboxes can be found and
|
|
42
|
+
* attributed in provider dashboards.
|
|
43
|
+
*/
|
|
44
|
+
export type SandboxBackendTags = Readonly<Record<string, string>>;
|
|
45
|
+
/**
|
|
46
|
+
* Framework-owned runtime context handed to a backend on every
|
|
47
|
+
* {@link SandboxBackend.create} call.
|
|
48
|
+
*
|
|
49
|
+
* Backends use this to derive any per-call state that depends on the
|
|
50
|
+
* surrounding application — for example, the local backend computes its
|
|
51
|
+
* cache directory from `appRoot`. Backends that don't need anything
|
|
52
|
+
* here may ignore the field entirely.
|
|
53
|
+
*/
|
|
54
|
+
export interface SandboxBackendRuntimeContext {
|
|
55
|
+
readonly appRoot: string;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Input passed to {@link SandboxBackend.create} when the runtime needs a
|
|
59
|
+
* live sandbox session.
|
|
60
|
+
*/
|
|
61
|
+
export interface SandboxBackendCreateInput {
|
|
62
|
+
readonly templateKey: string;
|
|
63
|
+
readonly sessionKey: string;
|
|
64
|
+
readonly existingMetadata?: Record<string, unknown>;
|
|
65
|
+
/**
|
|
66
|
+
* Runtime tags the backend should attach to sandbox resources when
|
|
67
|
+
* the underlying provider supports tags.
|
|
68
|
+
*/
|
|
69
|
+
readonly tags?: SandboxBackendTags;
|
|
70
|
+
readonly runtimeContext: SandboxBackendRuntimeContext;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Input passed to {@link SandboxBackend.prewarm} when the build pipeline
|
|
74
|
+
* is preparing reusable templates.
|
|
75
|
+
*
|
|
76
|
+
* Every authored sandbox in the compiled graph receives exactly one
|
|
77
|
+
* `prewarm(...)` call before runtime opens its first session. The
|
|
78
|
+
* backend captures a reusable template snapshot from the supplied
|
|
79
|
+
* `bootstrap` hook and `seedFiles`, then `backend.create(...)` opens
|
|
80
|
+
* durable sessions from that snapshot.
|
|
81
|
+
*/
|
|
82
|
+
export interface SandboxBackendPrewarmInput {
|
|
83
|
+
readonly templateKey: string;
|
|
84
|
+
readonly bootstrap?: (input: SandboxBootstrapContext) => void | Promise<void>;
|
|
85
|
+
readonly runtimeContext: SandboxBackendRuntimeContext;
|
|
86
|
+
readonly seedFiles: ReadonlyArray<SandboxSeedFile>;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Pluggable sandbox backend.
|
|
90
|
+
*
|
|
91
|
+
* A `SandboxBackend` is a value an author attaches to a
|
|
92
|
+
* {@link SandboxDefinition} to choose which underlying runtime hosts the
|
|
93
|
+
* sandbox. Ash ships two built-in backends — `vercelBackend()` and
|
|
94
|
+
* `localBackend()` — but the interface is public so authors can write
|
|
95
|
+
* their own.
|
|
96
|
+
*
|
|
97
|
+
* Each backend owns the full template-then-session lifecycle internally;
|
|
98
|
+
* callers only need a single `create` call.
|
|
99
|
+
*/
|
|
100
|
+
export interface SandboxBackend<S extends SandboxSession = SandboxSession> {
|
|
101
|
+
/**
|
|
102
|
+
* Stable identifier for this backend implementation.
|
|
103
|
+
*
|
|
104
|
+
* Participates in cache-key derivation and the persisted reconnect
|
|
105
|
+
* state, so two backends that should not share template snapshots
|
|
106
|
+
* must use distinct names. Built-in backends use `"vercel"` and
|
|
107
|
+
* `"local"`. Custom backends pick a unique string.
|
|
108
|
+
*/
|
|
109
|
+
readonly name: string;
|
|
110
|
+
/**
|
|
111
|
+
* Creates or reattaches one live sandbox session from a template
|
|
112
|
+
* previously captured by {@link SandboxBackend.prewarm}. Throws
|
|
113
|
+
* {@link SandboxTemplateNotProvisionedError} when the requested
|
|
114
|
+
* template is missing.
|
|
115
|
+
*/
|
|
116
|
+
create(input: SandboxBackendCreateInput): Promise<SandboxBackendHandle<S>>;
|
|
117
|
+
/**
|
|
118
|
+
* Build-time prewarm hook. Ash invokes this for every authored
|
|
119
|
+
* sandbox in the compiled graph before serving traffic so the backend
|
|
120
|
+
* can capture a reusable template snapshot. Idempotent against an
|
|
121
|
+
* existing snapshot keyed by `templateKey`.
|
|
122
|
+
*/
|
|
123
|
+
prewarm(input: SandboxBackendPrewarmInput): Promise<void>;
|
|
124
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import type { SandboxSession } from "#shared/sandbox-session.js";
|
|
2
|
+
import type { SandboxBackend } from "#shared/sandbox-backend.js";
|
|
3
|
+
/**
|
|
4
|
+
* A transform applied to network requests matching a domain rule.
|
|
5
|
+
*/
|
|
6
|
+
export interface SandboxNetworkTransformer {
|
|
7
|
+
readonly headers?: Record<string, string>;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* A rule applied to requests matching a domain in the network policy.
|
|
11
|
+
*/
|
|
12
|
+
export interface SandboxNetworkPolicyRule {
|
|
13
|
+
readonly transform?: SandboxNetworkTransformer[];
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Network policy to define network restrictions for the sandbox.
|
|
17
|
+
*
|
|
18
|
+
* - `"allow-all"`: Full internet access (default). All traffic is allowed.
|
|
19
|
+
* - `"deny-all"`: No internet access. All traffic is denied.
|
|
20
|
+
* - Object: Custom access with explicit allow/deny lists.
|
|
21
|
+
*/
|
|
22
|
+
export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
|
|
23
|
+
readonly allow?: string[] | Readonly<Record<string, SandboxNetworkPolicyRule[]>>;
|
|
24
|
+
};
|
|
25
|
+
export interface SandboxBootstrapUseOptions {
|
|
26
|
+
readonly runtime?: string;
|
|
27
|
+
readonly ports?: number[];
|
|
28
|
+
readonly env?: Record<string, string>;
|
|
29
|
+
}
|
|
30
|
+
export interface SandboxSessionUseOptions {
|
|
31
|
+
readonly networkPolicy?: SandboxNetworkPolicy;
|
|
32
|
+
readonly resources?: {
|
|
33
|
+
vcpus?: number;
|
|
34
|
+
};
|
|
35
|
+
readonly timeout?: number;
|
|
36
|
+
readonly tags?: Record<string, string>;
|
|
37
|
+
}
|
|
38
|
+
export type SandboxBootstrapUseFn = (options?: SandboxBootstrapUseOptions) => Promise<SandboxSession>;
|
|
39
|
+
export type SandboxSessionUseFn<S extends SandboxSession = SandboxSession> = (options?: SandboxSessionUseOptions) => Promise<S>;
|
|
40
|
+
export interface SandboxBootstrapContext {
|
|
41
|
+
readonly use: SandboxBootstrapUseFn;
|
|
42
|
+
}
|
|
43
|
+
export interface SandboxSessionContext<S extends SandboxSession = SandboxSession> {
|
|
44
|
+
readonly use: SandboxSessionUseFn<S>;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Public sandbox definition authored in `agent/sandbox.ts` (shorthand)
|
|
48
|
+
* or `agent/sandbox/sandbox.ts` (folder layout, when paired with an
|
|
49
|
+
* authored `sandbox/workspace/` subtree).
|
|
50
|
+
*
|
|
51
|
+
* Each agent (and each subagent) owns exactly one sandbox. When the
|
|
52
|
+
* module file is absent the framework auto-provides a default sandbox
|
|
53
|
+
* via `defaultBackend()`. Authors override lifecycle and backend by
|
|
54
|
+
* creating `agent/sandbox.ts` (or `agent/sandbox/sandbox.ts` when they
|
|
55
|
+
* also want a workspace folder); subagents override independently via
|
|
56
|
+
* `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
|
|
57
|
+
* their parent's sandbox (skill seeds differ per agent).
|
|
58
|
+
*/
|
|
59
|
+
export interface SandboxDefinition<S extends SandboxSession = SandboxSession> {
|
|
60
|
+
/**
|
|
61
|
+
* Backend that runs this sandbox.
|
|
62
|
+
*
|
|
63
|
+
* When this field is omitted, Ash substitutes `defaultBackend()` at
|
|
64
|
+
* runtime, which delegates to `vercelBackend()` on hosted Vercel
|
|
65
|
+
* (where `process.env.VERCEL` is set) and to `localBackend()`
|
|
66
|
+
* everywhere else. Set `backend` explicitly to pin the sandbox to a
|
|
67
|
+
* specific backend regardless of environment.
|
|
68
|
+
*/
|
|
69
|
+
backend: SandboxBackend<S>;
|
|
70
|
+
bootstrap?(input: SandboxBootstrapContext): Promise<void> | void;
|
|
71
|
+
onSession?(input: SandboxSessionContext<S>): Promise<void> | void;
|
|
72
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import type { Sandbox as AiSdkSandbox } from "ai";
|
|
2
|
+
/**
|
|
3
|
+
* Options for running a sandbox command.
|
|
4
|
+
*/
|
|
5
|
+
export type SandboxCommandOptions = Readonly<Omit<Parameters<AiSdkSandbox["executeCommand"]>[0], "command">>;
|
|
6
|
+
/**
|
|
7
|
+
* Serializable result returned after running one sandbox command.
|
|
8
|
+
*/
|
|
9
|
+
export type SandboxCommandResult = Readonly<Awaited<ReturnType<AiSdkSandbox["executeCommand"]>>>;
|
|
10
|
+
/**
|
|
11
|
+
* Options for reading a text file from a sandbox with optional line ranges.
|
|
12
|
+
*/
|
|
13
|
+
export interface SandboxReadFileOptions {
|
|
14
|
+
/**
|
|
15
|
+
* 1-based inclusive end line. When past the file's line count, the read
|
|
16
|
+
* returns through EOF without error.
|
|
17
|
+
*/
|
|
18
|
+
readonly endLine?: number;
|
|
19
|
+
/**
|
|
20
|
+
* 1-based inclusive start line. Defaults to 1.
|
|
21
|
+
*/
|
|
22
|
+
readonly startLine?: number;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Minimal Ash-owned sandbox session exposed to authored lifecycle hooks.
|
|
26
|
+
*/
|
|
27
|
+
export interface SandboxSession {
|
|
28
|
+
/**
|
|
29
|
+
* Stable identifier for the backend session this handle wraps.
|
|
30
|
+
*
|
|
31
|
+
* Persists across reconnects to the same logical session: two calls
|
|
32
|
+
* that resume the same underlying backend sandbox observe the same
|
|
33
|
+
* `id`. Template sessions constructed during bootstrap expose the
|
|
34
|
+
* template key; live sessions expose the session key assigned by the
|
|
35
|
+
* runtime. Useful as a cache key for per-session state that must
|
|
36
|
+
* outlive individual step executions.
|
|
37
|
+
*/
|
|
38
|
+
readonly id: string;
|
|
39
|
+
/**
|
|
40
|
+
* Reads one text file from the sandbox as UTF-8.
|
|
41
|
+
*
|
|
42
|
+
* Returns `null` when the file does not exist. Throws when the file
|
|
43
|
+
* contains invalid UTF-8.
|
|
44
|
+
*
|
|
45
|
+
* Relative paths resolve from `/workspace`, the live working directory
|
|
46
|
+
* for every backend. Absolute paths pass through unchanged.
|
|
47
|
+
*
|
|
48
|
+
* Line ranges are 1-based and inclusive. When `endLine` is past EOF the
|
|
49
|
+
* read returns through EOF without error.
|
|
50
|
+
*/
|
|
51
|
+
readFile(path: string, options?: SandboxReadFileOptions): Promise<string | null>;
|
|
52
|
+
/**
|
|
53
|
+
* Reads one file from the sandbox as raw bytes.
|
|
54
|
+
*
|
|
55
|
+
* Returns `null` when the file does not exist. Unlike
|
|
56
|
+
* {@link SandboxSession.readFile}, this variant performs no UTF-8
|
|
57
|
+
* decoding and is safe for binary payloads (images, PDFs, archives,
|
|
58
|
+
* attachment bytes written by the framework at
|
|
59
|
+
* `/workspace/attachments/...`).
|
|
60
|
+
*
|
|
61
|
+
* Relative paths resolve from `/workspace`, the live working
|
|
62
|
+
* directory for every backend. Absolute paths pass through unchanged.
|
|
63
|
+
*/
|
|
64
|
+
readFileBytes(path: string): Promise<Buffer | null>;
|
|
65
|
+
/**
|
|
66
|
+
* Anchors a sandbox-relative path to `/workspace` and returns the
|
|
67
|
+
* resulting absolute path.
|
|
68
|
+
*
|
|
69
|
+
* Relative paths resolve from `/workspace`; absolute paths pass through.
|
|
70
|
+
* `readFile(...)` and `writeFile(...)` already apply this internally.
|
|
71
|
+
*/
|
|
72
|
+
resolvePath(path: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* Runs one shell command inside the current sandbox session and returns the
|
|
75
|
+
* captured stdout, stderr, and exit code.
|
|
76
|
+
*
|
|
77
|
+
* Commands execute with `/workspace` as the working directory on every
|
|
78
|
+
* backend.
|
|
79
|
+
*/
|
|
80
|
+
runCommand(command: string, options?: SandboxCommandOptions): Promise<SandboxCommandResult>;
|
|
81
|
+
/**
|
|
82
|
+
* Writes one file to the sandbox, creating parent directories
|
|
83
|
+
* recursively and overwriting any existing file.
|
|
84
|
+
*
|
|
85
|
+
* `content` accepts a UTF-8 `string` for text files or a `Buffer` for
|
|
86
|
+
* arbitrary bytes. The framework uses the `Buffer` overload to mount
|
|
87
|
+
* binary workspace assets (images under skill `assets/` directories,
|
|
88
|
+
* fixture payloads, and so on) through the same public surface authors
|
|
89
|
+
* use.
|
|
90
|
+
*
|
|
91
|
+
* Relative paths resolve from `/workspace`. Absolute paths pass through
|
|
92
|
+
* unchanged.
|
|
93
|
+
*/
|
|
94
|
+
writeFile(path: string, content: string | Buffer): Promise<void>;
|
|
95
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "experimental-ash",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.2",
|
|
4
4
|
"bin": {
|
|
5
5
|
"ash": "./bin/ash.js",
|
|
6
6
|
"experimental-ash": "./bin/ash.js"
|
|
@@ -143,7 +143,7 @@
|
|
|
143
143
|
"@ai-sdk/google": "4.0.0-canary.53",
|
|
144
144
|
"@ai-sdk/mcp": "2.0.0-canary.41",
|
|
145
145
|
"@ai-sdk/openai": "4.0.0-canary.49",
|
|
146
|
-
"@ai-sdk/otel": "1.0.0-canary.
|
|
146
|
+
"@ai-sdk/otel": "1.0.0-canary.77",
|
|
147
147
|
"@ai-sdk/provider": "4.0.0-canary.16",
|
|
148
148
|
"@chat-adapter/slack": "^4.27.0",
|
|
149
149
|
"@chat-adapter/state-memory": "^4.27.0",
|
|
@@ -154,7 +154,7 @@
|
|
|
154
154
|
"@workflow/core": "5.0.0-beta.5",
|
|
155
155
|
"@workflow/errors": "5.0.0-beta.2",
|
|
156
156
|
"@workflow/world-local": "5.0.0-beta.4",
|
|
157
|
-
"ai": "7.0.0-canary.
|
|
157
|
+
"ai": "7.0.0-canary.131",
|
|
158
158
|
"autoevals": "^0.0.132",
|
|
159
159
|
"chat": "^4.27.0",
|
|
160
160
|
"chokidar": "^5.0.0",
|
|
@@ -170,7 +170,7 @@
|
|
|
170
170
|
},
|
|
171
171
|
"peerDependencies": {
|
|
172
172
|
"@opentelemetry/api": "^1.9.0",
|
|
173
|
-
"ai": "7.0.0-canary.
|
|
173
|
+
"ai": "7.0.0-canary.131",
|
|
174
174
|
"braintrust": ">=3.0.0"
|
|
175
175
|
},
|
|
176
176
|
"peerDependenciesMeta": {
|