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
|
@@ -3,13 +3,13 @@ title: "TypeScript API Reference"
|
|
|
3
3
|
description: "The define* helpers, the runtime ctx, and where each one is imported from."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
The `eve` package's public surface is the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The package's export map defines the full contract; anything not reachable through an exported subpath is internal.
|
|
7
7
|
|
|
8
8
|
For changes to an existing application, follow [Prepare for 1.0](../guides/prepare-for-1-0).
|
|
9
9
|
|
|
10
10
|
Identity comes from the filesystem, not a field you set. A tool at `agent/tools/get_weather.ts` is `get_weather`, and a connection at `agent/connections/linear.ts` is `linear`, so no definition carries a `name` or `id`.
|
|
11
11
|
|
|
12
|
-
Most files
|
|
12
|
+
Most files import a helper and default-export the result:
|
|
13
13
|
|
|
14
14
|
```ts title="agent/agent.ts"
|
|
15
15
|
import { defineAgent } from "eve";
|
|
@@ -32,8 +32,7 @@ export default defineTool({
|
|
|
32
32
|
|
|
33
33
|
## Integration dependencies
|
|
34
34
|
|
|
35
|
-
Install the
|
|
36
|
-
using another entry does not require them.
|
|
35
|
+
Install the packages for each integration entry you import. They are optional peers of eve, so other entries don't need them.
|
|
37
36
|
|
|
38
37
|
| Entry | Required integration packages |
|
|
39
38
|
| ------------------------------------------------------------- | ----------------------------------------------------- |
|
|
@@ -84,29 +83,35 @@ The AI SDK is a required peer and has its own Zod peer requirement. To type the
|
|
|
84
83
|
| `mockModel` | `eve/evals` | Deterministic fixture agent models | [Evals](../evals/overview) |
|
|
85
84
|
| `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) |
|
|
86
85
|
|
|
87
|
-
Tool-wide
|
|
86
|
+
Tool-wide helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Built-in tool definitions use their own subpaths; see [Built-in tools](../concepts/built-in-tools):
|
|
88
87
|
|
|
89
|
-
|
|
88
|
+
- Reusable definitions such as `bash` and `glob` from `eve/tools/<name>`.
|
|
89
|
+
- `webSearch` from `eve/tools/web_search`, `agentRouter` from `eve/tools/agent_router`, `sleep` from `eve/tools/sleep`, and `noReply` from `eve/tools/no_reply`.
|
|
90
|
+
- Approval policies and types from `eve/tools/approval`.
|
|
90
91
|
|
|
91
|
-
|
|
92
|
+
The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` and `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`.
|
|
92
93
|
|
|
93
|
-
`
|
|
94
|
+
`eve` exports `AgentReasoningDefinition` for `defineAgent({ reasoning })`, `AgentLimitsDefinition` for `defineAgent({ limits })`, and `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` for `defineAgent({ experimental: { workflow } })`. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
|
|
94
95
|
|
|
95
|
-
|
|
96
|
+
`webSearch({ provider })` selects `"exa"`, `"parallel"`, `"browserbase"`, or `"native"` for AI Gateway search with the Gateway model's credentials. `"native"` uses the model vendor's own search for OpenAI, Anthropic, and Gemini 3 and later models. Other Gateway models get no search unless you set `fallback` to `"exa"`, `"parallel"`, or `"browserbase"`. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.
|
|
97
|
+
|
|
98
|
+
`defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omit `role` for `"system"`. Dynamic instructions use `defineDynamic(ctx => defineInstructions(...))` or return `null`.
|
|
99
|
+
|
|
100
|
+
Dynamic connections use `defineDynamic(ctx => value)`, returning one MCP or OpenAPI connection definition, a map, or `null`. Functions read the saved session context and can load conversation history with `ctx.messages()`. Set `instanceKey` to a stable, non-secret account or tenant identifier. eve rejects a pending sign-in callback when its resolved connection instance changes. See [Dynamic capabilities](../guides/dynamic-capabilities).
|
|
96
101
|
|
|
97
102
|
## Authored module lifecycle
|
|
98
103
|
|
|
99
|
-
eve evaluates TypeScript definition modules
|
|
104
|
+
eve evaluates TypeScript definition modules at build time to validate the agent, at most once per agent. The resolved definition decides whether the module also loads at runtime:
|
|
100
105
|
|
|
101
|
-
|
|
|
106
|
+
| When it loads | Authored definitions |
|
|
102
107
|
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
103
108
|
| Compile only | Static instructions and skills, prompt-form TypeScript schedules, static Gateway or default agent config, provider-managed web search, Workflow SDK configuration, fully shadowed channels, and a child sandbox that selects its parent's sandbox |
|
|
104
109
|
| Compile and runtime | Dynamic instructions, skills, tools, models, and subagents; executable tools; effective channels; connections; hooks; memory; handler schedules; direct-provider models; independent sandboxes; and remote subagents |
|
|
105
110
|
| Runtime only | Instrumentation modules and extension mount initialization |
|
|
106
111
|
|
|
107
|
-
|
|
112
|
+
The deployed runtime doesn't import a compile-only module; for example, a static `instructions.ts` runs only at build time. A compile-and-runtime module runs at build time and again in each runtime process. Keep module top-level work deterministic, and put request- or session-specific work in runtime callbacks.
|
|
108
113
|
|
|
109
|
-
|
|
114
|
+
These load rules apply to definition modules, not their ordinary imports. A helper that a tool imports stays runtime code even if static instructions also import it.
|
|
110
115
|
|
|
111
116
|
### Asset imports
|
|
112
117
|
|
|
@@ -119,21 +124,30 @@ import template from "../../prompts/template.txt?raw";
|
|
|
119
124
|
|
|
120
125
|
`?raw` embeds any file as UTF-8 text, including code files such as `.json` and files without an extension, such as a `Dockerfile`. Other non-code asset imports produce a data URL with an inferred media type. Compilation, local development, and production builds use the same resolution behavior.
|
|
121
126
|
|
|
122
|
-
A workspace package bundled from TypeScript source can import its own assets the same way. Each import may reach files inside the project package or
|
|
127
|
+
A workspace package bundled from TypeScript source can import its own assets the same way. Each import may reach files inside the project package or the importing module's package. eve rejects imports that escape both, so package those files with the application or the workspace package.
|
|
123
128
|
|
|
124
129
|
## Runtime context (`ctx`)
|
|
125
130
|
|
|
126
|
-
`ctx` is passed to your tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers. It
|
|
131
|
+
`ctx` is passed to your tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers. It exists only while authored code runs, so reading it at module top level throws. See [Session context](../guides/session-context) for the full model.
|
|
127
132
|
|
|
128
133
|
| Member | Use |
|
|
129
134
|
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
130
135
|
| `ctx.session` | Current session, turn, auth, and optional parent lineage (read-only) |
|
|
131
|
-
| `ctx.getSandbox()` | Live sandbox handle; `stop()` releases compute
|
|
136
|
+
| `ctx.getSandbox()` | Live sandbox handle; `stop()` releases compute and keeps the sandbox's files |
|
|
132
137
|
| `ctx.getToken(provider)` | Resolve a bearer token for an inline auth provider such as `connect("...")` |
|
|
133
138
|
| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
|
|
134
139
|
| `ctx.approval` | Present only while a call runs after a person approved it: `responder` is who approved it and `responder.getToken(provider)` resolves their token. The call still runs as `ctx.session.auth.current`; see [Human-in-the-loop](/docs/human-in-the-loop) |
|
|
135
140
|
|
|
136
|
-
Tool definitions accept
|
|
141
|
+
Tool definitions accept these options:
|
|
142
|
+
|
|
143
|
+
- `availableInSubagents: false` restricts the tool to top-level root sessions.
|
|
144
|
+
- `deferred: true` keeps the tool out of the model's tool list. The model finds it with `eve__search` and calls it with `eve__tool`; see [Tools](../tools#keep-a-tool-out-of-the-tool-list).
|
|
145
|
+
|
|
146
|
+
`defineTool` definitions accept `endsTurn: true`, or a function that receives the `execute` output, to end the turn without a reply after a successful call; see [Tools](../tools#end-the-turn-after-a-tool-call).
|
|
147
|
+
|
|
148
|
+
Authored workflow bodies also receive `ctx.agents`, a map that describes the agents the workflow can call. It stays the same across workflow replays. `ctx.agent(name)` returns an `AgentSession` whose `send(message, options?)` resolves to a response with `result()`. The `agent` entry is a copy of the root agent, and its description is empty when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
|
|
149
|
+
|
|
150
|
+
Type the context in a `"use step"` helper as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`. Its `getSandbox()` opens the sandbox of the session that called the tool (see [Use the session sandbox in a step](../tools/workflows#use-the-session-sandbox-in-a-step)).
|
|
137
151
|
|
|
138
152
|
## Imports at a glance
|
|
139
153
|
|
|
@@ -184,43 +198,30 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
|
|
|
184
198
|
| `eve/next`, `eve/nuxt`, `eve/sveltekit`, `eve/tanstack` | framework bundler plugins |
|
|
185
199
|
| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, `EveError` and the typed client errors |
|
|
186
200
|
| [`eve/sessions`](../guides/client/messages#reusable-delivery-reads) | `Delivery`, `DeliveryResult`, read options, `SessionReader`, `Session`, `EveError`, and `SessionNotActiveError` |
|
|
187
|
-
| [`eve/events`](../concepts/sessions-runs-and-streaming#query-session-state) |
|
|
201
|
+
| [`eve/events`](../concepts/sessions-runs-and-streaming#query-session-state) | Event types, opaque `SessionView`, immutable observations, and query/fold functions |
|
|
188
202
|
| [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process |
|
|
189
203
|
|
|
190
|
-
Exported types ship from the entry point that owns them
|
|
191
|
-
have one home, `eve/sessions`; client factories and transport-specific types stay in `eve/client`.
|
|
192
|
-
`SessionInfo` from `eve/context` is callback metadata, not a reader or an operable session.
|
|
193
|
-
`ChannelContext` from `eve/channels` separates session information from continuation aliasing.
|
|
204
|
+
Exported types ship from the entry point that owns them, such as `ToolDefinition` and `ToolContext` from `eve/tools`. Import event and view types from `eve/events`, `SessionContext` and `HistoryMessage` from `eve/context`, and assertion types and `ToolStub` from `eve/evals`. Frontend hook entries also export the types their hooks return.
|
|
194
205
|
|
|
195
|
-
|
|
206
|
+
Types for reading sent messages and sessions live in `eve/sessions`; client factories and transport-specific types stay in `eve/client`. `SessionInfo` from `eve/context` is callback metadata, not a reader or an operable session. `ChannelContext` from `eve/channels` holds the session's `id` and `auth`, plus an optional `continuation` routing token that `alias()` can extend.
|
|
196
207
|
|
|
197
|
-
|
|
208
|
+
`HistoryMessage`, `EveLanguageModel`, `TokenUsage`, and the sandbox session, process, result, and method-option types are eve-owned. So are the `SpanProcessor`, `SpanProcessorOrName`, and `SpanExporter` types from `eve/instrumentation/otel`, and the Linq and Photon credential and webhook-verifier types. Their declarations don't change with your app's AI SDK, OpenTelemetry, or channel-adapter versions. Named judge, mock-model, approval, and disabled-marker types are public for reusable helpers and declaration emission.
|
|
198
209
|
|
|
199
|
-
|
|
200
|
-
`eve/experimental/*` and `eve/internal/*` have no compatibility promise. The same
|
|
201
|
-
applies to `experimental` fields in stable definitions, such as
|
|
202
|
-
`defineAgent({ experimental })`, connection `experimental.events`, and
|
|
203
|
-
`JustBashSandbox.environment({ experimental })`.
|
|
210
|
+
## Stability policy
|
|
204
211
|
|
|
205
|
-
|
|
206
|
-
kinds under the [stream evolution rules](../concepts/sessions-runs-and-streaming#what-a-later-release-can-add)
|
|
207
|
-
is not a breaking change. Keep a default branch when switching on those values.
|
|
212
|
+
The `exports` field in eve's `package.json` lists every entry point. `eve/experimental/*` and `eve/internal/*` have no compatibility promise. Neither do `experimental` fields in stable definitions, such as `defineAgent({ experimental })`, connection `experimental.events`, and `JustBashSandbox.environment({ experimental })`. The CLI setup wizard is not a public authoring API.
|
|
208
213
|
|
|
209
|
-
|
|
210
|
-
release, such as a sandbox provider's `onSessionEnd()` `reason`, the provider
|
|
211
|
-
context's `kind`, and `SandboxNetworkRule` variants. Handle unknown values, for
|
|
212
|
-
example with a default branch, instead of switching exhaustively.
|
|
214
|
+
Event union types name today's values. A release can add event types, outcomes, and request kinds under the [stream evolution rules](../concepts/sessions-runs-and-streaming#what-a-later-release-can-add) without a breaking change, so keep a default branch when you switch on them.
|
|
213
215
|
|
|
214
|
-
`
|
|
215
|
-
types from the `chat` package (Chat SDK v4) as part of their contract. They track
|
|
216
|
-
`chat` v4, so a future breaking `chat` major may require a corresponding eve change.
|
|
216
|
+
Values eve passes into code you implement can also gain members in a minor release. Examples are a sandbox provider's `onSessionEnd()` `reason`, the provider context's `kind`, and `SandboxNetworkRule` variants. Handle unknown values with a default branch instead of switching exhaustively.
|
|
217
217
|
|
|
218
|
-
|
|
219
|
-
integration lives at `eve/internal/scaffold`.
|
|
218
|
+
`eve/channels/chat-sdk`, `eve/channels/linq`, and `eve/channels/photon` expose types from the `chat` package (Chat SDK v4) as part of their contract. A future breaking `chat` major can require a matching eve change.
|
|
220
219
|
|
|
221
220
|
## Direct provider models
|
|
222
221
|
|
|
223
|
-
`openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return AI SDK language models that use eve's credentials, so you can also pass them to AI SDK functions such as `generateText`. They accept only an optional model ID
|
|
222
|
+
`openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return AI SDK language models that use eve's credentials, so you can also pass them to AI SDK functions such as `generateText`. They accept only an optional model ID; omit it for `gpt-6-luna-fast` and `claude-sonnet-5`, respectively.
|
|
223
|
+
|
|
224
|
+
`EveLanguageModel`, exported from `eve` and `eve/models`, is the model type `agent.ts` accepts. Every AI SDK language model satisfies it.
|
|
224
225
|
|
|
225
226
|
Use `/login` for local credentials, or set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Local secret-store discovery is disabled in deployments; provision server credentials explicitly. See [Set the model](../agent-config#set-the-model) for an example.
|
|
226
227
|
|
|
@@ -237,32 +238,30 @@ export default defineAgent({
|
|
|
237
238
|
});
|
|
238
239
|
```
|
|
239
240
|
|
|
240
|
-
Pass another bare OpenAI model slug to override the default.
|
|
241
|
+
Pass another bare OpenAI model slug to override the default.
|
|
241
242
|
|
|
242
|
-
`chatgpt()`
|
|
243
|
+
`chatgpt()` sends stateless requests (`store: false`). eve preserves reasoning across tool calls and later turns, so you don't configure `reasoning.encrypted_content`.
|
|
243
244
|
|
|
244
|
-
|
|
245
|
+
To sign in, use one local path. Who stores the credential depends on whether Codex is installed:
|
|
245
246
|
|
|
246
247
|
1. Run `eve dev`, open `/login`, and select **ChatGPT subscription**.
|
|
247
248
|
2. If `codex` is on `PATH`, eve uses `codex app-server` and launches `codex login` when sign-in is needed. Codex owns credential storage and refresh.
|
|
248
249
|
3. If the Codex binary is not found, eve falls back to direct browser sign-in and owns the saved session and refresh. If the browser does not open, use the URL printed in the terminal.
|
|
249
250
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
For the eve-owned fallback, eve stores your refresh token and account details in your operating system's credential store through [just-secrets](https://github.com/vercel-labs/just-secrets): the login Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux. Access tokens stay in process memory; a new eve process refreshes the saved session when it first needs a token. The fallback login is separate from Codex and is never written to your project.
|
|
251
|
+
With Codex, eve asks app-server for tokens and doesn't read or write Codex login files. eve reports app-server errors other than a missing binary instead of switching credential owners.
|
|
253
252
|
|
|
254
|
-
|
|
253
|
+
The eve-owned fallback stores your refresh token and account details through [just-secrets](https://github.com/vercel-labs/just-secrets). It uses the login Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux. Access tokens stay in process memory, and a new eve process refreshes the saved session when it first needs a token. The fallback login is separate from Codex and never written to your project. eve doesn't fall back to file storage when the OS credential store is unavailable.
|
|
255
254
|
|
|
256
|
-
Linux, including WSL, requires `/usr/bin/secret-tool` (commonly provided by `libsecret-tools`), a session D-Bus, and an unlocked Secret Service keyring. On macOS, unlock your login keychain and allow credential access if prompted. On Windows, PowerShell and Credential Manager must be available in your user session. OS credential storage protects secrets at rest
|
|
255
|
+
Linux, including WSL, requires `/usr/bin/secret-tool` (commonly provided by `libsecret-tools`), a session D-Bus, and an unlocked Secret Service keyring. On macOS, unlock your login keychain and allow credential access if prompted. On Windows, PowerShell and Credential Manager must be available in your user session. OS credential storage protects secrets at rest, not from malicious processes running as your OS user.
|
|
257
256
|
|
|
258
|
-
|
|
257
|
+
The fallback uses a device code in SSH sessions or when localhost port 1455 is busy: open the displayed link and enter the code. Device sign-in requires device code authorization, enabled in **ChatGPT Settings → Security** or by a workspace admin in workspace permissions. Sign-in times out after five minutes; press **Ctrl+C** to cancel sooner. Device sign-in still needs an OS credential store; use an API-key model in headless environments without one.
|
|
259
258
|
|
|
260
|
-
|
|
259
|
+
`eve deploy` blocks agents whose active model is `chatgpt()`, because these local user credentials aren't uploaded to a deployment. Use an environment branch with a deployable model, or switch to an AI Gateway model before deploying.
|
|
261
260
|
|
|
262
261
|
Troubleshooting:
|
|
263
262
|
|
|
264
263
|
- **`chatgpt-sub login`**: open `/login` and select **ChatGPT subscription** to sign in again. eve launches `codex login` when Codex is available, or its direct sign-in flow when it is not.
|
|
265
|
-
- **`chatgpt-sub unavailable` with Codex installed**: update or restart Codex and retry.
|
|
264
|
+
- **`chatgpt-sub unavailable` with Codex installed**: update or restart Codex and retry.
|
|
266
265
|
- **`chatgpt-sub unavailable` without Codex**: follow the reported OS credential-store recovery steps, or check your network connection if token refresh failed. Retry from `/login`. If eve reports an invalid stored session, sign in again to replace it.
|
|
267
266
|
- **Model rejected by the backend**: model availability depends on the signed-in ChatGPT account. Pick another supported OpenAI model.
|
|
268
267
|
- **Device sign-in unavailable**: enable device code authorization in ChatGPT security settings, or sign in from a local terminal with port 1455 available.
|
package/docs/responsible-use.md
CHANGED
|
@@ -7,8 +7,8 @@ As the deployer, it is your responsibility to ensure your agent complies with ap
|
|
|
7
7
|
|
|
8
8
|
You are responsible for configuring approval policies, tool restrictions, connection scopes, route/session authorization, sandbox controls, telemetry exports, and other safeguards appropriate for your use case.
|
|
9
9
|
|
|
10
|
-
Before using eve with non-public, sensitive, regulated, or production data, review
|
|
10
|
+
Before using eve with non-public, sensitive, regulated, or production data, review what the agent can reach. Check its default tools, custom tools, MCP tools, shell/file/web tools, connected services, subagents, schedules, and external actions.
|
|
11
11
|
|
|
12
12
|
Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
|
|
13
13
|
|
|
14
|
-
Unless you configure stricter controls, eve agents may operate with permissive settings
|
|
14
|
+
Unless you configure stricter controls, eve agents may operate with permissive settings. Tools without an approval setting run without human approval, and sandbox network egress is not deny-all. Do not rely on model behavior alone to prevent sensitive or irreversible actions.
|
|
@@ -3,11 +3,11 @@ title: "Custom Sandbox Providers"
|
|
|
3
3
|
description: "Connect eve to your own sandbox backend with defineSandboxProvider()."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
A custom sandbox provider connects eve to a backend
|
|
6
|
+
A custom sandbox provider connects eve to a backend eve doesn't ship, such as your own container service or virtual machine pool. You write a connection that runs commands and moves file bytes in one sandbox, and four methods that build, create, reconnect, and delete sandboxes. eve builds the rest of the sandbox API from them.
|
|
7
7
|
|
|
8
8
|
## Define a provider
|
|
9
9
|
|
|
10
|
-
`defineSandboxProvider()` from `eve/sandbox/provider` takes a name and an `environment()` function that returns the
|
|
10
|
+
`defineSandboxProvider()` from `eve/sandbox/provider` takes a name and an `environment()` function that returns the four methods. This example targets `@acme/sdk`, a hypothetical client for a machine service that can take snapshots:
|
|
11
11
|
|
|
12
12
|
```ts title="agent/lib/acme-sandbox.ts"
|
|
13
13
|
import { createHash } from "node:crypto";
|
|
@@ -104,85 +104,101 @@ export const environment = AcmeSandbox.environment({
|
|
|
104
104
|
export default defineSandbox(() => environment.open({ egress: "deny-all" }));
|
|
105
105
|
```
|
|
106
106
|
|
|
107
|
-
`environment(options)`
|
|
107
|
+
`environment(options)` receives the caller's options without `prepare`, or `{}` when the sandbox file passes none. Make every field optional, or require the caller to pass it.
|
|
108
|
+
|
|
109
|
+
TypeScript infers the option, artifact, state, and extension types from the implementation. Write `start()` before `resume()` so the state type comes from `start()`'s return value, or annotate `resume()`'s `state` parameter.
|
|
108
110
|
|
|
109
111
|
## Implement the connection
|
|
110
112
|
|
|
111
|
-
A `SandboxConnection`
|
|
113
|
+
A `SandboxConnection` runs commands and reads and writes file bytes in one sandbox:
|
|
112
114
|
|
|
113
|
-
- `spawn({ command, workingDirectory, env, signal })` runs `command` as a Bash login-shell script (`bash -lc`) in `workingDirectory`, with the sandbox's environment plus
|
|
115
|
+
- `spawn({ command, workingDirectory, env, signal })` runs `command` as a Bash login-shell script (`bash -lc`) in `workingDirectory`, with the sandbox's environment plus the per-call `env`. Aborting kills the process tree. It resolves to a process with `stdout` and `stderr` byte streams, `wait()`, and `kill()`. When the call passes `stdin: true`, the process must also have a writable `stdin` stream, or eve kills the process and rejects the call.
|
|
114
116
|
- `readFile({ path, signal })` resolves to the file's bytes or a byte stream, or to `null` only when the path does not exist. A directory or an unreadable path rejects.
|
|
115
117
|
- `writeFiles({ files, signal })` writes every file, creating missing parent directories and overwriting existing files. It is the only write primitive.
|
|
116
118
|
- `removePath({ path, force, recursive, signal })` removes a file or directory. `force` ignores a missing path, and `recursive` removes a non-empty directory.
|
|
117
119
|
- `stop()` releases compute and keeps the sandbox's files.
|
|
118
|
-
- `close()
|
|
119
|
-
- `extensions
|
|
120
|
-
- `workspaceRoot
|
|
120
|
+
- `close()`, optional, releases what this process holds for the connection, such as a local interpreter or child processes, without touching the sandbox. eve calls it when the step that opened the connection ends, after `stop()`, and before deletion. A connection lasts at most one step, and the next step resumes the sandbox through a new connection.
|
|
121
|
+
- `extensions`, optional, is a plain object whose own properties eve adds to the sandbox, such as `setNetworkPolicy()`. Use closures rather than class methods, because eve doesn't copy inherited members.
|
|
122
|
+
- `workspaceRoot`, optional, is the absolute sandbox directory where commands start and relative paths resolve. Omit it to use `/workspace`, as every built-in provider does. The directory must exist before eve runs a command in it.
|
|
121
123
|
|
|
122
|
-
Every path a connection receives is absolute, and `workingDirectory` is always set.
|
|
124
|
+
Every path a connection receives is absolute, and `workingDirectory` is always set. The built-in file tools, inbound attachments, and GitHub checkouts use the same root. eve throws when it opens a connection whose `workspaceRoot` is not absolute:
|
|
123
125
|
|
|
124
126
|
```text
|
|
125
127
|
Sandbox connection workspaceRoot must be an absolute path, but received "project".
|
|
126
128
|
```
|
|
127
129
|
|
|
128
|
-
eve builds the rest of the
|
|
130
|
+
eve builds the rest of the sandbox API from these methods, including `run()`, the binary and text read and write variants, and `resolvePath()`. An extension member with the name of one of those methods, or `stop` or `delete`, is a type error. eve also throws when it opens the connection:
|
|
129
131
|
|
|
130
132
|
```text
|
|
131
133
|
Sandbox connection extensions cannot replace the session members eve provides: run. Rename them.
|
|
132
134
|
```
|
|
133
135
|
|
|
134
|
-
Type the connection with its extensions, such as `SandboxConnection<{ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void> }
|
|
136
|
+
Type the connection with its extensions, such as `SandboxConnection<{ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void> }>`. `environment.open()` and `ctx.getSandbox(environment)` then return a sandbox that includes them.
|
|
135
137
|
|
|
136
138
|
## Implement the lifecycle
|
|
137
139
|
|
|
138
|
-
eve calls the
|
|
140
|
+
eve calls the provider's methods at these points:
|
|
141
|
+
|
|
142
|
+
| When | eve calls |
|
|
143
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
144
|
+
| `eve build`, or the first sandbox access in `eve dev` | `prepare(ctx)`, and stores the artifact it returns with the deployment |
|
|
145
|
+
| The first sandbox access in a session, or prewarming | `start(ctx, options, artifact)` from `environment.open(options)` in the selector |
|
|
146
|
+
| A later workflow step or process, or a turn starting | `resume(ctx, artifact, state)` |
|
|
147
|
+
| The step that opened a connection ends | `connection.close()`, for a turn's step, a `"use step"` function, or an `invokeTool` call |
|
|
148
|
+
| `sandbox.stop()` | `connection.stop()`, then `connection.close()` |
|
|
149
|
+
| `sandbox.delete()` | `connection.close()`, then `onSessionEnd(ctx, state, { reason: "deleted" })` |
|
|
150
|
+
| The eve server shuts down | `connection.stop()`, then `connection.close()`, on every connection eve still holds |
|
|
151
|
+
| The session that owns the sandbox ends | `connection.close()` on a connection the ending step still holds, then `onSessionEnd(ctx, state, { reason })` with `"completed"`, `"expired"`, or `"failed"` |
|
|
139
152
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
| The step that opened a connection ends | `connection.close()`, for a turn's step, a `"use step"` function, or an `invokeTool` call |
|
|
146
|
-
| `sandbox.stop()` | `connection.stop()`, then `connection.close()` |
|
|
147
|
-
| `sandbox.delete()` | `connection.close()`, then `onSessionEnd(ctx, state, { reason: "deleted" })` |
|
|
148
|
-
| The eve server shuts down | `connection.stop()`, then `connection.close()`, on every connection eve still holds: any connection mid-step, and between steps a connection without `close()`; eve logs failures and does not throw them |
|
|
149
|
-
| The owning session reaches a terminal outcome | `connection.close()` on a connection the ending step still holds, then `onSessionEnd(ctx, state, { reason })` with `"completed"`, `"expired"`, or `"failed"` |
|
|
153
|
+
- A prewarmed session calls `start()` before its first message, and its first turn can call it again at the same time.
|
|
154
|
+
- Each turn of a session that recorded a sandbox calls `resume()` as the turn starts, whether or not the turn uses the sandbox.
|
|
155
|
+
- Server shutdown always stops connections that are mid-step. eve logs shutdown failures and doesn't throw them.
|
|
156
|
+
- eve calls `close()` at most once per connection, and calls it again only after a failure. A failed `close()` never prevents `onSessionEnd()` from deleting the sandbox.
|
|
157
|
+
- `stop()` can run again after the session uses a stopped connection, so make it a no-op when the sandbox is already stopped.
|
|
150
158
|
|
|
151
|
-
|
|
159
|
+
Defining `close()` changes shutdown behavior. Without `close()`, eve keeps the connection between steps, so server shutdown stops its sandbox. With `close()`, eve releases the connection at the end of its step, so server shutdown between steps doesn't stop that sandbox. If your provider defines `close()` and runs remote compute, limit idle compute yourself, for example with an idle timeout.
|
|
152
160
|
|
|
153
161
|
### `prepare()`
|
|
154
162
|
|
|
155
|
-
`prepare()` builds a reusable template and returns a JSON-compatible artifact, such as a snapshot or image id. It runs during `eve build`, so the deployment ships with the artifact
|
|
163
|
+
`prepare()` builds a reusable template and returns a JSON-compatible artifact, such as a snapshot or image id. It runs during `eve build`, so the deployment ships with the artifact. The production runtime never calls it.
|
|
164
|
+
|
|
165
|
+
A running sandbox keeps the template it started from. `resume()` receives the current deployment's artifact, but it reconnects to the existing sandbox.
|
|
156
166
|
|
|
157
|
-
`ctx.isEmpty` is `true` when the agent has no workspace files,
|
|
167
|
+
`ctx.isEmpty` is `true` when the agent has no workspace files, skill files, or authored `prepare`, so the provider can skip building a template. See [Bake files into templates](#bake-files-into-templates) for `ctx.populate()` and `ctx.templateKey()`.
|
|
158
168
|
|
|
159
169
|
### `start()`
|
|
160
170
|
|
|
161
|
-
`start()` returns the sandbox for `ctx.session.id`,
|
|
171
|
+
`start()` returns the sandbox for `ctx.session.id`, and creates it when none exists. It also returns the smallest JSON-compatible state that `resume()` needs, which eve saves with the session.
|
|
162
172
|
|
|
163
|
-
|
|
173
|
+
Every call for one session id must return the same sandbox while it exists and is usable. This includes concurrent calls from other processes or deployments, which can race to create it.
|
|
164
174
|
|
|
165
|
-
`ctx.session.id`
|
|
175
|
+
Derive the sandbox's native name only from `ctx.session.id` and a provider-level namespace, such as a project or account. Never derive it from the open options or the artifact, which can differ between callers and deployments. Apply them only when `start()` creates the sandbox.
|
|
176
|
+
|
|
177
|
+
`ctx.session.id` is the id of the session the sandbox belongs to. For a subagent that shares its parent's sandbox, it is the parent's id. `ctx.kind` is `"tool-session"` for a keyed `invokeTool` call's sandbox and `"session"` otherwise.
|
|
166
178
|
|
|
167
179
|
### `resume()`
|
|
168
180
|
|
|
169
|
-
`resume()` reconnects to the sandbox that `state` names and never recreates it.
|
|
181
|
+
`resume()` reconnects to the sandbox that `state` names and never recreates it. It doesn't receive open options, so put anything reconnection needs in the state.
|
|
182
|
+
|
|
183
|
+
When the sandbox no longer exists, throw `SandboxSessionGoneError`. eve then runs the selector again, which starts a fresh sandbox without the lost files. Let other failures, such as an outage, surface unchanged.
|
|
170
184
|
|
|
171
|
-
Validate the shape of your own state in `resume()`. When you change
|
|
185
|
+
Validate the shape of your own state in `resume()`. When you change the shape incompatibly, raise `stateProtocolVersion` in the provider definition. State saved under another version starts a fresh sandbox instead of reaching `resume()`.
|
|
172
186
|
|
|
173
187
|
### `onSessionEnd()`
|
|
174
188
|
|
|
175
|
-
`onSessionEnd()` deletes whatever exists for `ctx.session.id`. `state` is `null` when the session never
|
|
189
|
+
`onSessionEnd()` deletes whatever exists for `ctx.session.id`. `state` is `null` when the session never saved it, so find the sandbox from the session id. This happens, for example, when only a subagent opened the shared sandbox, or a step failed before saving state.
|
|
190
|
+
|
|
191
|
+
eve retries cleanup, so `onSessionEnd()` must be safe to repeat and must succeed when nothing exists. When every retry fails, eve logs the failure and the session's outcome doesn't change.
|
|
176
192
|
|
|
177
|
-
`sandbox.delete()`
|
|
193
|
+
`sandbox.delete()` calls the same method with `reason: "deleted"` and the caller's `signal`. An `invokeTool` call without a key calls it when the call ends, if the tool requested the sandbox. A subagent that shares its parent's sandbox never calls it, because cleanup belongs to the parent.
|
|
178
194
|
|
|
179
195
|
The sets of `reason` and `ctx.kind` values, like other values eve passes into a provider, can grow in a minor release, so handle unknown values instead of switching exhaustively. See [Stability policy](/docs/reference/typescript-api#stability-policy).
|
|
180
196
|
|
|
181
197
|
## Bake files into templates
|
|
182
198
|
|
|
183
|
-
|
|
199
|
+
In `prepare()`, call `ctx.populate(connection)` on the build instance before you capture it. `populate()` writes the agent's workspace files to the connection's workspace root and its skill files to `$HOME/.agents/skills` in one `writeFiles()` call. It then runs the authored `prepare` callback over the same connection. eve finds `$HOME` by running a command through `spawn()`. When the sandbox has no usable home directory, skills go to `skills/` under the workspace root.
|
|
184
200
|
|
|
185
|
-
A provider that can mount host directories can
|
|
201
|
+
A provider that can mount host directories can skip writing every file. `ctx.resourcesDirectory()` resolves to a read-only host directory that contains `workspace/` and `skills/`, or to `undefined`. Mount it in the build instance and pass its sandbox path:
|
|
186
202
|
|
|
187
203
|
```ts
|
|
188
204
|
const resources = await ctx.resourcesDirectory();
|
|
@@ -198,13 +214,17 @@ await ctx.populate(
|
|
|
198
214
|
|
|
199
215
|
With `mountedAt`, `populate()` copies `<mountedAt>/workspace/.` into the workspace root and `<mountedAt>/skills/.` into `$HOME/.agents/skills` with `cp -a`. When eve has no resource directory, `populate()` ignores `mountedAt` and writes the files instead.
|
|
200
216
|
|
|
201
|
-
`ctx.templateKey(identity)` returns a SHA-256 hex key
|
|
217
|
+
`ctx.templateKey(identity)` returns a SHA-256 hex key. The key changes whenever `identity`, the workspace files, the skill files, or the sandbox file's source changes. Pass every option that affects the template, such as the base image, and use the key to name or look up a cached template.
|
|
202
218
|
|
|
203
|
-
|
|
219
|
+
- `identity` accepts JSON values, `undefined` (omitted), plain objects and arrays, and functions (hashed by their source).
|
|
220
|
+
- `resources` and `sourceRevision` are reserved, and eve throws if `identity` sets either.
|
|
221
|
+
- Only the sandbox file's own source counts. Changing a `prepare` callback imported from another module doesn't change the key.
|
|
222
|
+
|
|
223
|
+
Only `prepare()` seeds files. A sandbox that `start()` creates gets them from the template, so a provider whose templates can't hold files can't provide workspace or skill files.
|
|
204
224
|
|
|
205
225
|
## Keep sandboxes for keyed tool calls
|
|
206
226
|
|
|
207
|
-
Set `toolSessions: true` on the implementation to let keyed `invokeTool` calls keep their sandbox between calls, as Vercel Sandbox and just-bash do.
|
|
227
|
+
Set `toolSessions: true` on the implementation to let keyed `invokeTool` calls keep their sandbox between calls, as Vercel Sandbox and just-bash do. eve runs the selector and `start()` on every keyed call, and calls `connection.close()` when the call ends. eve never calls `onSessionEnd()` for these sandboxes, so the provider must limit how long it keeps them, for example with snapshot expiration.
|
|
208
228
|
|
|
209
229
|
Without `toolSessions`, a keyed call fails when its tool requests the sandbox:
|
|
210
230
|
|
|
@@ -216,11 +236,11 @@ A keyed call whose tool never requests the sandbox runs normally. See [MCP tool
|
|
|
216
236
|
|
|
217
237
|
## Enforce network policy
|
|
218
238
|
|
|
219
|
-
eve has no built-in network control for custom providers. To offer one, accept a `SandboxNetworkPolicy` from `eve/sandbox` as an open option,
|
|
239
|
+
eve has no built-in network control for custom providers. To offer one, accept a `SandboxNetworkPolicy` from `eve/sandbox` as an open option, a `setNetworkPolicy()` extension, or both. Reject any part of a policy the backend can't enforce instead of weakening it. The Docker provider, for example, accepts `"allow-all"` and `"deny-all"` and throws on anything else.
|
|
220
240
|
|
|
221
241
|
## Set environment variables
|
|
222
242
|
|
|
223
|
-
`SANDBOX_AGENT_ENV` is `{ AI_AGENT: "eve" }`, which tells agent-aware CLIs to skip interactive prompts. Apply it beneath your environment-level variables when you create the sandbox, as the built-in providers do. A per-call `env` passed to `spawn()` overrides both. If the backend has no sandbox-level environment, merge it
|
|
243
|
+
`SANDBOX_AGENT_ENV` is `{ AI_AGENT: "eve" }`, which tells agent-aware CLIs to skip interactive prompts. Apply it beneath your environment-level variables when you create the sandbox, as the built-in providers do. A per-call `env` passed to `spawn()` overrides both. If the backend has no sandbox-level environment, merge it in `spawn()` instead: `{ ...SANDBOX_AGENT_ENV, ...env }`.
|
|
224
244
|
|
|
225
245
|
## Report missing templates
|
|
226
246
|
|
|
@@ -236,20 +256,4 @@ throw new SandboxTemplateNotProvisionedError({
|
|
|
236
256
|
});
|
|
237
257
|
```
|
|
238
258
|
|
|
239
|
-
eve
|
|
240
|
-
|
|
241
|
-
## Migrate from the handle-based API
|
|
242
|
-
|
|
243
|
-
Earlier releases asked a provider to return a handle with a complete sandbox session. To move a provider to the current API:
|
|
244
|
-
|
|
245
|
-
- Return `{ connection, state }` from `start()` and a connection from `resume()`, instead of a handle. Move provider-specific session methods to `extensions`.
|
|
246
|
-
- Remove `onSandboxStop()` and `onRuntimeShutdown()`; implement `connection.stop()`. Move `onSandboxDelete()` into `onSessionEnd()`, which receives `reason: "deleted"`.
|
|
247
|
-
- Replace hashes of `ctx.resources` and `ctx.sourceRevision` with `ctx.templateKey()`, and replace writes of resource files plus your own `prepare` call with `ctx.populate()`. Remove `prepare` from your environment options; eve owns it.
|
|
248
|
-
- Replace `ctx.host.resolveProjectPath()` with `ctx.resolveProjectPath()`. `ctx.host.loadOptionalPackage()` is no longer available; import your SDK directly.
|
|
249
|
-
- Drop the explicit type arguments to `defineSandboxProvider()` and let TypeScript infer them. `environment()` now receives `{}` instead of `undefined` when the sandbox file passes no options.
|
|
250
|
-
- Rename `SandboxPreparedArtifact` to `SandboxJson`, `SandboxProviderSessionContext` to `SandboxSessionContext`, and `SandboxProviderPrepareContext` to `SandboxPrepareContext`. `SandboxProviderHandle`, `SandboxProviderResources`, `SandboxProviderResourceTree`, `SandboxProviderResourceFile`, `SandboxProviderResourceSource`, and `SandboxProviderTargetFile` are removed.
|
|
251
|
-
|
|
252
|
-
Two changes in `eve/sandbox` also affect code outside providers:
|
|
253
|
-
|
|
254
|
-
- `SandboxSession` has a required `writeFiles()` method, so an object you build by hand as a `SandboxSession`, such as a test double, needs one.
|
|
255
|
-
- `SandboxNetworkPolicy` is an eve-owned type with `readonly` members instead of the Vercel Sandbox SDK's `NetworkPolicy`. Code that passes a policy to the SDK directly needs its own conversion.
|
|
259
|
+
eve returns the error to the caller and never retries or rebuilds the template at runtime. eve throws the same error when a deployment has no artifact for the sandbox. The provider decides how long to keep templates and when to delete them. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#sandbox-template--is-not-available-to-this-runtime).
|