eve 0.90.0 → 0.91.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/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/sandbox/default.mdx
CHANGED
|
@@ -3,7 +3,7 @@ title: "Default Sandbox"
|
|
|
3
3
|
description: "Let eve select the sandbox provider when it prepares the sandbox."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
`DefaultSandbox.environment()`
|
|
6
|
+
`DefaultSandbox.environment()` lets eve pick the sandbox provider for you. eve picks once, when it prepares the sandbox, and every session the build serves uses that provider. It's also what eve uses when the agent has no sandbox file.
|
|
7
7
|
|
|
8
8
|
```ts
|
|
9
9
|
import { DefaultSandbox, defineSandbox } from "eve/sandbox";
|
|
@@ -12,35 +12,28 @@ export const environment = DefaultSandbox.environment();
|
|
|
12
12
|
export default defineSandbox(() => environment.open());
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
On Vercel, it selects [Vercel Sandbox](/docs/sandbox/vercel). Elsewhere, it selects [Docker](/docs/sandbox/docker) when a Docker daemon is reachable, and [just-bash](/docs/sandbox/just-bash) only during `eve dev` and `eve eval`.
|
|
16
|
-
|
|
17
15
|
## How eve selects the provider
|
|
18
16
|
|
|
19
|
-
eve
|
|
20
|
-
|
|
21
|
-
1. If the `VERCEL` environment variable is set, it selects Vercel.
|
|
22
|
-
2. Otherwise, if `docker version` reports a running Linux Docker daemon within five seconds, it selects Docker.
|
|
23
|
-
3. Otherwise, during `eve dev` and `eve eval`, it selects just-bash.
|
|
24
|
-
4. Otherwise, in a production `eve build`, it selects no provider.
|
|
17
|
+
eve prepares the sandbox during `eve build`, or during `eve dev` the first time a session opens the sandbox. It takes the first row that matches:
|
|
25
18
|
|
|
26
|
-
| Where eve prepares the sandbox
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
| `eve dev` or `eve eval`
|
|
31
|
-
| A production `eve build`
|
|
19
|
+
| Where eve prepares the sandbox | Selected provider |
|
|
20
|
+
| ---------------------------------------------------------------------------- | --------------------------------------------- |
|
|
21
|
+
| The `VERCEL` environment variable is set (`vercel build` or a Vercel deploy) | [Vercel Sandbox](/docs/sandbox/vercel) |
|
|
22
|
+
| `docker version` reports a running Linux Docker daemon within five seconds | [Docker](/docs/sandbox/docker) |
|
|
23
|
+
| `eve dev` or `eve eval` | [just-bash](/docs/sandbox/just-bash) |
|
|
24
|
+
| A production `eve build` | None: opening the sandbox fails with an error |
|
|
32
25
|
|
|
33
|
-
Production builds never fall back to just-bash, because just-bash runs no native processes and provides no network isolation.
|
|
26
|
+
Production builds never fall back to just-bash, because just-bash runs no native processes and provides no network isolation. Without a provider, `eve build` succeeds and logs that no provider is available. The first session that opens the sandbox then fails. The error asks you to start Docker and rebuild, deploy to Vercel, or select a provider in your sandbox file. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#defaultsandbox-has-no-sandbox-provider-for-this-build).
|
|
34
27
|
|
|
35
28
|
## The build records the choice
|
|
36
29
|
|
|
37
|
-
`eve build`
|
|
30
|
+
`eve build` records the selected provider. The server always uses that provider, even on a different host, and doesn't check for Vercel or Docker again. To change the provider, rebuild where the provider you want is available.
|
|
38
31
|
|
|
39
|
-
|
|
32
|
+
When a session continues on a build with a different provider, it starts a fresh sandbox without the old sandbox's files. eve doesn't delete the old sandbox. A Vercel Sandbox stays in your Vercel project, and a Docker container stays on the Docker host until you remove it.
|
|
40
33
|
|
|
41
34
|
## Environment options
|
|
42
35
|
|
|
43
|
-
`DefaultSandbox.environment()` accepts options for each provider it might select.
|
|
36
|
+
`DefaultSandbox.environment()` accepts options for each provider it might select. It passes on only the selected provider's options:
|
|
44
37
|
|
|
45
38
|
```ts
|
|
46
39
|
import { DefaultSandbox, defineSandbox } from "eve/sandbox";
|
|
@@ -64,13 +57,13 @@ export default defineSandbox(() => environment.open());
|
|
|
64
57
|
| `vercel` | Vercel is selected | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials. |
|
|
65
58
|
| `justBash` | just-bash is selected | `autoInstall` and `prepare`. Use [`JustBashSandbox.environment()`](/docs/sandbox/just-bash#experimental-options) for experimental `customCommands` or `filesystem`. |
|
|
66
59
|
|
|
67
|
-
Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects.
|
|
60
|
+
Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects. Commands such as `apt-get` fail on just-bash, which runs no native binaries.
|
|
68
61
|
|
|
69
|
-
On Vercel, when the environment has no `prepare` callback, workspace seed, skill files, or `source
|
|
62
|
+
On Vercel, eve skips the snapshot when the environment has no `prepare` callback, workspace seed, skill files, or `source`. Each session sandbox then starts directly from the configured `image`, or from eve's base image when none is set. See [Vercel Sandbox](/docs/sandbox/vercel#snapshot-preparation).
|
|
70
63
|
|
|
71
64
|
## Network policy
|
|
72
65
|
|
|
73
|
-
|
|
66
|
+
To set a network policy on the selected provider, pass `networkPolicy` to `open()`. You can also call `setNetworkPolicy()` on the sandbox from `ctx.getSandbox(environment)`.
|
|
74
67
|
|
|
75
68
|
```ts
|
|
76
69
|
import { DefaultSandbox, defineSandbox } from "eve/sandbox";
|
|
@@ -79,6 +72,12 @@ export const environment = DefaultSandbox.environment();
|
|
|
79
72
|
export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
|
|
80
73
|
```
|
|
81
74
|
|
|
82
|
-
|
|
75
|
+
| Provider | Accepted policies |
|
|
76
|
+
| --------- | -------------------------------------------------------------------- |
|
|
77
|
+
| Vercel | Every policy, including domain allow-lists and credential transforms |
|
|
78
|
+
| Docker | `"allow-all"` and `"deny-all"` |
|
|
79
|
+
| just-bash | `"allow-all"` only, because it always allows network access |
|
|
80
|
+
|
|
81
|
+
Other policies throw an error.
|
|
83
82
|
|
|
84
|
-
Use a provider directly when you need its other `open()` options, such as Vercel compute resources or Drive `mounts`.
|
|
83
|
+
Use a provider directly when you need domain-level policies in every environment, or its other `open()` options, such as Vercel compute resources or Drive `mounts`. See [Vercel Sandbox](/docs/sandbox/vercel) and [Docker Sandbox](/docs/sandbox/docker).
|
package/docs/sandbox/docker.mdx
CHANGED
|
@@ -3,20 +3,21 @@ title: "Docker Sandbox"
|
|
|
3
3
|
description: "Create local persistent containers from an image or Dockerfile."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Docker
|
|
6
|
+
A Docker sandbox runs each session in its own local container, which keeps its files between turns. The container comes from eve's default image, an existing OCI image, or `agent/sandbox/Dockerfile`.
|
|
7
7
|
|
|
8
|
-
```ts
|
|
8
|
+
```ts title="agent/sandbox.ts"
|
|
9
9
|
import { defineSandbox } from "eve/sandbox";
|
|
10
10
|
import { DockerSandbox } from "eve/sandbox/docker";
|
|
11
11
|
|
|
12
12
|
export const environment = DockerSandbox.image("ghcr.io/acme/agent@sha256:...");
|
|
13
13
|
|
|
14
|
+
// networkPolicy is optional: "allow-all" or "deny-all"
|
|
14
15
|
export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
|
|
15
16
|
```
|
|
16
17
|
|
|
17
18
|
## Choose the base image
|
|
18
19
|
|
|
19
|
-
|
|
20
|
+
The three constructors create the same Docker environment. They differ only in how you pass the base image:
|
|
20
21
|
|
|
21
22
|
| Constructor | Base image without a Dockerfile |
|
|
22
23
|
| ------------------------------------------- | ---------------------------------------- |
|
|
@@ -24,28 +25,33 @@ export default defineSandbox(() => environment.open({ networkPolicy: "deny-all"
|
|
|
24
25
|
| `DockerSandbox.image("ghcr.io/acme/agent")` | The image reference you pass |
|
|
25
26
|
| `DockerSandbox.dockerfile()` | eve's default image |
|
|
26
27
|
|
|
27
|
-
When `agent/sandbox/Dockerfile` exists, eve builds it during preparation
|
|
28
|
+
When `agent/sandbox/Dockerfile` exists, eve builds it during preparation with `agent/sandbox/` as the build context. The result is the base image for every constructor, and it overrides any `image` you pass, including `DockerSandbox.image(ref)`. To use an existing image, remove the Dockerfile.
|
|
28
29
|
|
|
29
|
-
`DockerSandbox.dockerfile()
|
|
30
|
+
Use `DockerSandbox.dockerfile()`, which takes no `image` option, to make the sandbox file show that it uses the Dockerfile.
|
|
30
31
|
|
|
31
32
|
## eve's default image
|
|
32
33
|
|
|
33
34
|
eve's default image runs Ubuntu with Node.js 24, npm, Python 3, git, ripgrep, jq, and curl. Commands run as the `vercel-sandbox` user in `/workspace`, with passwordless `sudo`. Docker pulls it from `ghcr.io/vercel/eve`, and [Vercel Sandbox](/docs/sandbox/vercel) uses the same image from `vcr.vercel.com/vercel/eve/base`.
|
|
34
35
|
|
|
35
|
-
The default image
|
|
36
|
+
The default image doesn't include pnpm or pip, so install them in `prepare` when your agent needs them:
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
- `npm install -g pnpm` installs pnpm for the `vercel-sandbox` user.
|
|
39
|
+
- Ubuntu's system Python refuses `pip install`, so run `sudo apt-get install -y python3-venv` and use the pip inside a virtual environment. The [analysis tutorial](/docs/tutorial/run-analysis#install-the-chart-dependencies) shows the Python setup.
|
|
40
|
+
|
|
41
|
+
Preparation runs when eve builds the template, so it needs network access to the package registries.
|
|
42
|
+
|
|
43
|
+
Each eve release pins one tag of the default image, and the tag is not the eve version. Prepared templates include the image reference, so a new eve release reuses them unless it pins a different image.
|
|
38
44
|
|
|
39
45
|
To run a different published tag, set `EVE_SANDBOX_IMAGE_TAG` in both the build and runtime environments. eve applies the tag to both registries.
|
|
40
46
|
|
|
41
47
|
## Environment options
|
|
42
48
|
|
|
43
|
-
|
|
49
|
+
Pass `image`, `pullPolicy`, `env`, and `prepare` to the environment. During preparation, eve copies workspace and skill files into a temporary container and runs your `prepare`. It saves the result as the template image.
|
|
44
50
|
|
|
45
51
|
## Live container options
|
|
46
52
|
|
|
47
|
-
Pass `networkPolicy` to `open()
|
|
53
|
+
Pass `networkPolicy` to `open()` to set the live container's policy: `"allow-all"` or `"deny-all"`.
|
|
48
54
|
|
|
49
|
-
|
|
55
|
+
Each session's container keeps `/workspace` in its filesystem, and a stopped container restarts with those files. `sandbox.delete()` removes the container and succeeds when it's already gone.
|
|
50
56
|
|
|
51
57
|
See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.
|
package/docs/sandbox/index.mdx
CHANGED
|
@@ -3,11 +3,33 @@ title: "Sandbox"
|
|
|
3
3
|
description: "Configure the isolated filesystem and command environment used by an eve agent."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
The sandbox is the isolated filesystem and command environment of an eve agent. Each agent has one, and the built-in `bash`, `read_file`, and `write_file` tools run in it. Define it in `agent/sandbox.ts`, or omit the file to let eve select an environment automatically.
|
|
7
|
+
|
|
8
|
+
## Define an environment
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
agent/
|
|
12
|
+
├── agent.ts
|
|
13
|
+
└── sandbox.ts # or agent/sandbox/sandbox.ts when agent/sandbox/ exists
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
```ts title="agent/sandbox.ts"
|
|
17
|
+
import { DefaultSandbox, defineSandbox } from "eve/sandbox";
|
|
18
|
+
|
|
19
|
+
// required: `eve build` prepares this export before any session exists
|
|
20
|
+
export const environment = DefaultSandbox.environment();
|
|
21
|
+
// required: the selector that opens the sandbox for a session
|
|
22
|
+
export default defineSandbox(() => environment.open());
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- Put the file at `agent/sandbox/sandbox.ts` when the agent also has [workspace seeds](#managed-workspace-and-skills) or a Docker `Dockerfile` in `agent/sandbox/`. When the `agent/sandbox/` folder exists, put the definition there. A root `agent/sandbox.ts` beside that folder is a build error.
|
|
26
|
+
- `environment.open()` starts the sandbox for the current session.
|
|
27
|
+
- The selector runs until it succeeds once. After that, later workflow steps and process restarts resume the same sandbox without running the selector again.
|
|
28
|
+
- Commands start and relative paths resolve from the workspace root, `/workspace` on every built-in provider.
|
|
7
29
|
|
|
8
30
|
## Use the sandbox
|
|
9
31
|
|
|
10
|
-
Authored tools and callbacks
|
|
32
|
+
Authored tools and callbacks get the live sandbox with `ctx.getSandbox()`:
|
|
11
33
|
|
|
12
34
|
```ts title="agent/tools/run_analysis.ts"
|
|
13
35
|
import { defineTool } from "eve/tools";
|
|
@@ -19,6 +41,7 @@ export default defineTool({
|
|
|
19
41
|
async execute({ script }, ctx) {
|
|
20
42
|
const sandbox = await ctx.getSandbox();
|
|
21
43
|
await sandbox.writeTextFile({ path: "analysis.py", content: script });
|
|
44
|
+
// run() doesn't throw on a nonzero exit code
|
|
22
45
|
const result = await sandbox.run({ command: "python analysis.py" });
|
|
23
46
|
if (result.exitCode !== 0) throw new Error(result.stderr);
|
|
24
47
|
return result.stdout;
|
|
@@ -26,11 +49,11 @@ export default defineTool({
|
|
|
26
49
|
});
|
|
27
50
|
```
|
|
28
51
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
Built-in environments set `AI_AGENT=eve` on every `run()` and `spawn()` call, including the `bash` tool and `prepare
|
|
52
|
+
- `run()` returns `{ exitCode, stdout, stderr }`. `sandbox.resolvePath(".")` returns the workspace root's absolute path.
|
|
53
|
+
- Use `spawn()` for a long-running process. On Vercel and Docker, pass `stdin: true` to get a writable `stdin` stream, for example to talk to a stdio server. Closing the stream sends EOF.
|
|
54
|
+
- Built-in environments set `AI_AGENT=eve` on every `run()` and `spawn()` call, including the `bash` tool and `prepare`. Agent-aware CLIs such as `vercel` then skip interactive prompts. To override it, set `AI_AGENT` in the environment's `env` option or in one call's `env`.
|
|
32
55
|
|
|
33
|
-
Pass the configured environment to
|
|
56
|
+
The handle from `ctx.getSandbox()` has only the methods every provider shares. Pass the configured environment to also get provider-specific methods, such as Vercel's `setNetworkPolicy()`:
|
|
34
57
|
|
|
35
58
|
```ts
|
|
36
59
|
import { environment } from "../sandbox";
|
|
@@ -39,22 +62,22 @@ const sandbox = await ctx.getSandbox(environment);
|
|
|
39
62
|
await sandbox.setNetworkPolicy("deny-all");
|
|
40
63
|
```
|
|
41
64
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
## Define an environment
|
|
65
|
+
The environment you pass must match the one configured for the current sandbox.
|
|
45
66
|
|
|
46
|
-
|
|
67
|
+
## Providers
|
|
47
68
|
|
|
48
|
-
|
|
49
|
-
|
|
69
|
+
| Provider | Use it for |
|
|
70
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
71
|
+
| [Default](/docs/sandbox/default) | Vercel Sandbox on Vercel, Docker when reachable, and just-bash in development. |
|
|
72
|
+
| [Vercel](/docs/sandbox/vercel) | Persistent Vercel Sandboxes, prepared snapshots, domain network policies, and Drive mounts. |
|
|
73
|
+
| [Docker](/docs/sandbox/docker) | Local containers from the default image, an existing OCI image, or a Dockerfile. |
|
|
74
|
+
| [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation. |
|
|
50
75
|
|
|
51
|
-
|
|
52
|
-
export default defineSandbox(() => environment.open());
|
|
53
|
-
```
|
|
76
|
+
`DefaultSandbox` accepts only `autoInstall` and `prepare` for just-bash. Use the [experimental options](/docs/sandbox/just-bash#experimental-options) of `JustBashSandbox.environment()` from `eve/sandbox/just-bash` for custom commands or filesystems.
|
|
54
77
|
|
|
55
|
-
|
|
78
|
+
## Initialize a session's sandbox
|
|
56
79
|
|
|
57
|
-
Pass
|
|
80
|
+
Pass live sandbox options to `open()`, then configure the sandbox before you return it. `open()` applies its options only when it creates the sandbox.
|
|
58
81
|
|
|
59
82
|
```ts
|
|
60
83
|
import { defineSandbox } from "eve/sandbox";
|
|
@@ -69,13 +92,18 @@ export default defineSandbox(async ({ session }) => {
|
|
|
69
92
|
});
|
|
70
93
|
```
|
|
71
94
|
|
|
72
|
-
|
|
95
|
+
Make initialization safe to repeat, because it can run more than once against the same sandbox:
|
|
96
|
+
|
|
97
|
+
- A subagent that shares the sandbox opens it before the parent does.
|
|
98
|
+
- A [workflow step](/docs/tools/workflows#use-the-session-sandbox-in-a-step) opens it before the session records it.
|
|
99
|
+
- The first turn of a prewarmed session opens it while prewarming is still starting it.
|
|
100
|
+
- A previous initialization failed.
|
|
73
101
|
|
|
74
|
-
The
|
|
102
|
+
A [prewarmed session](/docs/guides/frontend/use-eve-agent#prewarming), for example from `useEveAgent({ prewarm: true })`, runs the selector before the first message. The selector sees `session.auth` from the request that created the session. eve keeps the sandbox options and `defineState()` values from that run, even when the first message's `onMessage` hook returns a different identity. In an agent whose clients prewarm, don't derive either from `session.auth`.
|
|
75
103
|
|
|
76
|
-
|
|
104
|
+
## Prepare a reusable environment
|
|
77
105
|
|
|
78
|
-
Use the environment's `prepare` option for setup every new sandbox inherits:
|
|
106
|
+
Use the environment's `prepare` option for setup that every new sandbox inherits:
|
|
79
107
|
|
|
80
108
|
```ts
|
|
81
109
|
import { defineSandbox } from "eve/sandbox";
|
|
@@ -93,19 +121,19 @@ export const environment = VercelSandbox.environment({
|
|
|
93
121
|
export default defineSandbox(() => environment.open());
|
|
94
122
|
```
|
|
95
123
|
|
|
96
|
-
|
|
124
|
+
`prepare` runs once per reusable template, not once per session. The template is a Vercel snapshot, a Docker image, or a just-bash filesystem template.
|
|
97
125
|
|
|
98
|
-
|
|
126
|
+
`eve build` prepares every environment. During `eve dev`, the first sandbox access after startup or a rebuild prepares all environments in the build, including those of subagents and extensions. That access can be slow, and a later access retries a failed preparation.
|
|
99
127
|
|
|
100
|
-
|
|
128
|
+
Production creates sandboxes only from the templates the build recorded, and never rebuilds a missing one. A missing image, snapshot, or template fails with rebuild or redeploy guidance; see [Sandbox troubleshooting](/docs/sandbox/troubleshooting).
|
|
101
129
|
|
|
102
|
-
|
|
130
|
+
## Reuse native resources across sessions
|
|
103
131
|
|
|
104
|
-
Built-in environments
|
|
132
|
+
Built-in environments don't share sandboxes across sessions. To reuse native compute or storage, define a [custom provider](/docs/sandbox/custom-providers) that gives each session its own view of the shared resources. Keep the shared resources out of its `stop()` and `onSessionEnd()`. A session-specific path is not an isolation boundary, so sessions that don't trust each other need separate native compute or stronger isolation from the provider.
|
|
105
133
|
|
|
106
|
-
|
|
134
|
+
## Share a parent sandbox
|
|
107
135
|
|
|
108
|
-
A declared subagent can use
|
|
136
|
+
A declared subagent can use the sandbox of the parent that called it:
|
|
109
137
|
|
|
110
138
|
```ts title="agent/subagents/reviewer/sandbox.ts"
|
|
111
139
|
import { defineParentSandbox } from "eve/sandbox";
|
|
@@ -113,13 +141,14 @@ import { defineParentSandbox } from "eve/sandbox";
|
|
|
113
141
|
export default defineParentSandbox();
|
|
114
142
|
```
|
|
115
143
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
144
|
+
- The parent and every subagent that shares its sandbox, including children of the built-in `agent` tool, use one sandbox that belongs to the parent's session.
|
|
145
|
+
- Whichever agent opens the sandbox first runs the parent's selector.
|
|
146
|
+
- eve deletes the sandbox when the parent session ends, even if only a subagent opened it.
|
|
147
|
+
- A subagent that shares its parent's sandbox can't declare its own managed workspace or skill files.
|
|
119
148
|
|
|
120
149
|
## Managed workspace and skills
|
|
121
150
|
|
|
122
|
-
|
|
151
|
+
Put workspace seed files in the sandbox directory:
|
|
123
152
|
|
|
124
153
|
```text
|
|
125
154
|
agent/sandbox/
|
|
@@ -128,61 +157,64 @@ agent/sandbox/
|
|
|
128
157
|
schema.sql
|
|
129
158
|
```
|
|
130
159
|
|
|
131
|
-
Files under `agent/sandbox/workspace/` seed writable `/workspace`.
|
|
160
|
+
Files under `agent/sandbox/workspace/` seed writable `/workspace`. Each new session sandbox starts with a copy of them. Later changes to the seeds don't overwrite existing sandboxes.
|
|
132
161
|
|
|
133
|
-
Agent skills
|
|
162
|
+
Agent skills appear at `$HOME/.agents/skills`, or at `skills/` under the workspace root when the sandbox has no usable home directory. Instructions and tools can refer to `/workspace` and `$HOME/.agents/skills` on every built-in provider. Don't refer to a concrete home directory or to `/eve/resources`, which is internal to providers.
|
|
134
163
|
|
|
135
|
-
|
|
164
|
+
A [custom provider](/docs/sandbox/custom-providers#bake-files-into-templates) can declare a different workspace root, so prefer relative paths in code that runs on any provider.
|
|
136
165
|
|
|
137
166
|
## Inbound attachments
|
|
138
167
|
|
|
139
|
-
eve
|
|
168
|
+
eve copies files that reach the agent into `.eve/attachments/` in the workspace root, which is `/workspace/.eve/attachments/` on built-in providers. Session history keeps only a reference to each file. This covers:
|
|
140
169
|
|
|
141
|
-
Files
|
|
170
|
+
- Files attached to user messages.
|
|
171
|
+
- Files that tools return with `toolOutputPart.file`.
|
|
172
|
+
- MCP image, audio, and blob content.
|
|
142
173
|
|
|
143
|
-
|
|
174
|
+
Files returned by URL with `toolOutputPart.fileUrl` aren't copied, because the model provider reads the URL directly; see [Send a file by URL](/docs/tools#send-a-file-by-url).
|
|
175
|
+
|
|
176
|
+
Every copied file reaches the model on every call with a label that names its sandbox path, such as `Attached file /workspace/.eve/attachments/<hash>/report.csv (text/csv)`. The agent can open that path with `read_file` or `bash`. The file's bytes follow the label only for formats every major provider reads natively:
|
|
144
177
|
|
|
145
178
|
- A PNG, JPEG, GIF, or WebP image up to 3 MiB and at most 8000 pixels per side.
|
|
146
179
|
- A PDF up to 20 MiB.
|
|
147
180
|
|
|
148
|
-
Other files, such as CSV, HEIC, audio, and video, reach the model as the label alone.
|
|
181
|
+
Other files, such as CSV, HEIC, audio, and video, reach the model as the label alone. An image or PDF whose bytes don't match its declared type is stored as `application/octet-stream`, so a provider never receives bytes it would reject.
|
|
149
182
|
|
|
150
|
-
To let the agent answer voice notes and other audio, add a tool that transcribes the
|
|
183
|
+
To let the agent answer voice notes and other audio, add a tool that transcribes the copied file. See [Voice notes](/docs/patterns/voice-notes).
|
|
151
184
|
|
|
152
|
-
|
|
185
|
+
| What happens | What the model receives |
|
|
186
|
+
| ---------------------------------------------------------------------- | ---------------------------------- |
|
|
187
|
+
| The copied file is missing from the sandbox, or something overwrote it | A `FileNotFound` note in its place |
|
|
188
|
+
| A channel's `fetchFile` fails | A note that names the file |
|
|
189
|
+
| A file part's `data` is not bytes, base64, a `data:` URL, or a URL | A note that names the file |
|
|
153
190
|
|
|
154
|
-
|
|
191
|
+
In the last two cases, the file never enters session history.
|
|
155
192
|
|
|
156
|
-
|
|
193
|
+
The model keeps seeing attachments from earlier turns. Each call sends the same bytes, so the provider's prompt cache stays valid. Compaction replaces files in older tool results with their text reference. `read_file` returns images and PDFs to the model as files. The agent can use it to reopen an attachment after compaction, or to view a PDF that `bash` wrote.
|
|
157
194
|
|
|
158
195
|
## Custom providers
|
|
159
196
|
|
|
160
|
-
To run sandboxes on a backend eve
|
|
161
|
-
|
|
162
|
-
## Providers
|
|
163
|
-
|
|
164
|
-
| Provider | Use it for |
|
|
165
|
-
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
166
|
-
| [Default](/docs/sandbox/default) | Vercel Sandbox on Vercel, Docker when reachable, and just-bash in development. |
|
|
167
|
-
| [Vercel](/docs/sandbox/vercel) | Persistent Vercel Sandboxes, prepared snapshots, domain network policies, and Drive mounts. |
|
|
168
|
-
| [Docker](/docs/sandbox/docker) | Local containers from the default image, an existing OCI image, or a Dockerfile. |
|
|
169
|
-
| [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation. |
|
|
170
|
-
|
|
171
|
-
For SDK-specific just-bash commands or filesystem factories, use the experimental options of
|
|
172
|
-
`JustBashSandbox.environment()` from `eve/sandbox/just-bash`. `DefaultSandbox` keeps only
|
|
173
|
-
`autoInstall` and `prepare` for its just-bash fallback.
|
|
197
|
+
To run sandboxes on a backend eve doesn't ship, define a provider with `defineSandboxProvider()` from `eve/sandbox/provider`. It implements a connection to one sandbox (`spawn`, `readFile`, `writeFiles`, `removePath`, and `stop`) and the methods `prepare`, `start`, `resume`, and `onSessionEnd`. See [Custom sandbox providers](/docs/sandbox/custom-providers) for a complete example.
|
|
174
198
|
|
|
175
199
|
## Lifecycle
|
|
176
200
|
|
|
177
|
-
|
|
201
|
+
Each session's sandbox persists across turns and deployments while the provider still has it.
|
|
202
|
+
|
|
203
|
+
| Event | Result |
|
|
204
|
+
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
205
|
+
| `sandbox.stop()` | Compute stops and files persist. The next access resumes it. |
|
|
206
|
+
| `sandbox.delete()` | The sandbox and its files are deleted. The next `ctx.getSandbox()` runs the selector again for a fresh sandbox. |
|
|
207
|
+
| The native sandbox is gone on resume, such as after a removed container or deleted just-bash session directory | The session continues in a fresh sandbox, without the lost files. |
|
|
208
|
+
| The session's sandbox came from another provider or state version, such as after you change providers | The session continues in a fresh sandbox. eve doesn't delete the old one. |
|
|
209
|
+
| The session ends | eve calls the provider's `onSessionEnd()` to delete the session's remaining sandbox. |
|
|
178
210
|
|
|
179
|
-
|
|
211
|
+
Session end doesn't wait for running subagent steps to stop. A subagent step still running at that moment can reopen the sandbox after cleanup, and eve doesn't remove a sandbox created that late.
|
|
180
212
|
|
|
181
|
-
|
|
213
|
+
New sessions get a new environment when you change the sandbox source, `prepare` code, Dockerfile, environment options, workspace seeds, or skills. Existing sessions keep their sandbox.
|
|
182
214
|
|
|
183
215
|
## What to read next
|
|
184
216
|
|
|
185
217
|
- [Sandbox troubleshooting](/docs/sandbox/troubleshooting) explains common sandbox errors and how to fix them.
|
|
186
|
-
- [Subagents](/docs/subagents) explains delegation and sandbox
|
|
218
|
+
- [Subagents](/docs/subagents) explains delegation and which agent's session a sandbox belongs to.
|
|
187
219
|
- [Security model](/docs/concepts/security-model) describes the app-runtime and sandbox trust boundary.
|
|
188
220
|
- [Vercel Sandbox](https://vercel.com/docs/sandbox) documents hosted sandbox behavior.
|
|
@@ -3,9 +3,9 @@ title: "just-bash Sandbox"
|
|
|
3
3
|
description: "Use a pure-JavaScript shell and virtual filesystem."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
`JustBashSandbox.environment()`
|
|
6
|
+
`JustBashSandbox.environment()` gives each session a pure-JavaScript shell and a virtual filesystem that keeps its files between turns. It starts no container or VM.
|
|
7
7
|
|
|
8
|
-
```ts
|
|
8
|
+
```ts title="agent/sandbox.ts"
|
|
9
9
|
import { defineSandbox } from "eve/sandbox";
|
|
10
10
|
import { JustBashSandbox } from "eve/sandbox/just-bash";
|
|
11
11
|
|
|
@@ -13,21 +13,21 @@ export const environment = JustBashSandbox.environment();
|
|
|
13
13
|
export default defineSandbox(() => environment.open());
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
just-bash can
|
|
16
|
+
just-bash can't use OCI images or Dockerfiles, runs no native processes, and provides no network isolation. Its session has no `setNetworkPolicy()`.
|
|
17
17
|
|
|
18
18
|
## Automatic installation
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
During `eve dev`, eve installs the `just-bash` package into your application when an environment uses it and it's missing. Set `autoInstall: false` in the environment options to skip this. Other commands require you to install the package yourself.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
With pnpm, automatic installation skips the optional native codecs `@mongodb-js/zstd` and `node-liblzma` unless they have an explicit package policy. It adds them to `ignoredOptionalDependencies` in the `pnpm-workspace.yaml` of the workspace that contains your app. Basic shell and filesystem operations don't need them, but commands that do may be unavailable. eve keeps your existing per-package build settings and doesn't approve build scripts.
|
|
23
23
|
|
|
24
24
|
## Experimental options
|
|
25
25
|
|
|
26
|
-
`experimental.customCommands` and `experimental.filesystem` follow just-bash's own command and filesystem contracts, so they
|
|
26
|
+
`experimental.customCommands` and `experimental.filesystem` follow just-bash's own command and filesystem contracts, so they have no compatibility promise. Import their types, such as `JustBashCommand` and `JustBashFilesystem`, from `eve/experimental/sandbox/just-bash`. `autoInstall` and `prepare` are stable.
|
|
27
27
|
|
|
28
28
|
### Custom commands
|
|
29
29
|
|
|
30
|
-
`experimental.customCommands`
|
|
30
|
+
`experimental.customCommands` adds your own functions as commands in each live shell. They work in pipelines and redirections:
|
|
31
31
|
|
|
32
32
|
```ts
|
|
33
33
|
import { defineSandbox } from "eve/sandbox";
|
|
@@ -47,13 +47,19 @@ export const environment = JustBashSandbox.environment({
|
|
|
47
47
|
export default defineSandbox(() => environment.open());
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
-
A `JustBashCommand` receives `cwd`, `env`, `fs`, and `signal` in its context. When a command needs standard input or the rest of just-bash's command context, create it with `defineCommand()` from `just-bash
|
|
50
|
+
A `JustBashCommand` receives `cwd`, `env`, `fs`, and `signal` in its context. When a command needs standard input or the rest of just-bash's command context, create it with `defineCommand()` from `just-bash`. `experimental.customCommands` accepts the result.
|
|
51
51
|
|
|
52
|
-
Custom commands run as
|
|
52
|
+
Custom commands run as app code in the app runtime process, outside the virtual filesystem. They aren't available while eve prepares the template.
|
|
53
53
|
|
|
54
54
|
### Custom filesystem
|
|
55
55
|
|
|
56
|
-
`experimental.filesystem`
|
|
56
|
+
`experimental.filesystem` builds the filesystem of each live sandbox. eve calls it with:
|
|
57
|
+
|
|
58
|
+
- `defaultFilesystem`: the session's saved filesystem that holds `/workspace`.
|
|
59
|
+
- `justBash`: the loaded `just-bash` module.
|
|
60
|
+
- `resolveProjectPath`: resolves a path relative to your app.
|
|
61
|
+
|
|
62
|
+
Return a `JustBashFilesystem` that keeps `defaultFilesystem` as its base, such as a just-bash `MountableFs`:
|
|
57
63
|
|
|
58
64
|
```ts
|
|
59
65
|
import { defineSandbox } from "eve/sandbox";
|
|
@@ -82,6 +88,6 @@ export const environment = JustBashSandbox.environment({
|
|
|
82
88
|
export default defineSandbox(() => environment.open());
|
|
83
89
|
```
|
|
84
90
|
|
|
85
|
-
eve does not call `filesystem` while it prepares the template, so files under a mount are not part of the template.
|
|
91
|
+
eve does not call `experimental.filesystem` while it prepares the template, so files under a mount are not part of the template.
|
|
86
92
|
|
|
87
93
|
See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.
|