Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): infer configured sandbox capabilities (#3653)

Casey Gowrieee286fe43a2a
diff --git a/.changeset/type-sandbox-environment-capabilities.md b/.changeset/type-sandbox-environment-capabilities.md
new file mode 100644
index 000000000..c1bc581fc
--- /dev/null
+++ b/.changeset/type-sandbox-environment-capabilities.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Pass a configured sandbox environment to `ctx.getSandbox(environment)` to preserve its provider-specific session capabilities in the returned eve sandbox handle. The common `SandboxSession` no longer exposes optional `setNetworkPolicy`; use the configured environment when accessing that capability.
diff --git a/docs/guides/session-context.md b/docs/guides/session-context.md
index 89ca38620..e5f5a92b3 100644
--- a/docs/guides/session-context.md
+++ b/docs/guides/session-context.md
@@ -60,6 +60,17 @@ const result = await sandbox.run({ command: "npm test" });
The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes `stop()` and `delete()`; see [Sandbox lifecycle](../sandbox#lifecycle) for their behavior.
+When you need capabilities specific to the configured environment, pass its exported environment object. The return type preserves the environment's session capabilities. Provider-specific methods such as `setNetworkPolicy()` are not available from the no-argument accessor:
+
+```ts
+import { environment } from "../sandbox";
+
+const sandbox = await ctx.getSandbox(environment);
+await sandbox.setNetworkPolicy("deny-all");
+```
+
+The environment must be the one configured for the current sandbox. eve rejects a different environment instead of returning a handle with capabilities that may not exist.
+
## Custom state with `defineState`
Use `defineState` for durable per-session values that tools, hooks, and channel handlers share. Unlike the `ctx` accessors, import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still require active eve execution. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
@@ -83,5 +94,4 @@ eve establishes the managed context before invoking authored runtime code and ke
- [State](../concepts/state): durable typed values scoped to one session.
- [Sandbox](../sandbox): runtime filesystem and process access.
-- [Skills](../skills): load procedures and read packaged skill files.
- [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): the durable session and event contract.
diff --git a/docs/sandbox/index.mdx b/docs/sandbox/index.mdx
index 7b856d372..c5f8dfa46 100644
--- a/docs/sandbox/index.mdx
+++ b/docs/sandbox/index.mdx
@@ -28,6 +28,17 @@ export default defineTool({
Relative paths resolve under `/workspace`. `run()` returns `{ exitCode, stdout, stderr }`; a nonzero exit code does not throw automatically. Use `spawn()` for a long-running process.
+Pass the configured environment to preserve its specific session capabilities in authored runtime code:
+
+```ts
+import { environment } from "../sandbox";
+
+const sandbox = await ctx.getSandbox(environment);
+await sandbox.setNetworkPolicy("deny-all");
+```
+
+For example, a Vercel environment returns a handle with `setNetworkPolicy()`. The common handle from `ctx.getSandbox()` does not expose provider-specific capabilities. The environment must match the one configured for the current sandbox.
+
## Define an environment
A sandbox module exports an environment and returns a sandbox from `defineSandbox()`:
diff --git a/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/agent.ts b/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/agent.ts
index 123e3d539..382111354 100644
--- a/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/agent.ts
+++ b/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/agent.ts
@@ -1,9 +1,20 @@
import { e2eSubagentConfig } from "@eve-e2e/config";
import { defineAgent } from "eve";
+import type { MockModelRequest, MockModelResponse } from "eve/evals";
-import { respond } from "../../lib/mock-responder.js";
+import { respond as respondToDirective } from "../../lib/mock-responder.js";
export default defineAgent({
description: "Runs commands in an independent sandbox opened with deny-all networking.",
...e2eSubagentConfig({ mock: respond }),
});
+
+function respond(request: MockModelRequest): MockModelResponse | string {
+ if (!request.lastUserMessage?.includes("configured environment")) {
+ return respondToDirective(request);
+ }
+ const result = request.toolResults.find((entry) => entry.name === "verify-typed-sandbox");
+ return result === undefined
+ ? { toolCalls: [{ input: {}, name: "verify-typed-sandbox" }] }
+ : JSON.stringify(result.output);
+}
diff --git a/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/tools/verify-typed-sandbox.ts b/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/tools/verify-typed-sandbox.ts
new file mode 100644
index 000000000..bd89ed2be
--- /dev/null
+++ b/e2e/fixtures/agent-tools-sandbox/agent/subagents/deny-all/tools/verify-typed-sandbox.ts
@@ -0,0 +1,21 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+import { environment } from "../sandbox.js";
+
+export default defineTool({
+ description: "Verifies that the configured environment exposes mutable network policy.",
+ inputSchema: z.object({}),
+ async execute(_input, ctx) {
+ const sandbox = await ctx.getSandbox(environment);
+ await sandbox.setNetworkPolicy("deny-all");
+ const result = await sandbox.run({
+ command: "curl -sS --max-time 5 -o /dev/null https://example.com",
+ });
+ return {
+ blocked: result.exitCode !== 0,
+ exitCode: result.exitCode,
+ stderr: result.stderr,
+ };
+ },
+});
diff --git a/e2e/fixtures/agent-tools-sandbox/agent/tools/network-probe.ts b/e2e/fixtures/agent-tools-sandbox/agent/tools/network-probe.ts
deleted file mode 100644
index 9ecf116be..000000000
--- a/e2e/fixtures/agent-tools-sandbox/agent/tools/network-probe.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-
-/**
- * Applies a `deny-all` network policy to the live sandbox mid-turn via
- * `sandbox.setNetworkPolicy(...)`, then attempts an HTTP egress with `curl`
- * and reports whether it was blocked.
- *
- * The assertion the eval gates on is self-contained: under `deny-all` the
- * sandbox has no egress at all (the Docker provider detaches every network, the
- * Vercel firewall blocks the request), so `curl` fails without depending on
- * any external host being reachable. `blocked` plus a network-failure `stderr`
- * signature distinguishes a policy block from `curl` being missing.
- */
-export default defineTool({
- description:
- "Smoke-test fixture: applies a deny-all network policy to the sandbox and probes egress. Only call when explicitly asked to use `network-probe`.",
- inputSchema: z.object({}),
- async execute(_input, ctx) {
- const sandbox = await ctx.getSandbox();
- if (sandbox.setNetworkPolicy === undefined) {
- throw new Error("The selected sandbox provider does not support mutable network policies.");
- }
- await sandbox.setNetworkPolicy("deny-all");
- const result = await sandbox.run({
- command: "curl -sS --max-time 5 -o /dev/null https://example.com",
- });
- return {
- blocked: result.exitCode !== 0,
- exitCode: result.exitCode,
- stderr: result.stderr,
- };
- },
-});
diff --git a/e2e/fixtures/agent-tools-sandbox/evals/sandbox/network-policy.eval.ts b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/network-policy.eval.ts
deleted file mode 100644
index f9565d08e..000000000
--- a/e2e/fixtures/agent-tools-sandbox/evals/sandbox/network-policy.eval.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { defineEval } from "eve/evals";
-
-// Distinguishes a real egress block from curl simply being absent: a blocked
-// request fails with a resolution/connection error, never "command not found".
-const NETWORK_FAILURE =
- /could ?n['o]t resolve|resolve host|could ?n['o]t connect|failed to connect|connection refused|network is unreachable|couldn't resolve host/i;
-
-function isBlocked(value: unknown): boolean {
- if (typeof value !== "object" || value === null) return false;
- const record = value as Record<string, unknown>;
- return (
- record.blocked === true &&
- typeof record.exitCode === "number" &&
- record.exitCode !== 0 &&
- typeof record.stderr === "string" &&
- NETWORK_FAILURE.test(record.stderr)
- );
-}
-
-// `network-probe` applies a deny-all policy to the live sandbox mid-turn and
-// then attempts egress. Asserting the probe came back blocked proves
-// `setNetworkPolicy("deny-all")` actually severs egress on the active provider.
-export default defineEval({
- tags: ["real-model"],
- description: "Sandbox: setNetworkPolicy('deny-all') blocks sandbox egress mid-turn.",
- async test(t) {
- await t.send(
- "Use the `network-probe` tool and tell me whether sandbox network egress was blocked.",
- );
-
- t.succeeded();
- t.calledTool("network-probe", {
- output: isBlocked,
- });
- },
-});
diff --git a/e2e/fixtures/agent-tools-sandbox/evals/sandbox/typed-environment-capability.eval.ts b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/typed-environment-capability.eval.ts
new file mode 100644
index 000000000..a2df7ae39
--- /dev/null
+++ b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/typed-environment-capability.eval.ts
@@ -0,0 +1,32 @@
+import { defineEval } from "eve/evals";
+import { includes } from "eve/evals/expect";
+
+export default defineEval({
+ description:
+ "Sandbox: ctx.getSandbox(environment) exposes the configured environment's capabilities.",
+ timeoutMs: 60_000,
+ async test(t) {
+ const turn = await t.send(
+ "Ask the `deny-all` subagent with message: Verify the configured environment sandbox capability.",
+ );
+ turn.expectOk();
+ const sessionId = turn.sessionId;
+ if (sessionId === undefined) throw new Error("Typed sandbox turn has no session id.");
+ const completed = await t.target
+ .watchTurn(sessionId, { startIndex: requireStreamIndex(turn.session) })
+ .result();
+ completed.expectOk();
+
+ t.succeeded();
+ t.calledSubagent("deny-all", { count: 1, status: "completed" });
+ t.check(completed.message, includes(/blocked[^\n]*true/iu));
+ },
+});
+
+function requireStreamIndex(session: {
+ readonly state?: { readonly streamIndex?: number };
+}): number {
+ const streamIndex = session.state?.streamIndex;
+ if (streamIndex === undefined) throw new Error("Typed sandbox turn has no stream index.");
+ return streamIndex;
+}
diff --git a/packages/eve-code/extension/lib/credentials.ts b/packages/eve-code/extension/lib/credentials.ts
index 97ca9efaa..27a0f7feb 100644
--- a/packages/eve-code/extension/lib/credentials.ts
+++ b/packages/eve-code/extension/lib/credentials.ts
@@ -1,4 +1,8 @@
-import type { MutableNetworkSandboxSession, SandboxSession } from "eve/sandbox";
+import type { SandboxNetworkPolicy, SandboxSession } from "eve/sandbox";
+
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { toolingPaths } from "./tooling.ts";
@@ -123,8 +127,8 @@ async function writeToolEnvironment(
}
}
-function hasMutableNetworkPolicy(sandbox: SandboxSession): sandbox is MutableNetworkSandboxSession {
- return sandbox.setNetworkPolicy !== undefined;
+function hasMutableNetworkPolicy(sandbox: SandboxSession): sandbox is NetworkPolicySandboxSession {
+ return "setNetworkPolicy" in sandbox;
}
function shellQuote(value: string): string {
diff --git a/packages/eve-code/test/integration/connect-authentication.test.ts b/packages/eve-code/test/integration/connect-authentication.test.ts
index a5f8f6b90..fdeefb6b1 100644
--- a/packages/eve-code/test/integration/connect-authentication.test.ts
+++ b/packages/eve-code/test/integration/connect-authentication.test.ts
@@ -2,7 +2,11 @@ import assert from "node:assert/strict";
import test from "node:test";
import { ConnectError, type ConnectTokenParams } from "@vercel/connect";
-import type { MutableNetworkSandboxSession, SandboxSession } from "eve/sandbox";
+import type { SandboxNetworkPolicy, SandboxSession } from "eve/sandbox";
+
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
(globalThis as Record<symbol, unknown>)[Symbol.for("eve.ext-config-scope")] =
"eve-code-connect-authentication-test";
@@ -72,11 +76,11 @@ test("Connect errors fail with the connector UID", async () => {
);
});
-function fakeSandbox(policies: { allow: Record<string, unknown> }[]): SandboxSession {
- const sandbox: Pick<MutableNetworkSandboxSession, "setNetworkPolicy"> = {
+function fakeSandbox(policies: { allow: Record<string, unknown> }[]): NetworkPolicySandboxSession {
+ const sandbox: Pick<NetworkPolicySandboxSession, "setNetworkPolicy"> = {
async setNetworkPolicy(policy) {
policies.push(policy as { allow: Record<string, unknown> });
},
};
- return sandbox as SandboxSession;
+ return sandbox as NetworkPolicySandboxSession;
}
diff --git a/packages/eve-code/test/integration/credentials.test.ts b/packages/eve-code/test/integration/credentials.test.ts
index 1c3c4db61..774761c77 100644
--- a/packages/eve-code/test/integration/credentials.test.ts
+++ b/packages/eve-code/test/integration/credentials.test.ts
@@ -1,7 +1,11 @@
import assert from "node:assert/strict";
import test from "node:test";
-import type { MutableNetworkSandboxSession, SandboxSession } from "eve/sandbox";
+import type { SandboxNetworkPolicy, SandboxSession } from "eve/sandbox";
+
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { authenticateGitHub, authenticateVercel } from "../../extension/lib/credentials.ts";
@@ -43,8 +47,9 @@ test("custom broker receives complete rules for each credential", async () => {
});
test("firewall delivery fails precisely without mutable network policy", async () => {
- const { setNetworkPolicy: _omitted, ...fixed } = fakeSandbox({});
- const sandbox = fixed as SandboxSession;
+ const sandbox = fakeSandbox({});
+
+ assert.equal("setNetworkPolicy" in sandbox, false);
for (const authenticate of [authenticateGitHub, authenticateVercel]) {
await assert.rejects(
@@ -75,7 +80,7 @@ function fakeSandbox(input: {
}): SandboxSession {
const writes = input.writes ?? new Map<string, string>();
const sandbox: Pick<SandboxSession, "resolvePath" | "readTextFile" | "writeTextFile" | "run"> &
- Pick<MutableNetworkSandboxSession, "setNetworkPolicy"> = {
+ Partial<Pick<NetworkPolicySandboxSession, "setNetworkPolicy">> = {
resolvePath(path: string) {
return `/workspace/${path}`.replace(/\/$/u, "");
},
@@ -89,9 +94,9 @@ function fakeSandbox(input: {
input.commands?.push(command);
return { exitCode: 0, stdout: "", stderr: "" };
},
- async setNetworkPolicy(policy) {
- input.setPolicy?.(policy);
- },
};
+ if (input.setPolicy !== undefined) {
+ sandbox.setNetworkPolicy = async (policy) => input.setPolicy?.(policy);
+ }
return sandbox as SandboxSession;
}
diff --git a/packages/eve-code/test/integration/diagnostics.test.ts b/packages/eve-code/test/integration/diagnostics.test.ts
index 376de934a..9506fd1a7 100644
--- a/packages/eve-code/test/integration/diagnostics.test.ts
+++ b/packages/eve-code/test/integration/diagnostics.test.ts
@@ -98,7 +98,6 @@ function commandSandbox(
async readTextFile({ path }) {
return path.endsWith("diagnostics.cjs") ? worker : null;
},
- async setNetworkPolicy() {},
async removePath() {},
async spawn() {
throw new Error("not used by this test");
diff --git a/packages/eve-code/test/integration/github-shell.test.ts b/packages/eve-code/test/integration/github-shell.test.ts
index 6dfe95152..7f4d5b343 100644
--- a/packages/eve-code/test/integration/github-shell.test.ts
+++ b/packages/eve-code/test/integration/github-shell.test.ts
@@ -1,7 +1,11 @@
import assert from "node:assert/strict";
import test from "node:test";
import type { ConnectTokenParams } from "@vercel/connect";
-import type { MutableNetworkSandboxSession, SandboxSession } from "eve/sandbox";
+import type { SandboxNetworkPolicy, SandboxSession } from "eve/sandbox";
+
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import {
executeGitHubShell,
@@ -11,7 +15,7 @@ import {
type GitHubShellInput,
} from "../../extension/lib/github-shell.ts";
-type NetworkPolicy = Parameters<MutableNetworkSandboxSession["setNetworkPolicy"]>[0];
+type NetworkPolicy = Parameters<NetworkPolicySandboxSession["setNetworkPolicy"]>[0];
const CONFIG = {
connector: "github/citron-compass",
@@ -23,8 +27,9 @@ const CONFIG = {
const allow = Object.fromEntries(
Object.entries(rules ?? {}).map(([host, entries]) => [host, [...entries]]),
);
- if (sandbox.setNetworkPolicy === undefined) throw new Error("test sandbox lacks networking");
- await sandbox.setNetworkPolicy(rules ? { allow: { "*": [], ...allow } } : "allow-all");
+ await (sandbox as NetworkPolicySandboxSession).setNetworkPolicy(
+ rules ? { allow: { "*": [], ...allow } } : "allow-all",
+ );
},
};
@@ -362,7 +367,7 @@ function fakeSandbox(
policies: NetworkPolicy[] = [],
): SandboxSession {
const sandbox: Pick<SandboxSession, "resolvePath" | "run" | "removePath"> &
- Pick<MutableNetworkSandboxSession, "setNetworkPolicy"> = {
+ Pick<NetworkPolicySandboxSession, "setNetworkPolicy"> = {
resolvePath(path: string) {
if (path === ".") return "/workspace";
if (path.startsWith("/")) return path;
@@ -377,5 +382,5 @@ function fakeSandbox(
policies.push(policy);
},
};
- return sandbox as SandboxSession;
+ return sandbox as NetworkPolicySandboxSession;
}
diff --git a/packages/eve-code/test/integration/patch.test.ts b/packages/eve-code/test/integration/patch.test.ts
index 554a7a028..c9907012a 100644
--- a/packages/eve-code/test/integration/patch.test.ts
+++ b/packages/eve-code/test/integration/patch.test.ts
@@ -382,7 +382,6 @@ function memorySandbox(
}
return { exitCode: 0, stdout: "", stderr: "" };
},
- async setNetworkPolicy() {},
async spawn() {
throw new Error("not used by this test");
},
diff --git a/packages/eve/extension-contracts/reports/channel/v31.json b/packages/eve/extension-contracts/reports/channel/v31.json
new file mode 100644
index 000000000..1ff83d0ae
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v31.json
@@ -0,0 +1,21 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 31,
+ "sha256": "c41b47f40b43dee7bf81c4722654b827f373d4cf5d439678f0e693a3f6ebba91",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/connection/v26.json b/packages/eve/extension-contracts/reports/connection/v26.json
new file mode 100644
index 000000000..069848d99
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v26.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 26,
+ "sha256": "a5b34c703afad33e4e9f72576dc16f3b87809c43b0336f1798b0e50d99810a61",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineDynamic",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v54.json b/packages/eve/extension-contracts/reports/dynamicTool/v54.json
new file mode 100644
index 000000000..fbbc69ae2
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v54.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 54,
+ "sha256": "8e59668df739dd15a28e747d599844b94ccdb15a0ac10ea2c6c7aa59d751b4e1",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "auto",
+ "defineDurableCallback",
+ "defineDurableSchema",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v27.json b/packages/eve/extension-contracts/reports/hook/v27.json
new file mode 100644
index 000000000..fae3215ec
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v27.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 27,
+ "sha256": "f422c1f2f2e1a29f3d93d1f331e821de3cb7190561facb074bacb62396e6f6bd",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/extension-contracts/reports/state/v9.json b/packages/eve/extension-contracts/reports/state/v9.json
new file mode 100644
index 000000000..36f7d5ed3
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/state/v9.json
@@ -0,0 +1,15 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "state",
+ "epoch": 9,
+ "sha256": "8ab4986b4ba5974a538c5c9fe161b1fac7fb190afa4c537daeae7760750c6234",
+ "exports": [
+ "Session",
+ "SessionAuth",
+ "SessionAuthContext",
+ "SessionContext",
+ "SessionParent",
+ "SessionTurn",
+ "defineState"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v57.json b/packages/eve/extension-contracts/reports/tool/v57.json
new file mode 100644
index 000000000..12f0a6e47
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v57.json
@@ -0,0 +1,27 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 57,
+ "sha256": "303b41aa8d22642c6fda922c7e7a8d963a998f642925e69a00c7b4fad5255b1b",
+ "exports": [
+ "AgentRouterInput",
+ "AgentRouterTool",
+ "WorkflowStepToolContext",
+ "WorkflowTool",
+ "WorkflowToolInput",
+ "WorkflowToolOptions",
+ "agentRouter",
+ "defaultWebSearch",
+ "defineTool",
+ "defineWorkflowTool",
+ "disableTool",
+ "evaluate",
+ "isDisabledToolSentinel",
+ "isWebSearchToolDefinition",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch",
+ "workflow"
+ ]
+}
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 9c116100e..c89a03d5a 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,8 +22,8 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 56,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 56],
+ current: 57,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 57],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
15: "TaskExec replaces stageEffect with send",
@@ -59,12 +59,13 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
51: "Background defineTool and TaskExec were removed; use defineWorkflowTool for durable background work.",
52: "Background defineTool and TaskExec were removed; use defineWorkflowTool for durable background work.",
53: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
+ 56: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",
},
},
dynamicTool: {
- current: 53,
+ current: 54,
supported: [
- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 53,
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 54,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -94,11 +95,12 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
49: "Background dynamic tools were removed; use a static defineWorkflowTool for durable background work.",
50: "Background dynamic tools were removed; use a static defineWorkflowTool for durable background work.",
51: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
+ 53: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",
},
},
channel: {
- current: 30,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 30],
+ current: 31,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
19: "Continuation rekey was removed; channel extensions must use additive continuation.alias instead.",
@@ -111,6 +113,7 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
26: "Task views no longer expose executor bindings; background work is owned by workflow runs.",
27: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
28: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
+ 30: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",
},
},
schedule: {
@@ -132,17 +135,18 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
connection: {
- current: 25,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 25],
+ current: 26,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 26],
dropped: {
9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",
10: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
23: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
+ 25: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",
},
},
hook: {
- current: 26,
- supported: [10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 22, 23, 25, 26],
+ current: 27,
+ supported: [10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 22, 23, 25, 27],
dropped: {
1: "Model identity moved from session.started runtime metadata to step.started call attribution.",
2: "Model identity moved from session.started runtime metadata to step.started call attribution.",
@@ -155,6 +159,7 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
9: "Model identity moved from session.started runtime metadata to step.started call attribution.",
16: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
24: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
+ 26: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",
},
},
skill: { current: 2, supported: [1, 2], dropped: {} },
@@ -175,10 +180,11 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
config: { current: 1, supported: [1], dropped: {} },
state: {
- current: 8,
- supported: [1, 2, 3, 4, 5, 7, 8],
+ current: 9,
+ supported: [1, 2, 3, 4, 5, 7, 9],
dropped: {
6: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
+ 8: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",
},
},
} as const satisfies Record<string, ExtensionCapabilityContract>;
diff --git a/packages/eve/src/context/accessors.integration.test.ts b/packages/eve/src/context/accessors.integration.test.ts
index 900b50ee1..19bbaf6fa 100644
--- a/packages/eve/src/context/accessors.integration.test.ts
+++ b/packages/eve/src/context/accessors.integration.test.ts
@@ -4,6 +4,7 @@ import { buildCallbackContext } from "#context/build-callback-context.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
import type { RuntimeSandboxSession, SandboxSession } from "#public/definitions/sandbox.js";
+import { VercelSandbox } from "#public/sandbox/vercel.js";
/**
* Integration coverage for {@link buildCallbackContext} — the single
@@ -98,6 +99,33 @@ describe("buildCallbackContext – getSandbox", () => {
expect(sandbox.commandLog).toEqual(["echo ready"]);
});
+ it("accepts the configured sandbox environment", async () => {
+ const environment = VercelSandbox.environment();
+ const sandbox = mockSandbox();
+ const runtime = await createTestRuntime();
+
+ const live = await runtime.runAsSession(
+ { sandboxAccess: { ...sandbox.access, environment } },
+ async () => await buildCallbackContext().getSandbox(environment),
+ );
+
+ expect(live).toBeDefined();
+ });
+
+ it("rejects a sandbox environment that is not active for the session", async () => {
+ const environment = VercelSandbox.environment();
+ const otherEnvironment = VercelSandbox.environment();
+ const sandbox = mockSandbox();
+ const runtime = await createTestRuntime();
+
+ await expect(
+ runtime.runAsSession(
+ { sandboxAccess: { ...sandbox.access, environment } },
+ async () => await buildCallbackContext().getSandbox(otherEnvironment),
+ ),
+ ).rejects.toThrow("The requested sandbox environment is not active for the current session.");
+ });
+
it("passes file operations through the expanded session surface", async () => {
const sandbox = mockSandbox({
id: "sbx_public_sandbox_file",
diff --git a/packages/eve/src/context/build-base-tool-context.integration.test.ts b/packages/eve/src/context/build-base-tool-context.integration.test.ts
index 757e4753d..f0eea9a41 100644
--- a/packages/eve/src/context/build-base-tool-context.integration.test.ts
+++ b/packages/eve/src/context/build-base-tool-context.integration.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import { buildBaseToolContext } from "#context/build-base-tool-context.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
+import { VercelSandbox } from "#public/sandbox/vercel.js";
describe("buildBaseToolContext – getSandbox abort binding", () => {
it("returns a session bound to the turn abort signal", async () => {
@@ -33,6 +34,20 @@ describe("buildBaseToolContext – getSandbox abort binding", () => {
expect(observed?.aborted).toBe(true);
});
+ it("forwards the configured environment", async () => {
+ const environment = VercelSandbox.environment();
+ const sandbox = mockSandbox();
+ const runtime = await createTestRuntime();
+
+ await runtime.runAsSession({ sandboxAccess: { ...sandbox.access, environment } }, async () => {
+ const ctx = buildBaseToolContext({
+ options: { toolCallId: "call_1" },
+ toolName: "shell",
+ });
+ await expect(ctx.getSandbox(environment)).resolves.toBeDefined();
+ });
+ });
+
it("binds the inert fallback signal when no turn signal exists", async () => {
let observed: AbortSignal | undefined;
const sandbox = mockSandbox({
diff --git a/packages/eve/src/context/build-base-tool-context.ts b/packages/eve/src/context/build-base-tool-context.ts
index fb42b09e4..28e6fe6b8 100644
--- a/packages/eve/src/context/build-base-tool-context.ts
+++ b/packages/eve/src/context/build-base-tool-context.ts
@@ -1,6 +1,7 @@
import { buildCallbackContext } from "#context/build-callback-context.js";
import type { SessionContext } from "#context/session-context.js";
import { bindSandboxAbortSignal } from "#execution/sandbox/abort-bound-session.js";
+import type { SandboxEnvironment } from "#shared/sandbox-environment.js";
import type { ToolExecuteOptions } from "#tools/definition.js";
/** Base context shared by tool executors. */
@@ -18,11 +19,19 @@ export function buildBaseToolContext(input: {
const callbackContext = buildCallbackContext();
const signal = input.options.abortSignal ?? new AbortController().signal;
+ const getSandbox = (async (environment?: SandboxEnvironment) =>
+ bindSandboxAbortSignal(
+ await (environment === undefined
+ ? callbackContext.getSandbox()
+ : callbackContext.getSandbox(environment)),
+ signal,
+ )) as SessionContext["getSandbox"];
+
return {
...callbackContext,
abortSignal: signal,
callId: input.options.toolCallId,
- getSandbox: async () => bindSandboxAbortSignal(await callbackContext.getSandbox(), signal),
+ getSandbox,
toolName: input.toolName,
};
}
diff --git a/packages/eve/src/context/build-callback-context.ts b/packages/eve/src/context/build-callback-context.ts
index b516776f9..1d138ba63 100644
--- a/packages/eve/src/context/build-callback-context.ts
+++ b/packages/eve/src/context/build-callback-context.ts
@@ -1,4 +1,5 @@
import type { SessionContext } from "#context/session-context.js";
+import type { SandboxEnvironmentIdentity } from "#shared/sandbox-environment.js";
import type { RuntimeSandboxSession, SandboxSession } from "#shared/sandbox-session.js";
import { loadContext } from "#context/container.js";
import { DynamicSkillSandboxKey, SandboxKey, SessionKey } from "#context/keys.js";
@@ -21,7 +22,7 @@ export function buildCallbackContext(): SessionContext {
parent: session.parent,
},
- getSandbox(): Promise<RuntimeSandboxSession> {
+ getSandbox(environment?: SandboxEnvironmentIdentity): Promise<RuntimeSandboxSession> {
const access = ctx.get(SandboxKey);
if (access === undefined) {
throw new Error(
@@ -29,6 +30,9 @@ export function buildCallbackContext(): SessionContext {
"Call ctx.getSandbox() only from authored runtime functions such as tools, hooks, and channel events.",
);
}
+ if (environment !== undefined && access.environment !== environment) {
+ throw new Error("The requested sandbox environment is not active for the current session.");
+ }
return access.get().then((sandbox) => {
if (sandbox === null) {
throw new Error("The sandbox is not available in the current authored runtime context.");
diff --git a/packages/eve/src/context/session-context.ts b/packages/eve/src/context/session-context.ts
index 78fc6ee9d..493aacb3c 100644
--- a/packages/eve/src/context/session-context.ts
+++ b/packages/eve/src/context/session-context.ts
@@ -1,4 +1,9 @@
-import type { RuntimeSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxEnvironment } from "#shared/sandbox-environment.js";
+import type {
+ RuntimeSandboxSession,
+ RuntimeSandboxSessionFor,
+ SandboxSession,
+} from "#shared/sandbox-session.js";
import type { SessionAuth, SessionParent, SessionTurn } from "#context/keys.js";
export type { SessionAuth, SessionParent, SessionTurn };
@@ -27,4 +32,11 @@ export interface SessionContext {
* in the current authored runtime context.
*/
getSandbox(): Promise<RuntimeSandboxSession>;
+ /**
+ * Resolves the session's sandbox with the capabilities declared by its
+ * configured environment. Throws when the environment is not active.
+ */
+ getSandbox<Session extends SandboxSession>(
+ environment: SandboxEnvironment<object | undefined, Session>,
+ ): Promise<RuntimeSandboxSessionFor<Session>>;
}
diff --git a/packages/eve/src/execution/sandbox/abort-bound-session.test.ts b/packages/eve/src/execution/sandbox/abort-bound-session.test.ts
index b885d62c6..c555d2154 100644
--- a/packages/eve/src/execution/sandbox/abort-bound-session.test.ts
+++ b/packages/eve/src/execution/sandbox/abort-bound-session.test.ts
@@ -54,7 +54,6 @@ function createRecordingSession(calls: RecordedCall[]): SandboxSession {
removePath: async (options) => {
record("removePath", options.abortSignal);
},
- setNetworkPolicy: async () => {},
};
}
diff --git a/packages/eve/src/execution/sandbox/bash.test.ts b/packages/eve/src/execution/sandbox/bash.test.ts
index 8556bb12b..dfab31d07 100644
--- a/packages/eve/src/execution/sandbox/bash.test.ts
+++ b/packages/eve/src/execution/sandbox/bash.test.ts
@@ -47,7 +47,6 @@ function createTestSandboxSession(result: SandboxCommandResult): SandboxSession
removePath: async () => {},
resolvePath: (path) => path,
run: vi.fn().mockResolvedValue(result),
- setNetworkPolicy: async () => {},
spawn: async () => {
throw new Error("spawn is not implemented in this test sandbox");
},
diff --git a/packages/eve/src/execution/sandbox/bindings/docker.ts b/packages/eve/src/execution/sandbox/bindings/docker.ts
index 91147e485..99549e3e7 100644
--- a/packages/eve/src/execution/sandbox/bindings/docker.ts
+++ b/packages/eve/src/execution/sandbox/bindings/docker.ts
@@ -1,4 +1,8 @@
-import type { MutableNetworkSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { randomUUID } from "node:crypto";
import {
@@ -90,7 +94,7 @@ export function createDockerSandboxProvider(
DockerSandboxRuntimeOptions,
DockerSandboxPreparedArtifact,
DockerSandboxSessionState,
- MutableNetworkSandboxSession
+ NetworkPolicySandboxSession
> {
const cli = dockerCli ?? createDockerCli();
const authoredOptions = createOptions ?? {};
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts b/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts
index 9ae0cb9d9..9f4b2d11a 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts
@@ -11,7 +11,7 @@ import { adaptMultiplexedCommandToSandboxProcess } from "#execution/sandbox/mult
import { shellQuote } from "#execution/sandbox/shell-quote.js";
import { buildSandboxSession } from "#execution/sandbox/session.js";
import type { SandboxProviderHandle, SandboxProviderHost } from "#shared/sandbox-provider.js";
-import type { FixedNetworkSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
import type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
import { WORKSPACE_ROOT } from "#runtime/workspace/types.js";
import type {
@@ -203,9 +203,7 @@ export async function createBashSandbox(input: {
* Throw rather than silently no-op so brokering code surfaces the gap instead
* of leaking.
*/
-export function createJustBashHandle(
- sandbox: BashSandbox,
-): SandboxProviderHandle<FixedNetworkSandboxSession> {
+export function createJustBashHandle(sandbox: BashSandbox): SandboxProviderHandle<SandboxSession> {
const session = buildSandboxSession(createFileBackedInternalSandboxSession({ sandbox }));
return {
sandbox: session,
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash.ts b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
index a647a49cb..8c629d649 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
@@ -27,7 +27,7 @@ import { buildSandboxSession } from "#execution/sandbox/session.js";
import { createSandboxProviderIdentity } from "#execution/sandbox/provider-identity.js";
import type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
import { resolveSandboxCacheDirectory } from "#internal/application/paths.js";
-import type { FixedNetworkSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
import {
isSandboxPreparedArtifactRecord,
providerResourceTargetFiles,
@@ -54,7 +54,7 @@ export function createJustBashSandboxProvider(
undefined,
JustBashPreparedArtifact,
JustBashSessionState,
- FixedNetworkSandboxSession
+ SandboxSession
> {
const options = authoredOptions ?? {};
const autoInstall = options.autoInstall ?? true;
diff --git a/packages/eve/src/execution/sandbox/bindings/microsandbox-lifecycle.ts b/packages/eve/src/execution/sandbox/bindings/microsandbox-lifecycle.ts
index 9eb071a0e..f0b60694d 100644
--- a/packages/eve/src/execution/sandbox/bindings/microsandbox-lifecycle.ts
+++ b/packages/eve/src/execution/sandbox/bindings/microsandbox-lifecycle.ts
@@ -1,3 +1,8 @@
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { randomUUID } from "node:crypto";
import {
@@ -59,10 +64,7 @@ import {
type SandboxProviderPrepareContext,
} from "#shared/sandbox-provider.js";
import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";
-import type {
- InternalSandboxSession,
- MutableNetworkSandboxSession,
-} from "#shared/sandbox-session.js";
+import type { InternalSandboxSession } from "#shared/sandbox-session.js";
type LiveMicrosandboxOptions = ResolvedMicrosandboxOptions & MicrosandboxSandboxRuntimeOptions;
@@ -75,7 +77,7 @@ export type MicrosandboxPreparedArtifact = {
const activeMicrosandboxSessionHandles = new Map<
string,
- SandboxProviderHandle<MutableNetworkSandboxSession>
+ SandboxProviderHandle<NetworkPolicySandboxSession>
>();
export async function prewarmMicrosandboxTemplate(input: {
@@ -229,7 +231,7 @@ export async function createMicrosandboxHandle(input: {
readonly runtimeOptions?: MicrosandboxSandboxRuntimeOptions;
readonly sessionIdentity?: string;
}): Promise<{
- readonly handle: SandboxProviderHandle<MutableNetworkSandboxSession>;
+ readonly handle: SandboxProviderHandle<NetworkPolicySandboxSession>;
readonly state: {
readonly optionsHash: string;
readonly sessionIdentity: string;
@@ -379,7 +381,7 @@ function createHandle(
sandbox: MicrosandboxVm,
_optionsHash: string,
onShutdown?: () => void,
-): SandboxProviderHandle<MutableNetworkSandboxSession> {
+): SandboxProviderHandle<NetworkPolicySandboxSession> {
const session = buildSandboxSession(
createMicrosandboxInternalSession(sandbox),
async (policy) => {
@@ -414,8 +416,8 @@ function createActiveMicrosandboxSessionKey(sessionRootPath: string, optionsHash
function cacheHandle(
key: string,
- handle: SandboxProviderHandle<MutableNetworkSandboxSession>,
-): SandboxProviderHandle<MutableNetworkSandboxSession> {
+ handle: SandboxProviderHandle<NetworkPolicySandboxSession>,
+): SandboxProviderHandle<NetworkPolicySandboxSession> {
activeMicrosandboxSessionHandles.set(key, handle);
return handle;
}
diff --git a/packages/eve/src/execution/sandbox/bindings/microsandbox.ts b/packages/eve/src/execution/sandbox/bindings/microsandbox.ts
index 65eeffa35..ec2809618 100644
--- a/packages/eve/src/execution/sandbox/bindings/microsandbox.ts
+++ b/packages/eve/src/execution/sandbox/bindings/microsandbox.ts
@@ -1,4 +1,8 @@
-import type { MutableNetworkSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { enrichMicrosandboxError } from "#execution/sandbox/bindings/microsandbox-create.js";
import {
createMicrosandboxHandle,
@@ -39,7 +43,7 @@ export function createMicrosandboxSandboxProvider(
MicrosandboxSandboxRuntimeOptions,
MicrosandboxPreparedArtifact,
MicrosandboxProviderSessionState,
- MutableNetworkSandboxSession
+ NetworkPolicySandboxSession
> {
const createOptions = authoredOptions ?? {};
const options = resolveMicrosandboxOptions(createOptions);
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.ts b/packages/eve/src/execution/sandbox/bindings/vercel.ts
index 9efdd6105..ce0f5d4f0 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel.ts
@@ -1,4 +1,7 @@
-import type { MutableNetworkSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { VERCEL_EVE_SANDBOX_IMAGE } from "#execution/sandbox/bindings/eve-image.js";
import {
applyInitialVercelNetworkPolicy,
@@ -82,7 +85,7 @@ export function createVercelSandboxProvider(
VercelSandboxRuntimeOptions,
VercelSandboxPreparedArtifact,
VercelSandboxSessionState,
- MutableNetworkSandboxSession
+ NetworkPolicySandboxSession
> {
const { prepare, ...authoredCreateOptions } = environmentOptions ?? {};
return createVercelSandbox({ createOptions: authoredCreateOptions, prepare });
@@ -103,7 +106,7 @@ export function createVercelSandbox(
VercelSandboxRuntimeOptions,
VercelSandboxPreparedArtifact,
VercelSandboxSessionState,
- MutableNetworkSandboxSession
+ NetworkPolicySandboxSession
> {
const loadSandboxModule =
input.loadSandboxModule ?? (async () => await import("#compiled/@vercel/sandbox/index.js"));
@@ -536,7 +539,7 @@ function createHandle(input: {
readonly createOptions: VercelCreateOptions;
readonly loadDeleteSandboxModule: () => Promise<VercelModule>;
readonly sandbox: VercelSandbox;
-}): SandboxProviderHandle<MutableNetworkSandboxSession> {
+}): SandboxProviderHandle<NetworkPolicySandboxSession> {
const { sandbox } = input;
return {
sandbox: buildSandboxSession(
diff --git a/packages/eve/src/execution/sandbox/ensure.ts b/packages/eve/src/execution/sandbox/ensure.ts
index 0cf3f514d..4ae87de90 100644
--- a/packages/eve/src/execution/sandbox/ensure.ts
+++ b/packages/eve/src/execution/sandbox/ensure.ts
@@ -273,7 +273,10 @@ export async function ensureSandboxAccess(input: EnsureSandboxAccessInput): Prom
return requiring;
}
+ const activeDefinition = registered.inheritance?.definition ?? registered.definition;
+
return {
+ environment: activeDefinition.kind === "independent" ? activeDefinition.environment : undefined,
async captureState() {
if (opening !== undefined) await opening;
return { session: persisted };
diff --git a/packages/eve/src/execution/sandbox/logging-session.test.ts b/packages/eve/src/execution/sandbox/logging-session.test.ts
index d2c8ae914..5eb1de1b0 100644
--- a/packages/eve/src/execution/sandbox/logging-session.test.ts
+++ b/packages/eve/src/execution/sandbox/logging-session.test.ts
@@ -24,37 +24,6 @@ describe("createLoggingSandboxSession", () => {
expect(log.mock.calls.flat().join("\n")).not.toContain("do-not-log");
});
- it("redacts brokered credential values from network policy logs", async () => {
- const log = vi.fn();
- const session = createTestSession();
- const wrapped = createLoggingSandboxSession({ log, session });
-
- const policy = {
- allow: {
- "api.github.com": [
- {
- transform: [
- {
- headers: {
- Authorization: "Bearer ghp_repro-do-not-log",
- "x-api-key": "repro-api-key-do-not-log",
- },
- },
- ],
- },
- ],
- },
- };
- await wrapped.setNetworkPolicy?.(policy);
-
- const message = log.mock.calls.flat().join("\n");
- expect(message).toContain("api.github.com");
- expect(message).toContain('"transform":"[redacted]"');
- expect(message).not.toContain("ghp_repro-do-not-log");
- expect(message).not.toContain("repro-api-key-do-not-log");
- expect(session.setNetworkPolicy).toHaveBeenCalledWith(policy);
- });
-
it("wraps the original session when no logger is provided", () => {
const session = createTestSession();
expect(createLoggingSandboxSession({ session })).not.toBe(session);
@@ -135,6 +104,5 @@ function createTestSession(runResult = { exitCode: 0, stderr: "", stdout: "" }):
writeBinaryFile: vi.fn(async () => {}),
writeTextFile: vi.fn(async () => {}),
removePath: vi.fn(async () => {}),
- setNetworkPolicy: vi.fn(async () => {}),
};
}
diff --git a/packages/eve/src/execution/sandbox/logging-session.ts b/packages/eve/src/execution/sandbox/logging-session.ts
index 3e6cea880..6a038171e 100644
--- a/packages/eve/src/execution/sandbox/logging-session.ts
+++ b/packages/eve/src/execution/sandbox/logging-session.ts
@@ -7,7 +7,6 @@ import type {
SandboxWriteFileOptions,
SandboxWriteTextFileOptions,
} from "#shared/sandbox-session.js";
-import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
import { truncateTail } from "#execution/sandbox/truncate-output.js";
const MAX_LOG_VALUE_LENGTH = 240;
@@ -33,14 +32,6 @@ export function createLoggingSandboxSession(input: {
log?.(`preparation spawn: ${formatCommand(options.command)}`);
return await session.spawn(options);
},
- ...(session.setNetworkPolicy === undefined
- ? {}
- : {
- async setNetworkPolicy(policy: SandboxNetworkPolicy) {
- log?.(`preparation set network policy: ${formatNetworkPolicy(policy)}`);
- return await session.setNetworkPolicy!(policy);
- },
- }),
async writeFile(options: SandboxWriteFileOptions) {
log?.(`preparation write file: ${options.path}`);
return await session.writeFile(options);
@@ -88,16 +79,6 @@ function formatCommand(command: string): string {
return truncateOneLine(command);
}
-function formatNetworkPolicy(policy: SandboxNetworkPolicy): string {
- return truncateOneLine(
- typeof policy === "string"
- ? policy
- : JSON.stringify(policy, (key, value: unknown) =>
- key === "transform" ? "[redacted]" : value,
- ),
- );
-}
-
function truncateOneLine(value: string): string {
const singleLine = value.replaceAll(/\s+/g, " ").trim();
if (singleLine.length <= MAX_LOG_VALUE_LENGTH) {
diff --git a/packages/eve/src/execution/sandbox/session.test.ts b/packages/eve/src/execution/sandbox/session.test.ts
index 07c3cdecc..772e57bdd 100644
--- a/packages/eve/src/execution/sandbox/session.test.ts
+++ b/packages/eve/src/execution/sandbox/session.test.ts
@@ -51,13 +51,13 @@ describe("buildSandboxSession", () => {
},
};
- await session.setNetworkPolicy?.(policy);
+ await session.setNetworkPolicy(policy);
expect(apply).toHaveBeenCalledWith(policy);
});
- it("omits setNetworkPolicy when no applier is supplied", () => {
- expect(buildSandboxSession(createTestPrimitives()).setNetworkPolicy).toBeUndefined();
+ it("returns the common session surface when no applier is supplied", () => {
+ expect(buildSandboxSession(createTestPrimitives())).not.toHaveProperty("setNetworkPolicy");
});
// ---------------------------------------------------------------------------
diff --git a/packages/eve/src/execution/sandbox/session.ts b/packages/eve/src/execution/sandbox/session.ts
index 54c7b07f1..e04d3211b 100644
--- a/packages/eve/src/execution/sandbox/session.ts
+++ b/packages/eve/src/execution/sandbox/session.ts
@@ -1,6 +1,9 @@
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import type {
InternalSandboxSession,
- MutableNetworkSandboxSession,
SandboxProcess,
SandboxReadBinaryFileOptions,
SandboxReadFileOptions,
@@ -13,7 +16,6 @@ import type {
SandboxWriteFileOptions,
SandboxWriteTextFileOptions,
} from "#shared/sandbox-session.js";
-import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
import { bufferToStream, streamToBuffer } from "./stream-utils.js";
export type { InternalSandboxSession };
@@ -33,7 +35,7 @@ export type { InternalSandboxSession };
export function buildSandboxSession(
primitives: InternalSandboxSession,
setNetworkPolicy: (policy: SandboxNetworkPolicy) => Promise<void>,
-): MutableNetworkSandboxSession;
+): NetworkPolicySandboxSession;
export function buildSandboxSession(primitives: InternalSandboxSession): SandboxSession;
export function buildSandboxSession(
primitives: InternalSandboxSession,
@@ -116,8 +118,8 @@ export function buildSandboxSession(
});
},
};
- if (setNetworkPolicy !== undefined) session.setNetworkPolicy = setNetworkPolicy;
- return session;
+ if (setNetworkPolicy === undefined) return session;
+ return { ...session, setNetworkPolicy } as NetworkPolicySandboxSession;
}
/**
diff --git a/packages/eve/src/internal/testing/mocks/mock-sandbox.ts b/packages/eve/src/internal/testing/mocks/mock-sandbox.ts
index 22f78a087..c09c95496 100644
--- a/packages/eve/src/internal/testing/mocks/mock-sandbox.ts
+++ b/packages/eve/src/internal/testing/mocks/mock-sandbox.ts
@@ -12,8 +12,11 @@ import type {
SandboxWriteFileOptions,
SandboxWriteTextFileOptions,
} from "#public/definitions/sandbox.js";
-import type { SandboxAccess, SandboxState } from "#sandbox/state.js";
import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
+import type { SandboxAccess, SandboxState } from "#sandbox/state.js";
import { bufferToStream, streamToBuffer } from "#execution/sandbox/stream-utils.js";
/**
@@ -83,7 +86,7 @@ export interface MockSandbox {
* Direct handle to the underlying sandbox session. Exposed for tests that
* want to call the session surface outside a `ctx` scope.
*/
- readonly session: SandboxSession;
+ readonly session: NetworkPolicySandboxSession;
/** Ordered log of every command received through `run`/`spawn`. */
readonly commandLog: readonly string[];
/** Ordered log of every path received through `removePath`. */
@@ -177,7 +180,7 @@ export function mockSandbox(input: MockSandboxInput = {}): MockSandbox {
}
}
- const baseSession: SandboxSession = {
+ const baseSession: NetworkPolicySandboxSession = {
resolvePath(path: string): string {
return resolveWorkspacePath(path);
},
@@ -252,7 +255,7 @@ export function mockSandbox(input: MockSandboxInput = {}): MockSandbox {
async delete(): Promise<void> {
await input.delete?.();
},
- async get(): Promise<SandboxSession> {
+ async get(): Promise<NetworkPolicySandboxSession> {
return session;
},
async stop(): Promise<void> {
diff --git a/packages/eve/src/public/channels/github/checkout.ts b/packages/eve/src/public/channels/github/checkout.ts
index 57badb51a..dddb1b7db 100644
--- a/packages/eve/src/public/channels/github/checkout.ts
+++ b/packages/eve/src/public/channels/github/checkout.ts
@@ -1,3 +1,8 @@
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import {
getGitHubPullRequest,
getGitHubRepository,
@@ -10,7 +15,6 @@ import {
} from "#public/channels/github/auth.js";
import { gitHubGitBrokerNetworkPolicy, gitHubRemoteUrl, isFullGitSha } from "#shared/git.js";
import { shellQuote } from "#shared/shell-quote.js";
-import type { SandboxSession } from "#shared/sandbox-session.js";
const DEFAULT_CHECKOUT_PATH = "/workspace";
const DEFAULT_CHECKOUT_DEPTH = 1;
@@ -65,7 +69,7 @@ export interface GitHubCheckoutInput extends GitHubCheckoutOptions {
* Channel-internal; not part of the public GitHub channel API.
*/
export async function checkoutGitHubRepository(
- sandbox: SandboxSession,
+ sandbox: NetworkPolicySandboxSession,
input: GitHubCheckoutInput,
): Promise<GitHubCheckout> {
const descriptor = await resolveCheckoutDescriptor(input);
@@ -99,9 +103,6 @@ export async function checkoutGitHubRepository(
// (token-free) URL and the platform injects `Authorization` on egress to
// GitHub, so the token never enters the sandbox process. The `"*"` rule keeps
// the agent's other egress open.
- if (sandbox.setNetworkPolicy === undefined) {
- throw new Error("GitHub checkout requires a sandbox provider with mutable network policy.");
- }
await sandbox.setNetworkPolicy(gitHubGitBrokerNetworkPolicy(token));
await runCheckoutCommand({
diff --git a/packages/eve/src/public/channels/github/defaults.ts b/packages/eve/src/public/channels/github/defaults.ts
index 44c80aaf3..ca9ab70e9 100644
--- a/packages/eve/src/public/channels/github/defaults.ts
+++ b/packages/eve/src/public/channels/github/defaults.ts
@@ -1,3 +1,8 @@
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import type { SessionAuthContext } from "#channel/types.js";
import { createLogger, extractErrorId, formatErrorHint, logError } from "#internal/logging.js";
@@ -19,6 +24,7 @@ import type {
} from "#public/channels/github/githubChannel.js";
import { splitGitHubCommentBody } from "#public/channels/github/limits.js";
import type { SessionContext } from "#public/definitions/callback-context.js";
+import type { RuntimeSandboxSession } from "#shared/sandbox-session.js";
import type { InputRequest } from "#shared/input.js";
const log = createLogger("github.defaults");
@@ -174,20 +180,26 @@ async function checkoutRepositoryForTurn(
const { state } = channel;
try {
const sandbox = await ctx.getSandbox();
- const checkout = await checkoutGitHubRepository(sandbox, {
- api: options.api,
- baseRef: state.baseRef,
- baseSha: state.baseSha,
- credentials: options.credentials,
- defaultBranch: state.defaultBranch,
- headRef: state.headRef,
- headSha: state.headSha,
- includeBase: state.pullRequestNumber !== null,
- installationId: state.installationId,
- owner: state.owner,
- pullRequestNumber: state.pullRequestNumber,
- repo: state.repo,
- });
+ if (!("setNetworkPolicy" in sandbox)) {
+ throw new Error("GitHub checkout requires a sandbox provider with mutable network policy.");
+ }
+ const checkout = await checkoutGitHubRepository(
+ sandbox as RuntimeSandboxSession & NetworkPolicySandboxSession,
+ {
+ api: options.api,
+ baseRef: state.baseRef,
+ baseSha: state.baseSha,
+ credentials: options.credentials,
+ defaultBranch: state.defaultBranch,
+ headRef: state.headRef,
+ headSha: state.headSha,
+ includeBase: state.pullRequestNumber !== null,
+ installationId: state.installationId,
+ owner: state.owner,
+ pullRequestNumber: state.pullRequestNumber,
+ repo: state.repo,
+ },
+ );
state.checkoutPath = checkout.path;
state.headSha = checkout.sha;
state.baseRef = checkout.baseRef;
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 8cb7b17a6..1049062fa 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -453,7 +453,7 @@ function typeOnlyFixtures(): void {
resources: { vcpus: 4 },
});
const sessionId: string = session.id;
- await sandbox.setNetworkPolicy?.("allow-all");
+ await sandbox.setNetworkPolicy("allow-all");
void sessionId;
return sandbox;
});
diff --git a/packages/eve/src/public/definitions/sandbox.ts b/packages/eve/src/public/definitions/sandbox.ts
index 12ee76482..ccaaf0828 100644
--- a/packages/eve/src/public/definitions/sandbox.ts
+++ b/packages/eve/src/public/definitions/sandbox.ts
@@ -7,8 +7,6 @@ export type {
SandboxReadFileOptions,
SandboxRemovePathOptions,
SandboxReadTextFileOptions,
- FixedNetworkSandboxSession,
- MutableNetworkSandboxSession,
SandboxRunOptions,
SandboxSession,
RuntimeSandboxSession,
diff --git a/packages/eve/src/public/sandbox/docker.ts b/packages/eve/src/public/sandbox/docker.ts
index 47332f47d..893a39042 100644
--- a/packages/eve/src/public/sandbox/docker.ts
+++ b/packages/eve/src/public/sandbox/docker.ts
@@ -1,3 +1,12 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+import type { DockerSandboxNetworkPolicy } from "#public/sandbox/docker-sandbox.js";
+
+/** Live sandbox capabilities exposed by a Docker environment. */
+export interface DockerSandboxSession extends SandboxSession {
+ /** Applies a coarse egress policy to the live container. */
+ setNetworkPolicy(policy: DockerSandboxNetworkPolicy): Promise<void>;
+}
+
export {
DockerSandbox,
type DockerSandboxEnvironmentOptions,
diff --git a/packages/eve/src/public/sandbox/index.ts b/packages/eve/src/public/sandbox/index.ts
index 1dc64b86e..19a8ce546 100644
--- a/packages/eve/src/public/sandbox/index.ts
+++ b/packages/eve/src/public/sandbox/index.ts
@@ -6,8 +6,6 @@ export {
type SandboxSelector,
type SandboxSelectorContext,
type SandboxCommandResult,
- type FixedNetworkSandboxSession,
- type MutableNetworkSandboxSession,
type SandboxProcess,
type SandboxReadBinaryFileOptions,
type SandboxReadFileOptions,
diff --git a/packages/eve/src/public/sandbox/microsandbox.ts b/packages/eve/src/public/sandbox/microsandbox.ts
index 5c6aefa1e..4d81d8868 100644
--- a/packages/eve/src/public/sandbox/microsandbox.ts
+++ b/packages/eve/src/public/sandbox/microsandbox.ts
@@ -1,3 +1,12 @@
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+
+/** Live sandbox capabilities exposed by a microsandbox environment. */
+export interface MicrosandboxSandboxSession extends SandboxSession {
+ /** Applies a firewall policy to the live microsandbox VM. */
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+}
+
export {
MicrosandboxSandbox,
type MicrosandboxEnvironmentOptions,
diff --git a/packages/eve/src/public/sandbox/vercel.test.ts b/packages/eve/src/public/sandbox/vercel.test.ts
index 02a378b5d..b5c844005 100644
--- a/packages/eve/src/public/sandbox/vercel.test.ts
+++ b/packages/eve/src/public/sandbox/vercel.test.ts
@@ -1,5 +1,7 @@
import { describe, expect, expectTypeOf, it } from "vitest";
-import { Drive, VercelSandbox } from "#public/sandbox/vercel.js";
+import type { SessionContext } from "#context/session-context.js";
+import type { RuntimeSandboxSessionFor } from "#public/definitions/sandbox.js";
+import { Drive, VercelSandbox, type VercelSandboxSession } from "#public/sandbox/vercel.js";
describe("VercelSandbox", () => {
it("creates environments", () => {
const environment = VercelSandbox.environment({ resources: { vcpus: 4 } });
@@ -7,4 +9,15 @@ describe("VercelSandbox", () => {
expectTypeOf(environment.open).toBeFunction();
expectTypeOf(Drive.getOrCreate).toBeFunction();
});
+
+ it("preserves its session capabilities through getSandbox", () => {
+ const environment = VercelSandbox.environment({});
+ const assertTypes = (ctx: SessionContext) => {
+ expectTypeOf(ctx.getSandbox(environment)).toEqualTypeOf<
+ Promise<RuntimeSandboxSessionFor<VercelSandboxSession>>
+ >();
+ };
+
+ expectTypeOf(assertTypes).toBeFunction();
+ });
});
diff --git a/packages/eve/src/public/sandbox/vercel.ts b/packages/eve/src/public/sandbox/vercel.ts
index ab9a4afb1..3b2845c48 100644
--- a/packages/eve/src/public/sandbox/vercel.ts
+++ b/packages/eve/src/public/sandbox/vercel.ts
@@ -1,3 +1,12 @@
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+
+/** Live sandbox capabilities exposed by a Vercel environment. */
+export interface VercelSandboxSession extends SandboxSession {
+ /** Applies a firewall policy to the live Vercel Sandbox. */
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+}
+
export {
VercelSandbox,
type VercelSandboxEnvironmentOptions,
diff --git a/packages/eve/src/sandbox/providers.test.ts b/packages/eve/src/sandbox/providers.test.ts
index bb3ce6da7..a208495b3 100644
--- a/packages/eve/src/sandbox/providers.test.ts
+++ b/packages/eve/src/sandbox/providers.test.ts
@@ -1,11 +1,9 @@
+import type { DockerSandboxSession } from "#public/sandbox/docker.js";
import { describe, expect, expectTypeOf, it } from "vitest";
import { defineDefaultSandboxProvider } from "#sandbox/providers/default.js";
import { DockerSandbox, MicrosandboxSandbox, VercelSandbox } from "#sandbox/providers.js";
-import type {
- MutableNetworkSandboxSession,
- RuntimeSandboxSessionFor,
-} from "#shared/sandbox-session.js";
+import type { RuntimeSandboxSessionFor } from "#shared/sandbox-session.js";
describe("sandbox providers", () => {
it("implements default selection through the provider contract", () => {
@@ -28,9 +26,9 @@ describe("sandbox providers", () => {
});
it("returns runtime sandboxes from open", () => {
- const environment = DockerSandbox.environment();
+ const environment = DockerSandbox.environment({});
expectTypeOf(environment.open).returns.toEqualTypeOf<
- Promise<RuntimeSandboxSessionFor<MutableNetworkSandboxSession>>
+ Promise<RuntimeSandboxSessionFor<DockerSandboxSession>>
>();
});
});
diff --git a/packages/eve/src/sandbox/providers/docker.ts b/packages/eve/src/sandbox/providers/docker.ts
index 889331260..bad50add4 100644
--- a/packages/eve/src/sandbox/providers/docker.ts
+++ b/packages/eve/src/sandbox/providers/docker.ts
@@ -1,3 +1,4 @@
+import type { DockerSandboxSession } from "#public/sandbox/docker.js";
import { createDockerSandboxProvider } from "#execution/sandbox/bindings/local.js";
import type {
DockerSandboxEnvironmentOptions,
@@ -5,7 +6,6 @@ import type {
} from "#public/sandbox/docker-sandbox.js";
import type { SandboxEnvironment } from "#shared/sandbox-environment.js";
import { defineSandboxProvider } from "#shared/sandbox-provider.js";
-import type { MutableNetworkSandboxSession } from "#shared/sandbox-session.js";
export type {
DockerSandboxEnvironmentOptions,
@@ -19,7 +19,7 @@ const provider = defineSandboxProvider<
DockerSandboxRuntimeOptions,
{ readonly imageReference: string },
{ readonly containerName: string; readonly generation: string; readonly version: 2 },
- MutableNetworkSandboxSession
+ DockerSandboxSession
>({
name: "docker",
environment(options) {
@@ -31,13 +31,13 @@ export const DockerSandbox = {
...provider,
dockerfile(
options: DockerfileEnvironmentInput = {},
- ): SandboxEnvironment<DockerSandboxRuntimeOptions, MutableNetworkSandboxSession> {
+ ): SandboxEnvironment<DockerSandboxRuntimeOptions, DockerSandboxSession> {
return provider.environment(options);
},
image(
reference: string,
options: DockerfileEnvironmentInput = {},
- ): SandboxEnvironment<DockerSandboxRuntimeOptions, MutableNetworkSandboxSession> {
+ ): SandboxEnvironment<DockerSandboxRuntimeOptions, DockerSandboxSession> {
return provider.environment({ ...options, image: reference });
},
};
diff --git a/packages/eve/src/sandbox/providers/just-bash.ts b/packages/eve/src/sandbox/providers/just-bash.ts
index 8ce20bf72..3397b1454 100644
--- a/packages/eve/src/sandbox/providers/just-bash.ts
+++ b/packages/eve/src/sandbox/providers/just-bash.ts
@@ -1,7 +1,7 @@
import { createJustBashSandboxProvider } from "#execution/sandbox/bindings/local.js";
import type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
import { defineSandboxProvider } from "#shared/sandbox-provider.js";
-import type { FixedNetworkSandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
export type JustBashEnvironmentOptions = JustBashSandboxCreateOptions;
@@ -10,7 +10,7 @@ export const JustBashSandbox = defineSandboxProvider<
undefined,
{ readonly templateRootPath: string },
{ readonly generation: string; readonly rootPath: string; readonly version: 2 },
- FixedNetworkSandboxSession
+ SandboxSession
>({
name: "just-bash",
environment: (options) => createJustBashSandboxProvider(options),
diff --git a/packages/eve/src/sandbox/providers/microsandbox.ts b/packages/eve/src/sandbox/providers/microsandbox.ts
index 68f175e68..1646c4b07 100644
--- a/packages/eve/src/sandbox/providers/microsandbox.ts
+++ b/packages/eve/src/sandbox/providers/microsandbox.ts
@@ -1,3 +1,4 @@
+import type { MicrosandboxSandboxSession } from "#public/sandbox/microsandbox.js";
import {
createMicrosandboxSandboxProvider,
type MicrosandboxProviderSessionState,
@@ -9,7 +10,6 @@ import type {
} from "#public/sandbox/microsandbox-sandbox.js";
import type { SandboxEnvironment } from "#shared/sandbox-environment.js";
import { defineSandboxProvider } from "#shared/sandbox-provider.js";
-import type { MutableNetworkSandboxSession } from "#shared/sandbox-session.js";
export type MicrosandboxEnvironmentOptions = MicrosandboxSandboxCreateOptions;
@@ -20,7 +20,7 @@ const provider = defineSandboxProvider<
MicrosandboxSandboxRuntimeOptions,
MicrosandboxPreparedArtifact,
MicrosandboxProviderSessionState,
- MutableNetworkSandboxSession
+ MicrosandboxSandboxSession
>({
name: "microsandbox",
stateProtocolVersion: 3,
@@ -31,13 +31,13 @@ export const MicrosandboxSandbox = {
...provider,
dockerfile(
options: DockerfileEnvironmentInput = {},
- ): SandboxEnvironment<MicrosandboxSandboxRuntimeOptions, MutableNetworkSandboxSession> {
+ ): SandboxEnvironment<MicrosandboxSandboxRuntimeOptions, MicrosandboxSandboxSession> {
return provider.environment(options);
},
image(
reference: string,
options: DockerfileEnvironmentInput = {},
- ): SandboxEnvironment<MicrosandboxSandboxRuntimeOptions, MutableNetworkSandboxSession> {
+ ): SandboxEnvironment<MicrosandboxSandboxRuntimeOptions, MicrosandboxSandboxSession> {
return provider.environment({ ...options, image: reference });
},
};
diff --git a/packages/eve/src/sandbox/providers/vercel.ts b/packages/eve/src/sandbox/providers/vercel.ts
index 149a0816d..5a3643fac 100644
--- a/packages/eve/src/sandbox/providers/vercel.ts
+++ b/packages/eve/src/sandbox/providers/vercel.ts
@@ -1,3 +1,4 @@
+import type { VercelSandboxSession } from "#public/sandbox/vercel.js";
import {
createVercelSandbox,
createVercelSandboxProvider,
@@ -10,7 +11,7 @@ import type {
} from "#public/sandbox/vercel-sandbox.js";
import type { SandboxEnvironment } from "#shared/sandbox-environment.js";
import { defineSandboxProvider } from "#shared/sandbox-provider.js";
-import type { MutableNetworkSandboxSession, SandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
export type VercelSandboxEnvironmentOptions = VercelSandboxCreateOptions & {
readonly prepare?: (sandbox: SandboxSession) => Promise<void> | void;
@@ -22,7 +23,7 @@ const defaultProvider = defineSandboxProvider<
VercelSandboxRuntimeOptions,
VercelSandboxPreparedArtifact,
VercelSandboxSessionState,
- MutableNetworkSandboxSession
+ VercelSandboxSession
>({
name: "vercel",
environment: (options) => {
@@ -36,7 +37,7 @@ const provider = defineSandboxProvider<
VercelSandboxRuntimeOptions,
VercelSandboxPreparedArtifact,
VercelSandboxSessionState,
- MutableNetworkSandboxSession
+ VercelSandboxSession
>({
name: "vercel",
environment: (options) => createVercelSandboxProvider(options),
@@ -44,7 +45,7 @@ const provider = defineSandboxProvider<
export function createDefaultVercelEnvironment(
options?: VercelSandboxEnvironmentOptions,
-): SandboxEnvironment<VercelSandboxRuntimeOptions, MutableNetworkSandboxSession> {
+): SandboxEnvironment<VercelSandboxRuntimeOptions, VercelSandboxSession> {
return defaultProvider.environment(options);
}
@@ -52,7 +53,7 @@ export const VercelSandbox = {
name: "vercel",
environment(
options?: VercelSandboxEnvironmentOptions,
- ): SandboxEnvironment<VercelSandboxRuntimeOptions, MutableNetworkSandboxSession> {
+ ): SandboxEnvironment<VercelSandboxRuntimeOptions, VercelSandboxSession> {
return provider.environment(options);
},
};
diff --git a/packages/eve/src/sandbox/state.ts b/packages/eve/src/sandbox/state.ts
index 8dfb90f12..db9af96ef 100644
--- a/packages/eve/src/sandbox/state.ts
+++ b/packages/eve/src/sandbox/state.ts
@@ -1,4 +1,5 @@
import type { SandboxSession } from "#public/definitions/sandbox.js";
+import type { SandboxEnvironmentIdentity } from "#shared/sandbox-environment.js";
import type { SandboxDeleteOptions, SandboxPreparedArtifact } from "#shared/sandbox-provider.js";
export interface SandboxSessionState {
@@ -12,6 +13,7 @@ export interface SandboxState {
}
export interface SandboxAccess {
+ readonly environment?: SandboxEnvironmentIdentity;
captureState(): Promise<SandboxState>;
delete?(options?: SandboxDeleteOptions): Promise<void>;
get(): Promise<SandboxSession | null>;
diff --git a/packages/eve/src/self-modification/git-workspace.ts b/packages/eve/src/self-modification/git-workspace.ts
index 2ee94062b..9a38b0961 100644
--- a/packages/eve/src/self-modification/git-workspace.ts
+++ b/packages/eve/src/self-modification/git-workspace.ts
@@ -1,5 +1,10 @@
import type { SandboxSession } from "eve/sandbox";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
+
import { gitHubRemoteUrl } from "#shared/git.js";
import { shellQuote } from "#shared/shell-quote.js";
@@ -22,8 +27,7 @@ export interface PreparedSelfModificationWorkspace {
readonly targetBranch: string;
}
-type CheckoutSandbox = Pick<SandboxSession, "run"> &
- Required<Pick<SandboxSession, "setNetworkPolicy">>;
+type CheckoutSandbox = Pick<NetworkPolicySandboxSession, "run" | "setNetworkPolicy">;
/** Prepares a token-free remote and immutable target-branch checkout for one child session. */
export async function prepareSelfModificationWorkspace(input: {
diff --git a/packages/eve/src/self-modification/git.ts b/packages/eve/src/self-modification/git.ts
index 96147e282..8c1d190a8 100644
--- a/packages/eve/src/self-modification/git.ts
+++ b/packages/eve/src/self-modification/git.ts
@@ -1,6 +1,10 @@
import type { SandboxSession } from "eve/sandbox";
import { gitHubGitBrokerNetworkPolicy } from "#shared/git.js";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+type NetworkPolicySandboxSession = SandboxSession & {
+ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+};
import { SELF_MODIFICATION_BASELINE_NETWORK_POLICY } from "./network-policy.js";
@@ -8,7 +12,7 @@ const MAX_ERROR_OUTPUT = 2_000;
type CommandSandbox = Pick<SandboxSession, "run">;
export async function withBrokeredGitHubCredential<T>(
- sandbox: Required<Pick<SandboxSession, "setNetworkPolicy">>,
+ sandbox: Pick<NetworkPolicySandboxSession, "setNetworkPolicy">,
token: string,
operation: () => Promise<T>,
): Promise<T> {
diff --git a/packages/eve/src/shared/sandbox-network-policy.ts b/packages/eve/src/shared/sandbox-network-policy.ts
index 340d2ef99..548b4ebff 100644
--- a/packages/eve/src/shared/sandbox-network-policy.ts
+++ b/packages/eve/src/shared/sandbox-network-policy.ts
@@ -9,7 +9,9 @@ import type * as Vercel from "#compiled/@vercel/sandbox/index.js";
* firewall so secrets never enter the sandbox process:
*
* ```ts
- * const sandbox = await ctx.getSandbox();
+ * import { environment } from "../sandbox";
+ *
+ * const sandbox = await ctx.getSandbox(environment);
* await sandbox.setNetworkPolicy({
* allow: {
* "github.com": [{ transform: [{ headers: { authorization: "Basic ..." } }] }],
@@ -19,9 +21,8 @@ import type * as Vercel from "#compiled/@vercel/sandbox/index.js";
* ```
*
* The Docker provider honors only the coarse `"allow-all"` and
- * `"deny-all"` policies; the just-bash provider rejects `setNetworkPolicy`
- * entirely (its network policy is fixed at sandbox creation and it runs
- * no binaries to govern).
+ * `"deny-all"` policies. just-bash environments do not expose
+ * `setNetworkPolicy` because their network policy is fixed at sandbox creation.
*/
export type SandboxNetworkPolicy = Vercel.NetworkPolicy;
diff --git a/packages/eve/src/shared/sandbox-session.ts b/packages/eve/src/shared/sandbox-session.ts
index 3c84edd80..3184e24f4 100644
--- a/packages/eve/src/shared/sandbox-session.ts
+++ b/packages/eve/src/shared/sandbox-session.ts
@@ -1,7 +1,6 @@
import type { Experimental_SandboxSession as AiSdkSandbox } from "ai";
import type { SandboxDeleteOptions } from "#shared/sandbox-provider.js";
-import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
/**
* Options for running one command in a sandbox. Shape mirrors the AI
@@ -109,8 +108,6 @@ export interface SandboxSession extends Pick<
* The read and write methods already apply this internally.
*/
resolvePath(path: string): string;
- /** Applies a firewall policy when the selected provider supports mutable networking. */
- setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
/**
* Removes one file or directory from the sandbox filesystem.
*
@@ -119,20 +116,6 @@ export interface SandboxSession extends Pick<
removePath(options: SandboxRemovePathOptions): Promise<void>;
}
-/**
- * Sandbox session exposed to authored runtime callbacks through
- * `ctx.getSandbox()`.
- *
- * Unlike the I/O-only session used during sandbox initialization, this handle
- * exposes provider-backed lifecycle operations.
- */
-export interface MutableNetworkSandboxSession extends SandboxSession {
- /** Applies a firewall policy to the live sandbox. */
- setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
-}
-
-export type FixedNetworkSandboxSession = Omit<SandboxSession, "setNetworkPolicy">;
-
export interface RuntimeSandboxSession extends SandboxSession {
/** Permanently deletes this sandbox and its disposable provider state. */
delete(options?: SandboxDeleteOptions): Promise<void>;