Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): gate workflow dispatch on approval (#3983)

OwenKephartbb7074318661
diff --git a/.changeset/workflow-tool-approval-dispatch.md b/.changeset/workflow-tool-approval-dispatch.md
new file mode 100644
index 000000000..3395bacf8
--- /dev/null
+++ b/.changeset/workflow-tool-approval-dispatch.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Workflow tools now wait for approval before starting, and calls denied by a person or policy never run. An approved workflow starts when it is approved.
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.md
index be7d2c857..355ea8732 100644
--- a/docs/tools/human-in-the-loop.md
+++ b/docs/tools/human-in-the-loop.md
@@ -13,7 +13,9 @@ An approval ends the turn and the session parks at `session.waiting`. A question
## Approvals
-Approval is a property of a [tool](/docs/tools) that gates it before it runs. The policy can decide automatically or pause for a person. Set `approval` with the helpers from `eve/tools/approval`:
+Approval is a property of a [tool](/docs/tools) that gates it before it runs. This includes [workflow tools](/docs/tools/workflows): a call waiting for approval does not start its workflow, and a call denied by a policy or person never runs. Other calls from the same model response that do not require approval can proceed while it waits.
+
+The policy can decide automatically or pause for a person. Set `approval` with the helpers from `eve/tools/approval`:
```ts title="agent/tools/refund_charge.ts"
import { defineTool } from "eve/tools";
diff --git a/e2e/fixtures/agent-workflow-tools/agent/agent.ts b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
index 019543916..28c6aef49 100644
--- a/e2e/fixtures/agent-workflow-tools/agent/agent.ts
+++ b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
@@ -87,7 +87,9 @@ function respond(request: MockModelRequest): MockModelResponse | string {
}
return `WORKFLOW-PROBE-RESULT ${String(result.output)}`;
}
- for (const [directive, tool] of [
+ for (const [directive, tool, service = "api"] of [
+ ["WORKFLOW-APPROVAL-START", "gated_deploy"],
+ ["WORKFLOW-APPROVAL-DENIED-START", "gated_deploy", "review-only"],
["WORKFLOW-DEPLOY-START", "deploy_service"],
["WORKFLOW-CONFIRM-START", "confirm_deploy"],
["WORKFLOW-ESCALATE-START", "escalate_deploy"],
@@ -99,7 +101,7 @@ function respond(request: MockModelRequest): MockModelResponse | string {
if (!message.includes(directive)) continue;
const result = [...request.toolResults].reverse().find((entry) => entry.name === tool);
if (result === undefined) {
- return { toolCalls: [{ input: { service: "api" }, name: tool }] };
+ return { toolCalls: [{ input: { service }, name: tool }] };
}
const output = result.output;
return `${directive.replace("-START", "-RESULT")} ${
diff --git a/e2e/fixtures/agent-workflow-tools/agent/tools/gated_deploy.ts b/e2e/fixtures/agent-workflow-tools/agent/tools/gated_deploy.ts
new file mode 100644
index 000000000..9a1f4246d
--- /dev/null
+++ b/e2e/fixtures/agent-workflow-tools/agent/tools/gated_deploy.ts
@@ -0,0 +1,14 @@
+import { defineWorkflowTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineWorkflowTool({
+ description: "Record Alice's release after approval.",
+ inputSchema: z.strictObject({ service: z.string() }),
+ approval: ({ toolInput }) => (toolInput?.service === "review-only" ? "denied" : "user-approval"),
+ async *execute({ service }) {
+ "use workflow";
+
+ yield "approved deployment started";
+ return { deployed: service };
+ },
+});
diff --git a/e2e/fixtures/agent-workflow-tools/evals/gated-deploy.approval.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/gated-deploy.approval.eval.ts
new file mode 100644
index 000000000..dd81b0a68
--- /dev/null
+++ b/e2e/fixtures/agent-workflow-tools/evals/gated-deploy.approval.eval.ts
@@ -0,0 +1,56 @@
+import { defineEval } from "eve/evals";
+
+export default defineEval({
+ description: "A workflow body starts only after approval and never starts after denial.",
+ async test(t) {
+ const review = await t.session();
+ const denied = await review.send(
+ "WORKFLOW-APPROVAL-DENIED-START Alice requests a review-only release; Bob's policy does not permit deployment.",
+ );
+ denied.expectOk();
+ denied.messageIncludes("WORKFLOW-APPROVAL-DENIED-RESULT");
+ denied.notEvent("input.requested");
+ denied.notEvent("action.partial");
+ denied.calledTool("gated_deploy", {
+ count: 1,
+ output: /Tool execution was denied/u,
+ status: "failed",
+ });
+
+ for (const decision of ["approve", "cancel"] as const) {
+ const session = await t.session();
+ const parked = await session.send(
+ "WORKFLOW-APPROVAL-START Alice asks Bob to review the API release before deployment.",
+ );
+ session.requireInputRequest({ toolName: "gated_deploy", display: "confirmation" });
+ parked.calledTool("gated_deploy", { count: 1, status: "pending" });
+ parked.notEvent("action.partial");
+ parked.notEvent("action.result");
+
+ const resumed = await session.respondAll(decision);
+ resumed.expectOk();
+ resumed.event("turn.started", { count: 1 });
+ resumed.event("input.resolved", { count: 1 });
+ resumed.messageIncludes("WORKFLOW-APPROVAL-RESULT");
+ if (decision === "approve") {
+ resumed.event("action.partial", {
+ count: 1,
+ data: { result: { toolName: "gated_deploy", output: "approved deployment started" } },
+ });
+ resumed.calledTool("gated_deploy", { status: "completed", output: /api/u });
+ resumed.eventOrder([
+ { type: "turn.started" },
+ { type: "action.partial" },
+ { type: "action.result" },
+ { type: "turn.completed" },
+ ]);
+ } else {
+ resumed.notEvent("action.partial");
+ resumed.event("action.result", {
+ count: 1,
+ data: { status: "rejected", result: { toolName: "gated_deploy" } },
+ });
+ }
+ }
+ },
+});
diff --git a/packages/eve/src/harness/coordination.test.ts b/packages/eve/src/harness/coordination.test.ts
index fbc0620f8..0a8f5f8c0 100644
--- a/packages/eve/src/harness/coordination.test.ts
+++ b/packages/eve/src/harness/coordination.test.ts
@@ -59,7 +59,6 @@ describe("createRuntimeActionRequestFromToolCall", () => {
input: { service: "api" },
toolCallId: "call-deploy",
toolName: "deploy",
- type: "tool-call",
},
tools: new Map([
[
diff --git a/packages/eve/src/harness/coordination.ts b/packages/eve/src/harness/coordination.ts
index 1c9dee26b..99781dfe7 100644
--- a/packages/eve/src/harness/coordination.ts
+++ b/packages/eve/src/harness/coordination.ts
@@ -1,4 +1,4 @@
-import type { ModelMessage, ToolSet, TypedToolCall } from "ai";
+import type { ModelMessage } from "ai";
import { createActionResultEvent } from "#protocol/message.js";
import { resolveRuntimeActionResultsForCallIds } from "#runtime/actions/results.js";
@@ -17,6 +17,7 @@ import {
} from "#harness/workflow-tool-runs.js";
import { validateHarnessModelMessages } from "#harness/messages.js";
import { normalizeToolModelOutput } from "#harness/tool-model-output.js";
+import { extractHistoricalInputRequests } from "#harness/input-extraction.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import { pendingTaskToolCalls } from "#execution/tasks/calls.js";
import { startsTasks } from "#execution/tasks/tool-entry-point.js";
@@ -106,6 +107,7 @@ export function commitCancelledCoordinationBatch(session: HarnessSession): Harne
const batch = getPendingCoordinationBatch(session.state);
if (batch === undefined) return session;
const cancelledCalls = [
+ ...approvedSiblingCalls(session.history, batch),
...batch.tasks.map((task) => ({ callId: task.callId, toolName: task.toolName })),
...pendingTaskToolCalls(batch.responseMessages).map((call) => ({
callId: call.callId,
@@ -128,6 +130,31 @@ export function commitCancelledCoordinationBatch(session: HarnessSession): Harne
return clearPendingCoordinationBatch({ ...session, history });
}
+/** Approved local calls parked with their workflow siblings, which have no result yet. */
+function approvedSiblingCalls(
+ history: readonly ModelMessage[],
+ batch: PendingCoordinationBatch,
+): { readonly callId: string; readonly toolName: string }[] {
+ const tail = batch.responseMessages.at(-1);
+ if (tail?.role !== "tool") return [];
+ const approvalIds = new Set(
+ tail.content.flatMap((part) =>
+ part.type === "tool-approval-response" && part.approved ? [part.approvalId] : [],
+ ),
+ );
+ const settled = new Set([
+ ...tail.content.flatMap((part) => (part.type === "tool-result" ? [part.toolCallId] : [])),
+ ...batch.tasks.map((task) => task.callId),
+ ]);
+ const requests = extractHistoricalInputRequests({
+ history: [...history, ...batch.responseMessages],
+ requestIds: approvalIds,
+ });
+ return [...requests.values()]
+ .map(({ action }) => ({ callId: action.callId, toolName: action.toolName }))
+ .filter(({ callId }) => !settled.has(callId));
+}
+
/**
* Stores one pending coordination batch on the session.
*/
@@ -301,10 +328,14 @@ export async function resolvePendingCoordination(input: {
const messages = [...nextSession.history, ...batch.responseMessages];
if (toolResults.length > 0) {
- messages.push({
- content: toolResults,
- role: "tool",
- });
+ // AI SDK reads approved calls and their results only from the tail tool
+ // message, so results join a trailing tool response instead of hiding it.
+ const tail = batch.responseMessages.at(-1);
+ if (tail?.role === "tool") {
+ messages[messages.length - 1] = { content: [...tail.content, ...toolResults], role: "tool" };
+ } else {
+ messages.push({ content: toolResults, role: "tool" });
+ }
}
return {
messages,
@@ -313,11 +344,18 @@ export async function resolvePendingCoordination(input: {
};
}
+/** The parts of a model tool call that coordination turns into a runtime request. */
+export interface CoordinationToolCall {
+ readonly input: unknown;
+ readonly toolCallId: string;
+ readonly toolName: string;
+}
+
/**
* Projects one AI SDK tool call into the eve runtime-action contract.
*/
export function createRuntimeActionRequestFromToolCall(input: {
- readonly toolCall: TypedToolCall<ToolSet>;
+ readonly toolCall: CoordinationToolCall;
readonly tools: HarnessToolMap;
}): RuntimeActionRequest {
const definition = input.tools.get(input.toolCall.toolName);
@@ -344,7 +382,7 @@ export function createRuntimeActionRequestFromToolCall(input: {
export function createCoordinationRequestFromToolCall(input: {
readonly entry: WorkflowToolCallEntry;
readonly input: JsonObject;
- readonly toolCall: TypedToolCall<ToolSet>;
+ readonly toolCall: CoordinationToolCall;
readonly tools: HarnessToolMap;
}): RuntimeWorkflowTaskRequest {
const definition = input.tools.get(input.toolCall.toolName);
diff --git a/packages/eve/src/harness/input-requests.ts b/packages/eve/src/harness/input-requests.ts
index 17b9621a4..3e3f9a156 100644
--- a/packages/eve/src/harness/input-requests.ts
+++ b/packages/eve/src/harness/input-requests.ts
@@ -16,7 +16,7 @@ import {
getPendingInputBatches,
queueDeferredStepInput,
} from "#harness/pending-input-batches.js";
-import { compactStepInput } from "#harness/hitl/pending-input-resolution.js";
+import { compactStepInput, finishResolvedInput } from "#harness/hitl/pending-input-resolution.js";
import type {
ResolvePendingInputResult,
ResolvedStepInput,
@@ -116,11 +116,21 @@ export function resolvePendingInput(input: {
}): ResolvePendingInputResult {
const baseHistory = [...(input.history ?? input.session.history)];
const batches = getPendingInputBatches(input.session.state);
+ const route = routePendingInput(batches);
+ // Finish already-approved work before another batch or user message can hide
+ // the approval response from the SDK. Session-limit prompts still take priority.
+ if (route.kind === "approvals" && hasTailApprovalResponse(baseHistory)) {
+ return finishResolvedInput({
+ deferTurnInput: true,
+ leftoverResponses: input.stepInput?.inputResponses ?? [],
+ messages: baseHistory,
+ resolvedStepInput: input.stepInput,
+ session: input.session,
+ });
+ }
if (batches.length === 0) {
return { outcome: "continue", messages: baseHistory, session: input.session };
}
-
- const route = routePendingInput(batches);
const deferTurnInput = hasTailApprovalResponse(baseHistory);
const textResolutionBatch =
route.kind === "session-limit" ? route.batch : batches.length === 1 ? batches[0] : undefined;
diff --git a/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts b/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
index 45a60072f..20032484a 100644
--- a/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
@@ -1,10 +1,16 @@
+import {
+ createApprovalContext,
+ textStreamResult,
+ toolCallStreamResult,
+ usage,
+} from "#internal/testing/approval-resume.js";
import { setTurnClientContextState } from "#harness/turn-client-context.js";
import { DynamicModelSelectionError } from "#context/dynamic-model-lifecycle.js";
import { dispatchDynamicInstructionEvent } from "#context/dynamic-instruction-lifecycle.js";
import { dispatchMemoryLifecycleEvent } from "#context/memory-event-lifecycle.js";
import { defineInstructions } from "#public/definitions/instructions.js";
import { defineMemory } from "#public/memory/index.js";
-import { jsonSchema, type LanguageModel, type ModelMessage, simulateReadableStream } from "ai";
+import { jsonSchema, type LanguageModel, type ModelMessage } from "ai";
import { MockLanguageModelV4 } from "ai/test";
import { describe, expect, it, vi } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
@@ -43,61 +49,6 @@ import {
// be written; the attribute contract is covered by emit.test.ts.
vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async () => {}) }));
-const usage = {
- inputTokens: {
- cacheRead: undefined,
- cacheWrite: undefined,
- noCache: 1,
- total: 1,
- },
- outputTokens: {
- reasoning: undefined,
- text: 1,
- total: 1,
- },
-};
-
-type StreamResult = Awaited<ReturnType<MockLanguageModelV4["doStream"]>>;
-type StreamPart = StreamResult["stream"] extends ReadableStream<infer Part> ? Part : never;
-
-function textStreamResult(text: string): StreamResult {
- return {
- stream: simulateReadableStream({
- chunks: [
- { type: "stream-start", warnings: [] },
- { id: "answer", type: "text-start" },
- { delta: text, id: "answer", type: "text-delta" },
- { id: "answer", type: "text-end" },
- {
- finishReason: { raw: undefined, unified: "stop" },
- type: "finish",
- usage,
- },
- ] satisfies StreamPart[],
- }),
- };
-}
-
-function toolCallStreamResult(call: {
- readonly input: string;
- readonly toolCallId: string;
- readonly toolName: string;
-}): StreamResult {
- return {
- stream: simulateReadableStream({
- chunks: [
- { type: "stream-start", warnings: [] },
- { ...call, type: "tool-call" },
- {
- finishReason: { raw: undefined, unified: "tool-calls" },
- type: "finish",
- usage,
- },
- ] satisfies StreamPart[],
- }),
- };
-}
-
const toolCall = {
input: { command: "pwd" },
toolCallId: "call-1",
@@ -270,25 +221,6 @@ function createMemoryInstructionPreamble(
return { handleEvent, instruction, recall };
}
-function createApprovalContext(): ContextContainer {
- const responder = {
- attributes: {},
- authenticator: "test",
- issuer: "test",
- principalId: "user-1",
- principalType: "user" as const,
- };
- const ctx = new ContextContainer();
- ctx.set(AuthKey, responder);
- ctx.set(SessionIdKey, "generate-approval-resume-session");
- ctx.set(SessionKey, {
- auth: { current: responder, initiator: null },
- sessionId: "generate-approval-resume-session",
- turn: { id: "turn-1", sequence: 1 },
- });
- return ctx;
-}
-
function createModel(): MockLanguageModelV4 {
return new MockLanguageModelV4({
doGenerate: {
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index cde4e8911..94fdfe0d8 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -81,7 +81,8 @@ import {
resolveCompactionModel,
shouldCompact,
} from "#harness/compaction.js";
-import { createCurrentMessages } from "#harness/current-messages.js";
+import { createCurrentMessages, hasTailApprovalResponse } from "#harness/current-messages.js";
+import { collectDeferredCalls, dispatchApprovedWorkflowCalls } from "#harness/workflow-dispatch.js";
import { estimateTokens } from "#harness/token-estimate.js";
import {
accumulateTurnUsage,
@@ -136,7 +137,11 @@ import {
selectApprovalReplayBatch,
appendPendingInputBatch,
} from "#harness/input-requests.js";
-import { getPendingInputBatches, queueDeferredStepInput } from "#harness/pending-input-batches.js";
+import {
+ getPendingInputBatches,
+ queueDeferredStepInput,
+ type PendingInputBatchEvent,
+} from "#harness/pending-input-batches.js";
import {
convertStaleResponsesToUserMessage,
dropStaleSessionLimitContinuationResponses,
@@ -170,7 +175,6 @@ import {
} from "#protocol/message.js";
import {
appendTaskContext,
- commitCallEntry,
isTaskTool,
taskSystemMessages,
withTaskTools,
@@ -200,13 +204,10 @@ import {
} from "#harness/prompt-cache.js";
import { resolveFrameworkToolFromUpstreamType } from "#harness/provider-tools.js";
import {
- createCoordinationRequestFromToolCall,
getPendingCoordinationBatch,
resolvePendingCoordination,
- resolveToolCallInputObject,
setPendingCoordinationBatch,
} from "#harness/coordination.js";
-import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
import {
getInvalidToolCallInputError,
isInvalidToolCall,
@@ -633,10 +634,15 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// Resolve deferred input, task/control coordination, then HITL input; each stage
// may park when its resume payload has not arrived.
- const stepInput = consumeDeferredStepInput({ input, session });
- session = stepInput.session;
-
const pendingCoordination = getPendingCoordinationBatch(session.state);
+ // Queued input waits for the pending batch: coalescing would drop its
+ // runtimeActionResults, and input queued behind approved workflows must
+ // replay only after they finish.
+ const stepInput =
+ pendingCoordination === undefined
+ ? consumeDeferredStepInput({ input, session })
+ : { input, session };
+ session = stepInput.session;
const resolvedCoordination = await resolvePendingCoordination({
emit,
session,
@@ -668,7 +674,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const approvalContext = contextStorage.getStore();
const prepareApprovalTools = async (
- batch: ReturnType<typeof getPendingInputBatches>[number] | undefined,
+ batch: { readonly event?: PendingInputBatchEvent } | undefined,
) => {
if (batch?.event !== undefined) await config.prepareApprovalTurn?.(batch.event);
if (approvalContext !== undefined) {
@@ -854,7 +860,11 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
};
}
- const replayBatch = selectApprovalReplayBatch(session, coordinated.stepInput);
+ // Approved siblings of a finished workflow run with their approval turn's tools.
+ const replayBatch =
+ pendingCoordination !== undefined && hasTailApprovalResponse(resolvedCoordination.messages)
+ ? pendingCoordination
+ : selectApprovalReplayBatch(session, coordinated.stepInput);
const responseAuthorizationTools =
replayBatch === undefined ? config.tools : await prepareApprovalTools(replayBatch);
const pending = resolvePendingInput({
@@ -1743,6 +1753,20 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
generation.signal,
);
+ // Approved workflows start like ungated ones: session limits gate model calls.
+ const dispatchedSession = dispatchApprovedWorkflowCalls({
+ messages,
+ resolvedInputs: pending.resolvedInputs,
+ session,
+ tools: buildResponseAuthorizationTools({ authoredTools: config.tools, context: ctx }),
+ });
+ if (dispatchedSession !== undefined) {
+ return {
+ next: null,
+ session: setHarnessEmissionState(dispatchedSession, advanceStep(emissionState)),
+ };
+ }
+
const limitResult = await enforceSessionUsageLimit({
config,
emit,
@@ -2298,7 +2322,7 @@ function getInvalidToolCallInputErrors(input: {
* history normalization, which runs after the backfill paths), so a
* tool-message-only scan would let a synthesized result duplicate them.
*/
-function extractToolResultCallIds(messages: readonly StepResponseMessage[]): ReadonlySet<string> {
+function extractToolResultCallIds(messages: readonly ModelMessage[]): ReadonlySet<string> {
const callIds = new Set<string>();
for (const message of messages) {
@@ -2596,8 +2620,14 @@ async function handleStepResult(input: {
session: baseSession,
tools: input.coordinationTools,
});
+ // Only unanswered calls can dispatch: automatic denials already have results.
+ const blockedCallIds = new Set([
+ ...approvalRequests.map((request) => request.action.callId),
+ ...extractToolResultCallIds(responseMessages),
+ ]);
const deferredToolCalls = ((result.toolCalls ?? []) as TypedToolCall<ToolSet>[])
.filter((toolCall) => !invalidInputToolCallIds.has(toolCall.toolCallId))
+ .filter((toolCall) => !blockedCallIds.has(toolCall.toolCallId))
.filter((toolCall) => isDeferredHarnessTool(input.coordinationTools.get(toolCall.toolName)))
.filter((toolCall) => {
if (isDeferredHarnessTool(advertisedCoordinationTools.get(toolCall.toolName))) {
@@ -2856,48 +2886,6 @@ function isDeferredHarnessTool(tool: HarnessToolDefinition | undefined): boolean
return tool?.workflowId !== undefined || isTaskTool(tool);
}
-/**
- * Turns a step's deferred calls into workflow runs, committing a task record
- * for each call that starts a task. Task tool calls stay in the response
- * alone: the session reads them from there.
- */
-function collectDeferredCalls(input: {
- readonly session: HarnessSession;
- readonly toolCalls: readonly TypedToolCall<ToolSet>[];
- readonly tools: HarnessToolMap;
- readonly turnId: string;
-}): {
- readonly session: HarnessSession;
- readonly workflowRequests: readonly RuntimeWorkflowTaskRequest[];
-} {
- let { session } = input;
- const workflowRequests: RuntimeWorkflowTaskRequest[] = [];
- for (const toolCall of input.toolCalls) {
- const definition = input.tools.get(toolCall.toolName);
- if (isTaskTool(definition)) continue;
- const committed = commitCallEntry(session, {
- callId: toolCall.toolCallId,
- definition,
- input: resolveToolCallInputObject(toolCall.input, {
- callId: toolCall.toolCallId,
- toolName: toolCall.toolName,
- }),
- toolName: toolCall.toolName,
- turnId: input.turnId,
- });
- session = committed.session;
- workflowRequests.push(
- createCoordinationRequestFromToolCall({
- entry: committed.entry,
- input: committed.input,
- toolCall,
- tools: input.tools,
- }),
- );
- }
- return { session, workflowRequests };
-}
-
/** Answers a `final_output` call made while tasks work with an error naming them. */
function rejectFinalOutput(
responseMessages: readonly ModelMessage[],
diff --git a/packages/eve/src/harness/workflow-approval-resume.integration.test.ts b/packages/eve/src/harness/workflow-approval-resume.integration.test.ts
new file mode 100644
index 000000000..43bdb9a40
--- /dev/null
+++ b/packages/eve/src/harness/workflow-approval-resume.integration.test.ts
@@ -0,0 +1,383 @@
+import { jsonSchema } from "ai";
+import { MockLanguageModelV4 } from "ai/test";
+import { describe, expect, it, vi } from "vitest";
+import { ContextContainer, contextStorage } from "#context/container.js";
+import { dispatchDynamicInstructionEvent } from "#context/dynamic-instruction-lifecycle.js";
+import { defineInstructions } from "#public/definitions/instructions.js";
+import { SessionIdKey, StepDynamicToolMetadataKey } from "#context/keys.js";
+import {
+ commitCancelledCoordinationBatch,
+ getPendingCoordinationBatch,
+} from "#harness/coordination.js";
+import { getHarnessEmissionState } from "#harness/emission.js";
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import { getPendingInputBatches } from "#harness/pending-input-batches.js";
+import { createToolLoopHarness } from "#harness/tool-loop.js";
+import { setTurnUsageState } from "#harness/turn-tag-state.js";
+import type { HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
+import {
+ createApprovalContext,
+ textStreamResult,
+ toolCallsStreamResult,
+} from "#internal/testing/approval-resume.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import { always } from "#tools/approval/policies.js";
+import {
+ clearDurableDynamicCallbacks,
+ registerDurableDynamicCallback,
+} from "#tools/durable-callbacks.js";
+
+vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async () => {}) }));
+
+function workflow(
+ name: string,
+ approval?: HarnessToolDefinition["approval"],
+): HarnessToolDefinition {
+ return {
+ approval,
+ description: name,
+ inputSchema: jsonSchema({ type: "object" }),
+ name,
+ workflowId: `workflow//./agent/tools/${name}//execute`,
+ };
+}
+
+function setup(
+ tools: readonly HarnessToolDefinition[],
+ overrides: Partial<ToolLoopHarnessConfig> = {},
+) {
+ const events: UnstampedMessageStreamEvent[] = [];
+ const model = new MockLanguageModelV4({
+ doStream: vi
+ .fn()
+ .mockImplementationOnce(async () =>
+ toolCallsStreamResult(
+ tools.map((tool, index) => ({
+ input: "{}",
+ toolCallId: `call-${index}`,
+ toolName: tool.name,
+ })),
+ ),
+ )
+ .mockImplementation(async () => textStreamResult("Finished.")),
+ modelId: "approval-model",
+ provider: "eve-integration-mock",
+ });
+ const config: ToolLoopHarnessConfig = {
+ capabilities: { requestInput: true },
+ handleEvent: async (event) => {
+ events.push(event);
+ },
+ resolveModel: async () => model,
+ tools: new Map(tools.map((tool) => [tool.name, tool])),
+ ...overrides,
+ };
+ const session: HarnessSession = {
+ agent: {
+ modelReference: { id: "approval-model" },
+ system: "Help Alice coordinate her release.",
+ tools: [],
+ },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "http:generate-approval-resume-session",
+ history: [],
+ sessionId: "generate-approval-resume-session",
+ };
+ const step = (
+ session: HarnessSession,
+ input?: Parameters<ReturnType<typeof createToolLoopHarness>>[1],
+ ) =>
+ contextStorage.run(createApprovalContext(), () =>
+ createToolLoopHarness(config)(session, input),
+ );
+ return { events, config, model, step, session };
+}
+
+function requests(session: HarnessSession) {
+ return getPendingInputBatches(session.state).flatMap((batch) => batch.requests);
+}
+
+function workflowResult(callId = "call-0") {
+ return {
+ runtimeActionResults: [
+ { callId, kind: "tool-result" as const, output: "deployed", toolName: "deploy" },
+ ],
+ };
+}
+
+function resultCallIds(session: HarnessSession) {
+ return session.history.flatMap((message) =>
+ message.role === "tool"
+ ? message.content.flatMap((part) => (part.type === "tool-result" ? [part.toolCallId] : []))
+ : [],
+ );
+}
+
+describe("workflow approval resume (real AI SDK)", () => {
+ it("opens one resume turn before dispatch and replays accompanying input after completion", async () => {
+ const fixture = setup([workflow("deploy", always())]);
+ const initial = await fixture.step(fixture.session, { message: "Deploy Alice's release." });
+ expect(getPendingCoordinationBatch(initial.session.state)).toBeUndefined();
+ const [request] = requests(initial.session);
+ expect(request).toBeDefined();
+ const start = fixture.events.length;
+ const approved = await fixture.step(initial.session, {
+ inputResponses: [{ optionId: "approve", requestId: request!.requestId }],
+ message: "Tell Alice when deployment finishes.",
+ });
+ expect(
+ getPendingCoordinationBatch(approved.session.state)?.tasks.map((task) => task.callId),
+ ).toEqual(["call-0"]);
+ const resumedTurn = getHarnessEmissionState(approved.session.state).turnId;
+ expect(resumedTurn).not.toBe("");
+ expect(
+ fixture.events.slice(start).filter((event) => event.type === "turn.started"),
+ ).toMatchObject([{ data: { turnId: resumedTurn } }]);
+ const completed = await fixture.step(approved.session, workflowResult());
+ expect(resultCallIds(completed.session)).toEqual(["call-0"]);
+ expect(fixture.model.doStreamCalls).toHaveLength(2);
+ expect(
+ fixture.events.slice(start).filter((event) => event.type === "step.started"),
+ ).toMatchObject([
+ { data: { turnId: resumedTurn, stepIndex: 0 } },
+ { data: { turnId: resumedTurn, stepIndex: 1 } },
+ ]);
+ expect(JSON.stringify(fixture.model.doStreamCalls[1]!.prompt)).not.toContain("Tell Alice");
+ expect(typeof completed.next).toBe("function");
+ const followUp = await fixture.step(completed.session);
+ expect(JSON.stringify(followUp.session.history)).toContain(
+ "Tell Alice when deployment finishes.",
+ );
+ expect(fixture.events.filter((event) => event.type === "input.resolved")).toHaveLength(1);
+ });
+
+ it("keeps approved calls runnable when the resume turn adds user instructions", async () => {
+ const fixture = setup([workflow("deploy", always())], {
+ handleEvent: async (event, messages) => {
+ const ctx = contextStorage.getStore();
+ if (!(ctx instanceof ContextContainer)) throw new Error("Missing test context.");
+ await dispatchDynamicInstructionEvent({
+ ctx,
+ event,
+ messages: messages ?? [],
+ resolvers: [
+ {
+ eventNames: ["turn.started"],
+ events: {
+ "turn.started": () =>
+ defineInstructions({ role: "user", content: "Keep Alice informed." }),
+ },
+ logicalPath: "instructions/release.ts",
+ slug: "release",
+ sourceId: "instructions/release.ts",
+ sourceKind: "module",
+ },
+ ],
+ });
+ },
+ });
+ const initial = await fixture.step(fixture.session, { message: "Deploy Alice's release." });
+ const approved = await fixture.step(initial.session, {
+ inputResponses: requests(initial.session).map((request) => ({
+ optionId: "approve",
+ requestId: request.requestId,
+ })),
+ });
+ expect(getPendingCoordinationBatch(approved.session.state)?.tasks).toHaveLength(1);
+ const completed = await fixture.step(approved.session, workflowResult());
+ expect(resultCallIds(completed.session)).toEqual(["call-0"]);
+ expect(JSON.stringify(fixture.model.doStreamCalls.at(-1)?.prompt)).toContain(
+ "Keep Alice informed.",
+ );
+ });
+
+ it("never dispatches a denied workflow", async () => {
+ const fixture = setup([workflow("deploy", always())]);
+ const initial = await fixture.step(fixture.session, { message: "Prepare Alice's deployment." });
+ const cancelled = await fixture.step(initial.session, {
+ inputResponses: requests(initial.session).map((request) => ({
+ optionId: "cancel",
+ requestId: request.requestId,
+ })),
+ });
+ expect(getPendingCoordinationBatch(cancelled.session.state)).toBeUndefined();
+ expect(resultCallIds(cancelled.session)).toEqual(["call-0"]);
+ });
+
+ it("never dispatches an automatically denied workflow", async () => {
+ const fixture = setup([workflow("deploy", () => "denied")]);
+ const initial = await fixture.step(fixture.session, { message: "Review Alice's deployment." });
+ expect(getPendingCoordinationBatch(initial.session.state)).toBeUndefined();
+ expect(requests(initial.session)).toEqual([]);
+ expect(resultCallIds(initial.session)).toEqual(["call-0"]);
+ });
+
+ it("runs ungated siblings first and dispatches only the approved workflow", async () => {
+ const fixture = setup([
+ workflow("deploy", always()),
+ workflow("archive", always()),
+ workflow("status"),
+ ]);
+ const initial = await fixture.step(fixture.session, {
+ message: "Prepare Alice's release and check status.",
+ });
+ expect(
+ getPendingCoordinationBatch(initial.session.state)?.tasks.map((task) => task.callId),
+ ).toEqual(["call-2"]);
+ const ordinary = await fixture.step(initial.session, {
+ runtimeActionResults: [
+ { callId: "call-2", kind: "tool-result", output: "healthy", toolName: "status" },
+ ],
+ });
+ const approved = await fixture.step(ordinary.session, {
+ inputResponses: requests(ordinary.session).map((request) => ({
+ optionId: request.action.toolName === "deploy" ? "approve" : "cancel",
+ requestId: request.requestId,
+ })),
+ });
+ expect(
+ getPendingCoordinationBatch(approved.session.state)?.tasks.map((task) => task.callId),
+ ).toEqual(["call-0"]);
+ const completed = await fixture.step(approved.session, workflowResult());
+ expect(resultCallIds(completed.session).sort()).toEqual(["call-0", "call-1", "call-2"]);
+ expect(getPendingCoordinationBatch(completed.session.state)).toBeUndefined();
+ });
+
+ it("restores an approved dynamic sibling on a cold workflow continuation", async () => {
+ const execute = vi.fn(async () => "notified");
+ const preparedTurns: string[] = [];
+ const fixture = setup(
+ [
+ workflow("deploy", always()),
+ {
+ name: "notify",
+ description: "Notify Bob.",
+ approval: always(),
+ inputSchema: jsonSchema({ type: "object" }),
+ execute: async () => {
+ throw new Error("The authored fallback must not execute.");
+ },
+ },
+ ],
+ {
+ prepareApprovalTurn: async (event) => {
+ preparedTurns.push(event.turnId);
+ },
+ resolveStepDynamicTools: async ({ ctx }) => {
+ registerDurableDynamicCallback({
+ owner: {
+ sessionId: ctx.require(SessionIdKey),
+ scope: "step",
+ resolverSlug: "notifications",
+ entryKey: "notify",
+ name: "notify",
+ },
+ phase: "execute",
+ callback: execute,
+ });
+ ctx.set(StepDynamicToolMetadataKey, [
+ {
+ name: "notify",
+ description: "Notify Bob.",
+ inputSchema: { type: "object" },
+ resolverSlug: "notifications",
+ entryKey: "notify",
+ callbacks: { execute: { closure: {} } },
+ },
+ ]);
+ },
+ },
+ );
+ const initial = await fixture.step(fixture.session, {
+ message: "Deploy Alice's release and notify Bob.",
+ });
+ const origin = getPendingInputBatches(initial.session.state)[0]!.event!.turnId;
+ const approved = await fixture.step(initial.session, {
+ inputResponses: requests(initial.session).map((request) => ({
+ optionId: "approve",
+ requestId: request.requestId,
+ })),
+ });
+ expect(execute).not.toHaveBeenCalled();
+ clearDurableDynamicCallbacks(initial.session.sessionId);
+ const completed = await fixture.step(
+ JSON.parse(JSON.stringify(approved.session)),
+ workflowResult(),
+ );
+ expect(preparedTurns).toEqual([origin, origin]);
+ expect(execute).toHaveBeenCalledOnce();
+ expect(resultCallIds(completed.session)).toEqual(["call-0", "call-1"]);
+ expect(JSON.stringify(completed.session.history)).toContain("notified");
+ expect(fixture.events.filter((event) => event.type === "input.resolved")).toHaveLength(1);
+ clearDurableDynamicCallbacks(initial.session.sessionId);
+ });
+
+ it("starts an approved workflow and applies the session budget to the next model call", async () => {
+ const fixture = setup([workflow("deploy", always())]);
+ const initial = await fixture.step(fixture.session, { message: "Deploy Alice's release." });
+ const totals = {
+ cacheReadTokens: 0,
+ cacheWriteTokens: 0,
+ costUsd: 0,
+ inputTokens: 12,
+ outputTokens: 1,
+ sawCost: false,
+ };
+ const exhausted = setTurnUsageState(
+ { ...initial.session, limits: { maxInputTokensPerSession: 12 } },
+ {
+ ...totals,
+ session: totals,
+ turnId: "turn_0",
+ },
+ );
+ const approved = await fixture.step(exhausted, {
+ inputResponses: requests(initial.session).map((request) => ({
+ optionId: "approve",
+ requestId: request.requestId,
+ })),
+ });
+ expect(
+ getPendingCoordinationBatch(approved.session.state)?.tasks.map((task) => task.callId),
+ ).toEqual(["call-0"]);
+ const limited = await fixture.step(approved.session, workflowResult());
+ expect(resultCallIds(limited.session)).toEqual(["call-0"]);
+ const [limit] = requests(limited.session);
+ expect(limit?.kind).toBe("session-limit");
+ const modelCalls = fixture.model.doStreamCalls.length;
+ const continued = await fixture.step(limited.session, {
+ inputResponses: [{ optionId: "continue", requestId: limit!.requestId }],
+ });
+ expect(fixture.model.doStreamCalls).toHaveLength(modelCalls + 1);
+ expect(resultCallIds(continued.session)).toEqual(["call-0"]);
+ });
+
+ it("settles approved siblings without executing them when workflow coordination is cancelled", async () => {
+ const execute = vi.fn(async () => "notified");
+ const fixture = setup([
+ workflow("deploy", always()),
+ {
+ name: "notify",
+ description: "Notify Bob.",
+ approval: always(),
+ inputSchema: jsonSchema({ type: "object" }),
+ execute,
+ },
+ ]);
+ const initial = await fixture.step(fixture.session, {
+ message: "Deploy Alice's release and notify Bob.",
+ });
+ const approved = await fixture.step(initial.session, {
+ inputResponses: requests(initial.session).map((request) => ({
+ optionId: "approve",
+ requestId: request.requestId,
+ })),
+ });
+ const cancelled = commitCancelledCoordinationBatch(approved.session);
+ expect(resultCallIds(cancelled).sort()).toEqual(["call-0", "call-1"]);
+ await fixture.step(cancelled, {
+ message: "Alice cancelled the release. Summarize the status.",
+ });
+ expect(execute).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/eve/src/harness/workflow-dispatch.ts b/packages/eve/src/harness/workflow-dispatch.ts
new file mode 100644
index 000000000..0ecadf932
--- /dev/null
+++ b/packages/eve/src/harness/workflow-dispatch.ts
@@ -0,0 +1,99 @@
+import type { ModelMessage } from "ai";
+import { commitCallEntry, isTaskTool } from "#execution/tasks/model-step.js";
+import {
+ createCoordinationRequestFromToolCall,
+ resolveToolCallInputObject,
+ setPendingCoordinationBatch,
+ type CoordinationToolCall,
+} from "#harness/coordination.js";
+import { hasTailApprovalResponse } from "#harness/current-messages.js";
+import type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
+import { validateHarnessModelMessages } from "#harness/messages.js";
+import type { HarnessSession, HarnessToolMap } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+
+/**
+ * Parks the step on the workflow tools a person just approved. The approval
+ * tool message moves into the batch's response so workflow results join it:
+ * AI SDK then resumes approved sibling tools without replaying the workflows.
+ */
+export function dispatchApprovedWorkflowCalls(input: {
+ readonly messages: readonly ModelMessage[];
+ readonly resolvedInputs: readonly ResolvedInputBatch[] | undefined;
+ readonly session: HarnessSession;
+ readonly tools: HarnessToolMap;
+}): HarnessSession | undefined {
+ for (const batch of input.resolvedInputs ?? []) {
+ const approved = batch.inputs.filter(
+ ({ outcome, request }) =>
+ outcome === "approved" &&
+ input.tools.get(request.action.toolName)?.workflowId !== undefined,
+ );
+ if (approved.length === 0) continue;
+ if (!hasTailApprovalResponse(input.messages)) {
+ throw new Error("Approved workflow calls must follow their approval tool message.");
+ }
+ const deferred = collectDeferredCalls({
+ session: input.session,
+ toolCalls: approved.map(({ request }) => ({
+ input: request.action.input,
+ toolCallId: request.action.callId,
+ toolName: request.action.toolName,
+ })),
+ tools: input.tools,
+ turnId: batch.event.turnId,
+ });
+ return setPendingCoordinationBatch({
+ tasks: deferred.workflowRequests,
+ event: batch.event,
+ responseMessages: input.messages.slice(-1),
+ session: {
+ ...deferred.session,
+ history: validateHarnessModelMessages(input.messages.slice(0, -1)),
+ },
+ });
+ }
+ return undefined;
+}
+
+/**
+ * Turns a step's deferred calls into workflow runs, committing a task record
+ * for each call that starts a task. Task tool calls stay in the response
+ * alone: the session reads them from there.
+ */
+export function collectDeferredCalls(input: {
+ readonly session: HarnessSession;
+ readonly toolCalls: readonly CoordinationToolCall[];
+ readonly tools: HarnessToolMap;
+ readonly turnId: string;
+}): {
+ readonly session: HarnessSession;
+ readonly workflowRequests: readonly RuntimeWorkflowTaskRequest[];
+} {
+ let { session } = input;
+ const workflowRequests: RuntimeWorkflowTaskRequest[] = [];
+ for (const toolCall of input.toolCalls) {
+ const definition = input.tools.get(toolCall.toolName);
+ if (isTaskTool(definition)) continue;
+ const committed = commitCallEntry(session, {
+ callId: toolCall.toolCallId,
+ definition,
+ input: resolveToolCallInputObject(toolCall.input, {
+ callId: toolCall.toolCallId,
+ toolName: toolCall.toolName,
+ }),
+ toolName: toolCall.toolName,
+ turnId: input.turnId,
+ });
+ session = committed.session;
+ workflowRequests.push(
+ createCoordinationRequestFromToolCall({
+ entry: committed.entry,
+ input: committed.input,
+ toolCall,
+ tools: input.tools,
+ }),
+ );
+ }
+ return { session, workflowRequests };
+}
diff --git a/packages/eve/src/internal/testing/approval-resume.ts b/packages/eve/src/internal/testing/approval-resume.ts
new file mode 100644
index 000000000..fa784d99c
--- /dev/null
+++ b/packages/eve/src/internal/testing/approval-resume.ts
@@ -0,0 +1,88 @@
+import { simulateReadableStream } from "ai";
+import type { MockLanguageModelV4 } from "ai/test";
+import { ContextContainer } from "#context/container.js";
+import { AuthKey, SessionIdKey, SessionKey } from "#context/keys.js";
+
+export const usage = {
+ inputTokens: {
+ cacheRead: undefined,
+ cacheWrite: undefined,
+ noCache: 1,
+ total: 1,
+ },
+ outputTokens: {
+ reasoning: undefined,
+ text: 1,
+ total: 1,
+ },
+};
+
+type StreamResult = Awaited<ReturnType<MockLanguageModelV4["doStream"]>>;
+type StreamPart = StreamResult["stream"] extends ReadableStream<infer Part> ? Part : never;
+
+export function textStreamResult(text: string): StreamResult {
+ return {
+ stream: simulateReadableStream({
+ chunks: [
+ { type: "stream-start", warnings: [] },
+ { id: "answer", type: "text-start" },
+ { delta: text, id: "answer", type: "text-delta" },
+ { id: "answer", type: "text-end" },
+ {
+ finishReason: { raw: undefined, unified: "stop" },
+ type: "finish",
+ usage,
+ },
+ ] satisfies StreamPart[],
+ }),
+ };
+}
+
+export function toolCallStreamResult(call: {
+ readonly input: string;
+ readonly toolCallId: string;
+ readonly toolName: string;
+}): StreamResult {
+ return toolCallsStreamResult([call]);
+}
+
+export function toolCallsStreamResult(
+ calls: readonly {
+ readonly input: string;
+ readonly toolCallId: string;
+ readonly toolName: string;
+ }[],
+): StreamResult {
+ return {
+ stream: simulateReadableStream({
+ chunks: [
+ { type: "stream-start", warnings: [] },
+ ...calls.map((call) => ({ ...call, type: "tool-call" as const })),
+ {
+ finishReason: { raw: undefined, unified: "tool-calls" },
+ type: "finish",
+ usage,
+ },
+ ] satisfies StreamPart[],
+ }),
+ };
+}
+
+export function createApprovalContext(): ContextContainer {
+ const responder = {
+ attributes: {},
+ authenticator: "test",
+ issuer: "test",
+ principalId: "user-1",
+ principalType: "user" as const,
+ };
+ const ctx = new ContextContainer();
+ ctx.set(AuthKey, responder);
+ ctx.set(SessionIdKey, "generate-approval-resume-session");
+ ctx.set(SessionKey, {
+ auth: { current: responder, initiator: null },
+ sessionId: "generate-approval-resume-session",
+ turn: { id: "turn-1", sequence: 1 },
+ });
+ return ctx;
+}