Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): cancel the turn tree when a session token-budget prompt is declined (#1050)

Ruidd1ba234d257
diff --git a/.changeset/violet-buttons-decline.md b/.changeset/violet-buttons-decline.md
new file mode 100644
index 000000000..0e83f65e7
--- /dev/null
+++ b/.changeset/violet-buttons-decline.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Declining a session token-budget prompt now cancels the in-flight turn cleanly (`turn.cancelled` → `session.waiting`) instead of completing the session or surfacing an error to the delegating parent. Declining a delegated child's prompt cancels the whole turn tree from the root, so the parent can no longer retry the child against a fresh quota share, and stale answers to budget prompts are dropped instead of being shown to the model. The prompt copy is reworded ("This session has hit the input-token limit (2M) per session…") with Approve/Stop buttons.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 21d574530..753e5fa77 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -139,11 +139,16 @@ Input and output budgets are checked independently. The model call that crosses
either limit is allowed to finish because providers only report exact token
usage after a call completes. Before the next model call, eve pauses the
session and sends a deterministic continuation prompt with two options:
-**Continue** grants a fresh budget window of the configured size (both input
-and output windows reset together), and **Stop** ends the session gracefully
-(`session.completed`) — declining is a user decision, not an error. A reply
-that answers neither option re-raises the prompt; the reply stays in history
-and is processed once the budget is granted.
+**Approve** grants a fresh budget window of the configured size (both input
+and output windows reset together), and **Stop** cancels the in-flight turn
+through the standard cancellation path (`turn.cancelled` → `session.waiting`)
+— a user decision, not an error. The session stays resumable; because it is
+still over budget, the next message re-raises the prompt. Declining a
+delegated child's prompt cancels the root turn, which cascades to the whole
+delegation tree — the delegating parent never receives an error result it
+could retry against a fresh quota share. A reply that answers neither option
+re-raises the prompt; the reply stays in history and is processed once the
+budget is granted.
Sessions that cannot reach a human — task-mode runs such as schedules and
subagents without input proxying — skip the prompt and fail the next model
diff --git a/e2e/fixtures/agent-session-limits/evals/limits/session-token-limit-continuation.eval.ts b/e2e/fixtures/agent-session-limits/evals/limits/session-token-limit-continuation.eval.ts
index 5237b26ea..210348c8d 100644
--- a/e2e/fixtures/agent-session-limits/evals/limits/session-token-limit-continuation.eval.ts
+++ b/e2e/fixtures/agent-session-limits/evals/limits/session-token-limit-continuation.eval.ts
@@ -4,11 +4,13 @@ import { equals } from "eve/evals/expect";
/**
* Session token limits over HTTP: a conversation session that crosses its
* input budget parks on the deterministic `session_limit_continuation`
- * prompt instead of failing, and answering "Continue" grants a fresh budget
- * window and processes the queued message.
+ * prompt instead of failing. Approving grants a fresh budget window and
+ * processes the queued message; declining cancels the in-flight turn
+ * (`turn.cancelled` → `session.waiting`) and keeps the session resumable —
+ * a user decision, not an error and not a session end.
*/
export default defineEval({
- description: "Session token limit parks on a continuation prompt; Continue resumes.",
+ description: "Session token limit parks on a continuation prompt; approve resumes, stop cancels.",
async test(t) {
// The 1-token budget lets this first call finish (limits are checked
// before the next call) but leaves the session over its input limit.
@@ -47,9 +49,10 @@ export default defineEval({
requestId: stopRequest.requestId,
});
stopped.expectOk();
- stopSession.succeeded();
stopSession.notEvent("turn.failed");
- stopSession.event("session.completed");
- t.check(stopped.status, equals("completed"));
+ stopSession.notEvent("session.failed");
+ stopSession.notEvent("session.completed");
+ stopSession.event("turn.cancelled");
+ t.check(stopped.status, equals("waiting"));
},
});
diff --git a/packages/eve/src/compiler/compile-from-memory.ts b/packages/eve/src/compiler/compile-from-memory.ts
index 6578666b9..88ced77c4 100644
--- a/packages/eve/src/compiler/compile-from-memory.ts
+++ b/packages/eve/src/compiler/compile-from-memory.ts
@@ -28,6 +28,11 @@ export interface CompileFromMemoryInput {
readonly agentRoot?: string;
/** Model id assigned to the synthetic agent config. */
readonly model: string;
+ /** Session token limits assigned to the synthetic agent config. */
+ readonly limits?: {
+ readonly maxInputTokensPerSession?: number | false;
+ readonly maxOutputTokensPerSession?: number | false;
+ };
readonly outputSchema?: JsonObject;
/**
* Authored tools to project into the compiled manifest and module map.
@@ -95,6 +100,9 @@ export function compileFromMemory(input: CompileFromMemoryInput): CompileFromMem
model: { id: input.model, routing: classifyModelRouting(input.model) },
name: agentName,
};
+ if (input.limits !== undefined) {
+ config.limits = input.limits;
+ }
if (input.outputSchema !== undefined) {
config.outputSchema = input.outputSchema;
}
diff --git a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
new file mode 100644
index 000000000..49fb634ca
--- /dev/null
+++ b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
@@ -0,0 +1,250 @@
+import { describe, expect, it } from "vitest";
+import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";
+
+import { createTestRuntime } from "#internal/testing/app-harness.js";
+import {
+ captureTurnEvents,
+ containsEventSequence,
+ filterEventsByType,
+} from "#internal/testing/events.js";
+import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { sessionCancelHookToken } from "#execution/turn-cancellation-token.js";
+import { workflowEntry } from "#execution/workflow-entry.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+
+/**
+ * Declining a session-limit continuation prompt cancels the in-flight turn
+ * tree through the standard cancellation path: `turn.cancelled` →
+ * `session.waiting`, zero failure events, and a session that stays
+ * resumable. A delegated child's decline cancels the root turn, so the
+ * delegating parent never receives an error result it could retry against a
+ * fresh budget share.
+ */
+
+const FAILURE_EVENT_TYPES = ["step.failed", "turn.failed", "session.failed"] as const;
+
+function buildSerializedContext(overrides: {
+ channelKind: string;
+ continuationToken: string;
+ mode: string;
+}): Record<string, unknown> {
+ return {
+ "eve.auth": null,
+ "eve.bundle": { source: createBundledRuntimeCompiledArtifactsSource() },
+ "eve.channel": { kind: overrides.channelKind, state: {} },
+ "eve.continuationToken": overrides.continuationToken,
+ "eve.mode": overrides.mode,
+ };
+}
+
+function expectNoFailureEvents(events: readonly HandleMessageStreamEvent[]): void {
+ const types = events.map((event) => event.type);
+ for (const failureType of FAILURE_EVENT_TYPES) {
+ expect(types).not.toContain(failureType);
+ }
+}
+
+/**
+ * Delivers a payload to the session's delivery hook, retrying through the
+ * park boundary's dispose/recreate window. `waitForHook` cannot gate
+ * repeated deliveries on one token — it treats a hook that ever received a
+ * payload as consumed — so the retry is the barrier here.
+ */
+async function deliver(
+ continuationToken: string,
+ payload: Record<string, unknown>,
+ timeout = 15_000,
+): Promise<void> {
+ const deadline = Date.now() + timeout;
+ while (true) {
+ try {
+ await resumeHook(continuationToken, payload);
+ return;
+ } catch (error) {
+ if (Date.now() > deadline) throw error;
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ }
+ }
+}
+
+/** Polls the world for a hook row by token (hooks are per-run; the token is global). */
+async function waitForHookByToken(token: string, timeout = 15_000): Promise<{ runId: string }> {
+ const world = await getWorld();
+ const deadline = Date.now() + timeout;
+ while (Date.now() < deadline) {
+ try {
+ const hook = await world.hooks.getByToken(token);
+ if (hook !== null && hook !== undefined) {
+ return hook;
+ }
+ } catch {
+ // Not registered yet.
+ }
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ }
+ throw new Error(`Timed out waiting for hook token "${token}".`);
+}
+
+/** Polls the world until the given run reaches `completed`. */
+async function waitForRunCompletion(runId: string, timeout = 15_000): Promise<void> {
+ const world = await getWorld();
+ const deadline = Date.now() + timeout;
+ while (Date.now() < deadline) {
+ const page = await world.runs.list({ pagination: { limit: 100 } });
+ const row = page.data.find((entry: { runId?: string }) => entry.runId === runId);
+ if (row?.status === "completed") return;
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ }
+ throw new Error(`Timed out waiting for run "${runId}" to complete.`);
+}
+
+function requestIdFromPromptTurn(events: readonly HandleMessageStreamEvent[]): string {
+ const requested = filterEventsByType(events, "input.requested");
+ expect(requested).toHaveLength(1);
+ const requestId = requested[0]?.data.requests[0]?.requestId;
+ if (requestId === undefined) {
+ throw new Error("Expected the continuation prompt to carry a request id.");
+ }
+ return requestId;
+}
+
+describe("session-limit continuation decline integration", () => {
+ it("cancels the turn and keeps the session resumable when the user declines", async () => {
+ const runtime = createTestRuntime({
+ agent: { limits: { maxInputTokensPerSession: 1 }, name: "limit-decline-root" },
+ });
+ const continuationToken = "http:limit-decline-root";
+
+ await runtime.run(async () => {
+ const run = await start(workflowEntry, [
+ {
+ input: { message: "Hello there" },
+ serializedContext: buildSerializedContext({
+ channelKind: "http",
+ continuationToken,
+ mode: "conversation",
+ }),
+ },
+ ]);
+ const stream = captureTurnEvents(run);
+
+ try {
+ // Turn 1 replies normally and spends the 1-token budget.
+ const firstTurn = await stream.nextTurn();
+ expect(firstTurn.at(-1)?.type).toBe("session.waiting");
+ expectNoFailureEvents(firstTurn);
+
+ // Turn 2 parks on the continuation prompt before any model call.
+ await deliver(continuationToken, {
+ kind: "deliver",
+ payloads: [{ message: "keep going please" }],
+ });
+ const promptTurn = await stream.nextTurn();
+ expect(promptTurn.at(-1)?.type).toBe("session.waiting");
+ const requestId = requestIdFromPromptTurn(promptTurn);
+
+ // Declining settles the turn as cancelled — a user decision, not an
+ // error, and not a session end.
+ await deliver(continuationToken, {
+ kind: "deliver",
+ payloads: [{ inputResponses: [{ optionId: "stop", requestId }] }],
+ });
+ const declinedTurn = await stream.nextTurn();
+
+ expect(declinedTurn.at(-1)?.type).toBe("session.waiting");
+ expect(
+ containsEventSequence(declinedTurn, [
+ "turn.started",
+ "turn.cancelled",
+ "session.waiting",
+ ]),
+ ).toBe(true);
+ expect(filterEventsByType(declinedTurn, "turn.cancelled")).toHaveLength(1);
+ expect(filterEventsByType(declinedTurn, "session.completed")).toHaveLength(0);
+ expectNoFailureEvents(declinedTurn);
+
+ // The session stays over budget, so the next message re-raises the
+ // prompt (fail-closed) instead of running a model call.
+ await deliver(continuationToken, {
+ kind: "deliver",
+ payloads: [{ message: "try again" }],
+ });
+ const repromptTurn = await stream.nextTurn();
+
+ expect(repromptTurn.at(-1)?.type).toBe("session.waiting");
+ expect(filterEventsByType(repromptTurn, "input.requested")).toHaveLength(1);
+ expect(filterEventsByType(repromptTurn, "turn.cancelled")).toHaveLength(0);
+ expectNoFailureEvents(repromptTurn);
+ } finally {
+ stream.dispose();
+ await run.cancel();
+ }
+ });
+ }, 60_000);
+
+ it("cancels the root turn when the user declines a delegated child's prompt", async () => {
+ const runtime = createTestRuntime({
+ agent: { limits: { maxInputTokensPerSession: 1 }, name: "limit-decline-child" },
+ });
+ const continuationToken = "http:limit-decline-child";
+
+ await runtime.run(async () => {
+ const run = await start(workflowEntry, [
+ {
+ input: { message: "Delegate to a subagent: summarize the weather." },
+ serializedContext: {
+ ...buildSerializedContext({
+ channelKind: "http",
+ continuationToken,
+ mode: "conversation",
+ }),
+ "eve.capabilities": { requestInput: true },
+ },
+ },
+ ]);
+ const stream = captureTurnEvents(run);
+
+ try {
+ // The root's first model call spends the budget, so the delegated
+ // child inherits a zero remainder and parks on its continuation
+ // prompt before any model call. The proxy epilogue streams this
+ // turn's waiting boundary while the root keeps waiting on the child.
+ const hitlTurn = await stream.nextTurn();
+ expect(hitlTurn.at(-1)?.type).toBe("session.waiting");
+ expect(filterEventsByType(hitlTurn, "subagent.called")).toHaveLength(1);
+ const requestId = requestIdFromPromptTurn(hitlTurn);
+
+ const cancelHook = await waitForHookByToken(sessionCancelHookToken(run.runId));
+
+ // Declining the child's prompt cancels the root turn. The waiting
+ // boundary is already on the stream, so settling emits nothing new;
+ // the turn run completing is the settle barrier.
+ await deliver(continuationToken, {
+ kind: "deliver",
+ payloads: [{ inputResponses: [{ optionId: "stop", requestId }] }],
+ });
+ await waitForRunCompletion(cancelHook.runId);
+
+ // The session accepts the next message; the root itself is over
+ // budget, so it re-raises its own prompt. Anything from the old
+ // decline path — a parent-visible subagent error, a retry
+ // re-dispatch, a model reply — would surface here instead.
+ await deliver(continuationToken, {
+ kind: "deliver",
+ payloads: [{ message: "follow up after decline" }],
+ });
+ const followUpTurn = await stream.nextTurn();
+
+ expect(followUpTurn.at(-1)?.type).toBe("session.waiting");
+ expect(filterEventsByType(followUpTurn, "input.requested")).toHaveLength(1);
+ expect(filterEventsByType(followUpTurn, "subagent.called")).toHaveLength(0);
+ expect(filterEventsByType(followUpTurn, "message.completed")).toHaveLength(0);
+ expect(filterEventsByType(followUpTurn, "session.completed")).toHaveLength(0);
+ expectNoFailureEvents(followUpTurn);
+ } finally {
+ stream.dispose();
+ await run.cancel();
+ }
+ });
+ }, 60_000);
+});
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index a05353d71..d8572458f 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -11,7 +11,11 @@ import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js
import { runStep } from "#context/run-step.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import { getHarnessEmissionState } from "#harness/emission.js";
-import { isTurnCancellation, throwIfTurnAborted } from "#harness/turn-cancellation.js";
+import {
+ isSessionLimitDecline,
+ isTurnCancellation,
+ throwIfTurnAborted,
+} from "#harness/turn-cancellation.js";
import { setChannelContext } from "#execution/channel-context.js";
import { hasPendingInputBatch } from "#harness/input-requests.js";
import { coalesceTurnInputs } from "#harness/messages.js";
@@ -62,6 +66,7 @@ import { buildTurnAttributes, readRootSessionId } from "#execution/eve-workflow-
import { normalizeEveAttributes } from "#runtime/attributes/normalize.js";
import {
createWorkflowRuntime,
+ requestWorkflowTurnCancellation,
startWorkflowPreferLatest,
turnWorkflowReference,
} from "#execution/workflow-runtime.js";
@@ -368,6 +373,19 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
} catch (error) {
if (!isTurnCancellation(error)) throw error;
writer.releaseLock();
+ // A declined session-limit prompt stops the whole delegation tree: a
+ // delegated session cancels the root turn before settling itself, and
+ // the root's cancelled arm cascades back down to every descendant. Root
+ // sessions carry no parent lineage and need no upward call — their own
+ // cancelled park runs the cascade. Both `accepted` and `no_active_turn`
+ // are successful outcomes, and the cascade's redundant cancel back to
+ // this already-settling session is a benign no-op.
+ if (isSessionLimitDecline(error)) {
+ const rootSessionId = readRootSessionId(input.serializedContext);
+ if (rootSessionId !== undefined) {
+ await requestWorkflowTurnCancellation({ sessionId: rootSessionId });
+ }
+ }
return {
action: "cancelled",
serializedContext: input.serializedContext,
diff --git a/packages/eve/src/harness/session-limit-continuation.test.ts b/packages/eve/src/harness/session-limit-continuation.test.ts
index 473d5083d..40f97627c 100644
--- a/packages/eve/src/harness/session-limit-continuation.test.ts
+++ b/packages/eve/src/harness/session-limit-continuation.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import {
createSessionLimitContinuationRequest,
isSessionLimitContinuationRequest,
+ isSessionLimitContinuationRequestId,
resolveSessionLimitContinuation,
} from "#harness/session-limit-continuation.js";
@@ -33,24 +34,41 @@ describe("createSessionLimitContinuationRequest", () => {
display: "confirmation",
options: [
{
- description: "Reset quota and keep going",
+ description: "Grant a fresh token budget",
id: "continue",
- label: "Continue",
+ label: "Approve",
style: "primary",
},
{
- description: "End the session here",
+ description: "Stop now",
id: "stop",
label: "Stop",
style: "danger",
},
],
prompt:
- "The session used 40,120,500 of its 40,000,000 input-token budget. Continue with a fresh budget?",
+ "This session has hit the input-token limit (40M) per session. This is a guardrail " +
+ "against defective long-running sessions. If session activity looks fine, just " +
+ "approve to keep going.",
requestId: "sess-test:limit:input:40120500",
});
});
+ it("formats the limit compactly in the prompt copy", () => {
+ const promptFor = (limit: number): string =>
+ createSessionLimitContinuationRequest({
+ sessionId: "sess-test",
+ totalUsedTokens: limit + 1,
+ violation: { kind: "input", limit, usedTokens: limit + 1 },
+ }).prompt;
+
+ expect(promptFor(2_000_000)).toContain("(2M)");
+ expect(promptFor(1_872_014)).toContain("(1.9M)");
+ expect(promptFor(200_000)).toContain("(200K)");
+ expect(promptFor(1_500)).toContain("(1.5K)");
+ expect(promptFor(999)).toContain("(999)");
+ });
+
it("gives each violation instance its own id as the session total grows", () => {
// The absolute total is strictly increasing across grants, so a stale
// response to an earlier prompt never resolves a later one.
@@ -66,6 +84,13 @@ describe("createSessionLimitContinuationRequest", () => {
it("is recognized by isSessionLimitContinuationRequest", () => {
expect(isSessionLimitContinuationRequest(createTestRequest())).toBe(true);
});
+
+ it("mints ids recognized by isSessionLimitContinuationRequestId", () => {
+ expect(isSessionLimitContinuationRequestId(createTestRequest().requestId)).toBe(true);
+ expect(isSessionLimitContinuationRequestId("sess-test:limit:output:12")).toBe(true);
+ expect(isSessionLimitContinuationRequestId("approval-1")).toBe(false);
+ expect(isSessionLimitContinuationRequestId("sess-test:limit:input:")).toBe(false);
+ });
});
describe("resolveSessionLimitContinuation", () => {
diff --git a/packages/eve/src/harness/session-limit-continuation.ts b/packages/eve/src/harness/session-limit-continuation.ts
index 88423a9c4..904a64663 100644
--- a/packages/eve/src/harness/session-limit-continuation.ts
+++ b/packages/eve/src/harness/session-limit-continuation.ts
@@ -40,8 +40,6 @@ export function createSessionLimitContinuationRequest(input: {
}): InputRequest {
const { sessionId, totalUsedTokens, violation } = input;
const requestId = `${sessionId}:limit:${violation.kind}:${String(totalUsedTokens)}`;
- const limitLabel = violation.limit.toLocaleString("en-US");
- const usedLabel = violation.usedTokens.toLocaleString("en-US");
return {
action: {
@@ -58,23 +56,46 @@ export function createSessionLimitContinuationRequest(input: {
display: "confirmation",
options: [
{
- description: "Reset quota and keep going",
+ description: "Grant a fresh token budget",
id: SESSION_LIMIT_CONTINUE_OPTION_ID,
- label: "Continue",
+ label: "Approve",
style: "primary",
},
{
- description: "End the session here",
+ description: "Stop now",
id: SESSION_LIMIT_STOP_OPTION_ID,
label: "Stop",
style: "danger",
},
],
- prompt: `The session used ${usedLabel} of its ${limitLabel} ${violation.kind}-token budget. Continue with a fresh budget?`,
+ prompt:
+ `This session has hit the ${violation.kind}-token limit ` +
+ `(${formatCompactTokenCount(violation.limit)}) per session. This is a guardrail ` +
+ `against defective long-running sessions. If session activity looks fine, ` +
+ `just approve to keep going.`,
requestId,
};
}
+/**
+ * Formats a token count compactly for prompt copy: `2M`, `1.9M`, `200K`;
+ * exact below 1,000.
+ */
+function formatCompactTokenCount(count: number): string {
+ if (count >= 1_000_000) {
+ return `${trimTrailingZero(count / 1_000_000)}M`;
+ }
+ if (count >= 1_000) {
+ return `${trimTrailingZero(count / 1_000)}K`;
+ }
+ return String(count);
+}
+
+function trimTrailingZero(value: number): string {
+ const rounded = value.toFixed(1);
+ return rounded.endsWith(".0") ? rounded.slice(0, -2) : rounded;
+}
+
/**
* Returns true when a request is a harness-authored session-limit
* continuation prompt.
@@ -83,6 +104,17 @@ export function isSessionLimitContinuationRequest(request: InputRequest): boolea
return request.action.toolName === SESSION_LIMIT_CONTINUATION_TOOL_NAME;
}
+/**
+ * Matches request ids minted by {@link createSessionLimitContinuationRequest}.
+ *
+ * Continuation requests never enter model history (no matching tool call
+ * exists), so the id shape is the only durable marker for recognizing a
+ * stale continuation answer after its request left the pending batch.
+ */
+export function isSessionLimitContinuationRequestId(requestId: string): boolean {
+ return /:limit:(?:input|output):\d+$/u.test(requestId);
+}
+
/**
* Resolves the user's answer to a session-limit continuation prompt.
*
diff --git a/packages/eve/src/harness/session-limit-enforcement.ts b/packages/eve/src/harness/session-limit-enforcement.ts
index c34876052..049f56799 100644
--- a/packages/eve/src/harness/session-limit-enforcement.ts
+++ b/packages/eve/src/harness/session-limit-enforcement.ts
@@ -5,7 +5,7 @@
*
* 1. {@link applySessionLimitContinuation} runs after pending-input
* resolution and acts on the user's answer to a continuation prompt —
- * grant a fresh budget window, or end the session.
+ * grant a fresh budget window, or cancel the in-flight turn tree.
* 2. {@link enforceSessionTokenLimit} runs before each model call and, when
* the session is over budget, parks it on the deterministic continuation
* prompt (sessions that can reach a human) or fails it (task-mode sessions
@@ -13,11 +13,7 @@
*/
import type { ModelMessage } from "ai";
-import {
- createInputRequestedEvent,
- createSessionCompletedEvent,
- createTurnCompletedEvent,
-} from "#protocol/message.js";
+import { createInputRequestedEvent } from "#protocol/message.js";
import {
emitFailedStep,
emitTurnEpilogue,
@@ -26,6 +22,7 @@ import {
} from "#harness/emission.js";
import { setPendingInputBatch } from "#harness/input-requests.js";
import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
+import { SessionLimitDeclinedError } from "#harness/turn-cancellation.js";
import {
extendSessionTokenBudget,
getSessionTokenLimitViolation,
@@ -48,11 +45,14 @@ interface SessionLimitPolicyInput {
*
* Granted: resets the token budget windows via
* {@link extendSessionTokenBudget} and lets the step continue transparently.
- * Declined: a user decision, not an error — conversation sessions end
- * gracefully (`turn.completed` → `session.completed`, no extra copy; the
- * resolved prompt is the acknowledgment), while task mode keeps the
- * structured failure so the parent tool call receives an error result rather
- * than an empty success.
+ * Declined: a user decision, not an error — the decline cancels the
+ * in-flight turn tree through the standard cancellation path, settling as
+ * `turn.cancelled` → `session.waiting` with no failure surfaced anywhere.
+ * The harness only declares the intent by throwing
+ * {@link SessionLimitDeclinedError}; the execution layer detects it at the
+ * step boundary and cancels the root turn, whose cancelled arm cascades to
+ * every descendant, so the delegating parent never receives an error result
+ * it could retry against a fresh budget share.
*
* Returns `result: null` when the step should continue with `session`.
*/
@@ -69,32 +69,26 @@ export async function applySessionLimitContinuation(
return { result: null, session: extendSessionTokenBudget(input.session) };
}
- const violation = getSessionTokenLimitViolation(input.session);
- if (violation === null) {
- return { result: null, session: input.session };
- }
-
- if (input.config.mode === "task") {
+ // A session parked on the continuation prompt always satisfies the
+ // cancelled-park guard (conversation mode, or a continuation token
+ // anchoring it to a waiting parent) — parking the prompt required one of
+ // the two. The terminal fallback covers any future caller that resolves
+ // a decline outside that state, where a thrown cancellation could not
+ // settle as a park.
+ const canSettleCancelledPark =
+ input.config.mode === "conversation" || input.session.continuationToken !== "";
+ if (!canSettleCancelledPark) {
+ const violation = getSessionTokenLimitViolation(input.session);
return {
- result: await failSessionTokenLimit({ ...input, violation }),
+ result:
+ violation === null
+ ? { next: { done: true, output: "" }, session: input.session }
+ : await failSessionTokenLimit({ ...input, violation }),
session: input.session,
};
}
- if (input.emit) {
- await input.emit(
- createTurnCompletedEvent({
- sequence: input.emissionState.sequence,
- turnId: input.emissionState.turnId,
- }),
- );
- await input.emit(createSessionCompletedEvent());
- }
-
- return {
- result: { next: { done: true, output: "" }, session: input.session },
- session: input.session,
- };
+ throw new SessionLimitDeclinedError();
}
/**
diff --git a/packages/eve/src/harness/stale-input-responses.test.ts b/packages/eve/src/harness/stale-input-responses.test.ts
index 637dcf6df..b0575e568 100644
--- a/packages/eve/src/harness/stale-input-responses.test.ts
+++ b/packages/eve/src/harness/stale-input-responses.test.ts
@@ -2,7 +2,10 @@ import { expect, it } from "vitest";
import type { ModelMessage } from "ai";
-import { convertStaleResponsesToUserMessage } from "#harness/stale-input-responses.js";
+import {
+ convertStaleResponsesToUserMessage,
+ dropStaleSessionLimitContinuationResponses,
+} from "#harness/stale-input-responses.js";
const approvalHistory: ModelMessage[] = [
{
@@ -145,3 +148,78 @@ it("returns unchanged when every response matches the pending batch", () => {
expect(result.kind).toBe("unchanged");
expect(result.stepInput).toBe(stepInput);
});
+
+it("drops a stale session-limit continuation answer and keeps the rest of the input", () => {
+ const stepInput = dropStaleSessionLimitContinuationResponses({
+ pendingRequestIds: new Set(),
+ stepInput: {
+ inputResponses: [{ optionId: "stop", requestId: "sess-1:limit:input:12" }],
+ message: "also do this",
+ },
+ });
+
+ // Nothing model-visible: a stale "Stop" must not read as prose, and a
+ // stale grant must not extend any budget.
+ expect(stepInput?.inputResponses).toBeUndefined();
+ expect(stepInput?.message).toBe("also do this");
+});
+
+it("keeps pending and non-continuation responses while dropping stale continuation answers", () => {
+ const stepInput = dropStaleSessionLimitContinuationResponses({
+ pendingRequestIds: new Set(["question-1", "sess-1:limit:input:20"]),
+ stepInput: {
+ inputResponses: [
+ { optionId: "candidate", requestId: "question-1" },
+ { optionId: "continue", requestId: "sess-1:limit:input:12" },
+ { optionId: "stop", requestId: "sess-1:limit:input:20" },
+ ],
+ },
+ });
+
+ // The stale grant is dropped; the pending question answer and the answer
+ // to the currently pending continuation prompt pass through.
+ expect(stepInput?.inputResponses).toEqual([
+ { optionId: "candidate", requestId: "question-1" },
+ { optionId: "stop", requestId: "sess-1:limit:input:20" },
+ ]);
+});
+
+it("returns the input unchanged when nothing is dropped", () => {
+ const stepInput = {
+ inputResponses: [{ optionId: "candidate", requestId: "question-1" }],
+ };
+
+ expect(
+ dropStaleSessionLimitContinuationResponses({
+ pendingRequestIds: new Set(),
+ stepInput,
+ }),
+ ).toBe(stepInput);
+});
+
+it("converts remaining stale responses after the drop pass", () => {
+ const pendingRequestIds = new Set<string>();
+ const stepInput = dropStaleSessionLimitContinuationResponses({
+ pendingRequestIds,
+ stepInput: {
+ inputResponses: [
+ { optionId: "candidate", requestId: "question-1" },
+ { optionId: "stop", requestId: "sess-1:limit:input:12" },
+ ],
+ },
+ });
+ const result = convertStaleResponsesToUserMessage({
+ history: questionHistory,
+ pendingRequestIds,
+ stepInput,
+ });
+
+ expect(result.kind).toBe("converted");
+ if (result.kind !== "converted") {
+ throw new Error("Expected the stale response to be converted.");
+ }
+
+ expect(result.stepInput.inputResponses).toBeUndefined();
+ expect(result.stepInput.message).toEqual(expect.stringContaining("question-1"));
+ expect(result.stepInput.message).not.toEqual(expect.stringContaining("limit:input"));
+});
diff --git a/packages/eve/src/harness/stale-input-responses.ts b/packages/eve/src/harness/stale-input-responses.ts
index 0f50808f6..0bc351fa0 100644
--- a/packages/eve/src/harness/stale-input-responses.ts
+++ b/packages/eve/src/harness/stale-input-responses.ts
@@ -3,6 +3,7 @@ import type { ModelMessage, UserContent } from "ai";
import { extractHistoricalInputRequests } from "#harness/input-extraction.js";
import { isApprovalRequest } from "#harness/input-requests.js";
import { appendUserContent, normalizeUserContent } from "#harness/messages.js";
+import { isSessionLimitContinuationRequestId } from "#harness/session-limit-continuation.js";
import type { StepInput } from "#harness/types.js";
import type { InputRequest, InputResponse } from "#runtime/input/types.js";
@@ -18,14 +19,53 @@ type StaleResponseConversion =
};
/**
- * A response is stale when its request ID is not in the currently pending
- * HITL batch: the request was already answered, cleared by a follow-up
- * message, or cancelled.
+ * Filter pass: removes stale answers to session-limit continuation prompts
+ * from the step input before any stale handling runs.
+ *
+ * These are dropped rather than converted: surfacing a stale "Stop" as
+ * conversational prose would read fail-open, and a stale grant must not
+ * extend any budget — a currently pending prompt (if any) stays parked and
+ * re-raises. Stripping the responses also keeps them from resolving (and
+ * clearing) a pending batch they never answered. Answers to a currently
+ * pending continuation prompt pass through untouched.
+ */
+export function dropStaleSessionLimitContinuationResponses(input: {
+ readonly pendingRequestIds: ReadonlySet<string>;
+ readonly stepInput?: StepInput;
+}): StepInput | undefined {
+ const responses = input.stepInput?.inputResponses;
+ if (input.stepInput === undefined || responses === undefined || responses.length === 0) {
+ return input.stepInput;
+ }
+
+ const retained = responses.filter(
+ (response) =>
+ input.pendingRequestIds.has(response.requestId) ||
+ !isSessionLimitContinuationRequestId(response.requestId),
+ );
+ if (retained.length === responses.length) {
+ return input.stepInput;
+ }
+
+ const { inputResponses: _dropped, ...remainingInput } = input.stepInput;
+ if (retained.length === 0) {
+ return remainingInput;
+ }
+ return { ...remainingInput, inputResponses: retained };
+}
+
+/**
+ * Transformation pass: a response is stale when its request ID is not in
+ * the currently pending HITL batch — the request was already answered,
+ * cleared by a follow-up message, or cancelled.
*
* Responses for pending requests stay structured; stale responses become
* plain user-message text. A stale response never reaches structured HITL
* processing, so a stale approval cannot authorize an earlier tool call.
* Request details recovered from history are best-effort model context.
+ *
+ * Assumes {@link dropStaleSessionLimitContinuationResponses} already ran:
+ * stale continuation answers must never reach this conversion.
*/
export function convertStaleResponsesToUserMessage(input: {
readonly history: readonly ModelMessage[];
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index d4dc2feab..74ea2c3ed 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -44,7 +44,7 @@ import {
import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
import { stashToolInterrupt } from "#harness/tool-interrupts.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
-import { TurnCancelledError } from "#harness/turn-cancellation.js";
+import { isSessionLimitDecline, TurnCancelledError } from "#harness/turn-cancellation.js";
import {
getSessionTokenLimitViolation,
getSessionTokenUsage,
@@ -1209,7 +1209,7 @@ describe("createToolLoopHarness", () => {
allowFreeform: false,
display: "confirmation",
options: [
- { id: "continue", label: "Continue", style: "primary" },
+ { id: "continue", label: "Approve", style: "primary" },
{ id: "stop", label: "Stop", style: "danger" },
],
requestId: LIMIT_REQUEST_ID,
@@ -1267,25 +1267,27 @@ describe("createToolLoopHarness", () => {
expect(getSessionTokenLimitViolation(resumed.session)).toBeNull();
});
- it("ends the session gracefully when the user declines the limit continuation prompt", async () => {
+ it("cancels the turn when the user declines the limit continuation prompt", async () => {
const { emit, events } = createEventCollector();
const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
const parked = await runStep(createLimitReachedSession(), { message: "Hi again" });
- const declined = await runStep(parked.session, {
+ const declined = runStep(parked.session, {
inputResponses: [{ optionId: "stop", requestId: LIMIT_REQUEST_ID }],
});
+ // A decline is a user decision, not an error: the harness declares
+ // intent by throwing the decline-flavored cancellation, which the
+ // execution layer settles as `turn.cancelled` → `session.waiting` (and,
+ // for delegated sessions, escalates to a root-turn cancel). No failure
+ // or completion events are emitted here.
+ await expect(declined).rejects.toSatisfy((error) => isSessionLimitDecline(error));
expect(vi.mocked(ToolLoopAgent)).not.toHaveBeenCalled();
- expect(declined.next).toEqual({ done: true, output: "" });
- // A decline is a user decision, not an error: no failure events, no extra
- // chat copy — the resolved prompt is the acknowledgment.
expect(events.some((event) => event.type.endsWith(".failed"))).toBe(false);
- expect(events.at(-2)?.type).toBe("turn.completed");
- expect(events.at(-1)?.type).toBe("session.completed");
+ expect(events.some((event) => event.type === "session.completed")).toBe(false);
});
- it("fails the task when a proxied user declines the limit continuation prompt", async () => {
+ it("declines with the same cancellation when the prompt was proxied to a task session", async () => {
const { emit, events } = createEventCollector();
const runStep = createToolLoopHarness(
createTestConfig("task", emit, { capabilities: { requestInput: true } }),
@@ -1294,20 +1296,16 @@ describe("createToolLoopHarness", () => {
const parked = await runStep(createLimitReachedSession(), { message: "Hi again" });
expect(parked.next).toBeNull();
- const declined = await runStep(parked.session, {
+ const declined = runStep(parked.session, {
inputResponses: [{ optionId: "stop", requestId: LIMIT_REQUEST_ID }],
});
+ // The delegating parent must never receive an error result it could
+ // retry against a fresh budget share: task-mode declines throw the same
+ // decline-flavored cancellation instead of failing the step.
+ await expect(declined).rejects.toSatisfy((error) => isSessionLimitDecline(error));
expect(vi.mocked(ToolLoopAgent)).not.toHaveBeenCalled();
- expect(declined.next).toEqual({
- done: true,
- isError: true,
- output: "The session reached its configured input token limit.",
- });
- expect(events.find((event) => event.type === "step.failed")?.data).toMatchObject({
- code: "SESSION_TOKEN_LIMIT_REACHED",
- details: { kind: "input", limit: 12, usedTokens: 12 },
- });
+ expect(events.some((event) => event.type.endsWith(".failed"))).toBe(false);
});
it("re-raises the limit prompt when the user replies without answering it", async () => {
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index b5e85c615..a9f205249 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -111,7 +111,10 @@ import {
resolvePendingInput,
setPendingInputBatch,
} from "#harness/input-requests.js";
-import { convertStaleResponsesToUserMessage } from "#harness/stale-input-responses.js";
+import {
+ convertStaleResponsesToUserMessage,
+ dropStaleSessionLimitContinuationResponses,
+} from "#harness/stale-input-responses.js";
import { getInstrumentationConfig } from "#harness/instrumentation-config.js";
import { normalizeUserContent, resolveAssistantStepText } from "#harness/messages.js";
import { normalizeProviderToolHistory } from "#harness/provider-tool-history.js";
@@ -538,10 +541,17 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
}
session = resolvedRuntimeActions.session;
+ // Stale-response handling is two passes: drop what must never reach the
+ // model (session-limit continuation answers), then convert what should
+ // reach it as plain text.
+ const pendingRequestIds = getPendingInputRequestIds(session.state);
const staleConversion = convertStaleResponsesToUserMessage({
history: resolvedRuntimeActions.messages,
- pendingRequestIds: getPendingInputRequestIds(session.state),
- stepInput: stepInput.input,
+ pendingRequestIds,
+ stepInput: dropStaleSessionLimitContinuationResponses({
+ pendingRequestIds,
+ stepInput: stepInput.input,
+ }),
});
const effectiveStepInput = staleConversion.stepInput;
const preambleStepInput =
diff --git a/packages/eve/src/harness/turn-cancellation.test.ts b/packages/eve/src/harness/turn-cancellation.test.ts
index 4719ca983..df8a7c4e8 100644
--- a/packages/eve/src/harness/turn-cancellation.test.ts
+++ b/packages/eve/src/harness/turn-cancellation.test.ts
@@ -1,7 +1,9 @@
import { describe, expect, it } from "vitest";
import {
+ isSessionLimitDecline,
isTurnCancellation,
+ SessionLimitDeclinedError,
throwIfTurnAborted,
TurnCancelledError,
} from "#harness/turn-cancellation.js";
@@ -50,6 +52,33 @@ describe("isTurnCancellation", () => {
});
});
+describe("SessionLimitDeclinedError", () => {
+ it("is a turn cancellation carrying the decline marker", () => {
+ const error = new SessionLimitDeclinedError();
+ // Keeps the canonical name so every existing cancellation check matches.
+ expect(error.name).toBe("TurnCancelledError");
+ expect(isTurnCancellation(error)).toBe(true);
+ expect(isSessionLimitDecline(error)).toBe(true);
+ });
+});
+
+describe("isSessionLimitDecline", () => {
+ it("walks the cause chain and ignores plain cancellations", () => {
+ const wrapped = new Error("outer", { cause: new SessionLimitDeclinedError() });
+ expect(isSessionLimitDecline(wrapped)).toBe(true);
+
+ expect(isSessionLimitDecline(new TurnCancelledError())).toBe(false);
+ expect(isSessionLimitDecline(undefined)).toBe(false);
+ });
+
+ it("survives a cause cycle", () => {
+ const a = new Error("a");
+ const b = new Error("b", { cause: a });
+ (a as { cause?: unknown }).cause = b;
+ expect(isSessionLimitDecline(a)).toBe(false);
+ });
+});
+
describe("throwIfTurnAborted", () => {
it("is a no-op for a missing or live signal", () => {
expect(() => throwIfTurnAborted(undefined)).not.toThrow();
diff --git a/packages/eve/src/harness/turn-cancellation.ts b/packages/eve/src/harness/turn-cancellation.ts
index 804fb6fa4..090085266 100644
--- a/packages/eve/src/harness/turn-cancellation.ts
+++ b/packages/eve/src/harness/turn-cancellation.ts
@@ -8,6 +8,37 @@ export class TurnCancelledError extends Error {
}
}
+/**
+ * A turn cancellation raised when the user declines a session-limit
+ * continuation prompt. Carries intent only — the execution layer detects it
+ * at the step boundary and cancels the root turn, so a delegated child's
+ * decline stops the whole delegation tree. Keeps the harness free of
+ * cross-session cancellation authority.
+ */
+export class SessionLimitDeclinedError extends TurnCancelledError {
+ readonly sessionLimitDeclined = true;
+
+ constructor() {
+ super("The user declined a fresh session token budget.");
+ }
+}
+
+/** True when the error, or one of its causes, marks a session-limit decline. */
+export function isSessionLimitDecline(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 { sessionLimitDeclined?: unknown }).sessionLimitDeclined === true) {
+ return true;
+ }
+ current = (current as { cause?: unknown }).cause;
+ }
+
+ return false;
+}
+
/** True when the error, or one of its causes, is a {@link TurnCancelledError}. */
export function isTurnCancellation(error: unknown): boolean {
let current: unknown = error;
diff --git a/packages/eve/src/internal/testing/app-harness.ts b/packages/eve/src/internal/testing/app-harness.ts
index 94eb222c4..b58633978 100644
--- a/packages/eve/src/internal/testing/app-harness.ts
+++ b/packages/eve/src/internal/testing/app-harness.ts
@@ -34,6 +34,10 @@ import type { MockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
*/
export interface TestAppDescriptor {
readonly agent?: {
+ readonly limits?: {
+ readonly maxInputTokensPerSession?: number | false;
+ readonly maxOutputTokensPerSession?: number | false;
+ };
readonly model?: string;
readonly name?: string;
readonly outputSchema?: JsonObject;
@@ -132,6 +136,10 @@ export function createTestRuntime(descriptor: TestAppDescriptor = {}): TestRunti
const compileInput: {
name: string;
model: string;
+ limits?: {
+ readonly maxInputTokensPerSession?: number | false;
+ readonly maxOutputTokensPerSession?: number | false;
+ };
outputSchema?: JsonObject;
tools?: readonly {
readonly name: string;
@@ -146,6 +154,7 @@ export function createTestRuntime(descriptor: TestAppDescriptor = {}): TestRunti
} = {
name: descriptor.agent?.name ?? DEFAULT_AGENT_NAME,
model: descriptor.agent?.model ?? TEST_DEFAULT_MODEL_ID,
+ limits: descriptor.agent?.limits,
outputSchema: descriptor.agent?.outputSchema,
};