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.
Files changed (31) hide show
  1. package/dist/src/chunks/{dev-authored-source-watcher-Bk-ZWzF_.js → dev-authored-source-watcher-MDHwWfTE.js} +1 -1
  2. package/dist/src/chunks/{host-CEiB9Ps8.js → host-CDvE1sV_.js} +2 -2
  3. package/dist/src/chunks/{paths-Dxh19LKr.js → paths-D1gMcyWw.js} +4 -4
  4. package/dist/src/chunks/{prewarm-BK_ZT4-w.js → prewarm-CCU5VjXa.js} +1 -1
  5. package/dist/src/cli/commands/info.js +1 -1
  6. package/dist/src/cli/run.js +1 -1
  7. package/dist/src/cli/templates/init-app/package.json +1 -1
  8. package/dist/src/compiled/.vendor-stamp.json +2 -2
  9. package/dist/src/compiled/@ai-sdk/otel/index.js +3 -3
  10. package/dist/src/compiled/@ai-sdk/otel/package.json +1 -1
  11. package/dist/src/compiled/@vercel/sandbox/index.d.ts +1 -0
  12. package/dist/src/evals/cli/eval.js +1 -1
  13. package/dist/src/execution/sandbox/bindings/local.js +32 -3
  14. package/dist/src/execution/sandbox/bindings/vercel.js +3 -2
  15. package/dist/src/execution/sandbox/session.d.ts +2 -2
  16. package/dist/src/execution/sandbox/session.js +2 -2
  17. package/dist/src/internal/application/package.js +1 -1
  18. package/dist/src/internal/authored-definition/sandbox.d.ts +3 -10
  19. package/dist/src/public/channels/slack/slackChannel.d.ts +7 -0
  20. package/dist/src/public/channels/slack/slackChannel.js +5 -0
  21. package/dist/src/public/definitions/sandbox-backend.d.ts +1 -123
  22. package/dist/src/public/definitions/sandbox.d.ts +6 -165
  23. package/dist/src/public/sandbox/index.d.ts +1 -1
  24. package/dist/src/runtime/types.d.ts +5 -8
  25. package/dist/src/shared/sandbox-backend.d.ts +124 -0
  26. package/dist/src/shared/sandbox-backend.js +1 -0
  27. package/dist/src/shared/sandbox-definition.d.ts +72 -0
  28. package/dist/src/shared/sandbox-definition.js +1 -0
  29. package/dist/src/shared/sandbox-session.d.ts +95 -0
  30. package/dist/src/shared/sandbox-session.js +1 -0
  31. package/package.json +4 -4
@@ -1,168 +1,9 @@
1
- import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
2
- /**
3
- * Serializable result returned after running one sandbox command.
4
- */
5
- export interface SandboxCommandResult {
6
- readonly exitCode: number;
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 {@link SandboxBackend} value, even when the
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 interface ResolvedSandboxDefinition extends ResolvedModuleSourceRef {
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
- readonly onSession?: (input: SandboxSessionContext) => Promise<void> | void;
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.1",
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.67",
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.121",
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.121",
173
+ "ai": "7.0.0-canary.131",
174
174
  "braintrust": ">=3.0.0"
175
175
  },
176
176
  "peerDependenciesMeta": {