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.mdnew file mode 100644index 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.mdxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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[]): HarnessTotools.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.tsindex 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.tsindex 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.tsindex 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): Stconst 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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<WebFetchMAX_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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 insteaddiff --git a/packages/eve/src/harness/tool-interrupts.test.ts b/packages/eve/src/harness/tool-interrupts.test.tsindex 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.tsnew file mode 100644index 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.tsindex 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-requeimport { 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 thediff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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-toimport { 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.tsindex 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.tsindex 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-toimport { 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.tsindex 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-toimport { 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.tsindex 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/sandboximport { 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.tsindex 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.tsindex 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.tsindex 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. Dispatchdiff --git a/research/turn-cancellation-harness-abort.md b/research/turn-cancellation-harness-abort.mdnew file mode 100644index 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.