From e28244e1dc5adcfd589c8884ff352383a5afeb58 Mon Sep 17 00:00:00 2001 From: James Long Date: Tue, 10 Nov 2026 14:31:53 +0000 Subject: [PATCH 1/2] feat(plugin): let promise tools stop cooperatively through their signal A promise tool's `ctx.signal` is now a getter. Reading it awaits the call's `cancel`, so the step counts the tool as one that stops on its own: on the user's stop the signal aborts, and whatever the tool then returns or rejects with is reported as the call's result, through execute.after hooks. The signal still aborts when the call is interrupted (a server shutdown, or the 5 s safety net). A tool that never reads the signal is interrupted at once, as before; contexts without `cancel` (CodeMode nested calls) register nothing. The registration ends when the call does. User decisions: - Promise tools opt into a cooperative stop by reading `ctx.signal` - `signal` fires on the user's stop request --- .../test/plugin/promise-tool-cancel.test.ts | 246 ++++++++++++++++++ packages/plugin/src/promise/adapter.ts | 33 ++- packages/plugin/src/promise/tool.ts | 6 + 3 files changed, 279 insertions(+), 6 deletions(-) create mode 100644 packages/core/test/plugin/promise-tool-cancel.test.ts diff --git a/packages/core/test/plugin/promise-tool-cancel.test.ts b/packages/core/test/plugin/promise-tool-cancel.test.ts new file mode 100644 index 000000000000..a0c446170cd2 --- /dev/null +++ b/packages/core/test/plugin/promise-tool-cancel.test.ts @@ -0,0 +1,246 @@ +import { describe, expect } from "bun:test" +import { ai, LanguageModel, LLMEvent } from "@opencode/ai/effect" +import { OpenAIChat } from "@opencode/ai/protocols/openai-chat" +import { TestLLM } from "@opencode/ai/testing" +import { Agent } from "@opencode/core/agent" +import { Bus } from "@opencode/core/bus" +import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder" +import { Location } from "@opencode/core/location" +import { Plugin } from "@opencode/core/plugin" +import { PluginHooks } from "@opencode/core/plugin/hooks" +import { PluginHost } from "@opencode/core/plugin/host" +import { PluginPromise } from "@opencode/core/plugin/promise" +import { Session } from "@opencode/core/session" +import { SessionEvent } from "@opencode/core/session/event" +import { SessionMessage } from "@opencode/core/session/message" +import { SessionRunnerModel } from "@opencode/core/session/runner/model" +import { SessionStep } from "@opencode/core/session/runner/step" +import { Snapshot } from "@opencode/core/snapshot" +import { Tool } from "@opencode/core/tool" +import { ToolOutput } from "@opencode/core/tool-output" +import { Deferred, Effect, Exit, Fiber, Layer } from "effect" +import { TestClock } from "effect/testing" +import { testEffect } from "../lib/effect" +import { PluginTestLayer } from "./fixture" + +const it = testEffect(Layer.merge(PluginTestLayer, TestLLM.testLayer())) + +const model = SessionRunnerModel.resolved( + LanguageModel.make({ id: "test-model", provider: "test", route: OpenAIChat.route }), + { + capabilities: { tools: true, input: ["text"], output: ["text"] }, + limit: { context: 100_000, output: 1_000 }, + cost: [], + }, +) + +const empty = { type: "object", properties: {}, additionalProperties: false } as const + +// Registers the promise tools the tests call. Each reports the signal it was given through `started`. +const register = Effect.fn(function* (started: Deferred.Deferred) { + const plugins = yield* Plugin.Service + const report = (signal: AbortSignal | undefined) => Effect.runSync(Deferred.succeed(started, signal)) + yield* PluginPromise.fromPromise({ + id: "stoppable-tools", + async setup(context) { + await context.tool.transform((editor) => { + editor.add({ + name: "listens", + description: "Rejects once stopped", + input: empty, + options: { codemode: false }, + execute: (_input, context) => + new Promise((_resolve, reject) => { + const signal = context.signal + signal.addEventListener("abort", () => reject(new Error("stopped with partial work")), { once: true }) + report(signal) + }), + }) + editor.add({ + name: "deaf", + description: "Never reads its signal", + input: empty, + options: { codemode: false }, + execute: () => + new Promise(() => { + report(undefined) + }), + }) + editor.add({ + name: "ignores", + description: "Reads its signal but never settles", + input: empty, + options: { codemode: false }, + execute: (_input, context) => + new Promise(() => { + report(context.signal) + }), + }) + editor.add({ + name: "nested", + description: "Called from CodeMode; reads its signal", + input: empty, + execute: (_input, context) => + new Promise((_resolve, reject) => { + const signal = context.signal + signal.addEventListener("abort", () => reject(new Error("nested stopped")), { once: true }) + report(signal) + }), + }) + }) + }, + }).effect(yield* PluginHost.make(plugins, "test")) +}) + +// Runs one step calling `call`, stops it once the tool started (as the user, or as a server shutdown), and returns +// how its call ended. +const stop = Effect.fn(function* ( + call: LLMEvent, + reason: "user" | "shutdown", + afterInterrupt: (interrupting: Fiber.Fiber) => Effect.Effect = () => Effect.void, +) { + const llm = yield* TestLLM.Test + const tools = yield* Tool.Service + const bus = yield* Bus.Service + const sessions = yield* Session.Service + const started = yield* Deferred.make() + yield* register(started) + const failures: SessionEvent.Tool.Failed["data"][] = [] + yield* bus.listen((event) => + Effect.sync(() => { + if (event.type === SessionEvent.Tool.Failed.type) failures.push(event.data as SessionEvent.Tool.Failed["data"]) + }), + ) + const steps = yield* SessionStep.make.pipe( + Effect.provide( + Layer.mock(Snapshot.Service)({ + capture: () => Effect.succeed(undefined), + files: () => Effect.succeed([]), + }), + ), + Effect.provide(AppNodeBuilder.build(ToolOutput.node)), + ) + yield* llm.push( + TestLLM.complete({ reason: { normalized: "tool-calls" }, usage: { inputTokens: 1, outputTokens: 1 } }, call), + ) + const snapshot = yield* tools.snapshot() + const location = yield* Location.Service + const session = yield* sessions.create({ + location: Location.Ref.make({ directory: location.directory, workspaceID: location.workspaceID }), + }) + const attempt = yield* steps + .attempt({ + isLocationClosed: () => false, + interruption: () => reason, + sessionID: session.id, + assistantMessageID: SessionMessage.ID.create(), + agent: Agent.defaultID, + model, + prepared: { + retry: () => Effect.void, + request: ai.request({ model: model.model, prompt: "Run a tool" }), + options: {}, + executeTool: (input) => snapshot.execute(input), + }, + retry: () => Effect.succeed({ retry: false }), + recoverContinuation: true, + recoverOverflow: Effect.succeed(false), + }) + .pipe(Effect.forkChild({ startImmediately: true })) + const signal = yield* Deferred.await(started) + const startedAt = Date.now() + const interrupting = yield* Fiber.interrupt(attempt).pipe(Effect.forkChild({ startImmediately: true })) + yield* afterInterrupt(interrupting) + yield* Fiber.join(interrupting) + return { + exit: yield* Fiber.await(attempt), + elapsed: Date.now() - startedAt, + failures, + requests: (yield* llm.requests()).length, + signal, + } +}) + +const generic = { type: "aborted", message: "Tool execution interrupted" } + +describe("Promise tool cooperative stop", () => { + it.live("reports the error of a tool that read its signal and gave up when the user stopped it", () => + Effect.gen(function* () { + const hooks = yield* PluginHooks.Service + const after: string[] = [] + yield* hooks.register("tool", "execute.after", (event) => + Effect.sync(() => { + if (event.status === "error") after.push(event.error.message) + }), + ) + const { exit, failures, requests, signal } = yield* stop( + LLMEvent.toolCall({ id: "call-listens", name: "listens", input: {} }), + "user", + ) + expect(Exit.hasInterrupts(exit)).toBe(true) + expect(requests).toBe(1) + expect(signal?.aborted).toBe(true) + expect(after).toEqual(["stopped with partial work"]) + expect(failures).toMatchObject([{ id: "call-listens", error: { message: "stopped with partial work" } }]) + }), + ) + + it.live("interrupts a tool that never read its signal at once", () => + Effect.gen(function* () { + const { exit, elapsed, failures, requests } = yield* stop( + LLMEvent.toolCall({ id: "call-deaf", name: "deaf", input: {} }), + "user", + ) + expect(Exit.hasInterrupts(exit)).toBe(true) + expect(requests).toBe(1) + // Well under the 5 s a listening tool is given. + expect(elapsed).toBeLessThan(2_000) + expect(failures).toMatchObject([{ id: "call-deaf", error: generic }]) + }), + ) + + it.effect("interrupts a tool that read its signal but ignored the stop after the safety net", () => + Effect.gen(function* () { + const { exit, failures, signal } = yield* stop( + LLMEvent.toolCall({ id: "call-ignores", name: "ignores", input: {} }), + "user", + // The stop waits for a tool that read its signal, on the clock; this one never settles. + (interrupting) => + Effect.gen(function* () { + yield* Effect.promise(() => Bun.sleep(50)) + expect(interrupting.pollUnsafe()).toBeUndefined() + yield* TestClock.adjust("5 seconds") + }), + ) + expect(Exit.hasInterrupts(exit)).toBe(true) + expect(signal?.aborted).toBe(true) + expect(failures).toMatchObject([{ id: "call-ignores", error: generic }]) + }), + ) + + it.live("aborts the signal and records the generic result on a server shutdown", () => + Effect.gen(function* () { + const { exit, failures, signal } = yield* stop( + LLMEvent.toolCall({ id: "call-shutdown", name: "listens", input: {} }), + "shutdown", + ) + expect(Exit.hasInterrupts(exit)).toBe(true) + expect(signal?.aborted).toBe(true) + expect(failures).toMatchObject([{ id: "call-shutdown", error: generic }]) + }), + ) + + it.live("never lets a promise tool called from CodeMode take the execute call's stop", () => + Effect.gen(function* () { + const { exit, elapsed, failures, signal } = yield* stop( + LLMEvent.toolCall({ id: "call-execute", name: "execute", input: { code: "return await tools.nested({})" } }), + "user", + ) + expect(Exit.hasInterrupts(exit)).toBe(true) + // The execute call never awaited the stop, so it is interrupted at once, its nested call with it. + expect(elapsed).toBeLessThan(2_000) + expect(signal?.aborted).toBe(true) + expect(failures).toMatchObject([{ id: "call-execute", error: generic }]) + }), + ) +}) diff --git a/packages/plugin/src/promise/adapter.ts b/packages/plugin/src/promise/adapter.ts index 62387459a660..144a8fe5d0b5 100644 --- a/packages/plugin/src/promise/adapter.ts +++ b/packages/plugin/src/promise/adapter.ts @@ -692,11 +692,32 @@ const toolHook: { const executePromiseTool = (tool: Info, input: any, context: Tool.Context) => Effect.tryPromise({ - try: (signal) => - tool.execute(input, { - ...context, - signal, - progress: (update) => Effect.runPromise(context.progress(update), { signal }), - }), + try: (interrupted) => { + // `signal` aborts when the call is interrupted, and also when the user stops the call once the tool has read + // it. Reading it awaits `cancel`, which tells the step this tool stops on its own instead of being interrupted. + const stopped = new AbortController() + const finished = new AbortController() + const signal = AbortSignal.any([interrupted, stopped.signal]) + const cancel = context.cancel + let listening = false + const listen = () => { + if (listening || !cancel) return + listening = true + Effect.runPromise(cancel, { signal: AbortSignal.any([interrupted, finished.signal]) }).then( + () => stopped.abort(), + () => {}, + ) + } + return Promise.resolve( + tool.execute(input, { + ...context, + get signal() { + listen() + return signal + }, + progress: (update) => Effect.runPromise(context.progress(update), { signal: interrupted }), + }), + ).finally(() => finished.abort()) + }, catch: toolError, }) diff --git a/packages/plugin/src/promise/tool.ts b/packages/plugin/src/promise/tool.ts index 7de64a8cbe2b..e2a05b47f661 100644 --- a/packages/plugin/src/promise/tool.ts +++ b/packages/plugin/src/promise/tool.ts @@ -9,6 +9,12 @@ import type { Types } from "effect" import type { Hooks, Transform } from "./registration.js" export interface ToolContext extends Omit { + /** + * Aborted when the call is interrupted, and when the user stops the call if the tool has read this property. + * Reading it (spreading the context reads it too) opts the tool into a cooperative stop: on the user's stop the + * signal aborts and whatever the tool then returns or throws is still reported as the call's result. A tool + * that never reads it, or does not settle soon after the stop, is interrupted. + */ readonly signal: AbortSignal readonly progress: (update: Tool.Metadata) => Promise } From b55a9bf208708699b39fbdc0ef1a8a987e3861fd Mon Sep 17 00:00:00 2001 From: James Long Date: Tue, 10 Nov 2026 18:45:30 +0000 Subject: [PATCH 2/2] fix(plugin): keep cancel out of the promise tool context The promise context no longer carries `cancel` at runtime; promise tools stop through `signal` only. A test covers a tool that resolves with a partial result when stopped: the result is recorded as the call's, and the step still ends interrupted with one model request. The safety-net test waits on the fiber scheduler instead of real time. User decisions: - Destructure cancel out of the promise context - Test a cooperative promise tool that resolves on abort - Replace the real-time sleep in the TestClock test --- .../test/plugin/promise-tool-cancel.test.ts | 35 ++++++++++++++++++- packages/plugin/src/promise/adapter.ts | 5 +-- 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/packages/core/test/plugin/promise-tool-cancel.test.ts b/packages/core/test/plugin/promise-tool-cancel.test.ts index a0c446170cd2..7070e605f84c 100644 --- a/packages/core/test/plugin/promise-tool-cancel.test.ts +++ b/packages/core/test/plugin/promise-tool-cancel.test.ts @@ -56,6 +56,18 @@ const register = Effect.fn(function* (started: Deferred.Deferred + new Promise<{ content: string }>((resolve) => { + const signal = context.signal + signal.addEventListener("abort", () => resolve({ content: "partial result" }), { once: true }) + report(signal) + }), + }) editor.add({ name: "deaf", description: "Never reads its signal", @@ -106,9 +118,11 @@ const stop = Effect.fn(function* ( const started = yield* Deferred.make() yield* register(started) const failures: SessionEvent.Tool.Failed["data"][] = [] + const successes: SessionEvent.Tool.Success["data"][] = [] yield* bus.listen((event) => Effect.sync(() => { if (event.type === SessionEvent.Tool.Failed.type) failures.push(event.data as SessionEvent.Tool.Failed["data"]) + if (event.type === SessionEvent.Tool.Success.type) successes.push(event.data as SessionEvent.Tool.Success["data"]) }), ) const steps = yield* SessionStep.make.pipe( @@ -156,6 +170,7 @@ const stop = Effect.fn(function* ( exit: yield* Fiber.await(attempt), elapsed: Date.now() - startedAt, failures, + successes, requests: (yield* llm.requests()).length, signal, } @@ -185,6 +200,23 @@ describe("Promise tool cooperative stop", () => { }), ) + it.live("records the result of a tool that read its signal and resolved with what it had when stopped", () => + Effect.gen(function* () { + const { exit, failures, successes, requests, signal } = yield* stop( + LLMEvent.toolCall({ id: "call-resolves", name: "resolves", input: {} }), + "user", + ) + // The call keeps its result, but the step still ends interrupted, without another model request. + expect(Exit.hasInterrupts(exit)).toBe(true) + expect(requests).toBe(1) + expect(signal?.aborted).toBe(true) + expect(failures).toEqual([]) + expect(successes).toMatchObject([ + { id: "call-resolves", content: [{ type: "text", text: expect.stringContaining("partial result") }] }, + ]) + }), + ) + it.live("interrupts a tool that never read its signal at once", () => Effect.gen(function* () { const { exit, elapsed, failures, requests } = yield* stop( @@ -207,7 +239,8 @@ describe("Promise tool cooperative stop", () => { // The stop waits for a tool that read its signal, on the clock; this one never settles. (interrupting) => Effect.gen(function* () { - yield* Effect.promise(() => Bun.sleep(50)) + // Let the stop reach the tool; with the clock held, it is still waiting for it. + for (let turn = 0; turn < 20; turn++) yield* Effect.yieldNow expect(interrupting.pollUnsafe()).toBeUndefined() yield* TestClock.adjust("5 seconds") }), diff --git a/packages/plugin/src/promise/adapter.ts b/packages/plugin/src/promise/adapter.ts index 144a8fe5d0b5..a45c2fc5909a 100644 --- a/packages/plugin/src/promise/adapter.ts +++ b/packages/plugin/src/promise/adapter.ts @@ -698,7 +698,8 @@ const executePromiseTool = (tool: Info, input: any, context: Tool.Context) => const stopped = new AbortController() const finished = new AbortController() const signal = AbortSignal.any([interrupted, stopped.signal]) - const cancel = context.cancel + // `cancel` stays out of the promise context; promise tools stop through `signal`. + const { cancel, ...rest } = context let listening = false const listen = () => { if (listening || !cancel) return @@ -710,7 +711,7 @@ const executePromiseTool = (tool: Info, input: any, context: Tool.Context) => } return Promise.resolve( tool.execute(input, { - ...context, + ...rest, get signal() { listen() return signal