Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): cancellation - propagate turn abort signals through the harness (#494)

Andrew Barbac233a6adbbb6
diff --git a/.changeset/turn-cancellation-harness-abort.md b/.changeset/turn-cancellation-harness-abort.md
new file mode 100644
index 000000000..fbfce76d4
--- /dev/null
+++ b/.changeset/turn-cancellation-harness-abort.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+The turn harness now propagates a cooperative `AbortSignal` end to end: model calls, retries, recovery, compaction, and tool executions all honor it, and an aborted turn settles with a canonical `TurnCancelledError` that is never retried or misclassified as a failure. Authored tools receive the signal as `ctx.abortSignal` (and via the AI SDK execute options), and framework tools forward it into sandbox commands, file I/O, `web_fetch`, and MCP/OpenAPI connection calls. This is the lowest layer of turn cancellation — no trigger exists yet, so runtime behavior is unchanged until the cancellation API ships.
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
index 1a2782af5..ba48b2d66 100644
--- a/docs/tools/overview.mdx
+++ b/docs/tools/overview.mdx
@@ -37,6 +37,7 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or
`execute` gets a `ctx` carrying the runtime accessors:
- `ctx.session`: session metadata, turn, auth, parent lineage.
+- `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
- `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
- `ctx.getSkill(id)`: read a packaged [skill](/docs/skills)'s metadata and files.
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
new file mode 100644
index 000000000..dbd5582e6
--- /dev/null
+++ b/packages/eve/src/context/build-base-tool-context.integration.test.ts
@@ -0,0 +1,47 @@
+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";
+
+describe("buildBaseToolContext – getSandbox abort binding", () => {
+ it("returns a session bound to the turn abort signal", async () => {
+ let observed: AbortSignal | undefined;
+ const sandbox = mockSandbox({
+ run: (options) => {
+ observed = options.abortSignal;
+ return { exitCode: 0, stderr: "", stdout: "" };
+ },
+ });
+ const runtime = createTestRuntime();
+ const controller = new AbortController();
+
+ await runtime.runAsSession({ sandbox }, async () => {
+ const ctx = buildBaseToolContext(controller.signal);
+ const live = await ctx.getSandbox();
+ await live.run({ command: "echo ready" });
+ });
+
+ expect(observed).toBe(controller.signal);
+ });
+
+ it("binds the inert fallback signal when no turn signal exists", async () => {
+ let observed: AbortSignal | undefined;
+ const sandbox = mockSandbox({
+ run: (options) => {
+ observed = options.abortSignal;
+ return { exitCode: 0, stderr: "", stdout: "" };
+ },
+ });
+ const runtime = createTestRuntime();
+
+ await runtime.runAsSession({ sandbox }, async () => {
+ const ctx = buildBaseToolContext(undefined);
+ const live = await ctx.getSandbox();
+ await live.run({ command: "echo ready" });
+ });
+
+ expect(observed).toBeDefined();
+ expect(observed?.aborted).toBe(false);
+ });
+});
diff --git a/packages/eve/src/context/build-base-tool-context.ts b/packages/eve/src/context/build-base-tool-context.ts
new file mode 100644
index 000000000..a12f63c0d
--- /dev/null
+++ b/packages/eve/src/context/build-base-tool-context.ts
@@ -0,0 +1,20 @@
+import { buildCallbackContext } from "#context/build-callback-context.js";
+import type { SessionContext } from "#public/definitions/callback-context.js";
+import { bindSandboxAbortSignal } from "#execution/sandbox/abort-bound-session.js";
+
+/** Base context shared by tool executors. */
+export type BaseToolContext = SessionContext & {
+ readonly abortSignal: AbortSignal;
+};
+
+/** Builds the base context for one tool execution. */
+export function buildBaseToolContext(abortSignal: AbortSignal | undefined): BaseToolContext {
+ const callbackContext = buildCallbackContext();
+ const signal = abortSignal ?? new AbortController().signal;
+
+ return {
+ ...callbackContext,
+ abortSignal: signal,
+ getSandbox: async () => bindSandboxAbortSignal(await callbackContext.getSandbox(), signal),
+ };
+}
diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.ts
index 865c70e2e..4dbac5bd1 100644
--- a/packages/eve/src/context/build-dynamic-tools.ts
+++ b/packages/eve/src/context/build-dynamic-tools.ts
@@ -8,7 +8,7 @@ import {
LiveStepToolsKey,
} from "#context/keys.js";
import type { DurableDynamicToolMetadata } from "#context/keys.js";
-import { buildCallbackContext } from "#context/build-callback-context.js";
+import { buildBaseToolContext } from "#context/build-base-tool-context.js";
import { createLogger } from "#internal/logging.js";
import type { ApprovalContext, ApprovalStatus } from "#public/definitions/approval.js";
@@ -50,7 +50,8 @@ function replayTools(metadata: readonly DurableDynamicToolMetadata[]): HarnessTo
tools.push({
description: m.description,
- execute: (input: unknown) => stepFn(m.closureVars, input, buildCallbackContext()),
+ execute: (input: unknown, options) =>
+ stepFn(m.closureVars, input, buildBaseToolContext(options?.abortSignal)),
inputSchema: jsonSchema(m.inputSchema),
name: m.name,
approval: buildReplayedApproval(m),
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.ts
index 372340ba3..3ee9e25cd 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts
@@ -12,7 +12,7 @@ import type { ResolvedDynamicToolResolver } from "#runtime/types.js";
import { createLogger } from "#internal/logging.js";
import { normalizeJsonSchemaDefinition } from "#internal/json-schema.js";
import { toErrorMessage } from "#shared/errors.js";
-import { buildCallbackContext } from "#context/build-callback-context.js";
+import { buildBaseToolContext } from "#context/build-base-tool-context.js";
import type { ContextContainer } from "#context/container.js";
import type { ContextKey } from "#context/key.js";
import {
@@ -32,8 +32,8 @@ const log = createLogger("dynamic-tools");
function toHarnessToolDefinition(name: string, entry: DynamicToolEntry): HarnessToolDefinition {
return {
description: entry.description,
- execute: (input: unknown) =>
- entry.execute(input as Record<string, unknown>, buildCallbackContext()),
+ execute: (input: unknown, options) =>
+ entry.execute(input as Record<string, unknown>, buildBaseToolContext(options?.abortSignal)),
inputSchema: convertInputSchema(entry.inputSchema),
name,
approval: entry.approval,
@@ -118,7 +118,8 @@ export function replayDynamicSessionTools(
tools.push({
description: m.description,
- execute: (input: unknown) => stepFn(m.closureVars, input, buildCallbackContext()),
+ execute: (input: unknown, options) =>
+ stepFn(m.closureVars, input, buildBaseToolContext(options?.abortSignal)),
inputSchema: jsonSchema(m.inputSchema),
name: m.name,
outputSchema: m.outputSchema === undefined ? undefined : jsonSchema(m.outputSchema),
diff --git a/packages/eve/src/execution/durable-session-migrations/turn-workflow.ts b/packages/eve/src/execution/durable-session-migrations/turn-workflow.ts
index 347724582..fdca10a6b 100644
--- a/packages/eve/src/execution/durable-session-migrations/turn-workflow.ts
+++ b/packages/eve/src/execution/durable-session-migrations/turn-workflow.ts
@@ -20,6 +20,8 @@ import { turnWorkflowInputV0ToV1 } from "./turn-workflow-v0-to-v1.js";
export const TURN_WORKFLOW_INPUT_VERSION = 1;
export interface TurnStepInput {
+ /** Cancellation signal forwarded into the turn step. */
+ readonly abortSignal?: AbortSignal;
readonly input: HookPayload | undefined;
readonly parentWritable: WritableStream<Uint8Array>;
readonly serializedContext: Record<string, unknown>;
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index e01404122..4082f7f25 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -46,6 +46,8 @@ export type CreateRuntime = (config: {
* Input for building a harness step for one resolved runtime node.
*/
export interface CreateExecutionNodeStepInput {
+ /** Cancellation signal forwarded to the tool-loop harness. */
+ readonly abortSignal?: AbortSignal;
/**
* Session-level capabilities propagated from the runtime. The
* harness passes this through to `buildToolSet` so `ask_question`
@@ -72,6 +74,7 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
const resolveModel = createRuntimeModelResolver(input.modelResolutionScope);
const tools = createNodeHarnessTools({ node: input.node });
return createToolLoopHarness({
+ abortSignal: input.abortSignal,
capabilities: input.capabilities,
workflow: input.node.agent.workflowEnabled === true,
handleEvent: input.handleEvent,
diff --git a/packages/eve/src/execution/sandbox/abort-bound-session.test.ts b/packages/eve/src/execution/sandbox/abort-bound-session.test.ts
new file mode 100644
index 000000000..3823e41f5
--- /dev/null
+++ b/packages/eve/src/execution/sandbox/abort-bound-session.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+ SandboxCommandResult,
+ SandboxProcess,
+ SandboxSession,
+} from "#shared/sandbox-session.js";
+import { bindSandboxAbortSignal } from "#execution/sandbox/abort-bound-session.js";
+
+interface RecordedCall {
+ readonly method: string;
+ readonly abortSignal: AbortSignal | undefined;
+}
+
+function createRecordingSession(calls: RecordedCall[]): SandboxSession {
+ const record = (method: string, abortSignal: AbortSignal | undefined): void => {
+ calls.push({ abortSignal, method });
+ };
+ const commandResult: SandboxCommandResult = { exitCode: 0, stderr: "", stdout: "" };
+
+ return {
+ id: "sbx_recording",
+ resolvePath: (path: string) => `/workspace/${path}`,
+ run: async (options) => {
+ record("run", options.abortSignal);
+ return commandResult;
+ },
+ spawn: (options): Promise<SandboxProcess> => {
+ record("spawn", options.abortSignal);
+ return Promise.reject(new Error("spawn is unused in this test"));
+ },
+ readFile: async (options) => {
+ record("readFile", options.abortSignal);
+ return null;
+ },
+ readBinaryFile: async (options) => {
+ record("readBinaryFile", options.abortSignal);
+ return null;
+ },
+ readTextFile: async (options) => {
+ record("readTextFile", options.abortSignal);
+ return null;
+ },
+ writeFile: async (options) => {
+ record("writeFile", options.abortSignal);
+ },
+ writeBinaryFile: async (options) => {
+ record("writeBinaryFile", options.abortSignal);
+ },
+ writeTextFile: async (options) => {
+ record("writeTextFile", options.abortSignal);
+ },
+ removePath: async (options) => {
+ record("removePath", options.abortSignal);
+ },
+ setNetworkPolicy: async () => {},
+ };
+}
+
+describe("bindSandboxAbortSignal", () => {
+ it("injects the bound signal into every I/O method by default", async () => {
+ const calls: RecordedCall[] = [];
+ const signal = new AbortController().signal;
+ const bound = bindSandboxAbortSignal(createRecordingSession(calls), signal);
+
+ await bound.run({ command: "echo hi" });
+ await expect(bound.spawn({ command: "sleep 1" })).rejects.toThrow("unused");
+ await bound.readFile({ path: "a.txt" });
+ await bound.readBinaryFile({ path: "a.bin" });
+ await bound.readTextFile({ path: "a.txt" });
+ await bound.writeFile({ content: new ReadableStream<Uint8Array>(), path: "a.txt" });
+ await bound.writeBinaryFile({ content: new Uint8Array(), path: "a.bin" });
+ await bound.writeTextFile({ content: "hello", path: "a.txt" });
+ await bound.removePath({ path: "a.txt" });
+
+ expect(calls.map((call) => call.method)).toEqual([
+ "run",
+ "spawn",
+ "readFile",
+ "readBinaryFile",
+ "readTextFile",
+ "writeFile",
+ "writeBinaryFile",
+ "writeTextFile",
+ "removePath",
+ ]);
+ for (const call of calls) {
+ expect(call.abortSignal).toBe(signal);
+ }
+ });
+
+ it("composes a call-level signal with the bound signal instead of replacing it", async () => {
+ const calls: RecordedCall[] = [];
+ const boundController = new AbortController();
+ const bound = bindSandboxAbortSignal(createRecordingSession(calls), boundController.signal);
+
+ const callController = new AbortController();
+ await bound.run({ abortSignal: callController.signal, command: "echo hi" });
+
+ const composed = calls[0]?.abortSignal;
+ expect(composed).toBeDefined();
+ expect(composed).not.toBe(boundController.signal);
+ expect(composed).not.toBe(callController.signal);
+ expect(composed?.aborted).toBe(false);
+
+ callController.abort(new Error("call-level abort"));
+ expect(composed?.aborted).toBe(true);
+
+ await bound.run({ abortSignal: new AbortController().signal, command: "echo again" });
+ const second = calls[1]?.abortSignal;
+ expect(second?.aborted).toBe(false);
+ boundController.abort(new Error("turn cancelled"));
+ expect(second?.aborted).toBe(true);
+ });
+
+ it("passes non-I/O members through unchanged", () => {
+ const calls: RecordedCall[] = [];
+ const session = createRecordingSession(calls);
+ const bound = bindSandboxAbortSignal(session, new AbortController().signal);
+
+ expect(bound.id).toBe("sbx_recording");
+ expect(bound.resolvePath("nested/file.txt")).toBe("/workspace/nested/file.txt");
+ });
+});
diff --git a/packages/eve/src/execution/sandbox/abort-bound-session.ts b/packages/eve/src/execution/sandbox/abort-bound-session.ts
new file mode 100644
index 000000000..ff5c56527
--- /dev/null
+++ b/packages/eve/src/execution/sandbox/abort-bound-session.ts
@@ -0,0 +1,46 @@
+import type {
+ SandboxReadBinaryFileOptions,
+ SandboxReadFileOptions,
+ SandboxReadTextFileOptions,
+ SandboxRemovePathOptions,
+ SandboxRunOptions,
+ SandboxSession,
+ SandboxSpawnOptions,
+ SandboxWriteBinaryFileOptions,
+ SandboxWriteFileOptions,
+ SandboxWriteTextFileOptions,
+} from "#shared/sandbox-session.js";
+
+/**
+ * Returns a sandbox session that applies `abortSignal` to every operation.
+ * Per-call signals are composed with the bound signal.
+ */
+export function bindSandboxAbortSignal(
+ session: SandboxSession,
+ abortSignal: AbortSignal,
+): SandboxSession {
+ const compose = (callSignal: AbortSignal | undefined): AbortSignal =>
+ callSignal === undefined ? abortSignal : AbortSignal.any([abortSignal, callSignal]);
+
+ return {
+ ...session,
+ run: (options: SandboxRunOptions) =>
+ session.run({ ...options, abortSignal: compose(options.abortSignal) }),
+ spawn: (options: SandboxSpawnOptions) =>
+ session.spawn({ ...options, abortSignal: compose(options.abortSignal) }),
+ readFile: (options: SandboxReadFileOptions) =>
+ session.readFile({ ...options, abortSignal: compose(options.abortSignal) }),
+ readBinaryFile: (options: SandboxReadBinaryFileOptions) =>
+ session.readBinaryFile({ ...options, abortSignal: compose(options.abortSignal) }),
+ readTextFile: (options: SandboxReadTextFileOptions) =>
+ session.readTextFile({ ...options, abortSignal: compose(options.abortSignal) }),
+ writeFile: (options: SandboxWriteFileOptions) =>
+ session.writeFile({ ...options, abortSignal: compose(options.abortSignal) }),
+ writeBinaryFile: (options: SandboxWriteBinaryFileOptions) =>
+ session.writeBinaryFile({ ...options, abortSignal: compose(options.abortSignal) }),
+ writeTextFile: (options: SandboxWriteTextFileOptions) =>
+ session.writeTextFile({ ...options, abortSignal: compose(options.abortSignal) }),
+ removePath: (options: SandboxRemovePathOptions) =>
+ session.removePath({ ...options, abortSignal: compose(options.abortSignal) }),
+ };
+}
diff --git a/packages/eve/src/execution/sandbox/require-sandbox.ts b/packages/eve/src/execution/sandbox/require-sandbox.ts
index a0b2f1a21..8925002c3 100644
--- a/packages/eve/src/execution/sandbox/require-sandbox.ts
+++ b/packages/eve/src/execution/sandbox/require-sandbox.ts
@@ -1,6 +1,7 @@
import { loadContext } from "#context/container.js";
import { SandboxKey } from "#context/keys.js";
import type { SandboxSession } from "#public/definitions/sandbox.js";
+import { bindSandboxAbortSignal } from "#execution/sandbox/abort-bound-session.js";
/**
* Resolves the active sandbox session from the runtime context.
@@ -9,8 +10,10 @@ import type { SandboxSession } from "#public/definitions/sandbox.js";
* `read_file`, `write_file`, `glob`, `grep`). Centralizes the context
* lookup, null checks, and error messages so each executor does not
* duplicate them.
+ *
+ * Binds the returned session to `abortSignal` when provided.
*/
-export async function requireSandboxSession(): Promise<SandboxSession> {
+export async function requireSandboxSession(abortSignal?: AbortSignal): Promise<SandboxSession> {
const sandboxAccess = loadContext().get(SandboxKey);
if (sandboxAccess === undefined) {
@@ -26,7 +29,7 @@ export async function requireSandboxSession(): Promise<SandboxSession> {
throw new Error("The sandbox is not available in the current runtime context.");
}
- return sandbox;
+ return abortSignal === undefined ? sandbox : bindSandboxAbortSignal(sandbox, abortSignal);
}
/**
diff --git a/packages/eve/src/execution/tool-auth.ts b/packages/eve/src/execution/tool-auth.ts
index 0b63839be..d031f3c79 100644
--- a/packages/eve/src/execution/tool-auth.ts
+++ b/packages/eve/src/execution/tool-auth.ts
@@ -13,7 +13,7 @@
* execution-layer adapter that wraps one tool's `execute`.
*/
-import { buildCallbackContext } from "#context/build-callback-context.js";
+import { buildBaseToolContext } from "#context/build-base-tool-context.js";
import {
ConnectionAuthorizationFailedError,
ConnectionAuthorizationRequiredError,
@@ -34,6 +34,7 @@ import {
startScopedAuthorization,
type ScopedAuthorization,
} from "#runtime/connections/scoped-authorization.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Wraps one authored tool's `execute` with a context that supports inline
@@ -53,16 +54,17 @@ import {
export function createToolExecuteWithAuth(input: {
readonly scope: string;
readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
-}): (toolInput: unknown) => Promise<unknown> {
+}): (toolInput: unknown, options?: ToolExecuteOptions) => Promise<unknown> {
const { scope, execute } = input;
- return async (toolInput: unknown): Promise<unknown> => {
+ return async (toolInput: unknown, options?: ToolExecuteOptions): Promise<unknown> => {
const justAuthorizedScopes = new Set<string>();
try {
return await execute(
toolInput,
buildToolContext({
+ abortSignal: options?.abortSignal,
inlineAuthState: {},
justAuthorizedScopes,
scope,
@@ -79,12 +81,13 @@ export function createToolExecuteWithAuth(input: {
}
function buildToolContext(input: {
+ readonly abortSignal: AbortSignal | undefined;
readonly scope: string;
readonly justAuthorizedScopes: Set<string>;
readonly inlineAuthState: InlineAuthState;
}): ToolContext {
const { scope, justAuthorizedScopes, inlineAuthState } = input;
- const base = buildCallbackContext();
+ const base = buildBaseToolContext(input.abortSignal);
return {
...base,
async getToken(provider?: ToolAuthProvider, options?: ToolAuthOptions): Promise<TokenResult> {
diff --git a/packages/eve/src/execution/web-fetch/tool.ts b/packages/eve/src/execution/web-fetch/tool.ts
index 003dec455..0a10928ed 100644
--- a/packages/eve/src/execution/web-fetch/tool.ts
+++ b/packages/eve/src/execution/web-fetch/tool.ts
@@ -24,6 +24,12 @@ export interface WebFetchInput {
readonly url: string;
}
+/** Per-call options accepted by {@link executeWebFetchTool}. */
+export interface WebFetchExecuteOptions {
+ /** Signal combined with the request timeout. */
+ readonly abortSignal?: AbortSignal;
+}
+
/**
* Structured result returned from {@link executeWebFetchTool}.
*/
@@ -48,7 +54,10 @@ export interface WebFetchResult {
* is capped at the shared tool-output budget (50 KB / 2000 lines) so
* large pages do not exhaust the model's context window.
*/
-export async function executeWebFetchTool(args: WebFetchInput): Promise<WebFetchResult> {
+export async function executeWebFetchTool(
+ args: WebFetchInput,
+ options?: WebFetchExecuteOptions,
+): Promise<WebFetchResult> {
const { url, format = "markdown", timeout } = args;
if (!url.startsWith("http://") && !url.startsWith("https://")) {
@@ -60,7 +69,11 @@ export async function executeWebFetchTool(args: WebFetchInput): Promise<WebFetch
MAX_TIMEOUT_MS,
);
- const signal = AbortSignal.timeout(timeoutMs);
+ const timeoutSignal = AbortSignal.timeout(timeoutMs);
+ const signal =
+ options?.abortSignal === undefined
+ ? timeoutSignal
+ : AbortSignal.any([options.abortSignal, timeoutSignal]);
const headers = buildHeaders(format);
const initial = await fetch(url, { headers, signal });
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index a0c56af94..10e96a2f7 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -318,6 +318,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
});
const step = createExecutionNodeStep({
+ abortSignal: input.abortSignal,
capabilities,
createRuntime: createWorkflowRuntime,
handleEvent,
diff --git a/packages/eve/src/harness/compaction.test.ts b/packages/eve/src/harness/compaction.test.ts
index 59392d9ff..e91916cde 100644
--- a/packages/eve/src/harness/compaction.test.ts
+++ b/packages/eve/src/harness/compaction.test.ts
@@ -284,6 +284,41 @@ describe("compactMessages", () => {
);
});
+ it("forwards the turn abort signal to the compaction model call", async () => {
+ const { generateText } = await import("ai");
+
+ vi.mocked(generateText).mockResolvedValue({
+ text: "Summary of prior context",
+ } as Awaited<ReturnType<typeof generateText>>);
+
+ const messages: ModelMessage[] = [
+ { content: "old message 1", role: "user" },
+ { content: "old message 2", role: "assistant" },
+ { content: "recent 1", role: "user" },
+ { content: "recent 2", role: "assistant" },
+ ];
+
+ const model = {} as Parameters<typeof compactMessages>[1];
+ const abortController = new AbortController();
+
+ await compactMessages(
+ messages,
+ model,
+ config,
+ undefined,
+ undefined,
+ undefined,
+ abortController.signal,
+ );
+
+ expect(generateText).toHaveBeenCalledWith(
+ expect.objectContaining({
+ abortSignal: abortController.signal,
+ model,
+ }),
+ );
+ });
+
it("folds oversized recent tool results into the summary when the raw tail does not fit", async () => {
const { generateText } = await import("ai");
diff --git a/packages/eve/src/harness/compaction.ts b/packages/eve/src/harness/compaction.ts
index 076794757..648a4884f 100644
--- a/packages/eve/src/harness/compaction.ts
+++ b/packages/eve/src/harness/compaction.ts
@@ -111,6 +111,7 @@ export async function compactMessages(
providerOptions?: Parameters<typeof generateText>[0]["providerOptions"],
telemetry?: TelemetryOptions,
headers?: Record<string, string>,
+ abortSignal?: AbortSignal,
): Promise<ModelMessage[]> {
let keep = selectRecentWindowSize(messages, config);
@@ -126,6 +127,7 @@ export async function compactMessages(
}));
const result = await generateText({
+ abortSignal,
headers,
model,
prompt: formatCompactionPrompt(prunedOlder),
diff --git a/packages/eve/src/harness/emission.ts b/packages/eve/src/harness/emission.ts
index 18778023a..fa9b35f29 100644
--- a/packages/eve/src/harness/emission.ts
+++ b/packages/eve/src/harness/emission.ts
@@ -613,6 +613,9 @@ export async function emitStreamContent(
// `cause` instead of degrading to `new Error("[object Object]")`.
streamError = toError(part.error);
break;
+ case "abort":
+ // The SDK does not resolve step results for aborted in-flight steps.
+ throw new DOMException(part.reason ?? "The model stream was aborted.", "AbortError");
default:
break;
}
diff --git a/packages/eve/src/harness/execute-tool.ts b/packages/eve/src/harness/execute-tool.ts
index 2712fabe2..eb7192d4d 100644
--- a/packages/eve/src/harness/execute-tool.ts
+++ b/packages/eve/src/harness/execute-tool.ts
@@ -1,6 +1,7 @@
import type { FlexibleSchema } from "ai";
import type { Approval } from "#public/definitions/approval.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Runtime-owned action metadata attached to one harness-visible tool.
@@ -21,7 +22,7 @@ export type HarnessRuntimeActionDefinition = {
export interface HarnessToolDefinition {
readonly approvalKey?: (toolInput: Readonly<Record<string, unknown>>) => string;
readonly description: string;
- readonly execute?: (input: any) => any;
+ readonly execute?: (input: any, options?: ToolExecuteOptions) => any;
readonly inputSchema: FlexibleSchema;
readonly name: string;
readonly approval?: Approval;
diff --git a/packages/eve/src/harness/model-call-error.test.ts b/packages/eve/src/harness/model-call-error.test.ts
index b3b3626e1..8f3a5fcc5 100644
--- a/packages/eve/src/harness/model-call-error.test.ts
+++ b/packages/eve/src/harness/model-call-error.test.ts
@@ -9,6 +9,7 @@ import {
summarizeKnownModelCallConfigError,
summarizeKnownModelCallRequestError,
} from "#harness/model-call-error.js";
+import { TurnCancelledError } from "#harness/turn-cancellation.js";
/**
* Builds the shape `[email protected]+` rejects with when a model
@@ -128,6 +129,16 @@ describe("classifyModelCallError", () => {
expect(classifyModelCallError(new EmptyModelResponseError())).toBe("recoverable");
});
+ it("returns terminal for a turn cancellation, even when marked retryable", () => {
+ expect(classifyModelCallError(new TurnCancelledError())).toBe("terminal");
+
+ const wrapped = Object.assign(new Error("socket hang up"), {
+ cause: new TurnCancelledError(),
+ isRetryable: true,
+ });
+ expect(classifyModelCallError(wrapped)).toBe("terminal");
+ });
+
it("returns retry when the AI SDK marks the error as retryable", () => {
const err = Object.assign(new Error("upstream flaky"), { isRetryable: true });
expect(classifyModelCallError(err)).toBe("retry");
diff --git a/packages/eve/src/harness/model-call-error.ts b/packages/eve/src/harness/model-call-error.ts
index 98936ffe5..587053511 100644
--- a/packages/eve/src/harness/model-call-error.ts
+++ b/packages/eve/src/harness/model-call-error.ts
@@ -1,5 +1,6 @@
import { isObject } from "#shared/guards.js";
import type { JsonObject, JsonValue } from "#shared/json.js";
+import { isTurnCancellation } from "#harness/turn-cancellation.js";
const RESPONSE_BODY_SNIPPET_LIMIT = 1_000;
const GATEWAY_MODEL_REQUEST_REJECTED_MESSAGE =
@@ -289,6 +290,10 @@ export function isNoOutputGeneratedError(error: unknown): boolean {
* Classifies a model-call failure into the runtime's recovery policy.
*/
export function classifyModelCallError(error: unknown): "retry" | "recoverable" | "terminal" {
+ if (isTurnCancellation(error)) {
+ return "terminal";
+ }
+
// Not "retry": the empty response already resolved the step hooks'
// one-shot stepResult promise, so a same-hooks retry would read the
// stale empty result. The harness reissues with fresh hooks instead
diff --git a/packages/eve/src/harness/tool-interrupts.test.ts b/packages/eve/src/harness/tool-interrupts.test.ts
index 72cb4ecac..a82f5b5cb 100644
--- a/packages/eve/src/harness/tool-interrupts.test.ts
+++ b/packages/eve/src/harness/tool-interrupts.test.ts
@@ -93,7 +93,9 @@ describe("wrapToolExecute", () => {
const signal = signalWithVerifier();
const wrapped = wrapToolExecute({ ...baseDef, execute: async () => signal })!;
const ctx = new ContextContainer();
- const output = await contextStorage.run(ctx, () => wrapped({}, { toolCallId: "call_1" }));
+ const output = await contextStorage.run(ctx, () =>
+ wrapped({}, { messages: [], toolCallId: "call_1" }),
+ );
expect(isAuthorizationPendingModelOutput(output)).toBe(true);
expect(output).toEqual(modelFacingAuthorizationOutput(signal));
@@ -105,7 +107,9 @@ describe("wrapToolExecute", () => {
it("passes non-interrupt outputs through unchanged", async () => {
const wrapped = wrapToolExecute({ ...baseDef, execute: async () => ({ ok: true }) })!;
const ctx = new ContextContainer();
- const output = await contextStorage.run(ctx, () => wrapped({}, { toolCallId: "call_3" }));
+ const output = await contextStorage.run(ctx, () =>
+ wrapped({}, { messages: [], toolCallId: "call_3" }),
+ );
expect(output).toEqual({ ok: true });
expect(readToolInterrupt(ctx, "call_3")).toBeUndefined();
diff --git a/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts b/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts
new file mode 100644
index 000000000..ec72a8b94
--- /dev/null
+++ b/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts
@@ -0,0 +1,227 @@
+import { jsonSchema, type LanguageModel } from "ai";
+import { MockLanguageModelV3 } from "ai/test";
+import { describe, expect, it, vi } from "vitest";
+
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { createToolLoopHarness } from "#harness/tool-loop.js";
+import { TurnCancelledError } from "#harness/turn-cancellation.js";
+import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
+
+type StreamResult = Awaited<ReturnType<MockLanguageModelV3["doStream"]>>;
+type StreamPart = StreamResult["stream"] extends ReadableStream<infer Part> ? Part : never;
+
+const FAILURE_EVENT_TYPES = ["step.failed", "turn.failed", "session.failed"] as const;
+
+function createSession(): HarnessSession {
+ return {
+ agent: {
+ modelReference: { id: "integration-model" },
+ system: "You are a test assistant.",
+ tools: [],
+ },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "http:integration-session",
+ history: [],
+ sessionId: "integration-session",
+ };
+}
+
+function createEventCollector(): {
+ emit: HarnessEmitFn;
+ events: HandleMessageStreamEvent[];
+} {
+ const events: HandleMessageStreamEvent[] = [];
+ const emit: HarnessEmitFn = async (event) => {
+ events.push(event);
+ };
+ return { emit, events };
+}
+
+function createConfig(
+ model: LanguageModel,
+ emit: HarnessEmitFn,
+ overrides?: Partial<ToolLoopHarnessConfig>,
+): ToolLoopHarnessConfig {
+ return {
+ handleEvent: emit,
+ mode: "conversation",
+ resolveModel: vi.fn().mockResolvedValue(model),
+ tools: new Map(),
+ ...overrides,
+ };
+}
+
+function createHangingStreamModel(onStreamStarted: () => void): MockLanguageModelV3 {
+ return new MockLanguageModelV3({
+ modelId: "integration-model",
+ provider: "eve-integration-mock",
+ doStream: async () => ({
+ stream: new ReadableStream<StreamPart>({
+ start(controller) {
+ controller.enqueue({ type: "stream-start", warnings: [] });
+ controller.enqueue({ id: "text-1", type: "text-start" });
+ controller.enqueue({ delta: "Working on it", id: "text-1", type: "text-delta" });
+ onStreamStarted();
+ },
+ }),
+ }),
+ });
+}
+
+describe("tool loop cancellation (real AI SDK)", () => {
+ it("aborting mid-stream settles with the canonical cancellation and no failure events", async () => {
+ const abortController = new AbortController();
+ const cancellation = new TurnCancelledError();
+ const model = createHangingStreamModel(() => {
+ abortController.abort(cancellation);
+ });
+
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(
+ createConfig(model, emit, { abortSignal: abortController.signal }),
+ );
+
+ await expect(runStep(createSession(), { message: "Do a lot of work" })).rejects.toBe(
+ cancellation,
+ );
+
+ const eventTypes = events.map((event) => event.type);
+ for (const failureType of FAILURE_EVENT_TYPES) {
+ expect(eventTypes).not.toContain(failureType);
+ }
+ });
+
+ it("forwards a live signal to executing tools and discards the straggler result", async () => {
+ const abortController = new AbortController();
+ const cancellation = new TurnCancelledError();
+
+ let toolSignal: AbortSignal | undefined;
+ let toolSignalAborted = false;
+
+ const doStream = vi.fn().mockImplementation(async () => ({
+ stream: new ReadableStream<StreamPart>({
+ start(controller) {
+ controller.enqueue({ type: "stream-start", warnings: [] });
+ controller.enqueue({
+ input: JSON.stringify({}),
+ toolCallId: "call-wait-1",
+ toolName: "wait_for_cancel",
+ type: "tool-call",
+ });
+ controller.enqueue({
+ finishReason: { raw: undefined, unified: "tool-calls" },
+ type: "finish",
+ usage: {
+ inputTokens: { cacheRead: 0, cacheWrite: 0, noCache: 1, total: 1 },
+ outputTokens: { reasoning: 0, text: 1, total: 1 },
+ },
+ });
+ controller.close();
+ },
+ }),
+ }));
+ const model = new MockLanguageModelV3({
+ modelId: "integration-model",
+ provider: "eve-integration-mock",
+ doStream,
+ });
+
+ const tools: ToolLoopHarnessConfig["tools"] = new Map([
+ [
+ "wait_for_cancel",
+ {
+ description: "Waits until the turn is cancelled.",
+ execute: (_input: unknown, options?: ToolExecuteOptions) => {
+ toolSignal = options?.abortSignal;
+ return new Promise((_resolve, reject) => {
+ options?.abortSignal?.addEventListener(
+ "abort",
+ () => {
+ toolSignalAborted = true;
+ reject(options.abortSignal?.reason);
+ },
+ { once: true },
+ );
+ abortController.abort(cancellation);
+ });
+ },
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "wait_for_cancel",
+ },
+ ],
+ ]);
+
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(
+ createConfig(model, emit, { abortSignal: abortController.signal, tools }),
+ );
+
+ const session: HarnessSession = {
+ ...createSession(),
+ agent: {
+ modelReference: { id: "integration-model" },
+ system: "You are a test assistant.",
+ tools: [
+ {
+ description: "Waits until the turn is cancelled.",
+ inputSchema: { type: "object" },
+ name: "wait_for_cancel",
+ },
+ ],
+ },
+ };
+
+ await expect(runStep(session, { message: "wait for cancel" })).rejects.toBe(cancellation);
+
+ expect(doStream).toHaveBeenCalledTimes(1);
+ expect(toolSignal).toBeInstanceOf(AbortSignal);
+ expect(toolSignalAborted).toBe(true);
+
+ const eventTypes = events.map((event) => event.type);
+ for (const failureType of FAILURE_EVENT_TYPES) {
+ expect(eventTypes).not.toContain(failureType);
+ }
+ });
+
+ it("leaves behavior unchanged when the signal never aborts", async () => {
+ const buildModel = (): MockLanguageModelV3 =>
+ new MockLanguageModelV3({
+ modelId: "integration-model",
+ provider: "eve-integration-mock",
+ doStream: async () => ({
+ stream: new ReadableStream<StreamPart>({
+ start(controller) {
+ controller.enqueue({ type: "stream-start", warnings: [] });
+ controller.enqueue({ id: "text-1", type: "text-start" });
+ controller.enqueue({ delta: "All done.", id: "text-1", type: "text-delta" });
+ controller.enqueue({ id: "text-1", type: "text-end" });
+ controller.enqueue({
+ finishReason: { raw: undefined, unified: "stop" },
+ type: "finish",
+ usage: {
+ inputTokens: { cacheRead: 0, cacheWrite: 0, noCache: 1, total: 1 },
+ outputTokens: { reasoning: 0, text: 1, total: 1 },
+ },
+ });
+ controller.close();
+ },
+ }),
+ }),
+ });
+
+ const inert = createEventCollector();
+ const inertResult = await createToolLoopHarness(
+ createConfig(buildModel(), inert.emit, { abortSignal: new AbortController().signal }),
+ )(createSession(), { message: "Hi" });
+
+ const bare = createEventCollector();
+ const bareResult = await createToolLoopHarness(createConfig(buildModel(), bare.emit))(
+ createSession(),
+ { message: "Hi" },
+ );
+
+ expect(inertResult.next).toBe(bareResult.next);
+ expect(inert.events.map((event) => event.type)).toEqual(bare.events.map((event) => event.type));
+ });
+});
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 6d3f40ce8..b5e1fcd14 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -37,6 +37,7 @@ import { hasDeferredStepInput, setPendingInputBatch } from "#harness/input-reque
import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
import { stashToolInterrupt } from "#harness/tool-interrupts.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
+import { TurnCancelledError } from "#harness/turn-cancellation.js";
import { getSessionTokenUsage, setTurnUsageState } from "#harness/turn-tag-state.js";
import { DEFAULT_SUBAGENT_MAX_DEPTH } from "#harness/subagent-depth.js";
import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
@@ -2599,6 +2600,100 @@ describe("createToolLoopHarness", () => {
});
});
+ it("propagates streamed cancellation without waiting for onStepFinish or emitting failures", async () => {
+ const abortController = new AbortController();
+ const abortReason = new TurnCancelledError();
+
+ vi.mocked(ToolLoopAgent).mockImplementation(function (
+ this: ToolLoopAgent,
+ settings: MockAgentSettings,
+ ) {
+ this.stream = vi
+ .fn()
+ .mockImplementation(async (options: { abortSignal?: AbortSignal; messages: unknown[] }) => {
+ expect(options.abortSignal).toBe(abortController.signal);
+ if (settings.prepareStep) {
+ await settings.prepareStep({
+ context: undefined,
+ messages: options.messages,
+ model: {},
+ stepNumber: 0,
+ steps: [],
+ });
+ }
+
+ return {
+ fullStream: (async function* () {
+ abortController.abort(abortReason);
+ yield { reason: abortReason.message, type: "abort" };
+ })(),
+ steps: new Promise<never>(() => {}),
+ };
+ });
+ return this;
+ } as MockAgentConstructor);
+
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(
+ createTestConfig("conversation", emit, { abortSignal: abortController.signal }),
+ );
+
+ await expect(runStep(createTestSession(), { message: "Hi" })).rejects.toBe(abortReason);
+
+ const eventTypes = events.map((event) => event.type);
+ expect(eventTypes).not.toContain("step.failed");
+ expect(eventTypes).not.toContain("turn.failed");
+ expect(eventTypes).not.toContain("session.failed");
+ });
+
+ it("does not retry or recover a model call once the turn signal has aborted", async () => {
+ const abortController = new AbortController();
+ const cancellation = new TurnCancelledError();
+ const streamMock = vi.fn().mockImplementation(async () => {
+ abortController.abort(cancellation);
+ throw Object.assign(new Error("socket hang up"), { isRetryable: true });
+ });
+ vi.mocked(ToolLoopAgent).mockImplementation(function (this: ToolLoopAgent) {
+ this.stream = streamMock;
+ this.generate = streamMock;
+ return this;
+ } as MockAgentConstructor);
+
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(
+ createTestConfig("conversation", emit, { abortSignal: abortController.signal }),
+ );
+
+ await expect(runStep(createTestSession(), { message: "Hi" })).rejects.toBe(cancellation);
+ expect(streamMock).toHaveBeenCalledTimes(1);
+
+ const eventTypes = events.map((event) => event.type);
+ expect(eventTypes).not.toContain("step.failed");
+ expect(eventTypes).not.toContain("turn.failed");
+ expect(eventTypes).not.toContain("session.failed");
+ });
+
+ it("does not start a model call when the turn signal is already aborted", async () => {
+ const abortController = new AbortController();
+ const cancellation = new TurnCancelledError();
+ abortController.abort(cancellation);
+
+ const streamMock = vi.fn();
+ vi.mocked(ToolLoopAgent).mockImplementation(function (this: ToolLoopAgent) {
+ this.stream = streamMock;
+ this.generate = streamMock;
+ return this;
+ } as MockAgentConstructor);
+
+ const { emit } = createEventCollector();
+ const runStep = createToolLoopHarness(
+ createTestConfig("conversation", emit, { abortSignal: abortController.signal }),
+ );
+
+ await expect(runStep(createTestSession(), { message: "Hi" })).rejects.toBe(cancellation);
+ expect(streamMock).not.toHaveBeenCalled();
+ });
+
it("emits a recoverable failure cascade and parks the session on a non-terminal model-call error", async () => {
setupMockAgentError(new Error("Model blew up"));
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 9bcc35963..11c67a1a0 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -120,6 +120,7 @@ import {
summarizeKnownModelCallConfigError,
summarizeKnownModelCallRequestError,
} from "#harness/model-call-error.js";
+import { throwIfTurnAborted } from "#harness/turn-cancellation.js";
import type { JsonObject, JsonValue } from "#shared/json.js";
import {
CONDITIONAL_DELIVERY_INSTRUCTION,
@@ -519,6 +520,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const attributionHeaders = buildGatewayAttributionHeaders(model, config.runtimeIdentity);
({ messages, session } = await maybeCompact({
+ abortSignal: config.abortSignal,
emit,
emissionState,
headers: attributionHeaders,
@@ -747,7 +749,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
FINAL_OUTPUT_TOOL_NAME,
...hiddenRuntimeActionToolNames,
]);
- const streamResult = await agent.stream({ messages: callMessages });
+ const streamResult = await agent.stream({
+ abortSignal: config.abortSignal,
+ messages: callMessages,
+ });
const {
emittedActionCallIds,
handledInlineToolResultCallIds,
@@ -758,6 +763,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
excludedActionToolNames,
tools: config.tools,
});
+ throwIfTurnAborted(config.abortSignal);
const stepResult = await hooks.stepResult;
if (
isEmptyModelResponse(stepResult) &&
@@ -817,7 +823,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
}
return stepResult;
}
- await agent.generate({ messages: callMessages });
+ await agent.generate({ abortSignal: config.abortSignal, messages: callMessages });
+ throwIfTurnAborted(config.abortSignal);
const stepResult = await hooks.stepResult;
if (isEmptyModelResponse(stepResult)) {
throw new EmptyModelResponseError();
@@ -831,6 +838,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
sessionId: session.sessionId,
turnId: emissionState.turnId,
},
+ config.abortSignal,
);
};
@@ -876,6 +884,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
suppressStepStartedEmission: true,
});
} catch (error) {
+ throwIfTurnAborted(config.abortSignal);
+
// Stage order: drop a gateway-rejected provider tool first, then
// reissue an empty response; see runModelCallRecoveryPipeline for
// the skip/act semantics.
@@ -900,6 +910,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
}),
],
});
+ throwIfTurnAborted(config.abortSignal);
if (recoveryResult.outcome === "recovered") {
result = recoveryResult.result;
@@ -2110,6 +2121,7 @@ function createNextCompactionConfig(
* harness uses to rebuild `session.history` after the step.
*/
async function maybeCompact(input: {
+ readonly abortSignal?: AbortSignal;
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly headers?: Record<string, string>;
@@ -2154,6 +2166,7 @@ async function maybeCompact(input: {
compaction.providerOptions,
input.telemetry,
input.headers,
+ input.abortSignal,
);
if (input.onCompaction) {
@@ -2202,11 +2215,14 @@ function resolveApprovalKeyFromTools(
async function runModelCallWithRetries<T>(
fn: () => Promise<T>,
diag: { readonly sessionId: string; readonly turnId: string },
+ abortSignal?: AbortSignal,
): Promise<T> {
for (let attempt = 1; ; attempt++) {
+ throwIfTurnAborted(abortSignal);
try {
return await fn();
} catch (error) {
+ throwIfTurnAborted(abortSignal);
if (attempt === MODEL_CALL_MAX_ATTEMPTS || classifyModelCallError(error) !== "retry") {
throw error;
}
diff --git a/packages/eve/src/harness/tools.test.ts b/packages/eve/src/harness/tools.test.ts
index db86d8710..d112e4bcf 100644
--- a/packages/eve/src/harness/tools.test.ts
+++ b/packages/eve/src/harness/tools.test.ts
@@ -16,6 +16,9 @@ import type { JsonObject } from "#shared/json.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import { buildToolApproval, buildToolSet, buildToolSetWithProviderTools } from "#harness/tools.js";
import type { HarnessToolMap } from "#harness/types.js";
+import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
+import type { ToolContext } from "#public/definitions/tool.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
function getJsonSchema(tool: unknown): unknown {
return (tool as { inputSchema: { jsonSchema: unknown } }).inputSchema.jsonSchema;
@@ -51,6 +54,7 @@ async function resolveApproval(
}
async function executeSdkTool(input: {
+ readonly abortSignal?: AbortSignal;
readonly tool: unknown;
readonly toolCallId?: string;
readonly toolInput?: unknown;
@@ -59,12 +63,16 @@ async function executeSdkTool(input: {
input.tool as {
readonly execute?: (
toolInput: unknown,
- options: { readonly toolCallId: string },
+ options: ToolExecuteOptions,
) => Promise<unknown> | unknown;
}
).execute;
expect(execute).toBeTypeOf("function");
- return await execute!(input.toolInput ?? {}, { toolCallId: input.toolCallId ?? "call_1" });
+ return await execute!(input.toolInput ?? {}, {
+ abortSignal: input.abortSignal,
+ messages: [],
+ toolCallId: input.toolCallId ?? "call_1",
+ });
}
async function projectSdkToolOutput(input: {
@@ -90,6 +98,106 @@ async function projectSdkToolOutput(input: {
}
describe("buildToolSet", () => {
+ it("forwards the AI SDK execute options to the tool definition", async () => {
+ const abortController = new AbortController();
+ let receivedOptions: ToolExecuteOptions | undefined;
+ const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([
+ [
+ "observe_options",
+ {
+ description: "Observe the AI SDK execute options.",
+ execute: (_input: unknown, options?: ToolExecuteOptions) => {
+ receivedOptions = options;
+ return { ok: true };
+ },
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "observe_options",
+ },
+ ],
+ ]);
+
+ const result = buildToolSet({ tools });
+ await executeSdkTool({
+ abortSignal: abortController.signal,
+ tool: result.observe_options,
+ toolCallId: "call_observe",
+ });
+
+ expect(receivedOptions?.abortSignal).toBe(abortController.signal);
+ expect(receivedOptions?.toolCallId).toBe("call_observe");
+ });
+
+ it("passes the AI SDK abort signal to the authored tool context", async () => {
+ const abortController = new AbortController();
+ let receivedSignal: AbortSignal | undefined;
+ const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([
+ [
+ "observe_signal",
+ {
+ description: "Observe the active turn signal.",
+ execute: createToolExecuteWithAuth({
+ execute(_input, ctx) {
+ receivedSignal = (ctx as ToolContext).abortSignal;
+ return { ok: true };
+ },
+ scope: "observe_signal",
+ }),
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "observe_signal",
+ },
+ ],
+ ]);
+ const ctx = new ContextContainer();
+ ctx.set(SessionKey, {
+ auth: { current: null, initiator: null },
+ sessionId: "session-1",
+ turn: { id: "turn-1", sequence: 0 },
+ });
+
+ const result = buildToolSet({ tools });
+ await contextStorage.run(ctx, () =>
+ executeSdkTool({
+ abortSignal: abortController.signal,
+ tool: result.observe_signal,
+ }),
+ );
+
+ expect(receivedSignal).toBe(abortController.signal);
+ });
+
+ it("supplies an inert abort signal when the SDK provides none", async () => {
+ let receivedSignal: AbortSignal | undefined;
+ const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([
+ [
+ "observe_signal",
+ {
+ description: "Observe the active turn signal.",
+ execute: createToolExecuteWithAuth({
+ execute(_input, ctx) {
+ receivedSignal = (ctx as ToolContext).abortSignal;
+ return { ok: true };
+ },
+ scope: "observe_signal",
+ }),
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "observe_signal",
+ },
+ ],
+ ]);
+ const ctx = new ContextContainer();
+ ctx.set(SessionKey, {
+ auth: { current: null, initiator: null },
+ sessionId: "session-1",
+ turn: { id: "turn-1", sequence: 0 },
+ });
+
+ const result = buildToolSet({ tools });
+ await contextStorage.run(ctx, () => executeSdkTool({ tool: result.observe_signal }));
+
+ expect(receivedSignal).toBeInstanceOf(AbortSignal);
+ expect(receivedSignal?.aborted).toBe(false);
+ });
+
it("passes through the input schema to the SDK tool", () => {
const schema = {
properties: { city: { type: "string" } },
diff --git a/packages/eve/src/harness/tools.ts b/packages/eve/src/harness/tools.ts
index 722510c1b..a99188741 100644
--- a/packages/eve/src/harness/tools.ts
+++ b/packages/eve/src/harness/tools.ts
@@ -26,6 +26,7 @@ import {
} from "#harness/authorization.js";
import { stashToolInterrupt } from "#harness/tool-interrupts.js";
import { withToolOutputSerializationError } from "#harness/tool-output-serialization.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
type ToolModelOutputValue =
| { readonly type: "json"; readonly value: JSONValue }
@@ -170,11 +171,11 @@ export function buildToolSetFromDefinitions(input: {
*/
export function wrapToolExecute(
definition: HarnessToolDefinition,
-): ((input: any, options: { readonly toolCallId: string }) => Promise<any>) | undefined {
+): ((input: any, options: ToolExecuteOptions) => Promise<any>) | undefined {
const execute = definition.execute;
if (execute === undefined) return undefined;
return async (input, options) => {
- const output = await execute(input);
+ const output = await execute(input, options);
if (isAuthorizationSignal(output)) {
stashToolInterrupt(loadContext(), options.toolCallId, output);
return modelFacingAuthorizationOutput(output);
diff --git a/packages/eve/src/harness/turn-cancellation.test.ts b/packages/eve/src/harness/turn-cancellation.test.ts
new file mode 100644
index 000000000..4719ca983
--- /dev/null
+++ b/packages/eve/src/harness/turn-cancellation.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ isTurnCancellation,
+ throwIfTurnAborted,
+ TurnCancelledError,
+} from "#harness/turn-cancellation.js";
+
+describe("TurnCancelledError", () => {
+ it("carries the stable name and a default message", () => {
+ const error = new TurnCancelledError();
+ expect(error.name).toBe("TurnCancelledError");
+ expect(error.message).toBe("The turn was cancelled.");
+ expect(error.cause).toBeUndefined();
+ });
+});
+
+describe("isTurnCancellation", () => {
+ it("matches the canonical error and name-preserving copies", () => {
+ expect(isTurnCancellation(new TurnCancelledError())).toBe(true);
+
+ const copy = Object.assign(new Error("The turn was cancelled."), {
+ name: "TurnCancelledError",
+ });
+ expect(isTurnCancellation(copy)).toBe(true);
+ expect(isTurnCancellation({ name: "TurnCancelledError" })).toBe(true);
+ });
+
+ it("walks the cause chain", () => {
+ const wrapped = new Error("model call failed", { cause: new TurnCancelledError() });
+ expect(isTurnCancellation(wrapped)).toBe(true);
+
+ const deep = new Error("outer", { cause: new Error("inner", { cause: wrapped }) });
+ expect(isTurnCancellation(deep)).toBe(true);
+ });
+
+ it("survives a cause cycle", () => {
+ const a = new Error("a");
+ const b = new Error("b", { cause: a });
+ (a as { cause?: unknown }).cause = b;
+ expect(isTurnCancellation(a)).toBe(false);
+ });
+
+ it("does not match generic abort shapes", () => {
+ expect(isTurnCancellation(new DOMException("aborted", "AbortError"))).toBe(false);
+ expect(isTurnCancellation(new DOMException("timeout", "TimeoutError"))).toBe(false);
+ expect(isTurnCancellation(new Error("aborted"))).toBe(false);
+ expect(isTurnCancellation(undefined)).toBe(false);
+ expect(isTurnCancellation("TurnCancelledError")).toBe(false);
+ });
+});
+
+describe("throwIfTurnAborted", () => {
+ it("is a no-op for a missing or live signal", () => {
+ expect(() => throwIfTurnAborted(undefined)).not.toThrow();
+ expect(() => throwIfTurnAborted(new AbortController().signal)).not.toThrow();
+ });
+
+ it("rethrows a cancellation reason as-is", () => {
+ const reason = new TurnCancelledError();
+ const controller = new AbortController();
+ controller.abort(reason);
+
+ expect(() => throwIfTurnAborted(controller.signal)).toThrow(reason);
+ try {
+ throwIfTurnAborted(controller.signal);
+ } catch (error) {
+ expect(error).toBe(reason);
+ }
+ });
+
+ it("normalizes non-cancellation reasons to the canonical error", () => {
+ const bare = new AbortController();
+ bare.abort();
+ expect(() => throwIfTurnAborted(bare.signal)).toThrow(TurnCancelledError);
+
+ const custom = new AbortController();
+ custom.abort(new Error("stop it"));
+ expect(() => throwIfTurnAborted(custom.signal)).toThrow(TurnCancelledError);
+ });
+});
diff --git a/packages/eve/src/harness/turn-cancellation.ts b/packages/eve/src/harness/turn-cancellation.ts
new file mode 100644
index 000000000..804fb6fa4
--- /dev/null
+++ b/packages/eve/src/harness/turn-cancellation.ts
@@ -0,0 +1,36 @@
+const TURN_CANCELLED_ERROR_NAME = "TurnCancelledError";
+
+/** Terminal outcome of a cancelled turn. */
+export class TurnCancelledError extends Error {
+ constructor(message = "The turn was cancelled.") {
+ super(message);
+ this.name = TURN_CANCELLED_ERROR_NAME;
+ }
+}
+
+/** True when the error, or one of its causes, is a {@link TurnCancelledError}. */
+export function isTurnCancellation(error: unknown): boolean {
+ let current: unknown = error;
+ const seen = new Set<unknown>();
+
+ while (typeof current === "object" && current !== null && !seen.has(current)) {
+ seen.add(current);
+ if ((current as { name?: unknown }).name === TURN_CANCELLED_ERROR_NAME) {
+ return true;
+ }
+ current = (current as { cause?: unknown }).cause;
+ }
+
+ return false;
+}
+
+/** Throws when the turn signal has aborted. */
+export function throwIfTurnAborted(abortSignal: AbortSignal | undefined): void {
+ if (abortSignal?.aborted !== true) {
+ return;
+ }
+ if (isTurnCancellation(abortSignal.reason)) {
+ throw abortSignal.reason;
+ }
+ throw new TurnCancelledError();
+}
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index b879670b1..de1f46064 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -211,6 +211,8 @@ export type HandleEventFn = (
* Dependencies injected into the tool-loop harness at construction time.
*/
export interface ToolLoopHarnessConfig {
+ /** Cancellation signal for the active turn. */
+ readonly abortSignal?: AbortSignal;
/**
* Session-level capabilities. The harness reads
* {@link SessionCapabilities.requestInput} when assembling the
diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.ts
index 30462fcf2..c6870acf0 100644
--- a/packages/eve/src/public/definitions/tool.ts
+++ b/packages/eve/src/public/definitions/tool.ts
@@ -72,6 +72,8 @@ export interface ToolAuthOptions {
* resolves that provider inline, which lets one tool use multiple credentials.
*/
export type ToolContext = SessionContext & {
+ /** Aborts when the active turn is cancelled. */
+ readonly abortSignal: AbortSignal;
/**
* Resolves the bearer token for an inline provider. This accepts the same
* auth shapes as a connection's `auth` field, including `connect("...")`
diff --git a/packages/eve/src/runtime/connections/mcp-client.ts b/packages/eve/src/runtime/connections/mcp-client.ts
index cb046f456..a947ea979 100644
--- a/packages/eve/src/runtime/connections/mcp-client.ts
+++ b/packages/eve/src/runtime/connections/mcp-client.ts
@@ -11,6 +11,7 @@ import { isObject } from "#shared/guards.js";
import type {
AuthorizationDefinition,
ConnectionClient,
+ ConnectionToolExecuteOptions,
ConnectionToolMetadata,
HeadersDefinition,
HeaderValue,
@@ -116,7 +117,11 @@ export class McpConnectionClient implements ConnectionClient {
* so callers re-enter the authorization flow instead of surfacing an
* opaque transport error.
*/
- async executeTool(toolName: string, args: unknown): Promise<unknown> {
+ async executeTool(
+ toolName: string,
+ args: unknown,
+ options?: ConnectionToolExecuteOptions,
+ ): Promise<unknown> {
try {
const { tools } = await this.#ensureTools();
@@ -127,7 +132,7 @@ export class McpConnectionClient implements ConnectionClient {
);
}
- return await sdkTool.execute(args, {} as never);
+ return await sdkTool.execute(args, { abortSignal: options?.abortSignal } as never);
} catch (error) {
return await this.#rethrowClassified(error);
}
diff --git a/packages/eve/src/runtime/connections/openapi-client.ts b/packages/eve/src/runtime/connections/openapi-client.ts
index bb8414764..c35ced847 100644
--- a/packages/eve/src/runtime/connections/openapi-client.ts
+++ b/packages/eve/src/runtime/connections/openapi-client.ts
@@ -19,7 +19,11 @@ import {
} from "#runtime/connections/openapi-schema.js";
import { applySecurity, resolveSecurity } from "#runtime/connections/openapi-security.js";
import { extractServerUrl, parseSpecDocument } from "#runtime/connections/openapi-spec.js";
-import type { ConnectionClient, ConnectionToolMetadata } from "#runtime/connections/types.js";
+import type {
+ ConnectionClient,
+ ConnectionToolExecuteOptions,
+ ConnectionToolMetadata,
+} from "#runtime/connections/types.js";
import { isObject } from "#shared/guards.js";
interface OpenApiToolCache {
@@ -95,7 +99,11 @@ export class OpenApiConnectionClient implements ConnectionClient {
return cache.tools;
}
- async executeTool(toolName: string, args: unknown): Promise<OpenApiToolResult> {
+ async executeTool(
+ toolName: string,
+ args: unknown,
+ options?: ConnectionToolExecuteOptions,
+ ): Promise<OpenApiToolResult> {
const cache = await this.#ensureTools();
const operation = cache.operations.get(toolName);
if (operation === undefined) {
@@ -103,7 +111,9 @@ export class OpenApiConnectionClient implements ConnectionClient {
`Tool "${toolName}" not found in connection "${this.#connection.connectionName}".`,
);
}
- return this.#request(operation, cache.baseUrl, isObject(args) ? args : {});
+ return this.#request(operation, cache.baseUrl, isObject(args) ? args : {}, {
+ abortSignal: options?.abortSignal,
+ });
}
async close(): Promise<void> {
@@ -153,8 +163,10 @@ export class OpenApiConnectionClient implements ConnectionClient {
tools[operation.toolName] = tool({
description: operation.description,
inputSchema: jsonSchema(operation.inputSchema),
- execute: async (input: unknown) =>
- this.#request(operation, baseUrl, isObject(input) ? input : {}),
+ execute: async (input: unknown, toolOptions) =>
+ this.#request(operation, baseUrl, isObject(input) ? input : {}, {
+ abortSignal: toolOptions?.abortSignal,
+ }),
});
}
@@ -381,6 +393,7 @@ export class OpenApiConnectionClient implements ConnectionClient {
operation: OpenApiOperation,
baseUrl: string,
args: Record<string, unknown>,
+ options?: ConnectionToolExecuteOptions,
): Promise<OpenApiToolResult> {
const headers = await resolveHeaders(this.#connection);
@@ -425,6 +438,7 @@ export class OpenApiConnectionClient implements ConnectionClient {
method: operation.method.toUpperCase(),
headers,
body,
+ signal: options?.abortSignal,
});
return {
diff --git a/packages/eve/src/runtime/connections/types.ts b/packages/eve/src/runtime/connections/types.ts
index fd941f9f4..33c1b40d2 100644
--- a/packages/eve/src/runtime/connections/types.ts
+++ b/packages/eve/src/runtime/connections/types.ts
@@ -431,11 +431,21 @@ export interface ConnectionToolMetadata {
readonly outputSchema?: Record<string, unknown>;
}
+/** Per-call options for {@link ConnectionClient.executeTool}. */
+export interface ConnectionToolExecuteOptions {
+ /** Signal forwarded into the underlying transport. */
+ readonly abortSignal?: AbortSignal;
+}
+
/** A live client for a single connection. */
export interface ConnectionClient {
close(): Promise<void>;
connect(): Promise<unknown>;
- executeTool(toolName: string, args: unknown): Promise<unknown>;
+ executeTool(
+ toolName: string,
+ args: unknown,
+ options?: ConnectionToolExecuteOptions,
+ ): Promise<unknown>;
getToolMetadata(): Promise<readonly ConnectionToolMetadata[]>;
getTools(): Promise<ToolSet>;
}
diff --git a/packages/eve/src/runtime/framework-tools/bash.ts b/packages/eve/src/runtime/framework-tools/bash.ts
index f33f79837..a45df4dc5 100644
--- a/packages/eve/src/runtime/framework-tools/bash.ts
+++ b/packages/eve/src/runtime/framework-tools/bash.ts
@@ -2,6 +2,7 @@ import { type BashInput, executeBashOnSandbox } from "#execution/sandbox/bash-to
import { requireSandboxSession } from "#execution/sandbox/require-sandbox.js";
import type { JsonObject } from "#shared/json.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Shared input schema used by the framework `bash` tool and any author tool
@@ -47,8 +48,11 @@ export const BASH_OUTPUT_SCHEMA: JsonObject = {
* sandbox dependencies remain lazily loaded inside the execution layer, so the
* top-level import here does not force those backends to initialize eagerly.
*/
-async function executeBash(input: unknown): Promise<unknown> {
- return executeBashOnSandbox(await requireSandboxSession(), input as BashInput);
+async function executeBash(input: unknown, options?: ToolExecuteOptions): Promise<unknown> {
+ return executeBashOnSandbox(
+ await requireSandboxSession(options?.abortSignal),
+ input as BashInput,
+ );
}
export const BASH_TOOL_DEFINITION: ResolvedToolDefinition = {
diff --git a/packages/eve/src/runtime/framework-tools/connection-search-dynamic.ts b/packages/eve/src/runtime/framework-tools/connection-search-dynamic.ts
index 3b97d22e5..e4ad4cf38 100644
--- a/packages/eve/src/runtime/framework-tools/connection-search-dynamic.ts
+++ b/packages/eve/src/runtime/framework-tools/connection-search-dynamic.ts
@@ -433,7 +433,7 @@ export function createConnectionSearchEvents(): DynamicToolEvents {
}) as JsonObject,
approval,
outputSchema: result.outputSchema as JsonObject | undefined,
- async execute(input: Record<string, unknown>) {
+ async execute(input: Record<string, unknown>, executeCtx) {
const reg = loadContext().get(ConnectionRegistryKey)!;
const conn = reg.getConnections().find((c) => c.connectionName === connectionName);
const interactiveAuth = (await resolveInteractiveAuth(reg, connectionName)) as
@@ -460,7 +460,9 @@ export function createConnectionSearchEvents(): DynamicToolEvents {
try {
const client = reg.getClient(connectionName);
- return await client.executeTool(toolName, input);
+ return await client.executeTool(toolName, input, {
+ abortSignal: executeCtx.abortSignal,
+ });
} catch (err) {
if (!isConnectionAuthorizationRequiredError(err) || !interactiveAuth) {
throw err;
diff --git a/packages/eve/src/runtime/framework-tools/glob.ts b/packages/eve/src/runtime/framework-tools/glob.ts
index 7bf10df13..fbf095573 100644
--- a/packages/eve/src/runtime/framework-tools/glob.ts
+++ b/packages/eve/src/runtime/framework-tools/glob.ts
@@ -2,6 +2,7 @@ import { executeGlobOnSandbox, type GlobInput } from "#execution/sandbox/glob-to
import { requireSandboxSession } from "#execution/sandbox/require-sandbox.js";
import type { JsonObject } from "#shared/json.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Shared input schema used by the framework `glob` tool and any author tool
@@ -54,8 +55,11 @@ export const GLOB_OUTPUT_SCHEMA: JsonObject = {
/**
* Framework-owned executor that delegates to the default sandbox.
*/
-async function executeGlob(input: unknown): Promise<unknown> {
- return executeGlobOnSandbox(await requireSandboxSession(), input as GlobInput);
+async function executeGlob(input: unknown, options?: ToolExecuteOptions): Promise<unknown> {
+ return executeGlobOnSandbox(
+ await requireSandboxSession(options?.abortSignal),
+ input as GlobInput,
+ );
}
export const GLOB_TOOL_DEFINITION: ResolvedToolDefinition = {
diff --git a/packages/eve/src/runtime/framework-tools/grep.ts b/packages/eve/src/runtime/framework-tools/grep.ts
index 0f72e2e07..80ea630fb 100644
--- a/packages/eve/src/runtime/framework-tools/grep.ts
+++ b/packages/eve/src/runtime/framework-tools/grep.ts
@@ -2,6 +2,7 @@ import { executeGrepOnSandbox, type GrepInput } from "#execution/sandbox/grep-to
import { requireSandboxSession } from "#execution/sandbox/require-sandbox.js";
import type { JsonObject } from "#shared/json.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Shared input schema used by the framework `grep` tool and any author tool
@@ -74,8 +75,11 @@ export const GREP_OUTPUT_SCHEMA: JsonObject = {
/**
* Framework-owned executor that delegates to the default sandbox.
*/
-async function executeGrep(input: unknown): Promise<unknown> {
- return executeGrepOnSandbox(await requireSandboxSession(), input as GrepInput);
+async function executeGrep(input: unknown, options?: ToolExecuteOptions): Promise<unknown> {
+ return executeGrepOnSandbox(
+ await requireSandboxSession(options?.abortSignal),
+ input as GrepInput,
+ );
}
export const GREP_TOOL_DEFINITION: ResolvedToolDefinition = {
diff --git a/packages/eve/src/runtime/framework-tools/read-file.ts b/packages/eve/src/runtime/framework-tools/read-file.ts
index 64121e903..cb9a8b00b 100644
--- a/packages/eve/src/runtime/framework-tools/read-file.ts
+++ b/packages/eve/src/runtime/framework-tools/read-file.ts
@@ -2,6 +2,7 @@ import { executeReadFileOnSandbox, type ReadFileInput } from "#execution/sandbox
import { requireSandboxSession } from "#execution/sandbox/require-sandbox.js";
import type { JsonObject } from "#shared/json.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Shared input schema used by the framework `read_file` tool and any author
@@ -53,8 +54,11 @@ export const READ_FILE_OUTPUT_SCHEMA: JsonObject = {
/**
* Framework-owned executor that delegates to the default sandbox.
*/
-async function executeReadFile(input: unknown): Promise<unknown> {
- return executeReadFileOnSandbox(await requireSandboxSession(), input as ReadFileInput);
+async function executeReadFile(input: unknown, options?: ToolExecuteOptions): Promise<unknown> {
+ return executeReadFileOnSandbox(
+ await requireSandboxSession(options?.abortSignal),
+ input as ReadFileInput,
+ );
}
export const READ_FILE_TOOL_DEFINITION: ResolvedToolDefinition = {
diff --git a/packages/eve/src/runtime/framework-tools/web-fetch.ts b/packages/eve/src/runtime/framework-tools/web-fetch.ts
index ae2552d5d..f7cfeb19a 100644
--- a/packages/eve/src/runtime/framework-tools/web-fetch.ts
+++ b/packages/eve/src/runtime/framework-tools/web-fetch.ts
@@ -1,9 +1,10 @@
import { executeWebFetchTool, type WebFetchInput } from "#execution/web-fetch/tool.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
import type { JsonObject } from "#shared/json.js";
-async function executeWebFetch(input: unknown): Promise<unknown> {
- return executeWebFetchTool(input as WebFetchInput);
+async function executeWebFetch(input: unknown, options?: ToolExecuteOptions): Promise<unknown> {
+ return executeWebFetchTool(input as WebFetchInput, { abortSignal: options?.abortSignal });
}
export const WEB_FETCH_INPUT_SCHEMA: JsonObject = {
diff --git a/packages/eve/src/runtime/framework-tools/write-file.ts b/packages/eve/src/runtime/framework-tools/write-file.ts
index 8bf36c9dc..170574f5e 100644
--- a/packages/eve/src/runtime/framework-tools/write-file.ts
+++ b/packages/eve/src/runtime/framework-tools/write-file.ts
@@ -5,6 +5,7 @@ import {
import { requireSandboxSession } from "#execution/sandbox/require-sandbox.js";
import type { JsonObject } from "#shared/json.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
+import type { ToolExecuteOptions } from "#shared/tool-definition.js";
/**
* Shared input schema used by the framework `write_file` tool and any author
@@ -47,8 +48,11 @@ export const WRITE_FILE_OUTPUT_SCHEMA: JsonObject = {
/**
* Framework-owned executor that delegates to the default sandbox.
*/
-async function executeWriteFile(input: unknown): Promise<unknown> {
- return executeWriteFileOnSandbox(await requireSandboxSession(), input as WriteFileInput);
+async function executeWriteFile(input: unknown, options?: ToolExecuteOptions): Promise<unknown> {
+ return executeWriteFileOnSandbox(
+ await requireSandboxSession(options?.abortSignal),
+ input as WriteFileInput,
+ );
}
export const WRITE_FILE_TOOL_DEFINITION: ResolvedToolDefinition = {
diff --git a/packages/eve/src/shared/dynamic-tool-definition.ts b/packages/eve/src/shared/dynamic-tool-definition.ts
index cfe3fc0ec..4eb6f4aa2 100644
--- a/packages/eve/src/shared/dynamic-tool-definition.ts
+++ b/packages/eve/src/shared/dynamic-tool-definition.ts
@@ -10,7 +10,10 @@ import type { Approval } from "#public/definitions/approval.js";
import type { SessionAuth } from "#context/keys.js";
import type { HandleMessageStreamEvent } from "#protocol/message.js";
-type ToolContext = SessionContext;
+type ToolContext = SessionContext & {
+ /** Aborts when the active turn is cancelled. */
+ readonly abortSignal: AbortSignal;
+};
/**
* Stream event types allowed for dynamic tool resolvers. Dispatch
diff --git a/research/turn-cancellation-harness-abort.md b/research/turn-cancellation-harness-abort.md
new file mode 100644
index 000000000..478f14833
--- /dev/null
+++ b/research/turn-cancellation-harness-abort.md
@@ -0,0 +1,171 @@
+---
+issue: https://github.com/vercel/eve/issues/483
+status: proposed
+last_updated: "2026-07-02"
+---
+
+# Turn cancellation, layer 0: harness abort propagation
+
+## Summary
+
+Five cancellation attempts (#118/#127/#128/#135, #230, #347) failed to land, and every blocking
+failure lived in the _trigger and cross-process_ layers: raced hooks in the non-terminating session
+driver (#230), deterministic hook-token reclaim conflicts and duplicate finalizer-step execution
+(upstream Workflow bugs blocking #347), and dispatch-adoption races with delegates. The abort
+_propagation_ layer, by contrast, was rewritten three times and converged on the same shape each
+time. It has never shipped only because it was always chained to the layers that break.
+
+This plan ships the propagation layer alone: the turn harness accepts an optional `AbortSignal` and
+honors it end-to-end — model calls, retries, recovery, compaction, and tool execution. No production
+code creates or aborts the signal yet, so runtime behavior is unchanged; the layer is exercised by
+tests. Each later layer then adds exactly one trigger concern.
+
+## The cancellation stack
+
+Cancellation lands bottom-up. Each layer is independently shippable and reviewable:
+
+```text
+layer 4 clients + channels + evals MessageResponse.cancel(), channel ops, /new, eval controls
+layer 3 descendants subagent inbox cascade, remote cancel POST, adoption races
+layer 2 trigger surface POST /eve/v1/session/:id/cancel, `${continuationToken}:cancel`
+ hook, best-effort 202/409
+layer 1 turn-workflow ownership durable AbortController + cancel race in the terminating
+ turnWorkflow, cancelled-turn finalizer,
+ turn.cancelled → session.waiting
+layer 0 harness abort propagation ← this plan
+```
+
+Layers 1–2 stay blocked on the two documented upstream Workflow issues (hook dispose-before-reclaim
+determinism; duplicate step execution under one correlation id). Layer 0 involves **no hooks, no
+routes, no events, and no durable state**, so it has no upstream dependency. Layer 4 semantics
+remain governed by `research/channel-session-reset.md`.
+
+## Authoring API
+
+Two small public additions; everything else is internal plumbing.
+
+### `ToolContext.abortSignal`
+
+```ts
+export type ToolContext = SessionContext & {
+ /** Aborts when the active turn is cancelled. */
+ readonly abortSignal: AbortSignal;
+ // ...existing members
+};
+```
+
+Always present. When no upstream signal exists (all of production until layer 1), the harness
+supplies a signal that never aborts, so authored code is written once and works unchanged when
+triggers arrive.
+
+### Tool execute options
+
+`ToolDefinition.execute` gains an optional second parameter, the AI SDK's per-call tool options
+(minus `context`), carrying `toolCallId` and `abortSignal`:
+
+```ts
+export type ToolExecuteOptions = Omit<ToolExecutionOptions<unknown>, "context">;
+execute?: (input, options?: ToolExecuteOptions) => Promise<unknown> | unknown;
+```
+
+## Semantics
+
+- **Absent or never-aborted signal: byte-for-byte unchanged behavior.** The signal is optional at
+ every internal seam.
+- **Abort during a model call:** the AI SDK call rejects; the harness rethrows `signal.reason`
+ without retrying (`runModelCallWithRetries` checks the signal before each attempt and after each
+ error) and without entering the empty-response/provider-tool recovery pipeline.
+- **Abort during stream consumption:** a stream that ends quietly after abort is caught by an
+ explicit aborted-check after stream drain, so the turn can never complete "successfully" from a
+ truncated stream.
+- **Abort during compaction:** the compaction `generateText` call receives the same signal.
+- **Abort during a tool call:** best effort. The AI SDK forwards the call-level signal into every
+ tool's execute options; framework tools honor it (sandbox commands, MCP/OpenAPI fetches), authored
+ tools receive it via `ctx.abortSignal` and `options.abortSignal` and may ignore it. The harness
+ does not wait for a non-cooperating tool: the surrounding model-call promise settles on abort and
+ the straggler's result is discarded.
+- **Abort is not failure.** A new `isTurnCancellation(error)` classifier (matching the canonical
+ serializable cancellation reason, `TurnCancelledError`) is checked before retry/recovery
+ classification. `classifyModelCallError` must never return `"retry"` or `"recoverable"` for a
+ cancellation. This is the invariant #347's Windows leak violated (`AbortError` escaping into
+ `session.failed`); it is pinned by unit tests now so later layers inherit it.
+- The cancellation reason must round-trip Workflow step serialization, because layer 1 will observe
+ it across a `"use step"` boundary. `TurnCancelledError` is a plain, cause-free error with a stable
+ `name` checked by name (not `instanceof`), like `isNoOutputGeneratedError`
+ (`harness/model-call-error.ts:279`).
+
+## Implementation seams
+
+The signal enters at `TurnStepInput` and flows one direction. Workflow-core already serializes
+`AbortSignal` across `"use step"` boundaries and propagates aborts to running steps in real time
+(`.generated/compiled/@workflow/core/workflow/abort-controller.d.ts`,
+`serialization/types.d.ts:240`), so this typing is forward-compatible with layer 1's durable
+controller.
+
+```text
+TurnStepInput.abortSignal? execution/durable-session-migrations/turn-workflow.ts
+ └─ turnStep execution/workflow-steps.ts:108
+ └─ CreateExecutionNodeStepInput execution/node-step.ts:48
+ └─ ToolLoopHarnessConfig harness/types.ts:184
+ ├─ agent.stream / generate harness/tool-loop.ts:750, 813
+ ├─ post-drain aborted check harness/tool-loop.ts:760 (after emitStreamContent)
+ ├─ runModelCallWithRetries harness/tool-loop.ts:2150
+ ├─ recovery pipeline guards harness/tool-loop.ts:~830 catch block
+ ├─ maybeCompact → compactMessages harness/tool-loop.ts:2098, compaction.ts:128
+ └─ AI SDK ToolCallOptions.abortSignal (automatic once passed to stream/generate)
+ ├─ wrapToolExecute forwards options harness/tools.ts:176 (execute(input, options))
+ ├─ HarnessToolDefinition.execute harness/execute-tool.ts:25
+ ├─ authored ToolContext.abortSignal execution/tool-auth.ts:53, node-step.ts
+ ├─ sandbox sessions bound to the signal execution/sandbox/abort-bound-session.ts
+ │ (requireSandboxSession(signal) + ctx.getSandbox(); per-call signals compose
+ │ via AbortSignal.any, so callers can never opt out of turn cancellation)
+ └─ MCP/OpenAPI executeTool(name, args, { abortSignal })
+ runtime/connections/mcp-client.ts:119, openapi-client.ts:98
+```
+
+Notes:
+
+- `wrapToolExecute` is the single splice point for all tool kinds; today it drops the AI SDK
+ options (`harness/tools.ts:176`). Forwarding them reaches framework, authored, MCP, and dynamic
+ connection tools uniformly.
+- The sandbox stack already plumbs `abortSignal` end-to-end through every backend (Vercel, Docker,
+ just-bash, microsandbox); the framework sandbox tools simply never pass one. Layer 0 turns that
+ dead plumbing live, which is where "truly stopping work" (killing a running `bash` command)
+ materializes first.
+- `harness/tool-loop.ts` has drifted since #347 (e.g. hidden runtime-action tool names in the
+ stream branch, `rethrowNoOutputAsEmptyResponse`). Re-derive the diff on main; do not cherry-pick.
+- The mock model adapter (`runtime/agent/mock-model-adapter.ts`) gains abort support (#118 had a
+ 19-line version) so unit tests need no real provider.
+
+## Out of scope for layer 0
+
+- No AbortController is created in production code; no hook, route, event (`turn.cancelled`), or
+ client API exists yet.
+- No cancelled-turn epilogue: with no trigger, a turn can never abort in production. The epilogue
+ (settle → `turn.cancelled` → `session.waiting`) is layer 1, where the failure classification
+ seam (`isTurnCancellation`) built here gets consumed.
+- No delegate/remote cascade; pending runtime-action batches are untouched.
+
+## Delivery and verification
+
+One PR with a patch changeset covering both halves:
+
+1. **Core propagation** — signal threading (`TurnStepInput` → harness), model-call/retry/recovery/
+ compaction handling, `TurnCancelledError` + `isTurnCancellation`, `wrapToolExecute` options
+ forwarding, `ToolContext.abortSignal`, docs for the public additions.
+2. **Framework tool executors** — sandbox tools pass `options.abortSignal` into `sandbox.run` and
+ file I/O; `web_fetch` composes the signal with its timeout; MCP/OpenAPI `executeTool` accepts
+ and threads a signal into the underlying request.
+
+Tests (no hooks → unit + integration tiers only):
+
+- unit: retries never resume after abort; recovery pipeline never runs on abort;
+ `classifyModelCallError` interplay with `isTurnCancellation`; `wrapToolExecute` forwards options;
+ compaction receives the signal; post-drain aborted check.
+- integration (`tool-loop-cancellation.integration.test.ts`): a real `ToolLoopAgent` over a
+ cancellable `MockLanguageModelV3` — abort mid-stream settles with the canonical cancellation and
+ no failure events; an executing tool observes a live signal and its straggler result is
+ discarded; an inert signal produces output identical to no signal.
+- #347's harness test additions (`tool-loop.test.ts` +45, `tools.test.ts` +50) were the starting
+ corpus; its e2e fixture (`agent-cancellation`, `wait-for-cancellation` tool) stays shelved until
+ layer 2 provides a trigger.