Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): keep tool sessions and sandboxes across invokeTool calls (#4235)

Rui933996ce63d1
diff --git a/.changeset/invoke-tool-sessions.md b/.changeset/invoke-tool-sessions.md
new file mode 100644
index 000000000..db5397c0c
--- /dev/null
+++ b/.changeset/invoke-tool-sessions.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+`invokeTool` now accepts a `key`: calls from the same caller with the same key share one session id and keep their sandbox between calls, on Vercel Sandbox and just-bash. `mcpChannel({ tools: true })` advertises the `dev.eve/tool-sessions` extension, so MCP clients that declare it can join a tool session with `_meta["dev.eve/tool-session"]`. A forwarded caller's session also covers the verified forwarder, passed as `invokeTool`'s `forwardedBy` (`mcpChannel` passes the router its `auth` verified), so one user reached through two routers gets two sessions. Tool sessions need an authenticated caller: a keyed call from the anonymous principal `none()` gives is denied. On Vercel Sandbox, a tool session's saved filesystem expires a day after its last use, so the next call with the key starts a fresh sandbox; a deploy that changes the agent's sandbox definition also starts a fresh sandbox for each key.
diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdx
index b21151a26..c9348455f 100644
--- a/docs/channels/custom.mdx
+++ b/docs/channels/custom.mdx
@@ -68,7 +68,7 @@ Each route receives these operation surfaces:
- `to(channel, target).send(message, options)` hands work to another authored channel.
- `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
- `describe()` returns the agent's name, description, the compiled tools a caller can run outside a turn, with their JSON schemas, and the compiled skills, each with its `name` and `description`, sorted by name. It reads the compiled manifest only, never a skill file, and carries no other paths, config, or inspection detail, so a channel can publish it to its callers. Tools that need a turn (framework tools, workflow and provider tools, tools without `execute`) and tools and skills added by dynamic resolvers or subagents are left out.
-- `invokeTool(name, input, { auth })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Each call gets its own session. Authored state starts from its initial value and is not kept, and a sandbox the tool opens is deleted when the call ends. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
+- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox or just-bash, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
A direct call doesn't go through the AI SDK, so AI SDK telemetry integrations never see it. Conversation tool calls do: an integration that an `agent/instrumentation/*.ts` module registers with `registerTelemetry()` from `ai` receives `onToolExecutionStart` and `onToolExecutionEnd` for each of them. A direct call is traced by eve itself instead. It gets an `execute_tool` span under the caller's trace and emits `tool.call.started` and `tool.call.completed` to instrumentation. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
diff --git a/docs/channels/mcp.mdx b/docs/channels/mcp.mdx
index 2e732cb94..9545eacc3 100644
--- a/docs/channels/mcp.mdx
+++ b/docs/channels/mcp.mdx
@@ -227,7 +227,7 @@ export default mcpChannel({
`tools/list` returns the `agent_*` tools first, then the agent's tools in name order with their input and output JSON schemas. Framework tools, workflow and provider tools, tools without `execute`, and tools added by dynamic resolvers or subagents are not published. While `agent` is on, an agent tool named `agent_start`, `agent_get`, `agent_update`, or `agent_cancel` is not published, and eve logs a warning. With `agent: false`, the channel sends no `agent_*` instructions. Turning off `agent`, `tools`, and `skills` all at once throws, since the channel would publish nothing.
-Each `tools/call` checks the arguments against the tool's input schema, then runs the tool as the route-authenticated caller, or as a [forwarded user](#forwarded-principals), with no model, turn, or workflow run. Every caller the channel's `auth` admits can call these tools, outside the agent's instructions, so review what becomes callable before you turn this on. Each call gets its own session:
+Each `tools/call` checks the arguments against the tool's input schema, then runs the tool as the route-authenticated caller, or as a [forwarded user](#forwarded-principals), with no model, turn, or workflow run. Every caller the channel's `auth` admits can call these tools, outside the agent's instructions, so review what becomes callable before you turn this on. Unless the call joins a [tool session](#tool-sessions), it gets its own session:
- Authored state starts from its initial value, and updates are not kept.
- A sandbox the tool opens is deleted when the call ends.
@@ -238,7 +238,7 @@ A tool that cannot finish over MCP returns an error result with `isError: true`
| Code | When |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `invalid_input` | The tool rejected its input. |
-| `denied` | The tool's approval policy denied the call. |
+| `denied` | The tool's approval policy denied the call, or an anonymous caller sent a tool session key. |
| `approval_required` | The approval policy asks a person. The tool did not run; call it from a conversation instead. |
| `authorization_required` | The tool needs a sign-in to a connection first. Sign in from a conversation, then call it again. |
| `internal` | The tool failed. The message carries an error id that matches the server logs. |
@@ -277,6 +277,49 @@ The predicate receives the verified forwarder and the principals it asserts, as
| The channel has no `trustedForwarders` | `403` |
| The predicate throws | `500` |
+### Tool sessions
+
+A tool session lets several `tools/call` requests share one sandbox, so a file one call writes is there for the next. With `tools: true`, the channel advertises the `dev.eve/tool-sessions` extension in `capabilities.extensions` of `server/discover`. A client joins a session by declaring the same extension in the request's `io.modelcontextprotocol/clientCapabilities` and sending a key of 1 to 512 characters in `_meta["dev.eve/tool-session"]`:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "write_note",
+ "arguments": { "text": "Feed Biscuit at 18:00." },
+ "_meta": {
+ "dev.eve/tool-session": "alice-front-desk",
+ "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+ "io.modelcontextprotocol/clientInfo": { "name": "front-desk", "version": "1.0.0" },
+ "io.modelcontextprotocol/clientCapabilities": {
+ "extensions": { "dev.eve/tool-sessions": {} }
+ }
+ }
+ }
+}
+```
+
+eve derives the session id from the principal the call runs as (the route-authenticated caller, or a [forwarded user](#forwarded-principals) together with the verified router that forwarded them) and the key, so calls from the same principal with the same key share the session, and another caller who sends the same key gets a different one. That holds for forwarded users too: two users forwarded with the same key, or one user forwarded by two routers, get separate sessions. The router counted is the one the channel's `auth` verified, never one named in the forwarded principal. A key from a client that did not declare the extension is ignored, and the call gets its own session. Clients on the 2025-11-25 protocol send no per-request capabilities, so they always get their own session.
+
+Tool sessions need an authenticated caller. With `auth: none()` every request is the same anonymous principal, so a key alone would name the session and anyone who knew it could read what another client left in the sandbox. A keyed call from an anonymous caller is therefore denied with the `denied` error code before anything runs; unkeyed anonymous calls still get a one-off session.
+
+In a tool session:
+
+- The sandbox opens on the first `ctx.getSandbox()` and is kept for later calls with the same key. Concurrent first calls share one sandbox.
+- The sandbox belongs to the agent's current sandbox definition. A deploy that changes it (the template, its snapshot, or the open options in `sandbox.ts` and its resources) starts a fresh, empty sandbox for the same key; the old one expires as below.
+- `ctx.session.id` is the same for every call with the key.
+- Traces still show each call as its own run. Its `agent.run.id` and `gen_ai.conversation.id` are a fresh id for that call, not `ctx.session.id`, so traces do not link calls that share a key.
+- Authored state still starts from its initial value on every call, and updates are not kept. Keep data that must outlive a call in the sandbox.
+- Calls may still run in parallel, and nothing orders them.
+
+Tool sessions need a sandbox provider that finds the session's sandbox again: Vercel Sandbox or just-bash. On another provider, a call with a key fails with a `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` error when the tool opens its sandbox. Tools that never open a sandbox still run. just-bash keeps its sandboxes on the local disk, so on Vercel Functions a just-bash tool session lasts only as long as the function instance.
+
+A tool session has no end, so eve bounds how long its sandbox is kept. On Vercel Sandbox, a tool-session sandbox's saved filesystem expires a day after its last use, and each call that resumes it restarts that day. The next call with the key after that replaces it with a fresh, empty sandbox. If two calls with the key find the expired filesystem at the same time, each can replace the sandbox, and files the first one writes can be lost. Vercel only keeps the latest snapshot of the sandbox. Tool sessions use this one-day expiry whatever `snapshotExpiration` `sandbox.ts` sets; sessions that conversations start keep the authored setting.
+
+just-bash keeps tool-session sandboxes on the local disk, and nothing removes them.
+
## Publish the agent's skills
Set `skills: true` to serve the agent's skills as [SEP-2640](https://modelcontextprotocol.io/seps/2640) skills under `skill://`, so a client that calls the agent's tools can also read the workflow knowledge behind them:
diff --git a/e2e/fixtures/agent-mcp/agent/sandbox/sandbox.ts b/e2e/fixtures/agent-mcp/agent/sandbox/sandbox.ts
new file mode 100644
index 000000000..3f83a559d
--- /dev/null
+++ b/e2e/fixtures/agent-mcp/agent/sandbox/sandbox.ts
@@ -0,0 +1,11 @@
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+import { JustBashSandbox } from "eve/sandbox/just-bash";
+
+// A keyed tool session needs a provider that finds its sandbox again from the
+// session id: Vercel Sandbox on Vercel, just-bash elsewhere. The default's local
+// Docker and microsandbox providers cannot, so they are not used here.
+export const environment = process.env.VERCEL
+ ? DefaultSandbox.environment()
+ : JustBashSandbox.environment({});
+
+export default defineSandbox(async () => await environment.open());
diff --git a/e2e/fixtures/agent-mcp/agent/tools/read_note.ts b/e2e/fixtures/agent-mcp/agent/tools/read_note.ts
new file mode 100644
index 000000000..fdc4eef49
--- /dev/null
+++ b/e2e/fixtures/agent-mcp/agent/tools/read_note.ts
@@ -0,0 +1,13 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+import { NOTE_PATH } from "../../fixture";
+
+export default defineTool({
+ description: "Read the note the previous shift left in the sandbox workspace.",
+ inputSchema: z.object({}),
+ async execute(_input, ctx) {
+ const sandbox = await ctx.getSandbox();
+ return { text: await sandbox.readTextFile({ path: NOTE_PATH }) };
+ },
+});
diff --git a/e2e/fixtures/agent-mcp/agent/tools/write_note.ts b/e2e/fixtures/agent-mcp/agent/tools/write_note.ts
new file mode 100644
index 000000000..057dde1a7
--- /dev/null
+++ b/e2e/fixtures/agent-mcp/agent/tools/write_note.ts
@@ -0,0 +1,14 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+import { NOTE_PATH } from "../../fixture";
+
+export default defineTool({
+ description: "Leave a note for the next shift in the sandbox workspace.",
+ inputSchema: z.object({ text: z.string() }),
+ async execute({ text }, ctx) {
+ const sandbox = await ctx.getSandbox();
+ await sandbox.writeTextFile({ content: text, path: NOTE_PATH });
+ return { written: text };
+ },
+});
diff --git a/e2e/fixtures/agent-mcp/evals/tool-session.eval.ts b/e2e/fixtures/agent-mcp/evals/tool-session.eval.ts
new file mode 100644
index 000000000..1e4063880
--- /dev/null
+++ b/e2e/fixtures/agent-mcp/evals/tool-session.eval.ts
@@ -0,0 +1,70 @@
+import { defineEval, type EveEvalTargetHandle } from "eve/evals";
+import { equals } from "eve/evals/expect";
+
+import { MCP_PATH, NOTE_PATH, SERVICE_TOKEN } from "../fixture";
+
+const MCP_PROTOCOL_VERSION = "2026-07-28";
+
+/** One `tools/call` from a 2026-07-28 client that declares tool sessions. */
+async function callTool(
+ target: EveEvalTargetHandle,
+ name: string,
+ args: Record<string, unknown>,
+ key: string,
+): Promise<any> {
+ const response = await target.fetch(MCP_PATH, {
+ body: JSON.stringify({
+ id: crypto.randomUUID(),
+ jsonrpc: "2.0",
+ method: "tools/call",
+ params: {
+ _meta: {
+ "dev.eve/tool-session": key,
+ "io.modelcontextprotocol/clientCapabilities": {
+ extensions: { "dev.eve/tool-sessions": {} },
+ },
+ "io.modelcontextprotocol/clientInfo": { name: "front-desk", version: "0.0.0" },
+ "io.modelcontextprotocol/protocolVersion": MCP_PROTOCOL_VERSION,
+ },
+ arguments: args,
+ name,
+ },
+ }),
+ headers: {
+ accept: "application/json, text/event-stream",
+ authorization: `Bearer ${SERVICE_TOKEN}`,
+ "content-type": "application/json",
+ "mcp-method": "tools/call",
+ "mcp-name": name,
+ "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+ },
+ method: "POST",
+ });
+ const body = await response.text();
+ if (!response.ok) throw new Error(`tools/call ${name}: HTTP ${response.status}: ${body}`);
+ const data = response.headers.get("content-type")?.includes("text/event-stream")
+ ? body
+ .split("\n")
+ .find((line) => line.startsWith("data: "))
+ ?.slice("data: ".length)
+ : body;
+ if (data === undefined) throw new Error(`tools/call ${name} returned no event.`);
+ return JSON.parse(data).result;
+}
+
+export default defineEval({
+ description: `Two MCP tool calls with one tool-session key share a sandbox: the second reads the ${NOTE_PATH} the first wrote.`,
+ timeoutMs: 240_000,
+
+ async test(t) {
+ // Alice's front-desk app keeps one session for her shift.
+ const key = `alice-front-desk-${crypto.randomUUID()}`;
+ const text = `Feed Biscuit at 18:00 (${crypto.randomUUID()}).`;
+
+ const wrote = await callTool(t.target, "write_note", { text }, key);
+ await t.require(wrote?.structuredContent, equals({ written: text }));
+
+ const read = await callTool(t.target, "read_note", {}, key);
+ await t.require(read?.structuredContent, equals({ text }));
+ },
+});
diff --git a/e2e/fixtures/agent-mcp/fixture.ts b/e2e/fixtures/agent-mcp/fixture.ts
index b1b4e5829..d164e09df 100644
--- a/e2e/fixtures/agent-mcp/fixture.ts
+++ b/e2e/fixtures/agent-mcp/fixture.ts
@@ -18,6 +18,9 @@ export const LOOPBACK_CONNECTION = "loopback";
export const MCP_PATH = "/eve/v1/mcp";
+/** Where the note tools keep the front-desk note in the sandbox. */
+export const NOTE_PATH = "/workspace/front-desk-note.txt";
+
/** This deployment's MCP channel, the way `kennelUrl()` reaches its own kennel. */
export function selfMcpUrl(): string {
const deploymentHost = process.env.VERCEL_URL;
diff --git a/packages/eve/extension-contracts/compatibility/channel/v50.ts b/packages/eve/extension-contracts/compatibility/channel/v50.ts
new file mode 100644
index 000000000..397f42609
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v50.ts
@@ -0,0 +1,20 @@
+import { defineChannel, POST } from "#public/channels/index.js";
+
+// Epoch 50 invokeTool options had no `key` or `forwardedBy`; epoch 51 adds them.
+export default defineChannel({
+ routes: [
+ POST("/tools/:name", async (request, { describe, invokeTool, params }) => {
+ const { tools } = await describe();
+ if (!tools.some((tool) => tool.name === params.name)) {
+ return Response.json({ error: "unknown tool" }, { status: 404 });
+ }
+ const auth = {
+ attributes: {},
+ authenticator: "fixture",
+ principalId: "fixture",
+ principalType: "service",
+ };
+ return Response.json(await invokeTool(params.name!, await request.json(), { auth }));
+ }),
+ ],
+});
diff --git a/packages/eve/extension-contracts/reports/channel/v51.json b/packages/eve/extension-contracts/reports/channel/v51.json
new file mode 100644
index 000000000..c175ac398
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v51.json
@@ -0,0 +1,21 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 51,
+ "sha256": "ff0188570c7f0f7cb686ded015d604dad4755b0db890b4c8e66d6a9b20fc4c97",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/scripts/vendor-compiled/@modelcontextprotocol/server.mjs b/packages/eve/scripts/vendor-compiled/@modelcontextprotocol/server.mjs
index 80637c35e..009432109 100644
--- a/packages/eve/scripts/vendor-compiled/@modelcontextprotocol/server.mjs
+++ b/packages/eve/scripts/vendor-compiled/@modelcontextprotocol/server.mjs
@@ -18,6 +18,10 @@ export type McpJsonObject = Readonly<Record<string, unknown>>;
export interface McpRequestHandlerExtra {
readonly mcpReq: {
+ /** The request's \`_meta\`, without the reserved \`io.modelcontextprotocol/*\` keys. */
+ readonly _meta?: Readonly<Record<string, unknown>>;
+ /** The reserved \`io.modelcontextprotocol/*\` keys the request carried. */
+ readonly envelope?: Readonly<Record<string, unknown>>;
readonly signal: AbortSignal;
};
}
diff --git a/packages/eve/src/channel/invoke-tool.ts b/packages/eve/src/channel/invoke-tool.ts
index 3bf9e0728..d5366652b 100644
--- a/packages/eve/src/channel/invoke-tool.ts
+++ b/packages/eve/src/channel/invoke-tool.ts
@@ -1,12 +1,31 @@
import type { SessionAuthContext } from "#channel/types.js";
import type { ToolModelOutput } from "#tools/model-output.js";
+/** Longest {@link InvokeToolOptions.key} `invokeTool` accepts. */
+export const TOOL_SESSION_KEY_MAX_LENGTH = 512;
+
/** Options for one {@link InvokeToolFn} call. */
export interface InvokeToolOptions {
/** The caller this request authenticated. Becomes `ctx.session.auth.current`. */
readonly auth: SessionAuthContext;
/** Becomes `ctx.session.auth.initiator`. Defaults to `auth`. */
readonly initiator?: SessionAuthContext;
+ /**
+ * The verified caller that forwarded `auth`, when a trusted forwarder
+ * asserted it. A keyed session's identity includes it, so one user reached
+ * through two forwarders gets two sessions. Pass the principal the route
+ * authenticated, never one read from the request.
+ */
+ readonly forwardedBy?: SessionAuthContext;
+ /**
+ * Names a tool session the call joins: 1 to 512 characters, chosen by the
+ * caller. Calls from the same `auth` principal with the same key share one
+ * session id and one sandbox, which outlives the call. A different
+ * principal using the same key gets a different session. Without a key,
+ * the call runs in a one-off session. An anonymous `auth` (from `none()`)
+ * cannot send a key: the call is denied before anything runs.
+ */
+ readonly key?: string;
readonly signal?: AbortSignal;
}
@@ -27,10 +46,12 @@ export type InvokeToolResult =
/**
* Runs one of the agent's tools outside a conversation. No model, turn, or
- * workflow step is involved, and the call never parks. Each call gets its own
- * session: `ctx.session.auth.current` is the caller, authored state starts from
- * its initial value and is not kept, and a sandbox the tool opens is deleted
- * when the call ends.
+ * workflow step is involved, and the call never parks. `ctx.session.auth.current`
+ * is the caller, and authored state starts from its initial value and is not
+ * kept, with or without a key. Without `key`, each call gets its own session,
+ * and a sandbox the tool opens is deleted when the call ends. With `key`, the
+ * session id is stable for that caller and key, and its sandbox is kept for
+ * the next call with the same key.
*/
export type InvokeToolFn = (
name: string,
diff --git a/packages/eve/src/channel/principal-identity.ts b/packages/eve/src/channel/principal-identity.ts
new file mode 100644
index 000000000..195d41a0b
--- /dev/null
+++ b/packages/eve/src/channel/principal-identity.ts
@@ -0,0 +1,21 @@
+import type { SessionAuthContext } from "#channel/types.js";
+
+/**
+ * The fields that identify a principal, in a fixed order, for hashing into
+ * invocation owner keys and tool session ids. Attributes describe a principal;
+ * they do not identify it. Adding a field changes every derived hash.
+ */
+export function principalIdentity(auth: SessionAuthContext): readonly string[] {
+ return [
+ auth.authenticator,
+ auth.issuer ?? "",
+ auth.principalType,
+ auth.principalId,
+ auth.subject ?? "",
+ ];
+}
+
+/** Whether `auth` is the shared principal `none()` gives every unauthenticated caller. */
+export function isAnonymousPrincipal(auth: SessionAuthContext): boolean {
+ return auth.principalType === "anonymous";
+}
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 575cdd94a..6baadb041 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -127,10 +127,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
channel: {
- current: 50,
+ current: 51,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31, 36, 37, 38, 39, 40, 41, 42,
- 43, 44, 45, 46, 47, 48, 49, 50,
+ 43, 44, 45, 46, 47, 48, 49, 50, 51,
],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
diff --git a/packages/eve/src/context/providers/sandbox.test.ts b/packages/eve/src/context/providers/sandbox.test.ts
index 452aefa8d..675601338 100644
--- a/packages/eve/src/context/providers/sandbox.test.ts
+++ b/packages/eve/src/context/providers/sandbox.test.ts
@@ -59,6 +59,7 @@ describe("sandboxProvider", () => {
beforeEach(() => {
vi.mocked(ensureSandboxAccess).mockResolvedValue({
captureState: vi.fn().mockResolvedValue({ initialized: false, session: null }),
+ detach: vi.fn().mockResolvedValue(undefined),
get: vi.fn().mockResolvedValue(null),
stop: vi.fn().mockResolvedValue(undefined),
});
diff --git a/packages/eve/src/execution/invoke-tool-trace-ownership.integration.test.ts b/packages/eve/src/execution/invoke-tool-trace-ownership.integration.test.ts
index f3e20ba80..96b78332a 100644
--- a/packages/eve/src/execution/invoke-tool-trace-ownership.integration.test.ts
+++ b/packages/eve/src/execution/invoke-tool-trace-ownership.integration.test.ts
@@ -176,3 +176,27 @@ describe("invokeTool trace ownership", () => {
expect(processor.activeTraceIds().size).toBe(0);
});
});
+
+describe("invokeTool trace identity", () => {
+ const identity = (span: ReadableSpan) => ({
+ conversation: span.attributes["gen_ai.conversation.id"],
+ run: span.attributes["agent.run.id"],
+ });
+
+ it("gives each keyed call its own run and conversation, never the tool session id", async () => {
+ await invokeTool(runtime, "lookup", {}, { auth: alice, key: "desk" });
+ await invokeTool(runtime, "lookup", {}, { auth: alice, key: "desk" });
+
+ const [first, second] = exporter
+ .getFinishedSpans()
+ .filter((span) => span.name === "execute_tool lookup")
+ .map(identity);
+ expect(first!.run).toMatch(/^call_session_/u);
+ expect(first!.conversation).toBe(first!.run);
+ expect(second!.run).toMatch(/^call_session_/u);
+ expect(second!.run).not.toBe(first!.run);
+ expect(second!.conversation).not.toBe(first!.conversation);
+ const recorded = JSON.stringify(exporter.getFinishedSpans().map((span) => span.attributes));
+ expect(recorded).not.toContain("tool_session_");
+ });
+});
diff --git a/packages/eve/src/execution/invoke-tool.test.ts b/packages/eve/src/execution/invoke-tool.test.ts
index 0e8c45300..2940025b5 100644
--- a/packages/eve/src/execution/invoke-tool.test.ts
+++ b/packages/eve/src/execution/invoke-tool.test.ts
@@ -5,6 +5,7 @@ import type { SessionAuthContext } from "#channel/types.js";
import { shutdownActiveSandboxHandles } from "#execution/sandbox/active-handles.js";
import { invokeTool, type InvokeToolRuntime } from "#execution/invoke-tool.js";
import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
+import { withToolSessionSandboxes } from "#execution/tool-session/sandbox.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
import { defineSandbox } from "#public/definitions/sandbox.js";
@@ -92,6 +93,87 @@ function sandboxes(options: { readonly startGate?: Promise<void> } = {}) {
return { deleted, registry, shutdown, started };
}
+/**
+ * A provider whose `start` reopens a session's sandbox by session id, as
+ * Vercel Sandbox and just-bash do, opted into tool sessions.
+ * Each open hands out its own handle over the shared sandbox, as just-bash
+ * runs one interpreter per handle; `released` records which handles a call
+ * let go of, and `stopped` which were stopped through the sandbox API.
+ */
+function keyedSandboxes(options: { readonly failSelector?: () => boolean } = {}) {
+ const live = new Map<string, { sandbox: ReturnType<typeof mockSandbox> }>();
+ const starts: string[] = [];
+ const handles: object[] = [];
+ const released: object[] = [];
+ const stopped = vi.fn();
+ const deleted = vi.fn((sessionId: string) => void live.delete(sessionId));
+ const reopen = (sessionId: string) => {
+ let entry = live.get(sessionId);
+ if (entry === undefined) {
+ starts.push(sessionId);
+ entry = { sandbox: mockSandbox() };
+ live.set(sessionId, entry);
+ }
+ const handle = {
+ sandbox: entry.sandbox.session,
+ onRuntimeShutdown: async () => {},
+ onSessionDelete: async () => deleted(sessionId),
+ onSessionStop: stopped,
+ };
+ handles.push(handle);
+ return handle;
+ };
+ const environment = defineSandboxProvider({
+ name: "keyed",
+ environment: () =>
+ withToolSessionSandboxes(
+ {
+ prepare: async () => null,
+ resume: async (context: { readonly session: { readonly id: string } }) =>
+ reopen(context.session.id),
+ start: async (context: { readonly session: { readonly id: string } }) => ({
+ handle: reopen(context.session.id),
+ state: {},
+ }),
+ },
+ {
+ releaseHandle: async (handle) => void released.push(handle),
+ },
+ ),
+ }).environment();
+ const registry: RuntimeSandboxRegistry = {
+ sandbox: {
+ definition: {
+ environment,
+ kind: "independent",
+ logicalPath: "sandbox.ts",
+ revisionHash: "hash",
+ selector: defineSandbox(async () => {
+ const sandbox = await environment.open();
+ if (options.failSelector?.() === true) throw new Error("selector failed");
+ return sandbox;
+ }),
+ sourceId: "sandbox",
+ sourceKind: "module",
+ },
+ workspaceResourceRoot: { logicalPath: "", rootEntries: [] },
+ },
+ };
+ return { deleted, handles, live, registry, released, starts, stopped };
+}
+
+/** A tool that appends to a note in its sandbox and returns the note, after `gate` opens. */
+function noteTool(gate: Promise<void> = Promise.resolve()) {
+ return tool("note", async (input: { text: string }, ctx) => {
+ const sandbox = await ctx.getSandbox();
+ await gate;
+ const previous = await sandbox.readTextFile({ path: "/workspace/note.txt" });
+ const note = (previous ?? "") + input.text;
+ await sandbox.writeTextFile({ content: note, path: "/workspace/note.txt" });
+ return note;
+ });
+}
+
function runtimeWith(
tools: readonly HarnessToolDefinition[],
registry = sandboxes().registry,
@@ -243,4 +325,175 @@ describe("invokeTool", () => {
await shutdownActiveSandboxHandles();
expect(shutdown).not.toHaveBeenCalled();
});
+
+ it("keeps one sandbox per caller and key across calls", async () => {
+ const { deleted, registry, starts } = keyedSandboxes();
+ const runtime = runtimeWith([noteTool()], registry);
+ const note = (text: string, auth: SessionAuthContext, key: string) =>
+ invokeTool(runtime, "note", { text }, { auth, key });
+
+ // Concurrent first calls converge on one sandbox; later calls reuse it.
+ const first = await Promise.all([note("a", alice, "desk"), note("b", alice, "desk")]);
+ expect(first.map((result) => result.status)).toEqual(["completed", "completed"]);
+ expect(starts).toHaveLength(1);
+ expect(await note("c", alice, "desk")).toMatchObject({
+ output: expect.stringMatching(/^[ab]{1,2}c$/u),
+ });
+ // Another key, or another caller with the same key, gets its own sandbox.
+ expect(await note("x", alice, "lobby")).toMatchObject({ output: "x" });
+ expect(await note("y", bob, "desk")).toMatchObject({ output: "y" });
+ expect(starts).toHaveLength(3);
+ expect(deleted).not.toHaveBeenCalled();
+ });
+
+ it("keeps forwarded callers apart by effective user and by the forwarder that vouched", async () => {
+ const { registry, starts } = keyedSandboxes();
+ const runtime = runtimeWith([noteTool()], registry);
+ const router = (principalId: string): SessionAuthContext => ({
+ ...alice,
+ principalId,
+ principalType: "service",
+ });
+ const [routerA, routerB] = [router("router-a"), router("router-b")];
+ // A forwarded user's attributes are asserted by the forwarder, so the
+ // session must not depend on them: both routers stamp the same ones.
+ const forwarded = (principalId: string): SessionAuthContext => ({
+ ...alice,
+ attributes: { "eve:forwarded-by": "router" },
+ principalId,
+ });
+ const note = (text: string, auth: SessionAuthContext, forwardedBy: SessionAuthContext) =>
+ invokeTool(runtime, "note", { text }, { auth, forwardedBy, key: "desk" });
+
+ expect(await note("a", forwarded("alice"), routerA)).toMatchObject({ output: "a" });
+ // Another user through the same router, with the same key.
+ expect(await note("b", forwarded("bob"), routerA)).toMatchObject({ output: "b" });
+ // The same user and key through another router.
+ expect(await note("c", forwarded("alice"), routerB)).toMatchObject({ output: "c" });
+ // Neither is the user's direct session, and the first one is still there.
+ const direct = await invokeTool(runtime, "note", { text: "d" }, { auth: alice, key: "desk" });
+ expect(direct).toMatchObject({ output: "d" });
+ expect(await note("e", forwarded("alice"), routerA)).toMatchObject({ output: "ae" });
+ expect(starts).toHaveLength(4);
+ expect(new Set(starts).size).toBe(4);
+ });
+
+ it("lets go of each keyed call's own handle when it ends, and nothing else", async () => {
+ const { handles, registry, released, stopped } = keyedSandboxes();
+ let openGate!: () => void;
+ const held = runtimeWith(
+ [noteTool(new Promise<void>((resolve) => (openGate = resolve)))],
+ registry,
+ );
+ const runtime = runtimeWith([noteTool()], registry);
+ const note = (text: string, run = runtime) =>
+ invokeTool(run, "note", { text }, { auth: alice, key: "desk" });
+
+ const holding = note("a", held);
+ await vi.waitFor(() => expect(handles).toHaveLength(1));
+ // An overlapping call reopens the same sandbox through its own handle and
+ // releases only that one when it ends; the first call's handle stays open.
+ expect(await note("b")).toMatchObject({ status: "completed" });
+ expect(handles).toHaveLength(2);
+ expect(released).toEqual([handles[1]]);
+ openGate();
+ expect(await holding).toMatchObject({ status: "completed" });
+ expect(released).toEqual([handles[1], handles[0]]);
+ // The sandbox itself is neither stopped nor tracked for shutdown any more.
+ expect(stopped).not.toHaveBeenCalled();
+ await shutdownActiveSandboxHandles();
+ expect(await note("c")).toMatchObject({ output: expect.stringMatching(/^[ab]{2}c$/u) });
+
+ // A call that fails, or never opens a sandbox, has no handle to let go of.
+ const failing = tool("failing", () => {
+ throw new Error("boom");
+ });
+ expect(
+ await invokeTool(
+ runtimeWith([failing], registry),
+ "failing",
+ {},
+ { auth: alice, key: "desk" },
+ ),
+ ).toMatchObject({ status: "failed" });
+ expect(handles).toHaveLength(3);
+ expect(released).toHaveLength(3);
+ });
+
+ it("lets go of a keyed call's handle even when the call fails after opening it", async () => {
+ const { handles, registry, released } = keyedSandboxes();
+ const failing = tool("failing", async (_input: unknown, ctx) => {
+ await ctx.getSandbox();
+ throw new Error("boom");
+ });
+ expect(
+ await invokeTool(
+ runtimeWith([failing], registry),
+ "failing",
+ {},
+ { auth: alice, key: "desk" },
+ ),
+ ).toMatchObject({ status: "failed" });
+ expect(released).toEqual(handles);
+ expect(handles).toHaveLength(1);
+ });
+
+ it("denies an anonymous caller a key before deriving a session or opening a sandbox", async () => {
+ const { registry, starts } = keyedSandboxes();
+ const execute = vi.fn(() => "ran");
+ const runtime = runtimeWith([tool("note", execute)], registry);
+ const anonymous: SessionAuthContext = {
+ attributes: {},
+ authenticator: "none",
+ principalId: "anonymous",
+ principalType: "anonymous",
+ };
+
+ expect(await invokeTool(runtime, "note", {}, { auth: anonymous, key: "desk" })).toEqual({
+ reason: expect.stringContaining("anonymous caller cannot send a key"),
+ status: "denied",
+ });
+ expect(execute).not.toHaveBeenCalled();
+ expect(starts).toHaveLength(0);
+ // Without a key the anonymous caller still gets a one-off call.
+ expect(await invokeTool(runtime, "note", {}, { auth: anonymous })).toMatchObject({
+ output: "ran",
+ status: "completed",
+ });
+ });
+
+ it("refuses a keyed sandbox on a provider that cannot keep it, and an empty key", async () => {
+ const runtime = runtimeWith([noteTool()], sandboxes().registry);
+ expect(await invokeTool(runtime, "note", { text: "a" }, { auth: alice, key: "desk" })).toEqual({
+ message: expect.stringContaining('Sandbox provider "memory" cannot keep a sandbox'),
+ status: "failed",
+ });
+ expect(await invokeTool(runtime, "note", { text: "a" }, { auth: alice, key: "" })).toEqual({
+ message: "The tool session key must not be empty.",
+ status: "invalid-input",
+ });
+ });
+
+ it("never deletes a keyed sandbox another call is using when its own start fails", async () => {
+ let failSelector = false;
+ const { deleted, live, registry } = keyedSandboxes({ failSelector: () => failSelector });
+ let openGate!: () => void;
+ const runtime = runtimeWith(
+ [noteTool(new Promise<void>((resolve) => (openGate = resolve)))],
+ registry,
+ );
+ const holding = invokeTool(runtime, "note", { text: "a" }, { auth: alice, key: "desk" });
+ await vi.waitFor(() => expect(live.size).toBe(1));
+
+ // The second call's `start` finds the first call's sandbox, then its selector fails.
+ failSelector = true;
+ expect(
+ await invokeTool(runtime, "note", { text: "b" }, { auth: alice, key: "desk" }),
+ ).toMatchObject({ status: "failed" });
+ openGate();
+ expect(await holding).toMatchObject({ output: "a", status: "completed" });
+ expect(deleted).not.toHaveBeenCalled();
+ });
});
+
+const bob: SessionAuthContext = { ...alice, principalId: "bob" };
diff --git a/packages/eve/src/execution/invoke-tool.ts b/packages/eve/src/execution/invoke-tool.ts
index 3ec3b1517..823313e36 100644
--- a/packages/eve/src/execution/invoke-tool.ts
+++ b/packages/eve/src/execution/invoke-tool.ts
@@ -7,6 +7,7 @@ import {
type CompiledToolBindings,
isInvocableCompiledTool,
} from "#channel/tool-eligibility.js";
+import { isAnonymousPrincipal } from "#channel/principal-identity.js";
import type { SessionAuthContext } from "#channel/types.js";
import type { CompiledToolDefinition } from "#compiler/manifest.js";
import { isConnectionAuthorizationFailedError } from "#connections/errors.js";
@@ -14,6 +15,12 @@ import { buildCallbackContext } from "#context/build-callback-context.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { AuthKey, InitiatorAuthKey, SandboxKey, SessionIdKey, SessionKey } from "#context/keys.js";
import { ensureSandboxAccess } from "#execution/sandbox/ensure.js";
+import { deriveToolSessionId, validateToolSessionKey } from "#execution/tool-session/id.js";
+import {
+ assertToolSessionSandboxSupport,
+ releaseToolSessionHandle,
+ ToolSessionSandboxUnsupportedError,
+} from "#execution/tool-session/sandbox.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import {
AuthorizationHookKey,
@@ -89,8 +96,12 @@ function ineligibility(
}
/**
- * Runs one tool outside a turn; see `InvokeToolFn` for the contract. Each call
- * gets a fresh session id, so nothing it opens is shared with another call.
+ * Runs one tool outside a turn; see `InvokeToolFn` for the contract. A call
+ * without a key gets a fresh session id, so nothing it opens is shared with
+ * another call. A keyed call derives its session id from the caller and key.
+ * Either way the session's authored state is call-scoped: tool sessions keep
+ * only their sandbox. An anonymous caller is denied a keyed call: with one
+ * shared principal, the key alone would name the session.
*/
export async function invokeTool(
runtime: InvokeToolRuntime,
@@ -110,15 +121,34 @@ export async function invokeTool(
return failed(`Tool "${name}" cannot be invoked outside a conversation: ${ineligible}.`);
}
+ const key = options.key;
+ const keyProblem = key === undefined ? undefined : validateToolSessionKey(key);
+ if (keyProblem !== undefined) return { message: keyProblem, status: "invalid-input" };
+ // `none()` gives every caller one principal, so a key would be a shared secret
+ // that opens the same sandbox to anyone who guesses it.
+ if (key !== undefined && isAnonymousPrincipal(options.auth)) {
+ return denied(
+ "Tool sessions need an authenticated caller: an anonymous caller cannot send a key. " +
+ "Call without a key for a one-off session.",
+ );
+ }
+
const callId = `call_${createUlid()}`;
- const sessionId = `call_session_${createUlid()}`;
+ // Each call is its own run in traces. A tool session id is stable per caller
+ // and key, so it only finds the sandbox: as a run or conversation id it would
+ // join calls days apart and show which calls came from the same caller.
+ const runSessionId = `call_session_${createUlid()}`;
+ const sessionId =
+ key === undefined
+ ? runSessionId
+ : deriveToolSessionId({ current: options.auth, forwardedBy: options.forwardedBy, key });
return await withInvokeToolSpan(
{
agentName: runtime.agentName,
auth: options.auth,
callId,
origin: runtime.origin,
- sessionId,
+ sessionId: runSessionId,
toolName: name,
},
(observer) =>
@@ -144,7 +174,10 @@ async function runInvocation(input: {
}
if (validated.kind === "invalid") return { message: validated.message, status: "invalid-input" };
- const sandbox = await callSandbox(runtime, sessionId);
+ const sandbox =
+ options.key === undefined
+ ? await callSandbox(runtime, sessionId)
+ : await keyedSandbox(runtime, sessionId);
const context = createCallContext({
auth: options.auth,
initiator: options.initiator ?? options.auth,
@@ -167,16 +200,50 @@ async function runInvocation(input: {
);
} finally {
await sandbox.release().catch((error: unknown) => {
- logError(log, "failed to delete a call's sandbox", error, { sessionId, toolName: name });
+ logError(log, "failed to release a call's sandbox", error, { sessionId, toolName: name });
});
}
}
+interface CallSandbox {
+ readonly access: SandboxAccess;
+ release(): Promise<void>;
+}
+
+/**
+ * A keyed session's sandbox: found or created on the first `ctx.getSandbox()`
+ * through the provider's `start`, which reopens it by session id, and kept
+ * after the call. Concurrent first calls in this process share one start.
+ * The call does not own the sandbox, so a failed start never deletes it, and
+ * release only lets go of this call's handle: an overlapping call keeps its
+ * own.
+ */
+async function keyedSandbox(runtime: InvokeToolRuntime, sessionId: string): Promise<CallSandbox> {
+ const inner = await ensureSandboxAccess({
+ compiledArtifactsSource: runtime.compiledArtifactsSource,
+ nodeId: runtime.nodeId,
+ ownsSandbox: false,
+ registry: runtime.sandboxRegistry,
+ sessionId,
+ state: null,
+ });
+ return {
+ access: {
+ ...inner,
+ async get() {
+ assertToolSessionSandboxSupport(runtime.sandboxRegistry);
+ return await inner.get();
+ },
+ },
+ async release() {
+ const handle = await inner.detach();
+ if (handle !== undefined) await releaseToolSessionHandle(runtime.sandboxRegistry, handle);
+ },
+ };
+}
+
/** The call's sandbox: opened on the first `ctx.getSandbox()`, deleted after the call. */
-async function callSandbox(
- runtime: InvokeToolRuntime,
- sessionId: string,
-): Promise<{ readonly access: SandboxAccess; release(): Promise<void> }> {
+async function callSandbox(runtime: InvokeToolRuntime, sessionId: string): Promise<CallSandbox> {
const inner = await ensureSandboxAccess({
compiledArtifactsSource: runtime.compiledArtifactsSource,
nodeId: runtime.nodeId,
@@ -293,7 +360,10 @@ async function runCall(input: {
if (returned) {
return failedFromError(error, definition.name, "tool output could not be serialized");
}
- if (isConnectionAuthorizationFailedError(error)) {
+ if (
+ isConnectionAuthorizationFailedError(error) ||
+ error instanceof ToolSessionSandboxUnsupportedError
+ ) {
return failed(toErrorMessage(error));
}
return failedFromError(error, definition.name, "tool execution failed");
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash.ts b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
index 8c629d649..c180ce47a 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
@@ -25,6 +25,7 @@ import {
import { createLoggingSandboxSession } from "#execution/sandbox/logging-session.js";
import { buildSandboxSession } from "#execution/sandbox/session.js";
import { createSandboxProviderIdentity } from "#execution/sandbox/provider-identity.js";
+import { withToolSessionSandboxes } from "#execution/tool-session/sandbox.js";
import type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
import { resolveSandboxCacheDirectory } from "#internal/application/paths.js";
import type { SandboxSession } from "#shared/sandbox-session.js";
@@ -65,7 +66,9 @@ export function createJustBashSandboxProvider(
version: 2,
};
- return {
+ // `start` reopens the session's root by session id, so keyed tool sessions
+ // can reuse it. The roots are local files, so there is nothing to sweep.
+ const implementation: ReturnType<typeof createJustBashSandboxProvider> = {
async prepare(context) {
const templateIdentity = createSandboxProviderIdentity({
...environmentIdentity,
@@ -145,6 +148,10 @@ export function createJustBashSandboxProvider(
};
},
};
+ // Each handle runs its own interpreter in this process; stopping it keeps the root's files.
+ return withToolSessionSandboxes(implementation, {
+ releaseHandle: (handle) => handle.onSessionStop(),
+ });
}
function sessionRootPath(
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel-errors.ts b/packages/eve/src/execution/sandbox/bindings/vercel-errors.ts
index c12ae8609..1175fb0f9 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel-errors.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel-errors.ts
@@ -2,6 +2,50 @@ export function isVercelSnapshotUnavailableError(error: unknown): boolean {
return errorChainContainsStatus(error, 410);
}
+/**
+ * A resume that found the sandbox's snapshot expired or deleted: 410 with the
+ * `snapshot_not_found` code, rather than any other 410.
+ */
+export function isVercelSnapshotNotFoundError(error: unknown): boolean {
+ for (const candidate of walkErrorChain(error)) {
+ if (readErrorStatus(candidate) !== 410 || !isRecord(candidate)) continue;
+ const body =
+ isRecord(candidate.json) && isRecord(candidate.json.error) ? candidate.json.error : undefined;
+ if (body?.code === "snapshot_not_found") return true;
+ }
+ return false;
+}
+
+/**
+ * A create that lost the race for a sandbox name. The Sandbox API answers a
+ * taken name with 400 `bad_request` "A sandbox with the name '…' already
+ * exists"; 409 is accepted too in case it moves to a proper Conflict.
+ */
+export function isVercelSandboxNameConflictError(error: unknown): boolean {
+ for (const candidate of walkErrorChain(error)) {
+ const status = readErrorStatus(candidate);
+ if (status === 409) return true;
+ if (
+ status === 400 &&
+ /\bsandbox with the name\b.*\balready exists\b/is.test(readErrorText(candidate))
+ ) {
+ return true;
+ }
+ }
+ return false;
+}
+
+// The API error's message, falling back to its parsed JSON body.
+function readErrorText(value: unknown): string {
+ if (!isRecord(value)) return "";
+ const parts: string[] = [];
+ if (typeof value.message === "string") parts.push(value.message);
+ if (typeof value.text === "string") parts.push(value.text);
+ const body = isRecord(value.json) && isRecord(value.json.error) ? value.json.error : undefined;
+ if (body !== undefined && typeof body.message === "string") parts.push(body.message);
+ return parts.join("\n");
+}
+
export function isVercelSandboxMissingError(error: unknown): boolean {
return errorChainContainsStatus(error, 404);
}
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel-tool-sessions.ts b/packages/eve/src/execution/sandbox/bindings/vercel-tool-sessions.ts
new file mode 100644
index 000000000..cadda7b00
--- /dev/null
+++ b/packages/eve/src/execution/sandbox/bindings/vercel-tool-sessions.ts
@@ -0,0 +1,23 @@
+import type { VercelCreateOptions } from "#execution/sandbox/bindings/vercel-sdk-types.js";
+
+/**
+ * How long a tool session's saved filesystem outlives its last use. It is
+ * also the shortest `snapshotExpiration` the Sandbox API accepts.
+ */
+export const VERCEL_TOOL_SESSION_SNAPSHOT_EXPIRATION_MS = 24 * 60 * 60 * 1000;
+
+/*
+ * A tool session has no end to delete its sandbox at, so Vercel expires it:
+ * the sandbox's snapshots expire a day after their last use (each resume
+ * restarts that day), and only the latest is kept. The next call for the key
+ * then finds the snapshot gone and starts a fresh sandbox under the same
+ * name. These options apply when the sandbox is created, so they do not
+ * change its name.
+ */
+export function withToolSessionRetention(options: VercelCreateOptions): VercelCreateOptions {
+ return {
+ ...options,
+ keepLastSnapshots: { count: 1 },
+ snapshotExpiration: VERCEL_TOOL_SESSION_SNAPSHOT_EXPIRATION_MS,
+ };
+}
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts b/packages/eve/src/execution/sandbox/bindings/vercel.test.ts
index f8b2afd05..088f20b37 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel.test.ts
@@ -495,6 +495,175 @@ describe("createVercelSandbox", () => {
);
});
+ describe("tool sessions", () => {
+ const DAY_MS = 24 * 60 * 60 * 1000;
+ // What the Sandbox API answers a resume whose snapshot expired or was deleted.
+ const snapshotNotFound = () =>
+ Object.assign(new Error("Cannot resume sandbox: no snapshot available."), {
+ json: { error: { code: "snapshot_not_found" } },
+ response: { status: 410 },
+ });
+ const nameTaken = () =>
+ Object.assign(new Error("A sandbox with the name already exists"), {
+ response: { status: 400 },
+ });
+
+ /*
+ * A Vercel project over `sandboxes`, by name. `create` fails for a name
+ * that is taken, as the API does, so a test can let another instance win
+ * a name before this one's create lands.
+ */
+ function project(sandboxes: Map<string, ReturnType<typeof createMockSandbox>>) {
+ const sandboxModule = {
+ Sandbox: {
+ create: vi.fn(async (options: { name: string }) => {
+ if (sandboxes.has(options.name)) throw nameTaken();
+ const created = createMockSandbox({ name: options.name });
+ sandboxes.set(options.name, created);
+ return created;
+ }),
+ get: vi.fn(async (options: { name: string }) => sandboxes.get(options.name) ?? null),
+ },
+ };
+ const provider = createTestVercelSandbox({
+ loadDeleteSandboxModule: async () => sandboxModule as never,
+ loadSandboxModule: async () => sandboxModule as never,
+ });
+ const open = async (sessionId = "tool_session_abc") =>
+ await provider.openSession({
+ appRoot: "/tmp/test-app-root",
+ prepared: { snapshotId: "prepared-snapshot" },
+ sandboxName: sessionId,
+ });
+ return { open, sandboxModule };
+ }
+
+ function expiredSandbox(
+ sandboxes: Map<string, ReturnType<typeof createMockSandbox>>,
+ name: string,
+ ) {
+ const sandbox = createMockSandbox({ name, status: "stopped" });
+ sandbox.runCommand.mockRejectedValue(snapshotNotFound());
+ sandbox.delete.mockImplementation(async () => {
+ sandboxes.delete(name);
+ });
+ sandboxes.set(name, sandbox);
+ return sandbox;
+ }
+
+ async function baseName() {
+ const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();
+ await project(sandboxes).open();
+ return [...sandboxes.keys()][0]!;
+ }
+
+ it("expires a tool session's snapshots a day after last use and keeps only the latest", async () => {
+ const { open, sandboxModule } = project(new Map());
+ await open();
+ expect(sandboxModule.Sandbox.create).toHaveBeenCalledWith(
+ expect.objectContaining({ keepLastSnapshots: { count: 1 }, snapshotExpiration: DAY_MS }),
+ );
+ });
+
+ it("leaves a conversation session's snapshot retention to the author", async () => {
+ const { open, sandboxModule } = project(new Map());
+ await open("session-key");
+ const params = sandboxModule.Sandbox.create.mock.calls[0]?.[0];
+ expect(params).not.toHaveProperty("keepLastSnapshots");
+ expect(params).not.toHaveProperty("snapshotExpiration");
+ });
+
+ it("resumes a stopped sandbox whose snapshot is still there, keeping it", async () => {
+ const base = await baseName();
+ const stopped = createMockSandbox({ name: base, status: "stopped" });
+ const { open, sandboxModule } = project(new Map([[base, stopped]]));
+
+ await open();
+
+ expect(stopped.runCommand).toHaveBeenCalled();
+ expect(stopped.delete).not.toHaveBeenCalled();
+ expect(sandboxModule.Sandbox.create).not.toHaveBeenCalled();
+ });
+
+ it("starts a fresh sandbox under the same name once the snapshot expired", async () => {
+ const base = await baseName();
+ const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();
+ const expired = expiredSandbox(sandboxes, base);
+ const { open, sandboxModule } = project(sandboxes);
+
+ await open();
+
+ expect(expired.delete).toHaveBeenCalledTimes(1);
+ expect(sandboxModule.Sandbox.create).toHaveBeenCalledTimes(1);
+ expect(sandboxModule.Sandbox.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ name: base,
+ snapshotExpiration: DAY_MS,
+ source: { snapshotId: "prepared-snapshot", type: "snapshot" },
+ }),
+ );
+ expect(sandboxes.get(base)?.runCommand).toHaveBeenCalled();
+ });
+
+ it("adopts the fresh sandbox another instance made first after the same expiry", async () => {
+ const base = await baseName();
+ const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();
+ const expired = expiredSandbox(sandboxes, base);
+ const { open, sandboxModule } = project(sandboxes);
+ // Another instance recreates the name after this one finds it free
+ // and before its create lands.
+ const theirs = createMockSandbox({ name: base });
+ const get = sandboxModule.Sandbox.get.getMockImplementation()!;
+ sandboxModule.Sandbox.get.mockImplementation(async (options) => {
+ const found = await get(options);
+ if (found === null && !sandboxes.has(base)) sandboxes.set(base, theirs);
+ return found;
+ });
+
+ await open();
+
+ expect(sandboxModule.Sandbox.create).toHaveBeenCalledTimes(1);
+ await expect(sandboxModule.Sandbox.create.mock.results[0]!.value).rejects.toThrow(
+ "already exists",
+ );
+ expect(expired.delete).toHaveBeenCalledTimes(1);
+ expect(theirs.runCommand).toHaveBeenCalled();
+ expect(theirs.delete).not.toHaveBeenCalled();
+ });
+
+ it("starts fresh when another instance already deleted the expired sandbox", async () => {
+ const base = await baseName();
+ const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();
+ expiredSandbox(sandboxes, base);
+ const { open, sandboxModule } = project(sandboxes);
+ const get = sandboxModule.Sandbox.get.getMockImplementation()!;
+ sandboxModule.Sandbox.get.mockImplementationOnce(get).mockImplementationOnce(async () => {
+ sandboxes.delete(base);
+ throw Object.assign(new Error("Sandbox not found"), { response: { status: 404 } });
+ });
+
+ await open();
+
+ expect(sandboxModule.Sandbox.create).toHaveBeenCalledWith(
+ expect.objectContaining({ name: base }),
+ );
+ expect(sandboxes.get(base)?.runCommand).toHaveBeenCalled();
+ });
+
+ it("surfaces any other 410 instead of replacing the sandbox", async () => {
+ const base = await baseName();
+ const gone = createMockSandbox({ name: base, status: "stopped" });
+ gone.runCommand.mockRejectedValue(
+ Object.assign(new Error("Session is gone"), { response: { status: 410 } }),
+ );
+ const { open, sandboxModule } = project(new Map([[base, gone]]));
+
+ await expect(open()).rejects.toThrow();
+ expect(sandboxModule.Sandbox.create).not.toHaveBeenCalled();
+ expect(gone.delete).not.toHaveBeenCalled();
+ });
+ });
+
it("forwards author source to template create as the base layer", async () => {
/*
* The real Vercel SDK pre-populates `currentSnapshotId` on a
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.ts b/packages/eve/src/execution/sandbox/bindings/vercel.ts
index 52d89afa6..83fd6fabb 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel.ts
@@ -50,8 +50,13 @@ import {
} from "#execution/sandbox/bindings/vercel-options.js";
import {
isVercelSandboxMissingError,
+ isVercelSandboxNameConflictError,
+ isVercelSnapshotNotFoundError,
isVercelSnapshotUnavailableError,
} from "#execution/sandbox/bindings/vercel-errors.js";
+import { withToolSessionRetention } from "#execution/sandbox/bindings/vercel-tool-sessions.js";
+import { isToolSessionId } from "#execution/tool-session/id.js";
+import { withToolSessionSandboxes } from "#execution/tool-session/sandbox.js";
import { getNamedVercelSandbox } from "#execution/sandbox/bindings/vercel-lookup.js";
import {
deleteUnusableVercelSandbox,
@@ -127,7 +132,11 @@ export function createVercelSandbox(
) {
const artifact = requirePreparedVercelTemplate(artifactValue);
const { mounts, ...runtimeOptions } = options ?? {};
- const sessionCreateOptions = { ...createOptions, ...runtimeOptions };
+ const toolSession = isToolSessionId(context.session.id);
+ const authoredCreateOptions = { ...createOptions, ...runtimeOptions };
+ const sessionCreateOptions = toolSession
+ ? withToolSessionRetention(authoredCreateOptions)
+ : authoredCreateOptions;
const tags = resolveVercelSandboxTags(sessionCreateOptions.tags, {
sessionId: context.session.id,
});
@@ -145,6 +154,8 @@ export function createVercelSandbox(
try {
session = await ensureSession(ensureSessionInput);
session = await ensureUsableSession({
+ // Only an expired snapshot gives a tool session a fresh sandbox.
+ expired: toolSession ? isVercelSnapshotNotFoundError : isVercelSnapshotUnavailableError,
input: ensureSessionInput,
loadDeleteSandboxModule,
session,
@@ -193,7 +204,7 @@ export function createVercelSandbox(
return handle;
}
- return {
+ const implementation: ReturnType<typeof createVercelSandbox> = {
async prepare(context) {
const seedFiles = providerResourceTargetFiles(context.resources);
if (
@@ -253,6 +264,9 @@ export function createVercelSandbox(
};
},
};
+ // `start` finds a session's sandbox by name, so keyed tool sessions can reuse it.
+ // A handle is only an SDK client, so a call that ends has nothing to free.
+ return withToolSessionSandboxes(implementation);
}
interface VercelSandboxTemplateRecord {
@@ -446,6 +460,7 @@ interface VercelSandboxSessionCreateResult {
}
async function ensureUsableSession(input: {
+ readonly expired: (error: unknown) => boolean;
readonly input: EnsureSessionInput;
readonly loadDeleteSandboxModule: () => Promise<VercelModule>;
readonly session: VercelSandboxSessionCreateResult;
@@ -454,16 +469,21 @@ async function ensureUsableSession(input: {
await ensureVercelSandboxBaseRuntime(input.session.sandbox);
return input.session;
} catch (error) {
- if (input.session.created || !isVercelSnapshotUnavailableError(error)) {
+ if (input.session.created || !input.expired(error)) {
throw error;
}
}
- await deleteUnusableVercelSandbox({
- createOptions: input.input.createOptions,
- loadDeleteSandboxModule: input.loadDeleteSandboxModule,
- sandbox: input.session.sandbox,
- });
+ try {
+ await deleteUnusableVercelSandbox({
+ createOptions: input.input.createOptions,
+ loadDeleteSandboxModule: input.loadDeleteSandboxModule,
+ sandbox: input.session.sandbox,
+ });
+ } catch (error) {
+ // Another instance that saw the same expiry deleted it first.
+ if (!isVercelSandboxMissingError(error)) throw error;
+ }
const replacement = await ensureSession(input.input);
await ensureVercelSandboxBaseRuntime(replacement.sandbox);
return replacement;
@@ -488,13 +508,21 @@ async function ensureSession(input: EnsureSessionInput): Promise<VercelSandboxSe
createParams.tags = input.tags;
}
- return {
- created: true,
- sandbox: await input.createSandbox({
- createOptions: createParams,
- sandboxModule: input.sandboxModule,
- }),
- };
+ try {
+ return {
+ created: true,
+ sandbox: await input.createSandbox({
+ createOptions: createParams,
+ sandboxModule: input.sandboxModule,
+ }),
+ };
+ } catch (error) {
+ // Lookup-then-create is not atomic: another instance created the name first.
+ if (!isVercelSandboxNameConflictError(error)) throw error;
+ const winner = await getNamedVercelSandbox({ ...input, sandboxName });
+ if (winner === null) throw error;
+ return { created: false, sandbox: winner };
+ }
}
function createSessionCreateParams(
diff --git a/packages/eve/src/execution/sandbox/ensure.ts b/packages/eve/src/execution/sandbox/ensure.ts
index 8395d71d6..aacfc91d7 100644
--- a/packages/eve/src/execution/sandbox/ensure.ts
+++ b/packages/eve/src/execution/sandbox/ensure.ts
@@ -35,12 +35,25 @@ import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-err
interface EnsureSandboxAccessInput {
readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
readonly nodeId: string;
+ /** `false` when the sandbox outlives this access: it may not delete it, even after a failed start. */
readonly ownsSandbox?: boolean;
readonly registry: RuntimeSandboxRegistry;
readonly sessionId: string;
readonly state: SandboxState | null;
}
+/** The access `ensureSandboxAccess` builds, with what the opener may do beyond the sandbox API. */
+export interface EnsuredSandboxAccess extends SandboxAccess {
+ /**
+ * Lets go of the handle this access opened, if any, without stopping or
+ * deleting the sandbox, and returns it so the caller can free what it
+ * holds in this process. For a sandbox that outlives the access, such as a
+ * tool session's. Waits for an open still in flight, so a caller that
+ * finished early never leaves that handle behind.
+ */
+ detach(): Promise<SandboxProviderHandle | undefined>;
+}
+
interface OpenedSandbox {
readonly handle: SandboxProviderHandle;
readonly providerName: string;
@@ -53,7 +66,9 @@ interface OpenedSandbox {
// state instead.
const pendingSandboxStarts = new Map<string, Promise<SandboxSessionState | null>>();
-export async function ensureSandboxAccess(input: EnsureSandboxAccessInput): Promise<SandboxAccess> {
+export async function ensureSandboxAccess(
+ input: EnsureSandboxAccessInput,
+): Promise<EnsuredSandboxAccess> {
// Sessions saved before the provider redesign (eve 0.64) hold a backend
// record with no `providerName`. No provider can resume it, so treat it as
// no sandbox and let the selector start a fresh one.
@@ -70,6 +85,9 @@ export async function ensureSandboxAccess(input: EnsureSandboxAccessInput): Prom
async captureState() {
return { session: persisted };
},
+ async detach() {
+ return undefined;
+ },
async get() {
return null;
},
@@ -281,7 +299,9 @@ export async function ensureSandboxAccess(input: EnsureSandboxAccessInput): Prom
opened = undefined;
opening = undefined;
persisted = null;
- if (failed !== undefined) {
+ // `start` may have found a sandbox an owner, or another call with the
+ // same tool-session key, is using; only an owning access discards it.
+ if (failed !== undefined && input.ownsSandbox !== false) {
try {
await failed.onSessionDelete();
} catch (cleanupError) {
@@ -337,6 +357,21 @@ export async function ensureSandboxAccess(input: EnsureSandboxAccessInput): Prom
persisted = null;
requiring = undefined;
},
+ async detach() {
+ // A failed open left nothing to let go of.
+ if (requiring !== undefined) await requiring.catch(() => undefined);
+ const current = opened;
+ if (current === undefined) return undefined;
+ untrackActiveSandboxHandle({
+ handle: current.handle,
+ providerName: current.providerName,
+ sessionId: input.sessionId,
+ });
+ opened = undefined;
+ opening = undefined;
+ requiring = undefined;
+ return current.handle;
+ },
async get() {
await requireHandle();
return opened?.sandbox ?? null;
diff --git a/packages/eve/src/execution/tool-session/id.ts b/packages/eve/src/execution/tool-session/id.ts
new file mode 100644
index 000000000..500984933
--- /dev/null
+++ b/packages/eve/src/execution/tool-session/id.ts
@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+
+import { TOOL_SESSION_KEY_MAX_LENGTH } from "#channel/invoke-tool.js";
+import { principalIdentity } from "#channel/principal-identity.js";
+import type { SessionAuthContext } from "#channel/types.js";
+
+/**
+ * Prefix of every keyed tool session id. Sandbox bindings read it to name and
+ * find tool-session sandboxes, since a tool session keeps no record of its own.
+ */
+export const TOOL_SESSION_ID_PREFIX = "tool_session_";
+
+export function isToolSessionId(sessionId: string): boolean {
+ return sessionId.startsWith(TOOL_SESSION_ID_PREFIX);
+}
+
+/** Why a tool session key was refused, or `undefined` when it is usable. */
+export function validateToolSessionKey(key: string): string | undefined {
+ if (key.length === 0) return "The tool session key must not be empty.";
+ if (key.length > TOOL_SESSION_KEY_MAX_LENGTH) {
+ return `The tool session key must be at most ${TOOL_SESSION_KEY_MAX_LENGTH} characters.`;
+ }
+ return undefined;
+}
+
+/**
+ * Derives a keyed tool session id from the caller and the key. Nothing is
+ * stored: every call recomputes the id from its authenticated principal, so
+ * another caller sending the same key reaches a different session. The
+ * caller must not be anonymous; `invokeTool` denies that before calling.
+ * A forwarded caller's id also covers the verified forwarder, so one user
+ * reached through two forwarders gets two sessions.
+ */
+export function deriveToolSessionId(input: {
+ readonly current: SessionAuthContext;
+ readonly forwardedBy?: SessionAuthContext;
+ readonly key: string;
+}): string {
+ const identity: unknown[] = ["eve.tool-session.v1", principalIdentity(input.current), input.key];
+ if (input.forwardedBy !== undefined) identity.push(principalIdentity(input.forwardedBy));
+ const encoded = JSON.stringify(identity);
+ return `${TOOL_SESSION_ID_PREFIX}${createHash("sha256").update(encoded, "utf8").digest("hex")}`;
+}
diff --git a/packages/eve/src/execution/tool-session/sandbox.ts b/packages/eve/src/execution/tool-session/sandbox.ts
new file mode 100644
index 000000000..5b90ae96c
--- /dev/null
+++ b/packages/eve/src/execution/tool-session/sandbox.ts
@@ -0,0 +1,69 @@
+import type { RuntimeSandboxRegistry } from "#runtime/sandbox/registry.js";
+import { getSandboxEnvironmentRuntime } from "#shared/sandbox-environment.js";
+import type { SandboxProviderHandle, SandboxProviderRuntime } from "#shared/sandbox-provider.js";
+
+/*
+ * Keyed tool sessions reuse a provider's own `start`, which must find the
+ * session's sandbox again from the session id alone. Only eve's bindings that
+ * do so opt in, and the marker stays internal so the public provider API is
+ * unchanged.
+ */
+
+/** What a binding that keeps tool-session sandboxes tells the calls that use them. */
+export interface ToolSessionSandboxSupport {
+ /**
+ * Frees what a call's handle holds in this process once the call ends,
+ * leaving the session's sandbox for later and overlapping calls. Absent
+ * when a handle holds nothing of its own, such as a client to a remote
+ * sandbox.
+ */
+ releaseHandle?(handle: SandboxProviderHandle): Promise<void>;
+}
+
+const supported = new WeakMap<object, ToolSessionSandboxSupport>();
+
+/** Marks a binding whose `start` reopens a session's sandbox by session id. */
+export function withToolSessionSandboxes<Implementation extends object>(
+ implementation: Implementation,
+ support: ToolSessionSandboxSupport = {},
+): Implementation {
+ supported.set(implementation, support);
+ return implementation;
+}
+
+/** Raised when a keyed tool session opens a sandbox on a provider that cannot keep it. */
+export class ToolSessionSandboxUnsupportedError extends Error {
+ constructor(providerName: string) {
+ super(
+ `Sandbox provider "${providerName}" cannot keep a sandbox between invokeTool calls, ` +
+ "so a call with a key cannot open one. Call without a key for a sandbox that lasts " +
+ "one call, or use Vercel Sandbox or just-bash.",
+ );
+ this.name = "ToolSessionSandboxUnsupportedError";
+ }
+}
+
+/** Throws unless the registry's sandbox provider can keep tool-session sandboxes. */
+export function assertToolSessionSandboxSupport(registry: RuntimeSandboxRegistry): void {
+ const provider = registeredProvider(registry);
+ if (provider !== undefined && !supported.has(provider.implementation)) {
+ throw new ToolSessionSandboxUnsupportedError(provider.providerName);
+ }
+}
+
+/** Frees what a keyed call's handle holds in this process; the sandbox itself stays. */
+export async function releaseToolSessionHandle(
+ registry: RuntimeSandboxRegistry,
+ handle: SandboxProviderHandle,
+): Promise<void> {
+ const provider = registeredProvider(registry);
+ if (provider === undefined) return;
+ await supported.get(provider.implementation)?.releaseHandle?.(handle);
+}
+
+function registeredProvider(registry: RuntimeSandboxRegistry): SandboxProviderRuntime | undefined {
+ const registered = registry.sandbox;
+ const definition = registered?.inheritance?.definition ?? registered?.definition;
+ if (definition?.kind !== "independent") return undefined;
+ return getSandboxEnvironmentRuntime(definition.environment);
+}
diff --git a/packages/eve/src/internal/invocation/metadata.ts b/packages/eve/src/internal/invocation/metadata.ts
index 4c1814cdb..1ae38c482 100644
--- a/packages/eve/src/internal/invocation/metadata.ts
+++ b/packages/eve/src/internal/invocation/metadata.ts
@@ -1,5 +1,6 @@
import { createHash } from "node:crypto";
+import { principalIdentity } from "#channel/principal-identity.js";
import type { RunInput, SessionAuthContext } from "#channel/types.js";
import {
INVOCATION_OWNER_ATTRIBUTE,
@@ -19,16 +20,7 @@ export function invocationInputRequestId(pendingBatchId: string, requestId: stri
/** Fixed-width fingerprint used to bind an invocation to its initiating principal. */
export function invocationOwnerKey(auth: SessionAuthContext | null): string {
- const identity =
- auth === null
- ? ["anonymous"]
- : [
- auth.authenticator,
- auth.issuer ?? "",
- auth.principalType,
- auth.principalId,
- auth.subject ?? "",
- ];
+ const identity = auth === null ? ["anonymous"] : principalIdentity(auth);
return createHash("sha256").update(JSON.stringify(identity), "utf8").digest("hex");
}
diff --git a/packages/eve/src/internal/mcp/forwarded-principal-header.ts b/packages/eve/src/internal/mcp/forwarded-principal-header.ts
index a77025f49..5869dc1ec 100644
--- a/packages/eve/src/internal/mcp/forwarded-principal-header.ts
+++ b/packages/eve/src/internal/mcp/forwarded-principal-header.ts
@@ -19,6 +19,8 @@ export interface McpRequestPrincipals {
readonly current: SessionAuthContext;
/** The accepted forwarded initiator, or `current` when none was forwarded. */
readonly initiator: SessionAuthContext;
+ /** The verified route principal that forwarded `current`, when one did. */
+ readonly forwarder?: SessionAuthContext;
}
/**
@@ -55,7 +57,7 @@ export async function resolveMcpRequestPrincipals(
if (resolved instanceof Response) return resolved;
if (!resolved.accepted) return { current: routePrincipal, initiator: routePrincipal };
// resolveForwardedPrincipal already stamped both with `eve:forwarded-by`.
- return { current: resolved.auth, initiator: resolved.initiatorAuth };
+ return { current: resolved.auth, forwarder: routePrincipal, initiator: resolved.initiatorAuth };
}
/**
diff --git a/packages/eve/src/internal/mcp/published-tools.ts b/packages/eve/src/internal/mcp/published-tools.ts
index f19e4f763..f061742c9 100644
--- a/packages/eve/src/internal/mcp/published-tools.ts
+++ b/packages/eve/src/internal/mcp/published-tools.ts
@@ -9,8 +9,15 @@ import {
McpToolOperationError,
type McpCallToolResult,
type McpServerTool,
+ type McpToolCallContext,
} from "#internal/mcp/streamable-http-server.js";
import { isJsonObjectValue, type JsonValue } from "#shared/json.js";
+import { isObject } from "#shared/guards.js";
+
+/** Extension a client declares to join tool sessions with `_meta["dev.eve/tool-session"]`. */
+export const MCP_TOOL_SESSIONS_EXTENSION = "dev.eve/tool-sessions";
+/** `_meta` key carrying a `tools/call`'s tool session key. */
+export const MCP_TOOL_SESSION_META_KEY = "dev.eve/tool-session";
const log = createLogger("mcp.tools");
const warnedReserved = new Set<string>();
@@ -47,12 +54,17 @@ export function createPublishedTools(input: {
outputSchema:
tool.outputSchema === undefined ? undefined : fromJsonSchema(tool.outputSchema),
},
- async call(value, { signal }) {
- const { current, initiator } = input.principals;
+ async call(value, context) {
+ const { current, forwarder, initiator } = input.principals;
+ const key = toolSessionKey(context);
const result = await input.invokeTool(tool.name, value, {
auth: current,
+ // The verified forwarder scopes a keyed session, so two routers
+ // that name the same user do not share a sandbox.
+ forwardedBy: forwarder,
initiator,
- signal,
+ key,
+ signal: context.signal,
});
return toCallToolResult(tool.name, result, tool.outputSchema !== undefined);
},
@@ -60,6 +72,26 @@ export function createPublishedTools(input: {
);
}
+/**
+ * The call's tool session key. It is honoured only from a client that
+ * declared the extension in this request's capabilities; any other client,
+ * including every 2025-era client, gets a one-off session whatever its
+ * `_meta` carries. `invokeTool` checks the key's length.
+ */
+function toolSessionKey(context: McpToolCallContext): string | undefined {
+ const declared = context.clientCapabilities;
+ const extensions = isObject(declared) ? declared.extensions : undefined;
+ if (!isObject(extensions) || !isObject(extensions[MCP_TOOL_SESSIONS_EXTENSION])) {
+ return undefined;
+ }
+ const key = context.meta?.[MCP_TOOL_SESSION_META_KEY];
+ if (key === undefined || typeof key === "string") return key;
+ throw new McpToolOperationError(
+ "invalid_input",
+ `_meta["${MCP_TOOL_SESSION_META_KEY}"] must be a string.`,
+ );
+}
+
function toCallToolResult(
name: string,
result: InvokeToolResult,
diff --git a/packages/eve/src/internal/mcp/streamable-http-server.ts b/packages/eve/src/internal/mcp/streamable-http-server.ts
index 76b2a163b..3b8c4124c 100644
--- a/packages/eve/src/internal/mcp/streamable-http-server.ts
+++ b/packages/eve/src/internal/mcp/streamable-http-server.ts
@@ -106,6 +106,19 @@ export class McpToolOperationError extends Error {
/** Only `conflict` is retryable: the caller re-reads state and tries again. */
const RETRYABLE_CODES: ReadonlySet<McpToolOperationErrorCode> = new Set(["conflict"]);
+/** What a tool handler sees of one `tools/call`. */
+export interface McpToolCallContext {
+ readonly auth: SessionAuthContext | null;
+ /**
+ * The capabilities a 2026-07-28 request declared in its envelope. 2025-era
+ * requests declare none per request, so they get `undefined`.
+ */
+ readonly clientCapabilities: unknown;
+ /** The request's `_meta`, without the reserved `io.modelcontextprotocol/*` keys. */
+ readonly meta: Readonly<Record<string, unknown>> | undefined;
+ readonly signal: AbortSignal;
+}
+
export interface McpServerTool {
readonly name: string;
register(server: McpServer, auth: SessionAuthContext | null): void;
@@ -133,7 +146,7 @@ export function defineMcpTool<
readonly definition: McpToolDefinition<TInputSchema>;
call(
value: InferSchemaOutput<TInputSchema>,
- context: { readonly auth: SessionAuthContext | null; readonly signal: AbortSignal },
+ context: McpToolCallContext,
): Promise<McpCallToolResult<TStructured>>;
}): McpServerTool {
return {
@@ -162,12 +175,12 @@ export function defineMcpTool<
retryable: false,
});
}
- return await callTool(
- input.call,
- checked.value as InferSchemaOutput<TInputSchema>,
- context.mcpReq.signal,
+ return await callTool(input.call, checked.value as InferSchemaOutput<TInputSchema>, {
auth,
- );
+ clientCapabilities: declaredClientCapabilities(context.mcpReq.envelope),
+ meta: context.mcpReq._meta,
+ signal: context.mcpReq.signal,
+ });
},
);
},
@@ -453,17 +466,23 @@ function createServer(
return server;
}
+/** The envelope's client capabilities, when the request is 2026-07-28's. */
+function declaredClientCapabilities(
+ envelope: Readonly<Record<string, unknown>> | undefined,
+): unknown {
+ if (envelope?.["io.modelcontextprotocol/protocolVersion"] !== MCP_PROTOCOL_VERSION) {
+ return undefined;
+ }
+ return envelope["io.modelcontextprotocol/clientCapabilities"];
+}
+
async function callTool<TInput, TStructured>(
- call: (
- input: TInput,
- context: { readonly auth: SessionAuthContext | null; readonly signal: AbortSignal },
- ) => Promise<McpCallToolResult<TStructured>>,
+ call: (input: TInput, context: McpToolCallContext) => Promise<McpCallToolResult<TStructured>>,
input: TInput,
- signal: AbortSignal,
- auth: SessionAuthContext | null,
+ context: McpToolCallContext,
): Promise<McpCallToolResult<TStructured>> {
try {
- return await call(input, { auth, signal });
+ return await call(input, context);
} catch (error) {
if (error instanceof McpToolOperationError) {
return toolError({
diff --git a/packages/eve/src/public/channels/mcp.test.ts b/packages/eve/src/public/channels/mcp.test.ts
index 8f5067d94..513b5f08b 100644
--- a/packages/eve/src/public/channels/mcp.test.ts
+++ b/packages/eve/src/public/channels/mcp.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from "vitest";
+import { deriveToolSessionId } from "#execution/tool-session/id.js";
import type { AgentDescription, AgentToolDescription } from "#channel/agent-description.js";
import type { InvokeToolFn, InvokeToolResult } from "#channel/invoke-tool.js";
import type { SessionAuthContext } from "#channel/types.js";
@@ -646,7 +647,18 @@ describe("mcpChannel tools", () => {
],
["note", completed("saved", "Saved."), { content: [{ text: "Saved.", type: "text" }] }],
["note", { message: "Bad id.", status: "invalid-input" }, { code: "invalid_input" }],
- ["note", { reason: "Not today.", status: "denied" }, { code: "denied" }],
+ // The reason reaches the client verbatim, so an anonymous caller denied a
+ // tool session key learns why from `invokeTool`'s own message.
+ [
+ "note",
+ { reason: "Not today.", status: "denied" },
+ { code: "denied", message: "Not today." },
+ ],
+ [
+ "note",
+ { status: "denied" },
+ { code: "denied", message: expect.stringContaining("approval") },
+ ],
["note", { status: "approval-required" }, { code: "approval_required" }],
[
"note",
@@ -758,10 +770,12 @@ describe("mcpChannel tools", () => {
}
expect(response.status, label).toBe(200);
const [auth, initiator] = expected as Ran;
+ // An accepted header records the verified route principal as the forwarder.
expect(invokeTool.mock.calls[0]![2], label).toEqual({
auth,
initiator,
signal: expect.any(AbortSignal),
+ forwardedBy: auth === principal ? undefined : principal,
});
}
@@ -772,6 +786,169 @@ describe("mcpChannel tools", () => {
expect(createSession.mock.calls[0]![0]).toMatchObject({ auth: principal });
});
+ it("advertises tool sessions and honours a key only from clients that declare them", async () => {
+ const channel = mcpChannel({ auth: () => principal, skills: true, tools: true });
+ const post = channel.routes[1]!;
+ if (post.transport === "websocket") throw new Error("expected HTTP route");
+ const invokeTool = vi.fn<InvokeToolFn>(async () => ({
+ modelOutput: { type: "text", value: "Saved." },
+ output: "saved",
+ status: "completed",
+ }));
+ const files: SkillFileSource = {
+ listDirectories: async () => [],
+ listFiles: async () => [],
+ readFile: async () => new Uint8Array(),
+ };
+ const args = attachSkillFileSource(
+ routeArgs(vi.fn(), {
+ describe: async () => ({ name: "compiled-agent", skills: [], tools: [note] }),
+ invokeTool,
+ }),
+ files,
+ );
+ const modern = (method: string, params: object, capabilities: object) => {
+ const headers: Record<string, string> = {
+ "mcp-method": method,
+ "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+ };
+ if (method === "tools/call") headers["mcp-name"] = "note";
+ return mcpRequest(
+ {
+ id: 1,
+ jsonrpc: "2.0",
+ method,
+ params: {
+ ...params,
+ _meta: {
+ ...(params as { _meta?: object })._meta,
+ "io.modelcontextprotocol/clientCapabilities": capabilities,
+ "io.modelcontextprotocol/clientInfo": { name: "test-client", version: "0.0.0" },
+ "io.modelcontextprotocol/protocolVersion": MCP_PROTOCOL_VERSION,
+ },
+ },
+ },
+ headers,
+ );
+ };
+
+ const discovered = (await jsonRpcResponse(
+ await post.handler(modern("server/discover", {}, {}), args),
+ )) as { result: { capabilities: Record<string, unknown> } };
+ // Tool sessions and skills both advertise under `extensions`; neither replaces the other.
+ expect(discovered.result.capabilities.extensions).toEqual({
+ "dev.eve/tool-sessions": {},
+ "io.modelcontextprotocol/skills": { directoryRead: true },
+ });
+
+ const declared = { extensions: { "dev.eve/tool-sessions": {} } };
+ const call = { _meta: { "dev.eve/tool-session": "desk" }, arguments: {}, name: "note" };
+ const rows: Array<[string, Request, string | undefined]> = [
+ ["declaring client", modern("tools/call", call, declared), "desk"],
+ ["undeclaring client", modern("tools/call", call, {}), undefined],
+ [
+ "2025-era client",
+ mcpRequest({
+ id: 1,
+ jsonrpc: "2.0",
+ method: "tools/call",
+ params: {
+ ...call,
+ _meta: { ...call._meta, "io.modelcontextprotocol/clientCapabilities": declared },
+ },
+ }),
+ undefined,
+ ],
+ ];
+ for (const [client, request, key] of rows) {
+ invokeTool.mockClear();
+ await post.handler(request, args);
+ expect(invokeTool, client).toHaveBeenCalledOnce();
+ expect(invokeTool.mock.calls[0]![2].key, client).toBe(key);
+ }
+ });
+
+ it("scopes a forwarded tool session to the verified router, whatever the header claims", async () => {
+ const router = (principalId: string): SessionAuthContext => ({
+ ...principal,
+ principalId,
+ principalType: "service",
+ });
+ const routers = { a: router("router-a"), b: router("router-b") };
+ const channel = mcpChannel({
+ auth: (request) => routers[request.headers.get("x-router") as "a" | "b"],
+ tools: true,
+ trustedForwarders: () => true,
+ });
+ const post = channel.routes[1]!;
+ if (post.transport === "websocket") throw new Error("expected HTTP route");
+ const invokeTool = vi.fn<InvokeToolFn>(async () => ({
+ modelOutput: { type: "text", value: "ok" },
+ output: "ok",
+ status: "completed",
+ }));
+ const args = routeArgs(vi.fn(), {
+ describe: async () => ({ name: "compiled-agent", skills: [], tools: [note] }),
+ invokeTool,
+ });
+ const alice: SessionAuthContext = {
+ // The asserted user claims router-b; only the route principal counts.
+ attributes: { "eve:forwarded-by": "router-b" },
+ authenticator: "oidc",
+ principalId: "alice",
+ principalType: "user",
+ };
+ const call = (via: "a" | "b") =>
+ post.handler(
+ mcpRequest(
+ {
+ id: 1,
+ jsonrpc: "2.0",
+ method: "tools/call",
+ params: {
+ _meta: {
+ "dev.eve/tool-session": "desk",
+ "io.modelcontextprotocol/clientCapabilities": {
+ extensions: { "dev.eve/tool-sessions": {} },
+ },
+ "io.modelcontextprotocol/clientInfo": { name: "router", version: "0.0.0" },
+ "io.modelcontextprotocol/protocolVersion": MCP_PROTOCOL_VERSION,
+ },
+ arguments: {},
+ name: "note",
+ },
+ },
+ {
+ "eve-forwarded-principal": Buffer.from(JSON.stringify({ current: alice })).toString(
+ "base64url",
+ ),
+ "mcp-method": "tools/call",
+ "mcp-name": "note",
+ "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+ "x-router": via,
+ },
+ ),
+ args,
+ );
+
+ await call("a");
+ await call("b");
+ const [viaA, viaB] = invokeTool.mock.calls.map((call) => call[2]);
+ expect(viaA).toMatchObject({
+ auth: { principalId: "alice" },
+ forwardedBy: routers.a,
+ key: "desk",
+ });
+ expect(viaB).toMatchObject({
+ auth: { principalId: "alice" },
+ forwardedBy: routers.b,
+ key: "desk",
+ });
+ expect(deriveToolSessionId({ ...viaA!, current: viaA!.auth, key: "desk" })).not.toBe(
+ deriveToolSessionId({ ...viaB!, current: viaB!.auth, key: "desk" }),
+ );
+ });
+
it("checks arguments against the tool's JSON schema before invoking it", async () => {
const invokeTool = vi.fn<InvokeToolFn>();
const rpc = serve({ tools: true }, invokeTool);
diff --git a/packages/eve/src/public/channels/mcp.ts b/packages/eve/src/public/channels/mcp.ts
index b42ee6aea..856b563ef 100644
--- a/packages/eve/src/public/channels/mcp.ts
+++ b/packages/eve/src/public/channels/mcp.ts
@@ -16,7 +16,10 @@ import type {
} from "#internal/invocation/agent-invocation.js";
import { WorkflowAgentInvocationExecution } from "#internal/invocation/workflow-execution.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
-import { createPublishedTools } from "#internal/mcp/published-tools.js";
+import {
+ createPublishedTools,
+ MCP_TOOL_SESSIONS_EXTENSION,
+} from "#internal/mcp/published-tools.js";
import {
resolveMcpRequestPrincipals,
type McpRequestPrincipals,
@@ -65,7 +68,9 @@ export interface McpChannelInput {
/**
* Also publish the agent's invocable tools, each `tools/call` running the
* tool as the route-authenticated caller. While `agent` is on, an agent
- * tool named like an `agent_*` tool is not published.
+ * tool named like an `agent_*` tool is not published. Also advertises the
+ * `dev.eve/tool-sessions` extension: a client that declares it joins a tool
+ * session by sending `_meta["dev.eve/tool-session"]` on `tools/call`.
* @default false
*/
readonly tools?: boolean;
@@ -437,6 +442,13 @@ async function handleMcpRequest(
})
: [];
const features: McpServerFeature[] = [];
+ if (publish.tools) {
+ // Advertised only; published tools read the key from each call's `_meta`.
+ features.push({
+ capabilities: { extensions: { [MCP_TOOL_SESSIONS_EXTENSION]: {} } },
+ register() {},
+ });
+ }
if (publish.skills && described !== undefined) {
const files = readSkillFileSource(args);
if (files === undefined) {
diff --git a/packages/eve/src/tracing/invoke-tool-span.ts b/packages/eve/src/tracing/invoke-tool-span.ts
index 459b120fc..c91677510 100644
--- a/packages/eve/src/tracing/invoke-tool-span.ts
+++ b/packages/eve/src/tracing/invoke-tool-span.ts
@@ -70,6 +70,7 @@ export async function withInvokeToolSpan(
readonly auth: SessionAuthContext;
readonly callId: string;
readonly origin: InvokeToolTraceOrigin | undefined;
+ /** The call's own run id, never a tool session's: traces see each call as one run. */
readonly sessionId: string;
readonly toolName: string;
},