The Open Framework for Building Agents
feat(eve): tools - add durable sleep tool (#1416)
Andrew Barba255027e7c4c5
diff --git a/.changeset/durable-sleep-tool.md b/.changeset/durable-sleep-tool.mdnew file mode 100644index 000000000..3077e7d50--- /dev/null+++ b/.changeset/durable-sleep-tool.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add an opt-in durable `sleep` tool from `eve/tools/sleep`. Agents can export `sleep()` from `agent/tools/sleep.ts` to let the model pause a turn before checking progress or status again without holding an application runtime open.diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.mdindex 0f67c97c5..5c0e46ae3 100644--- a/docs/concepts/default-harness.md+++ b/docs/concepts/default-harness.md@@ -103,6 +103,18 @@ export default experimental_workflow({ maxSubagents: 100 });With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most the configured `maxSubagents` calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).+## The opt-in `sleep` tool++The framework also ships a durable `sleep` tool, but does not add it to agents by default. Enable it with `agent/tools/sleep.ts`:++```ts+import { sleep } from "eve/tools/sleep";++export default sleep();+```++The model calls it with `{ seconds }` when it is useful to wait before checking progress or status again. The pause sleeps the durable turn workflow, so it does not hold an application runtime open, and the same turn continues automatically when the duration elapses. If one model response makes concurrent `sleep` calls, eve waits for the longest requested duration.+## What to read next- [Tools](../tools): define your own tools, gate them on approval, and shape their output with `toModelOutput`diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.mdindex 95b3c40e6..a5002ac5a 100644--- a/docs/reference/typescript-api.md+++ b/docs/reference/typescript-api.md@@ -52,7 +52,7 @@ export default defineTool({| `mockModel` | `eve/evals` | Deterministic fixture agent models | [Evals](../evals/overview) || `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) |-A few non-`define*` helpers round out the set: `disableTool` and `experimental_workflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools` for the `experimental_workflow(...)` config shape.+A few non-`define*` helpers round out the set: `disableTool` and `experimental_workflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), `sleep` from `eve/tools/sleep`, the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools` for the `experimental_workflow(...)` config shape.## Runtime context (`ctx`)@@ -74,6 +74,7 @@ A few non-`define*` helpers round out the set: `disableTool` and `experimental_w| `eve/tools` | `defineTool`, `defineDynamic`, `disableTool`, `experimental_workflow` || `eve/tools/defaults` | the built-in tools as plain values || `eve/tools/approval` | `always`, `once`, `never` |+| `eve/tools/sleep` | opt-in durable `sleep` tool || `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection` || `eve/channels` | `defineChannel`, route verbs || `eve/channels/eve` | `eveChannel` |diff --git a/packages/eve/package.json b/packages/eve/package.jsonindex b385c9344..52877a835 100644--- a/packages/eve/package.json+++ b/packages/eve/package.json@@ -101,6 +101,11 @@"import": "./dist/src/public/tools/approval/index.js","default": "./dist/src/public/tools/approval/index.js"},+ "./tools/sleep": {+ "types": "./dist/src/public/tools/sleep/index.d.ts",+ "import": "./dist/src/public/tools/sleep/index.js",+ "default": "./dist/src/public/tools/sleep/index.js"+ },"./tools": {"types": "./dist/src/public/tools/index.d.ts","import": "./dist/src/public/tools/index.js",diff --git a/packages/eve/src/execution/turn-workflow.test.ts b/packages/eve/src/execution/turn-workflow.test.tsindex 9f352ebd0..5329a2fb2 100644--- a/packages/eve/src/execution/turn-workflow.test.ts+++ b/packages/eve/src/execution/turn-workflow.test.ts@@ -16,10 +16,12 @@ import { turnStep } from "#execution/workflow-steps.js";const resumeHookMock = vi.fn();const createHookMock = vi.fn();+const sleepMock = vi.fn(async (_duration: unknown) => {});vi.mock("#compiled/@workflow/core/index.js", () => ({createHook: (...args: unknown[]) => createHookMock(...args),getWorkflowMetadata: vi.fn(() => ({ url: "https://eve.example.com" })),+ sleep: (duration: unknown) => sleepMock(duration),}));vi.mock("#compiled/@workflow/core/runtime.js", () => ({@@ -59,6 +61,7 @@ describe("turnWorkflow", () => {vi.clearAllMocks();resumeHookMock.mockReset();createHookMock.mockReset();+ sleepMock.mockClear();});it("notifies the driver when a turn completes", async () => {@@ -155,6 +158,60 @@ describe("turnWorkflow", () => {);});+ it("durably sleeps the turn before continuing the tool loop", async () => {+ const sessionState = createSessionState();+ vi.mocked(turnStep)+ .mockResolvedValueOnce({+ action: "continue",+ sleepDurationMs: 2_500,+ serializedContext: { state: "sleeping" },+ sessionState,+ })+ .mockResolvedValueOnce({+ action: "done",+ output: "checked again",+ serializedContext: { state: "done" },+ sessionState,+ });++ const { input } = createInput({ sessionState });+ await turnWorkflow(input);++ expect(sleepMock).toHaveBeenCalledExactlyOnceWith(2_500);+ expect(sleepMock.mock.invocationCallOrder[0]).toBeLessThan(+ vi.mocked(turnStep).mock.invocationCallOrder[1]!,+ );+ });++ it("durably sleeps a turn-owned workflow before continuing the tool loop", async () => {+ const sessionState = createSessionState();+ installInbox([]);+ vi.mocked(turnStep)+ .mockResolvedValueOnce({+ action: "continue",+ sleepDurationMs: 1_250,+ serializedContext: { state: "sleeping" },+ sessionState,+ })+ .mockResolvedValueOnce({+ action: "done",+ output: "checked again",+ serializedContext: { state: "done" },+ sessionState,+ });++ const { input } = createInput({+ driverCapabilities: { turnInbox: true },+ sessionState,+ });+ await turnWorkflow(input);++ expect(sleepMock).toHaveBeenCalledExactlyOnceWith(1_250);+ expect(sleepMock.mock.invocationCallOrder[0]).toBeLessThan(+ vi.mocked(turnStep).mock.invocationCallOrder[1]!,+ );+ });+it("parks when an authorization is pending", async () => {const sessionState = createSessionState();vi.mocked(turnStep).mockResolvedValueOnce({diff --git a/packages/eve/src/execution/turn-workflow.ts b/packages/eve/src/execution/turn-workflow.tsindex e1250ff19..53d28536e 100644--- a/packages/eve/src/execution/turn-workflow.ts+++ b/packages/eve/src/execution/turn-workflow.ts@@ -1,4 +1,8 @@-import { createHook, getWorkflowMetadata } from "#compiled/@workflow/core/index.js";+import {+ createHook,+ getWorkflowMetadata,+ sleep as workflowSleep,+} from "#compiled/@workflow/core/index.js";import type { DeliverHookPayload } from "#channel/types.js";import { cancelDescendantTurnsStep } from "#execution/cancel-descendant-turns-step.js";@@ -129,6 +133,14 @@ async function runTurnOwnedWorkflow(input: TurnWorkflowInput): Promise<void> {return;}+ if (result.sleepDurationMs !== undefined) {+ const outcome = await waitForTurnSleep(result.sleepDurationMs, cancellation);+ if (outcome === "cancel") {+ await finishCancelledTurn({ bufferedDeliveries, cancellation, cursor });+ return;+ }+ }+if (result.action === "done") {await cancellation?.dispose();await cursor.finish(@@ -240,6 +252,15 @@ async function finishCancelledTurn(input: {);}+async function waitForTurnSleep(+ durationMs: number,+ cancellation: TurnCancellationControl | undefined,+): Promise<"cancel" | "slept"> {+ if (cancellation?.signal.aborted === true) return "cancel";+ const slept = workflowSleep(durationMs).then(() => "slept" as const);+ return cancellation === undefined ? slept : Promise.race([slept, cancellation.requested]);+}+// These sentinels stay outside `RuntimeActionResult`. That union is the// schema-validated wire type projected into harness resume calls; these are// turn-workflow control outcomes that never leave the workflow.@@ -352,6 +373,10 @@ async function runLegacyTurnWorkflow(input: TurnWorkflowInput): Promise<void> {while (true) {const result = await turnStep(currentStepInput);+ if (result.action !== "cancelled" && result.sleepDurationMs !== undefined) {+ await workflowSleep(result.sleepDurationMs);+ }+if (result.action === "done") {await sendTurnControlStep({controlToken: input.completionToken,diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.tsindex 97ee8f682..d51c084e3 100644--- a/packages/eve/src/execution/workflow-steps.test.ts+++ b/packages/eve/src/execution/workflow-steps.test.ts@@ -18,6 +18,7 @@ import {getPendingRuntimeActionBatch,setPendingRuntimeActionBatch,} from "#harness/runtime-actions.js";+import { requestTurnSleep } from "#harness/turn-sleep.js";import { getPendingAuthorization, setPendingAuthorization } from "#harness/authorization.js";import type { HarnessSession, StepResult } from "#harness/types.js";import { createEmptyHookRegistry } from "#runtime/hooks/registry.js";@@ -778,6 +779,36 @@ describe("turnStep", () => {});});+ it("projects a requested sleep onto the durable step result", async () => {+ const session = createStubSession();+ installSessionStoreMocks([session]);+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {+ return async (stepSession): Promise<StepResult> => {+ requestTurnSleep(2_500);+ return {+ next: async () => ({ next: null, session: stepSession }),+ session: stepSession,+ };+ };+ });++ const result = await turnStep({+ input: {+ kind: "deliver",+ payloads: [{ message: "wait before checking" }],+ },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result).toMatchObject({+ action: "continue",+ sleepDurationMs: 2_500,+ });+ expect(result.serializedContext).not.toHaveProperty("eve.pendingTurnSleepDuration");+ });+it("persists onDeliver context into the next durable step", async () => {const seenMessages: string[] = [];const session = createStubSession();diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.tsindex dfc3c031e..b7a37bf14 100644--- a/packages/eve/src/execution/workflow-steps.ts+++ b/packages/eve/src/execution/workflow-steps.ts@@ -20,6 +20,7 @@ import { runStep } from "#context/run-step.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import { getHarnessEmissionState } from "#harness/emission.js";import { preserveSerializedAgentTraceState } from "#harness/agent-trace-context-store.js";+import { readTurnSleepDurationMs } from "#harness/turn-sleep.js";import { isTurnCancellation, throwIfTurnAborted } from "#harness/turn-cancellation.js";import { setChannelContext } from "#execution/channel-context.js";import { hasPendingInputBatch } from "#harness/input-requests.js";@@ -96,6 +97,11 @@ export type DurableStepResult =readonly action: "continue" | "done";readonly output?: unknown;readonly isError?: boolean;+ /**+ * Optional durable pause for the turn workflow to fulfill before+ * dispatching this result's next action.+ */+ readonly sleepDurationMs?: number;readonly serializedContext: Record<string, unknown>;readonly sessionState: DurableSessionState;/** Session-total token usage; set on `done` when the session spent any. */@@ -112,12 +118,14 @@ export type DurableStepResult =readonly hasPendingAuthorization: boolean;readonly hasPendingInputBatch: boolean;readonly pendingRuntimeActionKeys?: readonly string[];+ readonly sleepDurationMs?: number;readonly serializedContext: Record<string, unknown>;readonly sessionState: DurableSessionState;}| {readonly action: "dispatch-workflow-runtime-actions";readonly pendingRuntimeActionKeys: readonly string[];+ readonly sleepDurationMs?: number;readonly serializedContext: Record<string, unknown>;readonly sessionState: DurableSessionState;};@@ -418,6 +426,8 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResustepResult = { ...stepResult, session: rekeyed };const nextState = createDurableSessionState({ session: stepResult.session });+ const sleepDurationMs = readTurnSleepDurationMs(ctx);+ const sleepTransition = sleepDurationMs === undefined ? {} : { sleepDurationMs };if (stepResult.next !== null &&@@ -430,6 +440,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResuaction: "done",output: stepResult.next.output,isError: stepResult.next.isError,+ ...sleepTransition,serializedContext: nextSerializedContext,sessionState: nextState,usage: sessionTotals === undefined ? undefined : toUsage(sessionTotals),@@ -449,6 +460,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResupendingRuntimeActionKeys: getRuntimeActionKeysFromWorkflowInterrupt(workflowInterrupt.interrupt,),+ ...sleepTransition,serializedContext: nextSerializedContext,sessionState: nextState,};@@ -457,6 +469,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResureturn {action: "park",...derivePendingState(stepResult.session),+ ...sleepTransition,serializedContext: nextSerializedContext,sessionState: nextState,};@@ -465,6 +478,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResuwriter.releaseLock();return {action: "continue",+ ...sleepTransition,serializedContext: nextSerializedContext,sessionState: nextState,};diff --git a/packages/eve/src/harness/turn-sleep.ts b/packages/eve/src/harness/turn-sleep.tsnew file mode 100644index 000000000..d4da47d4e--- /dev/null+++ b/packages/eve/src/harness/turn-sleep.ts@@ -0,0 +1,34 @@+import { type AlsContext, type ContextContainer, loadContext } from "#context/container.js";+import { ContextKey } from "#context/key.js";++const PendingTurnSleepDurationKey = new ContextKey<number>("eve.pendingTurnSleepDuration");++/**+ * Requests a durable pause before the turn's next action.+ *+ * The request is step-local: tool execution records it in virtual context,+ * then `turnStep` projects it onto its result for `turnWorkflow` to fulfill.+ * Concurrent sleep calls share the wait, so the longest requested duration+ * wins.+ */+export function requestTurnSleep(durationMs: number): void {+ if (!Number.isSafeInteger(durationMs) || durationMs <= 0) {+ throw new Error("Sleep duration must resolve to a positive safe integer of milliseconds.");+ }++ const ctx = loadContext();+ const pendingDurationMs = ctx.get(PendingTurnSleepDurationKey) ?? 0;+ asContainer(ctx).setVirtualContext(+ PendingTurnSleepDurationKey,+ Math.max(pendingDurationMs, durationMs),+ );+}++/** Returns the longest sleep requested during the current turn step. */+export function readTurnSleepDurationMs(ctx: AlsContext): number | undefined {+ return ctx.get(PendingTurnSleepDurationKey);+}++function asContainer(ctx: AlsContext): ContextContainer {+ return ctx as ContextContainer;+}diff --git a/packages/eve/src/public/tools/sleep/index.test.ts b/packages/eve/src/public/tools/sleep/index.test.tsnew file mode 100644index 000000000..c1737028a--- /dev/null+++ b/packages/eve/src/public/tools/sleep/index.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from "vitest";++import { ContextContainer, contextStorage } from "#context/container.js";+import { readTurnSleepDurationMs } from "#harness/turn-sleep.js";+import { sleep } from "#public/tools/sleep/index.js";++describe("sleep", () => {+ it("defines a model-facing tool that requests a turn sleep in seconds", async () => {+ const definition = sleep();+ const ctx = new ContextContainer();++ const output = await contextStorage.run(ctx, () =>+ definition.execute({ seconds: 2.5 }, {} as never),+ );++ expect(definition.description).toContain("before continuing");+ expect(output).toEqual({ waitedSeconds: 2.5 });+ expect(readTurnSleepDurationMs(ctx)).toBe(2_500);+ });++ it("shares concurrent waits by keeping the longest duration", async () => {+ const definition = sleep();+ const ctx = new ContextContainer();++ await contextStorage.run(ctx, async () => {+ await definition.execute({ seconds: 4 }, {} as never);+ await definition.execute({ seconds: 1 }, {} as never);+ });++ expect(readTurnSleepDurationMs(ctx)).toBe(4_000);+ });+});diff --git a/packages/eve/src/public/tools/sleep/index.ts b/packages/eve/src/public/tools/sleep/index.tsnew file mode 100644index 000000000..d11fc1642--- /dev/null+++ b/packages/eve/src/public/tools/sleep/index.ts@@ -0,0 +1,34 @@+import { defineTool, type ToolDefinition } from "#public/definitions/tool.js";+import {+ executeSleepTool,+ SLEEP_INPUT_SCHEMA,+ SLEEP_OUTPUT_SCHEMA,+ SLEEP_TOOL_DESCRIPTION,+ type SleepToolInput,+ type SleepToolOutput,+} from "#runtime/framework-tools/sleep.js";++export type { SleepToolInput, SleepToolOutput };++/**+ * Defines eve's opt-in durable `sleep` tool.+ *+ * Export it from `agent/tools/sleep.ts`:+ *+ * ```ts+ * import { sleep } from "eve/tools/sleep";+ *+ * export default sleep();+ * ```+ *+ * Calls pause the durable turn workflow rather than holding an application+ * runtime open with an in-process timer.+ */+export function sleep(): ToolDefinition<SleepToolInput, SleepToolOutput> {+ return defineTool({+ description: SLEEP_TOOL_DESCRIPTION,+ execute: executeSleepTool,+ inputSchema: SLEEP_INPUT_SCHEMA,+ outputSchema: SLEEP_OUTPUT_SCHEMA,+ });+}diff --git a/packages/eve/src/runtime/framework-tools/sleep.ts b/packages/eve/src/runtime/framework-tools/sleep.tsnew file mode 100644index 000000000..4e23d115f--- /dev/null+++ b/packages/eve/src/runtime/framework-tools/sleep.ts@@ -0,0 +1,28 @@+import { z } from "#compiled/zod/index.js";++import { requestTurnSleep } from "#harness/turn-sleep.js";++const MAX_SLEEP_SECONDS = Math.floor(Number.MAX_SAFE_INTEGER / 1_000);++export const SLEEP_TOOL_DESCRIPTION =+ "Wait for a specified amount of time before continuing. Use this when a process or condition needs time to change before it is useful to check its progress or status again.";++export const SLEEP_INPUT_SCHEMA = z.strictObject({+ seconds: z.number().positive().max(MAX_SLEEP_SECONDS).describe("How long to wait, in seconds."),+});++export const SLEEP_OUTPUT_SCHEMA = z.strictObject({+ waitedSeconds: z.number().positive(),+});++export type SleepToolInput = z.infer<typeof SLEEP_INPUT_SCHEMA>;+export type SleepToolOutput = z.infer<typeof SLEEP_OUTPUT_SCHEMA>;++/**+ * Records a durable wait for the owning turn workflow to fulfill after the+ * current atomic step finishes.+ */+export function executeSleepTool(input: SleepToolInput): SleepToolOutput {+ requestTurnSleep(Math.ceil(input.seconds * 1_000));+ return { waitedSeconds: input.seconds };+}