Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

refactor(eve): derive session lifecycle from published events (#4177)

OwenKephart4bef05e9de93
diff --git a/.changeset/harness-step-pipeline.md b/.changeset/harness-step-pipeline.md
new file mode 100644
index 000000000..1cfc2b82a
--- /dev/null
+++ b/.changeset/harness-step-pipeline.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+The harness step is now a short pipeline over focused modules: the model call, its recovery, and the human-in-the-loop lifecycle each live in their own module. Behavior is unchanged.
diff --git a/.changeset/lazy-subagent-hook-resume.md b/.changeset/lazy-subagent-hook-resume.md
new file mode 100644
index 000000000..79c1402c3
--- /dev/null
+++ b/.changeset/lazy-subagent-hook-resume.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Restoring a session no longer loads the workflow runtime up front. It now loads when a subagent forwards an approval, sign-in, or question to its parent.
diff --git a/.changeset/session-approved-execution.md b/.changeset/session-approved-execution.md
new file mode 100644
index 000000000..b3d591142
--- /dev/null
+++ b/.changeset/session-approved-execution.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Approved local tools execute through eve's tool wrappers instead of AI SDK approval-history replay. Execution retains schema and authorization rechecks, concurrent siblings, the originating tool bindings, and the AI SDK's tool telemetry in the step's first attempt; approval markers are replaced by ordinary tool results before the next model call.
diff --git a/.changeset/session-machine-withdrawals.md b/.changeset/session-machine-withdrawals.md
new file mode 100644
index 000000000..11cb2645f
--- /dev/null
+++ b/.changeset/session-machine-withdrawals.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Pending input is withdrawn when cancellation, context clearing, or a finished workflow removes its owner. Messages behind a session-limit prompt enter a held turn once and resume after a grant without duplicate receipt, and a typed approval or budget answer no longer passes the channel context of its consumed message to the model.
diff --git a/.changeset/session-stream-facts.md b/.changeset/session-stream-facts.md
new file mode 100644
index 000000000..408942ef8
--- /dev/null
+++ b/.changeset/session-stream-facts.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+The `input.requested` stream event type gains an optional `callId`. On a request relayed from a subagent or workflow tool run, it names the call in the receiving session that the request serves; the request keeps its original turn and step coordinates, and the stream stays on version 26.
diff --git a/.changeset/tool-call-state.md b/.changeset/tool-call-state.md
new file mode 100644
index 000000000..379755cf4
--- /dev/null
+++ b/.changeset/tool-call-state.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Added `toolCallState(conversation, callId, { streaming })` to the client and frontend bindings. Tool parts and ACP tool calls follow task outcomes rather than start receipts (an ACP task call still running when its turn fails ends as failed), withdrawn approvals render as denied, and results marked `isError` render as errors; public conversation fields and eval policy remain unchanged.
diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.md
index 361edd02a..9fd53fce9 100644
--- a/docs/concepts/sessions-runs-and-streaming.md
+++ b/docs/concepts/sessions-runs-and-streaming.md
@@ -127,11 +127,11 @@ A question or sign-in from inside a running call does not end the turn. This cov
### Task events
-A call to a tool that runs as a task, such as an agent tool, `agentRouter()`, the `workflow` tool, or a workflow tool that defines [`task(input, ctx)`](/docs/tools/workflows#run-calls-as-tasks-task) or [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve), returns a receipt as its `action.result` and keeps working. `task.started` reports the task's `taskId` for the call's `callId` and `turnId`, both when a call starts a task and when a call reaches a resumable task by its `taskId`, before any event the task's run publishes for that call. `task.settled` comes once per call, with the same `turnId`, `name`, and `kind` as its `task.started`, `status` `"completed"`, `"failed"`, or `"cancelled"`, and the call's `output` when it completed or `error.message` when it failed. Events recorded by earlier eve versions omit `name` and `kind` on `task.settled`, so match them to their `task.started` by `callId` when those fields are missing. Results reach the model as a message in its history, not as a stream event, so read outcomes from `task.settled`. A session the task's run opens with `ctx.agent` is announced with `agent.started` carrying the `taskId`. An `input.requested`, `authorization.required`, or `authorization.completed` event from a task's run carries its `taskId`. Each of these events names the call the task is serving when it happens: a resumable task's later call brings its own `callId` and `turnId`, which may belong to a later turn than the call that started the task.
+A call to a tool that runs as a task, such as an agent tool, `agentRouter()`, the `workflow` tool, or a workflow tool that defines [`task(input, ctx)`](/docs/tools/workflows#run-calls-as-tasks-task) or [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve), returns a receipt as its `action.result` and keeps working. `task.started` reports the task's `taskId` for the call's `callId` and `turnId`, both when a call starts a task and when a call reaches a resumable task by its `taskId`, before any event the task's run publishes for that call. `task.settled` comes once per call, with the same `turnId`, `name`, and `kind` as its `task.started`, `status` `"completed"`, `"failed"`, or `"cancelled"`, and the call's `output` when it completed or `error.message` when it failed. Events recorded by earlier eve versions omit `name` and `kind` on `task.settled`, so match them to their `task.started` by `callId` when those fields are missing. Results reach the model as a message in its history, not as a stream event, so read outcomes from `task.settled`. A session the task's run opens with `ctx.agent` is announced with `agent.started` carrying the `taskId`. An `input.requested`, `authorization.required`, or `authorization.completed` event from a task's run carries its `taskId`. Each of these events names the call the task is serving when it happens: a resumable task's later call brings its own `callId` and `turnId`, which may belong to a later turn than the call that started the task. An `input.requested` relayed from a subagent or a workflow tool run also carries `callId`, the call in this session that the request serves. The request keeps the coordinates it was raised with, and a relayed approval's `request.action.callId` still names the asking run's call, not one of this session's.
A turn doesn't end while tasks are working. When the model ends its text early, eve holds the turn and the stream emits `turn.waiting` for it; the turn continues once a result arrives or its caller writes. In a root session, that text completes as an ordinary `message.completed`. In a child session or a schedule's session, it reports `finishReason: "tool-calls"`, so channels post only the final reply. When the model calls `task_wait` and no result is ready yet, the stream also emits `turn.waiting`. Either way, the next `step.started` for the same `turnId` means the turn resumed, and `session.waiting` comes only after the turn ends. See [Tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
-`step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, and discards incomplete assistant output. Tool calls the cancellation stopped stay in history, each answered as cancelled, so the model sees that the work started and stopped instead of a request left unanswered. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`). Both carry `data.principalId` when a session principal started the sign-in. It holds the same value as `responderPrincipalId` on approval events, so a channel can deliver the challenge privately to that person even after someone else starts a later turn.
+`step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, and discards incomplete assistant output. Tool calls the cancellation stopped stay in history, each answered as cancelled, so the model sees that the work started and stopped instead of a request left unanswered. Before `turn.cancelled`, the stream reports requests the cancel strands as `cancelled` in `input.resolved`. These include the turn's own questions, the session-limit prompt, and requests relayed from the work it stops. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`). Both carry `data.principalId` when a session principal started the sign-in. It holds the same value as `responderPrincipalId` on approval events, so a channel can deliver the challenge privately to that person even after someone else starts a later turn.
A provider response ending with `content-filter` fails with `MODEL_CALL_FAILED`,
`details.semanticErrorId: "model-response-content-filtered"`, and
@@ -261,7 +261,7 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. Attributed [memory](../memory) records are excluded from the summary, canonicalized, and recalled again after the checkpoint. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails before a checkpoint, the session returns to waiting with its previous history.
-Clear removes model-message history in place, including static and dynamic user-role instructions and recalled memory records, while preserving the session identity, system-role instructions, tools, skills, application-defined durable state, limits, and sandbox. It clears framework memory locks and replay bookkeeping but does not delete data from a provider's external store. It does not rerun instruction definitions or resolvers. It emits `context.cleared` followed by `session.waiting`.
+Clear removes model-message history in place, including static and dynamic user-role instructions and recalled memory records, while preserving the session identity, system-role instructions, tools, skills, application-defined durable state, limits, and sandbox. It clears framework memory locks and replay bookkeeping but does not delete data from a provider's external store. It does not rerun instruction definitions or resolvers. Approvals, the session-limit prompt, and sign-ins the cleared history asked for are withdrawn: each resolves as `cancelled` in `input.resolved` or `declined` in `authorization.completed`. Requests relayed from tasks that keep running stay answerable. It then emits `context.cleared` followed by `session.waiting`.
Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.md
index 97b8e3edd..e8395e6c4 100644
--- a/docs/guides/dynamic-capabilities.md
+++ b/docs/guides/dynamic-capabilities.md
@@ -362,7 +362,7 @@ A dynamic connection, tool, or skill whose name matches an **authored** one **ov
At `turn.started`, model, tool, skill, and subagent resolvers receive the visible conversation history and incoming message in `ctx.messages`, oldest first. Request context is included, and history projection still applies. Read these messages from the handler's second argument; the event itself contains turn metadata. Instruction resolvers use the separate snapshot described under [Dynamic instructions](#dynamic-instructions).
-A message that steers a held turn, or waits behind its session-limit prompt, joins that turn instead of starting one, as does a completed sign-in, so `turn.started` resolvers do not see it; `step.started` resolvers do. When memory recall runs, its results appear in the projected snapshot before incoming input.
+A message that steers a held turn joins it without another `turn.started`, as does a completed sign-in, so `turn.started` resolvers do not see it; `step.started` resolvers do. A message sent while a session-limit prompt waits starts its own turn, so `turn.started` resolvers see it, and that turn waits for the prompt's answer before the model runs. When memory recall runs, its results appear in the projected snapshot before incoming input.
### Execution order
diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdx
index 9c81f0b24..61fb6b06d 100644
--- a/docs/guides/frontend/overview.mdx
+++ b/docs/guides/frontend/overview.mdx
@@ -174,7 +174,9 @@ supplied `session` remains externally owned and is never replaced by prewarming
Common text, reasoning, file, and dynamic-tool parts follow the [AI SDK `UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) rendering convention, but the types are not interchangeable. eve also exposes authorization and HITL metadata, and a file part's URL can be absent. Adapt those parts before passing messages to an API typed as `UIMessage[]`.
-When the root agent delegates, its stream emits `task.started` for the call, `agent.started` with the child's `sessionId`, and `task.settled` with the call's result, failure, or cancellation. The default reducer settles the subagent's tool part from `task.settled`, so the part shows the call's outcome rather than its start receipt. `data.tasks[taskId].calls[callId]` records each call's `status`, `output`, and `error`, and `data.agents[sessionId]` records each session a call opened, with its `taskId` and opening `callId`. These records come from the root stream alone.
+A tool part's `state` comes from the shared lifecycle interpretation of the event stream. Its events supply input, output, and error text. A call waiting on an approval or a question reads `approval-requested` until the stream settles the request. An answer you submit doesn't change the part until then. `toolCallState(conversation, callId)` reads tool-call status, including task cancellation and calls interrupted without a result. The full event projection remains internal; `ConversationState` retains its messages, turns, inputs, tasks, and agent sessions.
+
+When the root agent delegates, its stream emits `task.started` for the call, `agent.started` with the child's `sessionId`, and `task.settled` with the call's result, failure, or cancellation. The default reducer keeps the subagent's tool part running until `task.settled` arrives and then settles it with the call's outcome; the start receipt never settles it. `data.tasks[taskId].calls[callId]` records each call's `status`, `output`, and `error`, and `data.agents[sessionId]` records each session a call opened, with its `taskId` and opening `callId`. These records come from the root stream alone.
Detailed child progress lives on the child session's stream, not in the root `data.messages`. Pass `followSubagents: true` to follow the session each subagent call reaches while the component is mounted; following is off by default. Narrow `data.agents[sessionId].observation.status` before reading its `conversation`: `"not-followed"` has no child detail, `"following"` has live detail, and `"idle"` has everything the calls so far produced and resumes when another call reaches the task. `"unavailable"` means the stream failed, not that the child failed. Calls that continue a task with its `taskId` reach the same session, so one session's `conversation.messages`, `inputs`, and `turns` span all of them. Sessions that a custom task opens with `ctx.agent` are recorded but not followed.
diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
index 5400d802d..32c0b46a8 100644
--- a/docs/guides/hooks.md
+++ b/docs/guides/hooks.md
@@ -227,7 +227,7 @@ The remaining subscribers for the event still run. Then eve cancels the turn the
Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
-Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
+Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. A proxied `input.requested` also carries `event.data.callId`, the parent call that waits on it. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
## Hook vs tool vs provider
diff --git a/packages/eve/extension-contracts/compatibility/channel/v47.ts b/packages/eve/extension-contracts/compatibility/channel/v47.ts
new file mode 100644
index 000000000..cd3f896a5
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v47.ts
@@ -0,0 +1,13 @@
+import { defineChannel, GET } from "#public/channels/index.js";
+
+export default defineChannel({
+ routes: [
+ GET("/status", async (_request, { describe, invokeTool }) => {
+ const { tools } = await describe();
+ return Response.json({
+ tools: tools.length,
+ canInvokeTools: typeof invokeTool === "function",
+ });
+ }),
+ ],
+});
diff --git a/packages/eve/extension-contracts/compatibility/connection/v38.ts b/packages/eve/extension-contracts/compatibility/connection/v38.ts
new file mode 100644
index 000000000..66f54c1e2
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/connection/v38.ts
@@ -0,0 +1,15 @@
+import { defineDynamic, defineMcpClientConnection } from "#public/connections/index.js";
+
+// Epoch 38 sign-ins didn't name the calls they stopped, and calls had no `cancelled` status;
+// both are additive.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ ctx.session.auth.current === null
+ ? null
+ : defineMcpClientConnection({
+ description: "Search the support knowledge base.",
+ url: "https://support.example.com/mcp",
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v32.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v32.ts
new file mode 100644
index 000000000..e1a123345
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v32.ts
@@ -0,0 +1,10 @@
+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";
+
+// Epoch 32 `turn.started` had no `continuesTurnId`, and calls had no `cancelled` status; both
+// are additive.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineInstructions({ markdown: `Review evidence for session ${ctx.session.id}.` }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v31.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v31.ts
new file mode 100644
index 000000000..033c30b0e
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v31.ts
@@ -0,0 +1,13 @@
+import { defineDynamic, defineSkill } from "#public/skills/index.js";
+
+// Epoch 31 `turn.started` had no `continuesTurnId`, and calls had no `cancelled` status; both
+// are additive.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineSkill({
+ description: `Review evidence for session ${ctx.session.id}.`,
+ markdown: "# Evidence review\n\nCheck every claim against its source.",
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v70.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v70.ts
new file mode 100644
index 000000000..5f5d09ee4
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v70.ts
@@ -0,0 +1,14 @@
+import { defineDynamic, defineTool } from "#public/tools/index.js";
+
+// Epoch 70 `turn.started` had no `continuesTurnId`, and calls had no `cancelled` status; both
+// are additive.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineTool({
+ description: "Return the active session identifier.",
+ inputSchema: { type: "object", properties: {} },
+ execute: () => ({ sessionId: ctx.session.id }),
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/hook/v37.ts b/packages/eve/extension-contracts/compatibility/hook/v37.ts
new file mode 100644
index 000000000..7efb07e58
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/hook/v37.ts
@@ -0,0 +1,16 @@
+import { defineHook } from "#public/hooks/index.js";
+
+// Epoch 37 calls had no `cancelled` status, and sign-ins didn't name the calls they stopped;
+// both are additive, so a hook that handles the earlier statuses still compiles.
+export default defineHook({
+ events: {
+ "action.result"(event) {
+ if (event.data.status === "failed") {
+ console.info("call failed", { callId: event.data.result.callId });
+ }
+ },
+ "authorization.required"(event, ctx) {
+ console.info("sign-in required", { name: event.data.name, sessionId: ctx.session.id });
+ },
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/schedule/v26.ts b/packages/eve/extension-contracts/compatibility/schedule/v26.ts
new file mode 100644
index 000000000..c4acff4f8
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/schedule/v26.ts
@@ -0,0 +1,23 @@
+import { defineChannel } from "#public/channels/index.js";
+import { defineSchedule } from "#public/schedules/index.js";
+
+// Epoch 26 sign-ins didn't name the calls they stopped, and calls had no `cancelled` status;
+// both are additive.
+const updates = defineChannel({
+ routes: [],
+ events: {
+ "authorization.required"(event) {
+ console.info("sign-in required", { name: event.name });
+ },
+ },
+ receive(input, { from }) {
+ return from("daily-updates").send(input.message, { auth: input.auth });
+ },
+});
+
+export default defineSchedule({
+ cron: "0 9 * * *",
+ async run({ to, appAuth }) {
+ await to(updates, {}).send("Prepare the daily summary.", { auth: appAuth });
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/subagent/v29.ts b/packages/eve/extension-contracts/compatibility/subagent/v29.ts
new file mode 100644
index 000000000..a8d8d85a9
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/subagent/v29.ts
@@ -0,0 +1,15 @@
+import { defineAgent, defineDynamic } from "#public/index.js";
+
+// Epoch 29 `turn.started` had no `continuesTurnId`, and calls had no `cancelled` status; both
+// are additive.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ ctx.session.auth.current === null
+ ? null
+ : defineAgent({
+ description: "Investigate the authenticated user request.",
+ model: "openai/gpt-5.6-sol",
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/tool/v73.ts b/packages/eve/extension-contracts/compatibility/tool/v73.ts
new file mode 100644
index 000000000..f8d596d07
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v73.ts
@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { defineTool } from "#public/tools/index.js";
+
+// Epoch 73 sign-ins didn't name the calls they stopped, and calls had no `cancelled` status.
+// Compiled epoch 73 tools still park on sign-in through ctx.getToken; both are additive.
+export default defineTool({
+ description: "List the caller's open tickets.",
+ inputSchema: z.object({ project: z.string() }),
+ async execute({ project }, ctx) {
+ const { token } = await ctx.getToken({
+ principalType: "user",
+ async getToken() {
+ return { token: "ticket-token" };
+ },
+ });
+ return { authorized: token.length > 0, project };
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/channel/v48.json b/packages/eve/extension-contracts/reports/channel/v48.json
new file mode 100644
index 000000000..b602ff022
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v48.json
@@ -0,0 +1,21 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 48,
+ "sha256": "16198a3f39e87708852bd9f2d7040afbba918b5f2608629c7d9009e9c4c59ba7",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/connection/v39.json b/packages/eve/extension-contracts/reports/connection/v39.json
new file mode 100644
index 000000000..b3237f561
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v39.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 39,
+ "sha256": "ae08efbaa75bc416e4ec4f9f96959908b20366acacfb18abd32a0be5198f003f",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineDynamic",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v33.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v33.json
new file mode 100644
index 000000000..c8c6a8e67
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v33.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicInstructions",
+ "epoch": 33,
+ "sha256": "e5a22a29be3a087cde7b4453a979a7dee1fc827c3a2aeca4c01585f2c658ba1f",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v32.json b/packages/eve/extension-contracts/reports/dynamicSkill/v32.json
new file mode 100644
index 000000000..e6b471443
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v32.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicSkill",
+ "epoch": 32,
+ "sha256": "ab41a01fff81f49e1b6c1a01b9044d7db7b4bc858660a95a66b7b6798827652f",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v71.json b/packages/eve/extension-contracts/reports/dynamicTool/v71.json
new file mode 100644
index 000000000..1bdb3955d
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v71.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 71,
+ "sha256": "685f593d35536fd94249a1484507f36280b7174b8ec564dca873029a7726ea24",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "auto",
+ "defineDurableCallback",
+ "defineDurableSchema",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v38.json b/packages/eve/extension-contracts/reports/hook/v38.json
new file mode 100644
index 000000000..1c2e61053
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v38.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 38,
+ "sha256": "ceb5c68c72a7d60ad14d2edd9ed4dac53baa2668827c898ea7cd84390e536a8f",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/extension-contracts/reports/schedule/v27.json b/packages/eve/extension-contracts/reports/schedule/v27.json
new file mode 100644
index 000000000..032d6b571
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/schedule/v27.json
@@ -0,0 +1,15 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "schedule",
+ "epoch": 27,
+ "sha256": "b8ab84d75bddb735ed9420beee7f33809525e328b772361011addefe6d9fa677",
+ "exports": [
+ "ScheduleDefinition",
+ "ScheduleHandlerArgs",
+ "ScheduleRunHandler",
+ "ScheduleToFn",
+ "TypedReceiveTarget",
+ "defineSchedule",
+ "isScheduleAuth"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/subagent/v30.json b/packages/eve/extension-contracts/reports/subagent/v30.json
new file mode 100644
index 000000000..c4ca0aba4
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/subagent/v30.json
@@ -0,0 +1,23 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "subagent",
+ "epoch": 30,
+ "sha256": "2f079964cb2dd3908e4b4eedab77ddf85ddfada51216628fdd9d0289cc89f480",
+ "exports": [
+ "AgentCompactionDefinition",
+ "AgentDefinition",
+ "AgentModelDefinition",
+ "AgentStaticModelDefinition",
+ "DefinedAgent",
+ "DynamicLocalSubagentDefinition",
+ "DynamicSubagentDefinition",
+ "RemoteAgentDefinition",
+ "RemoteAgentDefinitionInput",
+ "WorkspaceAgentDefinition",
+ "WorkspaceAgentTransport",
+ "defineAgent",
+ "defineDynamic",
+ "defineRemoteAgent",
+ "defineWorkspaceAgent"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v74.json b/packages/eve/extension-contracts/reports/tool/v74.json
new file mode 100644
index 000000000..ab6ba51af
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v74.json
@@ -0,0 +1,29 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 74,
+ "sha256": "d42e66f8c207f011f037596be12e780c746f418a6931975fd2d84095c5b8650c",
+ "exports": [
+ "AgentRouterInput",
+ "AgentRouterTool",
+ "WorkflowStepToolContext",
+ "WorkflowTool",
+ "WorkflowToolDefinition",
+ "WorkflowToolInput",
+ "WorkflowToolOptions",
+ "agentRouter",
+ "defaultWebSearch",
+ "defineTool",
+ "defineWorkflowTool",
+ "disableTool",
+ "evaluate",
+ "isDisabledToolSentinel",
+ "isWebSearchToolDefinition",
+ "serializeModelInputSchema",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch",
+ "workflow"
+ ]
+}
diff --git a/packages/eve/src/acp/adapter.test.ts b/packages/eve/src/acp/adapter.test.ts
index 9f43264f1..f2304eb56 100644
--- a/packages/eve/src/acp/adapter.test.ts
+++ b/packages/eve/src/acp/adapter.test.ts
@@ -535,37 +535,70 @@ describe("EveAcpAdapter", () => {
expect(error).toMatchObject({ code: -32_002, data: { httpStatus: 401 } });
});
- it("reports rejected actions as failed tool calls", async () => {
+ it("reports a denied approval as failed, with the denial's reason", async () => {
+ const at = { sequence: 1, stepIndex: 0, turnId: "turn-1" };
+ const action = { callId: "call-1", input: {}, kind: "tool-call" as const, toolName: "write" };
+ const waiting = {
+ type: "session.waiting" as const,
+ data: { continuationToken: "session-id", wait: "next-user-message" as const },
+ };
const { adapter } = adapterWith([
[
+ { type: "actions.requested", data: { ...at, actions: [action] } },
{
- type: "action.result",
+ type: "input.requested",
data: {
- result: {
- callId: "call-1",
- kind: "tool-result",
- output: "Denied",
- toolName: "write",
- },
- sequence: 1,
- status: "rejected",
- stepIndex: 0,
- turnId: "turn-1",
+ ...at,
+ requests: [
+ {
+ action,
+ display: "confirmation",
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "deny", label: "Deny" },
+ ],
+ prompt: "Allow write?",
+ requestId: "req-1",
+ },
+ ],
},
},
+ waiting,
+ ],
+ // The denial resolves the request before the result that carries its reason arrives.
+ [
{
- type: "session.waiting",
- data: { continuationToken: "session-id", wait: "next-user-message" },
+ type: "input.resolved",
+ data: {
+ ...at,
+ resolutions: [{ kind: "tool-approval", outcome: "denied", requestId: "req-1" }],
+ },
},
+ {
+ type: "action.result",
+ data: {
+ ...at,
+ error: { code: "TOOL_EXECUTION_DENIED", message: "Bob declined the write." },
+ result: { callId: "call-1", kind: "tool-result", output: "Denied", toolName: "write" },
+ status: "rejected",
+ },
+ },
+ waiting,
],
]);
+ const request = vi.fn(async (_method: string, params: any) => ({
+ outcome: { outcome: "selected", optionId: params.options[1].optionId },
+ })) as AgentContext["request"];
+ const { client, notifications } = acpClient({ request });
const sessionId = await createSession(adapter);
- const { client, notifications } = acpClient();
await adapter.prompt(textPrompt(sessionId), client, new AbortController().signal);
- expect(notifications).toHaveLength(1);
- expect((notifications[0]!.params as any).update.status).toBe("failed");
+ const updates = notifications
+ .map((notification) => (notification.params as any).update)
+ .filter((update) => update.sessionUpdate === "tool_call_update");
+ expect(updates.at(-1)).toMatchObject({ rawOutput: "Denied", status: "failed" });
});
it("fails unsupported authorization requests instead of ending successfully", async () => {
@@ -653,4 +686,112 @@ describe("EveAcpAdapter", () => {
await expect(adapter.close()).resolves.toBeUndefined();
expect(session.reset).toHaveBeenCalledOnce();
});
+
+ it.each(["completed", "cancelled"] as const)(
+ "delivers task settlement without output: %s",
+ async (status) => {
+ const at = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+ const { adapter } = adapterWith([
+ [
+ { type: "turn.started", data: { sequence: 0, turnId: "turn_0" } },
+ {
+ type: "actions.requested",
+ data: {
+ ...at,
+ actions: [{ callId: "c", input: {}, kind: "tool-call", toolName: "research" }],
+ },
+ },
+ {
+ type: "task.started",
+ data: { callId: "c", kind: "tool", name: "research", taskId: "t", turnId: "turn_0" },
+ },
+ {
+ type: "action.result",
+ data: {
+ ...at,
+ result: { callId: "c", kind: "tool-result", toolName: "research", output: "Started" },
+ status: "completed",
+ },
+ },
+ { type: "task.settled", data: { callId: "c", taskId: "t", turnId: "turn_0", status } },
+ { type: "turn.completed", data: { sequence: 0, turnId: "turn_0" } },
+ {
+ type: "session.waiting",
+ data: { continuationToken: "session-id", wait: "next-user-message" },
+ },
+ ],
+ ]);
+ const sessionId = await createSession(adapter);
+ const { client, notifications } = acpClient();
+ await adapter.prompt(textPrompt(sessionId), client, new AbortController().signal);
+ const statuses = notifications
+ .map(
+ ({ params }) => (params as { update: { status?: string; toolCallId?: string } }).update,
+ )
+ .filter((update) => update.toolCallId === "c")
+ .map((update) => update.status);
+ expect(statuses).toEqual([
+ "pending",
+ "in_progress",
+ status === "completed" ? "completed" : "failed",
+ ]);
+ },
+ );
+
+ it("ends a running task call with its failed turn", async () => {
+ const at = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+ const action = {
+ callId: "call_1",
+ input: {},
+ kind: "tool-call" as const,
+ toolName: "research",
+ };
+ // Tasks a failed turn leaves running are cancelled after its response ends.
+ const { adapter } = adapterWith([
+ [
+ { type: "turn.started", data: { sequence: 0, turnId: "turn_0" } },
+ { type: "actions.requested", data: { ...at, actions: [action] } },
+ {
+ type: "task.started",
+ data: {
+ callId: "call_1",
+ kind: "tool",
+ name: "research",
+ taskId: "task_1",
+ turnId: "turn_0",
+ },
+ },
+ {
+ type: "action.result",
+ data: {
+ ...at,
+ result: {
+ callId: "call_1",
+ kind: "tool-result",
+ output: "Started task task_1.",
+ toolName: "research",
+ },
+ status: "completed",
+ },
+ },
+ { type: "turn.failed", data: { ...at, code: "MODEL_CALL_FAILED", message: "boom" } },
+ {
+ type: "session.waiting",
+ data: { continuationToken: "session-id", wait: "next-user-message" },
+ },
+ ],
+ ]);
+ const sessionId = await createSession(adapter);
+ const { client, notifications } = acpClient();
+
+ await expect(
+ adapter.prompt(textPrompt(sessionId), client, new AbortController().signal),
+ ).rejects.toThrow("boom");
+
+ const statuses = notifications
+ .map(({ params }) => (params as { update: { status?: string; toolCallId?: string } }).update)
+ .filter((update) => update.toolCallId === "call_1")
+ .map((update) => update.status);
+ expect(statuses).toEqual(["pending", "in_progress", "failed"]);
+ });
});
diff --git a/packages/eve/src/acp/adapter.ts b/packages/eve/src/acp/adapter.ts
index 17d763aaa..019a1d461 100644
--- a/packages/eve/src/acp/adapter.ts
+++ b/packages/eve/src/acp/adapter.ts
@@ -14,10 +14,18 @@ import {
type PromptResponse,
type SessionUpdate,
type ToolCall,
+ type ToolCallStatus,
} from "#compiled/@agentclientprotocol/sdk/index.js";
import { Client, ClientError } from "#client/index.js";
import type { ClientOptions, SendTurnInput, SendTurnPayload } from "#client/types.js";
import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import {
+ callStatus,
+ foldSession,
+ initialSessionProjection,
+ type SessionCallStatus,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
import type { RuntimeActionRequest, RuntimeActionResult } from "#shared/action-types.js";
import type { InputRequest, InputResponse } from "#shared/input.js";
@@ -56,9 +64,22 @@ interface AdapterClient {
interface AcpSession {
client?: AdapterClientSession;
active?: ActivePrompt;
+ /** The session's lifecycle, folded from every event it streams. */
+ projection: SessionProjection;
readonly tools: Map<string, ToolCall>;
}
+/** ACP v1 has no statuses for denied or stopped calls, so they report `failed`. */
+const ACP_TOOL_STATUS: Record<SessionCallStatus | "interrupted", ToolCallStatus> = {
+ running: "in_progress",
+ "awaiting-input": "pending",
+ completed: "completed",
+ failed: "failed",
+ rejected: "failed",
+ cancelled: "failed",
+ interrupted: "failed",
+};
+
/** Configuration for translating one ACP client connection to an eve server. */
export interface EveAcpAdapterOptions {
readonly eveVersion: string;
@@ -140,6 +161,7 @@ export class EveAcpAdapter {
const sessionId = randomUUID();
this.#sessions.set(sessionId, {
+ projection: initialSessionProjection(),
tools: new Map(),
});
return { sessionId };
@@ -230,7 +252,10 @@ export class EveAcpAdapter {
throw RequestError.requestCancelled({ sessionId: params.sessionId });
}
if (cancelled || active.cancelRequested) return { stopReason: "cancelled" };
- if (failure !== undefined) throw eveFailure(failure);
+ if (failure !== undefined) {
+ await this.#failRunningCalls(params.sessionId, session, client);
+ throw eveFailure(failure);
+ }
if (unsupportedEvent !== undefined) throw unsupportedEvent;
if (inputRequests.length === 0) return { stopReason: "end_turn" };
@@ -331,6 +356,76 @@ export class EveAcpAdapter {
session: AcpSession,
event: HandleMessageStreamEvent,
client: AgentContext,
+ ): Promise<void> {
+ const before = session.projection;
+ session.projection = foldSession(before, event);
+ await this.#projectContent(sessionId, session, event, client);
+ // A call's status is the projection's: a task call runs until its task settles, and a
+ // stopped or denied call ends when the stream says so.
+ // `tool_call` already announced the calls an `actions.requested` adds. Only an announced
+ // call gets updates: an approval reaches the client through its permission request.
+ if (event.type === "actions.requested") return;
+ const updated = new Set<string>();
+ const { calls, tasks, turns } = session.projection;
+ if (calls !== before.calls || tasks !== before.tasks || turns !== before.turns) {
+ for (const callId of Object.keys(calls)) {
+ if (!session.tools.has(callId)) continue;
+ const status = callStatus(session.projection, callId);
+ if (status === undefined || status === callStatus(before, callId)) continue;
+ updated.add(callId);
+ await notifyUpdate(client, sessionId, {
+ sessionUpdate: "tool_call_update",
+ toolCallId: callId,
+ status: ACP_TOOL_STATUS[status],
+ ...callOutput(event, callId),
+ });
+ }
+ }
+ // A result reports its content even when its call had already settled, such as the reason
+ // for a denial that `input.resolved` decided first.
+ const resultCallId =
+ event.type === "action.result"
+ ? event.data.result.callId
+ : event.type === "task.settled"
+ ? event.data.callId
+ : undefined;
+ if (resultCallId === undefined || updated.has(resultCallId)) return;
+ if (!session.tools.has(resultCallId)) return;
+ const output = callOutput(event, resultCallId);
+ const status = callStatus(session.projection, resultCallId);
+ if (!("content" in output) || status === undefined) return;
+ await notifyUpdate(client, sessionId, {
+ sessionUpdate: "tool_call_update",
+ toolCallId: resultCallId,
+ status: ACP_TOOL_STATUS[status],
+ ...output,
+ });
+ }
+
+ /**
+ * A failed turn's server cancels the tasks it left running only after the response ends, so
+ * their calls end with the turn here.
+ */
+ async #failRunningCalls(
+ sessionId: string,
+ session: AcpSession,
+ client: AgentContext,
+ ): Promise<void> {
+ for (const callId of session.tools.keys()) {
+ if (callStatus(session.projection, callId) !== "running") continue;
+ await notifyUpdate(client, sessionId, {
+ sessionUpdate: "tool_call_update",
+ toolCallId: callId,
+ status: ACP_TOOL_STATUS.failed,
+ });
+ }
+ }
+
+ async #projectContent(
+ sessionId: string,
+ session: AcpSession,
+ event: HandleMessageStreamEvent,
+ client: AgentContext,
): Promise<void> {
switch (event.type) {
case "message.appended":
@@ -354,20 +449,6 @@ export class EveAcpAdapter {
await notifyUpdate(client, sessionId, { sessionUpdate: "tool_call", ...toolCall });
}
return;
- case "action.result": {
- const result = event.data.result;
- const status = event.data.status !== "completed" || result.isError ? "failed" : "completed";
- await notifyUpdate(client, sessionId, {
- sessionUpdate: "tool_call_update",
- toolCallId: result.callId,
- status,
- content: [
- { type: "content", content: { type: "text", text: stringifyOutput(result.output) } },
- ],
- rawOutput: result.output,
- });
- return;
- }
default:
return;
}
@@ -560,3 +641,25 @@ function acpRequestError(error: unknown): RequestError {
function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
+
+/** The output an event carries for a call, if it reports one. */
+function callOutput(event: HandleMessageStreamEvent, callId: string) {
+ const output =
+ event.type === "action.result" && event.data.result.callId === callId
+ ? event.data.result.output
+ : event.type === "task.settled" && event.data.callId === callId
+ ? event.data.output !== undefined
+ ? event.data.output
+ : event.data.error?.message
+ : undefined;
+ if (output === undefined) return {};
+ return {
+ content: [
+ {
+ type: "content" as const,
+ content: { type: "text" as const, text: stringifyOutput(output) },
+ },
+ ],
+ rawOutput: output,
+ };
+}
diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.ts
index 033d50e7b..4fc3fca94 100644
--- a/packages/eve/src/cli/dev/tui/runner.ts
+++ b/packages/eve/src/cli/dev/tui/runner.ts
@@ -1573,6 +1573,16 @@ export class EveTUIRunner {
});
}
break;
+ // A task call's receipt never fails; its task's outcome does.
+ case "task.settled":
+ if (event.data.status === "failed") {
+ diagnostics.append({
+ source: "tool",
+ summary: `${this.#store.snapshot.conversation.tasks[event.data.taskId]?.name ?? "A task"} failed`,
+ detail: event.data.error?.message ?? "Task failed.",
+ });
+ }
+ break;
case "agent.started":
diagnostics.recordSubagentDispatch(event.data.callId);
break;
diff --git a/packages/eve/src/cli/dev/tui/transcript-parts.ts b/packages/eve/src/cli/dev/tui/transcript-parts.ts
index 39cd26f69..f63861c92 100644
--- a/packages/eve/src/cli/dev/tui/transcript-parts.ts
+++ b/packages/eve/src/cli/dev/tui/transcript-parts.ts
@@ -13,6 +13,7 @@ import type {
EveMessage,
EveMessagePart,
} from "#client/message-reducer-types.js";
+import { toolCallState } from "#client/tool-call-state.js";
import { stripTerminalControls } from "#cli/ui/terminal-text.js";
import type { Block, ToolStatus } from "./blocks.js";
import { formatTurnDuration } from "./stream-format.js";
@@ -155,47 +156,30 @@ export function nestedTaskRecord(
};
}
+/** The shared tool call state, in the transcript's vocabulary. */
export function toolState(
part: EveDynamicToolPart,
conversation: ConversationState,
working: boolean,
- taskWorking: boolean,
): ToolState {
- // A task call's receipt closes the tool part; the call runs until its task.settled, even after
- // its turn ends, as a root approval ends it.
- if (taskWorking) return { status: "running" };
- const state = settledToolState(part, conversation);
- return state.status === "running" && !working
- ? { status: "error", errorText: "interrupted" }
- : state;
-}
-
-function settledToolState(part: EveDynamicToolPart, conversation: ConversationState): ToolState {
- switch (part.state) {
- case "approval-requested": {
- const input = conversation.inputs[part.approval.id];
- if (input?.status !== "responded") return { status: "approval" };
- return input.response?.optionId === "approve"
- ? { status: "running" }
- : { status: "denied", errorText: "Denied by user." };
- }
- case "approval-responded":
- return part.approval.approved === false
- ? { status: "denied", errorText: part.approval.reason ?? "Denied by user." }
- : { status: "running" };
- case "output-available":
- return part.partial === true
+ const state = toolCallState(conversation, part.toolCallId, { streaming: working });
+ if (state === undefined) return { status: "running" };
+ switch (state.status) {
+ case "running":
+ return state.output === undefined
? { status: "running" }
- : { status: "done", output: part.output };
- case "output-error":
- return { status: "error", errorText: part.errorText };
- case "output-denied":
- return {
- status: "denied",
- errorText: part.approval.reason ?? "Tool execution was cancelled.",
- };
- default:
- return { status: "running" };
+ : { status: "running", output: state.output };
+ case "awaiting-input":
+ return { status: "approval" };
+ case "completed":
+ return { status: "done", output: state.output };
+ case "rejected":
+ return { status: "denied", errorText: state.errorText ?? "Denied by user." };
+ case "interrupted":
+ return { status: "error", errorText: "interrupted" };
+ case "cancelled":
+ case "failed":
+ return { status: "error", errorText: state.errorText };
}
}
diff --git a/packages/eve/src/cli/dev/tui/transcript.ts b/packages/eve/src/cli/dev/tui/transcript.ts
index d6bfa849a..3e8f135f9 100644
--- a/packages/eve/src/cli/dev/tui/transcript.ts
+++ b/packages/eve/src/cli/dev/tui/transcript.ts
@@ -183,9 +183,7 @@ export class ConversationTranscript {
!childToolIds.has(part.toolCallId) &&
!isPanelRoutedTool(part.toolName),
);
- const states = new Map(
- tools.map((part) => [part, toolState(part, conversation, working, false)]),
- );
+ const states = new Map(tools.map((part) => [part, toolState(part, conversation, working)]));
const activeSteps = activeToolSteps(states);
for (const [index, part] of message.parts.entries()) {
@@ -392,7 +390,7 @@ export class ConversationTranscript {
order += 1;
if (!isToolCallRow(part) || isTaskControlTool(part.toolName)) continue;
const childTask = childTasks.get(part.toolCallId);
- const state = toolState(part, child, running, childTask?.call.status === "working");
+ const state = toolState(part, child, running);
const id = `subagent:${record.callId}:tool:${part.toolCallId}`;
const block = this.#memoize(id, [part, state.status, record.name], () => {
const context = this.#presentationContext(part.toolCallId, part, state, options, {
diff --git a/packages/eve/src/client/conversation-projection.ts b/packages/eve/src/client/conversation-projection.ts
new file mode 100644
index 000000000..309bc9db3
--- /dev/null
+++ b/packages/eve/src/client/conversation-projection.ts
@@ -0,0 +1,19 @@
+import { initialSessionProjection, type SessionProjection } from "#protocol/session-projection.js";
+
+const projectionKey = Symbol("eve.conversationProjection");
+
+/** Keep event-contract details off the public state shape; reducers carry this hidden state forward. */
+export function conversationProjection(state: object): SessionProjection {
+ return (
+ (state as { [projectionKey]?: SessionProjection })[projectionKey] ?? initialSessionProjection()
+ );
+}
+
+export function withConversationProjection<T extends object>(
+ state: T,
+ projection: SessionProjection,
+): T {
+ if ((state as { [projectionKey]?: SessionProjection })[projectionKey] === projection)
+ return state;
+ return Object.defineProperty({ ...state }, projectionKey, { value: projection });
+}
diff --git a/packages/eve/src/client/conversation-reducer.test.ts b/packages/eve/src/client/conversation-reducer.test.ts
index a57ed83d1..fd763de05 100644
--- a/packages/eve/src/client/conversation-reducer.test.ts
+++ b/packages/eve/src/client/conversation-reducer.test.ts
@@ -174,13 +174,20 @@ describe("conversation reducer tasks and agent sessions", () => {
createTurnStartedEvent({ sequence: 0, turnId: "t1" }),
createTurnWaitingEvent({ on: "tasks", usage: TEST_USAGE, sequence: 0, turnId: "t1" }),
]);
- expect(parked.turns.t1).toEqual({ turnId: "t1", status: "active", waiting: true });
+ expect(parked.turns.t1).toEqual({
+ status: "active",
+ turnId: "t1",
+ waiting: true,
+ });
expect(parked.activeTurnId).toBe("t1");
const resumed = reduce(
[createStepStartedEvent({ modelId: "mock", sequence: 0, stepIndex: 1, turnId: "t1" })],
parked,
);
- expect(resumed.turns.t1).toEqual({ turnId: "t1", status: "active" });
+ expect(resumed.turns.t1).toEqual({
+ status: "active",
+ turnId: "t1",
+ });
const ended = reduce(
[
createTurnWaitingEvent({ on: "tasks", usage: TEST_USAGE, sequence: 0, turnId: "t1" }),
@@ -188,7 +195,10 @@ describe("conversation reducer tasks and agent sessions", () => {
],
resumed,
);
- expect(ended.turns.t1).toEqual({ turnId: "t1", status: "completed" });
+ expect(ended.turns.t1).toEqual({
+ status: "completed",
+ turnId: "t1",
+ });
expect(ended.activeTurnId).toBeUndefined();
});
});
diff --git a/packages/eve/src/client/conversation-reducer.ts b/packages/eve/src/client/conversation-reducer.ts
index da5bccef0..cf8e43878 100644
--- a/packages/eve/src/client/conversation-reducer.ts
+++ b/packages/eve/src/client/conversation-reducer.ts
@@ -1,14 +1,16 @@
+import {
+ conversationProjection,
+ withConversationProjection,
+} from "#client/conversation-projection.js";
import type {
AgentObservation,
ConversationAgentSession,
- ConversationInput,
ConversationState,
- ConversationTask,
- ConversationTurn,
} from "#client/conversation-state.js";
import { defaultMessageReducer } from "#client/message-reducer.js";
import type { EveAgentReducer, EveAgentReducerEvent } from "#client/reducer.js";
import type { MessageStreamEvent } from "#protocol/message.js";
+import { initialSessionProjection } from "#protocol/session-projection.js";
/**
* Transport facts about followed agent sessions. Only the canonical conversation receives them;
@@ -29,29 +31,10 @@ export type ConversationEvent = EveAgentReducerEvent | ClientAgentEvent;
type Mutable<T> = { -readonly [K in keyof T]: T[K] };
export function initialConversationState(): ConversationState {
- return { messages: [], turns: {}, inputs: {}, tasks: {}, agents: {} };
-}
-
-function updateTurn(
- state: ConversationState,
- turnId: string,
- update: (turn: ConversationTurn) => ConversationTurn,
-): ConversationState {
- const turn = state.turns[turnId];
- if (turn === undefined) return state;
- const next = update(turn);
- return next === turn ? state : { ...state, turns: { ...state.turns, [turnId]: next } };
-}
-
-function updateTask(
- state: ConversationState,
- taskId: string,
- update: (task: ConversationTask) => ConversationTask,
-): ConversationState {
- const task = state.tasks[taskId];
- if (task === undefined) return state;
- const next = update(task);
- return next === task ? state : { ...state, tasks: { ...state.tasks, [taskId]: next } };
+ return withConversationProjection(
+ { turns: {}, inputs: {}, tasks: {}, messages: [], agents: {} },
+ initialSessionProjection(),
+ );
}
function updateObservation(
@@ -70,90 +53,12 @@ function observedConversation(observation: AgentObservation): ConversationState
return observation.status === "not-followed" ? undefined : observation.conversation;
}
-/** Applies lifecycle identity and closure to an already projected message state. */
+/** Records the agent sessions the conversation's runs open, and the answers this client sent. */
function reduceConversationLifecycle(
state: ConversationState,
event: EveAgentReducerEvent,
): ConversationState {
switch (event.type) {
- case "turn.started":
- return {
- ...state,
- activeTurnId: event.data.turnId,
- turns: {
- ...state.turns,
- [event.data.turnId]: { turnId: event.data.turnId, status: "active" },
- },
- };
- case "turn.waiting":
- return updateTurn(state, event.data.turnId, (turn) =>
- turn.status === "active" && !turn.waiting ? { ...turn, waiting: true } : turn,
- );
- case "step.started":
- return updateTurn(state, event.data.turnId, (turn) =>
- turn.waiting ? { turnId: turn.turnId, status: turn.status } : turn,
- );
- case "turn.completed":
- case "turn.cancelled":
- case "turn.failed": {
- const { turnId } = event.data;
- return {
- ...state,
- activeTurnId: state.activeTurnId === turnId ? undefined : state.activeTurnId,
- turns: {
- ...state.turns,
- [turnId]: {
- turnId,
- status:
- event.type === "turn.completed"
- ? "completed"
- : event.type === "turn.failed"
- ? "failed"
- : "cancelled",
- },
- },
- };
- }
- // Only a turn's end reaches a session boundary, so no turn stays open across one.
- case "session.waiting":
- case "session.completed":
- case "session.failed":
- return state.activeTurnId === undefined ? state : { ...state, activeTurnId: undefined };
- case "task.started": {
- const { callId, kind, name, taskId, turnId } = event.data;
- const task = state.tasks[taskId] ?? { taskId, name, kind, calls: {} };
- if (task.calls[callId] !== undefined) return state;
- return {
- ...state,
- tasks: {
- ...state.tasks,
- [taskId]: {
- ...task,
- calls: { ...task.calls, [callId]: { callId, turnId, status: "working" } },
- },
- },
- };
- }
- case "task.settled": {
- const { callId, error, output, status, taskId } = event.data;
- return updateTask(state, taskId, (task) => {
- const call = task.calls[callId];
- if (call === undefined || call.status !== "working") return task;
- const settled = { callId, turnId: call.turnId, status };
- return {
- ...task,
- calls: {
- ...task.calls,
- [callId]:
- status === "completed" && output !== undefined
- ? { ...settled, output }
- : status === "failed" && error !== undefined
- ? { ...settled, error }
- : settled,
- },
- };
- });
- }
case "agent.started": {
const { callId, name, sessionId, taskId, turnId } = event.data;
if (state.agents[sessionId] !== undefined) return state;
@@ -165,23 +70,12 @@ function reduceConversationLifecycle(
observation: { status: "not-followed" },
};
if (taskId !== undefined) agent.taskId = taskId;
- return { ...state, agents: { ...state.agents, [sessionId]: agent } };
- }
- case "input.requested": {
- const inputs = { ...state.inputs };
- for (const request of event.data.requests) {
- if (inputs[request.requestId] !== undefined) continue;
- const input: Mutable<ConversationInput> = {
- request,
- turnId: event.data.turnId,
- stepIndex: event.data.stepIndex,
- status: "open",
- };
- if (event.data.taskId !== undefined) input.taskId = event.data.taskId;
- inputs[request.requestId] = input;
- }
- return { ...state, inputs };
+ return withConversationProjection(
+ { ...state, agents: { ...state.agents, [sessionId]: agent } },
+ conversationProjection(state),
+ );
}
+ // An answer this client sent shows as responded until the stream settles it.
case "client.input.responded": {
const inputs = { ...state.inputs };
for (const response of event.data.responses) {
@@ -189,44 +83,17 @@ function reduceConversationLifecycle(
if (current?.status !== "open") continue;
inputs[response.requestId] = { ...current, response, status: "responded" };
}
- return { ...state, inputs };
- }
- case "approval.candidate": {
- const current = state.inputs[event.data.requestId];
- if (current === undefined || current.status === "settled") return state;
- if (event.data.outcome === "pending") return state;
- return {
- ...state,
- inputs: {
- ...state.inputs,
- [event.data.requestId]: { ...current, status: "open", response: undefined },
- },
- };
- }
- case "approval.settled": {
- const current = state.inputs[event.data.requestId];
- if (current === undefined || current.status === "settled") return state;
- return {
- ...state,
- inputs: {
- ...state.inputs,
- [event.data.requestId]: { ...current, status: "settled", outcome: event.data.outcome },
- },
- };
- }
- case "input.resolved": {
- const inputs = { ...state.inputs };
- for (const resolution of event.data.resolutions) {
- const current = inputs[resolution.requestId];
- if (current === undefined || current.status === "settled") continue;
- inputs[resolution.requestId] = {
- ...current,
- status: "settled",
- outcome: resolution.outcome,
- response: resolution.response ?? current.response,
- };
+ const projection = conversationProjection(state);
+ const projectedInputs = { ...projection.inputs };
+ for (const response of event.data.responses) {
+ const current = projectedInputs[response.requestId];
+ if (current?.status === "open")
+ projectedInputs[response.requestId] = { ...current, response, status: "responded" };
}
- return { ...state, inputs };
+ return withConversationProjection(
+ { ...state, inputs },
+ { ...projection, inputs: projectedInputs },
+ );
}
default:
return state;
@@ -239,6 +106,16 @@ const messageReducer = defaultMessageReducer();
export function reduceConversation(
state: ConversationState,
event: ConversationEvent,
+): ConversationState {
+ const next = reduceConversationEvent(state, event);
+ return event.type.startsWith("client.agent.")
+ ? withConversationProjection(next, conversationProjection(state))
+ : next;
+}
+
+function reduceConversationEvent(
+ state: ConversationState,
+ event: ConversationEvent,
): ConversationState {
switch (event.type) {
case "client.agent.following":
@@ -272,10 +149,36 @@ export function reduceConversation(
? { status: "unavailable" }
: { status: "unavailable", conversation };
});
- default: {
- const projected = messageReducer.reduce(state, event);
- return reduceConversationLifecycle({ ...state, ...projected }, event);
- }
+ default:
+ const messages = messageReducer.reduce(state, event);
+ const projection = conversationProjection(messages);
+ const { activeTurnId: _activeTurnId, ...rest } = state;
+ const { activeTurnId: _messageTurnId, ...messageData } = messages as ConversationState;
+ const conversation: Mutable<ConversationState> = {
+ ...rest,
+ ...messageData,
+ turns: Object.fromEntries(
+ Object.entries(projection.turns).map(([id, turn]) => {
+ const { turnId, status, waiting } = turn;
+ const publicTurn: Mutable<ConversationState["turns"][string]> = { turnId, status };
+ if (waiting !== undefined) publicTurn.waiting = waiting;
+ return [id, publicTurn];
+ }),
+ ),
+ inputs: Object.fromEntries(
+ Object.entries(projection.inputs).map(([id, input]) => {
+ const { sequence: _sequence, callId: _callId, ...publicInput } = input;
+ return [id, publicInput];
+ }),
+ ),
+ tasks: projection.tasks,
+ };
+ if (projection.activeTurnId !== undefined)
+ conversation.activeTurnId = projection.activeTurnId;
+ return reduceConversationLifecycle(
+ withConversationProjection(conversation, projection),
+ event,
+ );
}
}
diff --git a/packages/eve/src/client/conversation-state.ts b/packages/eve/src/client/conversation-state.ts
index 05df8babe..95e7802dc 100644
--- a/packages/eve/src/client/conversation-state.ts
+++ b/packages/eve/src/client/conversation-state.ts
@@ -1,6 +1,13 @@
+import { conversationProjection } from "#client/conversation-projection.js";
import type { EveAuthorizationPart, EveMessageData } from "#client/message-reducer-types.js";
import type { InputRequest, InputResponse } from "#shared/input.js";
-import type { JsonValue } from "#shared/json.js";
+import {
+ type ConversationTask,
+ type ConversationTaskCall,
+ openSignIns,
+} from "#protocol/session-projection.js";
+
+export type { ConversationTask, ConversationTaskCall };
export interface ConversationTurn {
readonly turnId: string;
@@ -20,30 +27,6 @@ export interface ConversationInput {
readonly outcome?: string;
}
-/** One call that started or reached a task, settled by its `task.settled`. */
-export interface ConversationTaskCall {
- readonly callId: string;
- readonly turnId: string;
- readonly status: "working" | "completed" | "failed" | "cancelled";
- /** The call's result; present only when `status` is `"completed"`. */
- readonly output?: JsonValue;
- /** Why the call failed; present only when `status` is `"failed"`. */
- readonly error?: { readonly message: string };
-}
-
-export interface ConversationTask {
- readonly taskId: string;
- /** The tool whose call started the task. */
- readonly name: string;
- /**
- * `"agent"` when a subagent's tool, local or remote, started the task; `"tool"` for an authored
- * tool, including one that opens sessions with `ctx.agent`.
- */
- readonly kind: "agent" | "tool";
- /** Calls in the order they started or reached the task. */
- readonly calls: Readonly<Record<string, ConversationTaskCall>>;
-}
-
export type AgentObservation =
| { readonly status: "not-followed" }
| { readonly status: "following"; readonly conversation: ConversationState }
@@ -67,7 +50,9 @@ export interface ConversationAgentSession {
readonly observation: AgentObservation;
}
-/** Renderable conversation state. Root and agent-session input IDs occupy separate scopes. */
+/**
+ * Renderable conversation state. Root and agent-session input IDs occupy separate scopes.
+ */
export interface ConversationState extends EveMessageData {
readonly activeTurnId?: string;
readonly turns: Readonly<Record<string, ConversationTurn>>;
@@ -95,8 +80,8 @@ export function conversationAuthorizations(
/** A sign-in the session still waits on, which resumes its work when the callback arrives. */
export function hasPendingAuthorizations(state: ConversationState): boolean {
- return conversationAuthorizations(state).some(
- (part) => part.state === "required" && part.awaitsCallback === true,
+ return openSignIns(conversationProjection(state)).some(
+ (attempt) => attempt.awaitsCallback === true,
);
}
diff --git a/packages/eve/src/client/eve-agent-store.test.ts b/packages/eve/src/client/eve-agent-store.test.ts
index 79e81036c..0bbbafb76 100644
--- a/packages/eve/src/client/eve-agent-store.test.ts
+++ b/packages/eve/src/client/eve-agent-store.test.ts
@@ -270,7 +270,7 @@ describe("EveAgentStore lifecycle", () => {
await Promise.resolve();
expect(store.snapshot.status).toBe("submitted");
- expect(store.snapshot.data).toEqual({
+ expect(store.snapshot.data).toMatchObject({
messages: [
{
id: expect.stringMatching(/^optimistic:/),
@@ -286,7 +286,7 @@ describe("EveAgentStore lifecycle", () => {
expect(seenEvents).toEqual(events);
expect(store.snapshot.status).toBe("ready");
- expect(store.snapshot.data).toEqual({
+ expect(store.snapshot.data).toMatchObject({
messages: [
{
id: expect.stringMatching(/^evt_.+:user$/),
@@ -456,7 +456,7 @@ describe("EveAgentStore held turns", () => {
taskId: "task_1",
turnId: "turn_1",
}),
- createTurnWaitingEvent({ on: "input", usage: TEST_USAGE, sequence: 0, turnId: "turn_1" }),
+ createTurnWaitingEvent({ on: "tasks", usage: TEST_USAGE, sequence: 0, turnId: "turn_1" }),
]).map((event) => ({ ...event, meta: { ...event.meta, deliveryIds: ["delivery_1"] } }));
for (const event of parked) live.emit(event);
await sending;
@@ -1562,9 +1562,9 @@ describe("EveAgentStore session resume", () => {
it("publishes a hydrated terminal failure with error status", async () => {
const failed = stampTestEvents([
createSessionFailedEvent({
- usage: TEST_USAGE,
code: "SESSION_FAILED",
message: "Session failed.",
+ usage: TEST_USAGE,
sessionId: "session_1",
}),
])[0]!;
@@ -2344,7 +2344,7 @@ describe("EveAgentStore steering", () => {
}));
const fetchMock = vi
.spyOn(globalThis, "fetch")
- .mockResolvedValueOnce(startedResponse())
+ .mockResolvedValueOnce(startedResponse("first-delivery"))
.mockResolvedValueOnce(activeStream.response)
.mockResolvedValueOnce(startedResponse());
const store = createStore({ reducer: defaultMessageReducer() });
@@ -2402,9 +2402,9 @@ describe("EveAgentStore terminal failure", () => {
it("publishes a live terminal failure with error status", async () => {
const failed = stampTestEvents([
createSessionFailedEvent({
- usage: TEST_USAGE,
code: "SESSION_FAILED",
message: "Session failed.",
+ usage: TEST_USAGE,
sessionId: "session_1",
}),
])[0]!;
diff --git a/packages/eve/src/client/index.ts b/packages/eve/src/client/index.ts
index 9449ab054..cc2ab555a 100644
--- a/packages/eve/src/client/index.ts
+++ b/packages/eve/src/client/index.ts
@@ -10,6 +10,8 @@ export { ClientError } from "#client/client-error.js";
export { defaultMessageReducer } from "#client/message-reducer.js";
export { conversationReducer } from "#client/conversation-reducer.js";
export { openConversationInputs } from "#client/conversation-state.js";
+export { toolCallState, type ToolCallState, type ToolCallStatus } from "#client/tool-call-state.js";
+
export type {
AgentObservation,
ConversationAgentSession,
diff --git a/packages/eve/src/client/message-action-parts.ts b/packages/eve/src/client/message-action-parts.ts
index e0d8b119d..8b4484f5b 100644
--- a/packages/eve/src/client/message-action-parts.ts
+++ b/packages/eve/src/client/message-action-parts.ts
@@ -2,7 +2,6 @@ import { actionRequestName } from "#shared/action-request-name.js";
import type { RuntimeActionRequest, RuntimeActionResult } from "#shared/action-types.js";
import type { InputRequest } from "#shared/input.js";
import type {
- EveDynamicToolPart,
EveMessageInputRequest,
EveMessageToolMetadata,
} from "#client/message-reducer-types.js";
@@ -70,29 +69,6 @@ export function mergeToolMetadata(
};
}
-/**
- * Derives the approved-approval descriptor a resolved tool result carries
- * forward, or `undefined` when the tool part never had an approval.
- */
-export function approvedApproval(part: EveDynamicToolPart | undefined):
- | {
- readonly id: string;
- readonly approved: true;
- readonly reason?: string;
- readonly isAutomatic?: boolean;
- }
- | undefined {
- if (!part?.approval?.id) {
- return undefined;
- }
- return {
- approved: true,
- id: part.approval.id,
- isAutomatic: part.approval.isAutomatic,
- reason: part.approval.reason,
- };
-}
-
/** Maps a runtime action request onto its normalized tool descriptor. */
export function normalizeActionRequest(action: RuntimeActionRequest): ActionDescriptor {
const name = actionRequestName(action);
diff --git a/packages/eve/src/client/message-reducer.test.ts b/packages/eve/src/client/message-reducer.test.ts
index bf5d7634f..942cf9c6c 100644
--- a/packages/eve/src/client/message-reducer.test.ts
+++ b/packages/eve/src/client/message-reducer.test.ts
@@ -27,6 +27,7 @@ import {
type TaskSettledStreamEvent,
type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
+import { createTaskStartedEvent } from "#protocol/message.js";
function reduceServerEvents(
reducer: ReturnType<typeof defaultMessageReducer>,
@@ -1653,61 +1654,89 @@ describe("defaultMessageReducer", () => {
});
describe("task tool parts", () => {
- // Built without `name` and `kind`, as events recorded by older eve versions are.
- function settleResearchTask(settled: TaskSettledStreamEvent["data"]) {
+ const requested = createActionsRequestedEvent({
+ actions: [
+ {
+ callId: "call_1",
+ input: { topic: "Alice's notes" },
+ kind: "tool-call",
+ toolName: "research",
+ },
+ ],
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_1",
+ });
+ const started = createTaskStartedEvent({
+ callId: "call_1",
+ kind: "tool",
+ name: "research",
+ taskId: "task_1",
+ turnId: "turn_1",
+ });
+ const receipt = createActionResultEvent({
+ result: {
+ callId: "call_1",
+ kind: "tool-result",
+ output: "Started task task_1.",
+ toolName: "research",
+ },
+ sequence: 1,
+ stepIndex: 0,
+ turnId: "turn_1",
+ });
+ const turnCompleted = createTurnCompletedEvent({ sequence: 2, turnId: "turn_1" });
+ const settled = (
+ outcome: Omit<TaskSettledStreamEvent["data"], "callId" | "taskId" | "turnId">,
+ ) =>
+ createTaskSettledEvent({ callId: "call_1", taskId: "task_1", turnId: "turn_1", ...outcome });
+
+ function reduceResearchTask(events: readonly UnstampedMessageStreamEvent[]) {
const reducer = defaultMessageReducer();
- const data = reduceServerEvents(reducer, reducer.initial(), [
- createActionResultEvent({
- result: {
- callId: "call_1",
- kind: "tool-result",
- output: "Started task task_1.",
- toolName: "research",
- },
- sequence: 0,
- stepIndex: 0,
- turnId: "turn_1",
- }),
- createTurnCompletedEvent({ sequence: 0, turnId: "turn_1" }),
- { data: settled, type: "task.settled" },
- ]);
- const [message] = data.messages;
+ const [message] = reduceServerEvents(reducer, reducer.initial(), events).messages;
return { status: message?.metadata?.status, toolPart: message?.parts[1] };
}
- it("replaces the receipt with the output of a completed task", () => {
- expect(
- settleResearchTask({
- callId: "call_1",
- output: { summary: "done" },
- status: "completed",
- taskId: "task_1",
- turnId: "turn_1",
- }),
- ).toMatchObject({
+ it("keeps a task call running past its receipt and its turn until the task settles", () => {
+ expect(reduceResearchTask([requested, started, receipt, turnCompleted])).toMatchObject({
status: "complete",
- toolPart: { output: { summary: "done" }, state: "output-available" },
+ toolPart: { state: "input-available" },
});
});
+ it("replaces the running part with the output of a completed task", () => {
+ expect(
+ reduceResearchTask([
+ requested,
+ started,
+ receipt,
+ turnCompleted,
+ settled({ output: { summary: "done" }, status: "completed" }),
+ ]).toolPart,
+ ).toMatchObject({ output: { summary: "done" }, state: "output-available" });
+ });
+
it("shows a failed or cancelled task as a tool error", () => {
+ const settledAfter = (outcome: Parameters<typeof settled>[0]) =>
+ reduceResearchTask([requested, started, receipt, turnCompleted, settled(outcome)]).toolPart;
expect(
- settleResearchTask({
- callId: "call_1",
- error: { message: "Remote agent unavailable." },
- status: "failed",
- taskId: "task_1",
- turnId: "turn_1",
- }).toolPart,
+ settledAfter({ error: { message: "Remote agent unavailable." }, status: "failed" }),
).toMatchObject({ errorText: "Remote agent unavailable.", state: "output-error" });
- expect(
- settleResearchTask({
- callId: "call_1",
- status: "cancelled",
- taskId: "task_1",
- turnId: "turn_1",
- }).toolPart,
- ).toMatchObject({ errorText: "Task was cancelled.", state: "output-error" });
+ expect(settledAfter({ status: "cancelled" })).toMatchObject({
+ errorText: "Task was cancelled.",
+ state: "output-error",
+ });
+ });
+
+ it("keeps a task's outcome when its receipt arrives after the task settled", () => {
+ const failed = settled({
+ error: { message: "Alice's notes are unavailable." },
+ status: "failed",
+ });
+ expect(reduceResearchTask([requested, started, failed, receipt]).toolPart).toMatchObject({
+ errorText: "Alice's notes are unavailable.",
+ state: "output-error",
+ });
});
});
diff --git a/packages/eve/src/client/message-reducer.ts b/packages/eve/src/client/message-reducer.ts
index c40d432d6..2dd242c1b 100644
--- a/packages/eve/src/client/message-reducer.ts
+++ b/packages/eve/src/client/message-reducer.ts
@@ -1,3 +1,7 @@
+import {
+ conversationProjection,
+ withConversationProjection,
+} from "#client/conversation-projection.js";
import type { EveAgentReducer, EveAgentReducerEvent } from "#client/reducer.js";
import {
createAuthorizationCompletedPart,
@@ -11,7 +15,6 @@ import type {
EveMessagePart,
} from "#client/message-reducer-types.js";
import {
- approvedApproval,
createToolMetadata,
mergeToolMetadata,
normalizeActionRequest,
@@ -26,9 +29,9 @@ import {
upsertMessage,
} from "#client/message-reducer-primitives.js";
import { messageRun } from "#client/message-run-parts.js";
-import { createSettledTaskPart } from "#client/message-task-parts.js";
-import type { InputResponse } from "#shared/input.js";
-import type { AuthorizationCompletedStreamEvent, InputResolution } from "#protocol/message.js";
+import type { AuthorizationCompletedStreamEvent } from "#protocol/message.js";
+import { foldSession, initialSessionProjection } from "#protocol/session-projection.js";
+import { toolPartState } from "#client/tool-part-state.js";
export type {
EveAuthorizationChallenge,
@@ -57,12 +60,14 @@ function receivedMessageEventId(event: MessageReceivedEvent): string {
* The returned projection keeps eve-owned types while following the AI SDK
* `messages[].parts[]` rendering convention used by AI Elements. It projects
* text, reasoning, tool calls, tool results, tool approvals, submitted HITL
- * responses, and authorization prompts.
+ * responses, and authorization prompts. A tool part's `state` comes from the
+ * session projection the data carries, the same lifecycle every eve reader
+ * folds; its events supply only the part's content.
*/
export function defaultMessageReducer(): EveAgentReducer<EveMessageData> {
return {
initial() {
- return { messages: [] };
+ return withConversationProjection({ messages: [] }, initialSessionProjection());
},
reduce(data, event) {
return reduceMessageData(data, event);
@@ -71,6 +76,17 @@ export function defaultMessageReducer(): EveAgentReducer<EveMessageData> {
}
function reduceMessageData(data: EveMessageData, event: EveAgentReducerEvent): EveMessageData {
+ const projection = foldSession(conversationProjection(data), event);
+ const content = withConversationProjection(reduceContent(data, event), projection);
+ const callIds = toolCallIds(content, event);
+ return withConversationProjection(
+ callIds.length === 0 ? content : withToolPartStates(content, callIds),
+ projection,
+ );
+}
+
+/** What an event says about the conversation's messages and parts. */
+function reduceContent(data: EveMessageData, event: EveAgentReducerEvent): EveMessageData {
switch (event.type) {
case "client.message.submitted":
case "client.message.failed":
@@ -88,14 +104,6 @@ function reduceMessageData(data: EveMessageData, event: EveAgentReducerEvent): E
event.data.turnId,
);
- case "input.resolved": {
- let next = data;
- for (const resolution of event.data.resolutions) {
- next = resolveInputRequest(next, resolution);
- }
- return next;
- }
-
case "message.received":
return upsertMessage(
data,
@@ -152,28 +160,21 @@ function reduceMessageData(data: EveMessageData, event: EveAgentReducerEvent): E
case "action.input.appended": {
const existing = findToolPart(data, event.data.callId);
if (existing !== undefined && existing.state !== "input-streaming") return data;
-
const inputText =
(existing?.state === "input-streaming" ? existing.inputText : "") +
event.data.inputTextDelta;
-
- const nextPart: EveDynamicToolPart = {
+ return upsertToolPart(data, event.data.turnId, event.data.stepIndex, {
input: undefined,
inputText,
state: "input-streaming",
stepIndex: event.data.stepIndex,
toolCallId: event.data.callId,
toolMetadata: existing?.toolMetadata ?? {
- eve: {
- kind: "unknown",
- name: event.data.toolName,
- },
+ eve: { kind: "unknown", name: event.data.toolName },
},
toolName: event.data.toolName,
type: "dynamic-tool",
- };
-
- return upsertToolPart(data, event.data.turnId, event.data.stepIndex, nextPart);
+ });
}
case "actions.requested": {
@@ -204,136 +205,106 @@ function reduceMessageData(data: EveMessageData, event: EveAgentReducerEvent): E
if (
existing?.approval?.id === request.requestId ||
(existing !== undefined && isSettledToolPart(existing))
- )
+ ) {
continue;
+ }
const descriptor = normalizeActionRequest(request.action);
next = updateAssistantMessage(next, event.data.turnId, (message) =>
upsertPart(ensureStepStartPart(message, event.data.stepIndex), {
- approval: {
- id: request.requestId,
- },
+ ...existing,
+ approval: { id: request.requestId },
input: request.action.input,
state: "approval-requested",
- stepIndex: event.data.stepIndex,
+ stepIndex: existing?.stepIndex ?? event.data.stepIndex,
toolCallId: request.action.callId,
toolMetadata: createToolMetadata(descriptor, {
inputRequest: toMessageInputRequest(request),
}),
toolName: descriptor.toolName,
type: "dynamic-tool",
- }),
+ } as EveDynamicToolPart),
);
}
return next;
}
- case "approval.candidate":
- // Candidate progress is responder-specific. Applications can consume the
- // raw stream event for private UI without changing the shared tool part.
- return data;
-
- case "approval.settled": {
- const existing = findToolPartByApprovalId(data, event.data.requestId);
- if (existing === undefined) return data;
- if (event.data.outcome === "approved") {
- const approval = { approved: true as const, id: event.data.requestId, reason: undefined };
- return updateToolPart(
- data,
- existing.toolCallId,
- existing.state === "output-available"
- ? { ...existing, approval }
- : { ...toolPartIdentity(existing), approval, state: "approval-responded" },
- );
- }
- if (existing.state === "output-available") return data;
- return updateToolPart(data, existing.toolCallId, {
- ...toolPartIdentity(existing),
- approval: {
- approved: false,
- id: event.data.requestId,
- reason: "Tool execution was cancelled.",
- },
- state: "output-denied",
- });
- }
-
case "action.result": {
- const descriptor = normalizeActionResult(event.data.result);
+ // A task call's result is only its start receipt, which can arrive after the task settled.
+ if (conversationProjection(data).calls[event.data.result.callId]?.taskId !== undefined)
+ return data;
const existing = findToolPart(data, event.data.result.callId);
- const denied =
- event.data.status === "rejected" || event.data.error?.code === "TOOL_EXECUTION_DENIED";
- const failed = event.data.status === "failed" && !denied;
- const approvalId = existing?.approval?.id ?? event.data.result.callId;
- const toolMetadata = mergeToolMetadata(
- existing?.toolMetadata,
- createToolMetadata(descriptor),
- );
- const resultPartBase = {
+ const descriptor = normalizeActionResult(event.data.result);
+ const succeeded =
+ event.data.status === undefined || event.data.status === "completed"
+ ? event.data.result.isError !== true && event.data.error === undefined
+ : false;
+ const part = {
+ ...existing,
input: existing?.input,
- stepIndex: event.data.stepIndex,
+ stepIndex: existing?.stepIndex ?? event.data.stepIndex,
toolCallId: event.data.result.callId,
- toolMetadata,
+ toolMetadata: mergeToolMetadata(existing?.toolMetadata, createToolMetadata(descriptor)),
toolName: existing?.toolName ?? descriptor.toolName,
type: "dynamic-tool" as const,
};
-
- let nextPart: EveDynamicToolPart;
- if (denied) {
- nextPart = {
- ...resultPartBase,
- approval: {
- approved: false,
- id: approvalId,
- reason: event.data.error?.message,
- },
- state: "output-denied",
- };
- } else if (failed) {
- nextPart = {
- ...resultPartBase,
- approval: approvedApproval(existing),
- errorText: event.data.error?.message ?? stringifyUnknown(event.data.result.output),
- state: "output-error",
- };
- } else {
- nextPart = {
- ...resultPartBase,
- approval: approvedApproval(existing),
- output: event.data.result.output,
- state: "output-available",
- };
- }
-
- return upsertToolPart(data, event.data.turnId, event.data.stepIndex, nextPart);
+ const outcome = succeeded
+ ? { errorText: undefined, output: event.data.result.output }
+ : {
+ errorText: event.data.error?.message ?? stringifyUnknown(event.data.result.output),
+ output: undefined,
+ };
+ return upsertToolPart(data, event.data.turnId, event.data.stepIndex, {
+ ...part,
+ ...outcome,
+ partial: undefined,
+ } as EveDynamicToolPart);
}
case "action.partial": {
const existing = findToolPart(data, event.data.result.callId);
- if (existing !== undefined && isSettledToolPart(existing)) {
- return data;
- }
-
+ if (existing !== undefined && isSettledToolPart(existing)) return data;
const descriptor = normalizeActionResult(event.data.result);
- const nextPart: EveDynamicToolPart = {
- approval: approvedApproval(existing),
+ return upsertToolPart(data, event.data.turnId, event.data.stepIndex, {
+ ...existing,
input: existing?.input,
output: event.data.result.output,
partial: true,
state: "output-available",
- stepIndex: event.data.stepIndex,
+ stepIndex: existing?.stepIndex ?? event.data.stepIndex,
toolCallId: event.data.result.callId,
toolMetadata: mergeToolMetadata(existing?.toolMetadata, createToolMetadata(descriptor)),
toolName: existing?.toolName ?? descriptor.toolName,
type: "dynamic-tool",
- };
+ } as EveDynamicToolPart);
+ }
- return upsertToolPart(data, event.data.turnId, event.data.stepIndex, nextPart);
+ case "input.resolved": {
+ let next = data;
+ for (const { requestId, response } of event.data.resolutions) {
+ const existing =
+ response === undefined ? undefined : findToolPartByApprovalId(next, requestId);
+ if (existing === undefined) continue;
+ next = replaceToolPart(next, {
+ ...existing,
+ toolMetadata: mergeToolMetadata(existing.toolMetadata, {
+ eve: {
+ inputResponse: response,
+ kind: existing.toolMetadata?.eve?.kind ?? "unknown",
+ name: existing.toolMetadata?.eve?.name ?? existing.toolName,
+ },
+ }),
+ });
+ }
+ return next;
}
+ // A task's outcome is its call's: the call's `action.result` was only the start receipt.
case "task.settled": {
const existing = findToolPart(data, event.data.callId);
if (existing === undefined) return data;
- return replaceToolPart(data, createSettledTaskPart(existing, event));
+ const { error, output, status } = event.data;
+ const outcome = status === "completed" ? { output } : { errorText: error?.message };
+ return replaceToolPart(data, { ...existing, ...outcome } as EveDynamicToolPart);
}
case "authorization.required":
@@ -376,26 +347,19 @@ function reduceMessageData(data: EveMessageData, event: EveAgentReducerEvent): E
}));
case "turn.completed":
- return updateAssistantMessage(data, event.data.turnId, (message) => ({
- ...message,
- metadata: { ...message.metadata, status: "complete" },
- parts: removeStreamingToolParts(closeStreamingRuns(message.parts)),
- }));
-
case "turn.cancelled":
- // Finalize whatever the cancelled turn streamed: no message.completed
- // or reasoning.completed will follow a partial append.
- return updateAssistantMessage(data, event.data.turnId, (message) => ({
- ...message,
- metadata: { ...message.metadata, status: "complete" },
- parts: removeStreamingToolParts(closeStreamingRuns(message.parts)),
- }));
-
case "turn.failed": {
- const existing = data.messages.find(
- (message) => message.role === "assistant" && message.metadata?.turnId === event.data.turnId,
- );
- if (existing === undefined) return data;
+ // A failed turn that streamed nothing has no message to finalize. Otherwise finalize what
+ // the turn streamed: no completion follows a partial append.
+ if (
+ event.type === "turn.failed" &&
+ !data.messages.some(
+ (message) =>
+ message.role === "assistant" && message.metadata?.turnId === event.data.turnId,
+ )
+ ) {
+ return data;
+ }
return updateAssistantMessage(data, event.data.turnId, (message) => ({
...message,
metadata: { ...message.metadata, status: "complete" },
@@ -403,14 +367,51 @@ function reduceMessageData(data: EveMessageData, event: EveAgentReducerEvent): E
}));
}
- case "session.failed":
+ default:
return data;
+ }
+}
+/** The tool calls whose state the event may have changed. */
+function toolCallIds(data: EveMessageData, event: EveAgentReducerEvent): readonly string[] {
+ const byRequest = (requestId: string) =>
+ findToolPartByApprovalId(data, requestId)?.toolCallId ?? [];
+ switch (event.type) {
+ case "actions.requested":
+ return event.data.actions.map((action) => action.callId);
+ case "input.requested":
+ return event.data.requests.map((request) => request.action.callId);
+ case "action.result":
+ case "action.partial":
+ return [event.data.result.callId];
+ case "task.started":
+ case "task.settled":
+ return [event.data.callId];
+ case "input.resolved":
+ return event.data.resolutions.flatMap((resolution) => byRequest(resolution.requestId));
+ case "approval.settled":
+ return [byRequest(event.data.requestId)].flat();
default:
- return data;
+ return [];
}
}
+function withToolPartStates(data: EveMessageData, callIds: readonly string[]): EveMessageData {
+ let next = data;
+ for (const callId of new Set(callIds)) {
+ const part = findToolPart(next, callId);
+ if (part === undefined) continue;
+ const derived = toolPartState(next, part);
+ if (derived !== part) {
+ next = withConversationProjection(
+ replaceToolPart(next, derived),
+ conversationProjection(data),
+ );
+ }
+ }
+ return next;
+}
+
function closeStreamingRuns(
parts: readonly EveMessagePart[],
stepIndex?: number,
@@ -428,61 +429,6 @@ function removeStreamingToolParts(parts: readonly EveMessagePart[]): readonly Ev
return parts.filter((part) => part.type !== "dynamic-tool" || part.state !== "input-streaming");
}
-function respondToInputRequest(data: EveMessageData, response: InputResponse): EveMessageData {
- const existing = findToolPartByApprovalId(data, response.requestId);
- if (!existing) return data;
-
- const approval: { id: string; reason?: string } = {
- id: response.requestId,
- };
- if (response.text !== undefined) {
- approval.reason = response.text;
- }
-
- const toolMetadata = mergeToolMetadata(existing.toolMetadata, {
- eve: {
- inputResponse: response,
- kind: existing.toolMetadata?.eve?.kind ?? "unknown",
- name: existing.toolMetadata?.eve?.name ?? existing.toolName,
- },
- });
- return updateToolPart(
- data,
- existing.toolCallId,
- existing.state === "output-available"
- ? { ...existing, approval: { ...approval, approved: true }, toolMetadata }
- : { ...toolPartIdentity(existing), approval, state: "approval-responded", toolMetadata },
- );
-}
-
-function resolveInputRequest(data: EveMessageData, resolution: InputResolution): EveMessageData {
- if (resolution.response !== undefined) {
- // A batch's resolution repeats answers that `approval.settled` already decided.
- const decided = findToolPartByApprovalId(data, resolution.requestId)?.approval?.approved;
- return decided === undefined ? respondToInputRequest(data, resolution.response) : data;
- }
-
- const existing = findToolPartByApprovalId(data, resolution.requestId);
- if (!existing) return data;
-
- return updateToolPart(data, existing.toolCallId, {
- ...toolPartIdentity(existing),
- output: { status: resolution.outcome },
- state: "output-available",
- });
-}
-
-function toolPartIdentity(part: EveDynamicToolPart) {
- return {
- input: part.input,
- stepIndex: part.stepIndex,
- toolCallId: part.toolCallId,
- toolMetadata: part.toolMetadata,
- toolName: part.toolName,
- type: part.type,
- };
-}
-
function updateAssistantMessage(
data: EveMessageData,
turnId: string,
diff --git a/packages/eve/src/client/message-task-parts.ts b/packages/eve/src/client/message-task-parts.ts
deleted file mode 100644
index 82f7f1fd0..000000000
--- a/packages/eve/src/client/message-task-parts.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import type { TaskSettledStreamEvent } from "#protocol/message.js";
-import type { EveDynamicToolPart } from "#client/message-reducer-types.js";
-import { approvedApproval } from "#client/message-action-parts.js";
-
-/**
- * Settles a task call's tool part, whose `action.result` was only the start
- * receipt. A cancelled task already ran, so it settles as an error rather than
- * `output-denied`, which marks calls that never ran.
- */
-export function createSettledTaskPart(
- existing: EveDynamicToolPart,
- event: TaskSettledStreamEvent,
-): EveDynamicToolPart {
- const settledPartBase = {
- approval: approvedApproval(existing),
- input: existing.input,
- stepIndex: existing.stepIndex,
- toolCallId: existing.toolCallId,
- toolMetadata: existing.toolMetadata,
- toolName: existing.toolName,
- type: "dynamic-tool" as const,
- };
-
- switch (event.data.status) {
- case "completed":
- return { ...settledPartBase, output: event.data.output, state: "output-available" };
- case "failed":
- return {
- ...settledPartBase,
- errorText: event.data.error?.message ?? "Task failed.",
- state: "output-error",
- };
- case "cancelled":
- return { ...settledPartBase, errorText: "Task was cancelled.", state: "output-error" };
- }
-}
diff --git a/packages/eve/src/client/session-utils.ts b/packages/eve/src/client/session-utils.ts
index a78f8773d..50b974e9a 100644
--- a/packages/eve/src/client/session-utils.ts
+++ b/packages/eve/src/client/session-utils.ts
@@ -5,6 +5,12 @@ import type {
UnstampedMessageStreamEvent,
} from "#protocol/message.js";
import { isCurrentTurnBoundaryEvent, isTurnFailureEvent } from "#protocol/message.js";
+import {
+ foldSession,
+ initialSessionProjection,
+ openInputs,
+ openSignIns,
+} from "#protocol/session-projection.js";
import type { InputRequest } from "#shared/input.js";
/** A connection authorization challenge that remains unresolved at a turn boundary. */
@@ -94,50 +100,35 @@ export function endsTurnSegment(
/** The requests and sign-ins one segment of a session's events leaves open. */
export class TurnSegment {
+ #projection = initialSessionProjection();
readonly #authorizations = new Map<string, PendingAuthorization>();
readonly #followCallbacks: boolean;
- readonly #requests = new Map<string, InputRequest>();
constructor(options: { readonly followCallbacks?: boolean } = {}) {
this.#followCallbacks = options.followCallbacks === true;
}
get inputRequests(): readonly InputRequest[] {
- return [...this.#requests.values()];
+ return openInputs(this.#projection).map((input) => input.request);
}
get pendingAuthorizations(): readonly PendingAuthorization[] {
- return [...this.#authorizations.values()];
+ return openSignIns(this.#projection).flatMap(
+ (attempt) => this.#authorizations.get(attempt.attemptId) ?? [],
+ );
}
/** Records `event` and returns true when it ends the segment. */
observe(event: UnstampedMessageStreamEvent): boolean {
- switch (event.type) {
- case "input.requested":
- for (const request of event.data.requests) this.#requests.set(request.requestId, request);
- break;
- case "approval.settled":
- this.#requests.delete(event.data.requestId);
- break;
- case "input.resolved":
- for (const resolution of event.data.resolutions) {
- this.#requests.delete(resolution.requestId);
- }
- break;
- case "authorization.required":
- this.#authorizations.set(authorizationKey(event.data), event.data);
- break;
- case "authorization.completed":
- this.#authorizations.delete(authorizationKey(event.data));
- break;
+ this.#projection = foldSession(this.#projection, event);
+ if (event.type === "authorization.required") {
+ this.#authorizations.set(event.data.attemptId ?? event.data.name, event.data);
}
return endsTurnSegment(event, {
callbacks:
this.#followCallbacks &&
- [...this.#authorizations.values()].some(
- (authorization) => authorization.webhookUrl !== undefined,
- ),
- requests: this.#requests.size > 0,
+ openSignIns(this.#projection).some((attempt) => attempt.awaitsCallback === true),
+ requests: openInputs(this.#projection).length > 0,
});
}
}
diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.ts
index 75928736d..937bd083e 100644
--- a/packages/eve/src/client/session.ts
+++ b/packages/eve/src/client/session.ts
@@ -158,6 +158,8 @@ export class ClientSession {
"Message route did not return a delivery id. Update the server before sending with this client.",
);
}
+ // A message's response ends at the boundary that lists its delivery. An answer's ends at its
+ // first turn boundary: not every path that publishes an answer's events attributes them.
return this.#messageResponse<TOutput>(
response,
input,
@@ -269,7 +271,8 @@ export class ClientSession {
);
}
if (!started && !matches) continue;
- if (!terminal && event.meta?.deliveryIds !== undefined && !matches) continue;
+ const attributed = event.meta?.deliveryIds !== undefined;
+ if (!terminal && attributed && !matches) continue;
started = true;
}
reachedBoundary = segment.observe(event);
diff --git a/packages/eve/src/client/tool-call-state.ts b/packages/eve/src/client/tool-call-state.ts
new file mode 100644
index 000000000..4b5b8bd39
--- /dev/null
+++ b/packages/eve/src/client/tool-call-state.ts
@@ -0,0 +1,95 @@
+import { conversationProjection } from "#client/conversation-projection.js";
+import type { ConversationState } from "#client/conversation-state.js";
+import type { EveDynamicToolPart } from "#client/message-reducer-types.js";
+import { callStatus, type SessionCallStatus } from "#protocol/session-projection.js";
+
+/**
+ * Where a tool call stands. `interrupted` is a call still running when its turn ended without an
+ * outcome, or when the reader's stream stopped; `cancelled` follows task or input cancellation.
+ */
+export type ToolCallStatus = SessionCallStatus | "interrupted";
+
+export interface ToolCallState {
+ readonly status: ToolCallStatus;
+ /** The call's output, or its latest partial output while it runs. */
+ readonly output?: unknown;
+ readonly errorText?: string;
+ /** A reported execution error code, when available. */
+ readonly errorCode?: string;
+}
+
+/**
+ * A tool call's state for rendering: its status from the session projection, which every reader
+ * shares, and its content from the message part. Pass `streaming: false` once the reader's stream
+ * stopped, so a call left running reads as interrupted.
+ */
+export function toolCallState(
+ conversation: ConversationState,
+ callId: string,
+ options: { readonly streaming?: boolean } = {},
+): ToolCallState | undefined {
+ const part = findToolPart(conversation, callId);
+ const projection = conversationProjection(conversation);
+ const call = projection.calls[callId];
+ const status = callStatus(projection, callId, options) ?? partStatus(part, options);
+ if (status === undefined) return undefined;
+ const task = call?.taskId === undefined ? undefined : conversation.tasks[call.taskId];
+ const taskCall = task?.calls[callId];
+ const output = taskCall?.output ?? part?.output;
+ const errorText =
+ taskCall?.error?.message ??
+ part?.errorText ??
+ call?.error?.message ??
+ (part?.state === "output-denied" ? part.approval.reason : undefined);
+ const state: { -readonly [K in keyof ToolCallState]: ToolCallState[K] } = {
+ status: respondedStatus(conversation, part, status),
+ };
+ if (output !== undefined) state.output = output;
+ if (errorText !== undefined) state.errorText = errorText;
+ if (call?.error?.code !== undefined) state.errorCode = call.error.code;
+ return state;
+}
+
+/** An approval this client answered reads as decided until the stream settles it. */
+function respondedStatus(
+ conversation: ConversationState,
+ part: EveDynamicToolPart | undefined,
+ status: ToolCallStatus,
+): ToolCallStatus {
+ if (status !== "awaiting-input" || part?.state !== "approval-requested") return status;
+ const input = conversation.inputs[part.approval.id];
+ if (input?.status !== "responded") return status;
+ return input.response?.optionId === "approve" ? "running" : "rejected";
+}
+
+/** A part the stream hasn't announced as a call yet, such as one whose input still streams. */
+function partStatus(
+ part: EveDynamicToolPart | undefined,
+ options: { readonly streaming?: boolean },
+): ToolCallStatus | undefined {
+ if (part === undefined) return undefined;
+ switch (part.state) {
+ case "output-available":
+ return part.partial === true ? "running" : "completed";
+ case "output-error":
+ return "failed";
+ case "output-denied":
+ return "rejected";
+ case "approval-requested":
+ return "awaiting-input";
+ default:
+ return options.streaming === false ? "interrupted" : "running";
+ }
+}
+
+function findToolPart(
+ conversation: ConversationState,
+ callId: string,
+): EveDynamicToolPart | undefined {
+ for (let index = conversation.messages.length - 1; index >= 0; index -= 1) {
+ for (const part of conversation.messages[index]!.parts) {
+ if (part.type === "dynamic-tool" && part.toolCallId === callId) return part;
+ }
+ }
+ return undefined;
+}
diff --git a/packages/eve/src/client/tool-part-state.ts b/packages/eve/src/client/tool-part-state.ts
new file mode 100644
index 000000000..ef5b4e912
--- /dev/null
+++ b/packages/eve/src/client/tool-part-state.ts
@@ -0,0 +1,136 @@
+import { conversationProjection } from "#client/conversation-projection.js";
+import type { EveDynamicToolPart, EveMessageData } from "#client/message-reducer-types.js";
+import { isSettledCallStatus, reportedCallStatus } from "#protocol/session-projection.js";
+
+/** A tool part's content, whichever state it was written in. */
+interface ToolPartContent {
+ readonly approval?: { readonly id: string; readonly isAutomatic?: boolean };
+ readonly errorText?: string;
+ readonly output?: unknown;
+ readonly partial?: true;
+}
+
+/**
+ * A tool part in the state the session projection gives its call. A request a person still has
+ * to answer comes first, then the call's own status; a call the projection doesn't know, such as
+ * a child's call a relayed request names, keeps the state its events wrote.
+ */
+export function toolPartState(data: EveMessageData, part: EveDynamicToolPart): EveDynamicToolPart {
+ const content = part as ToolPartContent;
+ const projection = conversationProjection(data);
+ const call = projection.calls[part.toolCallId];
+ const requestId = content.approval?.id;
+ const input = requestId === undefined ? undefined : projection.inputs[requestId];
+ const base = {
+ input: part.input,
+ stepIndex: part.stepIndex,
+ toolCallId: part.toolCallId,
+ toolMetadata: part.toolMetadata,
+ toolName: part.toolName,
+ type: "dynamic-tool" as const,
+ };
+ const requested =
+ requestId === undefined
+ ? undefined
+ : {
+ id: requestId,
+ ...(content.approval?.isAutomatic !== undefined && {
+ isAutomatic: content.approval.isAutomatic,
+ }),
+ };
+ /** An answered request: approved, or answered without a decision, as a question is. */
+ const responded = (approved: boolean, reason: string | undefined): EveDynamicToolPart => ({
+ ...base,
+ approval: {
+ ...requested!,
+ ...(approved && { approved: true }),
+ ...(reason !== undefined && { reason }),
+ },
+ state: "approval-responded",
+ });
+ const approvedTrue =
+ requested === undefined ? undefined : { ...requested, approved: true as const };
+
+ // A request still open, or answered by this client before the stream settled it, waits for
+ // its answer, unless the call already ended.
+ if (
+ requested !== undefined &&
+ input !== undefined &&
+ input.status !== "settled" &&
+ (call === undefined || !isSettledCallStatus(reportedCallStatus(projection, call)))
+ ) {
+ return { ...base, approval: requested, state: "approval-requested" };
+ }
+
+ const task =
+ call?.taskId === undefined ? undefined : projection.tasks[call.taskId]?.calls[part.toolCallId];
+ if (call === undefined) {
+ if (input === undefined) return part;
+ return input.response === undefined
+ ? { ...base, output: { status: input.outcome }, state: "output-available" }
+ : responded(input.outcome === "approved", input.response.text);
+ }
+ switch (reportedCallStatus(projection, call)) {
+ case "running":
+ case "awaiting-input":
+ if (content.partial === true) {
+ return {
+ ...base,
+ approval: approvedTrue,
+ output: content.output,
+ partial: true,
+ state: "output-available",
+ };
+ }
+ if (input !== undefined && (input.outcome === "approved" || input.response !== undefined)) {
+ return responded(input.outcome === "approved", input.response?.text);
+ }
+ return { ...base, state: "input-available" };
+ case "completed":
+ return {
+ ...base,
+ approval: approvedTrue,
+ output: task?.output ?? content.output,
+ state: "output-available",
+ };
+ case "failed":
+ return {
+ ...base,
+ approval: approvedTrue,
+ errorText:
+ task?.error?.message ??
+ content.errorText ??
+ call.error?.message ??
+ (call.taskId === undefined ? "Action failed." : "Task failed."),
+ state: "output-error",
+ };
+ case "rejected":
+ return {
+ ...base,
+ approval: {
+ id: requestId ?? part.toolCallId,
+ approved: false,
+ reason: call.error?.message ?? content.errorText,
+ },
+ state: "output-denied",
+ };
+ case "cancelled":
+ // A withdrawn approval never ran its call; a stopped call or task did.
+ if (requestId !== undefined && input?.outcome === "cancelled") {
+ return {
+ ...base,
+ approval: { id: requestId, approved: false, reason: "Tool execution was cancelled." },
+ state: "output-denied",
+ };
+ }
+ return {
+ ...base,
+ approval: approvedTrue,
+ errorText:
+ call.taskId === undefined
+ ? (content.errorText ?? call.error?.message ?? "Action was cancelled.")
+ : "Task was cancelled.",
+ state: "output-error",
+ };
+ }
+}
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 4a960bc05..551bec41b 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,10 +22,10 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 73,
+ current: 74,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 63, 64, 65, 66, 67,
- 68, 69, 70, 71, 72, 73,
+ 68, 69, 70, 71, 72, 73, 74,
],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
@@ -72,10 +72,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
dynamicTool: {
- current: 70,
+ current: 71,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 54,
- 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70,
+ 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -114,10 +114,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
channel: {
- current: 47,
+ current: 48,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31, 36, 37, 38, 39, 40, 41, 42,
- 43, 44, 45, 46, 47,
+ 43, 44, 45, 46, 47, 48,
],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -139,8 +139,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
schedule: {
- current: 26,
- supported: [1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20, 21, 22, 23, 24, 25, 26],
+ current: 27,
+ supported: [
+ 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27,
+ ],
dropped: {
5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
16: 'Background task delivery was removed: sends no longer accept taskDeliveryPolicy and message.completed always carries text. input.resolved reports outcome "cancelled" when a workflow tool withdraws a ctx.ask() request, and stream events gained agent.started, published when a workflow run opens a ctx.agent session, and turn.waiting, which parks the open turn instead of emitting turn.completed and session.waiting.',
@@ -148,8 +150,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
subagent: {
- current: 29,
- supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 23, 24, 25, 26, 27, 28, 29],
+ current: 30,
+ supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 23, 24, 25, 26, 27, 28, 29, 30],
dropped: {
1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",
2: "Persistent subagent sessions are now the default and the experimental opt-in was removed",
@@ -162,10 +164,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
connection: {
- current: 38,
+ current: 39,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 26, 32, 33, 34,
- 35, 36, 37, 38,
+ 35, 36, 37, 38, 39,
],
dropped: {
9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",
@@ -180,8 +182,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
hook: {
- current: 37,
- supported: [20, 21, 22, 23, 25, 27, 31, 32, 33, 34, 35, 36, 37],
+ current: 38,
+ supported: [20, 21, 22, 23, 25, 27, 31, 32, 33, 34, 35, 36, 37, 38],
dropped: {
1: "Model identity moved from session.started runtime metadata to step.started call attribution.",
2: "Model identity moved from session.started runtime metadata to step.started call attribution.",
@@ -211,10 +213,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
skill: { current: 2, supported: [1, 2], dropped: {} },
dynamicSkill: {
- current: 31,
+ current: 32,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 25, 26, 27, 28, 29, 30,
- 31,
+ 31, 32,
],
dropped: {
13: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -225,10 +227,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
instructions: { current: 2, supported: [1, 2], dropped: {} },
dynamicInstructions: {
- current: 32,
+ current: 33,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 26, 27, 28, 29, 30,
- 31, 32,
+ 31, 32, 33,
],
dropped: {
14: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
diff --git a/packages/eve/src/context/providers/session.ts b/packages/eve/src/context/providers/session.ts
index 67566560e..4dce85739 100644
--- a/packages/eve/src/context/providers/session.ts
+++ b/packages/eve/src/context/providers/session.ts
@@ -9,14 +9,15 @@ import {
import type { ContextReader } from "#context/key.js";
import type { HarnessSession } from "#harness/types.js";
import type { FrameworkContextProvider } from "#context/provider.js";
-import { getHarnessEmissionState } from "#harness/emission.js";
+import { activeTurnId, turnPosition } from "#harness/session-machine/view.js";
+import { projectionFor } from "#harness/session-machine/current.js";
export const sessionProvider = {
key: SessionKey,
create(ctx: ContextReader, session: Pick<HarnessSession, "state">) {
const currentAuth = ctx.require(AuthKey);
- const emission = getHarnessEmissionState(session.state);
- const turnId = emission.turnId.length > 0 ? emission.turnId : `turn_${emission.sequence}`;
+ const emission = turnPosition(projectionFor(ctx, session.state));
+ const turnId = activeTurnId(emission);
return {
value: Object.freeze({
diff --git a/packages/eve/src/execution/cancel-descendant-turns-step.ts b/packages/eve/src/execution/cancel-descendant-turns-step.ts
index e70c41e5b..40a2324df 100644
--- a/packages/eve/src/execution/cancel-descendant-turns-step.ts
+++ b/packages/eve/src/execution/cancel-descendant-turns-step.ts
@@ -1,4 +1,3 @@
-import { getPendingCoordinationBatch } from "#harness/coordination.js";
import { readDurableSession, type DurableSessionState } from "#execution/durable-session-store.js";
import { cancelWorkflowToolRun } from "#execution/tools/workflow/cancel.js";
import {
@@ -6,11 +5,13 @@ import {
type BlockingWorkflowToolRun,
} from "#harness/workflow-tool-runs.js";
import { createLogger, logError } from "#internal/logging.js";
+import { runtimeWait, storedProjection, turnPosition } from "#harness/session-machine/view.js";
const log = createLogger("execution.cancel-descendant-turns");
/** Cancels every workflow tool run the turn is waiting on. */
export async function cancelDescendantTurnsStep(input: {
+ readonly serializedContext: Record<string, unknown>;
readonly sessionState: DurableSessionState;
}): Promise<void> {
"use step";
@@ -20,8 +21,8 @@ export async function cancelDescendantTurnsStep(input: {
const session = readDurableSession(input.sessionState);
workflowToolRuns = getBlockingWorkflowToolRuns(
session.state,
- getPendingCoordinationBatch(session.state)?.event.turnId ??
- input.sessionState.emissionState.turnId,
+ runtimeWait(session.state)?.event.turnId ??
+ turnPosition(storedProjection(session.state)).turnId,
);
} catch (error) {
logError(log, "failed to read pending descendants during cancellation", error, {
diff --git a/packages/eve/src/execution/cancelled-model-call-batch.ts b/packages/eve/src/execution/cancelled-model-call-batch.ts
index 2381a23d0..6084bf13d 100644
--- a/packages/eve/src/execution/cancelled-model-call-batch.ts
+++ b/packages/eve/src/execution/cancelled-model-call-batch.ts
@@ -6,6 +6,7 @@ import { preserveCancelledTurnMessage } from "#execution/cancelled-turn-message.
import { createDurableSessionValues } from "#execution/durable-session-store.js";
import type { DurableStepResult } from "#execution/session/turn-step-types.js";
import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";
+import { saveSessionProjection } from "#harness/session-machine/current.js";
import { preserveSerializedInstrumentationState } from "#instrumentation/state.js";
import { preserveSerializedAgentTraceState } from "#tracing/agent-trace-context-store.js";
@@ -30,6 +31,7 @@ export async function createCancelledModelCallBatchResult(input: {
preserveCancelledTurnMessage(checkpointSession, input.stepInput),
)
: checkpointSession;
+ // The stream keeps every event the cancelled batch published, so the projection does too.
const checkpointContext = {
...(input.checkpoint?.serializedContext ?? input.beforeBatchContext),
[AuthKey.name]: interruptedContext[AuthKey.name],
@@ -45,6 +47,6 @@ export async function createCancelledModelCallBatchResult(input: {
),
interruptedContext,
),
- ...createDurableSessionValues(cancelledSession),
+ ...createDurableSessionValues(saveSessionProjection(cancelledSession, input.ctx)),
};
}
diff --git a/packages/eve/src/execution/context.test.ts b/packages/eve/src/execution/context.test.ts
index b664ff1fa..3d37b3736 100644
--- a/packages/eve/src/execution/context.test.ts
+++ b/packages/eve/src/execution/context.test.ts
@@ -15,7 +15,7 @@ import {
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { runStep } from "#context/run-step.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
+import { positionState } from "#internal/testing/session-machine.js";
import type { HarnessSession } from "#harness/types.js";
vi.mock("./sandbox/ensure.js", () => ({
@@ -37,13 +37,13 @@ function createStubSession(overrides: Partial<HarnessSession> = {}): HarnessSess
}
function createSessionWithEmissionState(input: {
- readonly state: HarnessEmissionState;
+ readonly state: {
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+ };
}): HarnessSession {
- return createStubSession({
- state: {
- "eve.harness.emission": input.state,
- },
- });
+ return createStubSession({ state: positionState(input.state) });
}
function createSeedContext(overrides?: {
@@ -163,7 +163,6 @@ describe("runStep with sessionProvider", () => {
createSessionWithEmissionState({
state: {
sequence: 2,
- sessionStarted: true,
stepIndex: 0,
turnId: "turn_2",
},
@@ -173,7 +172,6 @@ describe("runStep with sessionProvider", () => {
createSessionWithEmissionState({
state: {
sequence: 2,
- sessionStarted: true,
stepIndex: 1,
turnId: "turn_2",
},
@@ -183,7 +181,6 @@ describe("runStep with sessionProvider", () => {
createSessionWithEmissionState({
state: {
sequence: 3,
- sessionStarted: true,
stepIndex: 0,
turnId: "",
},
diff --git a/packages/eve/src/execution/coordination-dispatch-shared.ts b/packages/eve/src/execution/coordination-dispatch-shared.ts
index 981c8a609..029b12c81 100644
--- a/packages/eve/src/execution/coordination-dispatch-shared.ts
+++ b/packages/eve/src/execution/coordination-dispatch-shared.ts
@@ -22,21 +22,18 @@ import {
} from "#runtime/sessions/runtime-context-keys.js";
import { deserializeContext } from "#context/serialize.js";
import type { HarnessSessionBase } from "#harness/types.js";
+import { assertUniqueCoordinationCallIds } from "#harness/coordination.js";
import {
- assertUniqueCoordinationCallIds,
- getPendingCoordinationBatch,
- setPendingCoordinationBatch,
-} from "#harness/coordination.js";
-import { activeTurnId } from "#harness/active-turn-id.js";
+ activeTurnId,
+ runtimeWait,
+ storedProjection,
+ turnPosition,
+} from "#harness/session-machine/view.js";
import type { RuntimeActionResult, RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
import type { SessionParent, SessionTraceRoot } from "#channel/types.js";
import type { ContextReader } from "#context/key.js";
import { resolveTraceRootSessionId } from "#shared/trace-root.js";
-import {
- createDurableSessionState,
- type DurableSessionState,
- readDurableSession,
-} from "#execution/durable-session-store.js";
+import { type DurableSessionState, readDurableSession } from "#execution/durable-session-store.js";
import { hydrateDurableSession } from "#execution/session.js";
import { buildSubagentRunInput } from "#subagents/tool.js";
import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";
@@ -101,39 +98,21 @@ export async function prepareCoordinationDispatch(input: {
readonly sessionState: DurableSessionState;
}): Promise<PreparedCoordinationDispatch | undefined> {
const durableSession = readDurableSession(input.sessionState);
- const pending = getPendingCoordinationBatch(durableSession.state);
-
- if (pending === undefined) return undefined;
- const requests = pending.tasks;
+ const waiting = runtimeWait(durableSession.state);
+ if (waiting === undefined) return undefined;
+ const requests = waiting.tasks;
if (requests.length === 0) return undefined;
- const turnId = pending.event.turnId || activeTurnId(input.sessionState.emissionState);
- const event = pending.event.turnId === turnId ? pending.event : { ...pending.event, turnId };
+ const turnId =
+ waiting.event.turnId || activeTurnId(turnPosition(storedProjection(durableSession.state)));
const ctx = await deserializeContext(input.serializedContext);
const prepared = await prepareActionDispatch({
- batch: {
- approvers: pending.approvers,
- event,
- requests,
- },
+ batch: { approvers: waiting.approvers, event: { ...waiting.event, turnId }, requests },
ctx,
durableSession,
plan: () => requests,
serializedContext: input.serializedContext,
});
- if (event === pending.event) {
- return { ...prepared, sessionState: input.sessionState };
- }
-
- const session = setPendingCoordinationBatch({
- ...pending,
- event,
- session: prepared.session,
- });
- return {
- ...prepared,
- session,
- sessionState: createDurableSessionState({ session }),
- };
+ return { ...prepared, sessionState: input.sessionState };
}
interface DispatchBatch {
diff --git a/packages/eve/src/execution/coordination-dispatch-step.ts b/packages/eve/src/execution/coordination-dispatch-step.ts
index f157cee99..f5f8423d1 100644
--- a/packages/eve/src/execution/coordination-dispatch-step.ts
+++ b/packages/eve/src/execution/coordination-dispatch-step.ts
@@ -18,6 +18,9 @@ import {
resolveStepAgentLimits,
} from "#execution/agent-sessions/context.js";
import type { TaskStartedStreamEvent } from "#protocol/message.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { startTask } from "#harness/session-machine/transitions.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import type { RuntimeActionResult } from "#shared/action-types.js";
import type { HarnessSessionBase } from "#harness/types.js";
@@ -50,7 +53,7 @@ async function dispatchCoordination(
const { batch, session } = prepared;
let nextSession = session;
const results: RuntimeActionResult[] = [];
- const started: TaskStartedStreamEvent[] = [];
+ const started: TaskStartedStreamEvent["data"][] = [];
const agentLimits = resolveStepAgentLimits(prepared);
for (const task of prepared.plan) {
@@ -82,7 +85,10 @@ async function dispatchCoordination(
: createDurableSessionState({ session: nextSession }),
sessionWritable: input.sessionWritable,
},
- started,
+ started.flatMap(
+ (task) =>
+ startTask(sessionView(storedProjection(nextSession.state), nextSession.state), task).events,
+ ),
);
return { results, ...published };
}
@@ -94,7 +100,7 @@ async function dispatchCoordination(
async function dispatchWorkflowCall(start: StartWorkflowTaskInput): Promise<{
readonly result?: RuntimeActionResult;
readonly session: HarnessSessionBase;
- readonly started?: TaskStartedStreamEvent;
+ readonly started?: TaskStartedStreamEvent["data"];
}> {
const { entry } = start.task;
switch (entry.entryPoint) {
diff --git a/packages/eve/src/execution/durable-session-read.ts b/packages/eve/src/execution/durable-session-read.ts
new file mode 100644
index 000000000..18a242dc6
--- /dev/null
+++ b/packages/eve/src/execution/durable-session-read.ts
@@ -0,0 +1,14 @@
+import type { DurableSession, DurableSessionState } from "#execution/durable-session-store.js";
+
+// Workflow bodies read checkpoints, so the reader stays free of the store's runtime imports.
+
+/** Explicit checkpoint contract shared by deployment handoffs. */
+export const DURABLE_SESSION_VERSION = 2;
+
+/** Reads only the embedded checkpoint; no stream or migration fallback exists. */
+export function readDurableSession(state: DurableSessionState): DurableSession {
+ if (state.version !== DURABLE_SESSION_VERSION || state.snapshot?.session === undefined) {
+ throw new Error("Unsupported session checkpoint. Start a new session on this deployment.");
+ }
+ return state.snapshot.session;
+}
diff --git a/packages/eve/src/execution/durable-session-store.test.ts b/packages/eve/src/execution/durable-session-store.test.ts
index c012cf93d..960be2db9 100644
--- a/packages/eve/src/execution/durable-session-store.test.ts
+++ b/packages/eve/src/execution/durable-session-store.test.ts
@@ -22,7 +22,6 @@ describe("durable session checkpoints", () => {
continuationToken: "alias",
version: DURABLE_SESSION_VERSION,
hasProxyInputRequests: false,
- emissionState: { sequence: 0, sessionStarted: false, stepIndex: 0, turnId: "" },
snapshot: { session: projectToDurableSession(session) },
});
expect(readDurableSession(state)).toBe(state.snapshot.session);
diff --git a/packages/eve/src/execution/durable-session-store.ts b/packages/eve/src/execution/durable-session-store.ts
index 73a22d0a7..3f4b65951 100644
--- a/packages/eve/src/execution/durable-session-store.ts
+++ b/packages/eve/src/execution/durable-session-store.ts
@@ -1,4 +1,3 @@
-import { getHarnessEmissionState, type HarnessEmissionState } from "#harness/emission.js";
import type { HarnessModelMessage } from "#harness/messages.js";
import { hasProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { HarnessSession, HarnessSessionBase, SessionStateMap } from "#harness/types.js";
@@ -6,8 +5,9 @@ import { projectToDurableSession } from "#execution/session.js";
import type { SandboxState } from "#sandbox/state.js";
import type { JsonObject } from "#shared/json.js";
-/** Explicit checkpoint contract shared by deployment handoffs. */
-export const DURABLE_SESSION_VERSION = 2;
+import { DURABLE_SESSION_VERSION } from "#execution/durable-session-read.js";
+
+export { DURABLE_SESSION_VERSION, readDurableSession } from "#execution/durable-session-read.js";
/**
* Serializable handle to a durable session.
@@ -17,10 +17,8 @@ export const DURABLE_SESSION_VERSION = 2;
* hook continuation token,
* `hasProxyInputRequests` (a closed-contract short-circuit that lets
* the owner skip a per-delivery proxy-routing step when no
- * descendant subagent is active), and `emissionState` (so workflow-body
- * framework steps can stamp protocol events
- * with `{ turnId, sequence, stepIndex }` without reading the full
- * durable session). Turn steps return state transitions to the owning
+ * descendant subagent is active). Turn coordinates come from the stored
+ * projection in the serialized context. Turn steps return state transitions to the owning
* `SessionStateCursor`; policy-only turn outcomes never carry snapshots.
*/
export interface DurableSessionState {
@@ -28,7 +26,6 @@ export interface DurableSessionState {
readonly sessionId: string;
readonly continuationToken: string;
readonly hasProxyInputRequests: boolean;
- readonly emissionState: HarnessEmissionState;
readonly snapshot: DurableSessionSnapshot;
}
@@ -74,14 +71,6 @@ export interface DurableSessionSnapshot {
readonly session: DurableSession;
}
-/** Reads only the embedded checkpoint; no stream or migration fallback exists. */
-export function readDurableSession(state: DurableSessionState): DurableSession {
- if (state.version !== DURABLE_SESSION_VERSION || state.snapshot?.session === undefined) {
- throw new Error("Unsupported session checkpoint. Start a new session on this deployment.");
- }
- return state.snapshot.session;
-}
-
/**
* Creates the projected {@link DurableSessionState} with the current
* snapshot embedded in the Workflow step result.
@@ -111,7 +100,6 @@ export function replaceDurableSessionSnapshot(input: {
function projectDurableSessionState(session: DurableSession): DurableSessionState {
return {
continuationToken: session.continuationToken,
- emissionState: getHarnessEmissionState(session.state),
hasProxyInputRequests: hasProxyInputRequests(session.state),
sessionId: session.sessionId,
version: DURABLE_SESSION_VERSION,
diff --git a/packages/eve/src/execution/dynamic-connections.ts b/packages/eve/src/execution/dynamic-connections.ts
index 2a5001c9a..dec2db2b5 100644
--- a/packages/eve/src/execution/dynamic-connections.ts
+++ b/packages/eve/src/execution/dynamic-connections.ts
@@ -1,13 +1,12 @@
import type { ContextContainer } from "#context/container.js";
import { dispatchDynamicConnectionEvent } from "#context/dynamic-connection-lifecycle.js";
import { announceConnections } from "#execution/connection-announcement.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import {
- createSessionStartedEvent,
- createTurnStartedEvent,
- type RuntimeIdentity,
- type UnstampedMessageStreamEvent,
-} from "#protocol/message.js";
+ sessionStartedForResolvers,
+ turnStartedForResolvers,
+} from "#harness/session-machine/resolver-events.js";
+import type { RuntimeIdentity, UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { ResolvedAgent } from "#runtime/types.js";
/** Binds dynamic connection lifecycle dispatch to one execution context. */
@@ -24,13 +23,13 @@ export function bindDynamicConnections(
return {
dispatch,
async rehydrate(
- state: HarnessEmissionState,
+ state: TurnPosition,
runtime: RuntimeIdentity,
turn?: { readonly sequence: number; readonly turnId: string },
): Promise<void> {
if (!state.sessionStarted) return;
- await dispatch(createSessionStartedEvent({ runtime }));
- if (turn !== undefined) await dispatch(createTurnStartedEvent(turn));
+ await dispatch(sessionStartedForResolvers(runtime));
+ if (turn !== undefined) await dispatch(turnStartedForResolvers(turn));
},
};
}
diff --git a/packages/eve/src/execution/legacy-session/interrupt-step.ts b/packages/eve/src/execution/legacy-session/interrupt-step.ts
index f4d82c5fd..4be3a0460 100644
--- a/packages/eve/src/execution/legacy-session/interrupt-step.ts
+++ b/packages/eve/src/execution/legacy-session/interrupt-step.ts
@@ -1,3 +1,5 @@
+import { readDurableSession } from "#execution/durable-session-store.js";
+import { isBetweenTurns, storedProjection } from "#harness/session-machine/view.js";
import {
EntityConflictError,
RunExpiredError,
@@ -69,7 +71,10 @@ export async function interruptLegacySessionStep(prepared: PreparedLegacySession
throw error;
}
}
- if (prepared.input.inputCommitted || prepared.sessionState.emissionState.turnId === "")
+ if (
+ prepared.input.inputCommitted ||
+ isBetweenTurns(storedProjection(readDurableSession(prepared.sessionState).state))
+ )
return {
history: prepared.history,
sessionState: prepared.sessionState,
diff --git a/packages/eve/src/execution/legacy-session/snapshot.test.ts b/packages/eve/src/execution/legacy-session/snapshot.test.ts
index 0b96145d1..14d5570f7 100644
--- a/packages/eve/src/execution/legacy-session/snapshot.test.ts
+++ b/packages/eve/src/execution/legacy-session/snapshot.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { importConversation, normalizeHistory } from "./snapshot.js";
import type { LegacySession } from "./snapshot.js";
+import { nextStepIndex, storedProjection, turnPosition } from "#harness/session-machine/view.js";
describe("conversation import", () => {
it("preserves authored state, budget, emission coordinates and storage", () => {
const session: LegacySession = {
@@ -37,7 +38,10 @@ describe("conversation import", () => {
"eve.runtime.pendingCoordinationBatch",
);
expect(result.snapshot.session.state).not.toHaveProperty("eve.agent.handles");
- expect(result.emissionState.sequence).toBe(9);
+ const projection = storedProjection(result.snapshot.session.state);
+ expect(turnPosition(projection).sequence).toBe(9);
+ // The legacy driver kept the index its next step takes.
+ expect(nextStepIndex(projection)).toBe(3);
expect(result.snapshot.session).not.toHaveProperty("history");
expect(history[0]).toMatchObject({
kind: "user",
diff --git a/packages/eve/src/execution/legacy-session/snapshot.ts b/packages/eve/src/execution/legacy-session/snapshot.ts
index 30ff2e6ab..ebe956900 100644
--- a/packages/eve/src/execution/legacy-session/snapshot.ts
+++ b/packages/eve/src/execution/legacy-session/snapshot.ts
@@ -1,5 +1,6 @@
import type { ModelMessage } from "ai";
-import { getHarnessEmissionState } from "#harness/emission.js";
+import { SESSION_PROJECTION_STATE_KEY } from "#harness/session-machine/view.js";
+import { initialSessionProjection, type SessionProjection } from "#protocol/session-projection.js";
import { isUserMessageKind, validateHarnessModelMessages } from "#harness/messages.js";
import {
DURABLE_SESSION_VERSION,
@@ -11,8 +12,9 @@ import { isObject } from "#shared/guards.js";
export type LegacySession = DurableSession & { readonly history: ModelMessage[] };
+const LEGACY_EMISSION_KEY = "eve.harness.emission";
+
const PRESERVED_FRAMEWORK_STATE = new Set([
- "eve.harness.emission",
"eve.harness.turnUsage",
"eve.harness.reportedSessionUsage",
"eve.harness.sessionRuntimeTokenLimit",
@@ -53,8 +55,38 @@ export function importConversation(session: LegacySession): {
sessionId: session.sessionId,
continuationToken: session.continuationToken,
hasProxyInputRequests: false,
- emissionState: getHarnessEmissionState(state),
- snapshot: { session: { ...durable, state } },
+ snapshot: {
+ session: {
+ ...durable,
+ state: { ...state, [SESSION_PROJECTION_STATE_KEY]: importProjection(session) },
+ },
+ },
+ },
+ };
+}
+
+/** The turn position a legacy driver persisted, as the projection that replaces it. */
+export function importProjection(session: LegacySession): SessionProjection {
+ const raw = session.state?.[LEGACY_EMISSION_KEY];
+ const projection = initialSessionProjection();
+ if (!isObject(raw) || typeof raw.sequence !== "number") return projection;
+ const started = raw.sessionStarted === true ? { started: true as const } : {};
+ const turnId = typeof raw.turnId === "string" ? raw.turnId : "";
+ if (turnId === "") return { ...projection, ...started, nextSequence: raw.sequence };
+ // A legacy driver kept the index its next step takes; the projection keeps the last started.
+ const next = typeof raw.stepIndex === "number" ? raw.stepIndex : 0;
+ return {
+ ...projection,
+ ...started,
+ activeTurnId: turnId,
+ nextSequence: raw.sequence + 1,
+ turns: {
+ [turnId]: {
+ turnId,
+ sequence: raw.sequence,
+ status: "active",
+ ...(next > 0 && { stepIndex: next - 1 }),
+ },
},
};
}
diff --git a/packages/eve/src/execution/model-call-batching.ts b/packages/eve/src/execution/model-call-batching.ts
index 1fe4812ee..2ca36485b 100644
--- a/packages/eve/src/execution/model-call-batching.ts
+++ b/packages/eve/src/execution/model-call-batching.ts
@@ -1,3 +1,4 @@
+import { storedProjection } from "#harness/session-machine/view.js";
import { derivePendingState } from "#execution/session/pending-turn-state.js";
import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";
@@ -51,7 +52,11 @@ function shouldRunAnotherModelCall(input: {
return false;
}
- const pending = derivePendingState(input.result.session);
+ // Each step saves the lifecycle it published with its result.
+ const pending = derivePendingState(
+ input.result.session,
+ storedProjection(input.result.session.state),
+ );
return (
!pending.hasPendingAuthorization &&
!pending.hasPendingInputBatch &&
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index 0503c9a12..295ef9795 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -11,7 +11,7 @@ import {
StepDynamicToolMetadataKey,
} from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
-import { appendPendingInputBatch } from "#harness/input-requests.js";
+import { withParkedStep } from "#internal/testing/session-machine.js";
import { createInstrumentationHooks } from "#instrumentation/lifecycle.js";
import {
bindInstrumentationRuntime,
@@ -41,9 +41,9 @@ import {
// be written; the attribute contract is covered by emit.test.ts.
vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async () => {}) }));
-vi.mock("ai", () => ({
+vi.mock("ai", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("ai")>()),
ToolLoopAgent: vi.fn(),
- jsonSchema: vi.fn((schema: unknown) => schema),
isStepCount: vi.fn((count: number) => count),
tool: vi.fn((definition: unknown) => definition),
}));
@@ -488,50 +488,52 @@ describe("createExecutionNodeStep", () => {
resolverSlug: "wired",
} satisfies OldSourceOffsetDynamicToolMetadata,
]);
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "call-wired",
- input: {},
- kind: "tool-call",
- toolName: "wired_dynamic_tool",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Approve" },
- { id: "cancel", label: "Cancel" },
- ],
- prompt: "Approve dynamic tool",
- requestId: "approval-wired",
- },
- ],
- responseMessages: [
- {
- content: [
- {
- input: {},
- toolCallId: "call-wired",
- toolName: "wired_dynamic_tool",
- type: "tool-call",
- },
- {
- approvalId: "approval-wired",
- toolCallId: "call-wired",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- },
- ],
- session: createSession({
+ const session = withParkedStep(
+ createSession({
continuationToken: "test-dynamic",
sessionId: "sess-dynamic",
turnAgent: node.turnAgent,
}),
- });
+ {
+ messages: [
+ {
+ content: [
+ {
+ input: {},
+ toolCallId: "call-wired",
+ toolName: "wired_dynamic_tool",
+ type: "tool-call",
+ },
+ {
+ approvalId: "approval-wired",
+ toolCallId: "call-wired",
+ type: "tool-approval-request",
+ },
+ ],
+ role: "assistant",
+ },
+ ],
+ requests: [
+ {
+ action: {
+ callId: "call-wired",
+ input: {},
+ kind: "tool-call",
+ toolName: "wired_dynamic_tool",
+ },
+ allowFreeform: false,
+ display: "confirmation",
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "cancel", label: "Cancel" },
+ ],
+ prompt: "Approve dynamic tool",
+ requestId: "approval-wired",
+ },
+ ],
+ },
+ );
await contextStorage.run(ctx, () =>
step(session, {
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index 4d48222cb..a3bdf729d 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -32,6 +32,7 @@ import {
resolveWebSearchActivityLabel,
WEB_SEARCH_TOOL_NAME,
} from "#harness/provider-tool-schemas.js";
+import type { ToolLoopHarnessConfig } from "#harness/types.js";
const log = createLogger("execution.node-step");
@@ -72,6 +73,7 @@ interface CreateExecutionNodeStepInput {
readonly sequence: number;
readonly turnId: string;
}) => Promise<void>;
+ readonly signInCompletions?: ToolLoopHarnessConfig["signInCompletions"];
readonly historyProjector?: HistoryViewProjector;
readonly historyView?: PreparedHistoryView;
readonly instrumentation: ExecutionInstrumentation | undefined;
@@ -107,6 +109,7 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
historyView: input.historyView,
instrumentation: sessionInstrumentation,
prepareApprovalTurn: input.prepareApprovalTurn,
+ signInCompletions: input.signInCompletions,
resolveStepDynamicTools: (resolveInput) =>
preparePersistedStepDynamicToolMetadata({
...resolveInput,
diff --git a/packages/eve/src/execution/proxied-deliver-step.ts b/packages/eve/src/execution/proxied-deliver-step.ts
index 0c4a1e2dd..abd8dfcdb 100644
--- a/packages/eve/src/execution/proxied-deliver-step.ts
+++ b/packages/eve/src/execution/proxied-deliver-step.ts
@@ -1,3 +1,6 @@
+import { sessionView } from "#harness/session-machine/commit.js";
+import { routeAnswer, hold, receiveRelayedAnswer } from "#harness/session-machine/transitions.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import type { SessionInboxAddress } from "#execution/session-inbox/address.js";
import { hasDelegatedSessionContext } from "#execution/delegated-session-context.js";
import { buildAdapterContext } from "#channel/adapter-context.js";
@@ -26,20 +29,15 @@ import {
resolveRemoteAgentStreamHeaders,
respondToRemoteAgentSession,
} from "#execution/agent-sessions/remote.js";
-import { createTurnWaitingOnInputEvent, routeDeliverPayload } from "#subagents/hitl-proxy.js";
+import { routeDeliverPayload } from "#subagents/hitl-proxy.js";
import { resumeSessionInbox } from "#execution/session-inbox/resume.js";
import {
sendWorkflowAskAnswers,
toToolInputResponseResponder,
} from "#execution/tools/workflow/answer.js";
-import type { PendingInputBatchEvent } from "#harness/pending-input-batches.js";
+import type { StepCoordinates as PendingInputBatchEvent } from "#harness/session-machine/view.js";
import type { WorkflowAskRoute } from "#harness/proxy-input-requests.js";
-import {
- createInputResolvedEvent,
- createMessageReceivedEvent,
- type InputResolution,
- type UnstampedMessageStreamEvent,
-} from "#protocol/message.js";
+import { type InputResolution, type UnstampedMessageStreamEvent } from "#protocol/message.js";
import { getProxyInputRequests, retireProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { InputResponse } from "#shared/input.js";
@@ -122,9 +120,7 @@ async function routeProxiedDeliver(
}
if (forChild.message !== undefined) {
const { sequence, turnId } = forChild.resolved.event;
- answerMessages.push(
- createMessageReceivedEvent({ message: forChild.message, sequence, turnId }),
- );
+ answerMessages.push(receiveRelayedAnswer({ message: forChild.message, sequence, turnId }));
for (const metadata of sourceDelivery.deliveryMetadata ?? []) {
if (metadata.payloadIndex === sourcePayloadIndex) {
answerDeliveryIds.push(metadata.deliveryId);
@@ -169,7 +165,7 @@ async function routeProxiedDeliver(
}
let retired = false;
- const resolvedEvents: UnstampedMessageStreamEvent[] = [];
+ const answered: { event: PendingInputBatchEvent; resolutions: InputResolution[] }[] = [];
for (const child of children.values()) {
if (child.workflowAsk !== undefined) {
const responses = coalesceDeliverPayloads(child.payloads).inputResponses ?? [];
@@ -206,16 +202,14 @@ async function routeProxiedDeliver(
);
}
}
- if (child.resolutions.size > 0) {
- resolvedEvents.push(
- createInputResolvedEvent({ resolutions: [...child.resolutions.values()], ...child.event }),
- );
- }
+ answered.push({ event: child.event, resolutions: [...child.resolutions.values()] });
// Successfully forwarded request IDs are retired so later deliveries
// cannot route through stale entries.
durableSession = retireProxyInputRequests(durableSession, [...child.resolutions.keys()]);
retired = true;
}
+ const view = sessionView(storedProjection(durableSession.state), durableSession.state);
+ const resolvedEvents = [...routeAnswer(view, { children: answered }).events];
// Answers that leave requests pending, and nothing for the turn itself, keep
// the open turn held, so it parks again as after a partial approval answer.
if (
@@ -224,7 +218,7 @@ async function routeProxiedDeliver(
parentAction === undefined &&
getProxyInputRequests(durableSession.state).size > 0
) {
- resolvedEvents.push(createTurnWaitingOnInputEvent(durableSession));
+ resolvedEvents.push(...hold(view, { on: "input" }).events);
}
let published: PublishedSessionEvents = {
diff --git a/packages/eve/src/execution/publish-session-events.integration.test.ts b/packages/eve/src/execution/publish-session-events.integration.test.ts
index cfabf409c..36d83d972 100644
--- a/packages/eve/src/execution/publish-session-events.integration.test.ts
+++ b/packages/eve/src/execution/publish-session-events.integration.test.ts
@@ -7,7 +7,8 @@ import { upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { HarnessSession } from "#harness/types.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { createTestSessionState } from "#internal/testing/session-state.js";
-import type { MessageStreamEvent } from "#protocol/message.js";
+import { createInputRequestedEvent, type MessageStreamEvent } from "#protocol/message.js";
+import { withPublished } from "#internal/testing/session-machine.js";
import { defineHook } from "#public/definitions/hook.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
@@ -97,7 +98,22 @@ it("relays a withdrawn workflow question's input.resolved to the stream and its
],
],
forChildContinuationToken: "ask-1",
- session: base.snapshot.session as HarnessSession,
+ session: withPublished(base.snapshot.session as HarnessSession, [
+ createInputRequestedEvent({
+ callId: "call-1",
+ requests: [
+ {
+ action: { callId: "call-1", input: {}, kind: "tool-call", toolName: "research" },
+ kind: "question",
+ prompt: "Which region should Alice's report cover?",
+ requestId: "ask-1",
+ },
+ ],
+ sequence: 1,
+ stepIndex: 0,
+ turnId: "turn-1",
+ }),
+ ]),
});
await runtime.run(async () => {
diff --git a/packages/eve/src/execution/publish-session-events.ts b/packages/eve/src/execution/publish-session-events.ts
index e916ebf1c..b5cf1e343 100644
--- a/packages/eve/src/execution/publish-session-events.ts
+++ b/packages/eve/src/execution/publish-session-events.ts
@@ -22,9 +22,14 @@ import {
import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";
import { reconcileSessionContinuationToken } from "#execution/reconcile-session-continuation-token.js";
import { hydrateDurableSession } from "#execution/session.js";
-import { activeTurnId } from "#harness/active-turn-id.js";
-import { getHarnessEmissionState } from "#harness/emission.js";
-import type { HarnessTurnRef } from "#harness/emission-state.js";
+import { dropClosedRecords } from "#harness/session-machine/commit.js";
+import {
+ currentProjection,
+ enterSessionProjection,
+ recordPublishedEvent,
+ saveSessionProjection,
+} from "#harness/session-machine/current.js";
+import { activeTurnId, turnPosition } from "#harness/session-machine/view.js";
import { validateHarnessModelMessages, type HarnessModelMessage } from "#harness/messages.js";
import type { HandleEventFn, HarnessSession, HarnessSessionBase } from "#harness/types.js";
import { bindSessionInstrumentation } from "#instrumentation/runtime.js";
@@ -35,6 +40,7 @@ import {
type MessageStreamEvent,
type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
+import { type SessionProjection } from "#protocol/session-projection.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
const log = createLogger("execution.publish-session-events");
@@ -99,7 +105,8 @@ async function publishEventsFromStep(
if (events.length === 0) {
return { serializedContext: target.serializedContext, sessionState: target.sessionState };
}
- const { published } = await publishFromSessionStep(await restoreSessionStep(target), {
+ const restored = await restoreSessionStep(target);
+ const { published } = await publishFromSessionStep(restored, {
origin,
async publish(emit) {
for (const event of events) await emit(event);
@@ -180,7 +187,12 @@ export async function publishFromSessionStep<T, R>(
const update: SessionUpdate<R> = publication.updateSession?.(scoped.session, scoped.result) ?? {
session: scoped.session,
};
- const session = reconcileSessionContinuationToken(ctx, update.session);
+ // The session saves the lifecycle it published, without the records whose owners it closed.
+ const projection = readSessionProjection(ctx);
+ const session = reconcileSessionContinuationToken(
+ ctx,
+ saveSessionProjection(dropClosedRecords(update.session, projection), ctx),
+ );
return {
published: {
serializedContext: serializeContext(ctx),
@@ -201,6 +213,7 @@ async function publishInSessionScope<T>(
publication: SessionStepPublication<T, unknown>,
): Promise<{ readonly result: T; readonly session: HarnessSessionBase }> {
const { ctx } = step;
+ enterSessionProjection(ctx, step.durableSession.state);
const effectiveAgent = resolveEffectiveAgentRuntime(ctx.require(BundleKey), ctx);
const hydrated = hydrateDurableSession({
compactionOverrides: { thresholdPercent: effectiveAgent.thresholdPercent },
@@ -232,7 +245,7 @@ async function publishInSessionScope<T>(
const emit =
instrumentation?.createHandleEvent({
handleEvent: publisher.publish,
- turnId: activeTurnId(getHarnessEmissionState(step.durableSession.state)),
+ turnId: activeTurnId(turnPosition(readSessionProjection(ctx))),
}) ?? publisher.publish;
return { result: await publication.publish(emit, enrichedSession), session: enrichedSession };
});
@@ -306,7 +319,9 @@ export function openSessionEventPublisher(input: {
sessionWritable: input.sessionWritable,
});
const emit = async (event: UnstampedMessageStreamEvent): Promise<MessageStreamEvent> => {
- return await writer.write(await dispatcher.deliver(event));
+ const stamped = await writer.write(await dispatcher.deliver(event));
+ recordPublishedEvent(ctx, stamped);
+ return stamped;
};
return {
dispatcher,
@@ -383,6 +398,11 @@ function openSessionEventWriter(input: {
};
}
+/** The session's projection as of the last event it published. */
+export function readSessionProjection(ctx: ContextContainer): SessionProjection {
+ return currentProjection(ctx);
+}
+
type TerminalSessionEvent = Extract<
UnstampedMessageStreamEvent,
{ type: "session.completed" | "session.failed" }
@@ -404,7 +424,7 @@ export async function publishTerminalSessionEvent(input: {
readonly serializedContext: Record<string, unknown>;
readonly sessionWritable: WritableStream<Uint8Array>;
/** The session's last turn, for channel handlers' `ctx.session.turn`. */
- readonly turn?: HarnessTurnRef;
+ readonly turn?: { readonly id: string; readonly sequence: number };
/** The turn the event ends, for instrumentation. */
readonly turnId?: string;
}): Promise<void> {
@@ -416,6 +436,7 @@ export async function publishTerminalSessionEvent(input: {
let publisher: SessionEventPublisher;
try {
ctx = await deserializeContext(input.serializedContext);
+ enterSessionProjection(ctx, undefined);
publisher = openSessionEventPublisher({
ctx,
origin: "own",
diff --git a/packages/eve/src/execution/session-workflow-tool-run.integration.test.ts b/packages/eve/src/execution/session-workflow-tool-run.integration.test.ts
index 4e4bb1d99..87e440953 100644
--- a/packages/eve/src/execution/session-workflow-tool-run.integration.test.ts
+++ b/packages/eve/src/execution/session-workflow-tool-run.integration.test.ts
@@ -45,10 +45,12 @@ describe("handleWorkflowToolRunMessage", () => {
created.taskId,
"reviewer-run",
).table;
- const base = createTestSessionState({
- emissionState: { sequence: 2, sessionStarted: true, stepIndex: 0, turnId: "turn_1" },
- sessionId: "support-session",
- });
+ const base = createTestSessionState(
+ {
+ sessionId: "support-session",
+ },
+ { sequence: 2, stepIndex: 0, turnId: "turn_1" },
+ );
const events: MessageStreamEvent[] = [];
const decoder = new TextDecoder();
const cursor = new SessionStateCursor({
diff --git a/packages/eve/src/execution/session/active-turn.ts b/packages/eve/src/execution/session/active-turn.ts
index f50487ad3..b442682a1 100644
--- a/packages/eve/src/execution/session/active-turn.ts
+++ b/packages/eve/src/execution/session/active-turn.ts
@@ -13,7 +13,8 @@ import type { SessionExecutionInput } from "#execution/session/turn.js";
import type { SessionInboxPayload } from "#execution/session-inbox/inbox.js";
import { decodeSessionInboxPayload } from "#execution/session-inbox/protocol.js";
import type { WorkflowToolRunMessage } from "#execution/tools/workflow/messages.js";
-import { activeTurnId } from "#harness/active-turn-id.js";
+import { readDurableSession } from "#execution/durable-session-read.js";
+import { activeTurnId, storedProjection, turnPosition } from "#harness/session-machine/view.js";
import { coalesceDeliveries } from "#harness/messages.js";
import { TurnCancelledError } from "#harness/turn-cancellation.js";
import type { RuntimeActionResult } from "#shared/action-types.js";
@@ -64,7 +65,9 @@ export class ActiveTurn {
this.input = input;
this.caller = owner.caller;
this.identity = { callerCallId: owner.caller?.callId, principal: owner.principal };
- this.expectedTurnId = activeTurnId(input.cursor.sessionState.emissionState);
+ this.expectedTurnId = activeTurnId(
+ turnPosition(storedProjection(readDurableSession(input.cursor.sessionState).state)),
+ );
this.unsubscribe = input.inbox.onInterrupt((payload) => {
if (this.cancelsThisTurn(payload)) this.abort();
});
diff --git a/packages/eve/src/execution/session/answer-caller.test.ts b/packages/eve/src/execution/session/answer-caller.test.ts
index f0f564441..c869e6624 100644
--- a/packages/eve/src/execution/session/answer-caller.test.ts
+++ b/packages/eve/src/execution/session/answer-caller.test.ts
@@ -1,7 +1,8 @@
import { describe, expect, it } from "vitest";
import type { SessionAuthContext } from "#channel/types.js";
import { attributeAnswers } from "#execution/session/answer-caller.js";
-import { appendPendingInputBatch } from "#harness/pending-input-batches.js";
+import { SESSION_PROJECTION_STATE_KEY } from "#harness/session-machine/view.js";
+import { foldSession, initialSessionProjection } from "#protocol/session-projection.js";
import type { InputRequest } from "#shared/input.js";
const approval: InputRequest = {
@@ -28,17 +29,13 @@ const bob: SessionAuthContext = {
principalId: "bob",
principalType: "user",
};
-const state = appendPendingInputBatch({
- requests: [approval, question],
- responseMessages: [],
- session: {
- agent: { modelReference: { id: "test" }, system: "", tools: [] },
- compaction: { recentWindowSize: 10, threshold: 0.8 },
- continuationToken: "test",
- history: [],
- sessionId: "session-1",
- },
-}).state;
+const at = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+const state = {
+ [SESSION_PROJECTION_STATE_KEY]: [
+ { type: "turn.started", data: { sequence: 0, turnId: "turn_0" } },
+ { type: "input.requested", data: { ...at, requests: [approval, question] } },
+ ].reduce(foldSession, initialSessionProjection()),
+};
const approve = { optionId: "approve", requestId: approval.requestId };
const saturday = { optionId: "saturday", requestId: question.requestId };
diff --git a/packages/eve/src/execution/session/answer-caller.ts b/packages/eve/src/execution/session/answer-caller.ts
index fbe11ff1c..fe9845658 100644
--- a/packages/eve/src/execution/session/answer-caller.ts
+++ b/packages/eve/src/execution/session/answer-caller.ts
@@ -1,5 +1,6 @@
import type { SessionAuthContext } from "#channel/types.js";
-import { getPendingInputBatches } from "#harness/pending-input-batches.js";
+import { openInputs } from "#protocol/session-projection.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import type { SessionStateMap, StepInput } from "#harness/types.js";
/**
@@ -20,9 +21,12 @@ export function attributeAnswers(input: {
if (stepInput === undefined || stepInput.message !== undefined || responses.length === 0) {
return undefined;
}
+ // The session's own requests; a relayed one belongs to the run that asked.
const requests = new Map(
- getPendingInputBatches(input.state).flatMap((batch) =>
- batch.requests.map((request) => [request.requestId, request.kind] as const),
+ openInputs(storedProjection(input.state)).flatMap((open) =>
+ open.taskId === undefined && open.callId === undefined
+ ? [[open.request.requestId, open.request.kind] as const]
+ : [],
),
);
if (!responses.every((response) => requests.has(response.requestId))) return undefined;
diff --git a/packages/eve/src/execution/session/checkpoint-migrations.test.ts b/packages/eve/src/execution/session/checkpoint-migrations.test.ts
index 6a0d37bf2..7cd2ea11e 100644
--- a/packages/eve/src/execution/session/checkpoint-migrations.test.ts
+++ b/packages/eve/src/execution/session/checkpoint-migrations.test.ts
@@ -24,7 +24,6 @@ describe("migrateSessionCheckpoint", () => {
},
sessionState: {
continuationToken: "",
- emissionState: { sessionStarted: true, sequence: 1, stepIndex: 0, turnId: "" },
hasProxyInputRequests: false,
sessionId: "session-1",
snapshot: {
@@ -33,7 +32,19 @@ describe("migrateSessionCheckpoint", () => {
continuationToken: "",
sandboxState: { session: null },
sessionId: "session-1",
- state: { "eve.harness.requestEnvelopeTokens": 2483.5 },
+ state: {
+ "eve.harness.requestEnvelopeTokens": 2483.5,
+ "eve.harness.sessionProjection": {
+ started: true,
+ nextSequence: 1,
+ turns: {},
+ inputs: {},
+ calls: {},
+ tasks: {},
+ authorizations: {},
+ candidates: {},
+ },
+ },
},
},
version: 2,
@@ -62,6 +73,87 @@ describe("migrateSessionCheckpoint", () => {
});
});
+ it("upgrades an idle v11 checkpoint without losing position, grants, or application state", () => {
+ const result = migrateSessionCheckpoint(
+ v11Checkpoint({
+ "app.counter": 4,
+ "eve.harness.emission": { sessionStarted: true, sequence: 3, stepIndex: 0, turnId: "" },
+ "eve.runtime.hitl.approvedTools": ["deploy:api"],
+ }),
+ );
+ expect(result).toMatchObject({
+ kind: "current",
+ checkpoint: {
+ version: SESSION_CHECKPOINT_VERSION,
+ history: [{ role: "user", kind: "user", content: "Alice asks for a report." }],
+ sessionState: {
+ version: 2,
+ snapshot: {
+ session: {
+ state: {
+ "app.counter": 4,
+ "eve.harness.sessionProjection": {
+ started: true,
+ nextSequence: 3,
+ turns: {},
+ inputs: {},
+ calls: {},
+ tasks: {},
+ authorizations: {},
+ candidates: {},
+ },
+ "eve.harness.turnState": { grants: ["deploy:api"], suspended: [] },
+ },
+ },
+ },
+ },
+ },
+ });
+ if (result.kind !== "current") throw new Error(result.detail);
+ expect(result.checkpoint.sessionState).not.toHaveProperty("emissionState");
+ expect(result.checkpoint.sessionState.snapshot.session.state).not.toHaveProperty(
+ "eve.harness.emission",
+ );
+ expect(result.checkpoint.sessionState.snapshot.session.state).not.toHaveProperty(
+ "eve.runtime.hitl.approvedTools",
+ );
+ });
+
+ it.each([
+ { "eve.runtime.pendingInputBatches": [{ requests: [] }] },
+ { "eve.runtime.pendingAuthorization": { challenges: [{}] } },
+ { "eve.runtime.pendingCoordinationBatch": { tasks: [] } },
+ { "eve.runtime.deferredStepInput": { message: "Bob asks for a follow-up." } },
+ { "eve.runtime.proxyInputRequests": { child: {} } },
+ {
+ "eve.harness.emission": { sessionStarted: true, sequence: 1, stepIndex: 0, turnId: "turn_1" },
+ },
+ { "eve.runtime.pendingInputBatches": "malformed" },
+ { "eve.runtime.hitl.approvedTools": [7] },
+ { "eve.runtime.hitl.approvalState": { activeCandidates: { alice: {} } } },
+ {
+ "eve.workflowTool": {
+ version: 4,
+ runs: [
+ {
+ callId: "call",
+ toolName: "report",
+ origin: { turnId: "turn_0", stepIndex: 0 },
+ address: { runId: "run", hookToken: "hook" },
+ },
+ ],
+ },
+ },
+ ])(
+ "refuses v11 pending or malformed state without changing the owner's checkpoint (%j)",
+ (state) => {
+ const checkpoint = v11Checkpoint(state);
+ const before = structuredClone(checkpoint);
+ expect(migrateSessionCheckpoint(checkpoint)).toMatchObject({ kind: "incompatible" });
+ expect(checkpoint).toEqual(before);
+ },
+ );
+
it.each([7, SESSION_CHECKPOINT_VERSION + 1])("refuses checkpoint version %s", (version) => {
expect(migrateSessionCheckpoint({ ...eve066Checkpoint(), version })).toMatchObject({
kind: "incompatible",
@@ -69,6 +161,23 @@ describe("migrateSessionCheckpoint", () => {
});
});
+function v11Checkpoint(state: Record<string, unknown>) {
+ return {
+ version: 11,
+ serializedContext: {},
+ history: [{ role: "user", kind: "user", content: "Alice asks for a report." }],
+ sessionTimeoutMs: false,
+ sessionState: {
+ version: 2,
+ sessionId: "session-1",
+ continuationToken: "token",
+ hasProxyInputRequests: false,
+ emissionState: { sessionStarted: true, sequence: 3, stepIndex: 0, turnId: "" },
+ snapshot: { session: { sessionId: "session-1", continuationToken: "token", state } },
+ },
+ };
+}
+
const CALLBACK = {
callId: "call-0",
subagentName: "research",
diff --git a/packages/eve/src/execution/session/checkpoint-migrations.ts b/packages/eve/src/execution/session/checkpoint-migrations.ts
index 5af9569bb..f1282fefc 100644
--- a/packages/eve/src/execution/session/checkpoint-migrations.ts
+++ b/packages/eve/src/execution/session/checkpoint-migrations.ts
@@ -1,5 +1,7 @@
import { SESSION_CHECKPOINT_VERSION, type SessionCheckpoint } from "#execution/session/handoff.js";
import { isObject } from "#shared/guards.js";
+import { initialSessionProjection } from "#protocol/session-projection.js";
+import { getBlockingWorkflowToolRuns } from "#harness/workflow-tool-runs.js";
/**
* Oldest checkpoint a successor upgrades (eve 0.66.0). Earlier checkpoints
@@ -87,6 +89,8 @@ const CHECKPOINT_UPGRADES: Readonly<
sessionState: { ...sessionState, snapshot: { ...snapshot, session }, version: 2 },
};
},
+ // Lifecycle moved from emission/batch registries to the projection and TurnState.
+ 11: upgradeIdleLifecycle,
};
/**
@@ -127,6 +131,88 @@ export function migrateSessionCheckpoint(checkpoint: unknown): SessionCheckpoint
return { kind: "current", checkpoint: current, childRunIdsToStop: effects.childRunIdsToStop };
}
+function upgradeIdleLifecycle(checkpoint: CheckpointRecord): CheckpointRecord {
+ const sessionState = readRecord(checkpoint, "sessionState");
+ if (sessionState.version !== 2) refuse("durable session version is not 2");
+ const snapshot = readRecord(sessionState, "snapshot");
+ const session = readRecord(snapshot, "session");
+ const state = session.state === undefined ? {} : readRecord(session, "state");
+ const emission = state["eve.harness.emission"] ?? sessionState.emissionState;
+ if (
+ !isObject(emission) ||
+ typeof emission.sessionStarted !== "boolean" ||
+ !Number.isSafeInteger(emission.sequence) ||
+ (emission.sequence as number) < 0 ||
+ !Number.isSafeInteger(emission.stepIndex) ||
+ (emission.stepIndex as number) < 0 ||
+ emission.turnId !== ""
+ )
+ refuse("lifecycle position is malformed or a turn is still open");
+
+ const retiredPendingKeys = [
+ "eve.runtime.pendingAuthorization",
+ "eve.runtime.pendingInputBatch",
+ "eve.runtime.pendingCoordinationBatch",
+ "eve.runtime.deferredStepInput",
+ "eve.harness.pendingWorkflowInterrupt",
+ ];
+ if (retiredPendingKeys.some((key) => state[key] !== undefined))
+ refuse("session holds pending work");
+ const batches = state["eve.runtime.pendingInputBatches"];
+ if (batches !== undefined && (!Array.isArray(batches) || batches.length > 0))
+ refuse("session holds pending input");
+ const routes = state["eve.runtime.proxyInputRequests"];
+ if (
+ sessionState.hasProxyInputRequests !== false ||
+ (routes !== undefined && (!isObject(routes) || Object.keys(routes).length > 0))
+ )
+ refuse("session holds relayed input");
+ try {
+ if (getBlockingWorkflowToolRuns(state).length > 0) refuse("session holds workflow runs");
+ } catch (error) {
+ if (error instanceof CheckpointRefusal) throw error;
+ refuse("workflow tool run registry is incompatible");
+ }
+ const approvals = state["eve.runtime.hitl.approvalState"];
+ if (
+ approvals !== undefined &&
+ (!isObject(approvals) ||
+ !isObject(approvals.activeCandidates) ||
+ Object.keys(approvals.activeCandidates).length > 0)
+ ) {
+ refuse("session holds approval candidates or malformed approval state");
+ }
+ const grants = state["eve.runtime.hitl.approvedTools"] ?? [];
+ if (!Array.isArray(grants) || !grants.every((grant) => typeof grant === "string"))
+ refuse("approval grants are malformed");
+ if (
+ state["eve.harness.turnState"] !== undefined ||
+ state["eve.harness.sessionProjection"] !== undefined
+ )
+ refuse("v11 checkpoint already contains machine state");
+ const projection = { ...initialSessionProjection(), nextSequence: emission.sequence as number };
+ if (emission.sessionStarted) projection.started = true;
+ const nextState: CheckpointRecord = {
+ ...omitKeys(state, [
+ "eve.harness.emission",
+ "eve.runtime.hitl.approvedTools",
+ "eve.runtime.pendingInputBatches",
+ "eve.runtime.proxyInputRequests",
+ ]),
+ "eve.harness.sessionProjection": projection,
+ };
+ if (grants.length > 0)
+ nextState["eve.harness.turnState"] = { grants: [...grants], suspended: [] };
+ const { emissionState: _emission, ...durable } = sessionState;
+ return {
+ ...checkpoint,
+ sessionState: {
+ ...durable,
+ snapshot: { ...snapshot, session: { ...session, state: nextState } },
+ },
+ };
+}
+
function isCurrentCheckpoint(value: unknown): value is SessionCheckpoint {
return (
isObject(value) &&
diff --git a/packages/eve/src/execution/session/entry-handoff.integration.test.ts b/packages/eve/src/execution/session/entry-handoff.integration.test.ts
index 992f95faa..f63220009 100644
--- a/packages/eve/src/execution/session/entry-handoff.integration.test.ts
+++ b/packages/eve/src/execution/session/entry-handoff.integration.test.ts
@@ -18,6 +18,7 @@ import {
} from "#execution/session-inbox/address.js";
import { createWorkflowRuntime, waitForCommandHookOwner } from "#execution/workflow-runtime.js";
import { buildSerializedContext, handoffFollowUp } from "#internal/testing/entry-test-helpers.js";
+import { SESSION_PROJECTION_STATE_KEY, storedProjection } from "#harness/session-machine/view.js";
import { captureConsoleOutput, workflowSdkNotice } from "#internal/testing/log-records.js";
const HANDOFF_LOG = "[eve:execution.handoff]";
@@ -60,18 +61,13 @@ describe("workflowEntry integration", () => {
candidateId = runId;
const session = args[0].checkpoint.sessionState.snapshot.session;
Object.assign(session, {
+ // Input the source still holds is pending work the target refuses.
state: {
...session.state,
- "eve.workflowTool": {
- version: 4,
- runs: [
- {
- callId: "call",
- toolName: "research",
- origin: { turnId: "turn", stepIndex: 0 },
- address: { runId: "run", hookToken: 42 },
- },
- ],
+ "eve.harness.turnState": {
+ grants: [],
+ queued: { message: "Alice asks for a summary." },
+ suspended: [],
},
},
});
@@ -724,6 +720,25 @@ describe("workflowEntry integration", () => {
});
/** The handoff input an eve 0.66 owner sends, per a captured checkpoint version 8. */
+/** The idle session's lifecycle as an eve 0.66 owner kept it: an emission position. */
+function eve066LifecycleState(state: Record<string, unknown> | undefined) {
+ const projection = storedProjection(state);
+ const {
+ [SESSION_PROJECTION_STATE_KEY]: _projection,
+ "eve.harness.turnState": _turnState,
+ ...rest
+ } = state ?? {};
+ return {
+ ...rest,
+ "eve.harness.emission": {
+ sequence: projection.nextSequence,
+ sessionStarted: projection.started === true,
+ stepIndex: 0,
+ turnId: "",
+ },
+ };
+}
+
function toEve066HandoffInput(input: HandoffWorkflowEntryInput): unknown {
const { checkpoint, handoffVersion: _handoffVersion, ...fields } = input;
const { history, serializedContext, sessionState, ...checkpointFields } = checkpoint;
@@ -746,7 +761,7 @@ function toEve066HandoffInput(input: HandoffWorkflowEntryInput): unknown {
...sessionState.snapshot.session,
history,
state: {
- ...sessionState.snapshot.session.state,
+ ...eve066LifecycleState(sessionState.snapshot.session.state),
// A finished subagent the old owner kept resumable; its run no longer exists.
"eve.agent.handles": {
handles: [
diff --git a/packages/eve/src/execution/session/entry.integration.test.ts b/packages/eve/src/execution/session/entry.integration.test.ts
index e4f1ea542..b5b1d2734 100644
--- a/packages/eve/src/execution/session/entry.integration.test.ts
+++ b/packages/eve/src/execution/session/entry.integration.test.ts
@@ -943,6 +943,31 @@ describe("workflowEntry integration", () => {
);
}, 60_000);
+ it("reads a message in the first step after its approval turn is cancelled", async () => {
+ const executions: string[] = [];
+ await withHeldApprovalRun(
+ {
+ agent: { name: "workflow-entry-cancelled-approval-follow-up" },
+ modules: [gatedTool("approve_change", executions)],
+ },
+ async ({ commandInbox, sessionInbox, stream }) => {
+ await withTimeout(stream.nextTurn(), "approval turn");
+ await resumeHook(sessionInbox, { kind: "cancel" });
+ await withTimeout(stream.nextTurn(), "cancelled turn");
+
+ await resumeHook(commandInbox, {
+ kind: "send",
+ payload: { message: "Reply with the follow-up." },
+ });
+ const followUp = await withTimeout(stream.nextTurn(), "follow-up turn");
+ // The model reads the cancelled call's result and the message in one step.
+ expect(filterEventsByType(followUp, "step.started")).toHaveLength(1);
+ expect(filterEventsByType(followUp, "message.completed")).toHaveLength(1);
+ expect(executions).toEqual([]);
+ },
+ );
+ }, 60_000);
+
it("exits a competing continuation owner before its first turn", async () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-hook-owner" } });
const continuationToken = "http:workflow-entry-hook-owner";
diff --git a/packages/eve/src/execution/session/finalization.ts b/packages/eve/src/execution/session/finalization.ts
index 468d7fe70..ca5b56726 100644
--- a/packages/eve/src/execution/session/finalization.ts
+++ b/packages/eve/src/execution/session/finalization.ts
@@ -8,7 +8,7 @@ import type { TurnOutcome } from "#execution/session/turn-step-types.js";
import { normalizeSerializableError } from "#execution/workflow-errors.js";
import type { WorkflowEntryResult } from "#execution/session/entry-input.js";
import type { TokenUsage } from "#shared/token-usage.js";
-import { lastHarnessTurn } from "#harness/emission-state.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import { getSessionUsage, takeSessionUsageDelta } from "#harness/turn-tag-state.js";
import { notifyTurnCallerStep } from "#subagents/parent-notification.js";
@@ -49,7 +49,7 @@ export async function finalizeSession(
await emitTerminalSessionCompletionStep({
sessionWritable: context.sessionWritable,
serializedContext,
- turn: lastHarnessTurn(session?.state),
+ turn: lastPublishedTurn(session?.state),
usage,
});
} else if (outcome.kind === "failed") {
@@ -128,3 +128,12 @@ function settledResult(
return { isError: true, output: normalizeSerializableError(outcome.error), ...usage };
}
}
+
+function lastPublishedTurn(state: import("#harness/types.js").SessionStateMap | undefined) {
+ const turns = Object.values(storedProjection(state).turns);
+ const turn = turns.reduce<(typeof turns)[number] | undefined>(
+ (last, next) => (last === undefined || next.sequence > last.sequence ? next : last),
+ undefined,
+ );
+ return turn === undefined ? undefined : { id: turn.turnId, sequence: turn.sequence };
+}
diff --git a/packages/eve/src/execution/session/handoff-steps.test.ts b/packages/eve/src/execution/session/handoff-steps.test.ts
index 8527b8af4..83efe9017 100644
--- a/packages/eve/src/execution/session/handoff-steps.test.ts
+++ b/packages/eve/src/execution/session/handoff-steps.test.ts
@@ -156,7 +156,6 @@ function createCheckpoint(): SessionCheckpoint {
serializedContext: {},
sessionState: createTestSessionState({
continuationToken: "channel:current",
- emissionState: { sequence: 0, sessionStarted: true, stepIndex: 0, turnId: "turn_0" },
hasProxyInputRequests: false,
sessionId: "session-1",
}),
diff --git a/packages/eve/src/execution/session/handoff-steps.ts b/packages/eve/src/execution/session/handoff-steps.ts
index 96359ae75..1dba19c70 100644
--- a/packages/eve/src/execution/session/handoff-steps.ts
+++ b/packages/eve/src/execution/session/handoff-steps.ts
@@ -1,3 +1,5 @@
+import { queuedInput, storedProjection } from "#harness/session-machine/view.js";
+import { openInputs, openSignIns } from "#protocol/session-projection.js";
import { getBlockingWorkflowToolRuns } from "#harness/workflow-tool-runs.js";
import {
EntityConflictError,
@@ -22,8 +24,10 @@ import { isObject } from "#shared/guards.js";
const log = createLogger("execution.handoff");
/** Parses retained work with this deployment's code before deciding whether it can move. */
-export function isSessionStateIdleForHandoff(sessionState: DurableSessionState): boolean {
- const { state } = readDurableSession(sessionState);
+export function isSessionStateIdleForHandoff(input: {
+ readonly sessionState: DurableSessionState;
+}): boolean {
+ const { state } = readDurableSession(input.sessionState);
// Decoding the run registry rejects corrupt state before any busy-work shortcut.
const workflowToolRuns = getBlockingWorkflowToolRuns(state);
@@ -45,7 +49,14 @@ export function isSessionStateIdleForHandoff(sessionState: DurableSessionState):
(!isObject(proxyRequests) || Object.keys(proxyRequests).length > 0)
)
return false;
- return workflowToolRuns.length === 0;
+ const projection = storedProjection(state);
+ return (
+ workflowToolRuns.length === 0 &&
+ projection.activeTurnId === undefined &&
+ openInputs(projection).length === 0 &&
+ openSignIns(projection).length === 0 &&
+ queuedInput(state) === undefined
+ );
}
/** Reads durable work using the source deployment's handoff contract. */
@@ -53,7 +64,7 @@ export async function isSessionIdleForHandoffStep(input: {
readonly sessionState: DurableSessionState;
}): Promise<boolean> {
"use step";
- return isSessionStateIdleForHandoff(input.sessionState);
+ return isSessionStateIdleForHandoff(input);
}
export type SessionCheckpointValidation =
@@ -121,7 +132,7 @@ export async function validateSessionCheckpointStep(input: {
throw new Error("Session checkpoint sandbox provider state is incompatible.");
}
}
- if (!isSessionStateIdleForHandoff(checkpoint.sessionState)) {
+ if (!isSessionStateIdleForHandoff(checkpoint)) {
throw new Error("Session checkpoint contains pending work and cannot be handed off.");
}
return { kind: "valid" };
diff --git a/packages/eve/src/execution/session/handoff.test.ts b/packages/eve/src/execution/session/handoff.test.ts
index bf23f8d8f..6d44adcd9 100644
--- a/packages/eve/src/execution/session/handoff.test.ts
+++ b/packages/eve/src/execution/session/handoff.test.ts
@@ -2,7 +2,11 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import type { DeliverHookPayload } from "#channel/types.js";
import type { DurableSessionState } from "#execution/durable-session-store.js";
-import { SessionHandoff, type SessionOwnerActivation } from "#execution/session/handoff.js";
+import {
+ SESSION_CHECKPOINT_VERSION,
+ SessionHandoff,
+ type SessionOwnerActivation,
+} from "#execution/session/handoff.js";
import type { TurnSelection } from "#execution/session/input-queue.js";
import type { SessionInboxHandle, SessionInboxPayload } from "#execution/session-inbox/inbox.js";
@@ -50,7 +54,7 @@ describe("SessionHandoff", () => {
checkpoint: expect.objectContaining({
history,
sessionTimeoutMs: 60_000,
- version: 11,
+ version: SESSION_CHECKPOINT_VERSION,
}),
delivery: trigger.delivery,
targetDeploymentId: "deployment-b",
diff --git a/packages/eve/src/execution/session/handoff.ts b/packages/eve/src/execution/session/handoff.ts
index 7b2f0ca28..8ef45efc2 100644
--- a/packages/eve/src/execution/session/handoff.ts
+++ b/packages/eve/src/execution/session/handoff.ts
@@ -26,7 +26,7 @@ import { isObject } from "#shared/guards.js";
* A newer successor must always accept older checkpoints: every bump adds the
* upgrade from the previous version in `checkpoint-migrations.ts`.
*/
-export const SESSION_CHECKPOINT_VERSION = 11;
+export const SESSION_CHECKPOINT_VERSION = 12;
/** Everything a successor needs to continue an idle session. Hooks are derived from the state. */
export interface SessionCheckpoint {
diff --git a/packages/eve/src/execution/session/pending-turn-state.test.ts b/packages/eve/src/execution/session/pending-turn-state.test.ts
index 9f4c41ef7..073f946d8 100644
--- a/packages/eve/src/execution/session/pending-turn-state.test.ts
+++ b/packages/eve/src/execution/session/pending-turn-state.test.ts
@@ -1,7 +1,8 @@
import { describe, expect, it } from "vitest";
import type { ModelMessage } from "ai";
import { derivePendingState } from "#execution/session/pending-turn-state.js";
-import { setPendingCoordinationBatch } from "#harness/coordination.js";
+import { withParkedStep } from "#internal/testing/session-machine.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import type { HarnessSession } from "#harness/types.js";
import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
import { TASK_WAIT_TOOL_NAME } from "#protocol/task-tools.js";
@@ -31,24 +32,25 @@ const deployRun: RuntimeWorkflowTaskRequest = {
};
function parked(tasks: readonly RuntimeWorkflowTaskRequest[]): HarnessSession {
- return setPendingCoordinationBatch({
+ return withParkedStep(session, {
event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
- responseMessages: [waitCall],
- session,
+ messages: [waitCall],
tasks,
});
}
describe("derivePendingState", () => {
it("waits on a task tool call without dispatching anything", () => {
- expect(derivePendingState(parked([]))).toMatchObject({
+ expect(derivePendingState(parked([]), storedProjection(parked([]).state))).toMatchObject({
hasRunsToDispatch: false,
pendingCoordinationCallIds: ["wait-call"],
});
});
it("dispatches the workflow tool runs a batch holds beside its task tool calls", () => {
- expect(derivePendingState(parked([deployRun]))).toMatchObject({
+ expect(
+ derivePendingState(parked([deployRun]), storedProjection(parked([deployRun]).state)),
+ ).toMatchObject({
hasRunsToDispatch: true,
pendingCoordinationCallIds: ["deploy-call", "wait-call"],
});
diff --git a/packages/eve/src/execution/session/pending-turn-state.ts b/packages/eve/src/execution/session/pending-turn-state.ts
index 8f3bb51ef..6f4d61afe 100644
--- a/packages/eve/src/execution/session/pending-turn-state.ts
+++ b/packages/eve/src/execution/session/pending-turn-state.ts
@@ -1,11 +1,20 @@
import { getPendingAuthorization } from "#harness/authorization.js";
-import { hasPendingInputBatch } from "#harness/input-requests.js";
-import { getPendingCoordinationBatch, pendingCoordinationCallIds } from "#harness/coordination.js";
-import { pendingTaskToolCalls, type TaskToolCall } from "#execution/tasks/calls.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { ownOpenRequestIds } from "#harness/session-machine/transitions.js";
+import { runtimeWait } from "#harness/session-machine/view.js";
+import type { TaskToolCall } from "#execution/tasks/calls.js";
import type { HarnessSession } from "#harness/types.js";
+import { openSignIns, type SessionProjection } from "#protocol/session-projection.js";
-/** Derives the workflow fields used to select the next action at the park boundary. */
-export function derivePendingState(session: HarnessSession): {
+/**
+ * Derives the workflow fields used to select the next action at the park boundary. Whether the
+ * session awaits input or a sign-in is the projection's; which callbacks resume it, and which
+ * calls wait on the runtime, is execution state.
+ */
+export function derivePendingState(
+ session: HarnessSession,
+ projection: SessionProjection,
+): {
readonly authorizationAttemptIds?: readonly string[];
readonly hasPendingAuthorization: boolean;
readonly hasPendingInputBatch: boolean;
@@ -14,20 +23,20 @@ export function derivePendingState(session: HarnessSession): {
readonly pendingCoordinationCallIds?: readonly string[];
readonly pendingTaskToolCalls?: readonly TaskToolCall[];
} {
- const batch = getPendingCoordinationBatch(session.state);
const pendingAuth = getPendingAuthorization(session.state);
const base = {
authorizationAttemptIds: pendingAuth?.challenges.flatMap((challenge) =>
challenge.attemptId === undefined ? [] : [challenge.attemptId],
),
- hasPendingAuthorization: pendingAuth !== undefined,
- hasPendingInputBatch: hasPendingInputBatch(session.state),
+ hasPendingAuthorization: openSignIns(projection).length > 0,
+ hasPendingInputBatch: ownOpenRequestIds(sessionView(projection, session.state)).size > 0,
};
- if (batch === undefined) return base;
+ const waiting = runtimeWait(session.state);
+ if (waiting === undefined) return base;
return {
...base,
- hasRunsToDispatch: batch.tasks.length > 0,
- pendingCoordinationCallIds: pendingCoordinationCallIds(batch),
- pendingTaskToolCalls: pendingTaskToolCalls(batch.responseMessages),
+ hasRunsToDispatch: waiting.tasks.length > 0,
+ pendingCoordinationCallIds: waiting.callIds,
+ pendingTaskToolCalls: waiting.taskToolCalls,
};
}
diff --git a/packages/eve/src/execution/session/state-compatibility.test.ts b/packages/eve/src/execution/session/state-compatibility.test.ts
index bcfcdaf03..b7aefac3d 100644
--- a/packages/eve/src/execution/session/state-compatibility.test.ts
+++ b/packages/eve/src/execution/session/state-compatibility.test.ts
@@ -1,61 +1,82 @@
import { describe, expect, it } from "vitest";
-import { createTestSessionState } from "#internal/testing/session-state.js";
+
import { isSessionStateIdleForHandoff } from "#execution/session/handoff-steps.js";
+import { createTestSessionState } from "#internal/testing/session-state.js";
+import {
+ positionState,
+ withPublished,
+ withQueuedInput,
+} from "#internal/testing/session-machine.js";
+import type { HarnessSession } from "#harness/types.js";
+import { createAuthorizationRequiredEvent, createInputRequestedEvent } from "#protocol/message.js";
-const run = {
- callId: "call",
- toolName: "research",
- origin: { turnId: "turn", stepIndex: 0 },
- address: { runId: "run", hookToken: "inbox" },
-};
+// A session hands off only with nothing open, whatever kind of work it is: the projection
+// reports every open turn, request, and sign-in, and execution state holds queued input.
-function checkpoint(state: Record<string, unknown>) {
+function checkpoint(session: Pick<HarnessSession, "state">) {
const value = createTestSessionState();
- return { ...value, snapshot: { session: { ...value.snapshot.session, state } } };
+ return {
+ serializedContext: {},
+ sessionState: {
+ ...value,
+ snapshot: { session: { ...value.snapshot.session, state: session.state } },
+ },
+ };
}
+function betweenTurns(): HarnessSession {
+ return {
+ agent: { dynamicModel: true, system: "", tools: [] },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "test-token",
+ history: [],
+ sessionId: "test-session",
+ state: { ...positionState({ sequence: 1, turnId: "" }), authored: { values: [null, false] } },
+ };
+}
+
+const at = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+
describe("handoff state inspection", () => {
- it("accepts additive framework metadata and opaque authored state", () => {
- expect(
- isSessionStateIdleForHandoff(
- checkpoint({
- authored: { version: "anything", values: [null, false] },
- }),
- ),
- ).toBe(true);
+ it("accepts a session between turns with opaque authored state", () => {
+ expect(isSessionStateIdleForHandoff(checkpoint(betweenTurns()))).toBe(true);
});
- it("parses workflow tool runs before checking for waiting work", () => {
- const incompatible = { ...run, address: { ...run.address, hookToken: 42 } };
- expect(() =>
- isSessionStateIdleForHandoff(
- checkpoint({
- "eve.workflowTool": { version: 4, runs: [incompatible] },
- }),
- ),
- ).toThrow("Corrupt workflow tool run registry");
+
+ it("refuses an open turn", () => {
+ expect(isSessionStateIdleForHandoff(checkpoint({ state: positionState(at) }))).toBe(false);
});
- it("does not skip run parsing when another registry is busy", () => {
- expect(() =>
- isSessionStateIdleForHandoff(
- checkpoint({
- "eve.runtime.pendingAuthorization": {},
- "eve.workflowTool": {
- version: 4,
- runs: [{ ...run, address: { ...run.address, runId: null } }],
+
+ it("refuses an open request", () => {
+ const asked = withPublished(betweenTurns(), [
+ createInputRequestedEvent({
+ requests: [
+ {
+ action: { callId: "call-1", input: {}, kind: "tool-call", toolName: "deploy" },
+ kind: "tool-approval",
+ prompt: "Approve deploy?",
+ requestId: "approval-1",
},
- }),
- ),
- ).toThrow("Corrupt workflow tool run registry");
+ ],
+ ...at,
+ }),
+ ]);
+ expect(isSessionStateIdleForHandoff(checkpoint(asked))).toBe(false);
});
- it.each([
- ["eve.runtime.pendingAuthorization", false],
- ["eve.runtime.pendingInputBatch", {}],
- ["eve.runtime.pendingInputBatches", [null]],
- ["eve.runtime.pendingCoordinationBatch", {}],
- ["eve.runtime.deferredStepInput", {}],
- ["eve.harness.pendingWorkflowInterrupt", {}],
- ["eve.runtime.proxyInputRequests", { malformed: null }],
- ])("refuses nonempty or unreadable pending work in %s", (key, value) => {
- expect(isSessionStateIdleForHandoff(checkpoint({ [key]: value }))).toBe(false);
+
+ it("refuses an open sign-in", () => {
+ const asked = withPublished(betweenTurns(), [
+ createAuthorizationRequiredEvent({
+ attemptId: "attempt-1",
+ description: "Sign in to Linear",
+ name: "linear",
+ ...at,
+ }),
+ ]);
+ expect(isSessionStateIdleForHandoff(checkpoint(asked))).toBe(false);
+ });
+
+ it("refuses input the session holds until it can run", () => {
+ const queued = withQueuedInput(betweenTurns(), { message: "Alice asks for a summary." });
+ expect(isSessionStateIdleForHandoff(checkpoint(queued))).toBe(false);
});
});
diff --git a/packages/eve/src/execution/session/state-cursor.test.ts b/packages/eve/src/execution/session/state-cursor.test.ts
index 2fd8dd496..1edae58d3 100644
--- a/packages/eve/src/execution/session/state-cursor.test.ts
+++ b/packages/eve/src/execution/session/state-cursor.test.ts
@@ -143,7 +143,6 @@ describe("SessionStateCursor", () => {
function state(continuationToken: string): DurableSessionState {
return createTestSessionState({
continuationToken,
- emissionState: { sequence: 0, sessionStarted: true, stepIndex: 0, turnId: "turn_0" },
hasProxyInputRequests: false,
sessionId: "session-1",
});
diff --git a/packages/eve/src/execution/session/terminal-session-completed-channel.test.ts b/packages/eve/src/execution/session/terminal-session-completed-channel.test.ts
index fe93de184..b727e5891 100644
--- a/packages/eve/src/execution/session/terminal-session-completed-channel.test.ts
+++ b/packages/eve/src/execution/session/terminal-session-completed-channel.test.ts
@@ -14,7 +14,7 @@ import { SessionIdKey } from "#context/keys.js";
import { deserializeContext } from "#context/serialize.js";
import { createDurableSessionState } from "#execution/durable-session-store.js";
import { finalizeSession } from "#execution/session/finalization.js";
-import { setHarnessEmissionState } from "#harness/emission-state.js";
+import { withOpenTurn } from "#internal/testing/session-machine.js";
import { POST, defineChannel } from "#public/definitions/channel.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
@@ -43,7 +43,7 @@ it("delivers session.completed to the channel handler when a session expires bet
vi.mocked(deserializeContext).mockResolvedValue(restored);
// `turn_3` completed: its epilogue cleared the turn id and advanced the sequence to 4.
- const session = setHarnessEmissionState(
+ const session = withOpenTurn(
{
agent: { modelReference: { id: "unused" }, system: "", tools: [] },
compaction: { recentWindowSize: 10, threshold: 100_000 },
@@ -51,7 +51,7 @@ it("delivers session.completed to the channel handler when a session expires bet
history: [],
sessionId: SESSION_ID,
},
- { sessionStarted: true, sequence: 4, stepIndex: 0, turnId: "" },
+ { sequence: 3, stepIndex: 0, turnId: "turn_3" },
);
const written: string[] = [];
diff --git a/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts b/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts
index 6fa7328f0..f79246a70 100644
--- a/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts
+++ b/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts
@@ -14,11 +14,11 @@ import type { DurableStepResult, TurnStepPayload } from "#execution/session/turn
import {
getApprovalAuditState,
markApprovalCandidateAuthorizationRequired,
-} from "#harness/approval-candidates.js";
+} from "#harness/hitl/candidates.js";
import { CallbackBaseUrlKey, setPendingAuthorization } from "#harness/authorization.js";
import { ConnectionAuthorizationRequiredError } from "#connections/errors.js";
import { defineInteractiveAuthorization } from "#shared/connection-types.js";
-import { getPendingInputBatches } from "#harness/pending-input-batches.js";
+import { suspendedSteps } from "#harness/session-machine/view.js";
import type { HarnessSession } from "#harness/types.js";
import { defineOpenAPIConnection } from "#public/definitions/connections/openapi.js";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
@@ -380,7 +380,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's notes." }] },
});
const parked = await fixture.step();
- const requests = getPendingInputBatches(readDurableSession(parked.sessionState).state).flatMap(
+ const requests = suspendedSteps(readDurableSession(parked.sessionState).state).flatMap(
(batch) => batch.requests,
);
await fixture.step({
@@ -418,8 +418,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's note." }] },
});
const parked = await fixture.step();
- const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
- .requests[0]!;
+ const request = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!.requests[0]!;
fixture.removeConnection();
await fixture.step({
delivery: {
@@ -450,8 +449,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's note." }] },
});
const parked = await fixture.step();
- const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
- .requests[0]!;
+ const request = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!.requests[0]!;
fixture.removeConnection();
await fixture.step({
delivery: {
@@ -465,7 +463,7 @@ describe("turn connection approval restoration", () => {
expect(fixture.response).not.toHaveBeenCalled();
expect(fixture.fetch).not.toHaveBeenCalled();
const state = readDurableSession(refused.sessionState).state;
- expect(getPendingInputBatches(state)[0]!.requests[0]!.requestId).toBe(request.requestId);
+ expect(suspendedSteps(state)[0]!.requests[0]!.requestId).toBe(request.requestId);
expect(getApprovalAuditState(state).candidateHistory).toEqual([
expect.objectContaining({
status: "rejected",
@@ -495,8 +493,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's note for Bob." }] },
});
const parked = await fixture.step();
- const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
- .requests[0]!;
+ const request = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!.requests[0]!;
const signInStart = fixture.events.length;
await fixture.step({
@@ -554,7 +551,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's note for Bob." }] },
});
const parked = await fixture.step();
- const batch = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!;
+ const batch = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!;
const request = batch.requests[0]!;
const ingested = await fixture.step({
delivery: {
@@ -602,11 +599,10 @@ describe("turn connection approval restoration", () => {
],
},
});
- expect(fixture.policyTurns).toEqual([batch.event!.turnId]);
+ expect(fixture.policyTurns).toEqual([batch.event.turnId]);
expect(fixture.response).toHaveBeenCalledOnce();
expect(fixture.fetch).toHaveBeenCalledOnce();
- // The approval held its turn, so the responder's sign-in resumes it
- // without starting another.
+ // The approval held its turn, so the responder's sign-in resumes it without starting another.
const events = fixture.events.slice(start);
expect(events.some((event) => event.type === "authorization.completed")).toBe(true);
expect(events.filter((event) => event.type === "turn.started")).toHaveLength(0);
@@ -620,7 +616,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Save hello in notes." }] },
});
const parked = await fixture.step();
- const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
+ const request = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!
.requests[0]!;
expect(request.action.toolName).toBe("connection_execute");
expect(request.prompt).toBe("Approve Notes: Save note?");
@@ -652,9 +648,8 @@ describe("turn connection approval restoration", () => {
expect(fixture.fetch).toHaveBeenCalledOnce();
// Bob approved Alice's call, so the approved request goes out as Bob.
expect(callerHeader(fixture.fetch.mock.calls[0])).toBe("bob");
- expect(getPendingInputBatches(readDurableSession(resumed.sessionState).state)).toEqual([]);
+ expect(suspendedSteps(readDurableSession(resumed.sessionState).state)).toEqual([]);
expect(resumed.serializedContext).not.toHaveProperty("eve.pendingConnectionCalls");
- // The approval held its turn, so approving it resumes the same turn.
expect(fixture.events.filter((event) => event.type === "turn.started")).toHaveLength(1);
// The connection call is reported as a nested action of the approved call.
const nestedCallId = `${request.action.callId}:1`;
@@ -699,8 +694,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Save hello in notes." }] },
});
const parked = await fixture.step();
- const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
- .requests[0]!;
+ const request = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!.requests[0]!;
await fixture.step({
delivery: {
kind: "deliver",
@@ -726,8 +720,7 @@ describe("turn connection approval restoration", () => {
delivery: { kind: "deliver", payloads: [{ message: "Save hello in notes." }] },
});
const parked = await fixture.step();
- const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
- .requests[0]!;
+ const request = suspendedSteps(readDurableSession(parked.sessionState).state)[0]!.requests[0]!;
await fixture.step({
delivery: {
kind: "deliver",
diff --git a/packages/eve/src/execution/session/turn-step-result.ts b/packages/eve/src/execution/session/turn-step-result.ts
index c32eef643..f18044c87 100644
--- a/packages/eve/src/execution/session/turn-step-result.ts
+++ b/packages/eve/src/execution/session/turn-step-result.ts
@@ -1,7 +1,9 @@
+import { storedProjection } from "#harness/session-machine/view.js";
import { createDurableSessionValues } from "#execution/durable-session-store.js";
import { derivePendingState } from "#execution/session/pending-turn-state.js";
import type { DurableStepResult } from "#execution/session/turn-step-types.js";
-import { getPendingInputBatches } from "#harness/pending-input-batches.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { ownOpenRequestIds } from "#harness/session-machine/transitions.js";
import { getTurnUsageState, takeSessionUsageDelta, toUsage } from "#harness/turn-tag-state.js";
import type { StepResult } from "#harness/types.js";
@@ -35,22 +37,21 @@ export function resolveSessionStepResult(
return { action: "held", hold: "tasks", ...values, taskIds: stepResult.held.taskIds };
}
if (stepResult.held?.kind === "request") {
- const pending = derivePendingState(stepResult.session);
+ const projection = storedProjection(stepResult.session.state);
+ const pending = derivePendingState(stepResult.session, projection);
return {
action: "held",
authorizationAttemptIds: pending.authorizationAttemptIds ?? [],
hasPendingInputBatch: pending.hasPendingInputBatch,
hold: "request",
- inputRequestIds: getPendingInputBatches(stepResult.session.state).flatMap((batch) =>
- batch.requests.map((request) => request.requestId),
- ),
+ inputRequestIds: [...ownOpenRequestIds(sessionView(projection, stepResult.session.state))],
...values,
};
}
if (stepResult.next === null) {
const { hasRunsToDispatch, pendingCoordinationCallIds, pendingTaskToolCalls } =
- derivePendingState(stepResult.session);
+ derivePendingState(stepResult.session, storedProjection(stepResult.session.state));
const pending = { hasRunsToDispatch, pendingCoordinationCallIds, pendingTaskToolCalls };
// Usage stays unreported until the turn settles, so the caller's result includes all of it.
diff --git a/packages/eve/src/execution/session/turn-step.test.ts b/packages/eve/src/execution/session/turn-step.test.ts
index b933a9964..637ea8e91 100644
--- a/packages/eve/src/execution/session/turn-step.test.ts
+++ b/packages/eve/src/execution/session/turn-step.test.ts
@@ -1,4 +1,3 @@
-import { TEST_USAGE } from "#internal/testing/events.js";
import { createTestSessionState } from "#internal/testing/session-state.js";
import type { ModelMessage } from "ai";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -16,7 +15,6 @@ import {
ContinuationHookTokensKey,
ContinuationTokenKey,
DynamicSubagentAgentConfigKey,
- InitiatorAuthKey,
SessionDynamicSubagentRuntimeRevisionKey,
SessionDynamicModelReferenceKey,
SessionDynamicToolMetadataKey,
@@ -32,13 +30,16 @@ import {
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import { startWorkflowTask } from "#execution/tools/workflow/start.js";
-import { getPendingCoordinationBatch, setPendingCoordinationBatch } from "#harness/coordination.js";
import { TurnCancelledError } from "#harness/turn-cancellation.js";
-import { setHarnessEmissionState } from "#harness/emission-state.js";
import { getPendingAuthorization, setPendingAuthorization } from "#harness/authorization.js";
import { upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
-import { appendPendingInputBatch } from "#harness/input-requests.js";
-import { queueDeferredStepInput } from "#harness/pending-input-batches.js";
+import {
+ positionOf,
+ positionState,
+ withOpenTurn,
+ withParkedStep,
+ withQueuedInput,
+} from "#internal/testing/session-machine.js";
import type { HarnessSession, StepFn, StepResult } from "#harness/types.js";
import { createRuntimeHookRegistry } from "#runtime/hooks/registry.js";
import {
@@ -53,20 +54,18 @@ import { setLogRecordSubscriber, type LogRecord } from "#internal/logging.js";
import type { HookContext } from "#public/definitions/hook.js";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
import {
- createDurableSessionState,
createDurableSessionValues,
type DurableSessionState,
readDurableSession,
} from "#execution/durable-session-store.js";
import { buildRuntimeIdentity, createExecutionNodeStep } from "#execution/node-step.js";
import { defineTool } from "#tools/definition.js";
-import { defineMemory } from "#public/memory/index.js";
import { defineState } from "#public/definitions/state.js";
import { stampDurableDynamicCallback } from "#tools/durable-callbacks.js";
-import { dispatchCoordinationStep } from "#execution/coordination-dispatch-step.js";
import { runProxySubagentEventStep } from "#subagents/event-proxy-step.js";
import { emitTerminalSessionFailureStep } from "#execution/terminal-session-failure-step.js";
import { turnStep as runTurnStep } from "#execution/session/turn-step.js";
+import { dispatchCoordinationStep } from "#execution/coordination-dispatch-step.js";
import type { TurnStepInput, TurnStepPayload } from "#execution/session/turn-step-types.js";
import type { DeliverHookPayload } from "#channel/types.js";
import type { RuntimeActionResult } from "#shared/action-types.js";
@@ -103,6 +102,7 @@ import {
} from "#execution/proxied-deliver-step.js";
import { captureLogRecords } from "#internal/testing/log-records.js";
import { runSessionStateStep } from "#internal/testing/session-state-step.js";
+import { TEST_USAGE } from "#internal/testing/events.js";
const REQUEST_EVENT = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
@@ -182,7 +182,6 @@ function installSessionStoreMocks(
function createStubSessionState(overrides: Partial<DurableSessionState> = {}): DurableSessionState {
return createTestSessionState({
continuationToken: "test-token",
- emissionState: { sequence: 0, sessionStarted: false, stepIndex: 0, turnId: "" },
hasProxyInputRequests: false,
sessionId: "sess-test",
...overrides,
@@ -763,7 +762,14 @@ describe("dispatchCoordinationStep", () => {
}
function pendingWorkflowTask(turnId: string): HarnessSession {
- return setPendingCoordinationBatch({
+ return withParkedStep(createStubSession(), {
+ event: { sequence: 3, stepIndex: 2, turnId },
+ messages: [
+ {
+ content: [{ input: {}, toolCallId: "call-1", toolName: "research", type: "tool-call" }],
+ role: "assistant",
+ },
+ ],
tasks: [
{
callId: "call-1",
@@ -775,32 +781,9 @@ describe("dispatchCoordinationStep", () => {
workflowId: "workflow//eve//research",
},
],
- event: { sequence: 3, stepIndex: 2, turnId },
- responseMessages: [],
- session: createStubSession(),
});
}
- it("repairs an empty pending turn id from the active session turn", async () => {
- mockCoordinationBundle();
- installSessionStoreMocks([pendingWorkflowTask("")]);
- const sessionState = createStubSessionState({
- emissionState: { sequence: 3, sessionStarted: true, stepIndex: 2, turnId: "" },
- });
-
- const result = await dispatchCoordinationStep({
- action: "park",
- workflowToolRunOwner: { inbox: "generated-owner-token" },
- sessionWritable: createTestWritable(),
- serializedContext: createSerializedContext(),
- sessionState,
- });
-
- const persisted = vi.mocked(createDurableSessionState).mock.calls.at(-1)?.[0].session;
- expect(result.stateDelta.sessionState).toBeDefined();
- expect(getPendingCoordinationBatch(persisted?.state)?.event.turnId).toBe("turn_3");
- });
-
it.each([
{ name: "a remote agent", traceRoot: { kind: "own" } as const, expected: "sess-test" },
{
@@ -825,9 +808,7 @@ describe("dispatchCoordinationStep", () => {
workflowToolRunOwner: { inbox: "generated-owner-token" },
sessionWritable: createTestWritable(),
serializedContext: serializeContext(ctx),
- sessionState: createStubSessionState({
- emissionState: { sequence: 3, sessionStarted: true, stepIndex: 2, turnId: "turn_3" },
- }),
+ sessionState: createStubSessionState(),
});
expect(vi.mocked(startWorkflowTask).mock.calls[0]?.[0].agentContext.traceRoot).toEqual({
@@ -861,10 +842,9 @@ describe("turnStep", () => {
adapterRegistry: { adaptersByKind: new Map([[adapter.kind, adapter]]) },
}) as never;
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);
- const emissionState = { sequence: 0, sessionStarted: true, stepIndex: 1, turnId: "turn_0" };
- const session = setHarnessEmissionState(
+ const session = withOpenTurn(
createStubSession({ history: [{ role: "user", kind: "user", content: "Original request" }] }),
- emissionState,
+ { sequence: 0, stepIndex: 1, turnId: "turn_0" },
);
installSessionStoreMocks([session]);
const execute = vi.fn(async (current: HarnessSession): Promise<StepResult> => {
@@ -899,12 +879,12 @@ describe("turnStep", () => {
},
sessionWritable: createTestWritable(),
serializedContext: serializeContext(ctx),
- sessionState: createStubSessionState({ emissionState }),
+ sessionState: createStubSessionState(),
});
expect(result).toMatchObject({ action: "done", output: "Original answer" });
expect(execute).toHaveBeenCalledOnce();
expect(execute.mock.calls[0]?.[0].history).toEqual(session.history);
- expect(result.sessionState.emissionState.turnId).toBe("turn_0");
+ expect(positionOf(result.sessionState.snapshot.session).turnId).toBe("turn_0");
expect(result.serializedContext[AuthKey.name]).toEqual(originalAuth);
expect(result.serializedContext[TurnDeliveryIdsKey.name]).toEqual(["original-delivery"]);
});
@@ -1041,22 +1021,30 @@ describe("turnStep", () => {
installSessionStoreMocks([createStubSession()]);
const continueStep: StepFn = async (session) => ({ next: null, session });
- const execute = vi.fn(async (session: HarnessSession): Promise<StepResult> => ({
- next: continueStep,
- session: appendPendingInputBatch({
- requests: [
- {
- action: { callId: "call-confirm", input: {}, kind: "tool-call", toolName: "confirm" },
- kind: "question",
- prompt: "Continue?",
- requestId: "request-confirm",
- },
- ],
- responseMessages: [],
- session,
- }),
- }));
- vi.mocked(createExecutionNodeStep).mockImplementation(() => execute);
+ let publish: ((event: UnstampedMessageStreamEvent) => Promise<void>) | undefined;
+ // The step asks, as a step does, by publishing the request.
+ const execute = vi.fn(async (session: HarnessSession): Promise<StepResult> => {
+ await publish?.(
+ createInputRequestedEvent({
+ requests: [
+ {
+ action: { callId: "call-confirm", input: {}, kind: "tool-call", toolName: "confirm" },
+ kind: "question",
+ prompt: "Continue?",
+ requestId: "request-confirm",
+ },
+ ],
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ }),
+ );
+ return { next: continueStep, session };
+ });
+ vi.mocked(createExecutionNodeStep).mockImplementation((input) => {
+ publish = input.handleEvent;
+ return execute;
+ });
const result = await turnStep({
input: { kind: "deliver", payloads: [{ message: "ask first" }] },
@@ -1072,12 +1060,7 @@ describe("turnStep", () => {
it("retains coalesced delivery ownership when a message steers the active turn", async () => {
const session = createStubSession({
state: {
- "eve.harness.emission": {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "turn_1",
- },
+ ...positionState({ sequence: 1, stepIndex: 0, turnId: "turn_1" }),
},
});
installSessionStoreMocks([session]);
@@ -1187,12 +1170,7 @@ describe("turnStep", () => {
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(compiledBundle);
const session = createStubSession({
state: {
- "eve.harness.emission": {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- },
+ ...positionState({ sequence: 1, stepIndex: 0, turnId: "" }),
},
});
installSessionStoreMocks([session]);
@@ -1229,14 +1207,7 @@ describe("turnStep", () => {
input: { kind: "deliver", payloads: [{ message: "next turn" }] },
sessionWritable: createTestWritable(),
serializedContext: serializeContext(ctx),
- sessionState: createStubSessionState({
- emissionState: {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- },
- }),
+ sessionState: createStubSessionState({}),
});
expect(handler).toHaveBeenCalledOnce();
@@ -1301,12 +1272,7 @@ describe("turnStep", () => {
{ content: "second", role: "assistant" },
],
state: {
- "eve.harness.emission": {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- },
+ ...positionState({ sequence: 1, stepIndex: 0, turnId: "" }),
},
});
installSessionStoreMocks([session]);
@@ -1336,14 +1302,7 @@ describe("turnStep", () => {
input: { kind: "deliver", payloads: [{ message: "follow up" }] },
sessionWritable: createTestWritable(),
serializedContext: serializeContext(ctx),
- sessionState: createStubSessionState({
- emissionState: {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- },
- }),
+ sessionState: createStubSessionState({}),
});
const expectedView = [
@@ -1520,122 +1479,6 @@ describe("turnStep", () => {
expect(observed).toEqual(expected);
});
- it.each([
- {
- current: {
- attributes: {},
- authenticator: "test",
- issuer: "test",
- principalId: "bob",
- principalType: "user",
- subject: "bob",
- } satisfies SessionAuthContext,
- title: "the follow-up caller",
- },
- { current: null, title: "an anonymous follow-up caller" },
- ])("keeps $title current when cancelled before the first model call", async ({ current }) => {
- installSessionStoreMocks([createStubSession()]);
- const alice: SessionAuthContext = {
- attributes: {},
- authenticator: "test",
- issuer: "test",
- principalId: "alice",
- principalType: "user",
- subject: "alice",
- };
- vi.mocked(createExecutionNodeStep).mockImplementation(() => async () => {
- throw new TurnCancelledError();
- });
-
- const result = await turnStep({
- input: {
- auth: current,
- kind: "deliver",
- payloads: [{ message: "follow up" }],
- deliveryMetadata: [
- { channelKind: "eve", channelName: "eve", deliveryId: "delivery-b", payloadIndex: 0 },
- ],
- },
- sessionWritable: createTestWritable(),
- serializedContext: {
- ...createSerializedContext(),
- [AuthKey.name]: alice,
- [InitiatorAuthKey.name]: alice,
- [TurnDeliveryIdsKey.name]: ["delivery-a"],
- },
- sessionState: createStubSessionState(),
- });
-
- expect(result.action).toBe("cancelled");
- expect(result.serializedContext).toMatchObject({
- [AuthKey.name]: current,
- [InitiatorAuthKey.name]: alice,
- [TurnDeliveryIdsKey.name]: ["delivery-b"],
- });
- });
-
- it("resumes a sign-in callback as the user who started it, not the last speaker", async () => {
- const alice: SessionAuthContext = {
- attributes: {},
- authenticator: "slack-webhook",
- issuer: "slack",
- principalId: "slack:alice",
- principalType: "user",
- };
- const bob: SessionAuthContext = { ...alice, principalId: "slack:bob" };
- installSessionStoreMocks([
- createStubSession({
- state: setPendingAuthorization(undefined, {
- challenges: [
- {
- attemptId: "attempt-linear",
- challenge: { url: "https://idp.example/authorize" },
- hookUrl: "https://agent.example/callback",
- name: "linear",
- principal: { id: "slack:alice", issuer: "slack", type: "user" },
- principalId: "slack:alice",
- requester: alice,
- },
- ],
- }),
- }),
- ]);
- const ctx = new ContextContainer();
- ctx.set(AuthKey, bob);
- ctx.set(BundleKey, createStubBundle());
- ctx.set(ChannelKey, threadContextAdapter);
- ctx.set(ContinuationTokenKey, "http:shared-thread");
- ctx.set(SessionIdKey, "session-1");
-
- let observed: SessionAuthContext | null | undefined;
- vi.mocked(createExecutionNodeStep).mockImplementation(() => {
- return async (session): Promise<StepResult> => {
- observed = loadContext().get(AuthKey);
- return { next: null, session };
- };
- });
-
- await turnStep({
- input: {
- kind: "deliver",
- payloads: [
- {
- authorizationCallback: {
- attemptId: "attempt-linear",
- callback: { method: "GET", params: { code: "oauth-code" } },
- connectionName: "linear",
- },
- },
- ],
- },
- sessionWritable: createTestWritable(),
- serializedContext: serializeContext(ctx),
- sessionState: createStubSessionState(),
- });
-
- expect(observed).toEqual(alice);
- });
-
it("keeps a session-scoped dynamic model selection when the first turn is cancelled", async () => {
const announcement = "Available skills\n- policy: Tenant policy";
const session = createStubSession({
@@ -2249,6 +2092,134 @@ describe("turnStep", () => {
});
});
+ it("resumes a sign-in callback as the user who started it, not the last speaker", async () => {
+ const alice: SessionAuthContext = {
+ attributes: {},
+ authenticator: "slack-webhook",
+ issuer: "slack",
+ principalId: "slack:alice",
+ principalType: "user",
+ };
+ const bob: SessionAuthContext = { ...alice, principalId: "slack:bob" };
+ installSessionStoreMocks([
+ createStubSession({
+ state: setPendingAuthorization(undefined, {
+ challenges: [
+ {
+ attemptId: "attempt-linear",
+ challenge: { url: "https://idp.example/authorize" },
+ hookUrl: "https://agent.example/callback",
+ name: "linear",
+ principal: { id: "slack:alice", issuer: "slack", type: "user" },
+ principalId: "slack:alice",
+ requester: alice,
+ },
+ ],
+ }),
+ }),
+ ]);
+ const ctx = new ContextContainer();
+ ctx.set(AuthKey, bob);
+ ctx.set(BundleKey, createStubBundle());
+ ctx.set(ChannelKey, threadContextAdapter);
+ ctx.set(ContinuationTokenKey, "http:shared-thread");
+ ctx.set(SessionIdKey, "session-1");
+
+ let observed: SessionAuthContext | null | undefined;
+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {
+ return async (session): Promise<StepResult> => {
+ observed = loadContext().get(AuthKey);
+ return { next: null, session };
+ };
+ });
+
+ await turnStep({
+ input: {
+ kind: "deliver",
+ payloads: [
+ {
+ authorizationCallback: {
+ attemptId: "attempt-linear",
+ callback: { method: "GET", params: { code: "oauth-code" } },
+ connectionName: "linear",
+ },
+ },
+ ],
+ },
+ sessionWritable: createTestWritable(),
+ serializedContext: serializeContext(ctx),
+ sessionState: createStubSessionState(),
+ });
+
+ expect(observed).toEqual(alice);
+ });
+
+ it.each([
+ {
+ name: "authorization",
+ withPending: (session: HarnessSession): HarnessSession => ({
+ ...session,
+ state: setPendingAuthorization(session.state, {
+ challenges: [
+ {
+ attemptId: "attempt-statuspage",
+ challenge: {
+ instructions: "Sign in to continue",
+ url: "https://idp.example/authorize",
+ },
+ hookUrl: "https://app.example/callback",
+ name: "statuspage",
+ principal: { type: "app" },
+ },
+ ],
+ }),
+ }),
+ },
+ {
+ name: "input batch",
+ withPending: (session: HarnessSession): HarnessSession =>
+ withParkedStep(session, {
+ requests: [
+ {
+ action: {
+ callId: "call-input",
+ input: {},
+ kind: "tool-call",
+ toolName: "confirm",
+ },
+ kind: "question",
+ prompt: "Continue?",
+ requestId: "request-input",
+ },
+ ],
+ }),
+ },
+ ])("does not infer settled output from a pending $name", async ({ withPending }) => {
+ const session = createStubSession();
+ installSessionStoreMocks([session]);
+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {
+ return async (stepSession): Promise<StepResult> => ({
+ next: null,
+ session: withPending(stepSession),
+ });
+ });
+
+ const result = await turnStep({
+ input: {
+ kind: "deliver",
+ payloads: [{ message: "hello" }],
+ },
+ sessionWritable: createTestWritable(),
+ serializedContext: createSerializedContext(),
+ sessionState: createStubSessionState(),
+ });
+
+ expect(result.action).toBe("park");
+ if (result.action === "park") {
+ expect(result.settled).toBeUndefined();
+ }
+ });
+
it("reads the durable session from normalized turn-step input", async () => {
const session = createStubSession({
continuationToken: "http:turn-step",
@@ -2573,12 +2544,7 @@ describe("turnStep", () => {
const session = createStubSession({
state: {
- "eve.harness.emission": {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- },
+ ...positionState({ sequence: 1, stepIndex: 0, turnId: "" }),
},
});
installSessionStoreMocks([session]);
@@ -2610,14 +2576,7 @@ describe("turnStep", () => {
},
sessionWritable: createTestWritable(),
serializedContext: serializeContext(ctx),
- sessionState: createStubSessionState({
- emissionState: {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- },
- }),
+ sessionState: createStubSessionState({}),
});
expect(handler).toHaveBeenCalledOnce();
@@ -2633,186 +2592,98 @@ describe("turnStep", () => {
]);
});
- it.each([
- [false, "none"],
- [true, "none"],
- [false, "current"],
- [true, "current"],
- [false, "deferred"],
- [true, "deferred"],
- ] as const)("auth resume (%s, %s)", async (withMemory, inputKind) => {
- const challenge = {
- attemptId: "attempt-statuspage",
- challenge: {
- instructions: "Sign in to continue",
- url: "https://idp.example/authorize",
- },
- hookUrl: "https://app.example/eve/v1/connections/statuspage/callback/sess-test:auth",
- name: "statuspage",
- principal: { type: "app" } as const,
- resume: { nonce: "n1" },
- };
- const hidden = {
- content: "HIDE_FROM_AUTH_CONTINUATION",
- kind: "user" as const,
- role: "user" as const,
- };
- mockIdentityHistoryViewProjector.mockImplementation(({ messages }) =>
- messages.filter((message) => message !== hidden),
- );
- const instructionHandler = vi.fn(
- (_event: unknown, _context: { readonly messages: readonly ModelMessage[] }) => null,
- );
- const toolHandler = vi.fn(
- (_event: unknown, _context: { readonly messages: readonly ModelMessage[] }) => null,
- );
- const recall = vi.fn(async () => ({
- messages: [{ content: "Recalled context", id: "item" }],
- }));
- const memories = withMemory
- ? [
- {
- ...defineMemory({
- namespace: "test",
- scope: "alice",
- provider: { recall: { "turn.started": recall } },
- }),
- logicalPath: "memory/profile.ts",
- slot: "profile",
- sourceId: "memory/profile.ts",
- sourceKind: "module",
- visibility: "scope",
- },
- ]
- : [];
- const session = createStubSession({
- history: [{ content: "visible", kind: "user", role: "user" }, hidden],
- state: setPendingAuthorization({ retained: "yes" }, { challenges: [challenge] }),
- });
- const turnInput = {
- context: ["Current context"],
- message: "Alice follows up after signing in.",
- };
- installSessionStoreMocks([
- inputKind === "deferred" ? queueDeferredStepInput(session, turnInput) : session,
- ]);
- vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
- adapterRegistry: {
- adaptersByKind: new Map([[threadContextAdapter.kind, threadContextAdapter]]),
- },
- compiledArtifactsSource: {} as never,
- graph: {
- nodesByNodeId: new Map(),
- root: {
- agent: { memories, connections: [] },
- sandboxRegistry: { sandbox: null },
- turnAgent: TestTurnAgent,
+ it.each(["none", "current", "deferred"] as const)(
+ "hands a completed sign-in to the harness (%s input)",
+ async (inputKind) => {
+ const challenge = {
+ attemptId: "attempt-statuspage",
+ challenge: {
+ instructions: "Sign in to continue",
+ url: "https://idp.example/authorize",
},
- },
- moduleMap: { nodes: {} },
- hookRegistry: createRuntimeHookRegistry([]),
- resolvedAgent: {
- config: {},
- dynamicToolResolvers: [
- {
- eventNames: ["turn.started"],
- events: { "turn.started": toolHandler },
- logicalPath: "tools/auth.ts",
- slug: "auth",
- sourceId: "tools/auth.ts",
- sourceKind: "module",
- },
- ],
- dynamicInstructionsResolvers: [
- {
- eventNames: ["session.started", "turn.started"],
- events: {
- "session.started": instructionHandler,
- "turn.started": instructionHandler,
- },
- logicalPath: "agent/instructions/auth.ts",
- slug: "auth",
- sourceId: "test:auth",
- sourceKind: "module",
+ hookUrl: "https://app.example/eve/v1/connections/statuspage/callback/sess-test:auth",
+ name: "statuspage",
+ principal: { type: "app" } as const,
+ resume: { nonce: "n1" },
+ };
+ const session = createStubSession({
+ history: [{ content: "visible", kind: "user", role: "user" }],
+ state: setPendingAuthorization({ retained: "yes" }, { challenges: [challenge] }),
+ });
+ const turnInput = {
+ context: ["Current context"],
+ message: "Alice follows up after signing in.",
+ };
+ installSessionStoreMocks([
+ inputKind === "deferred" ? withQueuedInput(session, turnInput) : session,
+ ]);
+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
+ adapterRegistry: {
+ adaptersByKind: new Map([[threadContextAdapter.kind, threadContextAdapter]]),
+ },
+ compiledArtifactsSource: {} as never,
+ graph: {
+ nodesByNodeId: new Map(),
+ root: {
+ agent: { connections: [] },
+ sandboxRegistry: { sandbox: null },
+ turnAgent: TestTurnAgent,
},
- ],
- },
- subagentRegistry: {},
- toolRegistry: {},
- turnAgent: TestTurnAgent,
- } as never);
+ },
+ moduleMap: { nodes: {} },
+ hookRegistry: createRuntimeHookRegistry([]),
+ resolvedAgent: { config: {} },
+ subagentRegistry: {},
+ toolRegistry: {},
+ turnAgent: TestTurnAgent,
+ } as never);
- let observedPendingAuth: unknown;
- let observedStepInput: unknown = "not-called";
- vi.mocked(createExecutionNodeStep).mockImplementation(() => {
- return async (session, stepInput): Promise<StepResult> => {
- observedPendingAuth = getPendingAuthorization(session.state);
- observedStepInput = stepInput;
- return { next: null, session };
- };
- });
+ let observedPendingAuth: unknown;
+ let observedStepInput: unknown = "not-called";
+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {
+ return async (session, stepInput): Promise<StepResult> => {
+ observedPendingAuth = getPendingAuthorization(session.state);
+ observedStepInput = stepInput;
+ return { next: null, session };
+ };
+ });
- const result = await turnStep({
- history: session.history,
- input: {
- kind: "deliver",
- payloads: [
- ...(inputKind === "current" ? [turnInput] : []),
- {
- authorizationCallback: {
- attemptId: "attempt-statuspage",
- callback: { code: "oauth-code" },
- connectionName: "statuspage",
+ const result = await turnStep({
+ history: session.history,
+ input: {
+ kind: "deliver",
+ payloads: [
+ ...(inputKind === "current" ? [turnInput] : []),
+ {
+ authorizationCallback: {
+ attemptId: "attempt-statuspage",
+ callback: { code: "oauth-code" },
+ connectionName: "statuspage",
+ },
},
- },
- ],
- },
- sessionWritable: createTestWritable(),
- serializedContext: createSerializedContext(),
- sessionState: createStubSessionState(),
- });
-
- expect(observedPendingAuth).toBeUndefined();
- expect(observedStepInput).toEqual(
- inputKind === "current" ? { message: `thread=unset; user=${turnInput.message}` } : undefined,
- );
- expect(result.action).toBe("park");
- const persistedSession = vi.mocked(createDurableSessionValues).mock.calls.at(-1)?.[0];
- expect(persistedSession?.state?.retained).toBe("yes");
- expect(getPendingAuthorization(persistedSession?.state)).toBeUndefined();
- expect(instructionHandler).toHaveBeenCalledTimes(2);
- for (const call of instructionHandler.mock.calls) {
- expect(call[1]).toMatchObject({
- messages: [{ content: "visible", kind: "user", role: "user" }],
+ ],
+ },
+ sessionWritable: createTestWritable(),
+ serializedContext: createSerializedContext(),
+ sessionState: createStubSessionState(),
});
- }
- expect(persistedSession?.history).toContain(hidden);
- const expectedInput =
- inputKind === "none"
- ? []
- : inputKind === "current"
- ? [{ content: `thread=unset; user=${turnInput.message}`, kind: "user", role: "user" }]
- : [
- { content: "Current context", kind: "context.instruction", role: "user" },
- { content: "Alice follows up after signing in.", kind: "user", role: "user" },
- ];
- expect(toolHandler).toHaveBeenCalledOnce();
- expect(toolHandler.mock.calls[0]?.[1].messages).toEqual([
- { content: "visible", kind: "user", role: "user" },
- ...(withMemory ? [{ content: "Recalled context", kind: "memory.load", role: "user" }] : []),
- ...expectedInput,
- ]);
- if (withMemory) {
- expect(recall).toHaveBeenCalledOnce();
- expect(recall).toHaveBeenCalledWith(
- expect.objectContaining({ turn: expect.objectContaining({ input: expectedInput }) }),
+
+ expect(observedPendingAuth).toBeUndefined();
+ expect(observedStepInput).toEqual(
+ inputKind === "current"
+ ? { message: `thread=unset; user=${turnInput.message}` }
+ : undefined,
);
- expect(
- persistedSession?.history.some((message) => message.content === "Recalled context"),
- ).toBe(true);
- expect(persistedSession?.state?.["eve.memory"]).toBeDefined();
- }
- });
+ expect(result).toMatchObject({ action: "park" });
+ // The harness completes the sign-in and resumes the turn it holds.
+ expect(vi.mocked(createExecutionNodeStep).mock.calls.at(-1)?.[0].signInCompletions).toEqual([
+ expect.objectContaining({ attemptId: "attempt-statuspage", name: "statuspage" }),
+ ]);
+ const persistedSession = vi.mocked(createDurableSessionValues).mock.calls.at(-1)?.[0];
+ expect(persistedSession?.state?.retained).toBe("yes");
+ expect(getPendingAuthorization(persistedSession?.state)).toBeUndefined();
+ },
+ );
});
describe("emitTerminalSessionFailureStep", () => {
@@ -2882,8 +2753,8 @@ describe("emitTerminalSessionFailureStep", () => {
const errorLog = vi.spyOn(console, "error").mockImplementation(() => {});
await emitTerminalSessionFailureStep({
- usage: TEST_USAGE,
error,
+ usage: TEST_USAGE,
sessionWritable: createTestWritable(),
serializedContext: serialized,
});
@@ -2932,8 +2803,8 @@ describe("emitTerminalSessionFailureStep", () => {
});
await emitTerminalSessionFailureStep({
- usage: TEST_USAGE,
error,
+ usage: TEST_USAGE,
sessionWritable: createTestWritable(),
serializedContext: serialized,
});
@@ -2981,8 +2852,8 @@ describe("emitTerminalSessionFailureStep", () => {
// a secondary failure during notification.
await expect(
emitTerminalSessionFailureStep({
- usage: TEST_USAGE,
error: new Error("inner"),
+ usage: TEST_USAGE,
sessionWritable: createTestWritable(),
serializedContext: serialized,
}),
@@ -3149,7 +3020,14 @@ describe("runProxySubagentEventStep", () => {
}
expect(order).toEqual(["channel", "hook"]);
expect(hook).toHaveBeenCalledExactlyOnceWith(
- expect.objectContaining({ type: "input.requested", data: hookPayload.event }),
+ // A relayed request names the call it serves.
+ expect.objectContaining({
+ type: "input.requested",
+ data:
+ delivery === "proxied"
+ ? { ...hookPayload.event, callId: hookPayload.callId }
+ : hookPayload.event,
+ }),
expect.objectContaining({ session: expect.objectContaining({ id: "parent-session" }) }),
);
},
@@ -3175,10 +3053,11 @@ describe("runProxySubagentEventStep", () => {
},
};
- const session: HarnessSession = createStubSession({
- continuationToken: "http:proxy-test",
- sessionId: "parent-session",
- });
+ // The parent's turn is open while its call waits on the child.
+ const session: HarnessSession = withOpenTurn(
+ createStubSession({ continuationToken: "http:proxy-test", sessionId: "parent-session" }),
+ { sequence: 0, stepIndex: 0, turnId: "turn_0" },
+ );
installSessionStoreMocks([session]);
const sessionState = createStubSessionState({
@@ -3247,10 +3126,11 @@ describe("runProxySubagentEventStep", () => {
},
};
- const session: HarnessSession = createStubSession({
- continuationToken: "http:proxy-test",
- sessionId: "parent-session",
- });
+ // The parent's turn is open while its call waits on the child.
+ const session: HarnessSession = withOpenTurn(
+ createStubSession({ continuationToken: "http:proxy-test", sessionId: "parent-session" }),
+ { sequence: 0, stepIndex: 0, turnId: "turn_0" },
+ );
installSessionStoreMocks([session]);
const sessionState = createStubSessionState({
diff --git a/packages/eve/src/execution/session/turn-step.ts b/packages/eve/src/execution/session/turn-step.ts
index e229512b4..34b4d229c 100644
--- a/packages/eve/src/execution/session/turn-step.ts
+++ b/packages/eve/src/execution/session/turn-step.ts
@@ -1,15 +1,12 @@
+import { bindTurnCallerContext } from "#subagents/parent-notification.js";
+import type { HandleEventFn } from "#harness/types.js";
import { bindDynamicConnections } from "#execution/dynamic-connections.js";
import { deriveSessionTitle } from "#execution/eve-workflow-attributes.js";
import { setEveAttributes } from "#runtime/attributes/emit.js";
import { defaultDeliverResult } from "#channel/adapter.js";
import { contextStorage } from "#context/container.js";
import { runStep } from "#context/run-step.js";
-import {
- drainDynamicInstructionUserMessages,
- prepareDynamicInstructionPreamble,
-} from "#context/dynamic-instruction-lifecycle.js";
import { refreshDynamicSessionSubagentsForRuntimeRevision } from "#context/dynamic-subagent-lifecycle.js";
-import { drainMemoryCommit, prepareMemoryPreamble } from "#context/memory-lifecycle.js";
import {
rebindMissingCompiledDynamicToolCallbacks,
refreshDynamicSessionToolsForRuntimeRevision,
@@ -29,27 +26,25 @@ import {
} from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
-import {
- emitTurnPreamble,
- getHarnessEmissionState,
- isHarnessBetweenTurns,
- setHarnessEmissionState,
-} from "#harness/emission.js";
import { bindSessionInstrumentation } from "#instrumentation/runtime.js";
import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";
import * as agentTraceState from "#tracing/agent-trace-context-store.js";
import { matchAuthorizationCallbacks } from "#execution/authorization-callback-match.js";
import { isTurnCancellation, throwIfTurnAborted } from "#harness/turn-cancellation.js";
import { setChannelContext } from "#execution/channel-context.js";
-import { activeTurnId } from "#harness/active-turn-id.js";
+import { activeTurnId, isBetweenTurns, turnPosition } from "#harness/session-machine/view.js";
import {
- coalesceTurnInputs,
- createTurnInputMessages,
- validateHarnessModelMessages,
- type UserModelMessage,
-} from "#harness/messages.js";
-import { consumeDeferredStepInput } from "#harness/pending-input-batches.js";
-import type { HandleEventFn, HarnessSession, StepInput, StepResult } from "#harness/types.js";
+ currentProjection,
+ enterSessionProjection,
+ saveSessionProjection,
+} from "#harness/session-machine/current.js";
+import { dropClosedRecords } from "#harness/session-machine/commit.js";
+import {
+ sessionStartedForResolvers,
+ turnStartedForResolvers,
+} from "#harness/session-machine/resolver-events.js";
+import { coalesceTurnInputs, validateHarnessModelMessages } from "#harness/messages.js";
+import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";
import { attributeAnswers } from "#execution/session/answer-caller.js";
import type {
DurableStepResult,
@@ -61,12 +56,6 @@ import { withSessionStateDelta } from "#execution/session/state-delta.js";
import { openSessionEventPublisher } from "#execution/publish-session-events.js";
import { createTurnEventHandler } from "#execution/session/turn-event-handler.js";
import { derivePendingState } from "#execution/session/pending-turn-state.js";
-import {
- createAuthorizationCompletedEvent,
- createSessionStartedEvent,
- createTurnStartedEvent,
-} from "#protocol/message.js";
-import { authorizationEventFields } from "#harness/authorization-event-fields.js";
import {
CallbackBaseUrlKey,
clearPendingAuthorization,
@@ -80,8 +69,6 @@ import {
readDurableSession,
} from "#execution/durable-session-store.js";
import { buildRuntimeIdentity, createExecutionNodeStep } from "#execution/node-step.js";
-import { prepareWorkflowPreambleTrace } from "#execution/workflow-trace-context.js";
-import { bindTurnCallerContext } from "#subagents/parent-notification.js";
import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";
import { reconcileSessionContinuationToken } from "#execution/reconcile-session-continuation-token.js";
import { hydrateDurableSession, refreshSessionFromTurnAgent } from "#execution/session.js";
@@ -93,6 +80,7 @@ import {
createCancelledModelCallBatchResult,
type CompletedModelCallCheckpoint,
} from "#execution/cancelled-model-call-batch.js";
+import type { AuthorizationChallenge } from "#harness/authorization.js";
function channelDeliveryErrorCode(error: unknown): string {
if (typeof error === "object" && error !== null && "code" in error) {
@@ -127,6 +115,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
durableSession = countRunUsage(durableSession, usage);
}
const ctx = await deserializeContext(input.serializedContext);
+ enterSessionProjection(ctx, durableSession.state);
const adapter = ctx.require(ChannelKey);
const bundle = ctx.require(BundleKey);
const effectiveAgent = resolveEffectiveAgentRuntime(bundle, ctx);
@@ -199,7 +188,8 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
rootSessionId: initialSession.rootSessionId ?? initialSession.sessionId,
sessionId: initialSession.sessionId,
});
- const initialEmissionState = getHarnessEmissionState(initialSession.state);
+ const initialEmissionState = turnPosition(currentProjection(ctx));
+ const startedBetweenTurns = isBetweenTurns(currentProjection(ctx));
if (
!initialEmissionState.sessionStarted &&
!ctx.has(SessionTitleKey) &&
@@ -282,7 +272,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
await emitTurnEvent(event, messages);
};
const previousAdapterState =
- delivery !== undefined && !isHarnessBetweenTurns(initialSession)
+ delivery !== undefined && !startedBetweenTurns
? structuredClone(adapterCtx.state)
: undefined;
// Run the adapter's deliver hook for each queued payload and coalesce
@@ -326,7 +316,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
if (!hadInitiator) ctx.delete(InitiatorAuthKey);
}
const ignoredActiveDelivery =
- delivery !== undefined && resolved === undefined && !isHarnessBetweenTurns(initialSession);
+ delivery !== undefined && resolved === undefined && !startedBetweenTurns;
if (ignoredActiveDelivery) {
// The adapter sees the incoming caller, but an ignored correction must
// not change the identity or reply destination of the interrupted work.
@@ -349,7 +339,6 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
ctx.set(TurnDeliveryIdsKey, [ctx.require(ChannelDeliveryKey).deliveryId]);
}
}
-
if (runtimeResults !== undefined) {
if (runtimeResults.acceptedAtMsByCallId !== undefined) {
ctx.set(RuntimeActionSettlementTimesKey, runtimeResults.acceptedAtMsByCallId);
@@ -362,7 +351,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
setChannelContext(ctx, updatedAdapter);
}
- if (delivery !== undefined && resolved === undefined && isHarnessBetweenTurns(initialSession)) {
+ if (delivery !== undefined && resolved === undefined && startedBetweenTurns) {
await contextStorage.run(ctx, () =>
instrumentation?.instrumentChannelDelivery({
ctx,
@@ -371,7 +360,10 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
}),
);
await instrumentation?.flush();
- const aliased = reconcileSessionContinuationToken(ctx, initialSession);
+ const aliased = saveSessionProjection(
+ reconcileSessionContinuationToken(ctx, initialSession),
+ ctx,
+ );
const nextSerializedContext = serializeContext(ctx);
const nextValues =
aliased === initialSession
@@ -380,7 +372,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
return {
action: "park",
- ...derivePendingState(aliased),
+ ...derivePendingState(aliased, currentProjection(ctx)),
serializedContext: nextSerializedContext,
...nextValues,
};
@@ -401,7 +393,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
ctx.set(SessionDynamicSubagentRuntimeRevisionKey, dynamicRuntimeRevision);
ctx.set(SessionDynamicToolRuntimeRevisionKey, dynamicRuntimeRevision);
} else {
- const refreshEvent = createSessionStartedEvent({ runtime: runtimeIdentity });
+ const refreshEvent = sessionStartedForResolvers(runtimeIdentity);
await Promise.all([
refreshDynamicSessionSubagentsForRuntimeRevision({
ctx,
@@ -422,10 +414,10 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
}),
),
]);
- if (!isHarnessBetweenTurns(initialSession)) {
+ if (!startedBetweenTurns) {
await rebindMissingCompiledDynamicToolCallbacks({
ctx,
- event: createTurnStartedEvent({
+ event: turnStartedForResolvers({
sequence: initialEmissionState.sequence,
turnId: activeTurnId(initialEmissionState),
}),
@@ -446,6 +438,7 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
const runHarnessStep = async (
lifecycleSession: HarnessSession,
stepInput: StepInput | undefined,
+ signInCompletions: readonly AuthorizationChallenge[] | undefined,
): Promise<StepResult> => {
const refreshedSession = refreshSessionFromTurnAgent({
compactionOverrides: {
@@ -464,7 +457,8 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
compactOnly: input.input?.control === "compact",
createRuntime: createWorkflowRuntime,
handleEvent,
- prepareApprovalTurn: (event) => dynamicConnections.dispatch(createTurnStartedEvent(event)),
+ prepareApprovalTurn: (event) => dynamicConnections.dispatch(turnStartedForResolvers(event)),
+ signInCompletions,
historyProjector: history.projector,
historyView: history.prepare(modelSession),
instrumentation,
@@ -497,82 +491,28 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
firstCall && resolved?.outputSchema !== undefined
? { ...enrichedSession, outputSchema: resolved.outputSchema }
: enrichedSession;
- const connectionState = getHarnessEmissionState(schemaSession.state);
+ const connectionState = turnPosition(currentProjection(ctx));
await dynamicConnections.rehydrate(
connectionState,
runtimeIdentity,
- isHarnessBetweenTurns(schemaSession)
+ isBetweenTurns(currentProjection(ctx))
? undefined
: { sequence: connectionState.sequence, turnId: activeTurnId(connectionState) },
);
- if (firstCall && completedAuths) {
- let emissionState = getHarnessEmissionState(schemaSession.state);
- const startsTurn = completedAuths.some(
- ({ challenge }) => challenge.candidateId === undefined,
- );
- if (startsTurn && isHarnessBetweenTurns(schemaSession)) {
- const turnInput = createTurnInputMessages(
- consumeDeferredStepInput({ session: schemaSession, input: stepInput }).input,
- );
- prepareDynamicInstructionPreamble(ctx, history.messages(schemaSession));
- prepareMemoryPreamble(ctx, {
- history: schemaSession.history,
- input: turnInput,
- projector: history.projector,
- state: schemaSession.state,
- });
- let instructionMessages: readonly UserModelMessage[] = [];
- const traceContext = await prepareWorkflowPreambleTrace({
- emissionState,
- instrumentation,
- });
- try {
- emissionState = await emitTurnPreamble(
- handleEvent,
- {},
- emissionState,
- history.projector({
- messages: [...schemaSession.history, ...turnInput],
- state: schemaSession.state,
- }),
- runtimeIdentity,
- traceContext,
- );
- } finally {
- instructionMessages = drainDynamicInstructionUserMessages(ctx);
- const memoryCommit = drainMemoryCommit(ctx);
- schemaSession = {
- ...schemaSession,
- history: validateHarnessModelMessages([
- ...schemaSession.history,
- ...(memoryCommit?.recalledMessages ?? []),
- ...instructionMessages,
- ]),
- state: memoryCommit?.state ?? schemaSession.state,
- };
- }
- schemaSession = setHarnessEmissionState(schemaSession, emissionState);
- }
- for (const { challenge } of completedAuths) {
- await handleEvent(
- createAuthorizationCompletedEvent({
- ...authorizationEventFields(challenge),
- outcome: "authorized",
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
- }
-
- return runHarnessStep(schemaSession, stepInput);
+ // A sign-in completes before the turn it resumes, in the first call only.
+ const completions =
+ firstCall && completedAuths !== undefined
+ ? completedAuths.map(({ challenge }) => challenge)
+ : undefined;
+ return runHarnessStep(schemaSession, stepInput, completions);
});
// The waiting boundary may reach the client before this step returns.
// Its settled result wins over a cancellation of that completed turn.
if (result.settledTurn === undefined) throwIfTurnAborted(abortSignal);
- completedModelCall = { result, serializedContext: serializeContext(ctx) };
- return result;
+ // The call's result carries the lifecycle it published, which batching reads.
+ const saved = { ...result, session: saveSessionProjection(result.session, ctx) };
+ completedModelCall = { result: saved, serializedContext: serializeContext(ctx) };
+ return saved;
},
});
} catch (error) {
@@ -590,7 +530,13 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>
}
// Re-stamp the current address after handlers add a continuation alias.
- const aliased = reconcileSessionContinuationToken(ctx, stepResult.session);
+ const aliased = saveSessionProjection(
+ dropClosedRecords(
+ reconcileSessionContinuationToken(ctx, stepResult.session),
+ currentProjection(ctx),
+ ),
+ ctx,
+ );
agentTraceState.pruneAgentTraceState(ctx, aliased.sessionId, aliased.state);
const nextSerializedContext = serializeContext(ctx);
stepResult = { ...stepResult, session: aliased };
diff --git a/packages/eve/src/execution/session/turn-waiting-step.ts b/packages/eve/src/execution/session/turn-waiting-step.ts
index ad01e1391..b735bc7e9 100644
--- a/packages/eve/src/execution/session/turn-waiting-step.ts
+++ b/packages/eve/src/execution/session/turn-waiting-step.ts
@@ -1,11 +1,12 @@
+import { readDurableSession } from "#execution/durable-session-store.js";
import { publishSessionEvents, type SessionStepState } from "#execution/publish-session-events.js";
import {
withSessionStateDelta,
type SessionStateTransition,
} from "#execution/session/state-delta.js";
-import { readDurableSession } from "#execution/durable-session-store.js";
-import { getSessionUsage } from "#harness/turn-tag-state.js";
-import { createTurnWaitingEvent } from "#protocol/message.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { hold } from "#harness/session-machine/transitions.js";
+import { storedProjection } from "#harness/session-machine/view.js";
/** Publishes `turn.waiting` for the open turn the session workflow just parked. */
export async function publishTurnWaitingStep(
@@ -14,10 +15,11 @@ export async function publishTurnWaitingStep(
"use step";
return await withSessionStateDelta(target, async (input) => {
- const { sequence, turnId } = input.sessionState.emissionState;
- const usage = getSessionUsage(readDurableSession(input.sessionState));
- return await publishSessionEvents(input, [
- createTurnWaitingEvent({ on: "tasks", sequence, turnId, usage }),
- ]);
+ const session = readDurableSession(input.sessionState);
+ const view = sessionView(storedProjection(session.state), session.state);
+ const { events } = hold(view, { on: "tasks" });
+ if (events.length === 0)
+ return { serializedContext: input.serializedContext, sessionState: input.sessionState };
+ return await publishSessionEvents(input, events);
});
}
diff --git a/packages/eve/src/execution/session/turn.test.ts b/packages/eve/src/execution/session/turn.test.ts
index d6f3aa7a5..700a6e937 100644
--- a/packages/eve/src/execution/session/turn.test.ts
+++ b/packages/eve/src/execution/session/turn.test.ts
@@ -524,7 +524,10 @@ describe("SessionExecution checkpoints", () => {
).resolves.toMatchObject({ cancelled: true, kind: "park" });
expect(dispatchCoordinationStep).toHaveBeenCalledTimes(1);
expect(inbox.next).not.toHaveBeenCalled();
- expect(cancelDescendantTurnsStep).toHaveBeenCalledWith({ sessionState });
+ expect(cancelDescendantTurnsStep).toHaveBeenCalledWith({
+ serializedContext: {},
+ sessionState,
+ });
});
it("consumes the cancelling command while retaining accepted follow-ups", async () => {
@@ -1507,7 +1510,6 @@ function stateWithBlockingRun(): DurableSessionState {
function state(continuationToken: string): DurableSessionState {
return createTestSessionState({
continuationToken,
- emissionState: { sequence: 0, sessionStarted: true, stepIndex: 0, turnId: "turn_0" },
hasProxyInputRequests: false,
sessionId: "session-1",
});
diff --git a/packages/eve/src/execution/session/turn.ts b/packages/eve/src/execution/session/turn.ts
index 04d1cdbc9..9d6cd8346 100644
--- a/packages/eve/src/execution/session/turn.ts
+++ b/packages/eve/src/execution/session/turn.ts
@@ -275,7 +275,10 @@ export class SessionExecution {
async cancelTurnWork(): Promise<void> {
const { cursor } = this.input;
if (mayWaitOnWorkflowToolRuns(cursor.sessionState)) {
- await cancelDescendantTurnsStep({ sessionState: cursor.sessionState });
+ await cancelDescendantTurnsStep({
+ serializedContext: cursor.serializedContext,
+ sessionState: cursor.sessionState,
+ });
}
await cancelWorkingTasks(cursor, "turn_cancelled");
}
diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.integration.test.ts b/packages/eve/src/execution/settle-cancelled-turn-step.integration.test.ts
index de555df10..713659c4b 100644
--- a/packages/eve/src/execution/settle-cancelled-turn-step.integration.test.ts
+++ b/packages/eve/src/execution/settle-cancelled-turn-step.integration.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import type { SessionStateMap } from "#harness/types.js";
+import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import { readDurableSession } from "#execution/durable-session-store.js";
import { settleCancelledTurnStep } from "#execution/settle-cancelled-turn-step.js";
import {
@@ -9,7 +9,9 @@ import {
type ProxyInputRequest,
} from "#harness/proxy-input-requests.js";
import { filterEventsByType } from "#internal/testing/events.js";
-import type { MessageStreamEvent } from "#protocol/message.js";
+import { createInputRequestedEvent, type MessageStreamEvent } from "#protocol/message.js";
+import type { InputRequest } from "#shared/input.js";
+import { withPublished } from "#internal/testing/session-machine.js";
import {
accumulateTurnUsage,
getTurnUsageState,
@@ -72,10 +74,12 @@ describe("settleCancelledTurnStep", () => {
])(
"reports only what the session spent since its caller's last report (reports usage: $reportUsage)",
async ({ reportUsage, reported, nextSettled }) => {
- const base = createTestSessionState({
- emissionState: { sequence: 1, sessionStarted: true, stepIndex: 0, turnId: "turn_2" },
- sessionId: "reviewer-session",
- });
+ const base = createTestSessionState(
+ {
+ sessionId: "reviewer-session",
+ },
+ { sequence: 1, stepIndex: 0, turnId: "turn_2" },
+ );
// The reviewer's first turn spent 100 tokens and settled, reporting them.
const settled = takeSessionUsageDelta(spend(base.snapshot.session, 100, "turn_1")).session;
// Its next turn spent 50 more before Alice cancelled it.
@@ -97,10 +101,12 @@ describe("settleCancelledTurnStep", () => {
);
it("withdraws every request the session relays before it reports the turn cancelled", async () => {
- const base = createTestSessionState({
- emissionState: { sequence: 3, sessionStarted: true, stepIndex: 1, turnId: "turn_1" },
- sessionId: "support-session",
- });
+ const base = createTestSessionState(
+ {
+ sessionId: "support-session",
+ },
+ { sequence: 3, stepIndex: 1, turnId: "turn_1" },
+ );
// Alice's turn relays a question from Bob's deploy task and an approval
// from the reviewer subagent when she cancels it.
const state = relay(
@@ -136,23 +142,33 @@ describe("settleCancelledTurnStep", () => {
});
});
+/** Relays a child's request: the session publishes it, then keeps its route. */
function relay(
state: SessionStateMap | undefined,
requestId: string,
route: Pick<ProxyInputRequest, "kind" | "runId" | "workflowAsk">,
): SessionStateMap | undefined {
+ const event = { sequence: 2, stepIndex: 0, turnId: "turn_1" };
+ const request: InputRequest = {
+ action: { callId: `${requestId}-call`, input: {}, kind: "tool-call", toolName: "deploy" },
+ kind: route.kind,
+ prompt: "Approve deploy?",
+ requestId,
+ };
+ const published = withPublished({ ...openSession, state }, [
+ createInputRequestedEvent({ callId: `${requestId}-served`, requests: [request], ...event }),
+ ]);
return upsertProxyInputRequestState({
- entries: [
- [
- requestId,
- {
- ...route,
- childContinuationToken: requestId,
- event: { sequence: 2, stepIndex: 0, turnId: "turn_1" },
- },
- ],
- ],
+ entries: [[requestId, { ...route, childContinuationToken: requestId, event }]],
forChildContinuationToken: requestId,
- state,
+ state: published.state,
});
}
+
+const openSession: HarnessSession = {
+ agent: { dynamicModel: true, system: "", tools: [] },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "test-token",
+ history: [],
+ sessionId: "support-session",
+};
diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.ts b/packages/eve/src/execution/settle-cancelled-turn-step.ts
index e263c7ab0..2626399bc 100644
--- a/packages/eve/src/execution/settle-cancelled-turn-step.ts
+++ b/packages/eve/src/execution/settle-cancelled-turn-step.ts
@@ -1,7 +1,3 @@
-import {
- commitCancelledCoordinationBatch,
- getPendingCoordinationBatch,
-} from "#harness/coordination.js";
import type { DurableSessionState } from "#execution/durable-session-store.js";
import {
publishFromSessionStep,
@@ -12,27 +8,16 @@ import {
withSessionStateDelta,
type WithSessionStateDelta,
} from "#execution/session/state-delta.js";
-import { relayWithdrawnRequests } from "#execution/tools/workflow/withdraw-step.js";
-import { emitCancelledTurn } from "#harness/cancelled-turn-emission.js";
-import { declinedSignInEvents, withdrawHeldSignIns } from "#harness/held-requests.js";
-import {
- cancelApprovalInputBatches,
- getPendingApprovalRequests,
-} from "#harness/hitl/approval-input-requests.js";
-import { createInputResolvedEvent } from "#protocol/message.js";
+import { retireCancelledCandidates } from "#harness/hitl/index.js";
import type { HarnessModelMessage } from "#harness/messages.js";
-import { clearPendingSessionLimitPrompt } from "#harness/input-requests.js";
-import { getHarnessEmissionState, setHarnessEmissionState } from "#harness/emission.js";
+import { cancel } from "#harness/session-machine/transitions.js";
+import { applyTransition, sessionView } from "#harness/session-machine/commit.js";
+import { currentProjection } from "#harness/session-machine/current.js";
+import { runtimeWait, storedProjection } from "#harness/session-machine/view.js";
import { removeBlockingWorkflowToolRuns } from "#harness/workflow-tool-runs.js";
-import {
- getSessionUsage,
- getTurnUsageState,
- takeSessionUsageDelta,
-} from "#harness/turn-tag-state.js";
+import { getTurnUsageState, takeSessionUsageDelta } from "#harness/turn-tag-state.js";
import type { TokenUsage } from "#shared/token-usage.js";
-const CANCELLED_REASON = "Cancelled.";
-
export interface CancelledTurnSettleResult {
readonly serializedContext: Record<string, unknown>;
readonly sessionState: DurableSessionState;
@@ -41,7 +26,7 @@ export interface CancelledTurnSettleResult {
readonly usage?: TokenUsage;
}
-/** Takes the history because the turn's pending calls move into it, each answered as cancelled. */
+/** Takes the history because the steps the cancel stopped commit to it. */
interface CancelledTurnSettleInput extends SessionHistoryStepState {
/**
* Whether a caller receives the turn's usage. Only then is it marked
@@ -51,11 +36,9 @@ interface CancelledTurnSettleInput extends SessionHistoryStepState {
}
/**
- * Settles one cancelled turn: relays `input.resolved` for every request the
- * session proxies, emits `turn.cancelled` → `session.waiting`, drops pending
- * coordination state, and persists the between-turns session. Runs in the
- * owner, whose wake sources exclude the cancel hook, so a queued cancel wake
- * cannot re-dispatch it.
+ * Settles one cancelled turn through the machine's `cancel`, and persists
+ * the between-turns session. Runs in the owner, whose wake sources exclude the
+ * cancel hook, so a queued cancel wake cannot re-dispatch it.
*/
export async function settleCancelledTurnStep(
input: CancelledTurnSettleInput,
@@ -68,71 +51,26 @@ export async function settleCancelledTurnStep(
export async function settleCancelledTurn(
input: CancelledTurnSettleInput,
): Promise<CancelledTurnSettleResult> {
- // The cancel stopped every descendant and task, so nobody can answer a request the session relays.
- const relayed = await relayWithdrawnRequests(input, () => true);
- const step = {
- ...(await restoreSessionStep({ ...relayed, sessionWritable: input.sessionWritable })),
- history: input.history,
- };
+ const step = { ...(await restoreSessionStep(input)), history: input.history };
const durableState = step.durableSession.state;
- // Every request the turn held ends with it: its sign-ins and its approvals.
- const withdraw = { completedAt: Date.now(), reason: CANCELLED_REASON };
- const withdrawal = withdrawHeldSignIns(durableState, withdraw);
- const cancelledApprovals = getPendingApprovalRequests(durableState);
+ const owningTurnId =
+ runtimeWait(durableState)?.event.turnId ?? storedProjection(durableState).activeTurnId ?? "";
const { published, result: usage } = await publishFromSessionStep(step, {
origin: "own",
- async publish(emit) {
- const emissionState = getHarnessEmissionState(durableState);
- for (const event of declinedSignInEvents(
- withdrawal.withdrawn,
- CANCELLED_REASON,
- emissionState,
- )) {
- await emit(event);
- }
- if (cancelledApprovals.length > 0) {
- await emit(
- createInputResolvedEvent({
- resolutions: cancelledApprovals.map((request) => ({
- kind: request.kind,
- outcome: "cancelled",
- requestId: request.requestId,
- })),
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
- return await emitCancelledTurn(emit, emissionState, getSessionUsage(step.durableSession));
- },
- updateSession(baseSession, emissionState) {
- const session = {
- ...baseSession,
- state: withdrawHeldSignIns(baseSession.state, withdraw).state,
- };
- // `clearPendingSessionLimitPrompt`: cancellation settles with the step's
- // input snapshot, which can resurrect an already-answered session-limit
- // prompt (the decline that cancelled this turn consumed the answer in the
- // discarded turn state). The pre-model gate re-raises the prompt while the
- // violation holds, so the next delivery gets a fresh prompt instead of
- // queueing forever behind a stale one.
- const owningTurnId =
- getPendingCoordinationBatch(session.state)?.event.turnId ??
- input.sessionState.emissionState.turnId;
- const cancelledSession = setHarnessEmissionState(
- clearPendingSessionLimitPrompt(
- // After the coordination batch, which owns an assistant response it
- // shares with approvals raised beside its calls.
- cancelApprovalInputBatches(
- commitCancelledCoordinationBatch(
- removeBlockingWorkflowToolRuns({ ...session, outputSchema: undefined }, owningTurnId),
- ),
- ),
- ),
- emissionState,
+ publish: (emit, session) =>
+ applyTransition(
+ session,
+ cancel(sessionView(currentProjection(step.ctx), session.state)),
+ emit,
+ ),
+ updateSession(_session, cancelled) {
+ // The cancel reported every request and call it closed and committed the steps it stopped;
+ // what remains is private: its runs are forgotten, and its responders stop.
+ const cancelledSession = removeBlockingWorkflowToolRuns(
+ retireCancelledCandidates({ ...cancelled, outputSchema: undefined }),
+ owningTurnId,
);
- if (!input.reportUsage || getTurnUsageState(session.state) === undefined) {
+ if (!input.reportUsage || getTurnUsageState(cancelled.state) === undefined) {
return { session: cancelledSession };
}
// Reported like a settled turn, as usage since the last report, so the
diff --git a/packages/eve/src/execution/tasks/session.test.ts b/packages/eve/src/execution/tasks/session.test.ts
index 908339888..2fb57e5fb 100644
--- a/packages/eve/src/execution/tasks/session.test.ts
+++ b/packages/eve/src/execution/tasks/session.test.ts
@@ -13,10 +13,10 @@ import {
writeTaskTable,
type TaskTable,
} from "#execution/tasks/table.js";
-import {
- getProxyInputRequests,
- upsertProxyInputRequestState,
-} from "#harness/proxy-input-requests.js";
+import { upsertProxyInputRequestState } from "#harness/proxy-input-requests.js";
+import type { HarnessSession } from "#harness/types.js";
+import { withPublished } from "#internal/testing/session-machine.js";
+import { createInputRequestedEvent } from "#protocol/message.js";
import { createTestSessionState } from "#internal/testing/session-state.js";
// No workflow runtime runs here: the run's cancel hook is a stub, and the
@@ -64,8 +64,7 @@ describe("answerTaskCancel", () => {
taskId: research.taskId,
});
- const committed = cursor.sessionState.snapshot.session;
- expect([...getProxyInputRequests(committed.state).keys()]).toEqual(["summarize-run-ask-1"]);
+ // Publishing drops the withdrawn question's route; here it only records what was published.
expect(published).toEqual([
{
event: {
@@ -130,8 +129,7 @@ describe("applyTaskRunMessageStep", () => {
}),
);
- const committed = cursor.sessionState.snapshot.session;
- expect([...getProxyInputRequests(committed.state).keys()]).toEqual(["summarize-run-ask-1"]);
+ // Publishing drops the withdrawn question's route; here it only records what was published.
expect(published).toEqual([
{
event: {
@@ -200,8 +198,23 @@ function startedTask(
};
}
+/** A question the task's run asked, relayed as the session relays it. */
function withQuestion(session: DurableSession, runId: string): DurableSession {
const requestId = `${runId}-ask-1`;
+ session = withPublished(session as HarnessSession, [
+ createInputRequestedEvent({
+ callId: `${runId.replace("-run", "")}-call`,
+ requests: [
+ {
+ action: { callId: requestId, input: {}, kind: "tool-call", toolName: "ask" },
+ kind: "question",
+ prompt: "Which region should Alice's report cover?",
+ requestId,
+ },
+ ],
+ ...REQUEST_EVENT,
+ }),
+ ]);
const state = upsertProxyInputRequestState({
entries: [
[
diff --git a/packages/eve/src/execution/tasks/start.ts b/packages/eve/src/execution/tasks/start.ts
index 866662cac..77ea9ff23 100644
--- a/packages/eve/src/execution/tasks/start.ts
+++ b/packages/eve/src/execution/tasks/start.ts
@@ -27,7 +27,7 @@ import {
import { createRuntimeToolResultFromValue } from "#harness/action-result-helpers.js";
import { createLogger, logError } from "#internal/logging.js";
import type { HarnessSessionBase } from "#harness/types.js";
-import { createTaskStartedEvent, type TaskStartedStreamEvent } from "#protocol/message.js";
+import type { TaskStartedStreamEvent } from "#protocol/message.js";
import { TOO_MANY_TASKS_CODE, UNKNOWN_TASK_CODE } from "#protocol/task-tools.js";
import type { RuntimeToolResultActionResult, WorkflowToolRunEntry } from "#shared/action-types.js";
@@ -35,11 +35,11 @@ const log = createLogger("execution.tasks");
type TaskDispatchInput = StartWorkflowTaskInput & { readonly taskId: string };
-/** The call's answer, and the `task.started` event the dispatch step publishes for it. */
+/** The call's answer, and the task start the dispatch step reports for it. */
interface TaskDispatchResult {
readonly result: RuntimeToolResultActionResult;
readonly session: HarnessSessionBase;
- readonly started?: TaskStartedStreamEvent;
+ readonly started?: TaskStartedStreamEvent["data"];
}
/** The entry of a run that does a task's work. */
@@ -156,14 +156,17 @@ function unknownTaskResult(input: TaskDispatchInput): RuntimeToolResultActionRes
});
}
-function taskStartedEvent(input: TaskDispatchInput, record: TaskRecord): TaskStartedStreamEvent {
- return createTaskStartedEvent({
+function taskStartedEvent(
+ input: TaskDispatchInput,
+ record: TaskRecord,
+): TaskStartedStreamEvent["data"] {
+ return {
callId: input.task.callId,
kind: record.kind,
name: input.task.toolName,
taskId: input.taskId,
turnId: input.batchEvent.turnId,
- });
+ };
}
function startReceipt(input: TaskDispatchInput, resumable: boolean): RuntimeToolResultActionResult {
diff --git a/packages/eve/src/execution/tasks/steps.ts b/packages/eve/src/execution/tasks/steps.ts
index 51d0f4c12..fd97599da 100644
--- a/packages/eve/src/execution/tasks/steps.ts
+++ b/packages/eve/src/execution/tasks/steps.ts
@@ -39,14 +39,12 @@ import type {
WorkflowToolRunOutcomeMessage,
} from "#execution/tools/workflow/messages.js";
import { workflowToolRunFailureOutput } from "#execution/tools/workflow/owner-inbox.js";
-import { withdrawProxyInputRequests } from "#harness/proxy-input-requests.js";
+import { getProxyInputRequests } from "#harness/proxy-input-requests.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { finishRun, settleTask } from "#harness/session-machine/transitions.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import { resumeHook } from "#internal/workflow/runtime.js";
-import {
- createTaskSettledEvent,
- type TaskCancelReason,
- type TaskSettledStreamEvent,
- type UnstampedMessageStreamEvent,
-} from "#protocol/message.js";
+import type { TaskCancelReason, UnstampedMessageStreamEvent } from "#protocol/message.js";
/** The messages a task's run sends that change its record. */
export type TaskRunMessage = Extract<
@@ -74,7 +72,7 @@ async function applyTaskRunMessage(
return { serializedContext: input.serializedContext, sessionState: input.sessionState };
}
let table = readTaskTable(session.state);
- const events: TaskSettledStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
let withdrawn: readonly UnstampedMessageStreamEvent[] = [];
switch (message.kind) {
case "started": {
@@ -89,7 +87,7 @@ async function applyTaskRunMessage(
const record = findTask(table, taskId);
const settled = settleTaskCalls(table, { callIds: message.callIds, outcome, taskId });
table = settled.table;
- events.push(...taskSettledEvents(record, settled.settled, outcome));
+ events.push(...taskSettledEvents(session, record, settled.settled, outcome));
break;
}
case "usage":
@@ -100,13 +98,13 @@ async function applyTaskRunMessage(
const outcome = toOutcome(message);
const record = findTask(table, taskId);
const settled = settleRemainingTaskCalls(table, taskId, outcome);
- events.push(...taskSettledEvents(record, settled.settled, outcome));
+ events.push(...taskSettledEvents(session, record, settled.settled, outcome));
table = finishTaskRun(settled.table, taskId, message.from.runId);
- // Nobody can answer what a finished run relayed, so channels must stop offering it.
- ({ events: withdrawn, session } = withdrawProxyInputRequests(
- session,
- (_requestId, route) => route.runId === message.from.runId,
- ));
+ // Nobody can answer what a finished run relayed, so channels stop offering it.
+ withdrawn = finishRun(viewOf(session), {
+ requestIds: runRequestIds(session, message.from.runId),
+ taskId,
+ }).events;
break;
}
}
@@ -141,67 +139,39 @@ async function cancelTasks(
): Promise<PublishedSessionEvents> {
const session = readDurableSession(input.sessionState);
let table = readTaskTable(session.state);
- const events: TaskSettledStreamEvent[] = [];
- const stoppedRunIds = new Set<string>();
+ const events: UnstampedMessageStreamEvent[] = [];
+ const view = viewOf(session);
+ const withdrawn: UnstampedMessageStreamEvent[] = [];
const outcome: TaskOutcome = { reason: input.reason, status: "cancelled" };
for (const taskId of input.taskIds) {
const record = findTask(table, taskId);
const cancelled = cancelTask(table, taskId);
table = cancelled.table;
- events.push(...taskSettledEvents(record, cancelled.settled, outcome));
+ events.push(...taskSettledEvents(session, record, cancelled.settled, outcome));
if (cancelled.send === undefined) continue;
- if (record?.resumable === false) stoppedRunIds.add(cancelled.send.run.runId);
+ // A `task()` run's cancel settles what it relayed; a `serve()` run withdraws its own.
+ if (record?.resumable === false) {
+ const requestIds = runRequestIds(session, cancelled.send.run.runId);
+ withdrawn.push(...finishRun(view, { requestIds, taskId }).events);
+ }
await sendTaskRunCommands(cancelled.send);
}
- const withdrawn = withdrawProxyInputRequests(
- session,
- (_requestId, route) => route.runId !== undefined && stoppedRunIds.has(route.runId),
- );
const relayed = await relaySessionEvents(
- { ...input, sessionState: saveTable(input.sessionState, withdrawn.session, table) },
- withdrawn.events,
+ { ...input, sessionState: saveTable(input.sessionState, session, table) },
+ withdrawn,
);
return await publishSessionEvents({ ...input, ...relayed }, events);
}
/** The `task.settled` events for a task's settled calls; calls only settle on a known task. */
function taskSettledEvents(
+ session: DurableSession,
record: TaskRecord | undefined,
- settled: readonly TaskCall[],
+ calls: readonly TaskCall[],
outcome: TaskOutcome,
-): TaskSettledStreamEvent[] {
+): readonly UnstampedMessageStreamEvent[] {
if (record === undefined) return [];
- return settled.map((call) => taskSettledEvent(record, call, outcome));
-}
-
-function taskSettledEvent(
- record: TaskRecord,
- call: TaskCall,
- outcome: TaskOutcome,
-): TaskSettledStreamEvent {
- const base = {
- callId: call.callId,
- kind: record.kind,
- name: record.name,
- taskId: record.id,
- turnId: call.turnId,
- };
- switch (outcome.status) {
- case "completed":
- return createTaskSettledEvent({ ...base, output: outcome.output, status: "completed" });
- case "failed":
- return createTaskSettledEvent({
- ...base,
- error: { message: outcome.error },
- status: "failed",
- });
- case "cancelled":
- return createTaskSettledEvent(
- outcome.reason === undefined
- ? { ...base, status: "cancelled" }
- : { ...base, cancel: { reason: outcome.reason }, status: "cancelled" },
- );
- }
+ return settleTask(viewOf(session), { calls, outcome, task: record }).events;
}
/**
@@ -262,6 +232,17 @@ function countTaskRunUsage(
};
}
+/** The requests a run relayed: its own questions and those of the sessions it opened. */
+function runRequestIds(session: DurableSession, runId: string): readonly string[] {
+ return [...getProxyInputRequests(session.state)]
+ .filter(([, route]) => route.runId === runId)
+ .map(([requestId]) => requestId);
+}
+
+function viewOf(session: DurableSession) {
+ return sessionView(storedProjection(session.state), session.state);
+}
+
function saveTable(
state: DurableSessionState,
session: DurableSession,
diff --git a/packages/eve/src/execution/terminal-session-completion-step.ts b/packages/eve/src/execution/terminal-session-completion-step.ts
index 7037f5835..b55716a5d 100644
--- a/packages/eve/src/execution/terminal-session-completion-step.ts
+++ b/packages/eve/src/execution/terminal-session-completion-step.ts
@@ -1,7 +1,7 @@
-import type { HarnessTurnRef } from "#harness/emission-state.js";
+type HarnessTurnRef = { readonly id: string; readonly sequence: number };
import { publishTerminalSessionEvent } from "#execution/publish-session-events.js";
-import { createSessionCompletedEvent } from "#protocol/message.js";
import type { TokenUsage } from "#shared/token-usage.js";
+import { sessionCompleted } from "#harness/session-machine/transitions.js";
/** Emits a terminal `session.completed` outside a turn. */
export async function emitTerminalSessionCompletionStep(input: {
@@ -13,10 +13,5 @@ export async function emitTerminalSessionCompletionStep(input: {
}): Promise<void> {
"use step";
- await publishTerminalSessionEvent({
- sessionWritable: input.sessionWritable,
- serializedContext: input.serializedContext,
- turn: input.turn,
- event: createSessionCompletedEvent(input.usage),
- });
+ await publishTerminalSessionEvent({ ...input, event: sessionCompleted(input.usage) });
}
diff --git a/packages/eve/src/execution/terminal-session-failure-step.ts b/packages/eve/src/execution/terminal-session-failure-step.ts
index ff956af11..80c8869ad 100644
--- a/packages/eve/src/execution/terminal-session-failure-step.ts
+++ b/packages/eve/src/execution/terminal-session-failure-step.ts
@@ -1,8 +1,8 @@
import { publishTerminalSessionEvent } from "#execution/publish-session-events.js";
+import type { TokenUsage } from "#shared/token-usage.js";
import { summarizeKnownError } from "#harness/semantic-errors/index.js";
import { createLogger, formatError } from "#internal/logging.js";
-import { createSessionFailedEvent } from "#protocol/message.js";
-import type { TokenUsage } from "#shared/token-usage.js";
+import { sessionFailed } from "#harness/session-machine/transitions.js";
const log = createLogger("execution.workflow-entry");
@@ -43,7 +43,7 @@ export async function emitTerminalSessionFailureStep(input: {
await publishTerminalSessionEvent({
errorId: typeof details.errorId === "string" ? details.errorId : undefined,
- event: createSessionFailedEvent({ code, details, message, sessionId, usage: input.usage }),
+ event: sessionFailed({ code, details, message, sessionId, usage: input.usage }),
sessionWritable: input.sessionWritable,
serializedContext: input.serializedContext,
turnId: input.turnId,
diff --git a/packages/eve/src/execution/tools/workflow/step.ts b/packages/eve/src/execution/tools/workflow/step.ts
index abac0a8f9..4509c022f 100644
--- a/packages/eve/src/execution/tools/workflow/step.ts
+++ b/packages/eve/src/execution/tools/workflow/step.ts
@@ -1,5 +1,4 @@
import { createHook, getWorkflowMetadata } from "#compiled/@workflow/core/index.js";
-import { authorizationEventFields } from "#harness/authorization-event-fields.js";
import type { AuthorizationChallenge } from "#harness/authorization.js";
import type { AuthorizationCallback } from "#shared/connection-types.js";
import type { ToolContext } from "#tools/definition.js";
@@ -8,10 +7,7 @@ import {
type WorkflowToolRunContext,
} from "#execution/tools/workflow/ask.js";
import { disposeHook } from "#execution/hook-ownership.js";
-import {
- createAuthorizationRequiredEvent,
- createAuthorizationCompletedEvent,
-} from "#protocol/message.js";
+import { runSignIn } from "#harness/session-machine/transitions.js";
import type {
WorkflowStepAuthorizationResult,
WorkflowStepContext,
@@ -221,21 +217,7 @@ async function reportAuthorization(
challenge: IdentifiedAuthorizationChallenge,
outcome?: "authorized" | "failed",
): Promise<void> {
- const eventInput = {
- ...authorizationEventFields(challenge),
- sequence: run.from.sequence,
- stepIndex: run.from.stepIndex,
- taskId: run.from.taskId,
- turnId: run.from.turnId,
- };
- const event =
- outcome === undefined
- ? createAuthorizationRequiredEvent({
- ...eventInput,
- description: `Sign in to ${challenge.name} to continue.`,
- webhookUrl: challenge.hookUrl,
- })
- : createAuthorizationCompletedEvent({ ...eventInput, outcome });
+ const event = runSignIn(run.from, challenge, outcome);
const acknowledged = createHook<void>();
try {
await withAbort(
diff --git a/packages/eve/src/execution/tools/workflow/withdraw-step.ts b/packages/eve/src/execution/tools/workflow/withdraw-step.ts
index cdb44bf99..e6b81a138 100644
--- a/packages/eve/src/execution/tools/workflow/withdraw-step.ts
+++ b/packages/eve/src/execution/tools/workflow/withdraw-step.ts
@@ -1,7 +1,4 @@
-import {
- readDurableSession,
- replaceDurableSessionSnapshot,
-} from "#execution/durable-session-store.js";
+import { readDurableSession } from "#execution/durable-session-store.js";
import {
relaySessionEvents,
type PublishedSessionEvents,
@@ -14,18 +11,17 @@ import {
import type { WorkflowToolRunControlMessage } from "#execution/tools/workflow/messages.js";
import { ignoreGoneTarget } from "#execution/tasks/workflow-target.js";
import { resumeHook } from "#internal/workflow/runtime.js";
-import {
- withdrawProxyInputRequests,
- type ProxyInputRequest,
-} from "#harness/proxy-input-requests.js";
+import { getProxyInputRequests, type ProxyInputRequest } from "#harness/proxy-input-requests.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { finishRun } from "#harness/session-machine/transitions.js";
+import { storedProjection } from "#harness/session-machine/view.js";
/**
* Decides a run's request to withdraw a question. A question the session
- * still offers is retired and relayed `cancelled`, so channels stop offering
- * it. One it no longer offers was already answered or withdrawn when its turn
- * was cancelled. Either way the run hears `withdrawn`, after any answer the
- * session sent it first, so the question resolves from the session's first
- * decision.
+ * still offers is withdrawn, so channels stop offering it. One it no longer
+ * offers was already answered or withdrawn when its turn was cancelled. Either
+ * way the run hears `withdrawn`, after any answer the session sent it first, so
+ * the question resolves from the session's first decision.
*/
export async function withdrawWorkflowToolRunQuestionStep(
input: WithdrawQuestionInput,
@@ -59,8 +55,7 @@ async function withdrawWorkflowToolRunQuestion(
/**
* Withdraws the requests a finished run left open: its own questions and those
- * of the sessions it opened, which ended with it. Nobody can answer them now,
- * so each is relayed `cancelled`.
+ * of the sessions it opened, which ended with it. Nobody can answer them now.
*/
export async function withdrawFinishedRunQuestionsStep(
input: SessionStepState & { readonly runId: string },
@@ -72,23 +67,17 @@ export async function withdrawFinishedRunQuestionsStep(
}
/**
- * Retires the relayed requests `select` picks and relays the `input.resolved`
- * that reports each one `cancelled`, for a step that owns the session.
+ * Withdraws the relayed requests `select` picks through the machine's `finishRun`, for a step
+ * that owns the session. Their routes drop with the save, once the projection shows them closed.
*/
export async function relayWithdrawnRequests(
input: SessionStepState,
select: (requestId: string, route: ProxyInputRequest) => boolean,
): Promise<PublishedSessionEvents> {
- const withdrawn = withdrawProxyInputRequests(readDurableSession(input.sessionState), select);
- return await relaySessionEvents(
- {
- serializedContext: input.serializedContext,
- sessionState: replaceDurableSessionSnapshot({
- session: withdrawn.session,
- state: input.sessionState,
- }),
- sessionWritable: input.sessionWritable,
- },
- withdrawn.events,
- );
+ const session = readDurableSession(input.sessionState);
+ const requestIds = [...getProxyInputRequests(session.state)]
+ .filter(([requestId, route]) => select(requestId, route))
+ .map(([requestId]) => requestId);
+ const view = sessionView(storedProjection(session.state), session.state);
+ return await relaySessionEvents(input, finishRun(view, { requestIds }).events);
}
diff --git a/packages/eve/src/execution/turn-cancellation.integration.test.ts b/packages/eve/src/execution/turn-cancellation.integration.test.ts
index 6c139a7bc..1bbde866c 100644
--- a/packages/eve/src/execution/turn-cancellation.integration.test.ts
+++ b/packages/eve/src/execution/turn-cancellation.integration.test.ts
@@ -634,6 +634,8 @@ describe("turn cancellation integration", () => {
).toBe(true);
expect(filterEventsByType(cancelledTurn, "turn.started")).toHaveLength(1);
expect(filterEventsByType(cancelledTurn, "turn.cancelled")).toHaveLength(1);
+ // v26 cancellation ends the turn without inventing a tool result.
+ expect(filterEventsByType(cancelledTurn, "action.result")).toEqual([]);
// The superseding step attempt settles before any model work, so
// the cancelled turn streams exactly one step.
expect(filterEventsByType(cancelledTurn, "step.started")).toHaveLength(1);
diff --git a/packages/eve/src/execution/workflow-trace-context.ts b/packages/eve/src/execution/workflow-trace-context.ts
index 747875b5b..0d72f464c 100644
--- a/packages/eve/src/execution/workflow-trace-context.ts
+++ b/packages/eve/src/execution/workflow-trace-context.ts
@@ -1,10 +1,10 @@
-import type { HarnessEmissionState } from "#harness/emission.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import type { ExecutionInstrumentation } from "#instrumentation/runtime.js";
import type { RuntimeTraceContext } from "#protocol/message.js";
/** Prepares native tracing for workflow-owned preambles emitted outside the tool loop. */
export async function prepareWorkflowPreambleTrace(input: {
- readonly emissionState: HarnessEmissionState;
+ readonly emissionState: TurnPosition;
readonly instrumentation: ExecutionInstrumentation | undefined;
}): Promise<RuntimeTraceContext | undefined> {
return await input.instrumentation?.preparePreamble({
diff --git a/packages/eve/src/harness/active-turn-id.test.ts b/packages/eve/src/harness/active-turn-id.test.ts
deleted file mode 100644
index 7cf7eef32..000000000
--- a/packages/eve/src/harness/active-turn-id.test.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { activeTurnId } from "#harness/active-turn-id.js";
-
-describe("activeTurnId", () => {
- it("returns the in-flight turn id when a turn is active", () => {
- expect(
- activeTurnId({ sessionStarted: true, sequence: 3, stepIndex: 1, turnId: "turn_3" }),
- ).toBe("turn_3");
- });
-
- it("mints the next turn id from the sequence between turns", () => {
- expect(activeTurnId({ sessionStarted: true, sequence: 4, stepIndex: 0, turnId: "" })).toBe(
- "turn_4",
- );
- });
-});
diff --git a/packages/eve/src/harness/active-turn-id.ts b/packages/eve/src/harness/active-turn-id.ts
deleted file mode 100644
index 858f28ce2..000000000
--- a/packages/eve/src/harness/active-turn-id.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import type { HarnessEmissionState } from "#harness/emission.js";
-
-/**
- * Returns the id of the in-flight turn, or — between turns — the id the
- * next turn will mint (`turn_${sequence}`, the same formula
- * `emitTurnPreamble` uses).
- *
- * Lives in a leaf module so `"use workflow"` bodies can import it without
- * pulling harness emission (and its Node builtins) into the workflow
- * bundle.
- */
-export function activeTurnId(state: HarnessEmissionState): string {
- return state.turnId === "" ? `turn_${state.sequence}` : state.turnId;
-}
diff --git a/packages/eve/src/harness/authorization.test.ts b/packages/eve/src/harness/authorization.test.ts
index d47813e1a..2b13e2d57 100644
--- a/packages/eve/src/harness/authorization.test.ts
+++ b/packages/eve/src/harness/authorization.test.ts
@@ -8,10 +8,10 @@ import {
consumeAuthorizationResult,
getPendingAuthorization,
getHookUrl,
- getSupersededAuthorizationChallenges,
PendingAuthorizationResultKey,
resolveActiveAuthorizationChallenges,
setPendingAuthorization,
+ supersededChallenges,
} from "#harness/authorization.js";
import type { ConnectionPrincipal } from "#shared/connection-types.js";
@@ -226,9 +226,9 @@ describe("pending authorization attempts", () => {
expect(resolveActiveAuthorizationChallenges([listTool, createTool, bobTool, approval])).toEqual(
[createTool, bobTool, approval],
);
- expect(getSupersededAuthorizationChallenges(pending, [createTool])).toEqual([
- grant("linear", "connection"),
- ]);
+ expect(
+ supersededChallenges(getPendingAuthorization(pending)?.challenges ?? [], [createTool]),
+ ).toEqual([grant("linear", "connection")]);
});
it("clears by exact attempt identity", () => {
diff --git a/packages/eve/src/harness/authorization.ts b/packages/eve/src/harness/authorization.ts
index d10bc6f03..ceb35b491 100644
--- a/packages/eve/src/harness/authorization.ts
+++ b/packages/eve/src/harness/authorization.ts
@@ -311,18 +311,27 @@ export function setPendingAuthorization(
sessionState: Record<string, unknown> | undefined,
value: PendingAuthorizationState,
): Record<string, unknown> {
- const active = resolveActiveAuthorizationChallenges(value.challenges);
- const pending = getPendingAuthorization(sessionState);
- const previous = pending?.challenges ?? [];
- const superseded = getSupersededAuthorizationChallenges(sessionState, active);
return {
...sessionState,
[PENDING_AUTHORIZATION_KEY]: {
- challenges: [...previous.filter((challenge) => !superseded.includes(challenge)), ...active],
+ challenges: withSignIns(
+ getPendingAuthorization(sessionState)?.challenges ?? [],
+ value.challenges,
+ ),
},
};
}
+/** The pending sign-ins once `challenges` are asked for: each replaces the attempt it supersedes. */
+export function withSignIns(
+ previous: readonly AuthorizationChallenge[],
+ challenges: readonly AuthorizationChallenge[],
+): readonly AuthorizationChallenge[] {
+ const active = resolveActiveAuthorizationChallenges(challenges);
+ const superseded = supersededChallenges(previous, active);
+ return [...previous.filter((challenge) => !superseded.includes(challenge)), ...active];
+}
+
/** Keeps the last challenge for each sign-in and principal. */
export function resolveActiveAuthorizationChallenges(
challenges: readonly AuthorizationChallenge[],
@@ -333,12 +342,11 @@ export function resolveActiveAuthorizationChallenges(
);
}
-/** Existing attempts replaced by newer attempts for the same sign-in and principal. */
-export function getSupersededAuthorizationChallenges(
- sessionState: Record<string, unknown> | undefined,
+/** The attempts in `previous` that `replacements` replace: the same sign-in and principal. */
+export function supersededChallenges(
+ previous: readonly AuthorizationChallenge[],
replacements: readonly AuthorizationChallenge[],
): readonly AuthorizationChallenge[] {
- const previous = getPendingAuthorization(sessionState)?.challenges ?? [];
return previous.filter((candidate) =>
replacements.some((replacement) => sameSignIn(candidate, replacement)),
);
diff --git a/packages/eve/src/harness/cancelled-turn-emission.test.ts b/packages/eve/src/harness/cancelled-turn-emission.test.ts
deleted file mode 100644
index 936cd0ec5..000000000
--- a/packages/eve/src/harness/cancelled-turn-emission.test.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { emitCancelledTurn } from "#harness/cancelled-turn-emission.js";
-import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
-
-const USAGE = {
- cacheReadTokens: 0,
- cacheWriteTokens: 0,
- costUsd: 0.5,
- inputTokens: 120,
- outputTokens: 30,
-};
-
-describe("emitCancelledTurn", () => {
- it("emits turn.cancelled → session.waiting with the session's usage and no failure events", async () => {
- const events: UnstampedMessageStreamEvent[] = [];
- const next = await emitCancelledTurn(
- async (event) => {
- events.push(event);
- },
- { sessionStarted: true, sequence: 3, stepIndex: 2, turnId: "turn_3" },
- USAGE,
- );
-
- expect(events.map((event) => event.type)).toEqual(["turn.cancelled", "session.waiting"]);
- expect(events[0]).toMatchObject({
- data: { sequence: 3, turnId: "turn_3" },
- type: "turn.cancelled",
- });
- expect(events[1]).toEqual({
- data: { continuationToken: "", usage: USAGE, wait: "next-user-message" },
- type: "session.waiting",
- });
- expect(next).toEqual({ sessionStarted: true, sequence: 4, stepIndex: 0, turnId: "" });
- });
-
- it("reconstructs the turn id when the cancelled step began the turn", async () => {
- // A first-step cancellation aborts before the preamble's state update
- // is persisted: the persisted state still has the between-turns
- // turnId "", but `turn.started` for `turn_${sequence}` is already on
- // the stream.
- const events: UnstampedMessageStreamEvent[] = [];
- const next = await emitCancelledTurn(
- async (event) => {
- events.push(event);
- },
- { sessionStarted: false, sequence: 0, stepIndex: 0, turnId: "" },
- USAGE,
- );
-
- expect(events[0]).toMatchObject({
- data: { sequence: 0, turnId: "turn_0" },
- type: "turn.cancelled",
- });
- // `session.started` was already emitted by the preamble.
- expect(next.sessionStarted).toBe(true);
- expect(next.sequence).toBe(1);
- expect(next.turnId).toBe("");
- });
-});
diff --git a/packages/eve/src/harness/cancelled-turn-emission.ts b/packages/eve/src/harness/cancelled-turn-emission.ts
deleted file mode 100644
index 26e8f6b58..000000000
--- a/packages/eve/src/harness/cancelled-turn-emission.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { createSessionWaitingEvent, createTurnCancelledEvent } from "#protocol/message.js";
-import type { HarnessEmitFn } from "#harness/types.js";
-import type { TokenUsage } from "#shared/token-usage.js";
-
-import { activeTurnId } from "#harness/active-turn-id.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
-
-/**
- * Emits the cancelled-turn epilogue: `turn.cancelled` → `session.waiting`
- * (never a failure event) and returns the between-turns emission state.
- *
- * `state` is the last *persisted* emission state, which may predate the
- * cancelled turn's preamble — the turn id is reconstructed via
- * {@link activeTurnId} and `sessionStarted` is stamped `true`.
- */
-export async function emitCancelledTurn(
- emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
- usage: TokenUsage,
-): Promise<HarnessEmissionState> {
- await emitFn(
- createTurnCancelledEvent({
- sequence: state.sequence,
- turnId: activeTurnId(state),
- }),
- );
- await emitFn(createSessionWaitingEvent(usage));
-
- return {
- sessionStarted: true,
- sequence: state.sequence + 1,
- stepIndex: 0,
- turnId: "",
- };
-}
diff --git a/packages/eve/src/harness/compaction.test.ts b/packages/eve/src/harness/compaction/engine.test.ts
similarity index 99%
rename from packages/eve/src/harness/compaction.test.ts
rename to packages/eve/src/harness/compaction/engine.test.ts
index 04e180793..49ca49214 100644
--- a/packages/eve/src/harness/compaction.test.ts
+++ b/packages/eve/src/harness/compaction/engine.test.ts
@@ -1,13 +1,13 @@
import type { ModelMessage } from "ai";
import { afterEach, describe, expect, it, vi } from "vitest";
-import { COMPACTION_PROMPT_ENVELOPE } from "#harness/compaction-prompt.js";
+import { COMPACTION_PROMPT_ENVELOPE } from "#harness/compaction/prompt.js";
import {
compactMessages,
getInputTokenCount,
resolveCompactionModel,
shouldCompact,
-} from "#harness/compaction.js";
+} from "#harness/compaction/engine.js";
import { createFrameworkUserMessage } from "#harness/messages.js";
import { estimateTokens } from "#harness/token-estimate.js";
import type { CompactionConfig } from "#harness/types.js";
diff --git a/packages/eve/src/harness/compaction.ts b/packages/eve/src/harness/compaction/engine.ts
similarity index 99%
rename from packages/eve/src/harness/compaction.ts
rename to packages/eve/src/harness/compaction/engine.ts
index f41c9bdcd..771fdb742 100644
--- a/packages/eve/src/harness/compaction.ts
+++ b/packages/eve/src/harness/compaction/engine.ts
@@ -8,7 +8,7 @@ import {
sliceUtf16Safe,
stubContentOutputFileParts,
TRANSCRIPT_PAYLOAD_LIMIT,
-} from "#harness/compaction-prompt.js";
+} from "#harness/compaction/prompt.js";
import { createFrameworkUserMessage, isFrameworkUserMessage } from "#harness/messages.js";
import { estimateTokens } from "#harness/token-estimate.js";
import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
diff --git a/packages/eve/src/harness/compaction-prompt.test.ts b/packages/eve/src/harness/compaction/prompt.test.ts
similarity index 99%
rename from packages/eve/src/harness/compaction-prompt.test.ts
rename to packages/eve/src/harness/compaction/prompt.test.ts
index b2c2e100c..22794a746 100644
--- a/packages/eve/src/harness/compaction-prompt.test.ts
+++ b/packages/eve/src/harness/compaction/prompt.test.ts
@@ -6,7 +6,7 @@ import {
createCompactionPrompt,
sliceUtf16Safe,
TRANSCRIPT_PAYLOAD_LIMIT,
-} from "#harness/compaction-prompt.js";
+} from "#harness/compaction/prompt.js";
describe("createCompactionPrompt", () => {
it("preserves the previous checkpoint without applying transcript truncation", () => {
diff --git a/packages/eve/src/harness/compaction-prompt.ts b/packages/eve/src/harness/compaction/prompt.ts
similarity index 100%
rename from packages/eve/src/harness/compaction-prompt.ts
rename to packages/eve/src/harness/compaction/prompt.ts
diff --git a/packages/eve/src/harness/compaction/step.ts b/packages/eve/src/harness/compaction/step.ts
new file mode 100644
index 000000000..21af2f0a4
--- /dev/null
+++ b/packages/eve/src/harness/compaction/step.ts
@@ -0,0 +1,259 @@
+import type { LanguageModel, TelemetryOptions } from "ai";
+
+import { createLogger, logError } from "#internal/logging.js";
+import { AuthKey, HistoryStateKey } from "#context/keys.js";
+import {
+ type CompactionConfig,
+ type HarnessSession,
+ requireSessionModelReference,
+ type StepResult,
+ type ToolLoopHarnessConfig,
+} from "#harness/types.js";
+import { type HarnessModelMessage, validateHarnessModelMessages } from "#harness/messages.js";
+import type { HistoryViewProjector } from "#shared/history-view.js";
+import type { Publish } from "#harness/session-machine/commit.js";
+import type { SessionAuthContext } from "#channel/types.js";
+import type { Step } from "#harness/step/context.js";
+import { activeTurnId, type TurnPosition } from "#harness/session-machine/view.js";
+import {
+ buildGatewayAttributionHeaders,
+ resolveEffectiveRuntimeModel,
+} from "#harness/model-call/model.js";
+import { canonicalizeMemoryRecords, shouldCanonicalizeMemory } from "#shared/memory-state.js";
+import {
+ compactMessages,
+ getInputTokenCount,
+ resolveCompactionModel,
+ shouldCompact,
+} from "#harness/compaction/engine.js";
+import { contextStorage } from "#context/container.js";
+import {
+ createCompactionCompletedEvent,
+ createCompactionRequestedEvent,
+} from "#protocol/message.js";
+import { drainMemoryCommit, prepareMemoryCompaction } from "#context/memory-lifecycle.js";
+import { gatewayModelId } from "#harness/model-call/usage.js";
+import { getRequestEnvelopeTokens } from "#harness/request-envelope.js";
+import { idle } from "#harness/session-machine/transitions.js";
+import { resolveCallProviderOptions } from "#harness/provider-safety.js";
+import { resolveConversationId } from "#shared/conversation-identity.js";
+
+const log = createLogger("harness.tool-loop");
+/**
+ * Processes the step result: extracts input requests, decides whether to
+ * park, continue the tool loop, or terminate.
+ */
+/** What a step needs from the machine after its model call. */
+/** `session.compact()`: summarizes the history now, then the session waits. */
+export async function compactHistory(step: Step): Promise<StepResult> {
+ const { config } = step;
+ if (step.session.history.length > 0) {
+ try {
+ const resolvedModel = await resolveEffectiveRuntimeModel({
+ config,
+ ctx: step.ctx,
+ session: step.session,
+ });
+ step.session = resolvedModel.session;
+ const position = step.position();
+ const compacted = await maybeCompact({
+ abortSignal: config.abortSignal,
+ auth: step.ctx?.get(AuthKey) ?? null,
+ emissionState: { ...position, turnId: activeTurnId(position) },
+ force: true,
+ historyProjector: config.historyProjector,
+ messages: [...step.session.history],
+ model: resolvedModel.model,
+ publish: step.publish,
+ requestEnvelopeTokens: getRequestEnvelopeTokens(step.session),
+ resolveModel: config.resolveModel,
+ runtimeIdentity: config.runtimeIdentity,
+ session: step.session,
+ telemetry: step.instrumentation?.telemetry(),
+ });
+ step.session = compacted.session;
+ } catch (error) {
+ logError(log, "manual session compaction failed", error, {
+ sessionId: step.session.sessionId,
+ });
+ }
+ }
+ await step.apply(idle(step.view()));
+ return { next: null, session: step.session };
+}
+
+export function replaceSessionHistory(
+ session: HarnessSession,
+ history: HarnessModelMessage[],
+): HarnessSession {
+ contextStorage.getStore()?.delete(HistoryStateKey);
+ return {
+ ...session,
+ history,
+ compaction: {
+ recentWindowSize: session.compaction.recentWindowSize,
+ threshold: session.compaction.threshold,
+ thresholdPercent: session.compaction.thresholdPercent,
+ },
+ };
+}
+
+/**
+ * Runs the compaction pipeline once if the session's input-token estimate
+ * is over the configured threshold. Mutates neither input; returns the new
+ * messages array and (possibly updated) session.
+ *
+ * Kept in the tool-loop (rather than the AI SDK's `prepareStep` hook) so
+ * the compacted messages flow through the same `messages` variable the
+ * harness uses to rebuild `session.history` after the step.
+ */
+export async function maybeCompact(input: {
+ readonly abortSignal?: AbortSignal;
+ readonly auth: SessionAuthContext | null;
+ readonly emissionState: TurnPosition;
+ readonly force?: boolean;
+ readonly historyProjector?: HistoryViewProjector;
+ readonly messages: HarnessModelMessage[];
+ readonly model: LanguageModel;
+ readonly publish: Publish;
+ /** Model-visible prompt used only to decide whether durable history needs compaction. */
+ readonly promptMessages?: readonly HarnessModelMessage[];
+ readonly requestEnvelopeTokens?: number;
+ readonly resolveModel: ToolLoopHarnessConfig["resolveModel"];
+ readonly runtimeIdentity?: ToolLoopHarnessConfig["runtimeIdentity"];
+ readonly session: HarnessSession;
+ readonly telemetry?: TelemetryOptions;
+}): Promise<{
+ readonly compacted: boolean;
+ readonly messages: HarnessModelMessage[];
+ readonly session: HarnessSession;
+}> {
+ const { emissionState, publish } = input;
+ let messages = input.messages;
+ let session = input.session;
+ const promptMessages = input.promptMessages ?? messages;
+ const projectedPromptMessages = validateHarnessModelMessages(
+ input.historyProjector?.({ messages: promptMessages, state: session.state }) ?? promptMessages,
+ );
+ const needsSummary =
+ input.force === true ||
+ shouldCompact(
+ projectedPromptMessages,
+ session.compaction,
+ input.requestEnvelopeTokens,
+ getRequestEnvelopeTokens(session),
+ );
+ const needsMemoryCanonicalization = shouldCanonicalizeMemory(messages);
+
+ if (!needsSummary && !needsMemoryCanonicalization) {
+ return { compacted: false, messages, session };
+ }
+
+ const compaction = await resolveCompactionModel({
+ compactionModelReference: session.agent.compactionModelReference,
+ model: input.model,
+ modelReference: requireSessionModelReference(session),
+ resolveModel: input.resolveModel,
+ });
+ const compactionModelReference =
+ session.agent.compactionModelReference ?? requireSessionModelReference(session);
+ const providerOptions = resolveCallProviderOptions({
+ auth: input.auth,
+ conversationId: resolveConversationId(session.rootSessionId ?? session.sessionId),
+ model: compaction.model,
+ modelReference: compactionModelReference,
+ providerOptions: compaction.providerOptions,
+ }) as Parameters<typeof compactMessages>[3];
+
+ {
+ const ctx = contextStorage.getStore();
+ if (ctx !== undefined) {
+ prepareMemoryCompaction(ctx, { history: messages, state: session.state });
+ }
+ await publish(
+ createCompactionRequestedEvent({
+ modelId: gatewayModelId(compaction.model) ?? "unknown",
+ sequence: emissionState.sequence,
+ sessionId: session.sessionId,
+ stepIndex: emissionState.stepIndex,
+ turnId: emissionState.turnId,
+ usageInputTokens: getInputTokenCount(
+ projectedPromptMessages,
+ session.compaction,
+ input.requestEnvelopeTokens,
+ getRequestEnvelopeTokens(session),
+ ),
+ }),
+ projectedPromptMessages,
+ );
+ }
+
+ const canonical = canonicalizeMemoryRecords(messages);
+ const ordinary = validateHarnessModelMessages(
+ input.historyProjector?.({ messages: canonical.ordinary, state: session.state }) ??
+ canonical.ordinary,
+ );
+ const requestEnvelopeTokens = input.requestEnvelopeTokens ?? 0;
+ const historyCompaction: CompactionConfig = {
+ ...session.compaction,
+ threshold: Math.max(1, session.compaction.threshold - requestEnvelopeTokens),
+ lastKnownInputTokens:
+ session.compaction.lastKnownInputTokens === undefined
+ ? undefined
+ : Math.max(
+ 0,
+ session.compaction.lastKnownInputTokens -
+ Math.min(getRequestEnvelopeTokens(session) ?? 0, requestEnvelopeTokens),
+ ),
+ };
+ const compactedOrdinary = needsSummary
+ ? await compactMessages(
+ [...ordinary],
+ compaction.model,
+ historyCompaction,
+ providerOptions,
+ input.telemetry,
+ buildGatewayAttributionHeaders(compaction.model, input.runtimeIdentity),
+ input.abortSignal,
+ input.force === true,
+ input.requestEnvelopeTokens === undefined
+ ? undefined
+ : Math.max(
+ 0,
+ getInputTokenCount(
+ projectedPromptMessages,
+ session.compaction,
+ requestEnvelopeTokens,
+ getRequestEnvelopeTokens(session),
+ ) - requestEnvelopeTokens,
+ ),
+ )
+ : [...ordinary];
+ messages = validateHarnessModelMessages([...canonical.memory, ...compactedOrdinary]);
+
+ {
+ const ctx = contextStorage.getStore();
+ if (ctx !== undefined) {
+ prepareMemoryCompaction(ctx, { history: messages, state: session.state });
+ }
+ await publish(
+ createCompactionCompletedEvent({
+ modelId: gatewayModelId(compaction.model) ?? "unknown",
+ sequence: emissionState.sequence,
+ sessionId: session.sessionId,
+ stepIndex: emissionState.stepIndex,
+ turnId: emissionState.turnId,
+ }),
+ input.historyProjector?.({ messages, state: session.state }) ?? messages,
+ );
+ if (ctx !== undefined) {
+ const commit = drainMemoryCommit(ctx);
+ if (commit !== undefined) {
+ messages = validateHarnessModelMessages([...messages, ...commit.recalledMessages]);
+ session = { ...session, state: commit.state };
+ }
+ }
+ }
+
+ return { compacted: true, messages, session: replaceSessionHistory(session, messages) };
+}
diff --git a/packages/eve/src/harness/coordination.test.ts b/packages/eve/src/harness/coordination.test.ts
index 3f6daed28..ca92e88a4 100644
--- a/packages/eve/src/harness/coordination.test.ts
+++ b/packages/eve/src/harness/coordination.test.ts
@@ -1,11 +1,12 @@
import { describe, expect, it } from "vitest";
import { createPresentedRuntimeActionRequestFromToolCall } from "#harness/action-presentation.js";
import {
+ assertUniqueCoordinationCallIds,
createCoordinationRequestFromToolCall,
createRuntimeActionRequestFromToolCall,
- resolvePendingCoordination,
+ forgetFinishedRuns,
resolveToolCallInputObject,
- setPendingCoordinationBatch,
+ runtimeResultCalls,
} from "#harness/coordination.js";
import {
getBlockingWorkflowToolRuns,
@@ -13,12 +14,17 @@ import {
} from "#harness/workflow-tool-runs.js";
import { toolOutput } from "#tools/model-output.js";
+import { getProxyInputRequests, upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
import { setTurnUsageState } from "#harness/turn-tag-state.js";
import type { HarnessSession } from "#harness/types.js";
import { isRuntimeWorkflowToolAction } from "#shared/action-types.js";
import { createPreparedWorkflowToolHarnessDefinition } from "#execution/tools/workflow/harness-definition.js";
import type { PreparedRuntimeDelegationTool } from "#runtime/sessions/turn.js";
+const REQUEST_EVENT = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+
+const CHILD_CONTINUATION_TOKEN = "subagent:private-token";
+
describe("createRuntimeActionRequestFromToolCall", () => {
it.each(["subagent", "remote"] as const)(
"retains %s dispatch identity for a background agent tool",
@@ -303,22 +309,7 @@ function createParkedSession(): HarnessSession {
turnId: "turn_0",
});
- return setPendingCoordinationBatch({
- tasks: [
- {
- callId: "call-1",
- executeInput: { message: "go", target: "researcher" },
- input: { description: "Research the topic", message: "go" },
- entry: { entryPoint: "execute" },
- kind: "workflow-task",
- toolName: "researcher",
- workflowId: "workflow://subagent-tool",
- },
- ],
- event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
- responseMessages: [],
- session: withUsage,
- });
+ return withUsage;
}
describe("coordination batch identity", () => {
@@ -333,70 +324,63 @@ describe("coordination batch identity", () => {
workflowId: "workflow://subagent-tool",
};
- expect(() =>
- setPendingCoordinationBatch({
- tasks: [task, { ...task, toolName: "other" }],
- event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
- responseMessages: [],
- session: createParkedSession(),
- }),
- ).toThrow('duplicate callId "duplicate-call"');
+ expect(() => assertUniqueCoordinationCallIds([task, { ...task, toolName: "other" }])).toThrow(
+ 'duplicate callId "duplicate-call"',
+ );
});
});
-describe("resolvePendingCoordination", () => {
- it("forgets a finished workflow tool run", async () => {
- const parked = setPendingCoordinationBatch({
- event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
- responseMessages: [],
- session: createParkedSession(),
- tasks: [
- {
- callId: "call-1",
- input: { service: "api" },
- entry: { entryPoint: "execute" },
- kind: "workflow-task",
- toolName: "deploy",
- workflowId: "workflow//./agent/tools/deploy//execute",
- },
- ],
- });
- const session = registerWorkflowToolRun(parked, {
+describe("runtime results", () => {
+ it("forgets a finished workflow tool run and names only its requests for withdrawal", () => {
+ const withRun = registerWorkflowToolRun(createParkedSession(), {
callId: "call-1",
toolName: "deploy",
origin: { turnId: "turn_0", stepIndex: 0 },
address: { runId: "run-1", hookToken: "eve:workflow-tool-run:op-1" },
});
-
- const resolved = await resolvePendingCoordination({
- session,
- stepInput: {
- runtimeActionResults: [
- { callId: "call-1", kind: "tool-result", output: { deployed: true }, toolName: "deploy" },
+ const answerToken = "eve:workflow-tool-run-answer:run-1:0";
+ const session = upsertProxyInputRequests({
+ entries: [
+ [
+ "other-request",
+ {
+ childContinuationToken: CHILD_CONTINUATION_TOKEN,
+ event: REQUEST_EVENT,
+ kind: "question",
+ },
],
- },
+ ],
+ forChildContinuationToken: CHILD_CONTINUATION_TOKEN,
+ session: upsertProxyInputRequests({
+ entries: [
+ [
+ answerToken,
+ {
+ runId: "run-1",
+ workflowAsk: { control: "control", question: {} },
+ childContinuationToken: answerToken,
+ event: REQUEST_EVENT,
+ kind: "question",
+ },
+ ],
+ ],
+ forChildContinuationToken: answerToken,
+ session: withRun,
+ }),
});
- expect(resolved.outcome).toBe("resolved");
- expect(getBlockingWorkflowToolRuns(resolved.session.state)).toEqual([]);
+ const finished = forgetFinishedRuns(
+ session,
+ [{ callId: "call-1", kind: "tool-result", output: { deployed: true }, toolName: "deploy" }],
+ "turn_0",
+ );
+
+ expect(getBlockingWorkflowToolRuns(finished.session.state)).toEqual([]);
+ expect(finished.requestIds).toEqual([answerToken]);
+ expect([...getProxyInputRequests(finished.session.state).keys()]).toContain("other-request");
});
it("projects a workflow tool's result through its toModelOutput", async () => {
- const parked = setPendingCoordinationBatch({
- event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
- responseMessages: [],
- session: createParkedSession(),
- tasks: [
- {
- callId: "call-1",
- input: { service: "api" },
- entry: { entryPoint: "execute" },
- kind: "workflow-task",
- toolName: "deploy",
- workflowId: "workflow//./agent/tools/deploy//execute",
- },
- ],
- });
const tools = new Map([
[
"deploy",
@@ -410,25 +394,20 @@ describe("resolvePendingCoordination", () => {
],
]);
- const resolved = await resolvePendingCoordination({
- session: parked,
- stepInput: {
- runtimeActionResults: [
- {
- callId: "call-1",
- kind: "tool-result",
- output: { deployed: true, url: "https://api.example" },
- toolName: "deploy",
- },
- ],
- },
+ const [settled] = await runtimeResultCalls(
+ [
+ {
+ callId: "call-1",
+ kind: "tool-result",
+ output: { deployed: true, url: "https://api.example" },
+ toolName: "deploy",
+ },
+ ],
tools,
- });
+ );
- const toolMessage = resolved.messages.at(-1);
- expect(toolMessage?.role).toBe("tool");
- expect(JSON.stringify(toolMessage?.content)).toContain("deployed to https://api.example");
- expect(JSON.stringify(toolMessage?.content)).not.toContain('"deployed":true');
+ expect(JSON.stringify(settled?.part.output)).toContain("deployed to https://api.example");
+ expect(JSON.stringify(settled?.part.output)).not.toContain('"deployed":true');
});
});
diff --git a/packages/eve/src/harness/coordination.ts b/packages/eve/src/harness/coordination.ts
index 4dc007d72..f3ca4ea1d 100644
--- a/packages/eve/src/harness/coordination.ts
+++ b/packages/eve/src/harness/coordination.ts
@@ -1,8 +1,5 @@
-import type { SessionAuthContext } from "#channel/types.js";
import type { ModelMessage } from "ai";
-import { createActionResultEvent } from "#protocol/message.js";
-import { resolveRuntimeActionResultsForCallIds } from "#runtime/actions/results.js";
import type {
RuntimeActionRequest,
RuntimeActionResult,
@@ -11,174 +8,19 @@ import type {
} from "#shared/action-types.js";
import { markRuntimeWorkflowToolAction } from "#shared/action-types.js";
import { parseJsonObject, type JsonObject } from "#shared/json.js";
+import { getProxyInputRequests } from "#harness/proxy-input-requests.js";
import {
findBlockingWorkflowToolRun,
removeBlockingWorkflowToolRuns,
} 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 { commitCallEntry, isTaskTool } from "#execution/tasks/model-step.js";
import { startsTasks } from "#execution/tasks/tool-entry-point.js";
-import type {
- HarnessEmitFn,
- HarnessSession,
- HarnessToolMap,
- SessionStateMap,
- StepInput,
-} from "#harness/types.js";
-
-const PENDING_COORDINATION_BATCH_KEY = "eve.runtime.pendingCoordinationBatch";
+import type { HarnessSession, HarnessToolMap } from "#harness/types.js";
type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
type ToolResultPart = Extract<ToolResponsePart, { type: "tool-result" }>;
-/**
- * Serializable event coordinates for one pending coordination batch.
- *
- * Runtime action results are projected back onto the parent stream using the
- * same turn and step identity as the originating `actions.requested` batch.
- */
-interface PendingCoordinationEventMetadata {
- readonly sequence: number;
- readonly stepIndex: number;
- readonly turnId: string;
-}
-
-/** Serializable pending coordination batch stored on `session.state`. */
-export interface PendingCoordinationBatch {
- /** Who approved each call this batch runs for an approval, by call id. */
- readonly approvers?: Readonly<Record<string, SessionAuthContext>>;
- /** Workflow tool runs pending coordination, including agent tools. */
- readonly tasks: readonly RuntimeWorkflowTaskRequest[];
- readonly event: PendingCoordinationEventMetadata;
- readonly responseMessages: readonly ModelMessage[];
-}
-
-/**
- * Outcome of resolving a pending coordination batch.
- */
-interface ResolvePendingCoordinationResult {
- readonly messages: ModelMessage[];
- readonly outcome: "continue" | "resolved" | "unresolved";
- readonly session: HarnessSession;
-}
-
-/** Returns the pending coordination batch stored on the session, if any. */
-export function getPendingCoordinationBatch(
- state: SessionStateMap | undefined,
-): PendingCoordinationBatch | undefined {
- const value = state?.[PENDING_COORDINATION_BATCH_KEY];
-
- if (typeof value !== "object" || value === null) {
- return undefined;
- }
-
- const batch = value as PendingCoordinationBatch;
-
- if (
- !Array.isArray(batch.tasks) ||
- !Array.isArray(batch.responseMessages) ||
- typeof batch.event !== "object" ||
- batch.event === null
- ) {
- return undefined;
- }
-
- return batch;
-}
-
-export function clearPendingCoordinationBatch(session: HarnessSession): HarnessSession {
- if (session.state?.[PENDING_COORDINATION_BATCH_KEY] === undefined) {
- return session;
- }
- const state = { ...session.state };
- delete state[PENDING_COORDINATION_BATCH_KEY];
- return { ...session, state: Object.keys(state).length > 0 ? state : undefined };
-}
-
-/** What the model reads for a call its turn's cancellation stopped before the call settled. */
-export const CANCELLED_CALL_RESULT = "The turn was cancelled before this call finished.";
-
-/**
- * Moves a cancelled turn's pending batch into history instead of dropping it.
- * The model keeps the calls it made, each answered as cancelled, so it sees
- * that the work started and stopped rather than a request left unanswered.
- */
-export function commitCancelledCoordinationBatch(session: HarnessSession): HarnessSession {
- 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,
- toolName: call.kind,
- })),
- ];
- const cancelledResults = cancelledCalls.map(({ callId, toolName }): ToolResultPart => ({
- output: { type: "text", value: CANCELLED_CALL_RESULT },
- toolCallId: callId,
- toolName,
- type: "tool-result",
- }));
- const history = validateHarnessModelMessages([
- ...session.history,
- ...batch.responseMessages,
- ...(cancelledResults.length === 0
- ? []
- : [{ content: cancelledResults, role: "tool" as const }]),
- ]);
- 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.
- */
-export function setPendingCoordinationBatch<T extends { readonly state?: SessionStateMap }>(input: {
- readonly approvers?: PendingCoordinationBatch["approvers"];
- readonly tasks: readonly RuntimeWorkflowTaskRequest[];
- readonly event: PendingCoordinationEventMetadata;
- readonly responseMessages: readonly ModelMessage[];
- readonly session: T;
-}): T {
- assertUniqueCoordinationCallIds(input.tasks);
- const state = { ...input.session.state };
- state[PENDING_COORDINATION_BATCH_KEY] = {
- ...(input.approvers !== undefined && { approvers: input.approvers }),
- tasks: [...input.tasks],
- event: input.event,
- responseMessages: [...input.responseMessages],
- } satisfies PendingCoordinationBatch;
-
- return { ...input.session, state };
-}
-
/** Rejects a batch before any result or side effect can bind ambiguously by call id. */
export function assertUniqueCoordinationCallIds(
requests: readonly { readonly callId: string }[],
@@ -193,152 +35,112 @@ export function assertUniqueCoordinationCallIds(
}
/**
- * Returns the ordered results for the current pending coordination batch when
- * every request has a matching result. Unknown and duplicate results
- * are ignored.
- */
-function resolveReadyCoordinationResults(input: {
- readonly results: readonly RuntimeActionResult[];
- readonly session: HarnessSession;
-}): RuntimeActionResult[] | undefined {
- const batch = getPendingCoordinationBatch(input.session.state);
-
- if (batch === undefined) {
- return undefined;
- }
-
- return resolveRuntimeActionResultsForCallIds({
- pendingCallIds: pendingCoordinationCallIds(batch),
- results: input.results,
- });
-}
-
-/** Every call a pending batch waits on: workflow runs and task tool calls. */
-export function pendingCoordinationCallIds(batch: PendingCoordinationBatch): readonly string[] {
- const taskToolCallIds = pendingTaskToolCalls(batch.responseMessages).map((call) => call.callId);
- return [...batch.tasks.map((request) => request.callId), ...taskToolCallIds];
-}
-
-/**
- * Resolves one pending coordination batch back into model history.
- *
- * When all expected runtime action results are present, this appends the
- * stored assistant tool-call messages plus synthesized tool-result messages to
- * history, clears the pending batch, and emits `action.result` events back
- * onto the parent stream.
+ * Forgets the workflow runs whose results arrived. Nobody can answer what a finished run asked,
+ * so its relayed requests are returned for the machine to withdraw.
*/
-export async function resolvePendingCoordination(input: {
- readonly emit?: HarnessEmitFn;
- readonly session: HarnessSession;
- readonly stepInput?: StepInput;
- /** Definitions whose `toModelOutput` projects a workflow tool's result for the model. */
- readonly tools?: HarnessToolMap;
-}): Promise<ResolvePendingCoordinationResult> {
- const batch = getPendingCoordinationBatch(input.session.state);
-
- if (batch === undefined) {
- return {
- messages: [...input.session.history],
- outcome: "continue",
- session: input.session,
- };
- }
-
- const readyResults = resolveReadyCoordinationResults({
- results: input.stepInput?.runtimeActionResults ?? [],
- session: input.session,
- });
-
- if (readyResults === undefined) {
- return {
- messages: [...input.session.history],
- outcome: "unresolved",
- session: input.session,
- };
- }
-
- let nextSession: HarnessSession = input.session;
- // The session withdrew each finished run's open questions when its outcome arrived.
- for (const result of readyResults) {
+export function forgetFinishedRuns(
+ session: HarnessSession,
+ results: readonly RuntimeActionResult[],
+ turnId: string,
+): { readonly requestIds: readonly string[]; readonly session: HarnessSession } {
+ let next = session;
+ const requestIds: string[] = [];
+ for (const result of results) {
if (result.kind !== "tool-result") continue;
- const record = findBlockingWorkflowToolRun(
- nextSession.state,
- result.callId,
- batch.event.turnId,
- );
+ const record = findBlockingWorkflowToolRun(next.state, result.callId, turnId);
if (record === undefined) continue;
- nextSession = removeBlockingWorkflowToolRuns(nextSession, batch.event.turnId, record.callId);
- }
-
- const state = { ...nextSession.state };
- delete state[PENDING_COORDINATION_BATCH_KEY];
- nextSession = {
- ...nextSession,
- state: Object.keys(state).length > 0 ? state : undefined,
- };
-
- if (input.emit !== undefined) {
- for (const result of readyResults) {
- await input.emit(
- createActionResultEvent({
- result,
- sequence: batch.event.sequence,
- stepIndex: batch.event.stepIndex,
- turnId: batch.event.turnId,
- }),
- );
+ for (const [requestId, route] of getProxyInputRequests(next.state)) {
+ if (route.runId === record.address.runId) requestIds.push(requestId);
}
+ next = removeBlockingWorkflowToolRuns(next, turnId, record.callId);
}
+ return { requestIds, session: next };
+}
- const toolResults: ToolResultPart[] = [];
- for (const result of readyResults) {
+/** Each runtime result as the model reads it, beside the result the stream reports. */
+export async function runtimeResultCalls(
+ results: readonly RuntimeActionResult[],
+ tools: HarnessToolMap | undefined,
+): Promise<{ readonly part: ToolResultPart; readonly result: RuntimeActionResult }[]> {
+ const settled: { part: ToolResultPart; result: RuntimeActionResult }[] = [];
+ for (const result of results) {
switch (result.kind) {
case "load-skill-result":
- toolResults.push({
- output: toToolResultOutput(result),
- toolCallId: result.callId,
- toolName: "load_skill",
- type: "tool-result",
+ settled.push({
+ part: toolResult(result, "load_skill", toToolResultOutput(result)),
+ result,
});
continue;
case "subagent-result":
- toolResults.push({
- output: toToolResultOutput(result),
- toolCallId: result.callId,
- toolName: result.subagentName,
- type: "tool-result",
+ settled.push({
+ part: toolResult(result, result.subagentName, toToolResultOutput(result)),
+ result,
});
continue;
case "tool-result":
- toolResults.push({
- output: await projectToolResultOutput(result, input.tools?.get(result.toolName)),
- toolCallId: result.callId,
- toolName: result.toolName,
- type: "tool-result",
+ settled.push({
+ part: toolResult(
+ result,
+ result.toolName,
+ await projectToolResultOutput(result, tools?.get(result.toolName)),
+ ),
+ result,
});
continue;
}
-
throw new Error(`Unsupported runtime action result kind "${String(result)}".`);
}
+ return settled;
+}
- const messages = [...nextSession.history, ...batch.responseMessages];
+function toolResult(
+ result: RuntimeActionResult,
+ toolName: string,
+ output: ToolResultPart["output"],
+): ToolResultPart {
+ return { output, toolCallId: result.callId, toolName, type: "tool-result" };
+}
- if (toolResults.length > 0) {
- // 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" });
- }
+/**
+ * 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 {
- messages,
- outcome: "resolved",
- session: nextSession,
- };
+ return { session, workflowRequests };
}
/** The parts of a model tool call that coordination turns into a runtime request. */
diff --git a/packages/eve/src/harness/current-messages.test.ts b/packages/eve/src/harness/current-messages.test.ts
index c2922d430..df38072b5 100644
--- a/packages/eve/src/harness/current-messages.test.ts
+++ b/packages/eve/src/harness/current-messages.test.ts
@@ -134,41 +134,6 @@ describe("createCurrentMessages", () => {
]);
});
- it("defers announcements when history ends with an approval response", () => {
- const approvalTail = {
- role: "tool" as const,
- content: [
- {
- approvalId: "approval-1",
- approved: true,
- type: "tool-approval-response" as const,
- },
- ],
- };
- const current = createCurrentMessages([
- { role: "user", content: "history", kind: "user" },
- {
- role: "assistant",
- content: [
- { type: "tool-call", toolCallId: "call-1", toolName: "bash", input: {} },
- { type: "tool-approval-request", approvalId: "approval-1", toolCallId: "call-1" },
- ],
- },
- approvalTail,
- ]);
-
- current.addAnnouncements({
- availableSkills: "skills",
- keyed: { connections: { value: "[]", render: () => "connections" } },
- });
-
- // A system-message fallback would change the cached prefix; nothing is
- // recorded, so the next step appends both announcements.
- expect(current.systemMessages).toEqual([]);
- expect(current.nonSystemMessages.at(-1)).toBe(approvalTail);
- expect(current.historyState).toEqual({});
- });
-
it("keeps hierarchy-sensitive context in instructions when requested", () => {
const current = createCurrentMessages([]);
diff --git a/packages/eve/src/harness/current-messages.ts b/packages/eve/src/harness/current-messages.ts
index f3f3ff39f..8a4e12e08 100644
--- a/packages/eve/src/harness/current-messages.ts
+++ b/packages/eve/src/harness/current-messages.ts
@@ -1,4 +1,4 @@
-import type { ModelMessage, SystemModelMessage } from "ai";
+import type { SystemModelMessage } from "ai";
import type { HistoryState } from "#context/keys.js";
import type { Announcement } from "#harness/announcements.js";
@@ -58,12 +58,6 @@ export function createCurrentMessages(
let userInsertionIndex = currentTurnInsertionIndex ?? nonSystemMessages.length;
const currentInputIndex = history.findIndex((message) => currentTurnMessages.has(message));
let historyInsertionIndex = currentInputIndex === -1 ? history.length : currentInputIndex;
- // The AI SDK collects approval responses only from the tail tool message.
- // Appending user-role context there would skip the approved tool's
- // execution and send the provider a tool call with no result.
- const canAppendUserMessages =
- currentTurnInsertionIndex !== undefined || !hasTailApprovalResponse(nonSystemMessages);
-
function appendUserMessage(message: string, kind: FrameworkMessageKind): void {
const entry = createFrameworkUserMessage(kind, message);
nonSystemMessages.splice(userInsertionIndex, 0, entry);
@@ -77,7 +71,7 @@ export function createCurrentMessages(
kind: FrameworkMessageKind,
{ cacheFriendly = true }: AddCurrentMessageOptions = {},
): void {
- if (cacheFriendly && canAppendUserMessages) {
+ if (cacheFriendly) {
appendUserMessage(message, kind);
return;
}
@@ -87,9 +81,6 @@ export function createCurrentMessages(
return {
add,
addAnnouncements(announcements) {
- // A system-message fallback would change the cached prefix; the next
- // step appends the announcement instead.
- if (!canAppendUserMessages) return;
const skills = announcements.availableSkills;
if (skills !== undefined && skills.length > 0 && historyState.availableSkills !== skills) {
appendUserMessage(skills, "context.state");
@@ -122,11 +113,3 @@ export function createCurrentMessages(
},
};
}
-
-/** True when the history ends with a tool message carrying a tool-approval-response. */
-export function hasTailApprovalResponse(messages: readonly ModelMessage[]): boolean {
- const tail = messages.at(-1);
- return (
- tail?.role === "tool" && tail.content.some((part) => part.type === "tool-approval-response")
- );
-}
diff --git a/packages/eve/src/harness/emission-state.ts b/packages/eve/src/harness/emission-state.ts
deleted file mode 100644
index d7dd643f1..000000000
--- a/packages/eve/src/harness/emission-state.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-import type { HarnessSession, SessionStateMap } from "#harness/types.js";
-import { clearTurnClientContextState } from "#harness/turn-client-context.js";
-
-/**
- * Tracks emission lifecycle state across harness step invocations.
- *
- * Persisted on `session.state` so the state survives when the durable
- * workflow runtime recreates the harness at each `"use step"` boundary.
- */
-export interface HarnessEmissionState {
- readonly assistantOutputStarted?: boolean;
- readonly sessionStarted: boolean;
- readonly sequence: number;
- readonly stepIndex: number;
- readonly turnId: string;
-}
-
-const HARNESS_EMISSION_STATE_KEY = "eve.harness.emission";
-
-const DEFAULT_EMISSION_STATE: HarnessEmissionState = {
- sessionStarted: false,
- sequence: 0,
- stepIndex: 0,
- turnId: "",
-};
-
-/** A turn's id and sequence. */
-export interface HarnessTurnRef {
- readonly id: string;
- readonly sequence: number;
-}
-
-/**
- * The open turn, or else the last completed one (the epilogue advances the
- * sequence past it). `undefined` before the first turn.
- */
-export function lastHarnessTurn(state: SessionStateMap | undefined): HarnessTurnRef | undefined {
- const { sequence, turnId } = getHarnessEmissionState(state);
- if (turnId !== "") return { id: turnId, sequence };
- return sequence === 0 ? undefined : { id: `turn_${sequence - 1}`, sequence: sequence - 1 };
-}
-
-/** Reads the emission state, returning defaults when absent. */
-export function getHarnessEmissionState(state: SessionStateMap | undefined): HarnessEmissionState {
- const emissionState = state?.[HARNESS_EMISSION_STATE_KEY] as HarnessEmissionState | undefined;
- return emissionState ?? DEFAULT_EMISSION_STATE;
-}
-
-/**
- * Returns `true` when the harness is between turns — either no turn has
- * started yet or the previous turn has emitted its epilogue and reset.
- *
- * The empty `turnId` sentinel distinguishes a fresh delivery from an in-flight
- * continuation. Callers should use this predicate instead of reading it.
- */
-export function isHarnessBetweenTurns(session: HarnessSession): boolean {
- return getHarnessEmissionState(session.state).turnId === "";
-}
-
-/** Writes the emission state onto a new copy of the session. */
-export function setHarnessEmissionState(
- session: HarnessSession,
- state: HarnessEmissionState,
-): HarnessSession {
- const scopedSession = state.turnId === "" ? clearTurnClientContextState(session) : session;
- return {
- ...scopedSession,
- state: {
- ...scopedSession.state,
- [HARNESS_EMISSION_STATE_KEY]: state,
- },
- };
-}
diff --git a/packages/eve/src/harness/emission.test.ts b/packages/eve/src/harness/emission.test.ts
index 5d1aad5db..923f1d310 100644
--- a/packages/eve/src/harness/emission.test.ts
+++ b/packages/eve/src/harness/emission.test.ts
@@ -1,21 +1,11 @@
import { jsonSchema, type TextStreamPart, type ToolSet } from "ai";
import { describe, expect, it, vi } from "vitest";
-import {
- emitTurnEpilogue,
- emitTurnPreamble,
- emitStreamContent,
- getHarnessEmissionState,
- type HarnessEmissionState,
- setHarnessEmissionState,
-} from "#harness/emission.js";
+import { emitStreamContent } from "#harness/emission.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import { resolveWebSearchActivityLabel } from "#harness/provider-tool-schemas.js";
-import {
- getTurnClientContextState,
- setTurnClientContextState,
-} from "#harness/turn-client-context.js";
-import type { HarnessEmitFn, HarnessSession } from "#harness/types.js";
+import type { HarnessEmitFn } from "#harness/types.js";
async function* streamOf(parts: TextStreamPart<ToolSet>[]): AsyncIterable<TextStreamPart<ToolSet>> {
for (const part of parts) {
@@ -23,7 +13,7 @@ async function* streamOf(parts: TextStreamPart<ToolSet>[]): AsyncIterable<TextSt
}
}
-const EMISSION_STATE: HarnessEmissionState = {
+const EMISSION_STATE: TurnPosition = {
sequence: 0,
sessionStarted: true,
stepIndex: 0,
@@ -34,184 +24,6 @@ function createEmitStub(): HarnessEmitFn {
return vi.fn(async () => {});
}
-function createSession(state?: Record<string, unknown>): HarnessSession {
- return {
- agent: {
- modelReference: { id: "test-model" },
- system: "test",
- tools: [],
- },
- compaction: { recentWindowSize: 10, threshold: 100_000 },
- continuationToken: "http:test",
- history: [],
- sessionId: "sess-test",
- state,
- };
-}
-
-describe("emitTurnEpilogue", () => {
- it("passes settled history with turn.completed", async () => {
- const emit = createEmitStub();
- const history = [{ content: "settled reply", role: "assistant" as const }];
-
- await emitTurnEpilogue(emit, EMISSION_STATE, history, {
- cacheReadTokens: 0,
- cacheWriteTokens: 0,
- inputTokens: 0,
- outputTokens: 0,
- });
-
- expect(emit).toHaveBeenNthCalledWith(
- 1,
- expect.objectContaining({ type: "turn.completed" }),
- history,
- );
- });
-});
-
-describe("getHarnessEmissionState", () => {
- it("returns defaults when no state exists", () => {
- expect(getHarnessEmissionState(createSession().state)).toEqual({
- sessionStarted: false,
- sequence: 0,
- stepIndex: 0,
- turnId: "",
- });
- });
-
- it("returns defaults when state key is missing", () => {
- expect(getHarnessEmissionState(createSession({ other: "value" }).state)).toEqual({
- sessionStarted: false,
- sequence: 0,
- stepIndex: 0,
- turnId: "",
- });
- });
-
- it("reads persisted emission state", () => {
- const session = createSession({
- "eve.harness.emission": {
- sessionStarted: true,
- sequence: 3,
- stepIndex: 1,
- turnId: "turn_3",
- },
- });
-
- expect(getHarnessEmissionState(session.state)).toEqual({
- sessionStarted: true,
- sequence: 3,
- stepIndex: 1,
- turnId: "turn_3",
- });
- });
-});
-
-describe("setHarnessEmissionState", () => {
- it("writes emission state to the session", () => {
- const session = createSession();
- const state: HarnessEmissionState = {
- sessionStarted: true,
- sequence: 2,
- stepIndex: 0,
- turnId: "turn_2",
- };
-
- const updated = setHarnessEmissionState(session, state);
-
- expect(getHarnessEmissionState(updated.state)).toEqual(state);
- });
-
- it("preserves existing session state keys", () => {
- const session = createSession({ "other.key": "preserved" });
- const state: HarnessEmissionState = {
- sessionStarted: true,
- sequence: 1,
- stepIndex: 0,
- turnId: "turn_1",
- };
-
- const updated = setHarnessEmissionState(session, state);
-
- expect(updated.state?.["other.key"]).toBe("preserved");
- expect(getHarnessEmissionState(updated.state)).toEqual(state);
- });
-
- it("round-trips through get after set", () => {
- const state: HarnessEmissionState = {
- sessionStarted: true,
- sequence: 5,
- stepIndex: 2,
- turnId: "turn_5",
- };
-
- const session = setHarnessEmissionState(createSession(), state);
- const retrieved = getHarnessEmissionState(session.state);
-
- expect(retrieved).toEqual(state);
- });
-
- it("clears client context when the emission state moves between turns", () => {
- const turnId = "turn_5";
- const session = setTurnClientContextState(createSession(), {
- insertionIndex: 0,
- messages: ["current page"],
- turnId,
- });
-
- const updated = setHarnessEmissionState(session, {
- sequence: 6,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "",
- });
-
- expect(getTurnClientContextState(updated.state, turnId)).toBeUndefined();
- });
-});
-
-describe("emitTurnPreamble", () => {
- it("keeps participant messages visible", async () => {
- const events: Array<Parameters<HarnessEmitFn>[0]> = [];
-
- await emitTurnPreamble(
- async (event) => {
- events.push(event);
- },
- { message: "Start the work" },
- { sequence: 0, sessionStarted: true, stepIndex: 0, turnId: "" },
- [],
- );
-
- expect(events.map((event) => event.type)).toEqual(["turn.started", "message.received"]);
- });
-
- it("attaches one trace context to the session and turn start events", async () => {
- const events: Array<Parameters<HarnessEmitFn>[0]> = [];
- const trace = {
- spanId: "0123456789abcdef",
- traceFlags: 1,
- traceId: "0123456789abcdef0123456789abcdef",
- };
-
- await emitTurnPreamble(
- async (event) => {
- events.push(event);
- },
- { message: "hello" },
- { sequence: 0, sessionStarted: false, stepIndex: 0, turnId: "" },
- [{ role: "user", content: "hello" }],
- undefined,
- trace,
- );
-
- expect(events.slice(0, 2)).toEqual([
- { data: { trace }, type: "session.started" },
- { data: { sequence: 0, trace, turnId: "turn_0" }, type: "turn.started" },
- ]);
- });
-});
-
describe("emitStreamContent empty delivery", () => {
it("reduces 368 saturated deltas to eight bounded dispatches", async () => {
const deltaCount = 368;
diff --git a/packages/eve/src/harness/emission.ts b/packages/eve/src/harness/emission.ts
index c63bfff59..9184ac9b8 100644
--- a/packages/eve/src/harness/emission.ts
+++ b/packages/eve/src/harness/emission.ts
@@ -10,11 +10,7 @@ import type {
type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
type InlineToolResultPart = Extract<ToolResponsePart, { type: "tool-result" }>;
-import type {
- AssistantStepFinishReason,
- RuntimeIdentity,
- RuntimeTraceContext,
-} from "#protocol/message.js";
+import type { AssistantStepFinishReason } from "#protocol/message.js";
import {
createActionsRequestedEvent,
createActionInputAppendedEvent,
@@ -22,20 +18,10 @@ import {
createActionResultEvent,
createMessageAppendedEvent,
createMessageCompletedEvent,
- createMessageReceivedEvent,
createReasoningAppendedEvent,
createReasoningCompletedEvent,
- createSessionFailedEvent,
- createSessionStartedEvent,
- createSessionWaitingEvent,
- createStepFailedEvent,
- createStepStartedEvent,
- createTurnCompletedEvent,
- createTurnFailedEvent,
- createTurnStartedEvent,
} from "#protocol/message.js";
import type { JsonObject } from "#shared/json.js";
-import type { TokenUsage } from "#shared/token-usage.js";
import {
createRuntimeToolResultFromStepResult,
createRuntimeToolResultFromToolError,
@@ -54,199 +40,15 @@ import {
} from "#harness/action-presentation.js";
import { projectResultPresentation, projectDeltaPresentation } from "#harness/tool-presentation.js";
import { createProviderStreamActionBatch } from "#harness/stream-actions.js";
-import { normalizeModelStreamError } from "#harness/model-call-error.js";
+import { normalizeModelStreamError } from "#harness/model-call/errors.js";
import { createOrderedStreamEmitter } from "#harness/ordered-stream-emitter.js";
import { interruptStreamOnFailure } from "#harness/interruptible-stream.js";
import { isInlineAuthorizationToolResult } from "#harness/inline-tool-authorization.js";
-import type { HarnessEmissionState } from "#harness/emission-state.js";
import { emitNestedToolActions } from "#harness/nested-actions.js";
-import type { HarnessEmitFn, HarnessToolMap, StepInput } from "#harness/types.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
+import type { HarnessEmitFn, HarnessToolMap } from "#harness/types.js";
import { normalizeAssistantStepFinishReason } from "#harness/finish-reason.js";
-export {
- getHarnessEmissionState,
- isHarnessBetweenTurns,
- setHarnessEmissionState,
-} from "#harness/emission-state.js";
-export type { HarnessEmissionState } from "#harness/emission-state.js";
-
-/**
- * Emits `session.started` (once), `turn.started`, and `message.received` at the
- * beginning of a new turn. Returns updated emission state.
- */
-export async function emitTurnPreamble(
- emitFn: HarnessEmitFn,
- input: StepInput,
- state: HarnessEmissionState,
- messages: readonly ModelMessage[],
- runtimeIdentity?: RuntimeIdentity,
- traceContext?: RuntimeTraceContext,
-): Promise<HarnessEmissionState> {
- // Steering re-enters an open turn: keep its id and step index and skip the
- // `turn.started` it already emitted.
- const steering = state.turnId !== "";
- const turnId = steering ? state.turnId : `turn_${state.sequence}`;
-
- if (!state.sessionStarted) {
- await emitFn(createSessionStartedEvent({ runtime: runtimeIdentity, trace: traceContext }));
- }
-
- if (!steering) {
- await emitFn(
- createTurnStartedEvent({ sequence: state.sequence, trace: traceContext, turnId }),
- messages,
- );
- }
-
- if (input.message !== undefined) {
- await emitFn(
- createMessageReceivedEvent({
- message: input.message,
- sequence: state.sequence,
- turnId,
- }),
- );
- }
-
- const nextState: HarnessEmissionState = {
- sessionStarted: true,
- sequence: state.sequence,
- stepIndex: steering ? state.stepIndex : 0,
- turnId,
- };
- return steering && state.assistantOutputStarted
- ? { ...nextState, assistantOutputStarted: true }
- : nextState;
-}
-
-/**
- * Emits `step.started` for one model call.
- */
-export async function emitStepStarted(
- emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
- modelId: string,
- messages?: readonly import("ai").ModelMessage[],
-): Promise<void> {
- await emitFn(
- createStepStartedEvent({
- modelId,
- sequence: state.sequence,
- stepIndex: state.stepIndex,
- turnId: state.turnId,
- }),
- messages,
- );
-}
-
-interface FailedStepPayload {
- readonly code: string;
- readonly details?: JsonObject;
- readonly message: string;
-}
-
-/**
- * Emits the shared head of both failure cascades: `step.failed` →
- * `turn.failed`. Both terminal and recoverable paths diverge only on
- * the third event (`session.failed` vs. `session.waiting`).
- */
-async function emitStepAndTurnFailed(
- emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
- input: FailedStepPayload,
-): Promise<void> {
- await emitFn(
- createStepFailedEvent({
- ...input,
- sequence: state.sequence,
- stepIndex: state.stepIndex,
- turnId: state.turnId,
- }),
- );
- await emitFn(
- createTurnFailedEvent({
- ...input,
- sequence: state.sequence,
- turnId: state.turnId,
- }),
- );
-}
-
-/**
- * Emits the full terminal failure cascade: `step.failed` →
- * `turn.failed` → `session.failed`.
- *
- * Use this when the session cannot be salvaged (structural config
- * error, auth misconfig, non-recoverable provider response). The
- * `session.failed` tail tells adapters the session is dead and no
- * further follow-up is possible on the same continuation token.
- */
-export async function emitFailedStep(
- emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
- input: FailedStepPayload & { readonly sessionId: string; readonly usage: TokenUsage },
-): Promise<void> {
- await emitStepAndTurnFailed(emitFn, state, input);
- await emitFn(createSessionFailedEvent(input));
-}
-
-/**
- * Emits the recoverable failure cascade: `step.failed` →
- * `turn.failed` → `session.waiting`.
- */
-export async function emitRecoverableFailedTurn(
- emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
- input: FailedStepPayload & { readonly continuationToken: string; readonly usage: TokenUsage },
-): Promise<HarnessEmissionState> {
- await emitStepAndTurnFailed(emitFn, state, input);
- await emitFn(createSessionWaitingEvent(input.usage));
-
- return {
- sessionStarted: state.sessionStarted,
- sequence: state.sequence + 1,
- stepIndex: 0,
- turnId: "",
- };
-}
-
-/**
- * Returns updated emission state for the next step in the current turn.
- */
-export function advanceStep(state: HarnessEmissionState): HarnessEmissionState {
- return {
- ...state,
- stepIndex: state.stepIndex + 1,
- };
-}
-
-/**
- * Emits `turn.completed` and `session.waiting` with the session's `usage`.
- * Returns updated emission state with an incremented sequence.
- */
-export async function emitTurnEpilogue(
- emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
- messages: readonly ModelMessage[],
- usage: TokenUsage,
-): Promise<HarnessEmissionState> {
- await emitFn(
- createTurnCompletedEvent({
- sequence: state.sequence,
- turnId: state.turnId,
- }),
- messages,
- );
- await emitFn(createSessionWaitingEvent(usage));
-
- return {
- sessionStarted: state.sessionStarted,
- sequence: state.sequence + 1,
- stepIndex: 0,
- turnId: "",
- };
-}
-
/**
* Result of consuming one step's `fullStream`.
*
@@ -282,7 +84,7 @@ interface StreamActionEmissionOptions {
*/
export async function emitStreamContent(
emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
+ state: TurnPosition,
fullStream: AsyncIterable<TextStreamPart<ToolSet>>,
options?: StreamActionEmissionOptions,
): Promise<EmittedStreamContent> {
@@ -319,7 +121,7 @@ function reportedFinishReason(
async function consumeStreamContent(
emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
+ state: TurnPosition,
fullStream: AsyncIterable<TextStreamPart<ToolSet>>,
providerActionBatch: ReturnType<typeof createProviderStreamActionBatch>,
options?: StreamActionEmissionOptions,
@@ -373,7 +175,9 @@ async function consumeStreamContent(
const emitActionRequest = async (projection: RuntimeActionRequestProjection): Promise<void> => {
const { action } = projection;
- if (emittedActionCallIds.has(action.callId)) return;
+ if (emittedActionCallIds.has(action.callId)) {
+ return;
+ }
if (currentMessage.trim().length > 0) {
await flushCurrentMessage();
@@ -397,9 +201,13 @@ async function consumeStreamContent(
readonly toolCallId: string;
readonly toolName: string;
}): Promise<void> => {
- if (providerToolCallIdsSeen.has(toolCall.toolCallId)) return;
+ if (providerToolCallIdsSeen.has(toolCall.toolCallId)) {
+ return;
+ }
providerToolCallIdsSeen.add(toolCall.toolCallId);
- if (emittedActionCallIds.has(toolCall.toolCallId)) return;
+ if (emittedActionCallIds.has(toolCall.toolCallId)) {
+ return;
+ }
emittedActionCallIds.add(toolCall.toolCallId);
if (currentMessage.trim().length > 0) {
@@ -422,7 +230,9 @@ async function consumeStreamContent(
};
const emitActionResult = async (result: RuntimeToolResultActionResult): Promise<void> => {
- if (emittedActionResultCallIds.has(result.callId)) return;
+ if (emittedActionResultCallIds.has(result.callId)) {
+ return;
+ }
emittedActionResultCallIds.add(result.callId);
await emitNestedToolActions(emitFn, state, result.callId);
const resultPresentation =
@@ -634,10 +444,6 @@ async function consumeStreamContent(
await emitActionResult(createRuntimeToolResultFromToolError(toolError));
handledInlineToolResultCallIds.add(toolError.toolCallId);
trailingInlineToolResultParts.push(createToolResultMessagePartFromToolError(toolError));
- } else if (!toolCallIdsSeenInStream.has(toolError.toolCallId)) {
- // An approved call from an earlier step failed; the SDK keeps its error in history.
- await emitActionResult(createRuntimeToolResultFromToolError(toolError));
- handledInlineToolResultCallIds.add(toolError.toolCallId);
}
break;
}
diff --git a/packages/eve/src/harness/final-output.ts b/packages/eve/src/harness/final-output.ts
index 8a5660020..55bed9ecf 100644
--- a/packages/eve/src/harness/final-output.ts
+++ b/packages/eve/src/harness/final-output.ts
@@ -12,6 +12,13 @@ const FINAL_OUTPUT_TOOL_DESCRIPTION =
"Deliver your final answer in the required structure by calling this tool. " +
"Call it exactly once, when you are done; do not answer in prose.";
+/**
+ * What the model reads when it gives its final output beside calls whose results it hasn't seen:
+ * the turn can't end on an answer written before them, so it answers again once they arrive.
+ */
+export const FINAL_OUTPUT_BESIDE_PENDING_CALLS =
+ "Your final output wasn't delivered because other calls in this response were still running. Use their results, then call final_output again.";
+
/**
* Builds the model-facing `final_output` tool from a lowered output schema.
*
diff --git a/packages/eve/src/harness/held-requests.ts b/packages/eve/src/harness/held-requests.ts
deleted file mode 100644
index c3fafb52c..000000000
--- a/packages/eve/src/harness/held-requests.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { finishApprovalCandidate, getApprovalAuditState } from "#harness/approval-candidates.js";
-import { authorizationEventFields } from "#harness/authorization-event-fields.js";
-import {
- clearPendingAuthorization,
- getPendingAuthorization,
- type AuthorizationChallenge,
-} from "#harness/authorization.js";
-import type { HarnessEmissionState } from "#harness/emission-state.js";
-import {
- createAuthorizationCompletedEvent,
- type AuthorizationCompletedStreamEvent,
-} from "#protocol/message.js";
-
-/**
- * Ends the sign-ins a held turn waits on when the person moves on, by steering
- * it with a message or cancelling it: the turn's own sign-ins, and the sign-ins
- * of responders still checking one of its approvals, whose candidates end as
- * stale. The approvals themselves resolve with the steering step or the cancel.
- */
-export function withdrawHeldSignIns(
- state: Record<string, unknown> | undefined,
- input: { readonly completedAt: number; readonly reason: string },
-): {
- readonly state: Record<string, unknown> | undefined;
- readonly withdrawn: readonly AuthorizationChallenge[];
-} {
- const withdrawn = getPendingAuthorization(state)?.challenges ?? [];
- let next = withdrawn.length === 0 ? state : clearPendingAuthorization(state);
- for (const candidate of getApprovalAuditState(next).activeCandidates) {
- next = finishApprovalCandidate({
- candidateId: candidate.candidateId,
- completedAt: input.completedAt,
- reason: input.reason,
- state: next,
- status: "stale",
- });
- }
- return { state: next, withdrawn };
-}
-
-/** The `authorization.completed` events reporting withdrawn sign-ins as declined. */
-export function declinedSignInEvents(
- withdrawn: readonly AuthorizationChallenge[],
- reason: string,
- emissionState: HarnessEmissionState,
-): AuthorizationCompletedStreamEvent[] {
- return withdrawn.map((challenge) =>
- createAuthorizationCompletedEvent({
- ...authorizationEventFields(challenge),
- outcome: "declined",
- reason,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
-}
diff --git a/packages/eve/src/harness/hitl/approval-input-requests.ts b/packages/eve/src/harness/hitl/approval-input-requests.ts
deleted file mode 100644
index fd89cbbf3..000000000
--- a/packages/eve/src/harness/hitl/approval-input-requests.ts
+++ /dev/null
@@ -1,323 +0,0 @@
-import type { ModelMessage } from "ai";
-
-import type { RuntimeToolResultActionResult } from "#shared/action-types.js";
-import type { InputRequest, InputResponse } from "#shared/input.js";
-import {
- buildResolvedInputBatch,
- resolveApprovalOutcome,
- TOOL_EXECUTION_DENIED_MESSAGE,
-} from "#harness/input-request-resolution.js";
-import { isApprovalRequest } from "#harness/input-request-class.js";
-import type { PendingInputBatch } from "#harness/pending-input-batches.js";
-import {
- getPendingInputBatches,
- queueDeferredStepInput,
- removePendingInputBatches,
-} from "#harness/pending-input-batches.js";
-import {
- appendResolvedBatchTranscript,
- compactStepInput,
- finishResolvedInput,
- responsesForBatches,
-} from "#harness/hitl/pending-input-resolution.js";
-import type {
- InputDomainResolverInput,
- ResolvedInputActionBatch,
- ResolvePendingInputResult,
- ToolResponsePart,
-} from "#harness/hitl/pending-input-resolution.js";
-import type { HarnessSession } from "#harness/types.js";
-import { validateHarnessModelMessages } from "#harness/messages.js";
-
-const APPROVED_TOOLS_KEY = "eve.runtime.hitl.approvedTools";
-const TOOL_EXECUTION_DENIED_CODE = "TOOL_EXECUTION_DENIED";
-type ToolApprovalInputRequest = InputRequest & { readonly kind: "tool-approval" };
-
-export type RejectedActionBatch = ResolvedInputActionBatch;
-
-export function findAnsweredApprovalBatches(
- batches: readonly PendingInputBatch[],
- responses: readonly InputResponse[],
-): PendingInputBatch[] {
- const responseIds = new Set(responses.map((response) => response.requestId));
- return batches.filter((batch) =>
- batch.requests.every(
- (request) => !isApprovalRequest(request) || responseIds.has(request.requestId),
- ),
- );
-}
-
-export function resolveApprovalInputBatches(
- input: InputDomainResolverInput & {
- readonly resolveApprovalKey?: (request: InputRequest) => string | undefined;
- },
-): ResolvePendingInputResult {
- const answered = new Set(findAnsweredApprovalBatches(input.batches, input.responses));
- // Only the first answered batch resolves: anything after it would hide its
- // approval response from AI SDK's tail-tool-message scan. Later answers
- // replay on the next step.
- const approvalBatch = input.batches.find((batch) => answered.has(batch));
- const openBatches = input.batches.filter((batch) => batch !== approvalBatch);
- const leftoverResponses = responsesForBatches(input.responses, openBatches);
-
- if (approvalBatch === undefined) {
- if (input.resolvedStepInput?.message === undefined) {
- return {
- outcome: "unresolved",
- messages: [...input.baseHistory],
- session: queueDeferredStepInput(input.session, compactStepInput(input.resolvedStepInput)),
- };
- }
- // A message instead of an answer steers the held turn past its approval.
- return ignoreApprovalInputBatch(input);
- }
-
- const approval = resolveApprovalBatch({
- batch: approvalBatch,
- messages: [...input.baseHistory],
- resolveApprovalKey: input.resolveApprovalKey,
- responses: input.responses,
- session: input.session,
- });
- const resolved = buildResolvedInputBatch(approvalBatch, input.responses);
-
- return finishResolvedInput({
- deferTurnInput: true,
- leftoverResponses,
- messages: approval.messages,
- rejectedActions: approval.rejectedActions,
- resolvedInputs: resolved === undefined ? [] : [resolved],
- resolvedStepInput: input.resolvedStepInput,
- session: removePendingInputBatches(approval.session, [approvalBatch]),
- });
-}
-
-/**
- * Resolves the first open approval batch when the person steered the held turn
- * with a message instead of finishing it. Requests they already answered, as in
- * a partial approval, keep that answer; the rest report `ignored`. Later
- * batches stay open, as with answered batches.
- */
-export function ignoreApprovalInputBatch(
- input: InputDomainResolverInput & {
- readonly resolveApprovalKey?: (request: InputRequest) => string | undefined;
- },
-): ResolvePendingInputResult {
- const batch = input.batches[0]!;
- const answers = responsesForBatches(input.responses, [batch]);
- const approval = resolveApprovalBatch({
- batch,
- messages: [...input.baseHistory],
- resolveApprovalKey: input.resolveApprovalKey,
- responses: answers,
- session: input.session,
- });
- const resolved = buildResolvedInputBatch(batch, answers);
- return finishResolvedInput({
- // Calls that will not run already have their results, so the message joins
- // this step. An approved call runs through AI SDK, which needs its approval
- // response last, so the message replays after it.
- deferTurnInput: answers.some((answer) => resolveApprovalOutcome(answer).approved),
- leftoverResponses: responsesForBatches(input.responses, input.batches.slice(1)),
- messages: approval.messages,
- rejectedActions: approval.rejectedActions,
- resolvedInputs: resolved === undefined ? [] : [resolved],
- resolvedStepInput: input.resolvedStepInput,
- session: removePendingInputBatches(approval.session, [batch]),
- });
-}
-
-const CANCELLED_APPROVAL_REASON = "Cancelled before anyone answered.";
-
-/**
- * Withdraws every pending tool approval when its turn is cancelled. Each held
- * call goes into history with a not-run result, so no call is left without one.
- */
-export function cancelApprovalInputBatches(session: HarnessSession): HarnessSession {
- const batches = pendingApprovalBatches(session.state);
- if (batches.length === 0) return session;
- const messages: ModelMessage[] = [...session.history];
- for (const batch of batches) {
- appendResolvedBatchTranscript(
- messages,
- batch,
- buildApprovalBatchToolResponseParts(batch, [], CANCELLED_APPROVAL_REASON),
- );
- }
- return {
- ...removePendingInputBatches(session, batches),
- history: validateHarnessModelMessages(messages),
- };
-}
-
-/** Tool approvals still waiting for an answer, which cancelling their turn withdraws. */
-export function getPendingApprovalRequests(
- state: HarnessSession["state"],
-): readonly InputRequest[] {
- return pendingApprovalBatches(state).flatMap((batch) => batch.requests);
-}
-
-function pendingApprovalBatches(state: HarnessSession["state"]): readonly PendingInputBatch[] {
- return getPendingInputBatches(state).filter((batch) => batch.requests.every(isApprovalRequest));
-}
-
-/** Returns recorded approval keys that have no matching request still pending. */
-export function getApprovedTools(
- session: HarnessSession,
- resolveApprovalKey?: (request: InputRequest) => string | undefined,
-): ReadonlySet<string> {
- const approvedTools = readRecordedApprovedTools(session);
- for (const batch of getPendingInputBatches(session.state)) {
- for (const request of batch.requests) {
- if (!isApprovalRequest(request)) continue;
- approvedTools.delete(resolveApprovalKey?.(request) ?? request.action.toolName);
- }
- }
- return approvedTools;
-}
-
-function readRecordedApprovedTools(session: HarnessSession): Set<string> {
- const value = session.state?.[APPROVED_TOOLS_KEY];
- return Array.isArray(value) ? new Set(value as string[]) : new Set();
-}
-
-function resolveApprovalBatch(input: {
- readonly batch: PendingInputBatch;
- readonly messages: ModelMessage[];
- readonly resolveApprovalKey?: (request: InputRequest) => string | undefined;
- readonly responses: readonly InputResponse[];
- readonly session: HarnessSession;
-}): ResolvedApprovalBatch {
- const session = recordApprovedTools({
- pendingBatch: input.batch,
- resolveApprovalKey: input.resolveApprovalKey,
- responses: input.responses,
- session: input.session,
- });
- const toolParts = buildApprovalBatchToolResponseParts(input.batch, input.responses);
- appendResolvedBatchTranscript(input.messages, input.batch, toolParts);
- const rejected = buildRejectedActionBatch(input.batch, input.responses);
-
- return {
- messages: input.messages,
- rejectedActions: rejected === undefined ? undefined : [rejected],
- session,
- };
-}
-
-type ResolvedApprovalBatch = {
- readonly messages: ModelMessage[];
- readonly rejectedActions?: readonly RejectedActionBatch[];
- readonly session: HarnessSession;
-};
-
-function recordApprovedTools(input: {
- readonly pendingBatch: PendingInputBatch;
- readonly resolveApprovalKey?: (request: InputRequest) => string | undefined;
- readonly responses: readonly InputResponse[];
- readonly session: HarnessSession;
-}): HarnessSession {
- const approvedIds = new Set(
- input.responses.filter((response) => response.optionId === "approve").map((r) => r.requestId),
- );
- const newKeys = input.pendingBatch.requests
- .filter((request) => isApprovalRequest(request) && approvedIds.has(request.requestId))
- .map((request) => input.resolveApprovalKey?.(request) ?? request.action.toolName);
-
- if (newKeys.length === 0) return input.session;
-
- const state = { ...input.session.state };
- state[APPROVED_TOOLS_KEY] = [
- ...new Set([...readRecordedApprovedTools(input.session), ...newKeys]),
- ];
- return { ...input.session, state };
-}
-
-function buildRejectedActionBatch(
- batch: PendingInputBatch,
- responses: readonly InputResponse[],
-): RejectedActionBatch | undefined {
- if (batch.event === undefined) return undefined;
-
- const responseMap = new Map(responses.map((response) => [response.requestId, response]));
- const results: RuntimeToolResultActionResult[] = [];
- for (const request of batch.requests) {
- if (!isApprovalRequest(request)) continue;
-
- const { approved, reason, status } = resolveApprovalOutcome(responseMap.get(request.requestId));
- if (approved) continue;
-
- results.push({
- callId: request.action.callId,
- isError: true,
- kind: "tool-result",
- output: {
- approval: { requestId: request.requestId, status },
- code: TOOL_EXECUTION_DENIED_CODE,
- message: reason ?? TOOL_EXECUTION_DENIED_MESSAGE,
- tool: { result: "not_run" },
- },
- toolName: request.action.toolName,
- });
- }
-
- return results.length > 0 ? { event: batch.event, results } : undefined;
-}
-
-function buildApprovalBatchToolResponseParts(
- batch: PendingInputBatch,
- responses: readonly InputResponse[],
- /** Why an unanswered request did not run, when not because the user moved on. */
- unansweredReason?: string,
-): ToolResponsePart[] {
- const responseMap = new Map(responses.map((response) => [response.requestId, response]));
- const parts: ToolResponsePart[] = [];
- for (const request of batch.requests) {
- const response = responseMap.get(request.requestId);
- switch (request.kind) {
- case "tool-approval":
- parts.push(
- ...buildApprovalToolResponseParts(
- request as ToolApprovalInputRequest,
- response,
- unansweredReason,
- ),
- );
- break;
- case "question":
- case "session-limit":
- throw new TypeError(
- `Approval pending input batches cannot contain a "${request.kind}" request.`,
- );
- default: {
- const unhandled: never = request.kind;
- throw new TypeError(`Unhandled pending input request kind: ${String(unhandled)}`);
- }
- }
- }
- return parts;
-}
-
-function buildApprovalToolResponseParts(
- request: ToolApprovalInputRequest,
- response: InputResponse | undefined,
- unansweredReason: string | undefined,
-): ToolResponsePart[] {
- const outcome = resolveApprovalOutcome(response);
- const approved = outcome.approved;
- const reason = response === undefined ? (unansweredReason ?? outcome.reason) : outcome.reason;
- const parts: ToolResponsePart[] = [
- { approvalId: request.requestId, approved, reason, type: "tool-approval-response" },
- ];
- // Persist an explicit denial result because AI SDK strips historical
- // approval responses during provider prompt conversion.
- if (!approved) {
- parts.push({
- output: { type: "execution-denied", reason },
- toolCallId: request.action.callId,
- toolName: request.action.toolName,
- type: "tool-result",
- });
- }
- return parts;
-}
diff --git a/packages/eve/src/harness/hitl/approvals.ts b/packages/eve/src/harness/hitl/approvals.ts
new file mode 100644
index 000000000..85f6e726d
--- /dev/null
+++ b/packages/eve/src/harness/hitl/approvals.ts
@@ -0,0 +1,647 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { ModelMessage } from "ai";
+
+import type { getApprovalAuditState } from "#harness/hitl/candidates.js";
+import {
+ supersededChallenges,
+ withSignIns,
+ type AuthorizationChallenge,
+} from "#harness/authorization.js";
+import { authorizationEventFields } from "#harness/authorization-event-fields.js";
+import { renderPendingApprovalsSnippet } from "#harness/hitl/approval-prompt.js";
+import { isApprovalRequest } from "#harness/input-request-class.js";
+import {
+ resolveApprovalOutcome,
+ resolveInputOutcome,
+ TOOL_EXECUTION_DENIED_MESSAGE,
+ type ResolvedInputBatch,
+} from "#harness/input-request-resolution.js";
+import { coalesceTurnInputs, createFrameworkUserMessage } from "#harness/messages.js";
+import { resolveSessionLimitContinuation } from "#harness/hitl/budget-request.js";
+import type { StepInput } from "#harness/types.js";
+import { readClientContext } from "#internal/client-context.js";
+import {
+ createActionResultEvent,
+ createApprovalCandidateEvent,
+ createApprovalSettledEvent,
+ createAuthorizationCompletedEvent,
+ createAuthorizationRequiredEvent,
+ createInputRequestedEvent,
+ createInputResolvedEvent,
+ createMessageCompletedEvent,
+ type UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
+import {
+ openInputs,
+ turnCoordinates,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import type { InputRequest } from "#shared/input.js";
+import type { Transition } from "#harness/session-machine/commit.js";
+import { signInWithdrawn } from "#harness/session-machine/events.js";
+import {
+ canonicalize,
+ compactInput,
+ hasInput,
+ isEmptyInput,
+ resolveTextInput,
+ withoutResponses,
+ withoutTurnInput,
+ type ResolvedStepInput,
+} from "./delivery.js";
+import type { StepCoordinates, SuspendedStep, TurnState } from "#harness/session-machine/view.js";
+import { withoutCalls } from "#harness/inline-tool-authorization.js";
+import {
+ finishTurn,
+ hold,
+ ownOpenRequestIds,
+ settle,
+ stepCallIds,
+ withoutApproved,
+ suspend,
+ withResult,
+} from "#harness/session-machine/transitions.js";
+import { turnPosition, type SessionView } from "#harness/session-machine/view.js";
+
+// The session's human-in-the-loop transitions. A model step parks on the approvals its calls
+// need (`parkOnApprovals`), a delivery answers them (`answer`), an exhausted budget asks to continue
+// (`requestLimit`), and a sign-in stops the calls that need it (`requireSignIn`). Approvals and
+// sign-ins hold their turn open; the rest of the machine sees only calls with and without results.
+
+// ---------------------------------------------------------------------------
+// parkOnApprovals
+// ---------------------------------------------------------------------------
+
+/**
+ * A model response made calls that need a person's approval. The response waits in a suspended
+ * step, beside any runtime calls it made, and the turn holds until the answers arrive.
+ */
+export function parkOnApprovals(
+ view: SessionView,
+ input: {
+ readonly event: StepCoordinates;
+ readonly messages: readonly ModelMessage[];
+ readonly requests: readonly InputRequest[];
+ readonly tasks: readonly RuntimeWorkflowTaskRequest[];
+ readonly responseAuthRequiredRequestIds?: readonly string[];
+ readonly requester?: SuspendedStep["requester"];
+ },
+): Transition {
+ // Every anonymous caller shares one synthetic identity, so an anonymous requester can't be told
+ // apart from another anonymous responder: record none.
+ const requester = input.requester?.principalType === "anonymous" ? null : input.requester;
+ // Results of work resumed in this step stay ahead of the notice; the rest waits for approval.
+ const pendingStart = input.messages.findIndex((message) => message.role !== "tool");
+ const committed = pendingStart === -1 ? input.messages : input.messages.slice(0, pendingStart);
+ const snippet = renderPendingApprovalsSnippet(input.requests);
+ const turn = suspend(view.turn, {
+ event: input.event,
+ messages: input.messages.slice(committed.length),
+ requester,
+ requests: input.requests,
+ responseAuthRequiredRequestIds: input.responseAuthRequiredRequestIds,
+ tasks: input.tasks,
+ });
+ return {
+ commit: [
+ ...committed,
+ ...(snippet === undefined ? [] : [createFrameworkUserMessage("context.state", snippet)]),
+ ],
+ events: [createInputRequestedEvent({ requests: input.requests, ...input.event })],
+ turn,
+ };
+}
+
+/** Approved workflow and agent calls join the runs their steps wait on, as their approvers. */
+export function dispatch(
+ view: SessionView,
+ input: {
+ readonly approvers: Readonly<Record<string, SessionAuthContext>>;
+ readonly tasks: readonly RuntimeWorkflowTaskRequest[];
+ },
+): Transition {
+ const suspended = view.turn.suspended.map((step) => {
+ const calls = stepCallIds(step);
+ const tasks = input.tasks.filter((task) => calls.has(task.callId));
+ if (tasks.length === 0) return step;
+ const dispatched = withoutApproved(step, new Set(tasks.map((task) => task.callId)));
+ const approvers = { ...step.approvers };
+ for (const { callId } of tasks) {
+ const approver = input.approvers[callId];
+ if (approver !== undefined) approvers[callId] = approver;
+ }
+ return {
+ ...dispatched,
+ tasks: [...step.tasks, ...tasks],
+ ...(Object.keys(approvers).length > 0 && { approvers }),
+ };
+ });
+ return { events: [], turn: { ...view.turn, suspended } };
+}
+
+/**
+ * Approved calls run before the delivery's own input, as the AI SDK ran them: the model reads
+ * their results first. The input waits in the queue, unreceived, for the step after.
+ */
+export function deferInput(view: SessionView, input: StepInput): Transition {
+ return { events: [], turn: withQueued(view.turn, input) };
+}
+
+function withQueued(turn: TurnState, queued: StepInput | undefined): TurnState {
+ if (queued === undefined || isEmptyInput(queued)) return turn;
+ return {
+ ...turn,
+ queued: turn.queued === undefined ? queued : coalesceTurnInputs(turn.queued, queued),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// answer
+// ---------------------------------------------------------------------------
+
+/** What the approval-response policies did with a delivery, before `answer` reads it. */
+export interface ResponsePolicyPass {
+ readonly kind:
+ | "continue"
+ | "continue-coordination"
+ | "authorization-required"
+ | "responses-completed"
+ | "park";
+ readonly challenges: readonly AuthorizationChallenge[];
+ readonly feedback: readonly string[];
+ /** The delivery minus the answers the policies took, plus the settlements they reached. */
+ readonly stepInput?: StepInput;
+ readonly audit: ReturnType<typeof getApprovalAuditState>;
+ /** Responder sign-ins pending when the pass began. */
+ readonly challengesAtStart: readonly AuthorizationChallenge[];
+}
+
+/** What `answer` concluded, beyond the events and state it changed. */
+export interface Answered extends Transition {
+ /**
+ * `continue`: the step goes on. `park`: nothing can run until more input arrives.
+ * `repeat`: a policy pass committed, so the next pass runs in a fresh step. `sign-in`: a
+ * responder must sign in first. `defer-message`: a message arrived while the session-limit
+ * prompt is open; it waits in its turn for the prompt.
+ */
+ readonly next: "continue" | "park" | "repeat" | "sign-in" | "defer-message";
+ /** The turn's input, without the answers `answer` consumed. */
+ readonly input?: StepInput;
+ /** Whether a plain-text answer consumed the message. */
+ readonly consumedMessage?: boolean;
+ /** The batches the delivery resolved, in order. */
+ readonly resolved: readonly ResolvedInputBatch[];
+ /** A decision on the session-limit prompt. */
+ readonly limit?: { readonly granted: boolean };
+}
+
+/**
+ * A delivery answers what the session asked. An approval batch resolves once every request in it
+ * has a decision: approved calls become ready to run, denied ones get their denial as a result,
+ * and `once()` approvals grant their key. A message steers the held turn instead: the first
+ * pending batch resolves with the answers it has, and the rest are ignored. A session-limit
+ * answer grants or declines a fresh budget. A partial answer waits, queued, for the rest.
+ */
+export function answer(
+ view: SessionView,
+ input: {
+ readonly delivery: ResolvedStepInput | undefined;
+ readonly policy: ResponsePolicyPass;
+ /** The delivery merged the queue in, so the queue empties. */
+ readonly takeQueued: boolean;
+ readonly approvalKey: (request: InputRequest) => string | undefined;
+ },
+): Answered {
+ const { policy } = input;
+ const { projection } = view;
+ const position = turnPosition(projection);
+ const events: UnstampedMessageStreamEvent[] = [
+ ...policy.feedback.map((message) =>
+ createMessageCompletedEvent({
+ message,
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ }),
+ ),
+ ...reportApprovalProgress(projection, policy.audit, policy.challengesAtStart),
+ ];
+ let turn: TurnState = input.takeQueued ? { ...view.turn, queued: undefined } : view.turn;
+ const done = (answered: Omit<Answered, "events" | "turn" | "resolved"> & Partial<Answered>) =>
+ ({ events, resolved: [], turn, ...answered }) satisfies Answered;
+ const queue = (queued: StepInput | undefined) => {
+ turn = withQueued(turn, queued);
+ };
+
+ if (policy.kind === "park") return done({ next: "park" });
+ if (policy.kind === "continue-coordination") {
+ queue(policy.stepInput);
+ return done({ next: "repeat" });
+ }
+ if (policy.challenges.length > 0) return done({ next: "sign-in" });
+
+ const delivery = input.delivery;
+ const limit = openInputs(projection).find(
+ (open) =>
+ open.request.kind === "session-limit" && ownOpenRequestIds(view).has(open.request.requestId),
+ );
+ const answerable = turn.suspended.filter((step) => step.requests.length > 0);
+ if (limit === undefined && answerable.length === 0) {
+ return done({ input: delivery, next: "continue" });
+ }
+
+ const textBatch =
+ limit !== undefined
+ ? { requests: [limit.request] }
+ : answerable.length === 1
+ ? answerable[0]
+ : undefined;
+ const resolved = textBatch === undefined ? delivery : resolveTextInput(textBatch, delivery);
+ const responses = canonicalize(resolved?.inputResponses ?? []);
+ const byId = new Map(responses.map((response) => [response.requestId, response]));
+ const answered = answerable.filter((step) =>
+ step.requests.every((request) => byId.has(request.requestId)),
+ );
+ const leftoverFor = (steps: readonly SuspendedStep[]) =>
+ responses.filter((response) =>
+ steps.some((step) =>
+ step.requests.some((request) => request.requestId === response.requestId),
+ ),
+ );
+ // Nothing runs: the input waits, and the held turn stays held.
+ const park = () => {
+ queue(compactInput(resolved));
+ return done({ next: "park" });
+ };
+ if (responses.length === 0 && resolved?.message === undefined) return park();
+
+ if (limit !== undefined) {
+ const response = byId.get(limit.request.requestId);
+ if (response === undefined) {
+ if (!hasInput(delivery)) {
+ queue(compactInput(resolved));
+ return done({ next: "park" });
+ }
+ // The message is received now, into the turn that holds for the prompt: only answers to
+ // other requests wait for the grant. What waits in the queue was never received.
+ queue(withoutTurnInput(resolved));
+ return done({ input: resolved, next: "defer-message" });
+ }
+ const batch: ResolvedInputBatch = {
+ event: { sequence: limit.sequence, stepIndex: limit.stepIndex, turnId: limit.turnId },
+ inputs: [
+ {
+ outcome: resolveInputOutcome(limit.request.kind, response),
+ request: limit.request,
+ response,
+ },
+ ],
+ };
+ events.push(resolvedEvent(batch));
+ const leftover = leftoverFor(answerable);
+ if (leftover.length > 0) queue({ inputResponses: leftover });
+ return done({
+ consumedMessage: resolved?.messageConsumed,
+ input: withoutResponses(resolved),
+ limit: resolveSessionLimitContinuation({ requests: [limit.request], responses }),
+ next: "continue",
+ resolved: [batch],
+ });
+ }
+
+ if (answered.length === 0 && resolved?.message === undefined) return park();
+ // A message steers the held turn past its first pending batch: the answers it has stand, and
+ // the requests nobody answered are ignored. Later batches stay open.
+ if (answered.length === 0) answered.push(answerable[0]!);
+ const leftover = leftoverFor(answerable.filter((step) => !answered.includes(step)));
+ if (leftover.length > 0) queue({ inputResponses: leftover });
+
+ const grants = new Set(turn.grants);
+ const batches: ResolvedInputBatch[] = [];
+ const rejected: UnstampedMessageStreamEvent[] = [];
+ const suspended = turn.suspended.map((step) => {
+ if (!answered.includes(step)) return step;
+ let messages = step.messages;
+ const approvedRequests: InputRequest[] = [];
+ for (const request of step.requests) {
+ const { approved, reason, status } = resolveApprovalOutcome(byId.get(request.requestId));
+ if (approved) {
+ grants.add(input.approvalKey(request) ?? request.action.toolName);
+ approvedRequests.push(request);
+ continue;
+ }
+ messages = withResult(messages, {
+ output: { reason, type: "execution-denied" },
+ toolCallId: request.action.callId,
+ toolName: request.action.toolName,
+ type: "tool-result",
+ });
+ rejected.push(
+ createActionResultEvent({
+ rejected: true,
+ result: {
+ callId: request.action.callId,
+ isError: true,
+ kind: "tool-result",
+ output: {
+ approval: { requestId: request.requestId, status },
+ code: "TOOL_EXECUTION_DENIED",
+ message: reason ?? TOOL_EXECUTION_DENIED_MESSAGE,
+ tool: { result: "not_run" },
+ },
+ toolName: request.action.toolName,
+ },
+ ...step.event,
+ }),
+ );
+ }
+ batches.push({
+ event: step.event,
+ inputs: step.requests.map((request) => {
+ const response = byId.get(request.requestId);
+ return { outcome: resolveInputOutcome(request.kind, response), request, response };
+ }),
+ });
+ const approved = [...(step.approved ?? []), ...approvedRequests];
+ return { ...step, messages, requests: [], ...(approved.length > 0 && { approved }) };
+ });
+ events.push(...batches.map(resolvedEvent), ...rejected);
+ turn = { ...turn, grants: [...grants], suspended };
+ return done({
+ consumedMessage: resolved?.messageConsumed,
+ input: withoutResponses(resolved),
+ next: "continue",
+ resolved: batches,
+ });
+}
+
+/** The `input.resolved` for a batch, at the coordinates of the step that asked. */
+function resolvedEvent(batch: ResolvedInputBatch): UnstampedMessageStreamEvent {
+ return createInputResolvedEvent({
+ resolutions: batch.inputs.map((resolved) => {
+ const resolution = {
+ kind: resolved.request.kind,
+ outcome: resolved.outcome,
+ requestId: resolved.request.requestId,
+ };
+ return resolved.response === undefined
+ ? resolution
+ : { ...resolution, response: resolved.response };
+ }),
+ ...batch.event,
+ });
+}
+
+/**
+ * Responder progress on approvals: candidates that started or finished, approvals they settled,
+ * and the sign-in of a candidate that expired. Each is reported once, when the projection hasn't
+ * heard it, for requests the projection still holds.
+ */
+function reportApprovalProgress(
+ projection: SessionProjection,
+ audit: ReturnType<typeof getApprovalAuditState>,
+ challenges: readonly AuthorizationChallenge[],
+): readonly UnstampedMessageStreamEvent[] {
+ const at = turnCoordinates(projection);
+ const isOpen = (requestId: string) => {
+ const open = projection.inputs[requestId];
+ return open !== undefined && open.status !== "settled";
+ };
+ const events: UnstampedMessageStreamEvent[] = [];
+ for (const challenge of challenges) {
+ const expired = audit.candidateHistory.some(
+ (candidate) =>
+ candidate.candidateId === challenge.candidateId && candidate.status === "timed-out",
+ );
+ const attempt = projection.authorizations[challenge.attemptId ?? challenge.name];
+ if (!expired || attempt?.status !== "required") continue;
+ events.push(
+ createAuthorizationCompletedEvent({
+ ...authorizationEventFields(challenge),
+ outcome: "failed",
+ reason: "The approval response expired. Please submit a new response.",
+ ...at,
+ }),
+ );
+ }
+ for (const candidate of audit.activeCandidates) {
+ if (projection.candidates[candidate.candidateId] !== undefined) continue;
+ if (!isOpen(candidate.requestId)) continue;
+ events.push(
+ createApprovalCandidateEvent({
+ candidateId: candidate.candidateId,
+ outcome: "pending",
+ requestId: candidate.requestId,
+ responderPrincipalId: candidate.responder.principalId,
+ ...at,
+ }),
+ );
+ }
+ for (const candidate of audit.candidateHistory) {
+ if (candidate.status === "allowed" || candidate.status === "authorization-required") continue;
+ if (projection.inputs[candidate.requestId] === undefined) continue;
+ if (projection.candidates[candidate.candidateId]?.outcome === candidate.status) continue;
+ events.push(
+ createApprovalCandidateEvent({
+ candidateId: candidate.candidateId,
+ outcome: candidate.status,
+ requestId: candidate.requestId,
+ responderPrincipalId: candidate.responder.principalId,
+ reason: candidate.reason,
+ ...at,
+ }),
+ );
+ }
+ for (const settlement of audit.settlements) {
+ if (!isOpen(settlement.requestId)) continue;
+ events.push(
+ createApprovalSettledEvent({
+ outcome: settlement.outcome === "allowed" ? "approved" : "cancelled",
+ requestId: settlement.requestId,
+ responderPrincipalId: settlement.actor.principalId,
+ ...at,
+ }),
+ );
+ }
+ return events;
+}
+
+/** Queued input that can run now, rather than wait for more answers. */
+export function hasRunnableQueue(view: SessionView): boolean {
+ const queued = view.turn.queued;
+ if (queued === undefined) return false;
+ if (
+ queued.message !== undefined ||
+ (queued.context?.length ?? 0) > 0 ||
+ readClientContext(queued) !== undefined ||
+ queued.outputSchema !== undefined ||
+ (queued.runtimeActionResults?.length ?? 0) > 0
+ ) {
+ return true;
+ }
+ const responses = [
+ ...(queued.inputResponses ?? []),
+ ...(queued.attributedInputResponses ?? []).map(({ response }) => response),
+ ];
+ if (responses.length === 0) return false;
+ const answered = new Set(responses.map((response) => response.requestId));
+ const limit = openInputs(view.projection).find((open) => open.request.kind === "session-limit");
+ if (limit !== undefined) return answered.has(limit.request.requestId);
+ return view.turn.suspended.some(
+ (step) =>
+ step.requests.length > 0 && step.requests.every((request) => answered.has(request.requestId)),
+ );
+}
+
+/** Keys `once()` approvals granted, except those a pending approval still asks about. */
+export function grantedApprovalKeys(
+ view: SessionView,
+ approvalKey: (request: InputRequest) => string | undefined,
+): ReadonlySet<string> {
+ const granted = new Set(view.turn.grants);
+ for (const step of view.turn.suspended) {
+ for (const request of step.requests) {
+ if (isApprovalRequest(request))
+ granted.delete(approvalKey(request) ?? request.action.toolName);
+ }
+ }
+ return granted;
+}
+
+/**
+ * The steps a delivery approves calls of, whose tools the calls run with: those it answers in
+ * full, approving at least one call, or the only pending step a plain-text answer approves.
+ */
+export function approvingSteps(
+ view: SessionView,
+ stepInput: StepInput | undefined,
+): readonly SuspendedStep[] {
+ const pending = view.turn.suspended.filter((step) => step.requests.length > 0);
+ const resolved = pending.length === 1 ? resolveTextInput(pending[0]!, stepInput) : stepInput;
+ const options = new Map(
+ (resolved?.inputResponses ?? []).map((response) => [response.requestId, response.optionId]),
+ );
+ return pending.filter(
+ (step) =>
+ step.requests.every((request) => options.has(request.requestId)) &&
+ step.requests.some(
+ (request) => isApprovalRequest(request) && options.get(request.requestId) === "approve",
+ ),
+ );
+}
+
+/** The suspended step that holds `requestId`. */
+export function stepForRequest(view: SessionView, requestId: string): SuspendedStep | undefined {
+ return view.turn.suspended.find((step) =>
+ step.requests.some((request) => request.requestId === requestId),
+ );
+}
+
+/**
+ * The held turn moves on, steered or cancelled: the sign-ins it waits on end, declined, including
+ * a responder's for one of its approvals.
+ */
+export function withdrawSignIns(view: SessionView, reason: string): Transition {
+ return {
+ events: view.signIns.flatMap((challenge) => {
+ const attempt = view.projection.authorizations[challenge.attemptId ?? challenge.name];
+ return attempt?.status === "required" ? [signInWithdrawn(attempt, reason)] : [];
+ }),
+ signIns: [],
+ turn: view.turn,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// requestLimit
+// ---------------------------------------------------------------------------
+
+/**
+ * The session spent its budget: it asks whether to continue instead of calling the model, and
+ * the turn ends. The prompt is the projection's open request; `answer` grants a
+ * fresh budget or declines it.
+ */
+export function requestLimit(
+ view: SessionView,
+ input: { readonly request: InputRequest },
+): Transition {
+ const position = turnPosition(view.projection);
+ return {
+ events: [
+ createInputRequestedEvent({
+ requests: [input.request],
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ }),
+ ...finishTurn(view).events,
+ ],
+ turn: view.turn,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// requireSignIn
+// ---------------------------------------------------------------------------
+
+/**
+ * Work needs a sign-in. The calls that need it stop, settling `cancelled` until it completes;
+ * an attempt it replaces fails; and each sign-in is asked for and recorded. The turn holds until
+ * every sign-in calls back. Input that waited on a responder's sign-in stays queued for it. An
+ * approved call that needs the sign-in leaves its step, so the model calls it again once the
+ * sign-in completes.
+ */
+export function requireSignIn(
+ view: SessionView,
+ input: {
+ readonly challenges: readonly AuthorizationChallenge[];
+ readonly callIdsByName?: ReadonlyMap<string, readonly string[]>;
+ readonly queued?: StepInput;
+ },
+): Transition {
+ const position = turnPosition(view.projection);
+ const at = {
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ };
+ const events: UnstampedMessageStreamEvent[] = [
+ ...supersededChallenges(view.signIns, input.challenges).map((superseded) =>
+ createAuthorizationCompletedEvent({
+ ...authorizationEventFields(superseded),
+ outcome: "failed",
+ reason: "Superseded by a newer authorization attempt.",
+ ...at,
+ }),
+ ),
+ ...input.challenges.map((challenge) =>
+ createAuthorizationRequiredEvent({
+ ...authorizationEventFields(challenge),
+ description:
+ challenge.challenge.instructions ?? `Authorization required for ${challenge.name}`,
+ webhookUrl: challenge.hookUrl,
+ ...at,
+ }),
+ ),
+ ];
+ events.push(...hold(view, { on: "input" }).events);
+ const queued =
+ input.queued === undefined
+ ? view.turn.queued
+ : view.turn.queued === undefined
+ ? input.queued
+ : coalesceTurnInputs(view.turn.queued, input.queued);
+ const signIns = withSignIns(view.signIns, input.challenges);
+ const stopped = new Set([...(input.callIdsByName?.values() ?? [])].flat());
+ const suspended = view.turn.suspended.map((step) =>
+ [...stepCallIds(step)].some((callId) => stopped.has(callId))
+ ? { ...step, messages: withoutCalls(step.messages, stopped) }
+ : step,
+ );
+ if (suspended.every((step, index) => step === view.turn.suspended[index])) {
+ return { events, signIns, turn: { ...view.turn, queued } };
+ }
+ const settled = settle({ ...view, turn: { ...view.turn, queued, suspended } }, { results: [] });
+ return { commit: settled.commit, events, signIns, turn: settled.turn };
+}
diff --git a/packages/eve/src/harness/approved-call-callers.ts b/packages/eve/src/harness/hitl/approved-call-callers.ts
similarity index 63%
rename from packages/eve/src/harness/approved-call-callers.ts
rename to packages/eve/src/harness/hitl/approved-call-callers.ts
index f78a8ae4f..4b3b79b8e 100644
--- a/packages/eve/src/harness/approved-call-callers.ts
+++ b/packages/eve/src/harness/hitl/approved-call-callers.ts
@@ -2,8 +2,8 @@ import type { SessionAuthContext } from "#channel/types.js";
import { runAsCaller } from "#context/caller-scope.js";
import { contextStorage } from "#context/container.js";
import { ContextKey } from "#context/key.js";
-import { approverOfRequest } from "#harness/approval-candidates.js";
-import type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
+import { approverOfRequest } from "./candidates.js";
+import type { InputRequest } from "#shared/input.js";
import type { SessionStateMap } from "#harness/types.js";
/**
@@ -14,25 +14,34 @@ const ApprovedCallCallersKey = new ContextKey<ReadonlyMap<string, SessionAuthCon
"eve.approvedCallCallers",
);
+/** Who approved each of the `approved` calls, by call id. */
+export function approversOf(
+ approved: readonly InputRequest[],
+ state: SessionStateMap | undefined,
+): Readonly<Record<string, SessionAuthContext>> {
+ const approvers: Record<string, SessionAuthContext> = {};
+ for (const request of approved) {
+ if (request.action === undefined) continue;
+ const approver = approverOfRequest(state, request.requestId);
+ if (approver !== undefined) approvers[request.action.callId] = approver;
+ }
+ return approvers;
+}
+
/**
- * Records who approved each call in `resolved`, so each approved call runs as
- * its approver while the rest of the turn keeps the turn's own caller.
+ * Records who approved each of the `approved` calls, so each runs as its approver while the rest
+ * of the turn keeps the turn's own caller.
*/
export function setApprovedCallCallers(
- resolved: readonly ResolvedInputBatch[] | undefined,
+ approved: readonly InputRequest[],
state: SessionStateMap | undefined,
): void {
const ctx = contextStorage.getStore();
if (ctx === undefined) return;
- const callers = new Map<string, SessionAuthContext>();
- for (const batch of resolved ?? []) {
- for (const { outcome, request } of batch.inputs) {
- if (outcome !== "approved" || request.action === undefined) continue;
- const approver = approverOfRequest(state, request.requestId);
- if (approver !== undefined) callers.set(request.action.callId, approver);
- }
- }
- ctx.setVirtualContext(ApprovedCallCallersKey, callers);
+ ctx.setVirtualContext(
+ ApprovedCallCallersKey,
+ new Map(Object.entries(approversOf(approved, state))),
+ );
}
/** Runs `fn` as the call's approver when `callId` is an approved call; otherwise as is. */
diff --git a/packages/eve/src/harness/hitl/approved-calls.ts b/packages/eve/src/harness/hitl/approved-calls.ts
new file mode 100644
index 000000000..a0cf075e5
--- /dev/null
+++ b/packages/eve/src/harness/hitl/approved-calls.ts
@@ -0,0 +1,340 @@
+import {
+ asSchema,
+ type ModelMessage,
+ type Telemetry,
+ type TelemetryOptions,
+ type ToolSet,
+ type TypedToolResult,
+} from "ai";
+
+import { createRuntimeToolResultFromValue } from "#harness/action-result-helpers.js";
+import { isInlineAuthorizationToolResult } from "#harness/inline-tool-authorization.js";
+import { projectDeltaPresentation, projectResultPresentation } from "#harness/tool-presentation.js";
+import { buildToolSet, recheckApprovedCall } from "#harness/tools.js";
+import { TOOL_EXECUTION_DENIED_MESSAGE } from "#harness/input-request-resolution.js";
+import { throwIfTurnAborted } from "#harness/turn-cancellation.js";
+import type { HarnessToolMap } from "#harness/types.js";
+import { emitNestedToolActions } from "#harness/nested-actions.js";
+import { createActionPartialEvent, createActionResultEvent } from "#protocol/message.js";
+import { isAsyncIterable } from "#shared/async-iterable.js";
+import { toError } from "#shared/errors.js";
+import { createLogger, logError } from "#internal/logging.js";
+import type { InputRequest } from "#shared/input.js";
+import { parseJsonObject } from "#shared/json.js";
+import type { HandleEventFn } from "#harness/types.js";
+
+type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
+export interface ApprovedCallResult {
+ readonly part: Extract<ToolResponsePart, { type: "tool-result" }>;
+}
+
+const log = createLogger("harness.tool-loop");
+
+/**
+ * Runs approved local calls before the model reads their results. Like the calls a model step
+ * runs inline, each streams its progress and result as it goes. The lifecycle owner places the
+ * results in the steps that made the calls.
+ */
+export async function runApprovedCalls(input: {
+ readonly requests: readonly InputRequest[];
+ readonly tools: HarnessToolMap;
+ readonly approvedTools?: ReadonlySet<string>;
+ /** The conversation the tools read as `ctx.messages`. */
+ readonly messages: readonly ModelMessage[];
+ readonly position: {
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+ };
+ readonly publish: HandleEventFn;
+ readonly abortSignal: AbortSignal | undefined;
+ /** The step attempt's telemetry, which hears each execution as the AI SDK reports it. */
+ readonly telemetry?: TelemetryOptions;
+}): Promise<{
+ readonly settled: readonly ApprovedCallResult[];
+ readonly toolResults: readonly TypedToolResult<ToolSet>[];
+}> {
+ const tools = buildToolSet({ tools: input.tools, approvedTools: input.approvedTools });
+ const calls = input.requests.map((request) => {
+ const definition = input.tools.get(request.action.toolName);
+ const tool = tools[request.action.toolName];
+ if (
+ definition?.execute === undefined ||
+ tool?.execute === undefined ||
+ tool.toModelOutput === undefined
+ ) {
+ throw new Error(
+ "The approved tool is no longer available. Request a new tool call and approval.",
+ );
+ }
+ return { request, definition, tool };
+ });
+ const at = {
+ sequence: input.position.sequence,
+ stepIndex: input.position.stepIndex,
+ turnId: input.position.turnId,
+ };
+ const executed = await Promise.allSettled(
+ calls.map(async ({ request, definition, tool }) => {
+ const settled: ApprovedCallResult[] = [];
+ const toolResults: TypedToolResult<ToolSet>[] = [];
+ const { callId, toolName, input: args } = request.action;
+ try {
+ throwIfTurnAborted(input.abortSignal);
+ // As in the AI SDK: the stored input revalidates against the tool's own schema and runs
+ // unchanged, so the call that runs is the one the person approved.
+ const validation = await asSchema(tool.inputSchema).validate?.(args);
+ if (validation?.success === false) {
+ const message = `The approved input is no longer valid for tool "${toolName}". Request a new tool call and approval.`;
+ await input.publish(
+ createActionResultEvent({
+ ...at,
+ result: createRuntimeToolResultFromValue({
+ callId,
+ isError: true,
+ output: message,
+ toolName,
+ }),
+ }),
+ );
+ return {
+ settled: [
+ {
+ part: {
+ type: "tool-result" as const,
+ toolCallId: callId,
+ toolName,
+ output: { type: "error-text" as const, value: message },
+ },
+ },
+ ],
+ toolResults,
+ };
+ }
+ const recheck = await recheckApprovedCall(definition, {
+ abortSignal: input.abortSignal,
+ callId,
+ input: args,
+ approvedTools: input.approvedTools,
+ });
+ if (recheck.denied) {
+ // The policy refused the call it approved earlier, so it doesn't run.
+ await input.publish(
+ createActionResultEvent({
+ ...at,
+ rejected: true,
+ result: {
+ callId,
+ isError: true,
+ kind: "tool-result",
+ output: {
+ code: "TOOL_EXECUTION_DENIED",
+ message: recheck.reason ?? TOOL_EXECUTION_DENIED_MESSAGE,
+ tool: { result: "not_run" },
+ },
+ toolName,
+ },
+ }),
+ );
+ settled.push({
+ part: {
+ output: { reason: recheck.reason, type: "execution-denied" },
+ toolCallId: callId,
+ toolName,
+ type: "tool-result",
+ },
+ });
+ return { settled, toolResults };
+ }
+ let output: unknown;
+ let failed = false;
+ const telemetry = toolTelemetry(input.telemetry, {
+ messages: [...input.messages],
+ toolCall: { input: args, toolCallId: callId, toolName, type: "tool-call" },
+ });
+ await telemetry.started();
+ let executionMs = 0;
+ try {
+ await telemetry.execute(async () => {
+ const startedAt = performance.now();
+ try {
+ const executed = tool.execute!(args, {
+ abortSignal: input.abortSignal,
+ context: undefined,
+ messages: [...input.messages],
+ toolCallId: callId,
+ });
+ if (isAsyncIterable(executed)) {
+ for await (const partial of executed) {
+ output = partial;
+ await input.publish(
+ createActionPartialEvent({
+ ...at,
+ presentation: projectDeltaPresentation(
+ definition,
+ callId,
+ parseJsonObject(args),
+ partial,
+ ),
+ result: createRuntimeToolResultFromValue({
+ callId,
+ output: partial,
+ toolName,
+ }),
+ }),
+ );
+ }
+ } else {
+ output = await executed;
+ }
+ } finally {
+ executionMs = performance.now() - startedAt;
+ }
+ });
+ } catch (error) {
+ await telemetry.ended(
+ { error, input: args, toolCallId: callId, toolName, type: "tool-error" },
+ executionMs,
+ );
+ throwIfTurnAborted(input.abortSignal);
+ logError(log, "tool execution failed", error, { toolName, toolCallId: callId });
+ failed = true;
+ output = toError(error).message;
+ }
+ if (!failed) {
+ await telemetry.ended(
+ { input: args, output, toolCallId: callId, toolName, type: "tool-result" },
+ executionMs,
+ );
+ }
+ const result = {
+ input: args,
+ output,
+ toolCallId: callId,
+ toolName,
+ type: "tool-result",
+ } as TypedToolResult<ToolSet>;
+ toolResults.push(result);
+ if (isInlineAuthorizationToolResult(result)) return { settled, toolResults };
+ // Calls the tool made on the model's behalf report before its result.
+ await emitNestedToolActions(input.publish, input.position, callId);
+ settled.push({
+ part: {
+ output: failed
+ ? { type: "error-text", value: String(output) }
+ : await tool.toModelOutput!({ input: args, output, toolCallId: callId }),
+ toolCallId: callId,
+ toolName,
+ type: "tool-result",
+ },
+ });
+ await input.publish(
+ createActionResultEvent({
+ ...at,
+ presentation: failed
+ ? undefined
+ : projectResultPresentation(definition, callId, parseJsonObject(args), output),
+ result: createRuntimeToolResultFromValue({ callId, isError: failed, output, toolName }),
+ }),
+ );
+ return { settled, toolResults };
+ } catch (error) {
+ throwIfTurnAborted(input.abortSignal);
+ const message = toError(error).message;
+ logError(log, "approved tool failed", error, { toolName, toolCallId: callId });
+ await input.publish(
+ createActionResultEvent({
+ ...at,
+ result: createRuntimeToolResultFromValue({
+ callId,
+ isError: true,
+ output: message,
+ toolName,
+ }),
+ }),
+ );
+ return {
+ settled: [
+ {
+ part: {
+ type: "tool-result" as const,
+ toolCallId: callId,
+ toolName,
+ output: { type: "error-text" as const, value: message },
+ },
+ },
+ ],
+ toolResults,
+ };
+ }
+ }),
+ );
+ const failed = executed.find((call) => call.status === "rejected");
+ if (failed?.status === "rejected") throw failed.reason;
+ const completed = executed.flatMap((call) => (call.status === "fulfilled" ? [call.value] : []));
+ return {
+ settled: completed.flatMap((call) => call.settled),
+ toolResults: completed.flatMap((call) => call.toolResults),
+ };
+}
+
+type ToolExecutionStart = Parameters<NonNullable<Telemetry["onToolExecutionStart"]>>[0];
+type ToolExecutionEnd = Parameters<NonNullable<Telemetry["onToolExecutionEnd"]>>[0];
+
+/**
+ * The telemetry around one tool execution, as the AI SDK dispatches it for an approved call it
+ * runs: each integration hears the start and the end, and their `executeTool` wrappers nest
+ * around the call so work it does is attributed to it. Integration failures don't fail the call.
+ */
+function toolTelemetry(
+ telemetry: TelemetryOptions | undefined,
+ execution: Pick<ToolExecutionStart, "messages" | "toolCall">,
+): {
+ readonly started: () => Promise<void>;
+ readonly execute: (execute: () => PromiseLike<void>) => Promise<void>;
+ readonly ended: (
+ toolOutput: ToolExecutionEnd["toolOutput"],
+ toolExecutionMs: number,
+ ) => Promise<void>;
+} {
+ const integrations =
+ telemetry === undefined || telemetry.isEnabled === false
+ ? []
+ : [telemetry.integrations ?? []].flat();
+ const event = {
+ ...execution,
+ callId: `approved:${execution.toolCall.toolCallId}`,
+ functionId: telemetry?.functionId,
+ recordInputs: telemetry?.recordInputs,
+ recordOutputs: telemetry?.recordOutputs,
+ toolContext: undefined,
+ } as ToolExecutionStart;
+ const notify = async (callback: (integration: Telemetry) => unknown) => {
+ await Promise.allSettled(integrations.map(async (integration) => await callback(integration)));
+ };
+ return {
+ started: () => notify((integration) => integration.onToolExecutionStart?.(event)),
+ execute: async (execute) => {
+ let wrapped: () => PromiseLike<void> = execute;
+ for (const integration of integrations) {
+ if (integration.executeTool === undefined) continue;
+ const inner = wrapped;
+ wrapped = () =>
+ integration.executeTool!({
+ ...event,
+ execute: inner,
+ toolCallId: execution.toolCall.toolCallId,
+ });
+ }
+ await wrapped();
+ },
+ ended: (toolOutput, toolExecutionMs) =>
+ notify((integration) =>
+ integration.onToolExecutionEnd?.({
+ ...event,
+ toolExecutionMs,
+ toolOutput,
+ } as ToolExecutionEnd),
+ ),
+ };
+}
diff --git a/packages/eve/src/harness/session-limit-continuation.test.ts b/packages/eve/src/harness/hitl/budget-request.test.ts
similarity index 99%
rename from packages/eve/src/harness/session-limit-continuation.test.ts
rename to packages/eve/src/harness/hitl/budget-request.test.ts
index 8e6ec9c24..a2a5315da 100644
--- a/packages/eve/src/harness/session-limit-continuation.test.ts
+++ b/packages/eve/src/harness/hitl/budget-request.test.ts
@@ -5,7 +5,7 @@ import {
isSessionLimitContinuationRequest,
isSessionLimitContinuationRequestId,
resolveSessionLimitContinuation,
-} from "#harness/session-limit-continuation.js";
+} from "#harness/hitl/budget-request.js";
const VIOLATION = { kind: "input", limit: 40_000_000, usedTokens: 40_120_500 } as const;
diff --git a/packages/eve/src/harness/session-limit-continuation.ts b/packages/eve/src/harness/hitl/budget-request.ts
similarity index 100%
rename from packages/eve/src/harness/session-limit-continuation.ts
rename to packages/eve/src/harness/hitl/budget-request.ts
diff --git a/packages/eve/src/harness/hitl/budget.ts b/packages/eve/src/harness/hitl/budget.ts
new file mode 100644
index 000000000..06cb46f84
--- /dev/null
+++ b/packages/eve/src/harness/hitl/budget.ts
@@ -0,0 +1,91 @@
+/**
+ * Session token and token-cost limit policy for the tool-loop harness.
+ *
+ * Before each model call, {@link checkSessionUsageLimit} says whether the
+ * session may call the model. Over budget, a session that can request input
+ * asks whether to continue (the machine's `requestLimit`); one nobody can
+ * answer fails with `SESSION_TOKEN_LIMIT_REACHED`. The answer is the
+ * machine's `answer`: a grant bumps the runtime limits with
+ * {@link bumpSessionRuntimeUsageLimits}; a decline cancels the turn tree.
+ */
+import { createSessionLimitContinuationRequest } from "#harness/hitl/budget-request.js";
+import {
+ getSessionUsageLimitViolation,
+ getSessionTokenUsage,
+ type SessionUsageLimitViolation,
+} from "#harness/turn-tag-state.js";
+import type { HarnessSession } from "#harness/types.js";
+import type { InputRequest } from "#shared/input.js";
+import type { JsonObject } from "#shared/json.js";
+
+export { bumpSessionRuntimeUsageLimits } from "#harness/turn-tag-state.js";
+
+const SESSION_TOKEN_LIMIT_REACHED_CODE = "SESSION_TOKEN_LIMIT_REACHED";
+const SESSION_TOKEN_COST_LIMIT_REACHED_CODE = "SESSION_TOKEN_COST_LIMIT_REACHED";
+
+export type SessionUsageLimitCheck =
+ | { readonly kind: "within" }
+ | { readonly kind: "ask"; readonly request: InputRequest }
+ | {
+ readonly kind: "fail";
+ readonly code: string;
+ readonly details: JsonObject;
+ readonly message: string;
+ };
+
+/** Whether the session may call the model, may ask to continue, or must fail. */
+export function checkSessionUsageLimit(input: {
+ readonly canAsk: boolean;
+ readonly session: HarnessSession;
+ readonly turnSequence: number;
+}): SessionUsageLimitCheck {
+ const violation = getSessionUsageLimitViolation(input.session);
+ if (violation === null) return { kind: "within" };
+ // A zero limit is an exhausted quota inherited by a delegated task.
+ // Approving would bump the runtime limit by the configured limit -- zero --
+ // so fail the child and let its parent reach the resumable limit gate.
+ if (violationWindow(violation) > 0 && input.canAsk) {
+ return {
+ kind: "ask",
+ request: createSessionLimitContinuationRequest({
+ sessionId: input.session.sessionId,
+ turnSequence: input.turnSequence,
+ violation,
+ }),
+ };
+ }
+ const usage = getSessionTokenUsage(input.session);
+ return {
+ code:
+ violation.kind === "token-cost"
+ ? SESSION_TOKEN_COST_LIMIT_REACHED_CODE
+ : SESSION_TOKEN_LIMIT_REACHED_CODE,
+ details:
+ violation.kind === "token-cost"
+ ? {
+ costUsd: usage.costUsd,
+ kind: violation.kind,
+ limitUsd: violation.limitUsd,
+ usedCostUsd: violation.usedCostUsd,
+ }
+ : {
+ inputTokens: usage.inputTokens,
+ kind: violation.kind,
+ limit: violation.limit,
+ outputTokens: usage.outputTokens,
+ usedTokens: violation.usedTokens,
+ },
+ kind: "fail",
+ message: formatSessionLimitMessage(violation.kind),
+ };
+}
+
+function violationWindow(violation: SessionUsageLimitViolation): number {
+ return violation.kind === "token-cost" ? violation.limitUsd : violation.limit;
+}
+
+function formatSessionLimitMessage(kind: SessionUsageLimitViolation["kind"]): string {
+ return kind === "token-cost"
+ ? "The session reached its configured model token-cost limit."
+ : `The session reached its configured ${kind} token limit.`;
+}
diff --git a/packages/eve/src/harness/approval-candidates.test.ts b/packages/eve/src/harness/hitl/candidates.test.ts
similarity index 99%
rename from packages/eve/src/harness/approval-candidates.test.ts
rename to packages/eve/src/harness/hitl/candidates.test.ts
index 7d1b2c340..c33def30e 100644
--- a/packages/eve/src/harness/approval-candidates.test.ts
+++ b/packages/eve/src/harness/hitl/candidates.test.ts
@@ -9,7 +9,7 @@ import {
markApprovalCandidateAuthorizationRequired,
settleAllowedCandidate,
settleDirectApprovalResponse,
-} from "#harness/approval-candidates.js";
+} from "#harness/hitl/candidates.js";
import type { SessionStateMap } from "#harness/types.js";
function responder(principalId: string): SessionAuthContext {
diff --git a/packages/eve/src/harness/approval-candidates.ts b/packages/eve/src/harness/hitl/candidates.ts
similarity index 87%
rename from packages/eve/src/harness/approval-candidates.ts
rename to packages/eve/src/harness/hitl/candidates.ts
index 33ff46717..a8753fb4f 100644
--- a/packages/eve/src/harness/approval-candidates.ts
+++ b/packages/eve/src/harness/hitl/candidates.ts
@@ -24,7 +24,6 @@ interface ApprovalCandidateAuditRecord {
readonly status: ApprovalCandidateStatus;
readonly createdAt: number;
readonly completedAt?: number;
- readonly eventEmitted?: boolean;
readonly expiresAt?: number;
readonly reason?: string;
}
@@ -44,7 +43,6 @@ export interface ApprovalSettlementAuditRecord {
readonly requestId: string;
readonly settledAt: number;
readonly candidateId?: string;
- readonly eventEmitted?: boolean;
}
export interface ActiveApprovalCandidate {
@@ -56,7 +54,6 @@ export interface ActiveApprovalCandidate {
readonly createdAt: number;
readonly expiresAt: number;
readonly authorizationChallenges?: readonly AuthorizationChallenge[];
- readonly pendingEventEmitted?: boolean;
}
interface DurableApprovalState {
@@ -131,59 +128,6 @@ export function createApprovalCandidate(input: {
return { changed: true, state: writeApprovalState(expiredState, next) };
}
-/** Marks the pending candidate event as emitted. */
-export function markApprovalCandidatePendingEventEmitted(input: {
- readonly candidateId: string;
- readonly state: SessionStateMap | undefined;
-}): SessionStateMap | undefined {
- const approvalState = readApprovalState(input.state);
- const candidate = approvalState.activeCandidates[input.candidateId];
- if (candidate === undefined || candidate.pendingEventEmitted === true) return input.state;
- return writeApprovalState(input.state, {
- ...approvalState,
- activeCandidates: {
- ...approvalState.activeCandidates,
- [input.candidateId]: { ...candidate, pendingEventEmitted: true },
- },
- });
-}
-
-/** Marks a terminal candidate history event as emitted. */
-export function markApprovalCandidateHistoryEventEmitted(input: {
- readonly candidateId: string;
- readonly state: SessionStateMap | undefined;
-}): SessionStateMap | undefined {
- const approvalState = readApprovalState(input.state);
- let changed = false;
- const candidateHistory = approvalState.candidateHistory.map((candidate) => {
- if (candidate.candidateId !== input.candidateId || candidate.eventEmitted === true) {
- return candidate;
- }
- changed = true;
- return { ...candidate, eventEmitted: true };
- });
- return changed
- ? writeApprovalState(input.state, { ...approvalState, candidateHistory })
- : input.state;
-}
-
-/** Marks a terminal settlement event as emitted. */
-export function markApprovalSettlementEventEmitted(input: {
- readonly requestId: string;
- readonly state: SessionStateMap | undefined;
-}): SessionStateMap | undefined {
- const approvalState = readApprovalState(input.state);
- const settlement = approvalState.settlements[input.requestId];
- if (settlement === undefined || settlement.eventEmitted === true) return input.state;
- return writeApprovalState(input.state, {
- ...approvalState,
- settlements: {
- ...approvalState.settlements,
- [input.requestId]: { ...settlement, eventEmitted: true },
- },
- });
-}
-
/** Marks a candidate as waiting on a private authorization challenge. */
export function markApprovalCandidateAuthorizationRequired(input: {
readonly authorizationChallenges: readonly AuthorizationChallenge[];
@@ -472,6 +416,27 @@ function writeApprovalState(
return { ...state, [APPROVAL_STATE_KEY]: approvalState };
}
+/**
+ * The held turn moved on, steered or cancelled: the responders still checking one of its
+ * approvals stop, their candidates stale.
+ */
+export function retireActiveCandidates(
+ state: SessionStateMap | undefined,
+ input: { readonly completedAt: number; readonly reason: string },
+): SessionStateMap | undefined {
+ let next = state;
+ for (const candidate of getApprovalAuditState(next).activeCandidates) {
+ next = finishApprovalCandidate({
+ candidateId: candidate.candidateId,
+ completedAt: input.completedAt,
+ reason: input.reason,
+ state: next,
+ status: "stale",
+ });
+ }
+ return next;
+}
+
/** The full auth of whoever approved `requestId`, when it was allowed. */
export function approverOfRequest(
state: SessionStateMap | undefined,
diff --git a/packages/eve/src/harness/approval-delivery-coordinator.test.ts b/packages/eve/src/harness/hitl/coordinator.test.ts
similarity index 89%
rename from packages/eve/src/harness/approval-delivery-coordinator.test.ts
rename to packages/eve/src/harness/hitl/coordinator.test.ts
index 63e117144..a11fc48ae 100644
--- a/packages/eve/src/harness/approval-delivery-coordinator.test.ts
+++ b/packages/eve/src/harness/hitl/coordinator.test.ts
@@ -2,18 +2,20 @@ import { describe, expect, it, vi } from "vitest";
import { jsonSchema } from "ai";
import type { ApprovalResponsePolicy } from "#approval/definition.js";
import { ContextContainer, contextStorage } from "#context/container.js";
-import { AuthKey, SessionKey } from "#context/keys.js";
+import { SessionKey } from "#context/keys.js";
import {
getApprovalAuditState,
markApprovalCandidateAuthorizationRequired,
-} from "#harness/approval-candidates.js";
+} from "#harness/hitl/candidates.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { SessionAuthContext } from "#channel/types.js";
-import { settleDirectApprovalResponse } from "#harness/approval-candidates.js";
-import { coordinateApprovalDelivery } from "#harness/approval-delivery-coordinator.js";
-import { selectApprovalReplayBatch } from "#harness/input-requests.js";
-import { appendPendingInputBatch, getPendingInputBatches } from "#harness/pending-input-batches.js";
+import { settleDirectApprovalResponse } from "#harness/hitl/candidates.js";
+import { coordinateApprovalDelivery } from "#harness/hitl/coordinator.js";
+import { approvingSteps } from "#harness/hitl/approvals.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { storedProjection } from "#harness/session-machine/view.js";
+import { parkedSteps, withParkedStep } from "#internal/testing/session-machine.js";
import type { HarnessSession } from "#harness/types.js";
import type { InputRequest } from "#shared/input.js";
@@ -37,19 +39,17 @@ const responder: SessionAuthContext = {
principalType: "user",
};
-function parkedSession(): HarnessSession {
- return appendPendingInputBatch({
- requests: [request],
- responseAuthRequiredRequestIds: [request.requestId],
- responseMessages: [],
- session: {
+function parkedSession(requester?: SessionAuthContext): HarnessSession {
+ return withParkedStep(
+ {
agent: { modelReference: { id: "test" }, system: "", tools: [] },
compaction: { recentWindowSize: 10, threshold: 0.8 },
continuationToken: "test",
history: [],
sessionId: "session-1",
},
- });
+ { requester, requests: [request], responseAuthRequiredRequestIds: [request.requestId] },
+ );
}
describe("coordinateApprovalDelivery", () => {
@@ -90,9 +90,7 @@ describe("coordinateApprovalDelivery", () => {
}
function parkedBy(auth: SessionAuthContext): HarnessSession {
- const ctx = new ContextContainer();
- ctx.set(AuthKey, auth);
- return contextStorage.run(ctx, parkedSession);
+ return parkedSession(auth);
}
it("passes the requester the batch parked with to the response policy", async () => {
@@ -124,7 +122,7 @@ describe("coordinateApprovalDelivery", () => {
);
expect(rejected.stepInput?.inputResponses ?? []).toEqual([]);
expect(getApprovalAuditState(rejected.session.state).settlements).toEqual([]);
- expect(getPendingInputBatches(rejected.session.state)).toHaveLength(1);
+ expect(parkedSteps(rejected.session)).toHaveLength(1);
const requesterCancel = await coordinateApprovalDelivery({
now: 102,
@@ -299,17 +297,16 @@ describe("coordinateApprovalDelivery", () => {
prompt: "Approve tool call: gate-2",
requestId: "approval-2",
};
- const parked = appendPendingInputBatch({
- requests: [request, secondRequest],
- responseMessages: [],
- session: {
+ const parked = withParkedStep(
+ {
agent: { modelReference: { id: "test" }, system: "", tools: [] },
compaction: { recentWindowSize: 10, threshold: 0.8 },
continuationToken: "test",
history: [],
sessionId: "session-1",
},
- });
+ { requests: [request, secondRequest] },
+ );
const settled = settleDirectApprovalResponse({
actor: responder,
outcome: "allowed",
@@ -351,7 +348,7 @@ describe("coordinateApprovalDelivery", () => {
expect(result.stepInput?.message).toBe("What else can you help with?");
expect(result.stepInput?.messageAuth).toEqual(messageAuth);
expect(
- getPendingInputBatches(result.session.state).flatMap((batch) =>
+ parkedSteps(result.session).flatMap((batch) =>
batch.requests.map((pending) => pending.requestId),
),
).toEqual([request.requestId]);
@@ -363,20 +360,9 @@ describe("approval responses without a response policy", () => {
const bob: SessionAuthContext = { ...responder, principalId: "bob" };
function parkedFor(requester: SessionAuthContext | null): HarnessSession {
- const base = appendPendingInputBatch({
- requests: [request],
- responseMessages: [],
- session: { ...parkedSession(), state: undefined },
- });
- if (requester === null) return base;
- const ctx = new ContextContainer();
- ctx.set(AuthKey, requester);
- return contextStorage.run(ctx, () =>
- appendPendingInputBatch({
- requests: [request],
- responseMessages: [],
- session: { ...parkedSession(), state: undefined },
- }),
+ return withParkedStep(
+ { ...parkedSession(), state: undefined },
+ { requester: requester ?? undefined, requests: [request] },
);
}
@@ -404,7 +390,7 @@ describe("approval responses without a response policy", () => {
]);
expect(getApprovalAuditState(result.session.state).settlements).toEqual([]);
expect(result.stepInput?.inputResponses ?? []).toEqual([]);
- expect(getPendingInputBatches(result.session.state)).toHaveLength(1);
+ expect(parkedSteps(result.session)).toHaveLength(1);
});
it("lets anyone respond when the requester is unauthenticated", async () => {
@@ -419,19 +405,18 @@ describe("text approval replay preparation", () => {
session: HarnessSession;
stepInput?: import("#harness/types.js").StepInput;
}) {
- return selectApprovalReplayBatch(input.session, input.stepInput) !== undefined;
+ const view = sessionView(storedProjection(input.session.state), input.session.state);
+ return approvingSteps(view, input.stepInput).length > 0;
}
function sessionWithRequests(
requests: InputRequest[] = [request],
responseAuthRequiredRequestIds?: string[],
) {
const base = parkedSession();
- return appendPendingInputBatch({
- requests,
- responseAuthRequiredRequestIds,
- responseMessages: [],
- session: { ...base, state: undefined },
- });
+ return withParkedStep(
+ { ...base, state: undefined },
+ { requests, responseAuthRequiredRequestIds },
+ );
}
it.each(["approve", "APPROVE", "1"])("prepares a matching text approval: %s", (message) => {
@@ -465,10 +450,9 @@ describe("text approval replay preparation", () => {
});
it("does not interpret text when multiple batches are pending", () => {
- const session = appendPendingInputBatch({
+ const session = withParkedStep(sessionWithRequests(), {
+ event: { sequence: 2, stepIndex: 0, turnId: "turn-2" },
requests: [{ ...request, requestId: "approval-2" }],
- responseMessages: [],
- session: sessionWithRequests(),
});
expect(shouldPrepareApprovalReplayTools({ session, stepInput: { message: "approve" } })).toBe(
false,
diff --git a/packages/eve/src/harness/approval-delivery-coordinator.ts b/packages/eve/src/harness/hitl/coordinator.ts
similarity index 97%
rename from packages/eve/src/harness/approval-delivery-coordinator.ts
rename to packages/eve/src/harness/hitl/coordinator.ts
index ecc42a68f..0619e0829 100644
--- a/packages/eve/src/harness/approval-delivery-coordinator.ts
+++ b/packages/eve/src/harness/hitl/coordinator.ts
@@ -19,7 +19,7 @@ import {
type ActiveApprovalCandidate,
type ApprovalCandidateDecision,
type ApprovalSettlementAuditRecord,
-} from "#harness/approval-candidates.js";
+} from "#harness/hitl/candidates.js";
import {
clearPendingAuthorization,
getAuthorizationResult,
@@ -28,7 +28,7 @@ import {
type AuthorizationChallenge,
} from "#harness/authorization.js";
import { isApprovalRequest } from "#harness/input-request-class.js";
-import { getPendingInputBatches, pendingInputRequester } from "#harness/pending-input-batches.js";
+import { suspendedSteps } from "#harness/session-machine/view.js";
import type { HarnessSession, HarnessToolMap, StepInput } from "#harness/types.js";
import type { InputRequest } from "#shared/input.js";
@@ -91,7 +91,7 @@ export async function coordinateApprovalDelivery(input: {
state: clearPendingAuthorization(expiredState, expiredChallengeIds),
};
const audit = getApprovalAuditState(session.state);
- const batches = getPendingInputBatches(session.state);
+ const batches = suspendedSteps(session.state).filter((step) => step.requests.length > 0);
const pendingRequestIds = new Set(
batches.flatMap((batch) => batch.requests.map((request) => request.requestId)),
);
@@ -151,7 +151,10 @@ export async function coordinateApprovalDelivery(input: {
// unauthenticated or anonymous requester has no identity to match, so
// any responder may settle it. A tool opts into other responders by
// defining `approval.response`.
- const requester = pendingInputRequester(session.state, response.requestId);
+ const requester =
+ suspendedSteps(session.state).find((step) =>
+ step.requests.some((request) => request.requestId === response.requestId),
+ )?.requester ?? null;
if (
responder !== null &&
decision !== undefined &&
@@ -327,7 +330,10 @@ async function authorizeCandidate(input: {
request: {
callId: input.request.action.callId,
requestId: input.request.requestId,
- principal: pendingInputRequester(session.state, input.request.requestId),
+ principal:
+ suspendedSteps(session.state).find((step) =>
+ step.requests.some((request) => request.requestId === input.request.requestId),
+ )?.requester ?? null,
toolInput: input.request.action.input,
toolName: input.request.action.toolName,
},
diff --git a/packages/eve/src/harness/hitl/delivery.ts b/packages/eve/src/harness/hitl/delivery.ts
new file mode 100644
index 000000000..c678ff71a
--- /dev/null
+++ b/packages/eve/src/harness/hitl/delivery.ts
@@ -0,0 +1,155 @@
+import type { UserContent } from "ai";
+
+import { resolveTextToResponses } from "#channel/resolve-text.js";
+import { coalesceTurnInputs } from "#harness/messages.js";
+import {
+ convertStaleResponsesToUserMessage,
+ dropStaleSessionLimitContinuationResponses,
+} from "#harness/hitl/stale-responses.js";
+import type { StepInput } from "#harness/types.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
+import { readAnswerText } from "#internal/input-text.js";
+import type { InputResponse } from "#shared/input.js";
+import type { SuspendedStep } from "#harness/session-machine/state.js";
+import { ownOpenRequestIds } from "#harness/session-machine/transitions.js";
+import type { SessionView } from "#harness/session-machine/view.js";
+
+// How a delivery reaches `answer`: queued input joins it, stale answers turn into text, and a
+// plain-text answer becomes the response it stands for.
+
+/**
+ * The delivery a step answers with: input queued behind earlier work joins it, unless the
+ * runtime still runs calls (queued input waits for them). A stale answer, to a request that
+ * already closed, never authorizes anything: a stale session-limit answer is dropped, and
+ * any other becomes plain text the model reads.
+ */
+export function deliver(
+ view: SessionView,
+ input: StepInput | undefined,
+ options: { readonly takeQueued: boolean },
+): {
+ readonly input?: StepInput;
+ readonly displayMessage?: string | UserContent;
+ readonly takeQueued: boolean;
+} {
+ const queued = options.takeQueued ? view.turn.queued : undefined;
+ const merged =
+ queued === undefined ? input : input === undefined ? queued : coalesceTurnInputs(queued, input);
+ // An approval settles on its own answer, before its batch resolves: the answer still counts
+ // while its batch waits for the rest.
+ const pendingRequestIds = new Set([
+ ...ownOpenRequestIds(view),
+ ...view.turn.suspended.flatMap((step) => step.requests.map((request) => request.requestId)),
+ ]);
+ const known = new Map(
+ Object.values(view.projection.inputs).map((entry) => [entry.request.requestId, entry.request]),
+ );
+ const converted = convertStaleResponsesToUserMessage({
+ pendingRequestIds,
+ requests: known,
+ stepInput: dropStaleSessionLimitContinuationResponses({ pendingRequestIds, stepInput: merged }),
+ });
+ return converted.kind === "converted"
+ ? {
+ displayMessage: converted.displayMessage,
+ input: converted.stepInput,
+ takeQueued: options.takeQueued,
+ }
+ : { input: converted.stepInput, takeQueued: options.takeQueued };
+}
+
+export type ResolvedStepInput = StepInput & { readonly messageConsumed?: boolean };
+
+/**
+ * Plain text answers the only pending batch, unless a response policy must decide it. A channel
+ * that wraps the typed text in an envelope for the model attaches the text itself to answer with.
+ * The answer consumes the message and the context the channel sent about it: the model reads
+ * neither.
+ */
+export function resolveTextInput(
+ batch: Pick<SuspendedStep, "requests" | "responseAuthRequiredRequestIds">,
+ stepInput: StepInput | undefined,
+): ResolvedStepInput | undefined {
+ const text = readAnswerText(stepInput);
+ if (stepInput === undefined || text === undefined) return stepInput;
+ const batchRequestIds = new Set(batch.requests.map((request) => request.requestId));
+ if (stepInput.inputResponses?.some((response) => batchRequestIds.has(response.requestId))) {
+ return stepInput;
+ }
+ const policyDecides = new Set(batch.responseAuthRequiredRequestIds ?? []);
+ const responses = resolveTextToResponses(
+ text,
+ batch.requests.filter((request) => !policyDecides.has(request.requestId)),
+ );
+ if (responses.length === 0) return stepInput;
+ return compactInput({
+ ...stepInput,
+ context: undefined,
+ inputResponses: [...(stepInput.inputResponses ?? []), ...responses],
+ message: undefined,
+ messageConsumed: true,
+ });
+}
+
+export function canonicalize(responses: readonly InputResponse[]): readonly InputResponse[] {
+ const byRequestId = new Map<string, InputResponse>();
+ for (const response of responses) byRequestId.set(response.requestId, response);
+ return [...byRequestId.values()];
+}
+
+export function hasInput(input: StepInput | undefined): boolean {
+ return input?.message !== undefined || (input?.inputResponses?.length ?? 0) > 0;
+}
+
+export function isEmptyInput(input: StepInput): boolean {
+ return Object.keys(compactInput(input)).length === 0;
+}
+
+export function withoutResponses(input: ResolvedStepInput | undefined): StepInput | undefined {
+ if (input === undefined) return undefined;
+ const {
+ attributedInputResponses: _attributed,
+ inputResponses: _responses,
+ messageConsumed: _consumed,
+ ...rest
+ } = input;
+ return rest;
+}
+
+/** The turn's own input: the message a plain-text answer didn't consume, and its context. */
+export function turnInputOnly(input: ResolvedStepInput | undefined): StepInput | undefined {
+ if (input === undefined) return undefined;
+ const result: { context?: StepInput["context"]; message?: StepInput["message"] } = {};
+ if ((input.context?.length ?? 0) > 0) result.context = input.context;
+ if (input.message !== undefined && input.messageConsumed !== true) result.message = input.message;
+ const turnInput = attachClientContext(result, readClientContext(input));
+ return isEmptyInput(turnInput) ? undefined : turnInput;
+}
+
+/** What of the input isn't the turn's: answers, and the output the session asks for. */
+export function withoutTurnInput(input: ResolvedStepInput | undefined): ResolvedStepInput {
+ const result: {
+ inputResponses?: StepInput["inputResponses"];
+ outputSchema?: StepInput["outputSchema"];
+ } = {};
+ if ((input?.inputResponses?.length ?? 0) > 0) result.inputResponses = input!.inputResponses;
+ if (input?.outputSchema !== undefined) result.outputSchema = input.outputSchema;
+ return result;
+}
+
+export function compactInput(input: ResolvedStepInput | undefined): ResolvedStepInput {
+ if (input === undefined) return {};
+ const result: {
+ context?: StepInput["context"];
+ inputResponses?: StepInput["inputResponses"];
+ message?: StepInput["message"];
+ messageConsumed?: boolean;
+ outputSchema?: StepInput["outputSchema"];
+ } = {};
+ if ((input.context?.length ?? 0) > 0) result.context = input.context;
+ if ((input.inputResponses?.length ?? 0) > 0) result.inputResponses = input.inputResponses;
+ if (input.message !== undefined) result.message = input.message;
+ if (input.messageConsumed === true) result.messageConsumed = true;
+ if (input.outputSchema !== undefined) result.outputSchema = input.outputSchema;
+ return attachClientContext(result, readClientContext(input));
+}
diff --git a/packages/eve/src/harness/hitl/index.ts b/packages/eve/src/harness/hitl/index.ts
new file mode 100644
index 000000000..1915b713b
--- /dev/null
+++ b/packages/eve/src/harness/hitl/index.ts
@@ -0,0 +1,191 @@
+import type { ModelMessage } from "ai";
+
+import type { SessionAuthContext } from "#channel/types.js";
+import { buildResponseAuthorizationTools } from "#context/build-dynamic-tools.js";
+import { AuthKey, SessionKey } from "#context/keys.js";
+import { clearPendingAuthorization } from "#harness/authorization.js";
+import type { resolveInlineAuthorizationInterrupt } from "#harness/inline-tool-authorization.js";
+import { validateHarnessModelMessages } from "#harness/messages.js";
+import { fail } from "#harness/session-machine/transitions.js";
+import type { StepCoordinates } from "#harness/session-machine/view.js";
+import type { Step } from "#harness/step/context.js";
+import type { HarnessSessionBase, HarnessToolMap, StepResult } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import type { InputRequest } from "#shared/input.js";
+import { renderPendingApprovalsInstruction } from "./approval-prompt.js";
+import {
+ grantedApprovalKeys,
+ hasRunnableQueue,
+ parkOnApprovals as parkOnApprovalsTransition,
+ requestLimit,
+ requireSignIn,
+} from "./approvals.js";
+import { checkSessionUsageLimit } from "./budget.js";
+import { retireActiveCandidates } from "./candidates.js";
+import { holdForInput } from "./intake.js";
+
+// The session's human-in-the-loop lifecycle, behind the few points where the rest of the harness
+// meets it: a delivery's answers and sign-in callbacks before its turn runs (`acceptHumanInput`),
+// the work they approved once its model step starts (`runApprovedLocalCalls`), a model step's gated calls and
+// sign-ins, the budget gate before each model call, and what the model reads about pending
+// approvals. Nothing outside this directory reads its records.
+
+export {
+ acceptHumanInput,
+ admitApprovedWork,
+ dispatchApprovedWorkflows,
+ hasApprovedWork,
+ runApprovedLocalCalls,
+ type ApprovedWork,
+ type HumanInputIntake,
+} from "./intake.js";
+export { extractToolApprovalInputRequests } from "#harness/input-extraction.js";
+export { hasRunnableQueue } from "./approvals.js";
+
+/**
+ * A model step made calls that need a person's approval: the step parks on them beside any
+ * runtime calls it made. The turn holds for the answers, unless the runtime runs calls for it
+ * meanwhile, or queued input can already run.
+ */
+export async function parkOnApprovals(
+ step: Step,
+ input: {
+ readonly event: StepCoordinates;
+ readonly messages: readonly ModelMessage[];
+ readonly requests: readonly InputRequest[];
+ readonly tasks: readonly RuntimeWorkflowTaskRequest[];
+ /** The step made calls the runtime runs, so the turn waits on them instead. */
+ readonly waitsOnRuntime: boolean;
+ },
+): Promise<StepResult> {
+ const transition = parkOnApprovalsTransition(step.view(), {
+ event: input.event,
+ messages: input.messages,
+ requests: input.requests,
+ tasks: input.tasks,
+ requester: currentRequester(step),
+ responseAuthRequiredRequestIds: responsePolicyRequestIds(step, input.requests),
+ });
+ await step.apply(transition, [...step.session.history, ...(transition.commit ?? [])]);
+ if (input.waitsOnRuntime) return { next: null, session: step.session };
+ if (hasRunnableQueue(step.view())) return { next: step.runStep, session: step.session };
+ return holdForInput(step);
+}
+
+/**
+ * A call the model step ran needs a sign-in: the calls that need it stop, and the model calls
+ * them again once it completes.
+ */
+export async function stopForToolSignIn(
+ step: Step,
+ interrupt: NonNullable<ReturnType<typeof resolveInlineAuthorizationInterrupt>>,
+): Promise<StepResult> {
+ step.session = { ...step.session, history: validateHarnessModelMessages(interrupt.history) };
+ await step.apply(
+ requireSignIn(step.view(), {
+ callIdsByName: interrupt.callIdsByName,
+ challenges: interrupt.challenges,
+ }),
+ step.session.history,
+ );
+ return { held: { kind: "request" }, next: null, session: step.session };
+}
+
+/**
+ * The gate before each model call. A spent budget asks whether to continue when someone can
+ * answer, and fails the session otherwise. `messages` are the step's: they park with the prompt,
+ * so the input that triggered it survives into the turn that resumes.
+ */
+export async function enforceBudget(
+ step: Step,
+ messages: readonly ModelMessage[],
+): Promise<StepResult | undefined> {
+ const limit = checkSessionUsageLimit({
+ canAsk: step.emit !== undefined && step.config.capabilities?.requestInput === true,
+ session: step.session,
+ turnSequence: step.position().sequence,
+ });
+ if (limit.kind === "within") return undefined;
+ if (limit.kind === "ask") {
+ step.session = { ...step.session, history: validateHarnessModelMessages([...messages]) };
+ await step.apply(requestLimit(step.view(), { request: limit.request }), step.session.history);
+ return { next: null, session: step.session };
+ }
+ await step.apply(
+ fail(step.view(), {
+ code: limit.code,
+ details: limit.details,
+ message: limit.message,
+ terminal: { sessionId: step.session.sessionId },
+ }),
+ );
+ return { next: { done: true, output: "" }, session: step.session };
+}
+
+/**
+ * What a model call needs from the approvals: the keys `once()` approvals granted, and a note on
+ * the calls still awaiting approval, which a message may revise.
+ */
+export function humanInputContext(step: Step): {
+ readonly approvedTools: ReadonlySet<string>;
+ readonly pendingApprovalsNote?: string;
+} {
+ const view = step.view();
+ const tools = responseTools(step);
+ return {
+ approvedTools: grantedApprovalKeys(view, (request) =>
+ tools.get(request.action.toolName)?.approvalKey?.(request.action.input),
+ ),
+ pendingApprovalsNote: renderPendingApprovalsInstruction(
+ view.turn.suspended.flatMap((parked) => parked.requests),
+ ),
+ };
+}
+
+const APPROVAL_STATE_KEY = "eve.runtime.hitl.approvalState";
+
+/**
+ * Drops what a cleared context owned: sign-in attempts and responders' approval progress. `clear`
+ * reported each close; relay routes for live tasks stay.
+ */
+export function discardClearedHumanInput<T extends HarnessSessionBase>(session: T): T {
+ const { [APPROVAL_STATE_KEY]: _approvals, ...state } =
+ clearPendingAuthorization(session.state) ?? {};
+ return { ...session, state: Object.keys(state).length > 0 ? state : undefined };
+}
+
+function responseTools(step: Step): HarnessToolMap {
+ return buildResponseAuthorizationTools({ authoredTools: step.config.tools, context: step.ctx });
+}
+
+/**
+ * The approvals whose tool defines a response policy. Every park records them, so no Approve or
+ * Cancel of such an approval skips the policy.
+ */
+function responsePolicyRequestIds(
+ step: Step,
+ requests: readonly InputRequest[],
+): readonly string[] {
+ const tools = responseTools(step);
+ return requests
+ .filter((request) => {
+ const approval = tools.get(request.action.toolName)?.approval;
+ return (
+ approval !== undefined && typeof approval !== "function" && approval.response !== undefined
+ );
+ })
+ .map((request) => request.requestId);
+}
+
+/** The caller whose turn parks a step. */
+function currentRequester(step: Step): SessionAuthContext | null {
+ return step.ctx?.get(AuthKey) ?? step.ctx?.get(SessionKey)?.auth.current ?? null;
+}
+
+/** The cancelled turn's responders stop checking its approvals: their candidates stale. */
+export function retireCancelledCandidates<T extends HarnessSessionBase>(session: T): T {
+ return {
+ ...session,
+ state: retireActiveCandidates(session.state, { completedAt: Date.now(), reason: "Cancelled." }),
+ };
+}
diff --git a/packages/eve/src/harness/hitl/intake.ts b/packages/eve/src/harness/hitl/intake.ts
new file mode 100644
index 000000000..551d63942
--- /dev/null
+++ b/packages/eve/src/harness/hitl/intake.ts
@@ -0,0 +1,392 @@
+import { buildResponseAuthorizationTools } from "#context/build-dynamic-tools.js";
+import { collectDeferredCalls } from "#harness/coordination.js";
+import { resolveInlineAuthorizationInterrupt } from "#harness/inline-tool-authorization.js";
+import { stepStartedForResolvers } from "#harness/session-machine/resolver-events.js";
+import {
+ approvedCalls,
+ completeSignIn,
+ hold,
+ settle,
+} from "#harness/session-machine/transitions.js";
+import type { SuspendedStep } from "#harness/session-machine/view.js";
+import { validateHarnessModelMessages } from "#harness/messages.js";
+import { openTurn, type Step } from "#harness/step/context.js";
+import { prepareTurnInput } from "#harness/step/intake.js";
+import { placeTurnInput } from "#harness/step/prompt.js";
+import { SessionLimitDeclinedError } from "#harness/turn-cancellation.js";
+import { bumpSessionRuntimeUsageLimits } from "#harness/turn-tag-state.js";
+import type { HarnessToolMap, StepInput, StepResult } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import {
+ answer,
+ approvingSteps,
+ grantedApprovalKeys,
+ dispatch,
+ requireSignIn,
+ deferInput,
+ stepForRequest,
+ withdrawSignIns,
+} from "./approvals.js";
+import { runApprovedCalls } from "./approved-calls.js";
+import { getApprovalAuditState, retireActiveCandidates } from "./candidates.js";
+import { coordinateApprovalDelivery } from "./coordinator.js";
+import { deliver, turnInputOnly, withoutTurnInput } from "./delivery.js";
+import { approversOf, setApprovedCallCallers } from "./approved-call-callers.js";
+import type { InputRequest } from "#shared/input.js";
+import type { InstrumentationAttempt } from "#instrumentation/runtime.js";
+import { activeTurnId } from "#harness/session-machine/view.js";
+
+/**
+ * What a delivery does before its turn runs. `stop` ends the step: the answers left nothing to
+ * run yet, so the turn holds, or a responder must sign in first. `run` carries the turn's input,
+ * without the answers the session took, and the approved work that runs once the turn opens.
+ */
+export type HumanInputIntake =
+ | { readonly kind: "stop"; readonly result: StepResult }
+ | {
+ readonly kind: "run";
+ readonly input: StepInput | undefined;
+ /** The message the turn receives, as the stream shows it. */
+ readonly message?: StepInput["message"];
+ /** A plain-text answer consumed the message, so the model never reads it. */
+ readonly consumedMessage: boolean;
+ /** The delivery carries input for a turn. */
+ readonly opensTurn: boolean;
+ readonly approved: ApprovedWork;
+ };
+
+/**
+ * What the delivery decided: the session-limit answer, and the tools approved calls run with.
+ * The calls themselves wait in their suspended steps until the turn's next model step.
+ */
+export interface ApprovedWork {
+ readonly limit?: { readonly granted: boolean };
+ /** The tools a parked step's calls run with: those of the step that asked. */
+ readonly toolsOf: (step: SuspendedStep | undefined) => HarnessToolMap;
+}
+
+/**
+ * Answers what the session asked: approval answers pass the response policies, and the session
+ * decides which parked steps they resolve. Runs before the delivery joins its turn, so approved
+ * calls get the tools of the step that asked.
+ */
+export async function acceptHumanInput(
+ step: Step,
+ input: StepInput | undefined,
+ options: { readonly takeQueued: boolean },
+): Promise<HumanInputIntake> {
+ const { config, ctx } = step;
+ // A sign-in completes first, at the coordinates of the turn it holds.
+ const completions = config.signInCompletions ?? [];
+ if (completions.length > 0) await step.apply(completeSignIn(step.view(), { completions }));
+ const delivered = deliver(step.view(), input, options);
+ // A new message reaching the held turn steers it: the sign-ins it waits on end, and its
+ // unanswered approvals resolve with the answers below.
+ const steered =
+ input?.message !== undefined || delivered.displayMessage !== undefined
+ ? await withdrawSteeredSignIns(step, delivered.input)
+ : delivered.input;
+ // Restoring a turn's tools runs its resolvers, so a step's tools are restored once, and again
+ // only after another step's.
+ const restoredTools = new Map<string, HarnessToolMap>();
+ let restoredStep: string | undefined;
+ const restoreTools = async (parked: SuspendedStep | undefined): Promise<HarnessToolMap> => {
+ const at = parked?.event ?? step.position();
+ const key = `${at.turnId}:${at.stepIndex}`;
+ const restored = restoredTools.get(key);
+ if (restored !== undefined && restoredStep === key) return restored;
+ if (parked !== undefined) await config.prepareApprovalTurn?.(parked.event);
+ if (ctx !== undefined) {
+ await config.resolveStepDynamicTools?.({
+ ctx,
+ event: stepStartedForResolvers({
+ modelId: step.session.agent.modelReference?.id ?? "dynamic",
+ sequence: at.sequence,
+ stepIndex: at.stepIndex,
+ turnId: at.turnId,
+ }),
+ messages: step.projectHistory(step.session.history),
+ });
+ }
+ const tools = buildResponseAuthorizationTools({ authoredTools: config.tools, context: ctx });
+ restoredTools.set(key, tools);
+ restoredStep = key;
+ return tools;
+ };
+ const toolsOf = (parked: SuspendedStep | undefined) =>
+ (parked && restoredTools.get(`${parked.event.turnId}:${parked.event.stepIndex}`)) ??
+ config.tools;
+
+ const challengesAtStart = step.view().signIns;
+ const coordinated = await coordinateApprovalDelivery({
+ session: step.session,
+ stepInput: steered,
+ tools: config.tools,
+ prepareTools: (request) => restoreTools(stepForRequest(step.view(), request.requestId)),
+ });
+ step.session = coordinated.session;
+
+ for (const parked of approvingSteps(step.view(), coordinated.stepInput)) {
+ await restoreTools(parked);
+ }
+ const decision = answer(step.view(), {
+ approvalKey: (request) =>
+ toolsOf(stepForRequest(step.view(), request.requestId))
+ .get(request.action.toolName)
+ ?.approvalKey?.(request.action.input),
+ delivery: coordinated.stepInput,
+ policy: {
+ ...coordinated,
+ audit: getApprovalAuditState(step.session.state),
+ challengesAtStart,
+ },
+ takeQueued: delivered.takeQueued,
+ });
+ for (const batch of decision.resolved) {
+ await step.instrumentation?.publishInputResolutions({
+ batch,
+ sessionId: step.session.sessionId,
+ });
+ }
+ await step.apply(decision);
+ const stop = (result: StepResult): HumanInputIntake => ({ kind: "stop", result });
+ switch (decision.next) {
+ case "park":
+ // A held turn's request is still open: a partial answer, or one a policy refused.
+ if (step.view().projection.activeTurnId === undefined) {
+ return stop({ next: null, session: step.session });
+ }
+ return stop(await holdForInput(step));
+ case "repeat":
+ return stop({ next: step.runStep, session: step.session });
+ case "sign-in":
+ await step.apply(
+ requireSignIn(step.view(), {
+ challenges: coordinated.challenges,
+ queued: coordinated.stepInput,
+ }),
+ );
+ return stop(held(step));
+ case "defer-message": {
+ // Approved calls wait behind the budget prompt, and the message waits behind them.
+ if (approvedCalls(step.view().turn).length > 0) {
+ const deferred = turnInputOnly(decision.input);
+ if (deferred !== undefined) await step.apply(deferInput(step.view(), deferred));
+ return stop({ next: null, session: step.session });
+ }
+ // The message is received now, into a turn that holds for the budget prompt: the grant
+ // resumes that turn, and the model reads the message from history.
+ const turn = await prepareTurnInput(step, decision.input, { consumedMessage: false });
+ const failed = await openTurn(step, {
+ input: [...turn.ephemeral, ...turn.messages],
+ message: delivered.displayMessage ?? decision.input?.message,
+ });
+ if (failed !== undefined) return stop(failed);
+ step.session = {
+ ...step.session,
+ history: validateHarnessModelMessages(placeTurnInput(step, step.session.history, turn)),
+ };
+ return stop(await holdForInput(step));
+ }
+ case "continue":
+ break;
+ }
+ // Approved calls run with the tools of the step that asked, including calls approved by an
+ // earlier delivery whose turn the budget stopped.
+ for (const parked of step.view().turn.suspended) {
+ if ((parked.approved?.length ?? 0) > 0) await restoreTools(parked);
+ }
+ // What the answers resolved comes before the delivery's own input, as with the AI SDK: the model
+ // reads the approved calls' results and the denials first, and the input waits a step. A
+ // message that steers past unanswered approvals joins this step.
+ const answeredApprovals = decision.resolved.some(
+ (batch) =>
+ batch.inputs.some((entry) => entry.request.kind === "tool-approval") &&
+ batch.inputs.every((entry) => entry.response !== undefined),
+ );
+ const deferred =
+ answeredApprovals || approvedCalls(step.view().turn).length > 0
+ ? turnInputOnly(decision.input)
+ : undefined;
+ if (deferred !== undefined) await step.apply(deferInput(step.view(), deferred));
+ return {
+ approved: { limit: decision.limit, toolsOf },
+ consumedMessage: decision.consumedMessage === true,
+ input: deferred === undefined ? decision.input : withoutTurnInput(decision.input),
+ message:
+ decision.consumedMessage === true || deferred !== undefined
+ ? undefined
+ : (delivered.displayMessage ?? delivered.input?.message),
+ kind: "run",
+ opensTurn: hasTurnInput(delivered.input) || hasTurnInput(coordinated.stepInput),
+ };
+}
+
+/**
+ * Admits what a delivery decided before its turn calls the model: a session-limit answer grants a
+ * fresh budget or ends the turn tree, and a step its answers completed, as denials do, commits.
+ */
+export async function admitApprovedWork(step: Step, work: ApprovedWork): Promise<void> {
+ if (work.limit !== undefined) {
+ if (!work.limit.granted) throw new SessionLimitDeclinedError();
+ step.session = bumpSessionRuntimeUsageLimits(step.session);
+ }
+ await step.apply(settle(step.view(), { results: [] }));
+}
+
+/** Whether a suspended step holds approved calls that haven't run. */
+export function hasApprovedWork(step: Step): boolean {
+ return approvedCalls(step.view().turn).length > 0;
+}
+
+/**
+ * Approved workflow and agent calls join the runs their steps wait on, once the step has started
+ * and before its budget check. Returns whether any did: the turn then waits on the runtime, and
+ * approved local calls run after their results arrive.
+ */
+export async function dispatchApprovedWorkflows(step: Step, work: ApprovedWork): Promise<boolean> {
+ const tasks: RuntimeWorkflowTaskRequest[] = [];
+ const approved: InputRequest[] = [];
+ for (const parked of step.view().turn.suspended) {
+ const tools = work.toolsOf(parked);
+ const requests = (parked.approved ?? []).filter(
+ (request) => tools.get(request.action.toolName)?.workflowId !== undefined,
+ );
+ if (requests.length === 0) continue;
+ approved.push(...requests);
+ const deferred = collectDeferredCalls({
+ session: step.session,
+ toolCalls: requests.map(({ action }) => ({
+ input: action.input,
+ toolCallId: action.callId,
+ toolName: action.toolName,
+ })),
+ tools,
+ turnId: parked.event.turnId,
+ });
+ step.session = deferred.session;
+ tasks.push(...deferred.workflowRequests);
+ }
+ if (tasks.length === 0) return false;
+ await step.apply(
+ dispatch(step.view(), { approvers: approversOf(approved, step.session.state), tasks }),
+ );
+ return true;
+}
+
+/**
+ * Runs approved local calls once the step has started and its budget allows it, as the AI SDK ran
+ * them before the model read their results: each with the tools of the step that asked, as
+ * whoever approved it, and in the step's first attempt. A call that needs a sign-in holds the
+ * turn.
+ */
+export async function runApprovedLocalCalls(
+ step: Step,
+ work: ApprovedWork,
+ setAttemptScope: (scope: InstrumentationAttempt | undefined) => void,
+): Promise<StepResult | undefined> {
+ const local = step.view().turn.suspended.map((parked) => {
+ const tools = work.toolsOf(parked);
+ const requests = (parked.approved ?? []).filter(
+ (request) => tools.get(request.action.toolName)?.workflowId === undefined,
+ );
+ return { requests, tools };
+ });
+ const approved = local.flatMap(({ requests }) => requests);
+ step.frameworkToolNames = new Set(
+ local.flatMap(({ tools }) =>
+ [...tools].filter(([, tool]) => tool.frameworkTool === true).map(([name]) => name),
+ ),
+ );
+ setApprovedCallCallers(approved, step.session.state);
+ const position = step.position();
+ const attempt =
+ approved.length === 0
+ ? undefined
+ : step.instrumentation?.prepareAttempt({
+ isFrameworkTool: (name) => step.frameworkToolNames.has(name),
+ attemptIndex: 0,
+ stepIndex: position.stepIndex,
+ turnId: activeTurnId(position),
+ });
+ if (attempt !== undefined) setAttemptScope(attempt.scope);
+ const executed = await Promise.all(
+ local.map(async ({ requests, tools }) => {
+ if (requests.length === 0) return { settled: [], toolResults: [] };
+ return await runApprovedCalls({
+ abortSignal: step.config.abortSignal,
+ approvedTools: grantedApprovalKeys(step.view(), (request) =>
+ tools.get(request.action.toolName)?.approvalKey?.(request.action.input),
+ ),
+ messages: step.projectHistory(step.session.history),
+ position: step.position(),
+ publish: step.publish,
+ requests,
+ telemetry: attempt?.telemetry,
+ tools,
+ });
+ }),
+ );
+ await step.apply(settle(step.view(), { results: executed.flatMap((run) => run.settled) }));
+ const signIn = resolveInlineAuthorizationInterrupt({
+ messages: [],
+ toolResults: executed.flatMap((run) => run.toolResults),
+ });
+ if (signIn === undefined) return undefined;
+ await step.apply(
+ requireSignIn(step.view(), {
+ callIdsByName: signIn.callIdsByName,
+ challenges: signIn.challenges,
+ }),
+ step.session.history,
+ );
+ return held(step);
+}
+
+const STEERED_SIGN_IN_REASON = "Cancelled because a new message arrived.";
+
+/**
+ * The held turn holds on, for a person to act on its sign-in, approval, or the session-limit
+ * prompt; the session resumes it when they do.
+ */
+export async function holdForInput(step: Step): Promise<StepResult> {
+ await step.apply(hold(step.view(), { on: "input" }));
+ return held(step);
+}
+
+function held(step: Step): StepResult {
+ return { held: { kind: "request" }, next: null, session: step.session };
+}
+
+/**
+ * A message steers the held turn: the responders still checking its approvals stop, the sign-ins
+ * it waits on end, declined, and the model learns why.
+ */
+async function withdrawSteeredSignIns(
+ step: Step,
+ input: StepInput | undefined,
+): Promise<StepInput | undefined> {
+ const names = [...new Set(step.view().signIns.map((challenge) => challenge.name))];
+ step.session = {
+ ...step.session,
+ state: retireActiveCandidates(step.session.state, {
+ completedAt: Date.now(),
+ reason: STEERED_SIGN_IN_REASON,
+ }),
+ };
+ if (names.length === 0) return input;
+ await step.apply(withdrawSignIns(step.view(), STEERED_SIGN_IN_REASON));
+ return {
+ ...input,
+ context: [
+ ...(input?.context ?? []),
+ `Sign-in to ${names.join(", ")} was cancelled because the user sent a new message instead. Ask to sign in again only if the new message still needs it.`,
+ ],
+ };
+}
+
+/** Whether the input carries user-facing turn input. */
+function hasTurnInput(input: StepInput | undefined): boolean {
+ if (input === undefined) return false;
+ return input.message !== undefined || (input.inputResponses?.length ?? 0) > 0;
+}
diff --git a/packages/eve/src/harness/hitl/pending-input-resolution.ts b/packages/eve/src/harness/hitl/pending-input-resolution.ts
deleted file mode 100644
index 012214bf8..000000000
--- a/packages/eve/src/harness/hitl/pending-input-resolution.ts
+++ /dev/null
@@ -1,148 +0,0 @@
-import type { ModelMessage } from "ai";
-
-import type { RuntimeToolResultActionResult } from "#shared/action-types.js";
-import type { InputResponse } from "#shared/input.js";
-import type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
-import type { PendingInputBatch, PendingInputBatchEvent } from "#harness/pending-input-batches.js";
-import { queueDeferredStepInput } from "#harness/pending-input-batches.js";
-import type { HarnessSession, StepInput } from "#harness/types.js";
-import { attachClientContext, readClientContext } from "#internal/client-context.js";
-
-export type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
-
-/** Action results from one resolved batch, attributed to their originating turn. */
-export interface ResolvedInputActionBatch {
- readonly event: PendingInputBatchEvent;
- readonly results: readonly RuntimeToolResultActionResult[];
-}
-
-export type ResolvedStepInput = StepInput & { readonly messageConsumed?: boolean };
-
-export type InputDomainResolverInput = {
- readonly baseHistory: ModelMessage[];
- readonly batches: readonly PendingInputBatch[];
- readonly deferTurnInput: boolean;
- readonly resolvedStepInput: ResolvedStepInput | undefined;
- readonly responses: readonly InputResponse[];
- readonly session: HarnessSession;
-};
-
-export type ResolvePendingInputResult = {
- readonly consumedMessage?: boolean;
- readonly deferredContext?: boolean;
- readonly deferredMessage?: boolean;
- /** Present when a session-limit continuation prompt was resolved. */
- readonly limitContinuation?: { readonly granted: boolean };
- readonly outcome: "resolved" | "continue" | "unresolved";
- readonly messages: ModelMessage[];
- readonly rejectedActions?: readonly ResolvedInputActionBatch[];
- readonly resolvedInputs?: readonly ResolvedInputBatch[];
- readonly session: HarnessSession;
-};
-
-export function responsesForBatches(
- responses: readonly InputResponse[],
- batches: readonly PendingInputBatch[],
-): readonly InputResponse[] {
- return responses.filter((response) =>
- batches.some((batch) =>
- batch.requests.some((request) => request.requestId === response.requestId),
- ),
- );
-}
-
-export function appendResolvedBatchTranscript(
- messages: ModelMessage[],
- batch: PendingInputBatch,
- toolParts: readonly ToolResponsePart[],
-): void {
- messages.push(...batch.responseMessages);
- if (toolParts.length > 0) {
- messages.push({ content: [...toolParts], role: "tool" });
- }
-}
-
-export function finishResolvedInput(input: {
- readonly deferTurnInput: boolean;
- readonly leftoverResponses: readonly InputResponse[];
- readonly limitContinuation?: { readonly granted: boolean };
- readonly messages: ModelMessage[];
- readonly rejectedActions?: readonly ResolvedInputActionBatch[];
- readonly resolvedInputs?: readonly ResolvedInputBatch[];
- readonly resolvedStepInput: ResolvedStepInput | undefined;
- readonly session: HarnessSession;
-}): ResolvePendingInputResult {
- // AI SDK collects approval responses only from the tail tool message. Turn
- // input must replay after that isolated approval response.
- const deferredInput: {
- context?: StepInput["context"];
- inputResponses?: StepInput["inputResponses"];
- message?: StepInput["message"];
- } = {};
- let clientContext: readonly string[] | undefined;
- if (input.leftoverResponses.length > 0) {
- deferredInput.inputResponses = input.leftoverResponses;
- }
- if (input.deferTurnInput) {
- if ((input.resolvedStepInput?.context?.length ?? 0) > 0) {
- deferredInput.context = input.resolvedStepInput?.context;
- }
- const resolvedClientContext = readClientContext(input.resolvedStepInput);
- if ((resolvedClientContext?.length ?? 0) > 0) {
- clientContext = resolvedClientContext;
- }
- if (input.resolvedStepInput?.message !== undefined) {
- deferredInput.message = input.resolvedStepInput.message;
- }
- }
- attachClientContext(deferredInput, clientContext);
-
- if (Object.keys(deferredInput).length > 0) {
- return {
- consumedMessage: input.resolvedStepInput?.messageConsumed,
- deferredContext:
- deferredInput.context === undefined && readClientContext(deferredInput) === undefined
- ? undefined
- : true,
- deferredMessage: deferredInput.message === undefined ? undefined : true,
- limitContinuation: input.limitContinuation,
- outcome: "resolved",
- messages: input.messages,
- rejectedActions: input.rejectedActions,
- resolvedInputs: input.resolvedInputs,
- session: queueDeferredStepInput(input.session, deferredInput),
- };
- }
-
- return {
- consumedMessage: input.resolvedStepInput?.messageConsumed,
- limitContinuation: input.limitContinuation,
- outcome: "resolved",
- messages: input.messages,
- rejectedActions: input.rejectedActions,
- resolvedInputs: input.resolvedInputs,
- session: input.session,
- };
-}
-
-export function compactStepInput(input: ResolvedStepInput | undefined): ResolvedStepInput {
- if (input === undefined) {
- return {};
- }
-
- const result: {
- context?: StepInput["context"];
- inputResponses?: StepInput["inputResponses"];
- message?: StepInput["message"];
- messageConsumed?: boolean;
- outputSchema?: StepInput["outputSchema"];
- } = {};
-
- if ((input.context?.length ?? 0) > 0) result.context = input.context;
- if ((input.inputResponses?.length ?? 0) > 0) result.inputResponses = input.inputResponses;
- if (input.message !== undefined) result.message = input.message;
- if (input.messageConsumed === true) result.messageConsumed = true;
- if (input.outputSchema !== undefined) result.outputSchema = input.outputSchema;
-
- return attachClientContext(result, readClientContext(input));
-}
diff --git a/packages/eve/src/harness/hitl/session-limit-input-requests.ts b/packages/eve/src/harness/hitl/session-limit-input-requests.ts
deleted file mode 100644
index ac67efa08..000000000
--- a/packages/eve/src/harness/hitl/session-limit-input-requests.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import type { PendingInputBatch } from "#harness/pending-input-batches.js";
-import { buildResolvedInputBatch } from "#harness/input-request-resolution.js";
-import {
- getPendingInputBatches,
- queueDeferredStepInput,
- removePendingInputBatches,
-} from "#harness/pending-input-batches.js";
-import {
- appendResolvedBatchTranscript,
- compactStepInput,
- finishResolvedInput,
- responsesForBatches,
-} from "#harness/hitl/pending-input-resolution.js";
-import type {
- InputDomainResolverInput,
- ResolvePendingInputResult,
-} from "#harness/hitl/pending-input-resolution.js";
-import {
- isSessionLimitContinuationRequest,
- resolveSessionLimitContinuation,
-} from "#harness/session-limit-continuation.js";
-import type { HarnessSession } from "#harness/types.js";
-
-const SESSION_LIMIT_BATCH_INVARIANT_MESSAGE =
- "Session-limit pending input batches must contain only session-limit requests.";
-
-/** Returns whether this is a valid session-limit batch and rejects mixed ownership. */
-export function isSessionLimitInputBatch(batch: PendingInputBatch): boolean {
- const hasSessionLimit = batch.requests.some((request) => request.kind === "session-limit");
- if (hasSessionLimit && batch.requests.some((request) => request.kind !== "session-limit")) {
- throw new TypeError(SESSION_LIMIT_BATCH_INVARIANT_MESSAGE);
- }
- return hasSessionLimit;
-}
-
-export function resolveSessionLimitInput(
- input: InputDomainResolverInput & { readonly pendingBatch: PendingInputBatch },
-): ResolvePendingInputResult {
- const responseIds = new Set(input.responses.map((response) => response.requestId));
- const answered =
- input.pendingBatch.requests.some((request) => responseIds.has(request.requestId)) &&
- input.pendingBatch.requests.every((request) => responseIds.has(request.requestId));
- if (!answered) {
- return {
- deferredMessage: true,
- outcome: "unresolved",
- messages: [...input.baseHistory],
- session: queueDeferredStepInput(input.session, compactStepInput(input.resolvedStepInput)),
- };
- }
-
- const openBatches = input.batches.filter((batch) => batch !== input.pendingBatch);
- const leftoverResponses = responsesForBatches(input.responses, openBatches);
- const limitBlocked = openBatches.some((batch) =>
- batch.requests.some((request) => isSessionLimitContinuationRequest(request)),
- );
- const messages = [...input.baseHistory];
- appendResolvedBatchTranscript(messages, input.pendingBatch, []);
- const session = removePendingInputBatches(input.session, [input.pendingBatch]);
- const limitContinuation = resolveSessionLimitContinuation({
- requests: input.pendingBatch.requests,
- responses: input.responses,
- });
-
- return finishResolvedInput({
- deferTurnInput: input.deferTurnInput || limitBlocked,
- leftoverResponses,
- limitContinuation,
- messages,
- resolvedInputs: [buildResolvedInputBatch(input.pendingBatch, input.responses)].filter(
- (batch): batch is NonNullable<typeof batch> => batch !== undefined,
- ),
- resolvedStepInput: input.resolvedStepInput,
- session,
- });
-}
-
-/** A batch of only harness-authored session-limit prompts, which a cancel drops. */
-export function isSessionLimitPromptBatch(batch: PendingInputBatch): boolean {
- return (
- batch.requests.length > 0 &&
- batch.requests.every((request) => isSessionLimitContinuationRequest(request))
- );
-}
-
-/** Drops only harness-authored session-limit prompts from a parked session. */
-export function clearPendingSessionLimitPrompt(session: HarnessSession): HarnessSession {
- const dropped = getPendingInputBatches(session.state).filter(isSessionLimitPromptBatch);
- if (dropped.length === 0) {
- return session;
- }
- return removePendingInputBatches(session, dropped);
-}
diff --git a/packages/eve/src/harness/stale-input-responses.test.ts b/packages/eve/src/harness/hitl/stale-responses.test.ts
similarity index 85%
rename from packages/eve/src/harness/stale-input-responses.test.ts
rename to packages/eve/src/harness/hitl/stale-responses.test.ts
index 0a07e3185..b13b36c1e 100644
--- a/packages/eve/src/harness/stale-input-responses.test.ts
+++ b/packages/eve/src/harness/hitl/stale-responses.test.ts
@@ -1,55 +1,40 @@
import { expect, it } from "vitest";
-import type { ModelMessage } from "ai";
+import type { InputRequest } from "#shared/input.js";
import {
convertStaleResponsesToUserMessage,
dropStaleSessionLimitContinuationResponses,
-} from "#harness/stale-input-responses.js";
-
-const approvalHistory: ModelMessage[] = [
- {
- content: [
- {
+} from "#harness/hitl/stale-responses.js";
+
+/** Requests the session still knows, closed ones included. */
+const knownApproval = new Map<string, InputRequest>([
+ [
+ "approval-1",
+ {
+ action: {
+ callId: "call-1",
input: { command: "deploy --force" },
- toolCallId: "call-1",
+ kind: "tool-call",
toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "call-1",
- type: "tool-approval-request",
},
- ],
- role: "assistant",
- },
-];
-
-const unrecoverableHistory: ModelMessage[] = [
- {
- content: [
- {
- input: {
- allowFreeform: true,
- options: [
- { id: "current", label: "Use current context" },
- { id: "candidate", label: "Use the candidate" },
- ],
- prompt: "Which context should I use?",
- },
- toolCallId: "question-1",
- toolName: "ask_question",
- type: "tool-call",
- },
- ],
- role: "assistant",
- },
-];
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "cancel", label: "Cancel" },
+ ],
+ prompt: "Approve tool call: bash",
+ requestId: "approval-1",
+ },
+ ],
+]);
+
+/** The session no longer knows the request a response answers. */
+const unknown = new Map<string, InputRequest>();
it("converts a stale approval into a non-authorizing user message", () => {
const result = convertStaleResponsesToUserMessage({
- history: approvalHistory,
+ requests: knownApproval,
pendingRequestIds: new Set(),
stepInput: {
inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
@@ -63,7 +48,9 @@ it("converts a stale approval into a non-authorizing user message", () => {
expect(result.displayMessage).toBe("Approve");
expect(result.stepInput.inputResponses).toBeUndefined();
- expect(result.stepInput.message).toEqual(expect.stringContaining('"prompt": "Approve Bash?"'));
+ expect(result.stepInput.message).toEqual(
+ expect.stringContaining('"prompt": "Approve tool call: bash"'),
+ );
expect(result.stepInput.message).toEqual(expect.stringContaining('"toolName": "bash"'));
expect(result.stepInput.message).toEqual(expect.stringContaining('"label": "Approve"'));
expect(result.stepInput.message).toEqual(
@@ -73,7 +60,7 @@ it("converts a stale approval into a non-authorizing user message", () => {
it("converts an attributed stale approval using its option label", () => {
const result = convertStaleResponsesToUserMessage({
- history: approvalHistory,
+ requests: knownApproval,
pendingRequestIds: new Set(),
stepInput: {
attributedInputResponses: [
@@ -102,7 +89,7 @@ it("converts an attributed stale approval using its option label", () => {
it("keeps responses for pending requests structured while converting stale ones", () => {
const result = convertStaleResponsesToUserMessage({
- history: unrecoverableHistory,
+ requests: unknown,
pendingRequestIds: new Set(["question-2"]),
stepInput: {
inputResponses: [
@@ -124,7 +111,7 @@ it("keeps responses for pending requests structured while converting stale ones"
it("keeps the non-authorization notice when request metadata is missing", () => {
const result = convertStaleResponsesToUserMessage({
- history: [],
+ requests: unknown,
pendingRequestIds: new Set(),
stepInput: {
inputResponses: [{ optionId: "approve", requestId: "approval-gone" }],
@@ -148,7 +135,7 @@ it("returns unchanged when every response matches the pending batch", () => {
inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
};
const result = convertStaleResponsesToUserMessage({
- history: approvalHistory,
+ requests: knownApproval,
pendingRequestIds: new Set(["approval-1"]),
stepInput,
});
@@ -217,7 +204,7 @@ it("converts remaining stale responses after the drop pass", () => {
},
});
const result = convertStaleResponsesToUserMessage({
- history: unrecoverableHistory,
+ requests: unknown,
pendingRequestIds,
stepInput,
});
diff --git a/packages/eve/src/harness/stale-input-responses.ts b/packages/eve/src/harness/hitl/stale-responses.ts
similarity index 91%
rename from packages/eve/src/harness/stale-input-responses.ts
rename to packages/eve/src/harness/hitl/stale-responses.ts
index c312bb51f..de22b91c2 100644
--- a/packages/eve/src/harness/stale-input-responses.ts
+++ b/packages/eve/src/harness/hitl/stale-responses.ts
@@ -1,8 +1,7 @@
-import type { ModelMessage, UserContent } from "ai";
+import type { UserContent } from "ai";
-import { extractHistoricalInputRequests } from "#harness/input-extraction.js";
import { appendUserContent, normalizeUserContent } from "#harness/messages.js";
-import { isSessionLimitContinuationRequestId } from "#harness/session-limit-continuation.js";
+import { isSessionLimitContinuationRequestId } from "#harness/hitl/budget-request.js";
import type { StepInput } from "#harness/types.js";
import type { InputRequest, InputResponse } from "#shared/input.js";
@@ -62,14 +61,15 @@ export function dropStaleSessionLimitContinuationResponses(input: {
* 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.
+ * Request details the session still knows 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[];
readonly pendingRequestIds: ReadonlySet<string>;
+ /** Requests the session still knows, by id, closed ones included. */
+ readonly requests: ReadonlyMap<string, InputRequest>;
readonly stepInput?: StepInput;
}): StaleResponseConversion {
if (input.stepInput === undefined) return { kind: "unchanged" };
@@ -99,10 +99,7 @@ export function convertStaleResponsesToUserMessage(input: {
return { kind: "unchanged", stepInput: input.stepInput };
}
- const requests = extractHistoricalInputRequests({
- history: input.history,
- requestIds: new Set(staleResponses.map((response) => response.requestId)),
- });
+ const { requests } = input;
const modelMessage = appendOptionalUserContent(
input.stepInput.message,
formatModelMessage(staleResponses, requests),
@@ -163,7 +160,7 @@ function formatModelMessage(
response: typeof responseDetails;
toolName?: string;
} = { requestId: response.requestId, response: responseDetails };
- if (request !== undefined) {
+ if (request?.kind === "tool-approval") {
resolved.prompt = request.prompt;
resolved.requestType = "approval";
// The prompt is display text; the model needs the tool's real name.
@@ -173,8 +170,7 @@ function formatModelMessage(
return resolved;
});
- // History only recovers approvals, and a response without recovered
- // metadata may still be one, so the notice always applies.
+ // A response without known metadata may still answer an approval, so the notice always applies.
return [
"The user submitted the following response to an earlier interactive prompt.",
"Treat it as new input at the current point in the conversation and decide whether it is still relevant. This does not authorize an earlier action; request approval again if that action is still needed.",
diff --git a/packages/eve/src/harness/inline-tool-authorization.ts b/packages/eve/src/harness/inline-tool-authorization.ts
index 461b44508..2fe9146d2 100644
--- a/packages/eve/src/harness/inline-tool-authorization.ts
+++ b/packages/eve/src/harness/inline-tool-authorization.ts
@@ -27,26 +27,34 @@ export function resolveInlineAuthorizationInterrupt(input: {
}):
| {
readonly challenges: AuthorizationSignal["challenges"];
+ /** The calls each sign-in stopped, by the challenge's connection name. */
+ readonly callIdsByName: ReadonlyMap<string, readonly string[]>;
readonly history: ModelMessage[];
}
| undefined {
const signals: AuthorizationSignal[] = [];
const interruptedCallIds = new Set<string>();
+ const callIdsByName = new Map<string, string[]>();
for (const toolResult of input.toolResults ?? []) {
const signal = readAuthorizationSignal(toolResult);
if (signal === undefined) continue;
signals.push(signal);
interruptedCallIds.add(toolResult.toolCallId);
+ for (const challenge of signal.challenges) {
+ const callIds = callIdsByName.get(challenge.name) ?? [];
+ callIdsByName.set(challenge.name, [...callIds, toolResult.toolCallId]);
+ }
}
if (signals.length === 0) return undefined;
return {
+ callIdsByName,
challenges: resolveActiveAuthorizationChallenges(
signals.flatMap((signal) => signal.challenges),
),
- history: projectCompletedSiblingCalls(input.messages, interruptedCallIds),
+ history: withoutCalls(input.messages, interruptedCallIds),
};
}
@@ -59,7 +67,8 @@ function readAuthorizationSignal(
return isAuthorizationSignal(toolResult.output) ? toolResult.output : undefined;
}
-function projectCompletedSiblingCalls(
+/** Drops the given calls and their results, keeping protocol-complete sibling calls. */
+export function withoutCalls(
messages: readonly ModelMessage[],
interruptedCallIds: ReadonlySet<string>,
): ModelMessage[] {
diff --git a/packages/eve/src/harness/input-extraction.ts b/packages/eve/src/harness/input-extraction.ts
index da7914b01..25dfa6d40 100644
--- a/packages/eve/src/harness/input-extraction.ts
+++ b/packages/eve/src/harness/input-extraction.ts
@@ -1,4 +1,4 @@
-import type { ContentPart, ModelMessage, ToolSet } from "ai";
+import type { ContentPart, ToolSet } from "ai";
import { z } from "#compiled/zod/index.js";
import { toolCallDisplayName } from "#execution/tools/connection-target.js";
@@ -48,7 +48,6 @@ export function extractToolApprovalInputRequests(input: {
function extractApprovalRequests(input: {
readonly content: readonly unknown[];
readonly excludedCallIds?: ReadonlySet<string>;
- readonly includedRequestIds?: ReadonlySet<string>;
}): InputRequest[] {
const requests: InputRequest[] = [];
const toolCallsById = new Map<string, ToolCallDescriptor>();
@@ -67,13 +66,6 @@ function extractApprovalRequests(input: {
}
const approval = parsed.data;
- if (
- input.includedRequestIds !== undefined &&
- !input.includedRequestIds.has(approval.approvalId)
- ) {
- continue;
- }
-
// AI SDK records automatic decisions as request/response pairs for history;
// only unresolved requests should become eve input.
if (approval.isAutomatic === true) {
@@ -107,41 +99,3 @@ function extractApprovalRequests(input: {
return requests;
}
-
-/**
- * Recovers approval request metadata for submitted input response IDs from
- * model history. The newest occurrence wins so compacted or repeated history
- * does not replace the request that is closest to the current turn.
- */
-export function extractHistoricalInputRequests(input: {
- readonly history: readonly ModelMessage[];
- readonly requestIds: ReadonlySet<string>;
-}): ReadonlyMap<string, InputRequest> {
- const requests = new Map<string, InputRequest>();
-
- for (let index = input.history.length - 1; index >= 0; index -= 1) {
- const message = input.history[index];
- if (message?.role !== "assistant" || !Array.isArray(message.content)) {
- continue;
- }
-
- const candidates = extractApprovalRequests({
- content: message.content,
- includedRequestIds: input.requestIds,
- });
-
- for (const request of candidates) {
- if (!input.requestIds.has(request.requestId) || requests.has(request.requestId)) {
- continue;
- }
-
- requests.set(request.requestId, request);
- }
-
- if (requests.size === input.requestIds.size) {
- break;
- }
- }
-
- return requests;
-}
diff --git a/packages/eve/src/harness/input-request-class.test.ts b/packages/eve/src/harness/input-request-class.test.ts
index d76b897f2..8848dc3a9 100644
--- a/packages/eve/src/harness/input-request-class.test.ts
+++ b/packages/eve/src/harness/input-request-class.test.ts
@@ -1,7 +1,7 @@
import { describe, expect, it } from "vitest";
import { isApprovalRequest } from "#harness/input-request-class.js";
-import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
+import { createSessionLimitContinuationRequest } from "#harness/hitl/budget-request.js";
describe("isApprovalRequest", () => {
const action = {
diff --git a/packages/eve/src/harness/input-request-resolution.ts b/packages/eve/src/harness/input-request-resolution.ts
index 6e90de5b6..f3ba00e24 100644
--- a/packages/eve/src/harness/input-request-resolution.ts
+++ b/packages/eve/src/harness/input-request-resolution.ts
@@ -1,4 +1,4 @@
-import type { PendingInputBatchEvent } from "#harness/pending-input-batches.js";
+import type { StepCoordinates as PendingInputBatchEvent } from "#harness/session-machine/view.js";
import type { InputRequest, InputResponse } from "#shared/input.js";
const IGNORED_INPUT_REASON = "Ignored because the user continued without responding.";
@@ -16,28 +16,6 @@ export interface ResolvedInputBatch {
}[];
}
-export function buildResolvedInputBatch(
- batch: {
- readonly event?: PendingInputBatchEvent;
- readonly requests: readonly InputRequest[];
- },
- responses: readonly InputResponse[],
-): ResolvedInputBatch | undefined {
- if (batch.event === undefined) return undefined;
- const responseMap = new Map(responses.map((response) => [response.requestId, response]));
- return {
- event: batch.event,
- inputs: batch.requests.map((request) => {
- const response = responseMap.get(request.requestId);
- return {
- outcome: resolveInputOutcome(request.kind, response),
- request,
- response,
- };
- }),
- };
-}
-
/**
* One request's terminal outcome once its batch resolves: an approval's
* decision, or whether a question received a response.
diff --git a/packages/eve/src/harness/input-requests.test.ts b/packages/eve/src/harness/input-requests.test.ts
deleted file mode 100644
index 693569807..000000000
--- a/packages/eve/src/harness/input-requests.test.ts
+++ /dev/null
@@ -1,1359 +0,0 @@
-import { jsonSchema, type ModelMessage } from "ai";
-import { describe, expect, it } from "vitest";
-
-import { ContextContainer, contextStorage } from "#context/container.js";
-import { SessionKey } from "#context/keys.js";
-import { attachInputText } from "#internal/input-text.js";
-import { once } from "#tools/approval/policies.js";
-import type { InputRequest } from "#shared/input.js";
-import type { HarnessToolDefinition } from "#harness/execute-tool.js";
-import {
- clearPendingSessionLimitPrompt,
- consumeDeferredStepInput,
- getApprovedTools,
- getPendingInputRequestIds,
- hasPendingInputBatch,
- hasStepInput,
- resolvePendingInput,
- appendPendingInputBatch,
-} from "#harness/input-requests.js";
-import { cancelApprovalInputBatches } from "#harness/hitl/approval-input-requests.js";
-import { getDeferredStepInput } from "#harness/pending-input-batches.js";
-import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
-import { createRuntimeToolCallActionFromToolCall } from "#harness/tool-call-action.js";
-import { buildToolApproval, buildToolSet } from "#harness/tools.js";
-import type { HarnessSession, HarnessToolMap } from "#harness/types.js";
-
-function createHarnessSession(): HarnessSession {
- return {
- agent: {
- modelReference: { modelId: "test", provider: "test" } as never,
- system: "",
- tools: [],
- },
- compaction: {
- recentWindowSize: 10,
- threshold: 0.8,
- },
- continuationToken: "test",
- history: [{ content: "previous", kind: "user", role: "user" }],
- sessionId: "sess-test",
- };
-}
-
-describe("hasStepInput", () => {
- it("returns false when input is undefined", () => {
- expect(hasStepInput(undefined)).toBe(false);
- });
-
- it("returns false when input has no message", () => {
- expect(hasStepInput({})).toBe(false);
- });
-
- it("returns true when input has a message", () => {
- expect(hasStepInput({ message: "hello" })).toBe(true);
- });
-});
-
-describe("createRuntimeToolCallActionFromToolCall", () => {
- it("creates a tool-call action from a typed tool call", () => {
- const result = createRuntimeToolCallActionFromToolCall({
- toolCall: {
- toolCallId: "call-123",
- toolName: "bash",
- input: { command: "ls -la" },
- type: "tool-call",
- } as never,
- });
-
- expect(result).toEqual({
- callId: "call-123",
- input: { command: "ls -la" },
- kind: "tool-call",
- toolName: "bash",
- });
- });
-
- it("defaults to empty object when input is undefined", () => {
- const result = createRuntimeToolCallActionFromToolCall({
- toolCall: {
- toolCallId: "call-456",
- toolName: "read_file",
- input: undefined,
- type: "tool-call",
- } as never,
- });
-
- expect(result.input).toEqual({});
- });
-
- it("omits undefined properties from tool call input objects", () => {
- const result = createRuntimeToolCallActionFromToolCall({
- toolCall: {
- toolCallId: "call-789",
- toolName: "read_file",
- input: {
- path: "/workspace/foo.txt",
- startLine: undefined,
- },
- type: "tool-call",
- } as never,
- });
-
- expect(result.input).toEqual({
- path: "/workspace/foo.txt",
- });
- });
-
- it("includes the tool name when tool call input is not a JSON object", () => {
- expect(() =>
- createRuntimeToolCallActionFromToolCall({
- toolCall: {
- toolCallId: "call-123",
- toolName: "bash",
- input: [],
- type: "tool-call",
- } as never,
- }),
- ).toThrow(
- 'Failed to parse tool-call arguments for "bash" (call-123): Expected a JSON-serializable object.',
- );
- });
-});
-
-describe("resolvePendingInput", () => {
- it("defers a follow-up message until after tool approvals are resolved", () => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "rm -rf /tmp/demo" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { command: "rm -rf /tmp/demo" },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- // Deliver an approval response AND a message simultaneously.
- const result = resolvePendingInput({
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "cancel" }],
- message: "Ignore that and say hi instead.",
- },
- session,
- });
-
- // The approval should be resolved immediately.
- expect(result.outcome).toBe("resolved");
-
- // The follow-up message should be deferred.
- expect(result.deferredMessage).toBe(true);
- expect(getDeferredStepInput(result.session)).toBeDefined();
-
- const deferred = consumeDeferredStepInput({
- session: result.session,
- });
-
- expect(deferred.input).toEqual({
- message: "Ignore that and say hi instead.",
- });
- expect(getDeferredStepInput(deferred.session)).toBeUndefined();
- });
-
- it("includes a new message immediately after a cancelled approval turn", () => {
- const pending = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "rm -rf /tmp/demo" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { command: "rm -rf /tmp/demo" },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
- const session = cancelApprovalInputBatches(pending);
-
- const result = resolvePendingInput({
- session,
- stepInput: { message: "Answer this in the first step." },
- });
-
- expect(result.outcome).toBe("continue");
- expect(result.deferredMessage).toBeUndefined();
- expect(getDeferredStepInput(result.session)).toBeUndefined();
- });
-
- it("still defers a new message after an approved response", () => {
- const session: HarnessSession = {
- ...createHarnessSession(),
- history: [
- ...createHarnessSession().history,
- {
- content: [
- {
- approvalId: "approval-1",
- approved: true,
- type: "tool-approval-response",
- },
- ],
- role: "tool",
- },
- ],
- };
-
- const result = resolvePendingInput({ session, stepInput: { message: "Wait for the tool." } });
-
- expect(result.outcome).toBe("resolved");
- expect(result.deferredMessage).toBe(true);
- expect(getDeferredStepInput(result.session)).toBeDefined();
- });
-
- it("defers channel context until after tool approvals are resolved", () => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { command: "pwd" },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- const context = "<linear_context>issue metadata</linear_context>";
- const result = resolvePendingInput({
- stepInput: {
- context: [context],
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
- expect(result.messages.at(-1)?.role).toBe("tool");
- expect(getDeferredStepInput(result.session)).toBeDefined();
-
- const deferred = consumeDeferredStepInput({ session: result.session });
- expect(deferred.input).toEqual({ context: [context] });
- expect(getDeferredStepInput(deferred.session)).toBeUndefined();
- });
-
- it.each([
- ["a plain message", { message: "approve" }],
- [
- "typed text inside a channel envelope",
- attachInputText({ message: "<slack_message>\n<content>\napprove\n</content>" }, "approve"),
- ],
- ])("resolves approval when follow-up text matches an option: %s", (_, stepInput) => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { command: "pwd" },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({ stepInput, session });
-
- expect(result.outcome).toBe("resolved");
- expect(result.deferredMessage).toBeUndefined();
- expect(result.consumedMessage).toBe(true);
- expect(result.messages.at(-1)).toEqual({
- content: [
- {
- approvalId: "approval-1",
- approved: true,
- reason: undefined,
- type: "tool-approval-response",
- },
- ],
- role: "tool",
- });
- expect(getApprovedTools(result.session).has("bash")).toBe(true);
- expect(getDeferredStepInput(result.session)).toBeUndefined();
- });
-
- it("records compound approval key when resolveApprovalKey is provided", () => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { teamId: "team_abc", limit: 10 },
- kind: "tool-call",
- toolName: "vercel__list_projects",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: vercel__list_projects",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { teamId: "team_abc", limit: 10 },
- toolCallId: "approval-call",
- toolName: "vercel__list_projects",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- resolveApprovalKey: (request) => {
- const team = request.action.input?.teamId;
- return typeof team === "string" ? `${request.action.toolName}:${team}` : undefined;
- },
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
- const approved = getApprovedTools(result.session);
- expect(approved.has("vercel__list_projects:team_abc")).toBe(true);
- expect(approved.has("vercel__list_projects")).toBe(false);
- });
-
- it("emits a matching execution-denied tool-result when the user explicitly denies an approval", () => {
- /*
- * AI SDK's `streamText` synthesizes an `execution-denied`
- * tool-result for the current turn only — on subsequent turns the
- * persisted `tool-approval-response` gets stripped during provider
- * prompt conversion, leaving the prior `tool_use` block
- * unmatched. The harness must emit the matching tool-result
- * itself so persisted history is replay-safe.
- */
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { command: "pwd" },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "cancel" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
- expect(result.messages.at(-1)).toEqual({
- content: [
- {
- approvalId: "approval-1",
- approved: false,
- reason: "Tool execution was denied.",
- type: "tool-approval-response",
- },
- {
- output: { type: "execution-denied", reason: "Tool execution was denied." },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-result",
- },
- ],
- role: "tool",
- });
- });
-
- it("returns a rejected action for an ACP denial", () => {
- const session = appendPendingInputBatch({
- event: { sequence: 5, stepIndex: 1, turnId: "turn_0" },
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "deny" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
- expect(result.rejectedActions).toEqual([
- {
- event: { sequence: 5, stepIndex: 1, turnId: "turn_0" },
- results: [
- {
- callId: "approval-call",
- isError: true,
- kind: "tool-result",
- output: {
- approval: {
- requestId: "approval-1",
- status: "denied",
- },
- code: "TOOL_EXECUTION_DENIED",
- message: "Tool execution was denied.",
- tool: {
- result: "not_run",
- },
- },
- toolName: "bash",
- },
- ],
- },
- ]);
- expect(result.resolvedInputs).toMatchObject([
- {
- event: { sequence: 5, stepIndex: 1, turnId: "turn_0" },
- inputs: [
- {
- outcome: "denied",
- request: { requestId: "approval-1" },
- response: { optionId: "deny", requestId: "approval-1" },
- },
- ],
- },
- ]);
- });
-
- it("does not return a rejected action when an approval is granted", () => {
- const session = appendPendingInputBatch({
- event: { sequence: 5, stepIndex: 1, turnId: "turn_0" },
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
- expect(result.rejectedActions).toBeUndefined();
- expect(result.resolvedInputs).toMatchObject([
- {
- event: { sequence: 5, stepIndex: 1, turnId: "turn_0" },
- inputs: [
- {
- outcome: "approved",
- request: { requestId: "approval-1" },
- response: { optionId: "approve", requestId: "approval-1" },
- },
- ],
- },
- ]);
- });
-
- it("does not retain approval when a deferred response is superseded", () => {
- const approval = (requestId: string, callId: string): InputRequest => ({
- action: { callId, input: { command: "pwd" }, kind: "tool-call", toolName: "bash" },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId,
- });
- const session = appendPendingInputBatch({
- event: { sequence: 5, stepIndex: 1, turnId: "turn_0" },
- requests: [approval("approval-1", "call-1"), approval("approval-2", "call-2")],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const partial = resolvePendingInput({
- session,
- stepInput: { inputResponses: [{ requestId: "approval-1", optionId: "approve" }] },
- });
- const deferred = consumeDeferredStepInput({
- input: {
- inputResponses: [
- { requestId: "approval-1", optionId: "cancel" },
- { requestId: "approval-2", optionId: "approve" },
- ],
- },
- session: partial.session,
- });
- const result = resolvePendingInput({
- resolveApprovalKey: (request) => request.requestId,
- session: deferred.session,
- stepInput: deferred.input,
- });
-
- expect(getApprovedTools(result.session)).toEqual(new Set(["approval-2"]));
- expect(result.rejectedActions?.[0]?.results).toEqual([
- expect.objectContaining({
- callId: "call-1",
- }),
- ]);
- });
-
- it("steers past a pending approval when a follow-up message arrives instead of an answer", () => {
- const session = appendPendingInputBatch({
- event: { sequence: 7, stepIndex: 2, turnId: "turn_1" },
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- stepInput: { message: "Never mind, do something else." },
- session,
- });
-
- // The message moves the turn on: the call never runs, and the model reads
- // the message in the same step.
- expect(result.outcome).toBe("resolved");
- expect(result.resolvedInputs).toMatchObject([
- { inputs: [{ outcome: "ignored", request: { requestId: "approval-1" } }] },
- ]);
- expect(result.rejectedActions?.[0]?.results).toMatchObject([{ callId: "approval-call" }]);
- expect(getDeferredStepInput(result.session)).toBeUndefined();
- expect(getPendingInputRequestIds(result.session.state)).toEqual(new Set());
- });
-
- it("preserves context-only input while a pending batch stays open", () => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- kind: "tool-approval",
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- },
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- session,
- stepInput: { context: ["channel context"] },
- });
- const deferred = consumeDeferredStepInput({ session: result.session });
-
- expect(result.outcome).toBe("unresolved");
- expect(deferred.input).toEqual({ context: ["channel context"] });
- });
-
- it("falls back to tool name when no approvalKey is provided", () => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "rm -rf /tmp" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: { command: "rm -rf /tmp" },
- toolCallId: "approval-call",
- toolName: "bash",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
- const approved = getApprovedTools(result.session);
- expect(approved.has("bash")).toBe(true);
- });
-
- it("approval survives the authorization park so an auth+approval tool is not approved twice", () => {
- // A tool requiring both approval and auth is approved first, then its
- // execute parks for sign-in. On resume the step re-runs and the toolset
- // is rebuilt from the persisted approvedTools. The recorded approval must
- // survive on session.state across the park, so approval returns
- // "not-applicable" and the user is never asked to approve a second time.
- // See research/per-tool-auth-known-issues.md, issue 3.
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: {},
- kind: "tool-call",
- toolName: "linear_whoami",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: linear_whoami",
- requestId: "approval-1",
- } satisfies InputRequest,
- ],
- responseMessages: [
- {
- content: [
- {
- input: {},
- toolCallId: "approval-call",
- toolName: "linear_whoami",
- type: "tool-call",
- },
- {
- approvalId: "approval-1",
- toolCallId: "approval-call",
- type: "tool-approval-request",
- },
- ],
- role: "assistant",
- } satisfies ModelMessage,
- ],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({
- stepInput: {
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- },
- session,
- });
-
- expect(result.outcome).toBe("resolved");
-
- // The resume-after-sign-in step rebuilds the toolset from the persisted
- // approvals. once() must not re-request approval for the now-approved tool.
- const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([
- [
- "linear_whoami",
- {
- description: "Resolve the caller's Linear identity.",
- execute: async () => ({ ok: true }),
- inputSchema: jsonSchema({ type: "object" }),
- name: "linear_whoami",
- approval: once(),
- },
- ],
- ]);
-
- const rebuilt = buildToolSet({
- approvedTools: getApprovedTools(result.session),
- tools,
- });
- const approval = buildToolApproval(rebuilt);
- if (typeof approval !== "function") throw new TypeError("Expected generic approval function.");
-
- const ctx = new ContextContainer();
- ctx.set(SessionKey, {
- auth: { current: null, initiator: null },
- sessionId: "sess-test",
- turn: { id: "turn-test", sequence: 0 },
- });
-
- return expect(
- contextStorage.run(ctx, () =>
- approval({
- messages: [],
- runtimeContext: {},
- toolCall: {
- input: {},
- toolCallId: "call-1",
- toolName: "linear_whoami",
- } as never,
- tools: rebuilt,
- toolsContext: {} as never,
- }),
- ),
- ).resolves.toBe("not-applicable");
- });
-});
-
-describe("pending input batch collection", () => {
- function approvalRequest(requestId: string, callId: string): InputRequest {
- return {
- action: { callId, input: { command: "pwd" }, kind: "tool-call", toolName: "bash" },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId,
- };
- }
-
- function batchOutput(callId: string, toolName: string): ModelMessage {
- return {
- content: [{ input: {}, toolCallId: callId, toolName, type: "tool-call" }],
- role: "assistant",
- };
- }
-
- it("reads a legacy singleton batch and rewrites it as a list", () => {
- const legacySession: HarnessSession = {
- ...createHarnessSession(),
- state: {
- "eve.runtime.pendingInputBatch": {
- requests: [approvalRequest("approval-1", "call-1")],
- responseMessages: [batchOutput("call-1", "bash")],
- },
- },
- };
-
- expect(getPendingInputRequestIds(legacySession.state)).toEqual(new Set(["approval-1"]));
-
- const appended = appendPendingInputBatch({
- requests: [approvalRequest("approval-2", "call-2")],
- responseMessages: [batchOutput("call-2", "bash")],
- session: legacySession,
- });
- expect(appended.state?.["eve.runtime.pendingInputBatch"]).toBeUndefined();
- expect(getPendingInputRequestIds(appended.state)).toEqual(
- new Set(["approval-1", "approval-2"]),
- );
-
- const result = resolvePendingInput({
- session: legacySession,
- stepInput: { inputResponses: [{ requestId: "approval-1", optionId: "approve" }] },
- });
- expect(result.outcome).toBe("resolved");
- expect(result.session.state?.["eve.runtime.pendingInputBatch"]).toBeUndefined();
- expect(hasPendingInputBatch(result.session.state)).toBe(false);
- });
-
- it("resolves only the first approval-bearing batch and defers later responses", () => {
- let session = appendPendingInputBatch({
- requests: [approvalRequest("approval-1", "call-1")],
- responseMessages: [batchOutput("call-1", "bash")],
- session: createHarnessSession(),
- });
- session = appendPendingInputBatch({
- requests: [approvalRequest("approval-2", "call-2")],
- responseMessages: [batchOutput("call-2", "bash")],
- session,
- });
-
- const first = resolvePendingInput({
- session,
- stepInput: {
- inputResponses: [
- { requestId: "approval-1", optionId: "approve" },
- { requestId: "approval-2", optionId: "approve" },
- ],
- },
- });
-
- expect(first.outcome).toBe("resolved");
- expect(first.messages).toEqual([
- { content: "previous", kind: "user", role: "user" },
- batchOutput("call-1", "bash"),
- {
- content: [
- {
- approvalId: "approval-1",
- approved: true,
- reason: undefined,
- type: "tool-approval-response",
- },
- ],
- role: "tool",
- },
- ]);
- expect(getPendingInputRequestIds(first.session.state)).toEqual(new Set(["approval-2"]));
-
- const deferred = consumeDeferredStepInput({ session: first.session });
- expect(deferred.input).toEqual({
- inputResponses: [{ requestId: "approval-2", optionId: "approve" }],
- });
-
- const second = resolvePendingInput({ session: deferred.session, stepInput: deferred.input });
- expect(second.outcome).toBe("resolved");
- expect(second.messages.at(-1)).toMatchObject({
- content: [{ approvalId: "approval-2", approved: true }],
- role: "tool",
- });
- expect(hasPendingInputBatch(second.session.state)).toBe(false);
- });
-
- it("does not apply an approval grant to already-pending calls with the same key", () => {
- let session = createHarnessSession();
- for (const index of [1, 2, 3]) {
- session = appendPendingInputBatch({
- requests: [approvalRequest(`approval-${index}`, `call-${index}`)],
- responseMessages: [batchOutput(`call-${index}`, "bash")],
- session,
- });
- }
-
- const first = resolvePendingInput({
- session,
- stepInput: { inputResponses: [{ requestId: "approval-1", optionId: "approve" }] },
- });
-
- expect(first.outcome).toBe("resolved");
- expect(getApprovedTools(first.session)).toEqual(new Set());
- expect(getPendingInputRequestIds(first.session.state)).toEqual(
- new Set(["approval-2", "approval-3"]),
- );
-
- const second = resolvePendingInput({
- session: first.session,
- stepInput: { inputResponses: [{ requestId: "approval-2", optionId: "cancel" }] },
- });
- expect(getApprovedTools(second.session)).toEqual(new Set());
- expect(getPendingInputRequestIds(second.session.state)).toEqual(new Set(["approval-3"]));
-
- const third = resolvePendingInput({
- session: second.session,
- stepInput: { inputResponses: [{ requestId: "approval-3", optionId: "cancel" }] },
- });
- expect(getApprovedTools(third.session)).toEqual(new Set(["bash"]));
- expect(hasPendingInputBatch(third.session.state)).toBe(false);
- });
-
- it("keeps approval grants independent across compound keys", () => {
- const scopedApproval = (
- requestId: string,
- callId: string,
- workspace: string,
- ): InputRequest => ({
- ...approvalRequest(requestId, callId),
- action: {
- callId,
- input: { workspace },
- kind: "tool-call",
- toolName: "notion__notion-update-page",
- },
- });
- const resolveApprovalKey = (request: InputRequest) =>
- `${request.action.toolName}:${String(request.action.input.workspace)}`;
- let session = appendPendingInputBatch({
- requests: [scopedApproval("approval-1", "call-1", "workspace-a")],
- responseMessages: [batchOutput("call-1", "notion__notion-update-page")],
- session: createHarnessSession(),
- });
- session = appendPendingInputBatch({
- requests: [scopedApproval("approval-2", "call-2", "workspace-b")],
- responseMessages: [batchOutput("call-2", "notion__notion-update-page")],
- session,
- });
- session = appendPendingInputBatch({
- requests: [scopedApproval("approval-3", "call-3", "workspace-a")],
- responseMessages: [batchOutput("call-3", "notion__notion-update-page")],
- session,
- });
-
- const first = resolvePendingInput({
- resolveApprovalKey,
- session,
- stepInput: { inputResponses: [{ requestId: "approval-1", optionId: "approve" }] },
- });
-
- // approval-3 shares the workspace-a key, so the grant stays masked; the
- // bare tool name would not mask it, which is what makes the resolver matter.
- expect(getApprovedTools(first.session, resolveApprovalKey)).toEqual(new Set());
- expect(getPendingInputRequestIds(first.session.state)).toEqual(
- new Set(["approval-2", "approval-3"]),
- );
-
- const second = resolvePendingInput({
- resolveApprovalKey,
- session: first.session,
- stepInput: { inputResponses: [{ requestId: "approval-3", optionId: "cancel" }] },
- });
-
- expect(getApprovedTools(second.session, resolveApprovalKey)).toEqual(
- new Set(["notion__notion-update-page:workspace-a"]),
- );
- expect(getPendingInputRequestIds(second.session.state)).toEqual(new Set(["approval-2"]));
- });
-
- it("holds on a pending approval when the step brings no answer or message", () => {
- const session = appendPendingInputBatch({
- event: { sequence: 5, stepIndex: 1, turnId: "turn_1" },
- requests: [approvalRequest("approval-1", "call-1")],
- responseMessages: [batchOutput("call-1", "bash")],
- session: createHarnessSession(),
- });
-
- const result = resolvePendingInput({ session });
-
- expect(result.outcome).toBe("unresolved");
- expect(getPendingInputRequestIds(result.session.state)).toEqual(new Set(["approval-1"]));
- });
-});
-
-describe("resolvePendingInput with a session-limit continuation batch", () => {
- function approvalRequest(): InputRequest {
- return {
- action: { callId: "call-1", input: { command: "pwd" }, kind: "tool-call", toolName: "bash" },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- };
- }
-
- function createLimitBatchSession(): HarnessSession {
- return appendPendingInputBatch({
- requests: [
- createSessionLimitContinuationRequest({
- sessionId: "sess-test",
- turnSequence: 0,
- violation: { kind: "input", limit: 12, usedTokens: 12 },
- }),
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
- }
-
- it("rejects a session-limit batch containing a model-anchored request", () => {
- const session = appendPendingInputBatch({
- requests: [
- createSessionLimitContinuationRequest({
- sessionId: "sess-test",
- turnSequence: 0,
- violation: { kind: "input", limit: 12, usedTokens: 12 },
- }),
- approvalRequest(),
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- expect(() => resolvePendingInput({ session })).toThrow(
- "Session-limit pending input batches must contain only session-limit requests.",
- );
- });
-
- it("resolves a continue answer without appending tool messages", () => {
- const result = resolvePendingInput({
- session: createLimitBatchSession(),
- stepInput: {
- inputResponses: [{ optionId: "continue", requestId: "sess-test:0:limit:input:12" }],
- },
- });
-
- expect(result.outcome).toBe("resolved");
- expect(result.limitContinuation).toEqual({ granted: true });
- // The prompt is harness-authored — no tool call exists in model history,
- // so resolution must not append a tool message.
- expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
- });
-
- it("resolves a stop answer as not granted", () => {
- const result = resolvePendingInput({
- session: createLimitBatchSession(),
- stepInput: {
- inputResponses: [{ optionId: "stop", requestId: "sess-test:0:limit:input:12" }],
- },
- });
-
- expect(result.outcome).toBe("resolved");
- expect(result.limitContinuation).toEqual({ granted: false });
- expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
- });
-
- it("keeps the prompt pending and queues a plain follow-up message", () => {
- const result = resolvePendingInput({
- session: createLimitBatchSession(),
- stepInput: { message: "also do this other thing" },
- });
-
- expect(result.outcome).toBe("unresolved");
- expect(result.limitContinuation).toBeUndefined();
- expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
- expect(getDeferredStepInput(result.session)).toBeDefined();
-
- const deferred = consumeDeferredStepInput({ session: result.session });
- expect(deferred.input).toEqual({ message: "also do this other thing" });
- });
-
- it("matches text against the limit batch while an approval batch is also open", () => {
- let session = appendPendingInputBatch({
- requests: [approvalRequest()],
- responseMessages: [],
- session: createHarnessSession(),
- });
- session = appendPendingInputBatch({
- requests: [
- createSessionLimitContinuationRequest({
- sessionId: "sess-test",
- turnSequence: 0,
- violation: { kind: "input", limit: 12, usedTokens: 12 },
- }),
- ],
- responseMessages: [],
- session,
- });
-
- const result = resolvePendingInput({ session, stepInput: { message: "continue" } });
-
- expect(result.outcome).toBe("resolved");
- expect(result.limitContinuation).toEqual({ granted: true });
- expect(result.consumedMessage).toBe(true);
- expect(getPendingInputRequestIds(result.session.state)).toEqual(new Set(["approval-1"]));
- expect(getDeferredStepInput(result.session)).toBeUndefined();
- });
-
- it("defers an approval response while the limit batch remains open", () => {
- let session = appendPendingInputBatch({
- requests: [approvalRequest()],
- responseMessages: [],
- session: createHarnessSession(),
- });
- session = appendPendingInputBatch({
- requests: [
- createSessionLimitContinuationRequest({
- sessionId: "sess-test",
- turnSequence: 0,
- violation: { kind: "input", limit: 12, usedTokens: 12 },
- }),
- ],
- responseMessages: [],
- session,
- });
-
- const result = resolvePendingInput({
- session,
- stepInput: { inputResponses: [{ requestId: "approval-1", optionId: "approve" }] },
- });
-
- expect(result.outcome).toBe("unresolved");
- expect(getPendingInputRequestIds(result.session.state)).toEqual(
- new Set(["approval-1", "sess-test:0:limit:input:12"]),
- );
- const deferred = consumeDeferredStepInput({ session: result.session });
- expect(deferred.input).toEqual({
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- });
- });
-});
-
-describe("clearPendingSessionLimitPrompt", () => {
- it("drops a pending batch made only of session-limit continuation prompts", () => {
- const session = appendPendingInputBatch({
- requests: [
- createSessionLimitContinuationRequest({
- sessionId: "sess-test",
- turnSequence: 0,
- violation: { kind: "input", limit: 12, usedTokens: 12 },
- }),
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const cleared = clearPendingSessionLimitPrompt(session);
- const result = resolvePendingInput({ session: cleared, stepInput: { message: "try again" } });
-
- // No stale batch left: the follow-up message flows to the step (where
- // the pre-model gate re-raises the prompt) instead of deferring forever.
- expect(result.outcome).toBe("continue");
- expect(getDeferredStepInput(cleared)).toBeUndefined();
- });
-
- it("keeps model-anchored batches (tool approvals) intact", () => {
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "approval-call",
- input: { command: "rm -rf /tmp/demo" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
- ],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- },
- ],
- responseMessages: [],
- session: createHarnessSession(),
- });
-
- const kept = clearPendingSessionLimitPrompt(session);
-
- expect(getPendingInputRequestIds(kept.state)).toEqual(new Set(["approval-1"]));
- });
-
- it("is a no-op without a pending batch", () => {
- const session = createHarnessSession();
- expect(clearPendingSessionLimitPrompt(session)).toBe(session);
- });
-});
diff --git a/packages/eve/src/harness/input-requests.ts b/packages/eve/src/harness/input-requests.ts
deleted file mode 100644
index 785dcfedb..000000000
--- a/packages/eve/src/harness/input-requests.ts
+++ /dev/null
@@ -1,245 +0,0 @@
-import type { ModelMessage } from "ai";
-
-import type { InputRequest, InputResponse } from "#shared/input.js";
-import { resolveTextToResponses } from "#channel/resolve-text.js";
-import { hasTailApprovalResponse } from "#harness/current-messages.js";
-import {
- getApprovedTools,
- findAnsweredApprovalBatches,
- resolveApprovalInputBatches,
-} from "#harness/hitl/approval-input-requests.js";
-import type { RejectedActionBatch } from "#harness/hitl/approval-input-requests.js";
-import { isApprovalRequest } from "#harness/input-request-class.js";
-import type { PendingInputBatch } from "#harness/pending-input-batches.js";
-import {
- getDeferredStepInput,
- getPendingInputBatches,
- queueDeferredStepInput,
-} from "#harness/pending-input-batches.js";
-import { compactStepInput, finishResolvedInput } from "#harness/hitl/pending-input-resolution.js";
-import type {
- ResolvePendingInputResult,
- ResolvedStepInput,
-} from "#harness/hitl/pending-input-resolution.js";
-import {
- clearPendingSessionLimitPrompt,
- isSessionLimitInputBatch,
- resolveSessionLimitInput,
-} from "#harness/hitl/session-limit-input-requests.js";
-import type { HarnessSession, StepInput } from "#harness/types.js";
-import { readClientContext } from "#internal/client-context.js";
-import { readAnswerText } from "#internal/input-text.js";
-
-export { getApprovedTools, clearPendingSessionLimitPrompt };
-export type { RejectedActionBatch };
-export type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
-export {
- appendPendingInputBatch,
- consumeDeferredStepInput,
- getPendingInputRequestIds,
- hasPendingInputBatch,
-} from "#harness/pending-input-batches.js";
-
-/** Returns true when the step input carries user-facing turn input. */
-export function hasStepInput(input?: StepInput): boolean {
- if (input === undefined) return false;
- return input.message !== undefined || (input.inputResponses?.length ?? 0) > 0;
-}
-
-/** Stored partial answers are not runnable work until they can resolve a batch. */
-export function hasRunnableDeferredStepInput(session: HarnessSession): boolean {
- const deferred = getDeferredStepInput(session);
- if (deferred === undefined) return false;
- if (
- deferred.message !== undefined ||
- (deferred.context?.length ?? 0) > 0 ||
- readClientContext(deferred) !== undefined ||
- deferred.outputSchema !== undefined ||
- (deferred.runtimeActionResults?.length ?? 0) > 0
- )
- return true;
-
- const responses = [
- ...(deferred.inputResponses ?? []),
- ...(deferred.attributedInputResponses ?? []).map(({ response }) => response),
- ];
- if (responses.length === 0) return false;
- const batches = getPendingInputBatches(session.state);
- const route = routePendingInput(batches);
- switch (route.kind) {
- case "session-limit":
- return route.batch.requests.every((request) =>
- responses.some((response) => response.requestId === request.requestId),
- );
- case "approvals":
- return findAnsweredApprovalBatches(batches, responses).length > 0;
- }
-}
-
-/** Selects the complete approval batch that pending-input resolution will resume. */
-export function selectApprovalReplayBatch(
- session: HarnessSession,
- stepInput?: StepInput,
-): PendingInputBatch | undefined {
- const batches = getPendingInputBatches(session.state);
- if (batches.some(isSessionLimitInputBatch)) return;
- const resolved =
- batches.length === 1 ? resolveTextMessageInput(batches[0]!, stepInput) : stepInput;
- const responses = canonicalizeInputResponses(resolved?.inputResponses ?? []);
- const batch = findAnsweredApprovalBatches(batches, responses)[0];
- return batch?.requests.some(
- (request) =>
- isApprovalRequest(request) &&
- responses.some(
- (response) => response.requestId === request.requestId && response.optionId === "approve",
- ),
- )
- ? batch
- : undefined;
-}
-
-/**
- * Resolves pending input at the start of a harness step.
- *
- * Ordered batches remain independently answerable. Session-limit prompts own
- * resolution while open; approval batches preserve AI SDK's tail-message
- * requirement.
- */
-export function resolvePendingInput(input: {
- readonly history?: readonly ModelMessage[];
- readonly resolveApprovalKey?: (request: InputRequest) => string | undefined;
- readonly session: HarnessSession;
- readonly stepInput?: StepInput;
-}): 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) &&
- (batches.length > 0 || hasApprovedTailResponse(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 deferTurnInput = hasTailApprovalResponse(baseHistory);
- const textResolutionBatch =
- route.kind === "session-limit" ? route.batch : batches.length === 1 ? batches[0] : undefined;
- const resolvedStepInput =
- textResolutionBatch === undefined
- ? input.stepInput
- : resolveTextMessageInput(textResolutionBatch, input.stepInput);
- const responses = canonicalizeInputResponses(resolvedStepInput?.inputResponses ?? []);
-
- if (responses.length === 0 && resolvedStepInput?.message === undefined) {
- const deferredInput = compactStepInput(resolvedStepInput);
- const session =
- deferredInput.context !== undefined ||
- readClientContext(deferredInput) !== undefined ||
- deferredInput.outputSchema !== undefined
- ? queueDeferredStepInput(input.session, deferredInput)
- : input.session;
- return { outcome: "unresolved", messages: baseHistory, session };
- }
-
- const resolverInput = {
- baseHistory,
- batches,
- deferTurnInput,
- resolvedStepInput,
- responses,
- session: input.session,
- };
- switch (route.kind) {
- case "session-limit":
- return resolveSessionLimitInput({ ...resolverInput, pendingBatch: route.batch });
- case "approvals":
- return resolveApprovalInputBatches({
- ...resolverInput,
- resolveApprovalKey: input.resolveApprovalKey,
- });
- }
-}
-
-/**
- * Answers an open budget prompt from new input's text before that input joins
- * a message deferred behind the prompt. Joined, the text no longer matches an
- * option, so the answer would queue behind the message it should release.
- */
-export function answerSessionLimitFromText(
- session: HarnessSession,
- stepInput: StepInput | undefined,
-): StepInput | undefined {
- if (stepInput === undefined || getDeferredStepInput(session) === undefined) return stepInput;
- const limitBatch = getPendingInputBatches(session.state).find(isSessionLimitInputBatch);
- return limitBatch === undefined ? stepInput : resolveTextMessageInput(limitBatch, stepInput);
-}
-
-type PendingInputRoute =
- | { readonly batch: PendingInputBatch; readonly kind: "session-limit" }
- | { readonly kind: "approvals" };
-
-function routePendingInput(batches: readonly PendingInputBatch[]): PendingInputRoute {
- const limitBatch = batches.find((batch) => isSessionLimitInputBatch(batch));
- if (limitBatch !== undefined) return { batch: limitBatch, kind: "session-limit" };
-
- for (const batch of batches) {
- for (const request of batch.requests) {
- if (!isApprovalRequest(request)) {
- throw new TypeError(`Unhandled pending input request kind: ${request.kind}`);
- }
- }
- }
- return { kind: "approvals" };
-}
-
-function hasApprovedTailResponse(messages: readonly ModelMessage[]): boolean {
- const tail = messages.at(-1);
- return (
- tail?.role === "tool" &&
- tail.content.some((part) => part.type === "tool-approval-response" && part.approved)
- );
-}
-
-function canonicalizeInputResponses(responses: readonly InputResponse[]): readonly InputResponse[] {
- const byRequestId = new Map<string, InputResponse>();
- for (const response of responses) byRequestId.set(response.requestId, response);
- return [...byRequestId.values()];
-}
-
-function resolveTextMessageInput(
- pendingBatch: PendingInputBatch,
- stepInput: StepInput | undefined,
-): ResolvedStepInput | undefined {
- const text = readAnswerText(stepInput);
- if (stepInput === undefined || text === undefined) return stepInput;
-
- const batchRequestIds = new Set(pendingBatch.requests.map((request) => request.requestId));
- if (stepInput.inputResponses?.some((response) => batchRequestIds.has(response.requestId))) {
- return stepInput;
- }
-
- const responseAuthRequired = new Set(pendingBatch.responseAuthRequiredRequestIds ?? []);
- const textRequests = pendingBatch.requests.filter(
- (request) => !responseAuthRequired.has(request.requestId),
- );
- const responses = resolveTextToResponses(text, textRequests);
- if (responses.length === 0) return stepInput;
-
- return compactStepInput({
- ...stepInput,
- inputResponses: [...(stepInput.inputResponses ?? []), ...responses],
- messageConsumed: true,
- message: undefined,
- });
-}
diff --git a/packages/eve/src/harness/issue-3494-adversarial.integration.test.ts b/packages/eve/src/harness/issue-3494-adversarial.integration.test.ts
index c7379e0ef..a4d1be99e 100644
--- a/packages/eve/src/harness/issue-3494-adversarial.integration.test.ts
+++ b/packages/eve/src/harness/issue-3494-adversarial.integration.test.ts
@@ -5,14 +5,14 @@ import type { ApprovalResponsePolicy } from "#approval/definition.js";
import {
getApprovalAuditState,
markApprovalCandidateAuthorizationRequired,
-} from "#harness/approval-candidates.js";
+} from "#harness/hitl/candidates.js";
import { setPendingAuthorization } from "#harness/authorization.js";
import { z } from "zod";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import { getHarnessEmissionState } from "#harness/emission.js";
-import { getPendingCoordinationBatch } from "#harness/coordination.js";
-import { getPendingInputBatches } from "#harness/pending-input-batches.js";
+import { createProjectionRecorder } from "#internal/testing/session-projection-recorder.js";
+import { runtimeWait, storedProjection, suspendedSteps } from "#harness/session-machine/view.js";
+import { openInputs } from "#protocol/session-projection.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";
@@ -21,7 +21,7 @@ import { always } from "#tools/approval/policies.js";
import { bindDynamicConnections } from "#execution/dynamic-connections.js";
import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
import { ConnectionRegistryImpl } from "#runtime/connections/registry.js";
-import { createTurnStartedEvent } from "#protocol/message.js";
+import { createAuthorizationRequiredEvent, createTurnStartedEvent } from "#protocol/message.js";
import { captureLogRecords } from "#internal/testing/log-records.js";
// The harness runs outside a workflow body here, where run attributes cannot
@@ -146,6 +146,7 @@ function fixture(
workflowId: "diagnostic-workflow",
});
const restoredTurns: string[] = [];
+ const recorder = createProjectionRecorder();
const harness = createToolLoopHarness({
prepareApprovalTurn: async (event) => {
const ctx = new ContextContainer();
@@ -175,13 +176,14 @@ function fixture(
resolveModel: async () => model,
handleEvent: async (event) => {
events.push(event);
+ recorder.record(event);
},
});
async function step(input?: StepInput): Promise<StepResult> {
const before = events.length;
const beforeCalls = modelCalls;
- const emission = getHarnessEmissionState(session.state);
- const ctx = new ContextContainer();
+ const emission = recorder.position;
+ const ctx = recorder.enter(new ContextContainer());
ctx.set(SessionKey, {
sessionId: session.sessionId,
auth: { current: null, initiator: null },
@@ -196,9 +198,9 @@ function fixture(
next: typeof result.next === "function" ? "continue" : result.next,
settledTurn: result.settledTurn,
historyLastRole: session.history.at(-1)?.role,
- emission: getHarnessEmissionState(session.state),
- deferred: session.state?.["eve.runtime.deferredStepInput"],
- pending: getPendingInputBatches(session.state).map((batch) => ({
+ emission: recorder.position,
+ deferred: suspendedSteps(session.state) && session.state?.["eve.harness.turnState"],
+ pending: suspendedSteps(session.state).map((batch) => ({
owner: batch.event,
requests: batch.requests.map((r) => ({
id: r.requestId,
@@ -221,6 +223,7 @@ function fixture(
reports.push(report);
return {
script,
+ prompts,
restoredTurns,
executions,
events,
@@ -229,14 +232,21 @@ function fixture(
get session() {
return session;
},
+ record(event: UnstampedMessageStreamEvent) {
+ events.push(event);
+ recorder.record(event);
+ },
updateSession(update: (session: HarnessSession) => HarnessSession) {
session = update(session);
},
- pending: () => getPendingInputBatches(session.state).flatMap((b) => b.requests),
+ // What the session asks and still awaits: approvals and the budget prompt.
+ pending: () =>
+ openInputs(storedProjection(session.state))
+ .filter((input) => input.callId === undefined && input.taskId === undefined)
+ .map((input) => input.request),
async gate(...names: string[]) {
script.push(calls(...names));
- const parked = await drive({ message: `Prepare ${names.join(" and ")}.` });
- expect(parked.held).toEqual({ kind: "request" });
+ await drive({ message: `Prepare ${names.join(" and ")}.` });
expect(this.pending().filter((r) => r.kind === "tool-approval")).toHaveLength(names.length);
expect(executions).toHaveLength(0);
},
@@ -246,8 +256,8 @@ function fixture(
return { inputResponses: [{ requestId: request.requestId, optionId }] };
},
async finishRuntime() {
- const batch = getPendingCoordinationBatch(session.state);
- if (!batch) throw new Error("Expected actual pending coordination batch");
+ const batch = runtimeWait(session.state);
+ if (!batch) throw new Error("Expected calls the runtime runs");
return drive({
runtimeActionResults: batch.tasks.map((r) => ({
kind: "tool-result" as const,
@@ -266,6 +276,30 @@ it("completes a plain tool turn without any pending input [control]", async () =
expect((await f.drive({ message: "Read the status." })).settledTurn?.output).toBe("FINAL");
});
+// A final output written beside calls whose results the model hasn't read can't end the turn:
+// the model reads their results and its answer's rejection, then answers again.
+for (const beside of ["workflow", "gateA"] as const) {
+ it(`asks for the final output again once a ${beside} call beside it settles`, async () => {
+ const schema = {
+ properties: { title: { type: "string" } },
+ required: ["title"],
+ type: "object",
+ };
+ const f = fixture(`final-output-beside-${beside}`, false, undefined, schema);
+ f.script.push([{ toolName: beside }, { toolName: "final_output", input: { title: "Early" } }]);
+ await f.drive({ message: "Run it, then report." });
+ f.script.push([{ toolName: "final_output", input: { title: "Done" } }]);
+ const result =
+ beside === "workflow" ? await f.finishRuntime() : await f.drive(f.respond("gateA"));
+
+ expect(result.settledTurn?.output).toEqual({ title: "Done" });
+ expect(suspendedSteps(f.session.state)).toEqual([]);
+ const rereads = JSON.stringify(f.prompts.at(-1));
+ expect(rereads).toContain(beside === "workflow" ? "runtime-RESULT" : "gateA-RESULT");
+ expect(rereads).toContain("Your final output wasn't delivered");
+ });
+}
+
it("finishes after resolving the only approval [control]", async () => {
const f = fixture("control-resolve-all");
await f.gate("gateA");
@@ -367,8 +401,12 @@ it("keeps a message waiting behind a budget prompt and runs it after the grant",
const waitingStart = f.events.length;
expect((await f.drive({ message: "Also say goodbye." })).held).toEqual({ kind: "request" });
- // The prompt still holds the turn; the message is announced when it runs.
- expect(f.events.slice(waitingStart).map((event) => event.type)).toEqual(["turn.waiting"]);
+ // The message is received into a turn that holds on the prompt; the grant resumes it.
+ expect(f.events.slice(waitingStart).map((event) => event.type)).toEqual([
+ "turn.started",
+ "message.received",
+ "turn.waiting",
+ ]);
expect(f.pending().map((r) => r.kind)).toEqual(["session-limit"]);
f.script.push(calls("read"), "FINAL");
@@ -454,12 +492,25 @@ it("runs an approved call and cancels the rest when a partial approval is steere
const parked = await f.drive({ message: "Prepare gateA and gateB." });
expect(parked.held).toEqual({ kind: "request" });
const partialStart = f.events.length;
- const partial = await f.drive(f.respond("gateA"));
- // The partial answer leaves gateB open, so the turn stays held on it.
+ // An HTTP answer is attributed: the approval settles, but its batch waits for gateB.
+ const partial = await f.drive({
+ attributedInputResponses: f.respond("gateA").inputResponses!.map((response) => ({
+ auth: {
+ attributes: {},
+ authenticator: "test",
+ issuer: "test",
+ principalId: "alice",
+ principalType: "user" as const,
+ },
+ response,
+ })),
+ });
expect(partial.held).toEqual({ kind: "request" });
- expect(f.events.slice(partialStart).map((event) => event.type)).toEqual(["turn.waiting"]);
+ expect(f.events.slice(partialStart).map((event) => event.type)).toEqual([
+ "approval.settled",
+ "turn.waiting",
+ ]);
expect(f.executions).toEqual([]);
- expect(f.pending().map((request) => request.action.toolName)).toEqual(["gateA", "gateB"]);
f.script.push("FINAL", "FINAL");
const result = await f.drive({ message: "Skip gateB for now." });
@@ -471,6 +522,12 @@ it("runs an approved call and cancels the rest when a partial approval is steere
.flatMap((event) => event.data.resolutions)
.map((resolution) => resolution.outcome),
).toEqual(["approved", "ignored"]);
+ // The settled answer still counted, so the message reaches the model as sent.
+ expect(
+ f.events
+ .filter((event) => event.type === "message.received")
+ .map((event) => event.data.message),
+ ).toEqual(["Prepare gateA and gateB.", "Skip gateB for now."]);
expect(result.settledTurn?.output).toBe("FINAL");
});
@@ -551,6 +608,7 @@ it("keeps the turn held while a responder signs in, and fails the sign-in on exp
const challenges = [
{
candidateId: candidate.candidateId,
+ attemptId: "notes-attempt",
name: "notes",
hookUrl: "https://example.com/callback",
challenge: { url: "https://example.com/sign-in" },
@@ -567,6 +625,16 @@ it("keeps the turn held while a responder signs in, and fails the sign-in on exp
{ challenges },
),
}));
+ f.record(
+ createAuthorizationRequiredEvent({
+ attemptId: "notes-attempt",
+ candidateId: candidate.candidateId,
+ name: "notes",
+ description: "Connect notes",
+ webhookUrl: "https://example.com/callback",
+ ...suspendedSteps(f.session.state)[0]!.event,
+ }),
+ );
const start = f.events.length;
expect((await f.drive()).held).toEqual({ kind: "request" });
expect(f.events.slice(start).map((event) => event.type)).toEqual(["turn.waiting"]);
diff --git a/packages/eve/src/harness/model-call/call.ts b/packages/eve/src/harness/model-call/call.ts
new file mode 100644
index 000000000..dae2d3dca
--- /dev/null
+++ b/packages/eve/src/harness/model-call/call.ts
@@ -0,0 +1,513 @@
+import { createStepCompletedEvent } from "#protocol/message.js";
+import {
+ isStepCount,
+ type LanguageModel,
+ type LanguageModelCallEndEvent,
+ type ModelMessage,
+ ToolLoopAgent,
+ type ToolSet,
+ type TypedToolResult,
+} from "ai";
+
+import { AuthKey, HistoryStateKey } from "#context/keys.js";
+import { workingTaskIds } from "#execution/tasks/model-step.js";
+import {
+ hydrateSandboxAttachments,
+ moveToolResultFilesToUserMessages,
+} from "#harness/attachment-staging.js";
+import { emitStreamContent } from "#harness/emission.js";
+import { FINAL_OUTPUT_TOOL_NAME } from "#harness/final-output.js";
+import type { GenerationSteering } from "#harness/generation-steering.js";
+import { interruptStreamOnFailure } from "#harness/interruptible-stream.js";
+import type { HarnessModelMessage, UserModelMessage } from "#harness/messages.js";
+import {
+ ContentFilteredModelResponseError,
+ EmptyModelResponseError,
+} from "#harness/model-call/errors.js";
+import {
+ type AnthropicCacheMarker,
+ detectPromptCachePath,
+ getAnthropicCacheMarker,
+ type PromptCachePath,
+} from "#harness/prompt-cache.js";
+import { estimateRequestEnvelope } from "#harness/request-envelope.js";
+import { summarizeKnownError } from "#harness/semantic-errors/index.js";
+import { activeTurnId } from "#harness/session-machine/view.js";
+import type { Step } from "#harness/step/context.js";
+import {
+ compactPrompt,
+ projectPrompt,
+ type Prompt,
+ withClientContext,
+} from "#harness/step/prompt.js";
+import {
+ buildStepHooks,
+ emitStepActions,
+ type HarnessStepResult,
+ readGatewayGenerationId,
+} from "#harness/step-hooks.js";
+import { estimateTokens } from "#harness/token-estimate.js";
+import { buildToolApproval } from "#harness/tools.js";
+import { throwIfTurnAborted } from "#harness/turn-cancellation.js";
+import {
+ accumulateTurnUsage,
+ getTurnUsageState,
+ setTurnUsageState,
+ type TokenUsageDelta,
+} from "#harness/turn-tag-state.js";
+import type { StepResult } from "#harness/types.js";
+import type { InstrumentationAttempt } from "#instrumentation/runtime.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { createLogger, logError } from "#internal/logging.js";
+import { maybeCompact } from "#harness/compaction/step.js";
+import { buildGatewayAttributionHeaders } from "./model.js";
+import { isEmptyModelResponse, rethrowNoOutputAsEmptyResponse } from "./recovery.js";
+import {
+ modelInstructions,
+ requestMessages,
+ type RequestMessages,
+ withTrailingUserNote,
+} from "./request.js";
+import {
+ appendMissingToolResultMessages,
+ answerSkippedToolCalls,
+ extractToolResultCallIds,
+ withAccumulatedResponseMessages,
+} from "./response.js";
+import { runModelCallWithRetries } from "./retry.js";
+import { logToolExecutionError, type ModelTools, prepareModelTools } from "./tools.js";
+import { extractGatewayCostUsd, extractTokenUsageDelta } from "./usage.js";
+
+const environment = process.env.NODE_ENV ?? "unknown";
+const eveVersion = resolveInstalledPackageInfo().version;
+
+const log = createLogger("harness.tool-loop");
+
+/** How one attempt differs from the step's first: what recovery and retries change. */
+export interface ModelCallOptions {
+ readonly disabledProviderTools?: ReadonlySet<string>;
+ readonly extraSystemNote?: string;
+ readonly retryReason?: "empty-response";
+ readonly suppressStepStartedEmission?: boolean;
+ readonly trailingUserNote?: string;
+}
+
+/** What a model step's caller needs from the step. */
+interface ModelCallerInput {
+ readonly model: LanguageModel;
+ readonly generation: GenerationSteering;
+ readonly hidesHeldText: boolean;
+ readonly turnMessages: readonly UserModelMessage[];
+ readonly approvedTools: ReadonlySet<string>;
+ readonly pendingApprovalsNote: string | undefined;
+ /** The prompt as the step started it, projected for the model. */
+ readonly projectedMessages: HarnessModelMessage[];
+ readonly startStep: (messages: readonly ModelMessage[]) => Promise<void>;
+ readonly setAttemptScope: (scope: InstrumentationAttempt | undefined) => void;
+}
+
+/**
+ * Calls the model for one step. Each attempt rebuilds the tools, the request, and the agent, so an
+ * earlier stream can't resolve a retry's one-shot step hooks with stale partial output. An attempt
+ * may first compact the prompt, which rewrites the durable messages the step later commits.
+ */
+export class ModelCaller {
+ readonly cachePath: PromptCachePath;
+ readonly marker: AnthropicCacheMarker | undefined;
+ private readonly attributionHeaders: Record<string, string> | undefined;
+ /** The prompt as the model reads it, projected for its history view. */
+ private projectedMessages: HarnessModelMessage[];
+ /** The latest attempt's request; its history is what the step commits. */
+ request: RequestMessages;
+ /** The latest attempt's tools, which decide how the step's calls defer and end the turn. */
+ tools: ModelTools | undefined;
+ /** The messages the latest attempt sent, after attachments were hydrated. */
+ modelMessages: ModelMessage[] = [];
+ requestEnvelopeTokens = 0;
+ /** Usage of a call steering interrupted, which the steered step still counts. */
+ private interruptedUsage: TokenUsageDelta | undefined;
+ private compactionFailure: { readonly error: unknown } | undefined;
+ private attemptIndex = 0;
+
+ private readonly step: Step;
+ private readonly prompt: Prompt;
+ private readonly input: ModelCallerInput;
+
+ constructor(step: Step, prompt: Prompt, input: ModelCallerInput) {
+ this.step = step;
+ this.prompt = prompt;
+ this.input = input;
+
+ this.cachePath = detectPromptCachePath(input.model);
+ this.marker =
+ this.cachePath.kind === "anthropic-direct" ? getAnthropicCacheMarker() : undefined;
+ this.attributionHeaders = buildGatewayAttributionHeaders(
+ input.model,
+ step.config.runtimeIdentity,
+ );
+ this.projectedMessages = input.projectedMessages;
+ this.request = this.buildRequest(step.config.tools);
+ }
+
+ /** Calls the model, retrying transient failures. */
+ async call(options: ModelCallOptions): Promise<HarnessStepResult> {
+ return await runModelCallWithRetries(
+ (attempt) =>
+ this.attempt({
+ ...options,
+ suppressStepStartedEmission: attempt === 1 ? options.suppressStepStartedEmission : true,
+ }),
+ {
+ canRetry: () => this.compactionFailure === undefined,
+ sessionId: this.step.session.sessionId,
+ turnId: this.step.position().turnId,
+ },
+ this.input.generation.signal,
+ );
+ }
+
+ /** A failed compaction fails the step, whatever recovery the call attempted. */
+ throwIfCompactionFailed(): void {
+ if (this.compactionFailure !== undefined) throw this.compactionFailure.error;
+ }
+
+ /** Steering interrupted the call: the step ends with what it committed, and runs again. */
+ async steered(): Promise<StepResult> {
+ const { step } = this;
+ throwIfTurnAborted(step.config.abortSignal);
+ step.ctx?.set(HistoryStateKey, this.request.historyState);
+ if (this.interruptedUsage !== undefined) {
+ step.session = setTurnUsageState(
+ step.session,
+ accumulateTurnUsage({
+ previous: getTurnUsageState(step.session.state),
+ turnId: step.position().turnId,
+ usage: this.interruptedUsage,
+ }),
+ );
+ }
+ await step.emit?.(
+ createStepCompletedEvent({
+ ...step.position(),
+ finishReason: "other",
+ usage: this.interruptedUsage,
+ }),
+ );
+ return {
+ next: step.runStep,
+ session: { ...step.session, history: [...this.request.history] },
+ steered: true,
+ };
+ }
+
+ /** The step's result counted its usage, so an interrupted call's usage no longer applies. */
+ clearInterruptedUsage(): void {
+ this.interruptedUsage = undefined;
+ }
+
+ private buildRequest(coordinationTools: ModelTools["coordinationTools"]): RequestMessages {
+ return requestMessages(this.step, {
+ coordinationTools,
+ hidesHeldText: this.input.hidesHeldText,
+ messages: this.prompt.messages,
+ pendingApprovalsNote: this.input.pendingApprovalsNote,
+ projectedMessages: this.projectedMessages,
+ turnMessages: this.input.turnMessages,
+ });
+ }
+
+ private instructions(extraSystemNote: string | undefined) {
+ return modelInstructions({
+ extraSystemNote,
+ marker: this.marker,
+ session: this.step.session,
+ systemMessages: this.request.systemMessages,
+ });
+ }
+
+ private async prepare(options: ModelCallOptions): Promise<ModelTools> {
+ const tools = await prepareModelTools(this.step, {
+ model: this.input.model,
+ approvedTools: this.input.approvedTools,
+ disabledProviderTools: options.disabledProviderTools,
+ generation: this.input.generation,
+ marker: this.marker,
+ });
+ this.tools = tools;
+ this.request = this.buildRequest(tools.coordinationTools);
+ this.requestEnvelopeTokens = await estimateRequestEnvelope({
+ history: this.projectedMessages,
+ instructions: this.instructions(options.extraSystemNote),
+ messages: withTrailingUserNote(this.request.nonSystemMessages, options.trailingUserNote),
+ tools: tools.effectiveTools,
+ });
+ return tools;
+ }
+
+ /** Compacts the prompt when it's over the threshold, then rebuilds what depends on it. */
+ private async compact(options: ModelCallOptions, tools: ModelTools): Promise<ModelTools> {
+ const { step, prompt } = this;
+ const { config } = step;
+ let compaction: Awaited<ReturnType<typeof maybeCompact>>;
+ try {
+ compaction = await maybeCompact({
+ abortSignal: config.abortSignal,
+ auth: step.ctx?.get(AuthKey) ?? null,
+ emissionState: step.position(),
+ historyProjector: config.historyProjector,
+ messages: [...prompt.messages],
+ model: this.input.model,
+ promptMessages: withClientContext(prompt),
+ publish: step.publish,
+ requestEnvelopeTokens: this.requestEnvelopeTokens,
+ resolveModel: config.resolveModel,
+ runtimeIdentity: config.runtimeIdentity,
+ session: step.session,
+ telemetry: step.instrumentation?.telemetry(),
+ });
+ } catch (error) {
+ this.compactionFailure = { error };
+ throw error;
+ }
+ step.session = compaction.session;
+ if (!compaction.compacted) return tools;
+ compactPrompt(step, prompt, compaction.messages);
+ const { compaction: settings } = step.session;
+ step.session = {
+ ...step.session,
+ compaction: {
+ recentWindowSize: settings.recentWindowSize,
+ threshold: settings.threshold,
+ thresholdPercent: settings.thresholdPercent,
+ },
+ };
+ this.projectedMessages = projectPrompt(step, prompt);
+ return await this.prepare(options);
+ }
+
+ private async attempt(options: ModelCallOptions): Promise<HarnessStepResult> {
+ const { step } = this;
+ const { generation, model } = this.input;
+ const tools = await this.compact(options, await this.prepare(options));
+ // New announcements join durable history, so they must not inflate the
+ // envelope baseline and hide instruction growth on the next step.
+ this.requestEnvelopeTokens = Math.max(
+ 0,
+ this.requestEnvelopeTokens -
+ (estimateTokens(this.request.history) - estimateTokens(this.prompt.messages)),
+ );
+ generation.begin();
+ // Hydrate `eve-sandbox:` file refs for this call only; history keeps the refs.
+ this.modelMessages = await hydrateSandboxAttachments(this.request.nonSystemMessages);
+ if (
+ typeof this.input.model !== "string" &&
+ typeof this.input.model.provider === "string" &&
+ this.input.model.provider.endsWith(".chat")
+ ) {
+ this.modelMessages = moveToolResultFilesToUserMessages(this.modelMessages);
+ }
+ const instructions = this.instructions(options.extraSystemNote);
+ const runtimeContext =
+ step.instrumentation?.resolveRuntimeContext({
+ emissionState: step.position(),
+ environment,
+ eveVersion,
+ modelInput: { instructions, messages: this.modelMessages },
+ session: step.session,
+ }) ?? {};
+ // Label a reissued call's telemetry; otherwise a retry shows only as a second span.
+ if (options.retryReason) runtimeContext["eve.retry.reason"] = options.retryReason;
+ // A trailing note rather than a system one keeps the provider's cached prefix valid; the
+ // step commits its prompt messages, so the note exists only on this call's request.
+ const callMessages = withTrailingUserNote(this.modelMessages, options.trailingUserNote);
+
+ const position = step.position();
+ const attempt = step.instrumentation?.prepareAttempt({
+ isFrameworkTool: (name) => step.frameworkToolNames.has(name),
+ attemptIndex: this.attemptIndex++,
+ runtimeContext,
+ stepIndex: position.stepIndex,
+ turnId: activeTurnId(position),
+ });
+ this.input.setAttemptScope(attempt?.scope);
+
+ const hooks = buildStepHooks({
+ auth: step.ctx?.get(AuthKey) ?? null,
+ cachePath: this.cachePath,
+ marker: this.marker,
+ session: step.session,
+ startStep: options.suppressStepStartedEmission === true ? undefined : this.input.startStep,
+ });
+ const settings = {
+ headers: this.attributionHeaders,
+ instructions,
+ model,
+ onLanguageModelCallEnd: (event: LanguageModelCallEndEvent) => {
+ if (generation.interrupted) return;
+ this.interruptedUsage = extractTokenUsageDelta({
+ costUsd: extractGatewayCostUsd(event.providerMetadata),
+ usage: event.usage,
+ });
+ },
+ onToolExecutionEnd: logToolExecutionError,
+ // Replaces the AI SDK's default `console.error`; the harness reports failures as events.
+ onError(event: { error: unknown }) {
+ if (generation.interrupted) return;
+ // A recognized configuration failure skips the raw dump: its stack points at the
+ // harness, not the fix, and the failure path logs a one-line summary.
+ if (summarizeKnownError(event.error)?.tags.includes("config") === true) return;
+ logError(log, "tool-loop stream error", event.error);
+ },
+ onStepEnd: hooks.onStepEnd,
+ onStepStart: hooks.onStepStart,
+ prepareStep: hooks.prepareStep,
+ reasoning: step.session.agent.modelReference?.reasoning ?? step.session.agent.reasoning,
+ runtimeContext,
+ stopWhen: isStepCount(1),
+ telemetry: attempt?.telemetry,
+ toolApproval: buildToolApproval(tools.modelTools, generation.signal),
+ tools: tools.effectiveTools,
+ };
+ const agent = new ToolLoopAgent(settings);
+
+ try {
+ const result =
+ step.emit === undefined
+ ? await this.generate(agent, callMessages, hooks.stepResult)
+ : await this.stream(agent, callMessages, hooks.stepResult, tools);
+ await attempt?.complete();
+ return result;
+ } catch (error) {
+ if (generation.interrupted) await attempt?.complete();
+ else await attempt?.fail(error);
+ generation.check();
+ return rethrowNoOutputAsEmptyResponse(error);
+ }
+ }
+
+ /** Streams the call, publishing its content as it arrives. */
+ private async stream(
+ agent: ToolLoopAgent,
+ messages: ModelMessage[],
+ stepResultPromise: Promise<HarnessStepResult>,
+ tools: ModelTools,
+ ): Promise<HarnessStepResult> {
+ const { step } = this;
+ const { generation } = this.input;
+ const excludedActionToolNames = new Set([FINAL_OUTPUT_TOOL_NAME]);
+ const streamResult = await agent.stream({ abortSignal: generation.signal, messages });
+ const {
+ emittedActionCallIds,
+ handledInlineToolResultCallIds,
+ invalidInputToolCallIds,
+ inlineAuthorizationResults,
+ trailingInlineToolResultParts,
+ } = await emitStreamContent(
+ step.publish,
+ step.position(),
+ interruptStreamOnFailure(streamResult.fullStream, generation.signal),
+ {
+ excludedActionToolNames,
+ hidesHeldText: this.input.hidesHeldText && workingTaskIds(step.session).length > 0,
+ tools: tools.presentationTools,
+ },
+ );
+ throwIfTurnAborted(step.config.abortSignal);
+ generation.check();
+ const [stepResult, accumulatedResponseMessages] = await Promise.all([
+ stepResultPromise,
+ streamResult.responseMessages,
+ ]);
+ assertUsableResponse(
+ stepResult,
+ accumulatedResponseMessages,
+ inlineAuthorizationResults.length > 0 || trailingInlineToolResultParts.length > 0,
+ );
+ const skipped = answerSkippedToolCalls(stepResult, tools.effectiveTools);
+ await emitStepActions(
+ step.publish,
+ step.position(),
+ skipped.length === 0
+ ? stepResult
+ : withAccumulatedResponseMessages({
+ stepResult,
+ responseMessages: appendMissingToolResultMessages({
+ append: skipped,
+ responseMessages: stepResult.response.messages,
+ }),
+ }),
+ {
+ emittedActionCallIds,
+ excludedActionCallIds: invalidInputToolCallIds,
+ excludedActionToolNames,
+ handledInlineToolResultCallIds,
+ tools: tools.presentationTools,
+ },
+ );
+ const toolResultsByCallId = new Map(
+ (stepResult.toolResults as TypedToolResult<ToolSet>[]).map((toolResult) => [
+ toolResult.toolCallId,
+ toolResult,
+ ]),
+ );
+ for (const toolResult of inlineAuthorizationResults) {
+ toolResultsByCallId.set(toolResult.toolCallId, toolResult);
+ }
+ return withAccumulatedResponseMessages({
+ invalidInputToolCallIds,
+ responseMessages: appendMissingToolResultMessages({
+ append: [
+ ...trailingInlineToolResultParts,
+ ...answerSkippedToolCalls(stepResult, tools.effectiveTools),
+ ],
+ responseMessages: accumulatedResponseMessages,
+ }),
+ stepResult,
+ toolResults: [...toolResultsByCallId.values()],
+ });
+ }
+
+ /** Runs the call without a listener: nothing streams. */
+ private async generate(
+ agent: ToolLoopAgent,
+ messages: ModelMessage[],
+ stepResultPromise: Promise<HarnessStepResult>,
+ ): Promise<HarnessStepResult> {
+ const { generation } = this.input;
+ const generateResult = await agent.generate({ abortSignal: generation.signal, messages });
+ throwIfTurnAborted(this.step.config.abortSignal);
+ generation.check();
+ const stepResult = await stepResultPromise;
+ assertUsableResponse(stepResult, generateResult.responseMessages, false);
+ return withAccumulatedResponseMessages({
+ responseMessages: appendMissingToolResultMessages({
+ append: answerSkippedToolCalls(stepResult, this.tools!.effectiveTools),
+ responseMessages: generateResult.responseMessages,
+ }),
+ stepResult,
+ });
+ }
+}
+
+/**
+ * A filtered response fails the step, and an empty one, without output or any tool result, is
+ * retried by the empty-response recovery.
+ */
+function assertUsableResponse(
+ stepResult: HarnessStepResult,
+ responseMessages: Parameters<typeof extractToolResultCallIds>[0],
+ hasInlineResults: boolean,
+): void {
+ if (stepResult.finishReason === "content-filter") {
+ throw new ContentFilteredModelResponseError(
+ readGatewayGenerationId(stepResult.providerMetadata),
+ );
+ }
+ if (
+ isEmptyModelResponse(stepResult) &&
+ extractToolResultCallIds(responseMessages).size === 0 &&
+ !hasInlineResults
+ ) {
+ throw new EmptyModelResponseError();
+ }
+}
diff --git a/packages/eve/src/harness/model-call-error.test.ts b/packages/eve/src/harness/model-call/errors.test.ts
similarity index 99%
rename from packages/eve/src/harness/model-call-error.test.ts
rename to packages/eve/src/harness/model-call/errors.test.ts
index 49c1f1daf..575e64509 100644
--- a/packages/eve/src/harness/model-call-error.test.ts
+++ b/packages/eve/src/harness/model-call/errors.test.ts
@@ -9,7 +9,7 @@ import {
isNoOutputGeneratedError,
normalizeModelStreamError,
extractUpstreamRejectionMessage,
-} from "#harness/model-call-error.js";
+} from "#harness/model-call/errors.js";
import { TurnCancelledError } from "#harness/turn-cancellation.js";
/**
diff --git a/packages/eve/src/harness/model-call-error.ts b/packages/eve/src/harness/model-call/errors.ts
similarity index 99%
rename from packages/eve/src/harness/model-call-error.ts
rename to packages/eve/src/harness/model-call/errors.ts
index 88eedb543..f70b28dcd 100644
--- a/packages/eve/src/harness/model-call-error.ts
+++ b/packages/eve/src/harness/model-call/errors.ts
@@ -206,7 +206,7 @@ function readErrorMessage(error: unknown): string {
}
/**
- * A model call that produced no content. Raised by tool-loop.ts from
+ * A model call that produced no content. Raised by the model caller from
* either of its two triggers: `isEmptyModelResponse` (a completed step
* with finishReason 'other' and no output — AI Gateway HTTP 200 whose
* stream carries no content, no usage, and no error) or
@@ -281,7 +281,7 @@ export function classifyModelCallError(error: unknown): "retry" | "recoverable"
// Not "retry": the empty response already resolved the step hooks'
// one-shot stepResult promise, so a same-hooks retry would read the
// stale empty result. The harness reissues with fresh hooks instead
- // (attemptEmptyResponseRecovery in tool-loop.ts).
+ // (`recoverModelCall` in model-call/recovery.ts).
if (error instanceof EmptyModelResponseError) {
return "recoverable";
}
diff --git a/packages/eve/src/harness/model-call/failure.ts b/packages/eve/src/harness/model-call/failure.ts
new file mode 100644
index 000000000..218d83fa0
--- /dev/null
+++ b/packages/eve/src/harness/model-call/failure.ts
@@ -0,0 +1,199 @@
+import type { JsonObject, JsonValue } from "#shared/json.js";
+import type { SemanticErrorSummary } from "#harness/semantic-errors/rule.js";
+import {
+ classifyModelCallError,
+ extractModelCallErrorDetails,
+ extractUpstreamRejectionMessage,
+ type UpstreamRejectionSummary,
+} from "#harness/model-call/errors.js";
+import { createErrorId, createLogger, formatError } from "#internal/logging.js";
+import { toErrorMessage } from "#shared/errors.js";
+import type { Step } from "#harness/step/context.js";
+import type { StepResult } from "#harness/types.js";
+import { extractWorkflowStreamWriteErrorDetails } from "#harness/workflow-stream-error.js";
+import { fail } from "#harness/session-machine/transitions.js";
+import { summarizeKnownError } from "#harness/semantic-errors/index.js";
+
+const log = createLogger("harness.tool-loop");
+/**
+ * Projects a model-call failure into the `step.failed` / `turn.failed`
+ * `details` payload. Three mutually exclusive branches:
+ *
+ * 1. Catalog match → the rule's curated `name`/`message`/`hint` plus its
+ * registered `semanticErrorId`, no SDK inspector dump.
+ * 2. Upstream rejection → raw error `message` with the extracted upstream
+ * identity, no inspector dump. No `semanticErrorId`: the message is
+ * arbitrary provider prose, not a registered failure shape.
+ * 3. Fallback → full {@link formatError} projection (cause chain via
+ * `util.inspect`) so unrecognized failures still carry the upstream
+ * stack to log aggregators.
+ *
+ * All branches merge {@link extractModelCallErrorDetails} on top so the
+ * compact gateway diagnostics (`statusCode`, `upstreamMessage`,
+ * `responseBodySnippet`, ...) always show up next to the message.
+ */
+export function buildModelCallFailureDetails(input: {
+ readonly catalogSummary: SemanticErrorSummary | null;
+ readonly error: unknown;
+ readonly errorId: string;
+ readonly modelCallDetails: JsonObject;
+ readonly upstreamRejection: UpstreamRejectionSummary | null;
+}): JsonObject {
+ const { catalogSummary, error, errorId, modelCallDetails, upstreamRejection } = input;
+
+ if (catalogSummary !== null) {
+ const details: Record<string, JsonValue> = {
+ errorId,
+ message: catalogSummary.message,
+ name: catalogSummary.name,
+ semanticErrorId: catalogSummary.id,
+ ...modelCallDetails,
+ };
+ if (catalogSummary.hint !== undefined) details.hint = catalogSummary.hint;
+ return details;
+ }
+
+ if (upstreamRejection !== null) {
+ return {
+ errorId,
+ message: toErrorMessage(error),
+ name: upstreamRejection.name,
+ ...modelCallDetails,
+ };
+ }
+
+ return { ...formatError(error, errorId), ...modelCallDetails };
+}
+
+/**
+ * Builds the structured log fields for a model-call failure. When the
+ * failure was recognized (catalog match or extracted upstream rejection),
+ * attach the compact `details` payload and *omit* the raw `error` so the
+ * logger's `util.inspect` of the cause chain (which would render
+ * `[object Object]` for upstream `APICallError` shapes) is bypassed.
+ * Otherwise fall back to the raw error so unrecognized failures keep
+ * their full stack in logs.
+ */
+export function buildModelCallFailureLogFields(input: {
+ readonly error: unknown;
+ readonly errorId: string;
+ readonly modelCallDetails: JsonObject;
+ readonly recognized: boolean;
+ readonly sessionId: string;
+ readonly turnId: string;
+}): Record<string, unknown> {
+ const base = {
+ errorId: input.errorId,
+ sessionId: input.sessionId,
+ turnId: input.turnId,
+ };
+ if (input.recognized) {
+ return { ...base, details: input.modelCallDetails };
+ }
+ return { ...base, error: input.error };
+}
+
+/**
+ * The model call failed past its retries and recoveries. A failed write to the session's stream is
+ * the workflow's failure, not the model's: the session parks for the user to retry. A terminal
+ * failure ends the session; any other fails the turn recoverably.
+ */
+export async function reportModelCallFailure(step: Step, error: unknown): Promise<StepResult> {
+ // Surface the full cause chain and upstream response body to OTel via the turn span: the AI
+ // SDK's own span records only `error.stack`, without `cause`.
+ step.instrumentation?.recordError(error);
+ // Callers without an event handler (tests, task-only paths) get the raw error.
+ if (step.emit === undefined) throw error;
+ const { sessionId } = step.session;
+ const { turnId } = step.position();
+
+ const streamWriteDetails = extractWorkflowStreamWriteErrorDetails(error);
+ if (streamWriteDetails !== null) {
+ const errorId = createErrorId();
+ log.error("workflow stream write failed — parking session for retry by the user", {
+ ...streamWriteDetails,
+ errorId,
+ error,
+ sessionId,
+ turnId,
+ });
+ await step.apply(
+ fail(step.view(), {
+ code: "WORKFLOW_STREAM_WRITE_FAILED",
+ details: { ...streamWriteDetails, errorId },
+ message: toErrorMessage(error),
+ }),
+ );
+ return { next: null, session: step.session };
+ }
+
+ const errorId = createErrorId();
+ const catalogSummary = summarizeKnownError(error);
+ const upstreamRejection = catalogSummary === null ? extractUpstreamRejectionMessage(error) : null;
+ const errorMessage =
+ catalogSummary?.message ?? upstreamRejection?.message ?? toErrorMessage(error);
+ // A task's failure reaches the parent agent as its tool-result text, so the remedy rides along
+ // in prose; event payloads keep the hint structured in `details`.
+ const taskFailureOutput =
+ catalogSummary?.hint === undefined ? errorMessage : `${errorMessage} ${catalogSummary.hint}`;
+ const modelCallDetails = extractModelCallErrorDetails(error);
+ const details = buildModelCallFailureDetails({
+ catalogSummary,
+ error,
+ errorId,
+ modelCallDetails,
+ upstreamRejection,
+ });
+ const logFields = buildModelCallFailureLogFields({
+ error,
+ errorId,
+ modelCallDetails,
+ recognized: catalogSummary !== null || upstreamRejection !== null,
+ sessionId,
+ turnId,
+ });
+
+ if (classifyModelCallError(error) === "terminal") {
+ if (catalogSummary !== null) {
+ // A recognized configuration failure logs one actionable line, not the SDK's dump.
+ log.error(`${catalogSummary.name}: ${catalogSummary.message}`, {
+ errorId,
+ hint: catalogSummary.hint,
+ sessionId,
+ turnId,
+ });
+ } else {
+ log.error(upstreamRejection?.message ?? "model call failed terminally", logFields);
+ }
+ await step.apply(
+ fail(step.view(), {
+ code: "MODEL_CALL_FAILED",
+ details,
+ message: errorMessage,
+ terminal: { sessionId },
+ }),
+ );
+ // A delegated run's caller needs a failed result to report; a conversation already ended
+ // with `session.failed`.
+ return {
+ next: step.hasDelegatedCaller
+ ? { done: true, isError: true, output: taskFailureOutput }
+ : { done: true, output: "" },
+ session: step.session,
+ };
+ }
+
+ log.error(
+ upstreamRejection?.message ?? "model call failed — parking session for retry by the user",
+ logFields,
+ );
+ await step.apply(
+ fail(step.view(), { code: "MODEL_CALL_FAILED", details, message: errorMessage }),
+ );
+ step.session = { ...step.session, outputSchema: undefined };
+ return {
+ next: null,
+ session: step.session,
+ settledTurn: { isError: true, output: taskFailureOutput },
+ };
+}
diff --git a/packages/eve/src/harness/model-call/model.ts b/packages/eve/src/harness/model-call/model.ts
new file mode 100644
index 000000000..e0c8bb608
--- /dev/null
+++ b/packages/eve/src/harness/model-call/model.ts
@@ -0,0 +1,102 @@
+import type { LanguageModel } from "ai";
+
+import type { CompactionConfig, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
+import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
+import { contextStorage } from "#context/container.js";
+import { getEffectiveModelSelection } from "#context/effective-model.js";
+import { resolveProviderHeaders } from "#internal/gateway.js";
+/**
+ * Builds AI Gateway app attribution headers when the model is gateway-routed.
+ *
+ * Bare model ids and `gateway.*` model instances route through AI Gateway.
+ * Direct-provider model instances receive no Gateway-specific headers.
+ */
+export function buildGatewayAttributionHeaders(
+ model: LanguageModel,
+ runtimeIdentity: ToolLoopHarnessConfig["runtimeIdentity"],
+): Record<string, string> | undefined {
+ const providerHeaders = resolveProviderHeaders(model);
+ if (providerHeaders === undefined) return undefined;
+
+ const title = runtimeIdentity?.agentName ?? runtimeIdentity?.agentId;
+ const deploymentHost = process.env.VERCEL_PROJECT_PRODUCTION_URL || process.env.VERCEL_URL;
+ const referer = deploymentHost ? `https://${deploymentHost}` : undefined;
+
+ const headers: Record<string, string> = { ...providerHeaders };
+ if (title) headers["x-title"] = title;
+ if (referer) headers["http-referer"] = referer;
+ return headers;
+}
+
+export async function resolveEffectiveRuntimeModel(input: {
+ readonly config: ToolLoopHarnessConfig;
+ readonly ctx: ReturnType<typeof contextStorage.getStore>;
+ readonly session: HarnessSession;
+}): Promise<{
+ readonly model: LanguageModel;
+ readonly session: HarnessSession;
+}> {
+ if (input.ctx === undefined) {
+ const reference = input.session.agent.modelReference;
+ if (reference === undefined) {
+ throw new Error("Dynamic model selection is unavailable outside an eve runtime context.");
+ }
+ return {
+ model: await input.config.resolveModel(reference),
+ session: input.session,
+ };
+ }
+
+ const selected = getEffectiveModelSelection(input.ctx);
+
+ if (selected === null) {
+ throw new Error(
+ "Dynamic model selection is required before model-dependent work begins. Add a matching resolver handler that returns a concrete model.",
+ );
+ }
+
+ return {
+ model:
+ selected.model !== undefined
+ ? selected.model
+ : await input.config.resolveModel(selected.reference),
+ session: updateSessionModelReference(input.session, selected.reference),
+ };
+}
+
+function updateSessionModelReference(
+ session: HarnessSession,
+ modelReference: RuntimeModelReference,
+): HarnessSession {
+ if (session.agent.modelReference === modelReference) return session;
+ return {
+ ...session,
+ agent: {
+ ...session.agent,
+ modelReference,
+ },
+ compaction: updateCompactionThresholdForModelReference({
+ compaction: session.compaction,
+ modelReference,
+ }),
+ };
+}
+
+function updateCompactionThresholdForModelReference(input: {
+ readonly compaction: CompactionConfig;
+ readonly modelReference: RuntimeModelReference;
+}): CompactionConfig {
+ if (input.modelReference.contextWindowTokens === undefined) {
+ return input.compaction;
+ }
+
+ return {
+ ...input.compaction,
+ threshold: Math.max(
+ 1,
+ Math.floor(
+ input.modelReference.contextWindowTokens * (input.compaction.thresholdPercent ?? 0.9),
+ ),
+ ),
+ };
+}
diff --git a/packages/eve/src/harness/model-call/recovery.ts b/packages/eve/src/harness/model-call/recovery.ts
new file mode 100644
index 000000000..571d08058
--- /dev/null
+++ b/packages/eve/src/harness/model-call/recovery.ts
@@ -0,0 +1,141 @@
+import { createLogger } from "#internal/logging.js";
+import {
+ EmptyModelResponseError,
+ extractUnsupportedProviderToolTypes,
+ isNoOutputGeneratedError,
+} from "#harness/model-call/errors.js";
+import type { HarnessStepResult } from "#harness/step-hooks.js";
+import { resolveAssistantStepText } from "#harness/messages.js";
+import { resolveFrameworkToolFromUpstreamType } from "#harness/provider-tools.js";
+
+const log = createLogger("harness.tool-loop");
+/** How a recovery reissues the call. */
+type RecoveryCall = (options: {
+ readonly disabledProviderTools?: ReadonlySet<string>;
+ readonly extraSystemNote?: string;
+ readonly retryReason?: "empty-response";
+ readonly suppressStepStartedEmission?: boolean;
+ readonly trailingUserNote?: string;
+}) => Promise<HarnessStepResult>;
+
+/**
+ * Recovers a failed model call, each recovery at most once and within the current step, so the
+ * reissue suppresses a second `step.started`:
+ *
+ * 1. AI Gateway rejected a provider-specific tool a fallback provider can't serve ("tool type 'X'
+ * is not supported"): the call is reissued without it, and a system note tells the model which
+ * capability went away. Only known provider tools are dropped, never an authored one.
+ * 2. The response was empty (see {@link EmptyModelResponseError}), including the first
+ * recovery's: the call is reissued with {@link EMPTY_RESPONSE_NUDGE}, repeating what the first
+ * recovery removed.
+ *
+ * Each reissue goes through `call` so it gets fresh step hooks: the failed attempt's one-shot
+ * `stepResult` already resolved. Returns the error that remains when nothing recovered.
+ */
+export async function recoverModelCall(input: {
+ readonly error: unknown;
+ readonly call: RecoveryCall;
+ readonly sessionId: string;
+ readonly turnId: string;
+}): Promise<{ readonly result: HarnessStepResult } | { readonly error: unknown }> {
+ let { error } = input;
+ const diagnostics = { sessionId: input.sessionId, turnId: input.turnId };
+ let options: Parameters<RecoveryCall>[0] = {};
+
+ const unsupportedTypes = extractUnsupportedProviderToolTypes(error);
+ const disabled = [
+ ...new Set(
+ unsupportedTypes.flatMap((type) => resolveFrameworkToolFromUpstreamType(type) ?? []),
+ ),
+ ];
+ if (disabled.length > 0) {
+ log.warn("disabling unsupported provider tool(s); retrying step once", {
+ ...diagnostics,
+ disabled,
+ upstreamTypes: unsupportedTypes,
+ });
+ options = {
+ disabledProviderTools: new Set(disabled),
+ extraSystemNote: buildDisabledToolNote(disabled),
+ };
+ try {
+ return { result: await input.call({ ...options, suppressStepStartedEmission: true }) };
+ } catch (retryError) {
+ error = retryError;
+ }
+ }
+
+ if (error instanceof EmptyModelResponseError) {
+ log.warn("empty model response; reissuing the model call once", diagnostics);
+ try {
+ return {
+ result: await input.call({
+ ...options,
+ retryReason: "empty-response",
+ suppressStepStartedEmission: true,
+ trailingUserNote: EMPTY_RESPONSE_NUDGE,
+ }),
+ };
+ } catch (retryError) {
+ error = retryError;
+ }
+ }
+ return { error };
+}
+
+/**
+ * Builds the one-shot system note prepended to the recovery retry's
+ * instructions so the model has explicit context for why a capability
+ * disappeared mid-turn.
+ */
+function buildDisabledToolNote(toolNames: readonly string[]): string {
+ const list = toolNames.join(", ");
+ const noun = toolNames.length === 1 ? "tool is" : "tools are";
+ return (
+ `The following ${noun} not available with the current model and ` +
+ `has been removed: ${list}. Proceed using the remaining tools or your ` +
+ `training knowledge.`
+ );
+}
+
+/**
+ * True when a step produced no assistant text and no tool calls. A blank
+ * response is ambiguous and must be retried instead of silently dropping a
+ * HITL reply.
+ */
+export function isEmptyModelResponse(step: HarnessStepResult): boolean {
+ return (
+ step.toolCalls.length === 0 &&
+ step.toolResults.length === 0 &&
+ resolveAssistantStepText(step.response.messages, step.text) === null
+ );
+}
+
+/**
+ * Rethrows the AI SDK's `NoOutputGeneratedError` as
+ * {@link EmptyModelResponseError}. Since `[email protected]`
+ * (vercel/ai#15938) a stream that closes after metadata without output or
+ * a finish chunk rejects — the SDK enqueues the error onto `fullStream`
+ * (so `emitStreamContent` throws it) and never emits `finish-step`, so
+ * `onStepEnd` does not fire and the step hooks' `stepResult` promise
+ * would never settle. The same condition previously completed as an empty
+ * step caught by {@link isEmptyModelResponse}; normalizing here funnels
+ * both shapes into the one-shot empty-response reissue.
+ */
+export function rethrowNoOutputAsEmptyResponse(error: unknown): never {
+ if (isNoOutputGeneratedError(error)) {
+ throw new EmptyModelResponseError({ cause: error });
+ }
+ throw error;
+}
+
+/**
+ * Wire-only note the empty-response reissue appends to its retry. Reads may
+ * be refreshed when earlier results are stale; completed writes and other
+ * side effects must not be repeated. Each recovery stage declares its own
+ * follow-up text: tool recovery prepends {@link buildDisabledToolNote} as
+ * a system note (its toolset change busts the prompt cache anyway), while
+ * this one trails as a user note to keep the cached prefix valid.
+ */
+const EMPTY_RESPONSE_NUDGE =
+ "Your previous reply was empty and was not delivered. Continue the current user request. Reuse completed results when they satisfy the request. If existing results are stale or insufficient, use the appropriate read tools to get fresh results. Do not repeat writes or other side effects that already completed. Do not mention this notice.";
diff --git a/packages/eve/src/harness/model-call/request.ts b/packages/eve/src/harness/model-call/request.ts
new file mode 100644
index 000000000..70f13aded
--- /dev/null
+++ b/packages/eve/src/harness/model-call/request.ts
@@ -0,0 +1,116 @@
+import type { ModelMessage, SystemModelMessage } from "ai";
+
+import { buildDynamicInstructionMessages } from "#context/dynamic-instruction-lifecycle.js";
+import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
+import { HistoryStateKey } from "#context/keys.js";
+import { taskSystemMessages } from "#execution/tasks/model-step.js";
+import { getPendingAnnouncements } from "#harness/announcements.js";
+import { createCurrentMessages } from "#harness/current-messages.js";
+import {
+ createFrameworkUserMessage,
+ type HarnessModelMessage,
+ type UserModelMessage,
+} from "#harness/messages.js";
+import { type AnthropicCacheMarker, applySystemCacheBreakpoint } from "#harness/prompt-cache.js";
+import type { Step } from "#harness/step/context.js";
+import type { HarnessSession, HarnessToolMap } from "#harness/types.js";
+
+export type RequestMessages = ReturnType<typeof createCurrentMessages>;
+
+/**
+ * The messages one model call sends: the durable prompt, then the step's system instructions and
+ * announcements. Announcements persist ahead of the new input, or after earlier tool results on a
+ * continuation, so later requests keep the full prefix.
+ */
+export function requestMessages(
+ step: Step,
+ input: {
+ readonly messages: readonly HarnessModelMessage[];
+ readonly projectedMessages: readonly HarnessModelMessage[];
+ readonly turnMessages: readonly UserModelMessage[];
+ readonly coordinationTools: HarnessToolMap;
+ readonly hidesHeldText: boolean;
+ readonly pendingApprovalsNote: string | undefined;
+ },
+): RequestMessages {
+ const { ctx } = step;
+ const messages = createCurrentMessages(input.messages, {
+ historyState: ctx?.get(HistoryStateKey),
+ currentTurnMessages: input.turnMessages,
+ projectedMessages: input.projectedMessages,
+ });
+ if (ctx !== undefined) messages.addSystem(buildDynamicInstructionMessages(ctx));
+ messages.addSystem(
+ taskSystemMessages(input.coordinationTools, { finalReplyOnly: input.hidesHeldText }),
+ );
+ messages.addAnnouncements({
+ availableSkills: ctx?.get(PendingSkillAnnouncementKey),
+ keyed: getPendingAnnouncements(ctx),
+ });
+ if (input.pendingApprovalsNote !== undefined) {
+ messages.add(input.pendingApprovalsNote, "context.state", { cacheFriendly: false });
+ }
+ return messages;
+}
+
+/** The call's system instructions: a retry's note, the agent's system prompt, then the step's. */
+export function modelInstructions(input: {
+ readonly session: HarnessSession;
+ readonly systemMessages: readonly SystemModelMessage[];
+ readonly marker: AnthropicCacheMarker | undefined;
+ readonly extraSystemNote?: string;
+}): SystemModelMessage | string | undefined {
+ const { session } = input;
+ const extra: SystemModelMessage[] = input.extraSystemNote
+ ? [{ role: "system", content: input.extraSystemNote }]
+ : [];
+ if (input.systemMessages.length === 0 && extra.length === 0) {
+ return session.agent.system ?? undefined;
+ }
+ const base: SystemModelMessage[] = session.agent.system
+ ? [{ role: "system", content: session.agent.system }]
+ : [];
+ const instructions = [...extra, ...base, ...input.systemMessages];
+ return mergeSystemInstructions(
+ input.marker ? applySystemCacheBreakpoint(instructions, input.marker) : instructions,
+ );
+}
+
+/** A retry's note, trailing the call's messages. */
+export function withTrailingUserNote(
+ messages: readonly ModelMessage[],
+ note?: string,
+): ModelMessage[] {
+ return note ? [...messages, createFrameworkUserMessage("execution.retry", note)] : [...messages];
+}
+
+export function mergeSystemInstructions(
+ instructions: readonly SystemModelMessage[],
+): SystemModelMessage | undefined {
+ if (instructions.length === 0) {
+ return undefined;
+ }
+
+ if (instructions.length === 1) {
+ return { ...instructions[0]! };
+ }
+
+ let providerOptions: SystemModelMessage["providerOptions"] | undefined;
+ for (const instruction of instructions) {
+ if (instruction.providerOptions !== undefined) {
+ providerOptions = {
+ ...providerOptions,
+ ...instruction.providerOptions,
+ };
+ }
+ }
+
+ const merged: SystemModelMessage = {
+ role: "system",
+ content: instructions.map((instruction) => instruction.content).join("\n\n"),
+ };
+ if (providerOptions !== undefined) {
+ merged.providerOptions = providerOptions;
+ }
+ return merged;
+}
diff --git a/packages/eve/src/harness/model-call/response.ts b/packages/eve/src/harness/model-call/response.ts
new file mode 100644
index 000000000..743e4091d
--- /dev/null
+++ b/packages/eve/src/harness/model-call/response.ts
@@ -0,0 +1,140 @@
+import {
+ getInvalidToolCallInputError,
+ isInvalidToolCall,
+} from "#harness/tool-call-input-errors.js";
+import type { ModelMessage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
+
+import type { HarnessStepResult } from "#harness/step-hooks.js";
+
+type StepResponseMessage = HarnessStepResult["response"]["messages"][number];
+type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
+type ToolResultPart = Extract<ToolResponsePart, { type: "tool-result" }>;
+
+export function withAccumulatedResponseMessages(input: {
+ readonly invalidInputToolCallIds?: ReadonlySet<string>;
+ readonly responseMessages: readonly StepResponseMessage[];
+ readonly stepResult: HarnessStepResult;
+ readonly toolResults?: readonly TypedToolResult<ToolSet>[];
+}): HarnessStepResult {
+ const { stepResult } = input;
+
+ /*
+ * AI SDK `StepResult` fields are prototype getters, so spreading the
+ * instance drops them. Materialize each field while replacing the final
+ * step's messages with the SDK's accumulated response, which also contains
+ * approval-resume results created before the model step.
+ */
+ return {
+ content: stepResult.content,
+ finishReason: stepResult.finishReason,
+ ...(input.invalidInputToolCallIds === undefined
+ ? {}
+ : { invalidInputToolCallIds: input.invalidInputToolCallIds }),
+ providerMetadata: stepResult.providerMetadata,
+ response: {
+ ...stepResult.response,
+ messages: [...input.responseMessages],
+ },
+ text: stepResult.text,
+ toolCalls: stepResult.toolCalls,
+ toolResults: input.toolResults === undefined ? stepResult.toolResults : [...input.toolResults],
+ usage: stepResult.usage,
+ };
+}
+
+/** True when provider history still owes a result for any assistant tool call. */
+export function hasUnansweredToolCall(messages: readonly ModelMessage[]): boolean {
+ const callIds = new Set<string>();
+ const resultIds = new Set<string>();
+
+ for (const message of messages) {
+ if (!Array.isArray(message.content)) continue;
+ for (const part of message.content) {
+ if (typeof part !== "object" || part === null) continue;
+ if (part.type === "tool-call") callIds.add(part.toolCallId);
+ if (part.type === "tool-result") resultIds.add(part.toolCallId);
+ }
+ }
+
+ for (const callId of callIds) {
+ if (!resultIds.has(callId)) return true;
+ }
+ return false;
+}
+
+/**
+ * Appends synthesized tool results for calls that have no result anywhere in
+ * the step's response messages. Exported for its dedupe contract: a call
+ * already answered — including provider-executed results the SDK keeps
+ * inline in the assistant message — must never receive a second
+ * `tool-result`, or the next Anthropic call rejects the history with
+ * "each tool_use must have a single result".
+ */
+export function appendMissingToolResultMessages(input: {
+ readonly append: readonly ToolResultPart[];
+ readonly responseMessages: readonly StepResponseMessage[];
+}): StepResponseMessage[] {
+ const existingCallIds = extractToolResultCallIds(input.responseMessages);
+ const append = input.append.filter((part) => !existingCallIds.has(part.toolCallId));
+
+ return [
+ ...input.responseMessages,
+ ...(append.length > 0 ? [{ role: "tool" as const, content: [...append] }] : []),
+ ] satisfies StepResponseMessage[];
+}
+
+/**
+ * CallIds answered anywhere in the response messages. Scans every message
+ * role: provider-executed tool results arrive inline in the *assistant*
+ * message (the SDK only moves them to a `tool` message during provider
+ * history normalization, which runs after the backfill paths), so a
+ * tool-message-only scan would let a synthesized result duplicate them.
+ */
+export function extractToolResultCallIds(messages: readonly ModelMessage[]): ReadonlySet<string> {
+ const callIds = new Set<string>();
+
+ for (const message of messages) {
+ if (!Array.isArray(message.content)) {
+ continue;
+ }
+
+ for (const part of message.content) {
+ if (typeof part === "object" && part !== null && part.type === "tool-result") {
+ callIds.add(part.toolCallId);
+ }
+ }
+ }
+
+ return callIds;
+}
+
+export function answerSkippedToolCalls(step: HarnessStepResult, tools: ToolSet): ToolResultPart[] {
+ const { finishReason } = step;
+ if (finishReason === "stop" || finishReason === "tool-calls") return [];
+
+ const answeredCallIds = extractToolResultCallIds(step.response.messages);
+ const pendingApprovalCallIds = new Set(
+ (step.content ?? []).flatMap((part) =>
+ part.type === "tool-approval-request" && part.isAutomatic !== true
+ ? [part.toolCall.toolCallId]
+ : [],
+ ),
+ );
+ const value = `The tool did not run because the model response ended early (finish reason: ${finishReason}). Call the tool again if you still need its result.`;
+ return ((step.toolCalls ?? []) as TypedToolCall<ToolSet>[])
+ .filter(
+ (toolCall) =>
+ tools[toolCall.toolName]?.execute !== undefined &&
+ toolCall.providerExecuted !== true &&
+ !isInvalidToolCall(toolCall) &&
+ getInvalidToolCallInputError({ toolCall }) === undefined &&
+ !answeredCallIds.has(toolCall.toolCallId) &&
+ !pendingApprovalCallIds.has(toolCall.toolCallId),
+ )
+ .map((toolCall) => ({
+ output: { type: "error-text", value },
+ toolCallId: toolCall.toolCallId,
+ toolName: toolCall.toolName,
+ type: "tool-result",
+ }));
+}
diff --git a/packages/eve/src/harness/model-call/retry.ts b/packages/eve/src/harness/model-call/retry.ts
new file mode 100644
index 000000000..091e83d60
--- /dev/null
+++ b/packages/eve/src/harness/model-call/retry.ts
@@ -0,0 +1,63 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+import { createLogger } from "#internal/logging.js";
+import { classifyModelCallError } from "#harness/model-call/errors.js";
+
+const log = createLogger("harness.tool-loop");
+/**
+ * Max attempts (1 original + N retries) for transient model-call
+ * failures before the harness gives up and falls back to the
+ * recoverable/terminal emission path. Kept small on purpose — every
+ * attempt costs a round-trip plus prompt tokens, and the dominant
+ * use case (429 / 502) clears quickly or not at all.
+ */
+const MODEL_CALL_MAX_ATTEMPTS = 3;
+
+/**
+ * Base delay (ms) between model-call retries. Doubled each attempt,
+ * plus a small random jitter to avoid thundering-herd behavior when
+ * a provider incident clears.
+ */
+const MODEL_CALL_RETRY_BASE_DELAY_MS = 500;
+
+/**
+ * Retries `fn` with exponential backoff while the thrown error is
+ * classified as `"retry"`. Rethrows the last error once attempts are
+ * exhausted or the error is classified as something other than
+ * transient.
+ */
+export async function runModelCallWithRetries<T>(
+ fn: (attempt: number) => Promise<T>,
+ diag: {
+ readonly sessionId: string;
+ readonly turnId: string;
+ readonly canRetry?: () => boolean;
+ },
+ signal: AbortSignal,
+): Promise<T> {
+ for (let attempt = 1; ; attempt++) {
+ signal.throwIfAborted();
+ try {
+ return await fn(attempt);
+ } catch (error) {
+ signal.throwIfAborted();
+ if (
+ diag.canRetry?.() === false ||
+ attempt === MODEL_CALL_MAX_ATTEMPTS ||
+ classifyModelCallError(error) !== "retry"
+ ) {
+ throw error;
+ }
+ const delayMs =
+ MODEL_CALL_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 250);
+ log.warn("model call failed transiently — retrying", {
+ attempt,
+ delayMs,
+ sessionId: diag.sessionId,
+ turnId: diag.turnId,
+ error,
+ });
+ await delay(delayMs, undefined, { signal });
+ }
+ }
+}
diff --git a/packages/eve/src/harness/model-call/run.ts b/packages/eve/src/harness/model-call/run.ts
new file mode 100644
index 000000000..5f0921b0a
--- /dev/null
+++ b/packages/eve/src/harness/model-call/run.ts
@@ -0,0 +1,195 @@
+import type { LanguageModel, ModelMessage } from "ai";
+
+import { HistoryStateKey } from "#context/keys.js";
+import type { GenerationSteering } from "#harness/generation-steering.js";
+import { type HarnessModelMessage, validateHarnessModelMessages } from "#harness/messages.js";
+import {
+ type ApprovedWork,
+ dispatchApprovedWorkflows,
+ enforceBudget,
+ hasApprovedWork,
+ humanInputContext,
+ runApprovedLocalCalls,
+} from "#harness/hitl/index.js";
+import { stepStartedForResolvers } from "#harness/session-machine/resolver-events.js";
+import { startStep } from "#harness/session-machine/transitions.js";
+import { activeTurnId } from "#harness/session-machine/view.js";
+import { failBoundaryEvent, failModelSelection, type Step } from "#harness/step/context.js";
+import type { TurnInput } from "#harness/step/intake.js";
+import {
+ buildPrompt,
+ previewPrompt,
+ projectPrompt,
+ type Prompt,
+ withClientContext,
+} from "#harness/step/prompt.js";
+import type { HarnessStepResult } from "#harness/step-hooks.js";
+import { throwIfTurnAborted } from "#harness/turn-cancellation.js";
+import {
+ type HarnessToolMap,
+ requireSessionModelReference,
+ type StepResult,
+} from "#harness/types.js";
+import type { InstrumentationAttempt } from "#instrumentation/runtime.js";
+import { ModelCaller } from "./call.js";
+import type { EndsTurnTools } from "./tools.js";
+import { reportModelCallFailure } from "./failure.js";
+import { resolveEffectiveRuntimeModel } from "./model.js";
+import { recoverModelCall } from "./recovery.js";
+import { recordModelUsage } from "./usage.js";
+
+/** A model step's response, for the session to act on. */
+export interface ModelResponse {
+ readonly coordinationTools: HarnessToolMap;
+ /** How many prompt messages the model read, when no client context was spliced in. */
+ readonly durableModelPromptMessageCount?: number;
+ /** Tools that can end the turn in this step, with their `endsTurn` option. */
+ readonly endsTurnTools: EndsTurnTools;
+ readonly promptMessages: readonly HarnessModelMessage[];
+ readonly requestEnvelopeTokens?: number;
+ readonly result: HarnessStepResult;
+}
+
+/**
+ * One model step of the open turn: the prompt it reads, the model that serves it, and the call
+ * with its retries and recoveries. `onResponse` decides what the session does with the response.
+ *
+ * Approved work runs where the AI SDK ran it, between the step's start and the model call:
+ * approved workflow calls join their runs, the budget gate passes, then approved local calls run
+ * and the model reads their results.
+ */
+export async function runModelStep(
+ step: Step,
+ input: {
+ readonly onResponse: (response: ModelResponse) => Promise<StepResult>;
+ readonly turn: TurnInput;
+ readonly approved: ApprovedWork;
+ readonly generation: GenerationSteering;
+ /** A child's caller and a schedule hear only the turn's real end. */
+ readonly hidesHeldText: boolean;
+ /** The attempt the step's events belong to, for instrumentation. */
+ readonly setAttemptScope: (scope: InstrumentationAttempt | undefined) => void;
+ },
+): Promise<StepResult> {
+ const { generation } = input;
+ const approves = hasApprovedWork(step);
+ let prompt = approves ? previewPrompt(step, input.turn) : await buildPrompt(step, input.turn);
+ const model = await selectModel(step, prompt);
+ if (!("model" in model)) return model.failed;
+
+ const start = (messages: readonly ModelMessage[]) =>
+ step.apply(
+ startStep(step.view(), { modelId: requireSessionModelReference(step.session).id }),
+ messages,
+ );
+ let projectedMessages = projectPrompt(step, prompt);
+ try {
+ await start(projectedMessages);
+ } catch (error) {
+ return failBoundaryEvent(step, error);
+ }
+ // The turn waits on the runtime for the runs approved calls joined.
+ if (approves && (await dispatchApprovedWorkflows(step, input.approved))) {
+ return { next: null, session: step.session };
+ }
+ // Over budget, neither approved calls nor the model run: the step's messages park with the
+ // prompt.
+ const overBudget = await enforceBudget(step, prompt.messages);
+ if (overBudget !== undefined) return overBudget;
+ if (approves) {
+ const held = await runApprovedLocalCalls(step, input.approved, input.setAttemptScope);
+ if (held !== undefined) return held;
+ prompt = await buildPrompt(step, input.turn);
+ projectedMessages = projectPrompt(step, prompt);
+ }
+ const { approvedTools, pendingApprovalsNote } = humanInputContext(step);
+ const caller = new ModelCaller(step, prompt, {
+ approvedTools,
+ generation,
+ hidesHeldText: input.hidesHeldText,
+ model: model.model,
+ pendingApprovalsNote,
+ projectedMessages,
+ setAttemptScope: input.setAttemptScope,
+ startStep: start,
+ turnMessages: input.turn.messages,
+ });
+
+ let result: HarnessStepResult;
+ try {
+ result = await caller.call({ suppressStepStartedEmission: true });
+ } catch (error) {
+ caller.throwIfCompactionFailed();
+ throwIfTurnAborted(step.config.abortSignal);
+ if (generation.interrupted) return caller.steered();
+ const recovery = await recoverModelCall({
+ call: (options) => caller.call(options),
+ error,
+ sessionId: step.session.sessionId,
+ turnId: step.position().turnId,
+ });
+ caller.throwIfCompactionFailed();
+ throwIfTurnAborted(step.config.abortSignal);
+ if (generation.interrupted) return caller.steered();
+ if (!("result" in recovery)) return reportModelCallFailure(step, recovery.error);
+ result = recovery.result;
+ }
+
+ await recordModelUsage(step, { model: model.model, result });
+ caller.clearInterruptedUsage();
+
+ let stepResult: StepResult;
+ try {
+ generation.check();
+ stepResult = await input.onResponse({
+ coordinationTools: caller.tools?.coordinationTools ?? step.config.tools,
+ // Usage measures what the model read only when no client context was spliced in.
+ durableModelPromptMessageCount:
+ prompt.clientContext === undefined || prompt.clientContext.messages.length === 0
+ ? caller.modelMessages.length
+ : undefined,
+ endsTurnTools: caller.tools?.endsTurnTools ?? new Map(),
+ promptMessages: caller.request.history,
+ requestEnvelopeTokens: caller.requestEnvelopeTokens,
+ result,
+ });
+ } catch (error) {
+ throwIfTurnAborted(step.config.abortSignal);
+ if (generation.interrupted) return caller.steered();
+ throw error;
+ }
+ // The returned session now owns these messages; persist their baseline with it.
+ step.ctx?.set(HistoryStateKey, caller.request.historyState);
+ return stepResult;
+}
+
+/**
+ * The model that serves the step: a dynamic model resolver picks it from the prompt, or the
+ * agent's model serves. No model fails the session.
+ */
+async function selectModel(
+ step: Step,
+ prompt: Prompt,
+): Promise<{ readonly model: LanguageModel } | { readonly failed: StepResult }> {
+ const { config, ctx } = step;
+ try {
+ if (ctx !== undefined && config.dispatchDynamicModelEvent !== undefined) {
+ const position = step.position();
+ await config.dispatchDynamicModelEvent({
+ ctx,
+ event: stepStartedForResolvers({
+ modelId: step.session.agent.modelReference?.id ?? "dynamic",
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: activeTurnId(position),
+ }),
+ messages: validateHarnessModelMessages(step.projectHistory(withClientContext(prompt))),
+ });
+ }
+ const resolved = await resolveEffectiveRuntimeModel({ config, ctx, session: step.session });
+ step.session = resolved.session;
+ return { model: resolved.model };
+ } catch (error) {
+ return { failed: await failModelSelection(step, error) };
+ }
+}
diff --git a/packages/eve/src/harness/model-call/tools.ts b/packages/eve/src/harness/model-call/tools.ts
new file mode 100644
index 000000000..75683b698
--- /dev/null
+++ b/packages/eve/src/harness/model-call/tools.ts
@@ -0,0 +1,187 @@
+import { resolveModelProvider } from "#internal/gateway.js";
+import type { ToolSet } from "ai";
+
+import { buildDynamicTools } from "#context/build-dynamic-tools.js";
+import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
+import { withTaskTools } from "#execution/tasks/model-step.js";
+import { getAdvertisedTools } from "#harness/advertised-tools.js";
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import { buildFinalOutputTool, FINAL_OUTPUT_TOOL_NAME } from "#harness/final-output.js";
+import type { GenerationSteering } from "#harness/generation-steering.js";
+import { type AnthropicCacheMarker, applyLastToolCacheBreakpoint } from "#harness/prompt-cache.js";
+import type { Step } from "#harness/step/context.js";
+import { buildToolSetFromDefinitions, buildToolSetWithProviderTools } from "#harness/tools.js";
+import { isTurnCancellation } from "#harness/turn-cancellation.js";
+import { type HarnessToolMap, requireSessionModelReference } from "#harness/types.js";
+import { createLogger, logError } from "#internal/logging.js";
+import { toModelSchema } from "#tools/schema.js";
+
+const log = createLogger("harness.tool-loop");
+
+/** The tools one model call offers, and the views of them the step reads afterwards. */
+export interface ModelTools {
+ /** What the AI SDK receives. */
+ readonly effectiveTools: ToolSet;
+ readonly modelTools: ToolSet;
+ /** Every tool the model can call, by name, for presenting its calls. */
+ readonly presentationTools: HarnessToolMap;
+ /** The advertised harness tools; they decide which calls defer to the runtime. */
+ readonly coordinationTools: HarnessToolMap;
+ /** Tools that can end the turn, with their `endsTurn` option. */
+ readonly endsTurnTools: EndsTurnTools;
+}
+
+/**
+ * Assembles the tools one model call offers: authored and dynamic subagent tools, task tools,
+ * provider tools, dynamic tools (which override a same-named authored tool), and `final_output`
+ * when the turn asks for a structured result.
+ */
+export async function prepareModelTools(
+ step: Step,
+ input: {
+ readonly approvedTools: ReadonlySet<string>;
+ readonly model: import("ai").LanguageModel;
+ readonly disabledProviderTools?: ReadonlySet<string>;
+ readonly generation: GenerationSteering;
+ readonly marker: AnthropicCacheMarker | undefined;
+ },
+): Promise<ModelTools> {
+ const { ctx } = step;
+ const { approvedTools, disabledProviderTools, marker } = input;
+ const coordinationTools = withTaskTools(
+ getAdvertisedTools({
+ session: step.session,
+ tools: buildHarnessToolsWithDynamicSubagents(step.config.tools, ctx),
+ }),
+ );
+
+ const flatTools = await buildToolSetWithProviderTools({
+ approvedTools,
+ disabledProviderTools,
+ modelProvider: resolveModelProvider(input.model),
+ modelReference: requireSessionModelReference(step.session),
+ tools: coordinationTools,
+ });
+
+ // Stream emitters resolve label callbacks by tool name, so they need the
+ // dynamic tools the model can call, not only the authored ones.
+ const presentationTools = new Map(coordinationTools);
+ if (ctx !== undefined) {
+ const dynamicTools = getAdvertisedTools({
+ session: step.session,
+ tools: buildDynamicTools(ctx),
+ });
+ const dynamicToolSet = buildToolSetFromDefinitions({
+ approvedTools,
+ disabledProviderTools,
+ tools: dynamicTools,
+ });
+ for (const [name, toolDefinition] of Object.entries(dynamicToolSet)) {
+ if (coordinationTools.get(name)?.workflowId !== undefined) {
+ throw new Error(
+ `Dynamic tool "${name}" collides with a coordination-visible deferred tool.`,
+ );
+ }
+ flatTools[name] = toolDefinition;
+ }
+ // Match `buildToolSetFromDefinitions`: the first dynamic definition of a
+ // name (step, then turn, then session) wins, and still overrides authored.
+ const presentedDynamicNames = new Set<string>();
+ for (const tool of dynamicTools) {
+ if (presentedDynamicNames.has(tool.name)) continue;
+ presentedDynamicNames.add(tool.name);
+ presentationTools.set(tool.name, tool);
+ }
+ }
+
+ if (step.session.outputSchema !== undefined) {
+ flatTools[FINAL_OUTPUT_TOOL_NAME] = buildFinalOutputTool(step.session.outputSchema);
+ }
+
+ const advertised = await getAdvertisedTools({
+ modelTools: flatTools,
+ session: step.session,
+ tools: coordinationTools,
+ });
+ step.session = advertised.session;
+ const { modelTools } = advertised;
+ // `endsTurn` applies only in root, unstructured turns. Only a literal
+ // `true` is described to the model; a function decides from each result.
+ const endsTurnTools = new Map<string, NonNullable<HarnessToolDefinition["endsTurn"]>>();
+ if (!step.hasDelegatedCaller && step.session.outputSchema === undefined) {
+ for (const [name, modelTool] of Object.entries(modelTools)) {
+ const endsTurn = presentationTools.get(name)?.endsTurn;
+ if (modelTool.type === "provider" || endsTurn === undefined || endsTurn === false) continue;
+ endsTurnTools.set(name, endsTurn);
+ if (endsTurn === true) {
+ modelTool.description =
+ `${modelTool.description ?? ""}\n\n${ENDS_TURN_TOOL_NOTE}`.trimStart();
+ }
+ }
+ }
+
+ const effectiveTools = marker ? applyLastToolCacheBreakpoint(modelTools, marker) : modelTools;
+ for (const tool of Object.values(effectiveTools)) {
+ // Whatever produced this tool, the AI SDK must only receive its own
+ // schema type; see toModelSchema.
+ tool.inputSchema = toModelSchema(tool.inputSchema, "input");
+ if (tool.outputSchema !== undefined) {
+ tool.outputSchema = toModelSchema(tool.outputSchema, "output");
+ }
+ const execute = tool.execute;
+ if (execute !== undefined) {
+ tool.execute = (...args) => {
+ input.generation.protectToolExecution();
+ return execute(...args);
+ };
+ }
+ }
+
+ step.frameworkToolNames = new Set(
+ [...presentationTools].filter(([, tool]) => tool.frameworkTool === true).map(([name]) => name),
+ );
+ return { coordinationTools, effectiveTools, endsTurnTools, modelTools, presentationTools };
+}
+
+/**
+ * Wired as the agent's `onToolExecutionEnd`. On the `tool-error` branch
+ * the `error` is still the original throwable (stack/cause intact),
+ * unlike the message-only `tool-error` part the model later sees.
+ */
+export function logToolExecutionError(event: {
+ readonly toolCall: { readonly toolName: string; readonly toolCallId: string };
+ readonly toolOutput: { readonly type: string; readonly error?: unknown };
+}): void {
+ // A tool unwinding because its turn was cancelled is the expected outcome
+ // of a user action, not a failure worth an error log.
+ if (event.toolOutput.type !== "tool-error" || isTurnCancellation(event.toolOutput.error)) {
+ return;
+ }
+ logError(log, "tool execution failed", event.toolOutput.error, {
+ toolName: event.toolCall.toolName,
+ toolCallId: event.toolCall.toolCallId,
+ });
+}
+
+function buildHarnessToolsWithDynamicSubagents(
+ tools: HarnessToolMap,
+ ctx: Parameters<typeof buildDynamicSubagentTools>[0] | undefined,
+): HarnessToolMap {
+ const effectiveTools = new Map(tools);
+ if (ctx === undefined) return effectiveTools;
+ for (const dynamicSubagent of buildDynamicSubagentTools(ctx)) {
+ if (effectiveTools.has(dynamicSubagent.name)) {
+ throw new Error(
+ `Dynamic subagent "${dynamicSubagent.name}" collides with another runtime-visible tool name.`,
+ );
+ }
+ effectiveTools.set(dynamicSubagent.name, dynamicSubagent);
+ }
+ return effectiveTools;
+}
+
+/** Appended to the model-facing description of every tool with `endsTurn: true`. */
+export const ENDS_TURN_TOOL_NOTE =
+ "Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.";
+
+export type EndsTurnTools = ReadonlyMap<string, NonNullable<HarnessToolDefinition["endsTurn"]>>;
diff --git a/packages/eve/src/harness/model-call/usage.ts b/packages/eve/src/harness/model-call/usage.ts
new file mode 100644
index 000000000..4f5b47188
--- /dev/null
+++ b/packages/eve/src/harness/model-call/usage.ts
@@ -0,0 +1,92 @@
+import type { LanguageModel, ProviderMetadata } from "ai";
+
+import type { HarnessStepResult } from "#harness/step-hooks.js";
+import {
+ accumulateTurnUsage,
+ getTurnUsageState,
+ setTurnUsageState,
+ type TokenUsageDelta,
+} from "#harness/turn-tag-state.js";
+import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
+import type { Step } from "#harness/step/context.js";
+import { setEveAttributes } from "#runtime/attributes/emit.js";
+/**
+ * The model's gateway id, or `undefined` for a model without a string `provider`, such as a
+ * test double, so a missing field never throws into the tool loop.
+ */
+export function gatewayModelId(model: LanguageModel): string | undefined {
+ try {
+ return formatLanguageModelGatewayId(model);
+ } catch {
+ return undefined;
+ }
+}
+
+export function extractTokenUsageDelta(input: {
+ readonly costUsd: number | undefined;
+ readonly usage: HarnessStepResult["usage"] | undefined;
+}): TokenUsageDelta | undefined {
+ const usage = input.usage;
+ if (usage === undefined && input.costUsd === undefined) {
+ return undefined;
+ }
+
+ return {
+ cacheReadTokens: usage?.inputTokenDetails?.cacheReadTokens,
+ cacheWriteTokens: usage?.inputTokenDetails?.cacheWriteTokens,
+ costUsd: input.costUsd,
+ inputTokens: usage?.inputTokens,
+ outputTokens: usage?.outputTokens,
+ };
+}
+
+export function extractGatewayCostUsd(
+ providerMetadata: ProviderMetadata | undefined,
+): number | undefined {
+ const gateway = readGatewayMetadata(providerMetadata);
+ const cost = gateway?.cost;
+ if (typeof cost === "number" && Number.isFinite(cost)) {
+ return cost;
+ }
+ if (typeof cost === "string") {
+ const parsed = Number(cost);
+ return Number.isFinite(parsed) ? parsed : undefined;
+ }
+ return undefined;
+}
+
+function readGatewayMetadata(
+ providerMetadata: ProviderMetadata | undefined,
+): ProviderMetadata[string] | undefined {
+ const gateway = providerMetadata?.gateway;
+ return gateway && typeof gateway === "object" && !Array.isArray(gateway) ? gateway : undefined;
+}
+
+/**
+ * Tags the turn's workflow run with the model and the turn's running token totals. Each model
+ * step is its own workflow step and attributes are last-write-wins, so the running total, kept in
+ * session state, is what reaches the dashboard. Best-effort: tagging never breaks the loop.
+ */
+export async function recordModelUsage(
+ step: Step,
+ input: { readonly model: LanguageModel; readonly result: HarnessStepResult },
+): Promise<void> {
+ const usage = accumulateTurnUsage({
+ previous: getTurnUsageState(step.session.state),
+ turnId: step.position().turnId,
+ usage: extractTokenUsageDelta({
+ costUsd: extractGatewayCostUsd(input.result.providerMetadata),
+ usage: input.result.usage,
+ }),
+ });
+ step.session = setTurnUsageState(step.session, usage);
+ await setEveAttributes({
+ "$eve.model": gatewayModelId(input.model),
+ "$eve.input_tokens": usage.inputTokens,
+ "$eve.output_tokens": usage.outputTokens,
+ "$eve.cache_read_tokens": usage.cacheReadTokens,
+ "$eve.cache_write_tokens": usage.cacheWriteTokens,
+ "$eve.cost_usd": usage.sawCost ? usage.costUsd : undefined,
+ "$eve.tool_count": step.config.tools.size,
+ });
+}
diff --git a/packages/eve/src/harness/nested-actions.ts b/packages/eve/src/harness/nested-actions.ts
index 3e74379d3..7b6935009 100644
--- a/packages/eve/src/harness/nested-actions.ts
+++ b/packages/eve/src/harness/nested-actions.ts
@@ -1,6 +1,6 @@
import { contextStorage, type ContextContainer } from "#context/container.js";
import { ContextKey } from "#context/key.js";
-import type { HarnessEmissionState } from "#harness/emission-state.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import type { HarnessEmitFn } from "#harness/types.js";
import { createRuntimeToolResultFromValue } from "#harness/action-result-helpers.js";
import { createActionResultEvent, createActionsRequestedEvent } from "#protocol/message.js";
@@ -46,7 +46,7 @@ export function reportNestedToolAction(parentCallId: string, action: NestedToolA
*/
export async function emitNestedToolActions(
emitFn: HarnessEmitFn,
- state: Pick<HarnessEmissionState, "sequence" | "stepIndex" | "turnId">,
+ state: Pick<TurnPosition, "sequence" | "stepIndex" | "turnId">,
parentCallId: string,
): Promise<void> {
const ctx = contextStorage.getStore() as ContextContainer | undefined;
diff --git a/packages/eve/src/harness/pending-input-batches.test.ts b/packages/eve/src/harness/pending-input-batches.test.ts
deleted file mode 100644
index bb34cec5f..000000000
--- a/packages/eve/src/harness/pending-input-batches.test.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import type { InputRequest } from "#shared/input.js";
-import { resolvePendingInput } from "#harness/input-requests.js";
-import { appendPendingInputBatch, getPendingInputBatches } from "#harness/pending-input-batches.js";
-import type { HarnessSession } from "#harness/types.js";
-
-const DUPLICATE_ID_ERROR =
- 'Internal pending input invariant violated: requestId must be unique across all pending batches: "duplicate".';
-
-function session(state?: HarnessSession["state"]): HarnessSession {
- return {
- agent: { modelReference: {} as never, system: "", tools: [] },
- compaction: { recentWindowSize: 10, threshold: 0.8 },
- continuationToken: "test",
- history: [],
- sessionId: "session-1",
- state,
- };
-}
-
-function approval(requestId: string, callId: string): InputRequest {
- return {
- action: { callId, input: {}, kind: "tool-call", toolName: "bash" },
- kind: "tool-approval",
- prompt: "Approve bash",
- requestId,
- };
-}
-
-function question(requestId: string, callId: string): InputRequest {
- return {
- action: { callId, input: {}, kind: "tool-call", toolName: "ask_question" },
- display: "text",
- kind: "question",
- prompt: "Which option?",
- requestId,
- };
-}
-
-describe("pending input request ID uniqueness", () => {
- it("rejects duplicate IDs within a newly appended batch", () => {
- expect(() =>
- appendPendingInputBatch({
- requests: [approval("duplicate", "call-1"), question("duplicate", "call-2")],
- responseMessages: [],
- session: session(),
- }),
- ).toThrow(DUPLICATE_ID_ERROR);
- });
-
- it("rejects an approval/question ID collision across newly appended batches", () => {
- const first = appendPendingInputBatch({
- requests: [approval("duplicate", "call-1")],
- responseMessages: [],
- session: session(),
- });
-
- expect(() =>
- appendPendingInputBatch({
- requests: [question("duplicate", "call-2")],
- responseMessages: [],
- session: first,
- }),
- ).toThrow(DUPLICATE_ID_ERROR);
- });
-
- it("rejects duplicate IDs in a persisted batch collection", () => {
- const persisted = session({
- "eve.runtime.pendingInputBatches": [
- { requests: [approval("duplicate", "call-1")], responseMessages: [] },
- { requests: [question("duplicate", "call-2")], responseMessages: [] },
- ],
- });
-
- expect(() =>
- resolvePendingInput({
- session: persisted,
- stepInput: { inputResponses: [{ optionId: "approve", requestId: "duplicate" }] },
- }),
- ).toThrow(DUPLICATE_ID_ERROR);
- });
-
- it("rejects duplicate IDs in a persisted legacy singleton", () => {
- const persisted = session({
- "eve.runtime.pendingInputBatch": {
- requests: [question("duplicate", "call-1"), question("duplicate", "call-2")],
- responseMessages: [],
- },
- });
-
- expect(() => getPendingInputBatches(persisted.state)).toThrow(DUPLICATE_ID_ERROR);
- });
-});
-
-describe("persisted pending input validation", () => {
- it("rejects an unknown request kind", () => {
- const persisted = session({
- "eve.runtime.pendingInputBatches": [
- {
- requests: [
- {
- ...question("unknown-kind", "call-unknown"),
- kind: "future-input-kind",
- },
- ],
- responseMessages: [],
- },
- ],
- });
-
- expect(() => resolvePendingInput({ session: persisted })).toThrow(
- "Unhandled pending input request kind: future-input-kind",
- );
- });
-});
diff --git a/packages/eve/src/harness/pending-input-batches.ts b/packages/eve/src/harness/pending-input-batches.ts
deleted file mode 100644
index 688e47eea..000000000
--- a/packages/eve/src/harness/pending-input-batches.ts
+++ /dev/null
@@ -1,265 +0,0 @@
-import type { ModelMessage } from "ai";
-
-import { contextStorage } from "#context/container.js";
-import type { SessionAuthContext } from "#channel/types.js";
-import { AuthKey, SessionKey } from "#context/keys.js";
-import type { InputRequest } from "#shared/input.js";
-import type { HarnessSession, SessionStateMap, StepInput } from "#harness/types.js";
-import { coalesceTurnInputs } from "#harness/messages.js";
-
-const PENDING_INPUT_BATCHES_KEY = "eve.runtime.pendingInputBatches";
-/** Pre-collection singleton key; read once for sessions parked before the upgrade. */
-const LEGACY_PENDING_INPUT_BATCH_KEY = "eve.runtime.pendingInputBatch";
-const DEFERRED_STEP_INPUT_KEY = "eve.runtime.deferredStepInput";
-const DUPLICATE_REQUEST_ID_MESSAGE =
- "Internal pending input invariant violated: requestId must be unique across all pending batches";
-
-/**
- * Stream-emit coordinates carried so a parked batch's resolution can attribute
- * its events to the turn and step that requested the input.
- */
-export interface PendingInputBatchEvent {
- readonly sequence: number;
- readonly stepIndex: number;
- readonly turnId: string;
-}
-
-/**
- * Serializable pending input batch stored on the session state: one parked
- * assistant turn's requests plus its withheld model output.
- */
-export interface PendingInputBatch {
- readonly event?: PendingInputBatchEvent;
- readonly requests: readonly InputRequest[];
- /**
- * Auth of the caller whose turn parked the batch, captured when it parked;
- * `null` when that caller was unauthenticated.
- */
- readonly requester?: SessionAuthContext | null;
- readonly responseAuthRequiredRequestIds?: readonly string[];
- readonly responseMessages: readonly ModelMessage[];
-}
-
-/**
- * Returns true when the session holds at least one pending HITL batch
- * (tool approvals or a session-limit continuation prompt).
- */
-export function hasPendingInputBatch(state: SessionStateMap | undefined): boolean {
- return getPendingInputBatches(state).length > 0;
-}
-
-/**
- * Returns the request IDs across every pending HITL batch.
- */
-export function getPendingInputRequestIds(state: SessionStateMap | undefined): ReadonlySet<string> {
- return new Set(
- getPendingInputBatches(state).flatMap((batch) =>
- batch.requests.map((request) => request.requestId),
- ),
- );
-}
-
-function coercePendingInputBatch(value: unknown): PendingInputBatch | undefined {
- if (typeof value !== "object" || value === null) {
- return undefined;
- }
-
- const batch = value as PendingInputBatch;
-
- if (!Array.isArray(batch.requests) || !Array.isArray(batch.responseMessages)) {
- return undefined;
- }
-
- return batch;
-}
-
-/**
- * Reads the ordered pending batches. Sessions parked before the collection
- * shape carry the legacy singleton key; it reads as a one-element list and
- * is rewritten to the list shape on the next batch write.
- */
-export function getPendingInputBatches(
- state: SessionStateMap | undefined,
-): readonly PendingInputBatch[] {
- const value = state?.[PENDING_INPUT_BATCHES_KEY];
- if (Array.isArray(value)) {
- const batches = value
- .map((entry) => coercePendingInputBatch(entry))
- .filter((batch): batch is PendingInputBatch => batch !== undefined);
- assertUniqueRequestIds(batches);
- return batches;
- }
-
- const legacy = coercePendingInputBatch(state?.[LEGACY_PENDING_INPUT_BATCH_KEY]);
- const batches = legacy === undefined ? [] : [legacy];
- assertUniqueRequestIds(batches);
- return batches;
-}
-
-function assertUniqueRequestIds(batches: readonly PendingInputBatch[]): void {
- const requestIds = new Set<string>();
- for (const batch of batches) {
- for (const request of batch.requests) {
- if (requestIds.has(request.requestId)) {
- throw new TypeError(
- `${DUPLICATE_REQUEST_ID_MESSAGE}: ${JSON.stringify(request.requestId)}.`,
- );
- }
- requestIds.add(request.requestId);
- }
- }
-}
-
-/**
- * Removes the given batches (matched by identity from a prior
- * {@link getPendingInputBatches} read) and keeps every other batch open.
- *
- * Removal is the only exported way to shrink the collection: a wholesale
- * setter would reintroduce the overwrite hazard the collection exists to
- * prevent — a writer clobbering batches it never resolved.
- */
-export function removePendingInputBatches(
- session: HarnessSession,
- batches: readonly PendingInputBatch[],
-): HarnessSession {
- const removed = new Set(batches);
- return setPendingInputBatches(
- session,
- getPendingInputBatches(session.state).filter((batch) => !removed.has(batch)),
- );
-}
-
-function setPendingInputBatches(
- session: HarnessSession,
- batches: readonly PendingInputBatch[],
-): HarnessSession {
- assertUniqueRequestIds(batches);
- const state = { ...session.state };
- delete state[LEGACY_PENDING_INPUT_BATCH_KEY];
- if (batches.length === 0) {
- delete state[PENDING_INPUT_BATCHES_KEY];
- } else {
- state[PENDING_INPUT_BATCHES_KEY] = batches.map((batch) => ({
- event: batch.event,
- requester: batch.requester,
- responseAuthRequiredRequestIds: batch.responseAuthRequiredRequestIds,
- requests: [...batch.requests],
- responseMessages: [...batch.responseMessages],
- }));
- }
-
- return { ...session, state: Object.keys(state).length > 0 ? state : undefined };
-}
-
-/**
- * Appends one pending HITL batch for a parked assistant turn. Earlier
- * batches stay open and independently answerable.
- */
-export function appendPendingInputBatch(input: {
- readonly event?: PendingInputBatchEvent;
- readonly requests: readonly InputRequest[];
- readonly responseAuthRequiredRequestIds?: readonly string[];
- readonly responseMessages: readonly ModelMessage[];
- readonly session: HarnessSession;
-}): HarnessSession {
- return setPendingInputBatches(input.session, [
- ...getPendingInputBatches(input.session.state),
- {
- event: input.event,
- requester: currentRequester(),
- responseAuthRequiredRequestIds: input.responseAuthRequiredRequestIds,
- requests: input.requests,
- responseMessages: input.responseMessages,
- },
- ]);
-}
-
-/**
- * Every anonymous caller shares one synthetic identity, so an anonymous
- * requester can't be told apart from another anonymous responder: record none.
- */
-function currentRequester(): SessionAuthContext | null {
- const context = contextStorage.getStore();
- const auth = context?.get(AuthKey) ?? context?.get(SessionKey)?.auth.current ?? null;
- return auth?.principalType === "anonymous" ? null : auth;
-}
-
-/** The requester recorded on the pending batch that holds `requestId`. */
-export function pendingInputRequester(
- state: SessionStateMap | undefined,
- requestId: string,
-): SessionAuthContext | null {
- const batch = getPendingInputBatches(state).find((candidate) =>
- candidate.requests.some((request) => request.requestId === requestId),
- );
- return batch?.requester ?? null;
-}
-
-// ---------------------------------------------------------------------------
-// Deferred step input
-// ---------------------------------------------------------------------------
-
-/**
- * Merges any queued follow-up input into the current step input and clears it
- * from session state.
- *
- * Used when the harness has to process a pending tool-approval response first
- * and defer the user's new message to the next internal model step.
- */
-export function consumeDeferredStepInput(input: {
- readonly input?: StepInput;
- readonly session: HarnessSession;
-}): {
- readonly input?: StepInput;
- readonly session: HarnessSession;
-} {
- const deferredInput = getDeferredStepInput(input.session);
-
- if (deferredInput === undefined) {
- return input;
- }
-
- const session = clearDeferredStepInput(input.session);
-
- if (input.input === undefined) {
- return {
- input: deferredInput,
- session,
- };
- }
-
- return {
- input: coalesceTurnInputs(deferredInput, input.input),
- session,
- };
-}
-
-export function getDeferredStepInput(session: HarnessSession): StepInput | undefined {
- return session.state?.[DEFERRED_STEP_INPUT_KEY] as StepInput | undefined;
-}
-
-export function queueDeferredStepInput(session: HarnessSession, input: StepInput): HarnessSession {
- const existing = getDeferredStepInput(session);
- const deferredInput = existing === undefined ? input : coalesceTurnInputs(existing, input);
- const state = { ...session.state };
- state[DEFERRED_STEP_INPUT_KEY] = deferredInput;
-
- return {
- ...session,
- state,
- };
-}
-
-function clearDeferredStepInput(session: HarnessSession): HarnessSession {
- if (session.state?.[DEFERRED_STEP_INPUT_KEY] === undefined) {
- return session;
- }
-
- const state = { ...session.state };
- delete state[DEFERRED_STEP_INPUT_KEY];
-
- return {
- ...session,
- state: Object.keys(state).length > 0 ? state : undefined,
- };
-}
diff --git a/packages/eve/src/harness/proxy-input-requests.ts b/packages/eve/src/harness/proxy-input-requests.ts
index bcb9f640f..3efb26d72 100644
--- a/packages/eve/src/harness/proxy-input-requests.ts
+++ b/packages/eve/src/harness/proxy-input-requests.ts
@@ -1,5 +1,5 @@
import type { SubagentInputRequestHookPayload } from "#channel/types.js";
-import type { PendingInputBatchEvent } from "#harness/pending-input-batches.js";
+import type { StepCoordinates as PendingInputBatchEvent } from "#harness/session-machine/view.js";
import type { HarnessSessionBase, SessionStateMap } from "#harness/types.js";
import { inputOptionSchema, type InputOption, type InputRequestKind } from "#shared/input.js";
import {
@@ -7,7 +7,6 @@ import {
type SessionInboxAddress,
} from "#execution/session-inbox/address.js";
import type { RemoteAgentBinding } from "#eve-channel/support.js";
-import { createInputResolvedEvent, type InputResolvedStreamEvent } from "#protocol/message.js";
const PROXY_INPUT_REQUESTS_KEY = "eve.runtime.proxyInputRequests";
@@ -142,28 +141,15 @@ export function upsertProxyInputRequestState(input: {
return Object.keys(state).length > 0 ? state : undefined;
}
-/**
- * Retires the requests `select` picks, which nobody can answer anymore, and
- * returns the `input.resolved` events that report them `cancelled` so
- * channels stop offering them. Publish the events as relayed.
- */
-export function withdrawProxyInputRequests<T extends { readonly state?: SessionStateMap }>(
+/** Removes every proxy route the predicate selects. */
+export function clearProxyInputRequestsWhere<T extends { readonly state?: SessionStateMap }>(
session: T,
- select: (requestId: string, route: ProxyInputRequest) => boolean,
-): { readonly events: readonly InputResolvedStreamEvent[]; readonly session: T } {
- const requestIds: string[] = [];
- const events: InputResolvedStreamEvent[] = [];
- for (const [requestId, route] of Object.entries(readMap(session.state))) {
- if (!select(requestId, route)) continue;
- requestIds.push(requestId);
- events.push(
- createInputResolvedEvent({
- resolutions: [{ kind: route.kind, outcome: "cancelled", requestId }],
- ...route.event,
- }),
- );
- }
- return { events, session: retireProxyInputRequests(session, requestIds) };
+ select: (route: ProxyInputRequest, requestId: string) => boolean,
+): T {
+ const requestIds = Object.entries(readMap(session.state))
+ .filter(([requestId, route]) => select(route, requestId))
+ .map(([requestId]) => requestId);
+ return retireProxyInputRequests(session, requestIds);
}
/** Removes only the request IDs whose responses were successfully forwarded. */
diff --git a/packages/eve/src/harness/session-limit-enforcement.ts b/packages/eve/src/harness/session-limit-enforcement.ts
deleted file mode 100644
index 84fd35c8e..000000000
--- a/packages/eve/src/harness/session-limit-enforcement.ts
+++ /dev/null
@@ -1,213 +0,0 @@
-/**
- * Session token and token-cost limit policy for the tool-loop harness.
- *
- * Two seams into the harness step:
- *
- * 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 cancel the in-flight turn tree.
- * 2. {@link enforceSessionUsageLimit} runs before each model call and, when
- * the session is over budget, parks it on the deterministic continuation
- * prompt (sessions that can request input) or fails it (nobody can answer
- * the prompt).
- */
-import { createInputRequestedEvent } from "#protocol/message.js";
-import {
- emitFailedStep,
- emitTurnEpilogue,
- setHarnessEmissionState,
- type HarnessEmissionState,
-} from "#harness/emission.js";
-import { appendPendingInputBatch } from "#harness/input-requests.js";
-import type { HarnessModelMessage } from "#harness/messages.js";
-import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
-import { SessionLimitDeclinedError } from "#harness/turn-cancellation.js";
-import {
- bumpSessionRuntimeUsageLimits,
- getSessionUsageLimitViolation,
- getSessionTokenUsage,
- getSessionUsage,
- type SessionUsageLimitViolation,
-} from "#harness/turn-tag-state.js";
-import type { HarnessSession, StepResult, ToolLoopHarnessConfig } from "#harness/types.js";
-
-const SESSION_TOKEN_LIMIT_REACHED_CODE = "SESSION_TOKEN_LIMIT_REACHED";
-const SESSION_TOKEN_COST_LIMIT_REACHED_CODE = "SESSION_TOKEN_COST_LIMIT_REACHED";
-
-interface SessionLimitPolicyInput {
- readonly config: ToolLoopHarnessConfig;
- readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly emissionState: HarnessEmissionState;
- readonly session: HarnessSession;
-}
-
-/**
- * Acts on a resolved session-limit continuation answer.
- *
- * Granted: bumps the runtime token limits via
- * {@link bumpSessionRuntimeUsageLimits} and lets the step continue
- * transparently.
- * 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`.
- */
-export async function applySessionLimitContinuation(
- input: SessionLimitPolicyInput & {
- readonly limitContinuation: { readonly granted: boolean } | undefined;
- },
-): Promise<{ readonly result: StepResult | null; readonly session: HarnessSession }> {
- if (input.limitContinuation === undefined) {
- return { result: null, session: input.session };
- }
-
- if (input.limitContinuation.granted) {
- return { result: null, session: bumpSessionRuntimeUsageLimits(input.session) };
- }
-
- throw new SessionLimitDeclinedError();
-}
-
-/**
- * Pre-model-call gate for the session token budget.
- *
- * Returns `null` when the session is within budget. Over budget, sessions
- * that can request input park on the deterministic continuation prompt;
- * others fail fast with `SESSION_TOKEN_LIMIT_REACHED`.
- */
-export async function enforceSessionUsageLimit(
- input: SessionLimitPolicyInput & { readonly messages: readonly HarnessModelMessage[] },
-): Promise<StepResult | null> {
- const violation = getSessionUsageLimitViolation(input.session);
- if (violation === null) {
- return null;
- }
-
- const { emit } = input;
- // A zero limit is an exhausted quota inherited by a delegated task.
- // Approving would bump the runtime limit by the configured limit -- zero --
- // so fail the child and let its parent reach the resumable limit gate.
- if (
- violationWindow(violation) > 0 &&
- emit !== undefined &&
- input.config.capabilities?.requestInput === true
- ) {
- return parkOnSessionUsageLimit({ ...input, emit, violation });
- }
-
- return failSessionUsageLimit({ ...input, violation });
-}
-
-/**
- * Parks the session on the deterministic HITL continuation prompt. No model
- * call happens: the request is harness-authored, and the parked history
- * carries the step's accumulated messages so the triggering user message
- * survives into the resumed turn.
- */
-async function parkOnSessionUsageLimit(input: {
- readonly config: ToolLoopHarnessConfig;
- readonly emit: NonNullable<ToolLoopHarnessConfig["handleEvent"]>;
- readonly emissionState: HarnessEmissionState;
- readonly messages: readonly HarnessModelMessage[];
- readonly session: HarnessSession;
- readonly violation: SessionUsageLimitViolation;
-}): Promise<StepResult> {
- const request = createSessionLimitContinuationRequest({
- sessionId: input.session.sessionId,
- turnSequence: input.emissionState.sequence,
- violation: input.violation,
- });
- let emissionState = input.emissionState;
-
- const parkedSession = appendPendingInputBatch({
- event: {
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- },
- requests: [request],
- responseMessages: [],
- session: { ...input.session, history: [...input.messages] },
- });
-
- await input.emit(
- createInputRequestedEvent({
- requests: [request],
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
-
- emissionState = await emitTurnEpilogue(
- input.emit,
- emissionState,
- parkedSession.history,
- getSessionUsage(parkedSession),
- );
-
- return {
- next: null,
- session: setHarnessEmissionState(parkedSession, emissionState),
- };
-}
-
-function violationWindow(violation: SessionUsageLimitViolation): number {
- return violation.kind === "token-cost" ? violation.limitUsd : violation.limit;
-}
-
-function formatSessionLimitMessage(kind: SessionUsageLimitViolation["kind"]): string {
- return kind === "token-cost"
- ? "The session reached its configured model token-cost limit."
- : `The session reached its configured ${kind} token limit.`;
-}
-
-async function failSessionUsageLimit(input: {
- readonly config: ToolLoopHarnessConfig;
- readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly emissionState: HarnessEmissionState;
- readonly session: HarnessSession;
- readonly violation: SessionUsageLimitViolation;
-}): Promise<StepResult> {
- const usage = getSessionTokenUsage(input.session);
- const message = formatSessionLimitMessage(input.violation.kind);
- const details: import("#shared/json.js").JsonObject =
- input.violation.kind === "token-cost"
- ? {
- costUsd: usage.costUsd,
- kind: input.violation.kind,
- limitUsd: input.violation.limitUsd,
- usedCostUsd: input.violation.usedCostUsd,
- }
- : {
- inputTokens: usage.inputTokens,
- kind: input.violation.kind,
- limit: input.violation.limit,
- outputTokens: usage.outputTokens,
- usedTokens: input.violation.usedTokens,
- };
-
- if (input.emit) {
- await emitFailedStep(input.emit, input.emissionState, {
- code:
- input.violation.kind === "token-cost"
- ? SESSION_TOKEN_COST_LIMIT_REACHED_CODE
- : SESSION_TOKEN_LIMIT_REACHED_CODE,
- details,
- message,
- sessionId: input.session.sessionId,
- usage: getSessionUsage(input.session),
- });
- }
-
- return {
- next: { done: true, output: "" },
- session: input.session,
- };
-}
diff --git a/packages/eve/src/harness/session-machine/commit.ts b/packages/eve/src/harness/session-machine/commit.ts
new file mode 100644
index 000000000..2237a2641
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/commit.ts
@@ -0,0 +1,111 @@
+import { getSessionUsage } from "#harness/turn-tag-state.js";
+import type { ModelMessage } from "ai";
+
+import {
+ getPendingAuthorization,
+ setPendingAuthorization,
+ type AuthorizationChallenge,
+} from "#harness/authorization.js";
+import {
+ clearProxyInputRequestsWhere,
+ getProxyInputRequests,
+} from "#harness/proxy-input-requests.js";
+import { validateHarnessModelMessages } from "#harness/messages.js";
+import type { HarnessSession, HarnessSessionBase, SessionStateMap } from "#harness/types.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import type { SessionProjection } from "#protocol/session-projection.js";
+import { readTurnState, writeTurnState, type TurnState } from "./state.js";
+import type { SessionView } from "./view.js";
+import { clearPendingAuthorization } from "#harness/authorization.js";
+
+// The save side of the machine. A transition returns the events that report what changed and
+// the execution state that follows; `applyTransition` publishes the events in order (the publish
+// sink folds each into the projection) and writes the rest. Nothing else writes `TurnState`.
+// A private record lives only while the projection shows its owner open, so closing an owner is
+// one event: a transition reports it, and the save drops the record here.
+
+/** What a transition returns. Nothing else changes session state. */
+export interface Transition {
+ readonly turn: TurnState;
+ readonly events: readonly UnstampedMessageStreamEvent[];
+ /** Messages the transition commits to the end of history. */
+ readonly commit?: readonly ModelMessage[];
+ /** The transition empties history, as `clear` does. */
+ readonly clearsHistory?: true;
+ /** Every sign-in the session waits on once the transition applies; `[]` withdraws them all. */
+ readonly signIns?: readonly AuthorizationChallenge[];
+}
+
+/** Publishes one event; `messages` is the conversation hooks see with it. */
+export type Publish = (
+ event: UnstampedMessageStreamEvent,
+ messages?: readonly ModelMessage[],
+) => Promise<void>;
+
+export function sessionView(
+ projection: SessionProjection,
+ state: SessionStateMap | undefined,
+): SessionView {
+ return {
+ projection,
+ relayedRequestIds: new Set(getProxyInputRequests(state).keys()),
+ signIns: getPendingAuthorization(state)?.challenges ?? [],
+ turn: readTurnState(state),
+ usage: getSessionUsage({ state }),
+ };
+}
+
+/**
+ * The events hooks and resolvers read the conversation at: a turn's and a step's boundaries. The
+ * session starts before any history, so `session.started` never carries the turn's input.
+ */
+const READS_HISTORY: ReadonlySet<string> = new Set([
+ "turn.started",
+ "step.started",
+ "turn.completed",
+]);
+
+/**
+ * Publishes a transition's events, then saves what it changed. A transition that changes history
+ * needs a session restored with it.
+ */
+export async function applyTransition<T extends HarnessSessionBase>(
+ session: T,
+ transition: Transition,
+ publish: Publish,
+ messages?: readonly ModelMessage[],
+): Promise<T> {
+ for (const event of transition.events) {
+ await publish(event, READS_HISTORY.has(event.type) ? messages : undefined);
+ }
+ const state =
+ transition.signIns === undefined
+ ? session.state
+ : transition.signIns.length === 0
+ ? clearPendingAuthorization(session.state)
+ : setPendingAuthorization(clearPendingAuthorization(session.state), {
+ challenges: transition.signIns,
+ });
+ const next = writeTurnState({ ...session, state }, transition.turn);
+ const commit = transition.commit ?? [];
+ if (transition.clearsHistory !== true && commit.length === 0) return next;
+ if (!("history" in session)) {
+ throw new Error("A transition that changes history needs the session's history.");
+ }
+ const { history: previous } = session as T & Pick<HarnessSession, "history">;
+ const history = transition.clearsHistory
+ ? []
+ : validateHarnessModelMessages([...previous, ...commit]);
+ return { ...next, history };
+}
+
+/** Drops the private records whose owner the projection shows closed. */
+export function dropClosedRecords<T extends HarnessSessionBase>(
+ session: T,
+ projection: SessionProjection,
+): T {
+ return clearProxyInputRequestsWhere(session, (_route, requestId) => {
+ const input = projection.inputs[requestId];
+ return input === undefined || input.status === "settled";
+ });
+}
diff --git a/packages/eve/src/harness/session-machine/current.ts b/packages/eve/src/harness/session-machine/current.ts
new file mode 100644
index 000000000..5174a86c4
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/current.ts
@@ -0,0 +1,108 @@
+import { contextStorage } from "#context/container.js";
+import type { ContextReader } from "#context/key.js";
+import type { HarnessSessionBase, SessionStateMap } from "#harness/types.js";
+import {
+ foldSession,
+ pruneSessionProjection,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+import type { MessageStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";
+import { SESSION_PROJECTION_STATE_KEY, storedProjection } from "./view.js";
+
+// A step-local holder for the projection as the step publishes. It survives provider scope
+// resets but never serializes with context; the step saves it into session state.
+const liveProjections = new WeakMap<ContextReader, { projection: SessionProjection }>();
+
+export function enterSessionProjection(
+ ctx: ContextReader,
+ state: SessionStateMap | undefined,
+): void {
+ liveProjections.set(ctx, { projection: storedProjection(state) });
+}
+
+/** Enters the stored projection unless this step already did. */
+export function ensureSessionProjection(
+ ctx: ContextReader,
+ state: SessionStateMap | undefined,
+): void {
+ if (!liveProjections.has(ctx)) enterSessionProjection(ctx, state);
+}
+
+/** The projection as of the last event the current step published. */
+export function currentProjection(
+ ctx: ContextReader | undefined = contextStorage.getStore(),
+): SessionProjection {
+ const live = ctx === undefined ? undefined : liveProjections.get(ctx);
+ if (live === undefined) throw new Error("Session lifecycle requires an initialized projection.");
+ return live.projection;
+}
+
+/** The step's live projection, or the session's stored one when no step entered it. */
+export function projectionFor(
+ ctx: ContextReader,
+ state: SessionStateMap | undefined,
+): SessionProjection {
+ return liveProjections.get(ctx)?.projection ?? storedProjection(state);
+}
+
+export function recordPublishedEvent(
+ ctx: ContextReader,
+ event: MessageStreamEvent | UnstampedMessageStreamEvent,
+): void {
+ const live = liveProjections.get(ctx);
+ if (live === undefined)
+ throw new Error("Session publication requires an initialized projection.");
+ const folded = foldSession(live.projection, event);
+ live.projection = event.type === "session.waiting" ? pruneSessionProjection(folded) : folded;
+}
+
+export function saveSessionProjection<T extends HarnessSessionBase>(
+ session: T,
+ ctx: ContextReader,
+): T {
+ return saveProjection(session, currentProjection(ctx));
+}
+
+/**
+ * The session saves the lifecycle its steps read. Calls and tasks are for the stream's readers,
+ * which fold them from the events, and their outputs can be large, so the checkpoint omits them.
+ */
+export function saveProjection<T extends HarnessSessionBase>(
+ session: T,
+ projection: SessionProjection,
+): T {
+ const saved: SessionProjection = { ...projection, calls: {}, tasks: {} };
+ return { ...session, state: { ...session.state, [SESSION_PROJECTION_STATE_KEY]: saved } };
+}
+
+/** The projection one step reads and folds what it publishes into. */
+export interface StepProjection {
+ read(): SessionProjection;
+ /** Folds an event no publish sink folded: the step runs without one. */
+ record(event: UnstampedMessageStreamEvent): void;
+}
+
+/**
+ * A step's projection: the context's live one, which the publish sink folds, or, for a step
+ * that runs without a context, a detached one the step folds itself.
+ */
+export function stepProjection(
+ ctx: ContextReader | undefined,
+ state: SessionStateMap | undefined,
+): StepProjection {
+ if (ctx !== undefined) {
+ ensureSessionProjection(ctx, state);
+ return {
+ read: () => currentProjection(ctx),
+ record: (event) => recordPublishedEvent(ctx, event),
+ };
+ }
+ let projection = storedProjection(state);
+ return {
+ read: () => projection,
+ record(event) {
+ const folded = foldSession(projection, event);
+ projection = event.type === "session.waiting" ? pruneSessionProjection(folded) : folded;
+ },
+ };
+}
diff --git a/packages/eve/src/harness/session-machine/events.ts b/packages/eve/src/harness/session-machine/events.ts
new file mode 100644
index 000000000..1cccb706b
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/events.ts
@@ -0,0 +1,41 @@
+import {
+ createAuthorizationCompletedEvent,
+ createInputResolvedEvent,
+ type AuthorizationCompletedStreamEvent,
+ type InputResolvedStreamEvent,
+} from "#protocol/message.js";
+import type { SessionAuthorization, SessionInput } from "#protocol/session-projection.js";
+
+// Lifecycle event builders for transitions. Each closes something the projection shows open,
+// at the coordinates the projection recorded for it, so readers attach the close to the open.
+
+/** Reports an open request withdrawn: nobody may answer it anymore. */
+export function inputWithdrawn(input: SessionInput): InputResolvedStreamEvent {
+ return createInputResolvedEvent({
+ resolutions: [
+ { kind: input.request.kind, outcome: "cancelled", requestId: input.request.requestId },
+ ],
+ sequence: input.sequence,
+ stepIndex: input.stepIndex,
+ turnId: input.turnId,
+ });
+}
+
+/** Reports an open sign-in withdrawn, as declined: its callback no longer resumes anything. */
+export function signInWithdrawn(
+ attempt: SessionAuthorization,
+ reason: string,
+): AuthorizationCompletedStreamEvent {
+ return createAuthorizationCompletedEvent({
+ attemptId: attempt.attemptId,
+ candidateId: attempt.candidateId,
+ name: attempt.name,
+ outcome: "declined",
+ principalId: attempt.principalId,
+ reason,
+ sequence: attempt.sequence,
+ stepIndex: attempt.stepIndex,
+ taskId: attempt.taskId,
+ turnId: attempt.turnId,
+ });
+}
diff --git a/packages/eve/src/harness/session-machine/machine.test.ts b/packages/eve/src/harness/session-machine/machine.test.ts
new file mode 100644
index 000000000..d92ce265a
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/machine.test.ts
@@ -0,0 +1,690 @@
+import type { ModelMessage } from "ai";
+import { describe, expect, it } from "vitest";
+
+import type { AuthorizationChallenge } from "#harness/authorization.js";
+import type { HarnessSession, StepInput } from "#harness/types.js";
+import { createSessionContract } from "#internal/testing/session-contract.js";
+import {
+ createActionsRequestedEvent,
+ type UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
+import {
+ callStatus,
+ foldSession,
+ initialSessionProjection,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+import type { InputRequest } from "#shared/input.js";
+import { createSessionLimitContinuationRequest } from "#harness/hitl/budget-request.js";
+import {
+ answer,
+ grantedApprovalKeys,
+ parkOnApprovals as parkOnApprovalsTransition,
+ requestLimit,
+ requireSignIn,
+ type ResponsePolicyPass,
+} from "#harness/hitl/approvals.js";
+import { deliver } from "#harness/hitl/delivery.js";
+import { applyTransition, sessionView, type Transition } from "./commit.js";
+import { saveProjection } from "./current.js";
+import {
+ cancel,
+ clear,
+ completeSignIn,
+ hold,
+ receive,
+ relay,
+ settle,
+ suspendStep,
+ startStep,
+ type SettledCall,
+} from "./transitions.js";
+import { storedProjection, suspendedSteps, turnPosition } from "./view.js";
+
+// The session machine's lifecycles, transition by transition. Each test publishes what the
+// transitions return, folds it into the projection as the publish sink does, and checks the
+// stream against what every reader relies on.
+
+function createMachine() {
+ let session: HarnessSession = {
+ agent: { modelReference: { id: "test-model" }, system: "test", tools: [] },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "http:test",
+ history: [],
+ sessionId: "session-test",
+ };
+ let projection: SessionProjection = initialSessionProjection();
+ const contract = createSessionContract();
+ const events: UnstampedMessageStreamEvent[] = [];
+ const publish = async (event: UnstampedMessageStreamEvent) => {
+ events.push(event);
+ expect(contract.observe(event)).toEqual([]);
+ projection = foldSession(projection, event);
+ };
+ return {
+ get events() {
+ return events.map((event) => event.type);
+ },
+ get projection() {
+ return projection;
+ },
+ get session() {
+ return session;
+ },
+ view: () => sessionView(projection, session.state),
+ position: () => turnPosition(projection),
+ async apply<T extends Transition>(transition: T): Promise<T> {
+ session = await applyTransition(session, transition, publish);
+ return transition;
+ },
+ /** What the model step streams as it runs: its calls. */
+ async stream(event: UnstampedMessageStreamEvent) {
+ await publish(event);
+ },
+ eventsSince(count: number) {
+ return events.slice(count);
+ },
+ };
+}
+
+type Machine = ReturnType<typeof createMachine>;
+
+function approval(callId: string, toolName = "deploy"): InputRequest {
+ return {
+ action: { callId, input: { service: "api" }, kind: "tool-call", toolName },
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "cancel", label: "Cancel" },
+ ],
+ prompt: `Approve tool call: ${toolName}`,
+ requestId: `approval-${callId}`,
+ };
+}
+
+function callMessage(...callIds: string[]): ModelMessage {
+ return {
+ content: callIds.flatMap((callId) => [
+ {
+ input: { service: "api" },
+ toolCallId: callId,
+ toolName: "deploy",
+ type: "tool-call" as const,
+ },
+ ]),
+ role: "assistant",
+ };
+}
+
+function result(callId: string, value = "ok"): SettledCall {
+ return {
+ part: {
+ output: { type: "text", value },
+ toolCallId: callId,
+ toolName: "deploy",
+ type: "tool-result",
+ },
+ };
+}
+
+const noPolicy = (stepInput?: StepInput): ResponsePolicyPass => ({
+ audit: { activeCandidates: [], candidateHistory: [], settlements: [] },
+ challenges: [],
+ challengesAtStart: [],
+ feedback: [],
+ kind: "continue",
+ stepInput,
+});
+
+/** Answers through `deliver` and `answer`, as the tool loop does with no response policy. */
+async function respond(machine: Machine, input: StepInput) {
+ const delivered = deliver(machine.view(), input, { takeQueued: true });
+ return machine.apply(
+ answer(machine.view(), {
+ approvalKey: () => undefined,
+ delivery: delivered.input,
+ policy: noPolicy(delivered.input),
+ takeQueued: delivered.takeQueued,
+ }),
+ );
+}
+
+/** A turn whose model step called `callIds`, each needing approval. */
+async function parkOnApprovals(machine: Machine, ...callIds: string[]) {
+ await machine.apply(receive(machine.view(), { message: "Deploy the API." }));
+ await machine.apply(startStep(machine.view(), { modelId: "test-model" }));
+ const position = machine.position();
+ await machine.stream(
+ createActionsRequestedEvent({
+ actions: callIds.map((callId) => ({
+ callId,
+ input: { service: "api" },
+ kind: "tool-call",
+ toolName: "deploy",
+ })),
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ }),
+ );
+ const parked = await machine.apply(
+ park(machine.view(), {
+ event: {
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ },
+ messages: [callMessage(...callIds)],
+ requests: callIds.map((callId) => approval(callId)),
+ tasks: [],
+ }),
+ );
+ // The seam holds the turn for the answers.
+ await machine.apply(hold(machine.view(), { on: "input" }));
+ return parked;
+}
+
+describe("session machine", () => {
+ it("parks a step on its approvals, holds the turn, and resumes it when the call runs", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+
+ expect(machine.events).toEqual([
+ "session.started",
+ "turn.started",
+ "message.received",
+ "step.started",
+ "actions.requested",
+ "input.requested",
+ "turn.waiting",
+ ]);
+ expect(machine.projection.activeTurnId).toBe("turn_0");
+ expect(callStatus(machine.projection, "call-1")).toBe("awaiting-input");
+ // The response waits outside history until its calls have results.
+ expect(suspendedSteps(machine.session.state)).toHaveLength(1);
+ expect(machine.session.history.map((message) => message.content)).toEqual([
+ expect.stringContaining("[Pending approvals]"),
+ ]);
+
+ const before = machine.events.length;
+ const decision = await respond(machine, {
+ inputResponses: [{ optionId: "approve", requestId: "approval-call-1" }],
+ });
+ expect(decision.next).toBe("continue");
+ expect(machine.eventsSince(before)).toEqual([
+ expect.objectContaining({
+ data: expect.objectContaining({
+ resolutions: [expect.objectContaining({ outcome: "approved" })],
+ turnId: "turn_0",
+ }),
+ type: "input.resolved",
+ }),
+ ]);
+
+ // The answer resumes the held turn.
+ await machine.apply(receive(machine.view(), {}));
+ expect(machine.eventsSince(before)).toHaveLength(1);
+
+ // eve ran the approved call: its result completes the step, which commits to history.
+ await machine.apply(settle(machine.view(), { results: [result("call-1", "deployed")] }));
+ expect(suspendedSteps(machine.session.state)).toEqual([]);
+ expect(machine.session.history.at(-1)).toMatchObject({
+ content: [{ output: { value: "deployed" }, toolCallId: "call-1", type: "tool-result" }],
+ role: "tool",
+ });
+ });
+
+ it("settles a denied call rejected and commits its step without running it", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+
+ await respond(machine, {
+ inputResponses: [{ optionId: "cancel", requestId: "approval-call-1" }],
+ });
+ expect(callStatus(machine.projection, "call-1")).toBe("rejected");
+
+ await machine.apply(settle(machine.view(), { results: [] }));
+ expect(suspendedSteps(machine.session.state)).toEqual([]);
+ expect(machine.session.history.at(-1)).toMatchObject({
+ content: [{ output: { type: "execution-denied" }, toolCallId: "call-1" }],
+ role: "tool",
+ });
+ });
+
+ it("holds a partial answer until the rest of its batch arrives", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1", "call-2");
+
+ const before = machine.events.length;
+ const partial = await respond(machine, {
+ inputResponses: [{ optionId: "approve", requestId: "approval-call-1" }],
+ });
+ expect(partial.next).toBe("park");
+ expect(machine.eventsSince(before)).toEqual([]);
+ expect(machine.view().turn.queued?.inputResponses).toHaveLength(1);
+
+ const complete = await respond(machine, {
+ inputResponses: [{ optionId: "cancel", requestId: "approval-call-2" }],
+ });
+ expect(complete.resolved).toHaveLength(1);
+ expect(complete.resolved[0]?.inputs.map((input) => input.outcome)).toEqual([
+ "approved",
+ "denied",
+ ]);
+ expect(machine.view().turn.queued).toBeUndefined();
+ });
+
+ it("steers the held turn past its approvals when a message arrives", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+
+ const decision = await respond(machine, { message: "Actually, what time is it?" });
+ expect(decision.next).toBe("continue");
+ expect(decision.input?.message).toBe("Actually, what time is it?");
+ expect(decision.resolved[0]?.inputs.map((input) => input.outcome)).toEqual(["ignored"]);
+ expect(callStatus(machine.projection, "call-1")).toBe("rejected");
+ await machine.apply(receive(machine.view(), { message: "Actually, what time is it?" }));
+
+ expect(machine.projection.activeTurnId).toBe("turn_0");
+ await machine.apply(settle(machine.view(), { results: [] }));
+ expect(suspendedSteps(machine.session.state)).toEqual([]);
+ });
+
+ it("keeps a workflow call's result with its step until the sibling approval is decided", async () => {
+ const machine = createMachine();
+ await machine.apply(receive(machine.view(), { message: "Deploy and notify." }));
+ await machine.apply(startStep(machine.view(), { modelId: "test-model" }));
+ const position = machine.position();
+ const event = {
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ };
+ await machine.apply(
+ park(machine.view(), {
+ event,
+ messages: [
+ {
+ content: [
+ ...(callMessage("call-1").content as unknown[] as never[]),
+ { input: {}, toolCallId: "call-2", toolName: "notify", type: "tool-call" },
+ ],
+ role: "assistant",
+ },
+ ],
+ requests: [approval("call-1")],
+ tasks: [
+ {
+ callId: "call-2",
+ entry: { entryPoint: "execute" },
+ input: {},
+ kind: "workflow-task",
+ toolName: "notify",
+ workflowId: "notify",
+ },
+ ],
+ }),
+ );
+ // The runtime still runs a call, so the turn stays open.
+ expect(machine.projection.activeTurnId).toBe("turn_0");
+
+ await machine.apply(
+ settle(machine.view(), {
+ results: [
+ {
+ part: {
+ output: { type: "text", value: "sent" },
+ toolCallId: "call-2",
+ toolName: "notify",
+ type: "tool-result",
+ },
+ result: { callId: "call-2", kind: "tool-result", output: "sent", toolName: "notify" },
+ },
+ ],
+ }),
+ );
+ expect(suspendedSteps(machine.session.state)).toHaveLength(1);
+
+ // Nothing else can run: the turn holds for the open approval.
+ const parked = await respond(machine, {});
+ expect(parked.next).toBe("park");
+ expect(machine.projection.activeTurnId).toBe("turn_0");
+
+ await respond(machine, {
+ inputResponses: [{ optionId: "approve", requestId: "approval-call-1" }],
+ });
+ await machine.apply(receive(machine.view(), {}));
+ await machine.apply(settle(machine.view(), { results: [result("call-1")] }));
+ const results = machine.session.history.flatMap((message) =>
+ message.role === "tool"
+ ? message.content.flatMap((part) => (part.type === "tool-result" ? [part.toolCallId] : []))
+ : [],
+ );
+ expect(results.sort()).toEqual(["call-1", "call-2"]);
+ });
+
+ it("cancels a held turn: withdraws what it asked, stops its calls, and commits its step", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+
+ await machine.apply(cancel(machine.view()));
+
+ expect(machine.projection.turns.turn_0?.status).toBe("cancelled");
+ expect(machine.projection.inputs["approval-call-1"]).toMatchObject({
+ outcome: "cancelled",
+ status: "settled",
+ });
+ expect(callStatus(machine.projection, "call-1")).toBe("cancelled");
+ expect(suspendedSteps(machine.session.state)).toEqual([]);
+ expect(machine.session.history.at(-1)).toMatchObject({
+ content: [{ output: { value: expect.stringContaining("cancelled") }, toolCallId: "call-1" }],
+ role: "tool",
+ });
+ });
+
+ it("clears the context: withdraws every request and empties history", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+
+ await machine.apply(clear(machine.view(), { sessionId: "session-test" }));
+
+ expect(machine.projection.inputs["approval-call-1"]?.status).toBe("settled");
+ expect(callStatus(machine.projection, "call-1")).toBeUndefined();
+ expect(machine.session.history).toEqual([]);
+ expect(suspendedSteps(machine.session.state)).toEqual([]);
+ });
+
+ it("holds for sign-in without publishing a fabricated call result", async () => {
+ const machine = createMachine();
+ await machine.apply(receive(machine.view(), { message: "Read my calendar." }));
+ await machine.apply(startStep(machine.view(), { modelId: "test-model" }));
+ const position = machine.position();
+ await machine.stream(
+ createActionsRequestedEvent({
+ actions: [{ callId: "call-1", input: {}, kind: "tool-call", toolName: "calendar" }],
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ }),
+ );
+ const challenge: AuthorizationChallenge = {
+ attemptId: "attempt-1",
+ challenge: { instructions: "Sign in to Google." },
+ hookUrl: "https://example.test/callback",
+ name: "google",
+ };
+
+ await machine.apply(
+ requireSignIn(machine.view(), {
+ callIdsByName: new Map([["google", ["call-1"]]]),
+ challenges: [challenge],
+ }),
+ );
+ expect(machine.eventsSince(0).some((event) => event.type === "action.result")).toBe(false);
+ expect(machine.projection.authorizations["attempt-1"]?.status).toBe("required");
+ expect(machine.events.at(-1)).toBe("turn.waiting");
+ expect(machine.projection.activeTurnId).toBe("turn_0");
+
+ const before = machine.events.length;
+ await machine.apply(completeSignIn(machine.view(), { completions: [challenge] }));
+ await machine.apply(receive(machine.view(), {}));
+ expect(machine.eventsSince(before).map((event) => event.type)).toEqual([
+ "authorization.completed",
+ ]);
+ });
+
+ it("retains a child's request coordinates while holding the parent turn", async () => {
+ const machine = createMachine();
+ await machine.apply(receive(machine.view(), { message: "Ask the researcher." }));
+ await machine.apply(startStep(machine.view(), { modelId: "test-model" }));
+ const position = machine.position();
+ await machine.stream(
+ createActionsRequestedEvent({
+ actions: [{ callId: "call-1", input: {}, kind: "tool-call", toolName: "researcher" }],
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ }),
+ );
+
+ await machine.apply(
+ relay(machine.view(), {
+ payload: {
+ callId: "call-1",
+ childContinuationToken: "child-token",
+ childSessionId: "child",
+ event: {
+ requests: [{ ...approval("child-call"), requestId: "child-question" }],
+ sequence: 4,
+ stepIndex: 2,
+ turnId: "child-turn",
+ },
+ kind: "subagent-input-request",
+ subagentName: "researcher",
+ },
+ }),
+ );
+
+ expect(machine.projection.inputs["child-question"]).toMatchObject({
+ callId: "call-1",
+ sequence: 4,
+ stepIndex: 2,
+ turnId: "child-turn",
+ });
+ expect(machine.projection.turns.turn_0?.waiting).toBe(true);
+ });
+});
+
+describe("checkpoint", () => {
+ it("saves the lifecycle its steps read, without the calls and task outputs readers fold", () => {
+ const at = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+ const report = "x".repeat(100_000);
+ const projection = [
+ { data: { sequence: 0, turnId: "turn_0" }, type: "turn.started" },
+ createActionsRequestedEvent({
+ ...at,
+ actions: [{ callId: "call_1", input: {}, kind: "tool-call", toolName: "research" }],
+ }),
+ {
+ data: { callId: "call_1", kind: "tool", name: "research", taskId: "t1", turnId: "turn_0" },
+ type: "task.started",
+ },
+ {
+ data: {
+ callId: "call_1",
+ output: report,
+ status: "completed",
+ taskId: "t1",
+ turnId: "turn_0",
+ },
+ type: "task.settled",
+ },
+ ].reduce(
+ (state, event) => foldSession(state, event as UnstampedMessageStreamEvent),
+ initialSessionProjection(),
+ );
+ expect(callStatus(projection, "call_1")).toBe("completed");
+
+ const saved = storedProjection(
+ saveProjection({ state: undefined } as HarnessSession, projection).state,
+ );
+ expect(saved).toMatchObject({ activeTurnId: "turn_0", calls: {}, tasks: {} });
+ expect(JSON.stringify(saved)).not.toContain(report);
+ });
+});
+
+describe("answers", () => {
+ it("takes a plain-text answer for the only pending batch", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+
+ const decision = await respond(machine, { message: "Approve" });
+
+ expect(decision.consumedMessage).toBe(true);
+ expect(decision.input?.message).toBeUndefined();
+ expect(decision.resolved[0]?.inputs[0]?.outcome).toBe("approved");
+ });
+
+ it("grants a once() approval's key, except to a call still asking for it", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+ await machine.apply(
+ answer(machine.view(), {
+ approvalKey: (request) => `deploy:${String(request.action.input.service)}`,
+ delivery: { inputResponses: [{ optionId: "approve", requestId: "approval-call-1" }] },
+ policy: noPolicy(),
+ takeQueued: false,
+ }),
+ );
+ const key = (request: InputRequest) => `deploy:${String(request.action.input.service)}`;
+ expect(grantedApprovalKeys(machine.view(), key)).toEqual(new Set(["deploy:api"]));
+
+ await machine.apply(settle(machine.view(), { results: [result("call-1")] }));
+ await parkOnApprovals(machine, "call-2");
+ expect(grantedApprovalKeys(machine.view(), key)).toEqual(new Set());
+ });
+
+ it("turns an answer to a closed request into text, which authorizes nothing", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+ await respond(machine, {
+ inputResponses: [{ optionId: "cancel", requestId: "approval-call-1" }],
+ });
+
+ const delivered = deliver(
+ machine.view(),
+ { inputResponses: [{ optionId: "approve", requestId: "approval-call-1" }] },
+ { takeQueued: true },
+ );
+
+ expect(delivered.input?.inputResponses).toBeUndefined();
+ expect(delivered.input?.message).toEqual(expect.stringContaining("does not authorize"));
+ expect(delivered.displayMessage).toBe("Approve");
+ });
+
+ describe("the session-limit prompt", () => {
+ const request = createSessionLimitContinuationRequest({
+ sessionId: "session-test",
+ turnSequence: 1,
+ violation: { kind: "input", limit: 100, usedTokens: 101 },
+ });
+
+ async function exhausted() {
+ const machine = createMachine();
+ await machine.apply(receive(machine.view(), { message: "Summarize Alice's notes." }));
+ await machine.apply(requestLimit(machine.view(), { request }));
+ return machine;
+ }
+
+ it("asks whether to continue and ends the turn", async () => {
+ const machine = await exhausted();
+
+ expect(machine.events.slice(-3)).toEqual([
+ "input.requested",
+ "turn.completed",
+ "session.waiting",
+ ]);
+ expect(machine.projection.inputs[request.requestId]?.status).toBe("open");
+ });
+
+ it("grants a fresh budget on continue and declines on stop", async () => {
+ for (const [optionId, granted] of [
+ ["continue", true],
+ ["stop", false],
+ ] as const) {
+ const machine = await exhausted();
+ const decision = await respond(machine, {
+ inputResponses: [{ optionId, requestId: request.requestId }],
+ });
+ expect(decision.limit).toEqual({ granted });
+ expect(machine.projection.inputs[request.requestId]?.status).toBe("settled");
+ }
+ });
+
+ it("receives a message now, and queues only what waits for the answer", async () => {
+ const machine = await exhausted();
+
+ const decision = await respond(machine, { message: "Any update?" });
+
+ expect(decision.next).toBe("defer-message");
+ expect(decision.input?.message).toBe("Any update?");
+ expect(machine.view().turn.queued).toBeUndefined();
+ });
+
+ it("takes the prompt's answer from text while an approval is also open", async () => {
+ const machine = createMachine();
+ await parkOnApprovals(machine, "call-1");
+ await machine.apply(receive(machine.view(), { message: "Keep going." }));
+ await machine.apply(requestLimit(machine.view(), { request }));
+
+ const decision = await respond(machine, { message: "Continue" });
+
+ expect(decision.limit).toEqual({ granted: true });
+ expect(callStatus(machine.projection, "call-1")).toBe("awaiting-input");
+ });
+ });
+});
+
+describe("receive", () => {
+ it("starts the session and the turn under one trace context, then receives the message", async () => {
+ const machine = createMachine();
+ const trace = {
+ spanId: "0123456789abcdef",
+ traceFlags: 1,
+ traceId: "0123456789abcdef0123456789abcdef",
+ };
+
+ await machine.apply(receive(machine.view(), { message: "hello", trace }));
+
+ expect(machine.eventsSince(0)).toEqual([
+ { data: { trace }, type: "session.started" },
+ {
+ data: { sequence: 0, trace, turnId: "turn_0" },
+ type: "turn.started",
+ },
+ expect.objectContaining({
+ data: expect.objectContaining({ turnId: "turn_0" }),
+ type: "message.received",
+ }),
+ ]);
+ });
+
+ it("gives hooks the turn's history from turn.started, never before the session started", async () => {
+ const seen: [string, readonly ModelMessage[] | undefined][] = [];
+ const history: ModelMessage[] = [{ content: "hello", role: "user" }];
+ const machine = createMachine();
+ await applyTransition(
+ machine.session,
+ receive(machine.view(), { message: "hello" }),
+ async (event, messages) => {
+ seen.push([event.type, messages]);
+ },
+ history,
+ );
+
+ expect(seen).toEqual([
+ ["session.started", undefined],
+ ["turn.started", history],
+ ["message.received", undefined],
+ ]);
+ });
+
+ it("joins the open turn when steering arrives", async () => {
+ const machine = createMachine();
+ await machine.apply(receive(machine.view(), { message: "Start the work" }));
+ const before = machine.events.length;
+
+ await machine.apply(receive(machine.view(), { message: "Use the staging data." }));
+
+ expect(machine.events.slice(before)).toEqual(["message.received"]);
+ });
+});
+
+function park(
+ view: Parameters<typeof parkOnApprovalsTransition>[0],
+ input: Parameters<typeof parkOnApprovalsTransition>[1],
+): Transition {
+ return input.requests.length === 0
+ ? suspendStep(view, input)
+ : parkOnApprovalsTransition(view, input);
+}
diff --git a/packages/eve/src/harness/session-machine/resolver-events.ts b/packages/eve/src/harness/session-machine/resolver-events.ts
new file mode 100644
index 000000000..d358a0146
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/resolver-events.ts
@@ -0,0 +1,29 @@
+import {
+ createSessionStartedEvent,
+ createStepStartedEvent,
+ createTurnStartedEvent,
+ type RuntimeIdentity,
+} from "#protocol/message.js";
+
+// The events resolvers (dynamic tools, connections, models) receive to describe where the
+// session is when they run. They are never published: the transitions publish the real ones.
+
+export function sessionStartedForResolvers(runtime?: RuntimeIdentity) {
+ return createSessionStartedEvent({ runtime });
+}
+
+export function turnStartedForResolvers(turn: {
+ readonly sequence: number;
+ readonly turnId: string;
+}) {
+ return createTurnStartedEvent(turn);
+}
+
+export function stepStartedForResolvers(step: {
+ readonly modelId: string;
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+}) {
+ return createStepStartedEvent(step);
+}
diff --git a/packages/eve/src/harness/session-machine/state.ts b/packages/eve/src/harness/session-machine/state.ts
new file mode 100644
index 000000000..bff2c6f02
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/state.ts
@@ -0,0 +1,71 @@
+import type { ModelMessage } from "ai";
+
+import type { SessionAuthContext } from "#channel/types.js";
+import type { SessionStateMap, StepInput } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import type { InputRequest } from "#shared/input.js";
+
+// Execution state the session machine keeps between steps. Lifecycle facts (whether a turn is
+// open, whether a request is answered, how a call ended) are the projection's; this holds only
+// what execution needs to resume work. Only the machine's `apply` writes it.
+
+const TURN_STATE_KEY = "eve.harness.turnState";
+
+/** The coordinates of the model step a suspended step parked from. */
+export interface StepCoordinates {
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+}
+
+/**
+ * A model step whose calls can't all settle yet: some await an approval, others the runtime.
+ * Its response stays out of history until every call it made has a result there, so a call
+ * never reaches the model without its result.
+ */
+export interface SuspendedStep {
+ readonly event: StepCoordinates;
+ /** The withheld response. Results join it as they arrive. */
+ readonly messages: readonly ModelMessage[];
+ /** Approvals the step still waits on. */
+ readonly requests: readonly InputRequest[];
+ /**
+ * Calls a person approved that haven't run. They run when the turn next calls the model, after
+ * its step starts and its budget allows it, as calls the model makes do.
+ */
+ readonly approved?: readonly InputRequest[];
+ /** Workflow and agent calls the runtime runs for the step. */
+ readonly tasks: readonly RuntimeWorkflowTaskRequest[];
+ /** Who approved each task an approval started, by call id: the task runs as them. */
+ readonly approvers?: Readonly<Record<string, SessionAuthContext>>;
+ readonly responseAuthRequiredRequestIds?: readonly string[];
+ /** The caller whose turn parked the step; `null` when unauthenticated. */
+ readonly requester?: SessionAuthContext | null;
+}
+
+export interface TurnState {
+ /** Input that arrived before it could run: a partial answer, or input behind a policy pass. */
+ readonly queued?: StepInput;
+ readonly suspended: readonly SuspendedStep[];
+ /** Approval keys a `once()` approval granted for the rest of the session. */
+ readonly grants: readonly string[];
+}
+
+export const EMPTY_TURN_STATE: TurnState = { grants: [], suspended: [] };
+
+export function readTurnState(state: SessionStateMap | undefined): TurnState {
+ return (state?.[TURN_STATE_KEY] as TurnState | undefined) ?? EMPTY_TURN_STATE;
+}
+
+export function writeTurnState<T extends { readonly state?: SessionStateMap }>(
+ session: T,
+ turn: TurnState,
+): T {
+ const state = { ...session.state };
+ if (turn.suspended.length === 0 && turn.queued === undefined && turn.grants.length === 0) {
+ delete state[TURN_STATE_KEY];
+ } else {
+ state[TURN_STATE_KEY] = turn;
+ }
+ return { ...session, state: Object.keys(state).length === 0 ? undefined : state };
+}
diff --git a/packages/eve/src/harness/session-machine/transitions.ts b/packages/eve/src/harness/session-machine/transitions.ts
new file mode 100644
index 000000000..7063a20a5
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/transitions.ts
@@ -0,0 +1,662 @@
+import type { ModelMessage, UserContent } from "ai";
+
+import type {
+ SubagentAuthorizationEventHookPayload,
+ SubagentInputRequestHookPayload,
+} from "#channel/types.js";
+import type { AuthorizationChallenge } from "#harness/authorization.js";
+import { authorizationEventFields } from "#harness/authorization-event-fields.js";
+import {
+ type TurnWaitingOn,
+ createActionResultEvent,
+ createAuthorizationCompletedEvent,
+ createAuthorizationRequiredEvent,
+ createContextClearedEvent,
+ createInputRequestedEvent,
+ createInputResolvedEvent,
+ createMessageReceivedEvent,
+ createResultCompletedEvent,
+ createSessionCompletedEvent,
+ createSessionFailedEvent,
+ createSessionStartedEvent,
+ createSessionWaitingEvent,
+ createStepFailedEvent,
+ createStepStartedEvent,
+ createTaskSettledEvent,
+ createTaskStartedEvent,
+ createTurnCancelledEvent,
+ createTurnCompletedEvent,
+ createTurnFailedEvent,
+ createTurnStartedEvent,
+ createTurnWaitingEvent,
+ type InputResolution,
+ type RuntimeIdentity,
+ type RuntimeTraceContext,
+ type TaskCancelReason,
+ type TaskStartedStreamEvent,
+ type UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
+import {
+ openInputs,
+ openSignIns,
+ turnCoordinates,
+ type SessionInput,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+import type { RuntimeActionResult } from "#shared/action-types.js";
+import type { InputRequest } from "#shared/input.js";
+import type { JsonObject, JsonValue } from "#shared/json.js";
+import type { TokenUsage } from "#shared/token-usage.js";
+import type { Transition } from "./commit.js";
+import { inputWithdrawn, signInWithdrawn } from "./events.js";
+import type { StepCoordinates, SuspendedStep, TurnState } from "./state.js";
+import {
+ activeTurnId,
+ answeredCallIds,
+ nextStepIndex,
+ turnPosition,
+ type SessionView,
+} from "./view.js";
+
+// The session's lifecycle. Every transition reads a `SessionView` and returns the events that
+// report what changed with the execution state that follows; `applyTransition` publishes and
+// saves them, and nothing else builds a lifecycle event or writes `TurnState`. Approvals,
+// the session-limit prompt, and sign-ins are in `approvals.ts`.
+//
+// Transitions are pure: what they need from effects (model responses, tool results, the
+// requests a session relays) arrives in their input.
+
+type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
+export type ToolResultPart = Extract<ToolResponsePart, { type: "tool-result" }>;
+
+const unchanged = (view: SessionView, events: readonly UnstampedMessageStreamEvent[]) => ({
+ events,
+ turn: view.turn,
+});
+
+/** The coordinates the next lifecycle event carries. */
+function at(projection: SessionProjection) {
+ const position = turnPosition(projection);
+ return {
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: activeTurnId(position),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Turns
+// ---------------------------------------------------------------------------
+
+/**
+ * Input arrives: the session starts once, a turn opens unless one is open (steering joins it),
+ * and a message is received.
+ */
+export function receive(
+ view: SessionView,
+ input: {
+ readonly message?: string | UserContent;
+ readonly runtime?: RuntimeIdentity;
+ readonly trace?: RuntimeTraceContext;
+ },
+): Transition {
+ const position = turnPosition(view.projection);
+ const turnId = activeTurnId(position);
+ const events: UnstampedMessageStreamEvent[] = [];
+ if (!position.sessionStarted) {
+ events.push(createSessionStartedEvent({ runtime: input.runtime, trace: input.trace }));
+ }
+ if (position.turnId === "") {
+ events.push(
+ createTurnStartedEvent({
+ sequence: position.sequence,
+ trace: input.trace,
+ turnId,
+ }),
+ );
+ }
+ if (input.message !== undefined) {
+ events.push(
+ createMessageReceivedEvent({ message: input.message, sequence: position.sequence, turnId }),
+ );
+ }
+ return unchanged(view, events);
+}
+
+/** The open turn calls the model. */
+export function startStep(view: SessionView, input: { readonly modelId: string }): Transition {
+ const { sequence, turnId } = at(view.projection);
+ return unchanged(view, [
+ createStepStartedEvent({
+ modelId: input.modelId,
+ sequence,
+ stepIndex: nextStepIndex(view.projection),
+ turnId,
+ }),
+ ]);
+}
+
+/**
+ * The open turn parks: on `"tasks"` while work it started runs, on `"input"` while a person must
+ * act on a sign-in, approval, or question. It resumes in the same turn.
+ */
+export function hold(view: SessionView, input: { readonly on: TurnWaitingOn }): Transition {
+ const { sequence, turnId } = turnPosition(view.projection);
+ if (turnId === "") return unchanged(view, []);
+ return unchanged(view, [
+ createTurnWaitingEvent({ on: input.on, sequence, turnId, usage: view.usage }),
+ ]);
+}
+
+/** Nothing is left to run: the turn completes, with its structured result when it has one. */
+export function finishTurn(
+ view: SessionView,
+ input: { readonly result?: JsonValue } = {},
+): Transition {
+ const { sequence, stepIndex, turnId } = at(view.projection);
+ const events: UnstampedMessageStreamEvent[] = [];
+ if (input.result !== undefined) {
+ events.push(createResultCompletedEvent({ result: input.result, sequence, stepIndex, turnId }));
+ }
+ if (view.projection.activeTurnId !== undefined) {
+ events.push(createTurnCompletedEvent({ sequence, turnId }));
+ }
+ events.push(createSessionWaitingEvent(view.usage));
+ return unchanged(view, events);
+}
+
+/**
+ * The step failed. A recoverable failure parks the session for the user to retry; a terminal
+ * one ends it.
+ */
+export function fail(
+ view: SessionView,
+ failure: {
+ readonly code: string;
+ readonly details?: JsonObject;
+ readonly message: string;
+ readonly terminal?: { readonly sessionId: string };
+ },
+): Transition {
+ const { sequence, stepIndex, turnId } = at(view.projection);
+ // The calls the turn approved but hadn't run never run: the model reads that they stopped.
+ const stopped = view.turn.suspended.filter((step) => (step.approved?.length ?? 0) > 0);
+ return {
+ commit: stopped.flatMap(cancelledTranscript),
+ events: failedEvents(view, failure, { sequence, stepIndex, turnId }),
+ turn: {
+ ...view.turn,
+ suspended: view.turn.suspended.filter((step) => !stopped.includes(step)),
+ },
+ };
+}
+
+function failedEvents(
+ view: SessionView,
+ failure: Parameters<typeof fail>[1],
+ at: StepCoordinates,
+): UnstampedMessageStreamEvent[] {
+ const { sequence, stepIndex, turnId } = at;
+ const { code, details, message } = failure;
+ return [
+ createStepFailedEvent({ code, details, message, sequence, stepIndex, turnId }),
+ createTurnFailedEvent({ code, details, message, sequence, turnId }),
+ failure.terminal === undefined
+ ? createSessionWaitingEvent(view.usage)
+ : createSessionFailedEvent({
+ code,
+ details,
+ message,
+ sessionId: failure.terminal.sessionId,
+ usage: view.usage,
+ }),
+ ];
+}
+
+/** The session waits for its next delivery. */
+export function idle(view: SessionView): Transition {
+ return unchanged(view, [createSessionWaitingEvent(view.usage)]);
+}
+
+// ---------------------------------------------------------------------------
+// Sessions
+// ---------------------------------------------------------------------------
+
+export function sessionCompleted(
+ usage: TokenUsage | undefined,
+): ReturnType<typeof createSessionCompletedEvent> {
+ return createSessionCompletedEvent(usage);
+}
+
+export function sessionFailed(input: {
+ readonly code: string;
+ readonly details?: JsonObject;
+ readonly message: string;
+ readonly sessionId: string;
+ readonly usage: TokenUsage | undefined;
+}): ReturnType<typeof createSessionFailedEvent> {
+ return createSessionFailedEvent(input);
+}
+
+// ---------------------------------------------------------------------------
+// Calls
+// ---------------------------------------------------------------------------
+
+/** One call's result, ready for its step's transcript. */
+export interface SettledCall {
+ readonly part: ToolResultPart;
+ /** A runtime result, reported at the coordinates of the step that made the call. */
+ readonly result?: RuntimeActionResult;
+}
+
+/**
+ * Results reach the steps that made their calls. A step whose every call now has a result
+ * commits to history, where the model reads it.
+ */
+export function settle(view: SessionView, input: { readonly results: readonly SettledCall[] }) {
+ const events: UnstampedMessageStreamEvent[] = [];
+ const steps = [...view.turn.suspended];
+ for (const { part, result } of input.results) {
+ const index = steps.findIndex((step) => stepCallIds(step).has(part.toolCallId));
+ const step = steps[index];
+ if (step === undefined) continue;
+ steps[index] = withoutApproved(
+ { ...step, messages: withResult(step.messages, part) },
+ new Set([part.toolCallId]),
+ );
+ if (result !== undefined) {
+ events.push(createActionResultEvent({ result, ...step.event }));
+ }
+ }
+ const complete = steps.filter(isComplete);
+ return {
+ commit: complete.flatMap((step) => step.messages),
+ events,
+ turn: { ...view.turn, suspended: steps.filter((step) => !complete.includes(step)) },
+ } satisfies Transition;
+}
+
+/**
+ * A model response made calls the runtime runs. The response waits in a suspended step until
+ * every call it made has a result, so a call never reaches the model without its result.
+ */
+export function suspendStep(
+ view: SessionView,
+ step: Pick<SuspendedStep, "event" | "messages" | "tasks">,
+): Transition {
+ return { events: [], turn: suspend(view.turn, { ...step, requests: [] }) };
+}
+
+/** The step without the approved calls in `callIds`, which have run or joined the runtime. */
+export function withoutApproved(step: SuspendedStep, callIds: ReadonlySet<string>): SuspendedStep {
+ if (step.approved === undefined) return step;
+ const approved = step.approved.filter((request) => !callIds.has(request.action.callId));
+ if (approved.length === step.approved.length) return step;
+ const { approved: _approved, ...rest } = step;
+ return approved.length === 0 ? rest : { ...rest, approved };
+}
+
+/** Approved calls of suspended steps that haven't run. */
+export function approvedCalls(turn: TurnState): readonly InputRequest[] {
+ return turn.suspended.flatMap((step) => step.approved ?? []);
+}
+
+export function suspend(turn: TurnState, step: SuspendedStep): TurnState {
+ return { ...turn, suspended: [...turn.suspended, step] };
+}
+
+/** The ids of the calls a step's response made, except provider-executed ones. */
+export function stepCallIds(step: Pick<SuspendedStep, "messages">): ReadonlySet<string> {
+ const ids = new Set<string>();
+ for (const message of step.messages) {
+ if (message.role !== "assistant" || typeof message.content === "string") continue;
+ for (const part of message.content) {
+ if (part.type === "tool-call" && part.providerExecuted !== true) ids.add(part.toolCallId);
+ }
+ }
+ return ids;
+}
+
+function isComplete(step: SuspendedStep): boolean {
+ if (step.requests.length > 0) return false;
+ const answered = answeredCallIds(step.messages);
+ return [...stepCallIds(step)].every((callId) => answered.has(callId));
+}
+
+/** Places a result right after the message that made its call. */
+export function withResult(
+ messages: readonly ModelMessage[],
+ part: ToolResultPart,
+): ModelMessage[] {
+ const next = [...messages];
+ const asking = next.findIndex(
+ (message) =>
+ message.role === "assistant" &&
+ Array.isArray(message.content) &&
+ message.content.some(
+ (content) => content.type === "tool-call" && content.toolCallId === part.toolCallId,
+ ),
+ );
+ const following = next[asking + 1];
+ if (asking >= 0 && following?.role === "tool") {
+ next[asking + 1] = { ...following, content: [...following.content, part] };
+ } else {
+ next.splice(asking >= 0 ? asking + 1 : next.length, 0, { content: [part], role: "tool" });
+ }
+ return next;
+}
+
+// ---------------------------------------------------------------------------
+// Tasks
+// ---------------------------------------------------------------------------
+
+/** A call started or reached a task. */
+export function startTask(view: SessionView, task: TaskStartedStreamEvent["data"]): Transition {
+ return unchanged(view, [createTaskStartedEvent(task)]);
+}
+
+export type TaskCallOutcome =
+ | { readonly status: "completed"; readonly output?: JsonValue }
+ | { readonly status: "failed"; readonly error: string }
+ | { readonly status: "cancelled"; readonly reason?: TaskCancelReason };
+
+/** A task's run settled calls: each reports its outcome, naming the task as it started. */
+export function settleTask(
+ view: SessionView,
+ input: {
+ readonly task: {
+ readonly id: string;
+ readonly kind?: TaskStartedStreamEvent["data"]["kind"];
+ readonly name?: string;
+ };
+ readonly calls: readonly { readonly callId: string; readonly turnId: string }[];
+ readonly outcome: TaskCallOutcome;
+ },
+): Transition {
+ const { outcome, task } = input;
+ return unchanged(
+ view,
+ input.calls.map((call) => {
+ const base = {
+ callId: call.callId,
+ kind: task.kind,
+ name: task.name,
+ taskId: task.id,
+ turnId: call.turnId,
+ };
+ switch (outcome.status) {
+ case "completed":
+ return createTaskSettledEvent({ ...base, output: outcome.output, status: "completed" });
+ case "failed":
+ return createTaskSettledEvent({
+ ...base,
+ error: { message: outcome.error },
+ status: "failed",
+ });
+ case "cancelled":
+ return createTaskSettledEvent(
+ outcome.reason === undefined
+ ? { ...base, status: "cancelled" }
+ : { ...base, cancel: { reason: outcome.reason }, status: "cancelled" },
+ );
+ }
+ }),
+ );
+}
+
+/**
+ * A task or workflow run ended, on its own or cancelled: nobody can answer what it relayed, so
+ * each request still open is withdrawn.
+ */
+export function finishRun(
+ view: SessionView,
+ run: { readonly taskId?: string; readonly requestIds?: Iterable<string> },
+): Transition {
+ const ids = new Set(run.requestIds);
+ return unchanged(
+ view,
+ openInputs(view.projection)
+ .filter(
+ (input) =>
+ ids.has(input.request.requestId) ||
+ (run.taskId !== undefined && input.taskId === run.taskId),
+ )
+ .map(inputWithdrawn),
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Relay
+// ---------------------------------------------------------------------------
+
+/**
+ * A child session or workflow run asks a question or for a sign-in. The session passes it up
+ * with its original coordinates, and the open turn waits on the call it serves.
+ * A child's fresh batch replaces its earlier one, whose open requests are withdrawn.
+ */
+export function relay(
+ view: SessionView,
+ input: {
+ readonly payload: SubagentInputRequestHookPayload | SubagentAuthorizationEventHookPayload;
+ readonly replacedRequestIds?: Iterable<string>;
+ },
+): Transition {
+ const { payload } = input;
+ const events: UnstampedMessageStreamEvent[] = [
+ ...finishRun(view, { requestIds: input.replacedRequestIds }).events,
+ ];
+ if (payload.kind === "subagent-input-request") {
+ const { event } = payload;
+ events.push(
+ createInputRequestedEvent({
+ callId: payload.callId,
+ requests: event.requests,
+ sequence: event.sequence,
+ stepIndex: event.stepIndex,
+ taskId: event.taskId,
+ turnId: event.turnId,
+ }),
+ );
+ } else {
+ const { event } = payload;
+ events.push(event);
+ if (event.type !== "authorization.required") return unchanged(view, events);
+ }
+ events.push(...hold(view, { on: "input" }).events);
+ return unchanged(view, events);
+}
+
+/**
+ * Answers to relayed requests are on their way to the asker: each request resolves here.
+ */
+export function receiveRelayedAnswer(input: {
+ readonly message: string | UserContent;
+ readonly sequence: number;
+ readonly turnId: string;
+}) {
+ return createMessageReceivedEvent(input);
+}
+
+export function routeAnswer(
+ view: SessionView,
+ input: {
+ readonly children: readonly {
+ readonly event: StepCoordinates;
+ readonly resolutions: readonly InputResolution[];
+ }[];
+ },
+): Transition {
+ const events: UnstampedMessageStreamEvent[] = input.children
+ .filter((child) => child.resolutions.length > 0)
+ .map((child) => createInputResolvedEvent({ resolutions: child.resolutions, ...child.event }));
+ return unchanged(view, events);
+}
+
+/**
+ * A workflow run's sign-in, reported to the session that owns the run, which relays it. Built
+ * where the run asks, at the coordinates of the call it serves.
+ */
+export function runSignIn(
+ from: {
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly taskId?: string;
+ readonly turnId: string;
+ },
+ challenge: AuthorizationChallenge,
+ outcome?: "authorized" | "failed",
+) {
+ const fields = {
+ ...authorizationEventFields(challenge),
+ sequence: from.sequence,
+ stepIndex: from.stepIndex,
+ taskId: from.taskId,
+ turnId: from.turnId,
+ };
+ return outcome === undefined
+ ? createAuthorizationRequiredEvent({
+ ...fields,
+ description: `Sign in to ${challenge.name} to continue.`,
+ webhookUrl: challenge.hookUrl,
+ })
+ : createAuthorizationCompletedEvent({ ...fields, outcome });
+}
+
+// ---------------------------------------------------------------------------
+// Sign-ins
+// ---------------------------------------------------------------------------
+
+/** Sign-in callbacks arrived: each completion is reported at the coordinates of the turn that asked. */
+export function completeSignIn(
+ view: SessionView,
+ input: { readonly completions: readonly AuthorizationChallenge[] },
+): Transition {
+ const position = at(view.projection);
+ return unchanged(
+ view,
+ input.completions.map((challenge) => {
+ const attempt =
+ challenge.attemptId === undefined
+ ? undefined
+ : view.projection.authorizations[challenge.attemptId];
+ return createAuthorizationCompletedEvent({
+ ...authorizationEventFields(challenge),
+ outcome: "authorized",
+ sequence: attempt?.sequence ?? position.sequence,
+ stepIndex: attempt?.stepIndex ?? position.stepIndex,
+ turnId: attempt?.turnId ?? position.turnId,
+ });
+ }),
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Cancel and clear
+// ---------------------------------------------------------------------------
+
+/** Requests this session asked itself and still awaits; relayed requests answer elsewhere. */
+export function ownOpenRequestIds(view: Omit<SessionView, "turn">): ReadonlySet<string> {
+ return new Set(
+ openInputs(view.projection)
+ .filter(
+ (input) =>
+ input.callId === undefined &&
+ input.taskId === undefined &&
+ !view.relayedRequestIds.has(input.request.requestId),
+ )
+ .map((input) => input.request.requestId),
+ );
+}
+
+/** What the model reads for a call its turn's cancellation stopped before the call settled. */
+export const CANCELLED_CALL_RESULT = "The turn was cancelled before this call finished.";
+
+/**
+ * `session.cancel()`: the open turn ends cancelled. Its requests, its sign-ins, and every
+ * relayed request are withdrawn, since the cancel stops the work that asked them; its unsettled
+ * calls are stopped. The steps it ran commit to history, each unfinished call answered as
+ * cancelled, so the model sees that the work started and stopped.
+ */
+export function cancel(view: SessionView): Transition {
+ const { projection } = view;
+ const turnId = projection.activeTurnId;
+ const stopped = view.turn.suspended.filter(
+ (step) =>
+ (turnId !== undefined && step.event.turnId === turnId) ||
+ step.tasks.some((task) => !answeredCallIds(step.messages).has(task.callId)) ||
+ (step.approved?.length ?? 0) > 0,
+ );
+ const stoppedRequestIds = new Set(
+ stopped.flatMap((step) => step.requests.map((request) => request.requestId)),
+ );
+ const owned = (input: SessionInput) =>
+ input.turnId === turnId ||
+ stoppedRequestIds.has(input.request.requestId) ||
+ view.relayedRequestIds.has(input.request.requestId) ||
+ input.request.kind === "session-limit";
+ const events: UnstampedMessageStreamEvent[] = [
+ ...openInputs(projection).filter(owned).map(inputWithdrawn),
+ ...openSignIns(projection)
+ .filter((attempt) => attempt.turnId === turnId)
+ .map((attempt) => signInWithdrawn(attempt, "Cancelled.")),
+ ];
+ if (turnId !== undefined) {
+ const { sequence } = turnCoordinates(projection);
+ events.push(createTurnCancelledEvent({ sequence, turnId }));
+ }
+ events.push(createSessionWaitingEvent(view.usage));
+ return {
+ commit: stopped.flatMap(cancelledTranscript),
+ events,
+ // Every sign-in the turn held ends with it.
+ signIns: [],
+ turn: {
+ ...view.turn,
+ suspended: view.turn.suspended.filter((step) => !stopped.includes(step)),
+ },
+ };
+}
+
+/** A stopped step's response, each call without a result answered as cancelled. */
+function cancelledTranscript(step: SuspendedStep): ModelMessage[] {
+ const answered = answeredCallIds(step.messages);
+ let messages = [...step.messages];
+ for (const message of step.messages) {
+ if (message.role !== "assistant" || typeof message.content === "string") continue;
+ for (const part of message.content) {
+ if (part.type !== "tool-call" || part.providerExecuted === true) continue;
+ if (answered.has(part.toolCallId)) continue;
+ messages = withResult(messages, {
+ output: { type: "text", value: CANCELLED_CALL_RESULT },
+ toolCallId: part.toolCallId,
+ toolName: part.toolName,
+ type: "tool-result",
+ });
+ }
+ }
+ return messages;
+}
+
+/**
+ * `session.clear()`: everything the cleared history asked for is withdrawn, its approvals and
+ * the session-limit prompt and every sign-in, and the calls awaiting them stop. Requests relayed
+ * from live tasks stay: clearing doesn't stop the work that asked them.
+ */
+export function clear(view: SessionView, input: { readonly sessionId: string }): Transition {
+ const { projection } = view;
+ const { sequence, turnId } = turnCoordinates(projection);
+ return {
+ clearsHistory: true,
+ events: [
+ ...openInputs(projection)
+ .filter((open) => !view.relayedRequestIds.has(open.request.requestId))
+ .map(inputWithdrawn),
+ ...openSignIns(projection).map((attempt) =>
+ signInWithdrawn(attempt, "The context was cleared."),
+ ),
+ createContextClearedEvent({ sequence, sessionId: input.sessionId, turnId }),
+ createSessionWaitingEvent(view.usage),
+ ],
+ turn: { grants: view.turn.grants, suspended: [] } satisfies TurnState,
+ };
+}
diff --git a/packages/eve/src/harness/session-machine/view.ts b/packages/eve/src/harness/session-machine/view.ts
new file mode 100644
index 000000000..3295f8a5f
--- /dev/null
+++ b/packages/eve/src/harness/session-machine/view.ts
@@ -0,0 +1,147 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { TokenUsage } from "#shared/token-usage.js";
+import type { ModelMessage } from "ai";
+
+import type { AuthorizationChallenge } from "#harness/authorization.js";
+import { pendingTaskToolCalls, type TaskToolCall } from "#execution/tasks/calls.js";
+import type { SessionStateMap, StepInput } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import {
+ initialSessionProjection,
+ turnCoordinates,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+import {
+ readTurnState,
+ type StepCoordinates,
+ type SuspendedStep,
+ type TurnState,
+} from "./state.js";
+
+// What the session machine reads, and the read-only selectors the rest of eve uses. Lifecycle
+// comes from the stored projection, which publishing folds from every event the session
+// publishes; execution comes from `TurnState`. Workflow bodies import this module, so it stays
+// free of runtime dependencies; a step reads the live projection through `current.ts`.
+
+export type { StepCoordinates, SuspendedStep, TurnState } from "./state.js";
+
+export const SESSION_PROJECTION_STATE_KEY = "eve.harness.sessionProjection";
+
+/** What a transition sees. */
+export interface SessionView {
+ readonly turn: TurnState;
+ readonly projection: SessionProjection;
+ /** Requests this session relays for a child session or a workflow run, by `requestId`. */
+ readonly relayedRequestIds: ReadonlySet<string>;
+ /** The sign-in attempts the session waits on, with what completing them needs. */
+ readonly signIns: readonly AuthorizationChallenge[];
+ /** The session's token usage so far, which its waiting and terminal events report. */
+ readonly usage: TokenUsage;
+}
+
+/** Reads the authoritative lifecycle facts saved alongside execution state. */
+export function storedProjection(state: SessionStateMap | undefined): SessionProjection {
+ return (
+ (state?.[SESSION_PROJECTION_STATE_KEY] as SessionProjection | undefined) ??
+ initialSessionProjection()
+ );
+}
+
+/** Coordinates the next lifecycle event carries, and whether a turn is open. */
+export interface TurnPosition {
+ readonly sessionStarted: boolean;
+ readonly sequence: number;
+ readonly stepIndex: number;
+ /** The open turn's id, or `""` between turns. */
+ readonly turnId: string;
+ /** The open turn streamed assistant output, so steering can no longer restart it. */
+ readonly assistantOutputStarted?: boolean;
+}
+
+export function turnPosition(projection: SessionProjection): TurnPosition {
+ const { sequence, stepIndex } = turnCoordinates(projection);
+ const turn =
+ projection.activeTurnId === undefined ? undefined : projection.turns[projection.activeTurnId];
+ const position: { -readonly [K in keyof TurnPosition]: TurnPosition[K] } = {
+ sessionStarted: projection.started === true,
+ sequence,
+ stepIndex,
+ turnId: turn?.turnId ?? "",
+ };
+ if (turn?.outputStarted === true) position.assistantOutputStarted = true;
+ return position;
+}
+
+/** The open turn's id, or the id the next turn takes. */
+export function activeTurnId(position: Pick<TurnPosition, "sequence" | "turnId">): string {
+ return position.turnId === "" ? `turn_${position.sequence}` : position.turnId;
+}
+
+export function isBetweenTurns(projection: SessionProjection): boolean {
+ return projection.activeTurnId === undefined;
+}
+
+/** The index the open turn's next `step.started` takes. */
+export function nextStepIndex(projection: SessionProjection): number {
+ const turn =
+ projection.activeTurnId === undefined ? undefined : projection.turns[projection.activeTurnId];
+ return turn?.stepIndex === undefined ? 0 : turn.stepIndex + 1;
+}
+
+/** Input the session holds until it can run. */
+export function queuedInput(state: SessionStateMap | undefined): StepInput | undefined {
+ return readTurnState(state).queued;
+}
+
+export function suspendedSteps(state: SessionStateMap | undefined): readonly SuspendedStep[] {
+ return readTurnState(state).suspended;
+}
+
+/** The ids of calls that already have a result in `messages`. */
+export function answeredCallIds(messages: readonly ModelMessage[]): ReadonlySet<string> {
+ const answered = new Set<string>();
+ for (const message of messages) {
+ if (message.role !== "tool" && message.role !== "assistant") continue;
+ if (typeof message.content === "string") continue;
+ for (const part of message.content) {
+ if (part.type === "tool-result") answered.add(part.toolCallId);
+ }
+ }
+ return answered;
+}
+
+/** Workflow and agent calls of `step` the runtime still runs. */
+export function runningTasks(step: SuspendedStep): readonly RuntimeWorkflowTaskRequest[] {
+ const answered = answeredCallIds(step.messages);
+ return step.tasks.filter((task) => !answered.has(task.callId));
+}
+
+/** What the turn waits on the runtime for: dispatched runs and the task tool calls. */
+export interface RuntimeWait {
+ readonly event: StepCoordinates;
+ readonly callIds: readonly string[];
+ readonly tasks: readonly RuntimeWorkflowTaskRequest[];
+ readonly taskToolCalls: readonly TaskToolCall[];
+ /** Who approved each task an approval started, by call id. */
+ readonly approvers: Readonly<Record<string, SessionAuthContext>>;
+}
+
+/** The calls suspended steps wait on the runtime for, or `undefined` when none do. */
+export function runtimeWait(state: SessionStateMap | undefined): RuntimeWait | undefined {
+ const waiting = suspendedSteps(state).flatMap((step) => {
+ const tasks = runningTasks(step);
+ const taskToolCalls = pendingTaskToolCalls(step.messages);
+ return tasks.length === 0 && taskToolCalls.length === 0 ? [] : [{ step, tasks, taskToolCalls }];
+ });
+ const first = waiting[0];
+ if (first === undefined) return undefined;
+ const tasks = waiting.flatMap((entry) => entry.tasks);
+ const taskToolCalls = waiting.flatMap((entry) => entry.taskToolCalls);
+ return {
+ approvers: Object.assign({}, ...waiting.map((entry) => entry.step.approvers)),
+ callIds: [...tasks.map((task) => task.callId), ...taskToolCalls.map((call) => call.callId)],
+ event: first.step.event,
+ taskToolCalls,
+ tasks,
+ };
+}
diff --git a/packages/eve/src/harness/step-hooks.test.ts b/packages/eve/src/harness/step-hooks.test.ts
index 17fa13a47..5e6418072 100644
--- a/packages/eve/src/harness/step-hooks.test.ts
+++ b/packages/eve/src/harness/step-hooks.test.ts
@@ -4,16 +4,8 @@ import { describe, expect, it, vi } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
import { ConversationIdKey } from "#context/keys.js";
import { buildStepHooks } from "#harness/step-hooks.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
import type { HarnessSession } from "#harness/types.js";
-const emissionState: HarnessEmissionState = {
- sequence: 0,
- sessionStarted: true,
- stepIndex: 0,
- turnId: "turn_0",
-};
-
function createSession(): HarnessSession {
return {
agent: {
@@ -29,14 +21,13 @@ function createSession(): HarnessSession {
}
describe("buildStepHooks", () => {
- it("emits step.started from onStepStart, not prepareStep", async () => {
- const emit = vi.fn(async () => {});
+ it("starts the step from onStepStart, not prepareStep", async () => {
+ const startStep = vi.fn(async () => {});
const hooks = buildStepHooks({
cachePath: { kind: "none" },
- emit,
- emissionState,
marker: undefined,
session: createSession(),
+ startStep,
});
const messages: ModelMessage[] = [{ content: "hello", role: "user" }];
@@ -53,17 +44,11 @@ describe("buildStepHooks", () => {
stepNumber: 0,
steps: [],
});
- expect(emit).not.toHaveBeenCalled();
+ expect(startStep).not.toHaveBeenCalled();
await Reflect.apply(hooks.onStepStart, null, [{ messages }]);
- expect(emit).toHaveBeenCalledWith(
- {
- data: { modelId: "test-model", sequence: 0, stepIndex: 0, turnId: "turn_0" },
- type: "step.started",
- },
- messages,
- );
+ expect(startStep).toHaveBeenCalledWith(messages);
});
it("sends the trace conversation ID to Gateway without changing direct-provider options", async () => {
@@ -84,7 +69,7 @@ describe("buildStepHooks", () => {
model: LanguageModel,
cachePath: Parameters<typeof buildStepHooks>[0]["cachePath"],
) =>
- buildStepHooks({ emissionState, marker: undefined, cachePath, session }).prepareStep({
+ buildStepHooks({ marker: undefined, cachePath, session }).prepareStep({
messages: [],
model,
instructions: undefined,
@@ -139,7 +124,6 @@ describe("buildStepHooks", () => {
it("preserves an authored Gateway session ID", async () => {
const hooks = buildStepHooks({
cachePath: { kind: "none" },
- emissionState,
marker: undefined,
session: {
...createSession(),
diff --git a/packages/eve/src/harness/step-hooks.ts b/packages/eve/src/harness/step-hooks.ts
index b391c4807..6360d729d 100644
--- a/packages/eve/src/harness/step-hooks.ts
+++ b/packages/eve/src/harness/step-hooks.ts
@@ -22,8 +22,7 @@ import {
createRuntimeToolResultFromMessagePart,
createRuntimeToolResultFromStepResult,
} from "#harness/action-result-helpers.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
-import { emitStepStarted } from "#harness/emission.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import { normalizeAssistantStepFinishReason } from "#harness/finish-reason.js";
import { extractToolApprovalInputRequests } from "#harness/input-extraction.js";
import {
@@ -86,16 +85,11 @@ export type HarnessStepResult = Pick<
interface StepHooksInput {
readonly auth?: import("#channel/types.js").SessionAuthContext | null;
readonly cachePath: PromptCachePath;
- readonly emit?: HarnessEmitFn;
- readonly emissionState: HarnessEmissionState;
/**
- * When `false`, `onStepStart` skips the `step.started` emission.
- * Used by the harness recovery path to avoid emitting `step.started`
- * twice when retrying the same step with a degraded toolset.
- *
- * Defaults to `true`.
+ * Starts the model step the SDK is about to run. Omitted when the step already started, as
+ * it has for a retry of the same step.
*/
- readonly emitStepStarted?: boolean;
+ readonly startStep?: (messages: readonly ModelMessage[]) => Promise<void>;
readonly marker: AnthropicCacheMarker | undefined;
readonly session: HarnessSession;
}
@@ -107,7 +101,7 @@ interface StepHooks {
/**
* `ToolLoopAgent` `onStepStart` callback.
*
- * Emits the `step.started` event from the prepared step input.
+ * Starts the step from the prepared step input.
*/
readonly onStepStart: GenerateTextOnStepStartCallback<ToolSet>;
@@ -134,7 +128,7 @@ interface StepHooks {
* have been emitted before proceeding to post-step handling.
*
* Resolves once per hooks instance: a retried model call must rebuild
- * hooks via a fresh `runOneModelCall` attempt. Re-running a call against
+ * hooks via a fresh `ModelCaller.call` attempt. Re-running a call against
* hooks whose `stepResult` already resolved reads the previous attempt's
* result, not the retry's.
*
@@ -160,7 +154,6 @@ interface StepHooks {
*/
export function buildStepHooks(input: StepHooksInput): StepHooks {
const session = input.session;
- const emit = input.emit;
let resolveStep: (step: HarnessStepResult) => void;
const stepResult = new Promise<HarnessStepResult>((resolve) => {
@@ -209,14 +202,7 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {
};
const onStepStart: GenerateTextOnStepStartCallback<ToolSet> = async ({ messages }) => {
- if (emit && input.emitStepStarted !== false) {
- await emitStepStarted(
- emit,
- input.emissionState,
- requireSessionModelReference(session).id,
- messages,
- );
- }
+ await input.startStep?.(messages);
};
return {
@@ -250,7 +236,7 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {
*/
export async function emitStepActions(
emitFn: HarnessEmitFn,
- state: HarnessEmissionState,
+ state: TurnPosition,
step: HarnessStepResult,
options: {
readonly emittedActionCallIds?: ReadonlySet<string>;
diff --git a/packages/eve/src/harness/step/after-model.ts b/packages/eve/src/harness/step/after-model.ts
new file mode 100644
index 000000000..c5b6c753a
--- /dev/null
+++ b/packages/eve/src/harness/step/after-model.ts
@@ -0,0 +1,460 @@
+import { stageToolResultMedia } from "#harness/attachment-staging.js";
+import type { ModelMessage, ToolSet, TypedToolCall, TypedToolError } from "ai";
+
+import type { CompactionConfig, StepResult } from "#harness/types.js";
+import {
+ FINAL_OUTPUT_BESIDE_PENDING_CALLS,
+ FINAL_OUTPUT_TOOL_NAME,
+} from "#harness/final-output.js";
+import {
+ type HarnessModelMessage,
+ resolveAssistantStepText,
+ validateHarnessModelMessages,
+} from "#harness/messages.js";
+import type { HarnessStepResult } from "#harness/step-hooks.js";
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import {
+ appendMissingToolResultMessages,
+ extractToolResultCallIds,
+} from "#harness/model-call/response.js";
+import type { ModelResponse } from "#harness/model-call/run.js";
+import type { EndsTurnTools } from "#harness/model-call/tools.js";
+import type { JsonValue } from "#shared/json.js";
+import type { Step } from "#harness/step/context.js";
+import {
+ fail,
+ finishTurn,
+ hold,
+ suspendStep,
+ type ToolResultPart,
+ withResult,
+} from "#harness/session-machine/transitions.js";
+import { clearTurnClientContextState } from "#harness/turn-client-context.js";
+import { collectDeferredCalls } from "#harness/coordination.js";
+import {
+ createToolResultMessagePartFromToolError,
+ isToolResultError,
+} from "#harness/action-result-helpers.js";
+import {
+ extractToolApprovalInputRequests,
+ hasRunnableQueue,
+ parkOnApprovals,
+ stopForToolSignIn,
+} from "#harness/hitl/index.js";
+import { getAdvertisedTools } from "#harness/advertised-tools.js";
+import {
+ getInvalidToolCallInputError,
+ isInvalidToolCall,
+} from "#harness/tool-call-input-errors.js";
+import { isTaskTool, workingTaskIds } from "#execution/tasks/model-step.js";
+import { normalizeProviderToolHistory } from "#harness/provider-tool-history.js";
+import { renderFinalOutputWhileWorkingError } from "#execution/tasks/render.js";
+import { resolveInlineAuthorizationInterrupt } from "#harness/inline-tool-authorization.js";
+import { setRequestEnvelopeTokens } from "#harness/request-envelope.js";
+import { createLogger } from "#internal/logging.js";
+
+const log = createLogger("harness.tool-loop");
+
+function getInvalidToolCallInputErrors(input: {
+ readonly toolCalls: readonly TypedToolCall<ToolSet>[];
+}): readonly TypedToolError<ToolSet>[] {
+ const errors: TypedToolError<ToolSet>[] = [];
+
+ for (const toolCall of input.toolCalls) {
+ if (toolCall.toolName === FINAL_OUTPUT_TOOL_NAME) {
+ continue;
+ }
+
+ const toolError = getInvalidToolCallInputError({ toolCall });
+ if (toolError !== undefined) {
+ errors.push(toolError);
+ }
+ }
+
+ return errors;
+}
+
+export async function handleStepResult(step: Step, input: ModelResponse): Promise<StepResult> {
+ const { promptMessages, result } = input;
+
+ const stepOutput = resolveAssistantStepText(result.response.messages, result.text);
+ const invalidInputToolErrors = getInvalidToolCallInputErrors({
+ toolCalls: result.toolCalls as TypedToolCall<ToolSet>[],
+ });
+ // Unions every invalid-input signal: SDK-marked invalid calls (which get
+ // SDK-synthesized tool errors), non-object inputs caught by
+ // getInvalidToolCallInputErrors, and ids the stream consumer observed.
+ const invalidInputToolCallIds = new Set([
+ ...(result.invalidInputToolCallIds ?? []),
+ ...result.toolCalls.filter(isInvalidToolCall).map((toolCall) => toolCall.toolCallId),
+ ...invalidInputToolErrors.map((toolError) => toolError.toolCallId),
+ ]);
+ const rawResponseMessages = appendMissingToolResultMessages({
+ append: invalidInputToolErrors.map((toolError) =>
+ createToolResultMessagePartFromToolError(toolError),
+ ),
+ responseMessages: result.response.messages,
+ });
+
+ const providerExecutedOutcomeIds = new Set<string>();
+ for (const part of [...(result.content ?? []), ...(result.toolResults ?? [])]) {
+ if (
+ (part.type === "tool-result" || part.type === "tool-error") &&
+ part.providerExecuted === true
+ ) {
+ providerExecutedOutcomeIds.add(part.toolCallId);
+ }
+ }
+ const normalizedProviderHistory = normalizeProviderToolHistory({
+ messages: rawResponseMessages,
+ providerExecutedOutcomeIds,
+ });
+ // eve runs approved calls itself, so the SDK's approval parts never reach history.
+ const responseMessages = await stageToolResultMedia(
+ withoutApprovalParts(normalizedProviderHistory.messages),
+ );
+
+ step.session = setRequestEnvelopeTokens(
+ {
+ ...step.session,
+ compaction: createNextCompactionConfig(
+ step.session.compaction,
+ input.durableModelPromptMessageCount,
+ result,
+ ),
+ },
+ result.usage?.inputTokens !== undefined && input.durableModelPromptMessageCount !== undefined
+ ? input.requestEnvelopeTokens
+ : undefined,
+ );
+
+ const approvalRequests = extractToolApprovalInputRequests({
+ content: result.content ?? [],
+ excludedCallIds: invalidInputToolCallIds,
+ });
+ const advertisedCoordinationTools = getAdvertisedTools({
+ session: step.session,
+ 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 unadvertised: TypedToolCall<ToolSet>[] = [];
+ 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))) {
+ return true;
+ }
+ log.warn("deferred tool call blocked because tool is not advertised", {
+ callId: toolCall.toolCallId,
+ sessionId: step.session.sessionId,
+ toolName: toolCall.toolName,
+ });
+ unadvertised.push(toolCall);
+ return false;
+ });
+
+ // --- Park on approvals or runtime calls ----------------------------------
+
+ if (deferredToolCalls.length > 0 || approvalRequests.length > 0) {
+ const { sequence, stepIndex, turnId } = step.position();
+ const deferred = collectDeferredCalls({
+ session: step.session,
+ toolCalls: deferredToolCalls,
+ tools: advertisedCoordinationTools,
+ turnId,
+ });
+ step.session = { ...deferred.session, history: validateHarnessModelMessages(promptMessages) };
+ const parked = {
+ event: { sequence, stepIndex, turnId },
+ // A suspended response commits once every call it made has a result, so a call that will
+ // never get one is answered now.
+ messages: answerCallsThatWontRun(responseMessages, result, unadvertised),
+ tasks: deferred.workflowRequests,
+ };
+ if (approvalRequests.length > 0) {
+ return parkOnApprovals(step, {
+ ...parked,
+ requests: approvalRequests,
+ waitsOnRuntime: deferredToolCalls.length > 0,
+ });
+ }
+ await step.apply(suspendStep(step.view(), parked));
+ return { next: null, session: step.session };
+ }
+
+ // --- Park on authorization request ------------------------------------------
+
+ const authorizationInterrupt = resolveInlineAuthorizationInterrupt({
+ messages: [...promptMessages, ...responseMessages],
+ toolResults: result.toolResults,
+ });
+ if (authorizationInterrupt) return stopForToolSignIn(step, authorizationInterrupt);
+
+ // --- Continue or terminate ------------------------------------------------
+
+ // History grows by append only; nothing rewrites earlier messages mid-turn,
+ // so the prompt prefix stays stable and the provider's prompt cache keeps
+ // hitting across steps. Compaction is the sole mechanism that ever rewrites
+ // history, and it runs before the model call (see `maybeCompact`).
+ step.session = {
+ ...step.session,
+ history: validateHarnessModelMessages([...promptMessages, ...responseMessages]),
+ };
+
+ // A `final_output` call is terminal even when the model emits it alongside
+ // executing tools: continuing the loop would leave the no-execute call as a
+ // dangling tool_use the next provider call rejects, and drop the result.
+ const calledFinalOutput =
+ step.session.outputSchema !== undefined && extractFinalOutput(result) !== undefined;
+ const workingTasks = workingTaskIds(step.session);
+ const finalOutputRejected = calledFinalOutput && workingTasks.length > 0;
+ let responseTail: readonly ModelMessage[] = responseMessages;
+ if (finalOutputRejected) {
+ responseTail = rejectFinalOutput(responseMessages, result, workingTasks);
+ step.session = {
+ ...step.session,
+ history: validateHarnessModelMessages([...promptMessages, ...responseTail]),
+ };
+ }
+
+ const endsTurn = await stepEndsTurn(result, responseMessages, input.endsTurnTools);
+ const continueLoop =
+ (!calledFinalOutput || finalOutputRejected) &&
+ ((responseTail.at(-1)?.role === "tool" && !endsTurn) ||
+ normalizedProviderHistory.outcomeEndsResponse ||
+ hasRunnableQueue(step.view()));
+ if (continueLoop) return { next: step.runStep, session: step.session };
+ // The turn rule: no turn ends while its tasks work. The session waits for
+ // one to settle, then calls the model again in the same turn.
+ if (workingTasks.length > 0) {
+ await step.apply(hold(step.view(), { on: "tasks" }));
+ return { held: { kind: "tasks", taskIds: workingTasks }, next: null, session: step.session };
+ }
+
+ return settleTurn(step, {
+ history: promptMessages,
+ result,
+ // Text written before an `endsTurn` call was narration, not the reply.
+ stepOutput: endsTurn ? null : stepOutput,
+ });
+}
+
+/**
+ * Answers the calls of a response that waits on others which will never get a result: a
+ * `final_output` written before the results it waits beside, and a deferred call to a tool this
+ * step didn't advertise.
+ */
+function answerCallsThatWontRun(
+ messages: readonly ModelMessage[],
+ result: HarnessStepResult,
+ unadvertised: readonly TypedToolCall<ToolSet>[],
+): ModelMessage[] {
+ const answered = extractToolResultCallIds(messages);
+ const finalOutputs = ((result.toolCalls ?? []) as TypedToolCall<ToolSet>[]).filter(
+ (call) => call.toolName === FINAL_OUTPUT_TOOL_NAME,
+ );
+ const answers: ToolResultPart[] = [
+ ...finalOutputs.map((call) => ({
+ output: { type: "error-text" as const, value: FINAL_OUTPUT_BESIDE_PENDING_CALLS },
+ toolCallId: call.toolCallId,
+ toolName: call.toolName,
+ type: "tool-result" as const,
+ })),
+ ...unadvertised.map((call) => ({
+ output: {
+ type: "error-text" as const,
+ value: `The tool "${call.toolName}" isn't available in this step, so the call didn't run.`,
+ },
+ toolCallId: call.toolCallId,
+ toolName: call.toolName,
+ type: "tool-result" as const,
+ })),
+ ];
+ return answers
+ .filter((part) => !answered.has(part.toolCallId))
+ .reduce<ModelMessage[]>((next, part) => withResult(next, part), [...messages]);
+}
+
+/** The SDK's approval parts: eve answers approvals itself, so history never holds them. */
+export function withoutApprovalParts(messages: readonly ModelMessage[]): ModelMessage[] {
+ return messages.flatMap((message): ModelMessage[] => {
+ if (message.role !== "assistant" && message.role !== "tool") return [message];
+ if (!Array.isArray(message.content)) return [message];
+ const content = message.content.filter(
+ (part) => part.type !== "tool-approval-request" && part.type !== "tool-approval-response",
+ );
+ return content.length === 0 ? [] : [{ ...message, content } as ModelMessage];
+ });
+}
+
+/**
+ * Whether the step ends the turn: every tool call targets a tool that can end
+ * the turn and succeeded, and each `endsTurn` function accepts its call's
+ * `execute` output. A failed or invalid call lets the model recover instead.
+ */
+async function stepEndsTurn(
+ result: HarnessStepResult,
+ responseMessages: readonly ModelMessage[],
+ endsTurnTools: EndsTurnTools,
+): Promise<boolean> {
+ const toolCalls = result.toolCalls ?? [];
+ if (toolCalls.length === 0) return false;
+ const outputs = new Map<string, ToolResultPart["output"]>();
+ for (const message of responseMessages) {
+ if (message.role !== "tool") continue;
+ for (const part of message.content) {
+ if (part.type === "tool-result") outputs.set(part.toolCallId, part.output);
+ }
+ }
+ const succeeded = toolCalls.every((toolCall) => {
+ const output = outputs.get(toolCall.toolCallId);
+ return (
+ endsTurnTools.has(toolCall.toolName) && output !== undefined && !isToolResultError(output)
+ );
+ });
+ if (!succeeded) return false;
+ const executeOutputs = new Map(
+ (result.toolResults ?? []).map((toolResult) => [toolResult.toolCallId, toolResult.output]),
+ );
+ for (const toolCall of toolCalls) {
+ const endsTurn = endsTurnTools.get(toolCall.toolName);
+ if (typeof endsTurn !== "function") continue;
+ if (!(await callEndsTurn(endsTurn, executeOutputs.get(toolCall.toolCallId), toolCall))) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/** A throwing `endsTurn` function keeps the turn going rather than failing it. */
+async function callEndsTurn(
+ endsTurn: (output: unknown) => boolean | Promise<boolean>,
+ output: unknown,
+ toolCall: { readonly toolCallId: string; readonly toolName: string },
+): Promise<boolean> {
+ try {
+ return (await endsTurn(output)) === true;
+ } catch (error) {
+ log.warn("endsTurn threw; continuing the turn", {
+ callId: toolCall.toolCallId,
+ error,
+ toolName: toolCall.toolName,
+ });
+ return false;
+ }
+}
+
+function isDeferredHarnessTool(tool: HarnessToolDefinition | undefined): boolean {
+ return tool?.workflowId !== undefined || isTaskTool(tool);
+}
+
+/** Answers a `final_output` call made while tasks work with an error naming them. */
+function rejectFinalOutput(
+ responseMessages: readonly ModelMessage[],
+ result: HarnessStepResult,
+ workingTasks: readonly string[],
+): ModelMessage[] {
+ const call = (result.toolCalls ?? []).find(
+ (toolCall) => toolCall.toolName === FINAL_OUTPUT_TOOL_NAME,
+ );
+ if (call === undefined) return [...responseMessages];
+ const rejection: ToolResultPart = {
+ output: { type: "error-text", value: renderFinalOutputWhileWorkingError(workingTasks) },
+ toolCallId: call.toolCallId,
+ toolName: FINAL_OUTPUT_TOOL_NAME,
+ type: "tool-result",
+ };
+ return [...responseMessages, { content: [rejection], role: "tool" }];
+}
+
+const OUTPUT_SCHEMA_NOT_FULFILLED = {
+ code: "OUTPUT_SCHEMA_NOT_FULFILLED",
+ message: "The agent could not produce a result matching the requested schema.",
+} as const;
+
+/**
+ * The structured value the model delivered by calling the framework
+ * `final_output` tool, or `undefined` when the terminal turn ended in prose.
+ */
+function extractFinalOutput(result: HarnessStepResult): JsonValue | undefined {
+ return (result.toolCalls ?? []).find(
+ (call) => call.toolName === FINAL_OUTPUT_TOOL_NAME && !isInvalidToolCall(call),
+ )?.input as JsonValue | undefined;
+}
+
+/**
+ * Closes a terminal turn. An unmet output schema fails the turn recoverably;
+ * otherwise the structured value (or prose) ends the turn and the session
+ * waits for the next message. The structured value replaces the un-executed
+ * `final_output` call, which would be a dangling tool_use on the next turn,
+ * and the schema, scoped to the turn, clears.
+ */
+async function settleTurn(
+ step: Step,
+ input: {
+ readonly history: readonly HarnessModelMessage[];
+ readonly result: HarnessStepResult;
+ readonly stepOutput: string | null;
+ },
+): Promise<StepResult> {
+ const { history, result, stepOutput } = input;
+ const schema = step.session.outputSchema;
+ step.session = clearTurnClientContextState(step.session);
+
+ if (schema === undefined) {
+ await step.apply(finishTurn(step.view()), step.session.history);
+ return { next: null, session: step.session, settledTurn: { output: stepOutput ?? "" } };
+ }
+
+ const structured = extractFinalOutput(result);
+ // The schema belongs to the settled turn. A later conversation turn that
+ // omits outputSchema must not inherit its contract.
+ if (structured === undefined) {
+ step.session = { ...step.session, outputSchema: undefined };
+ await step.apply(fail(step.view(), OUTPUT_SCHEMA_NOT_FULFILLED));
+ return {
+ next: null,
+ session: step.session,
+ settledTurn: { isError: true, output: OUTPUT_SCHEMA_NOT_FULFILLED.message },
+ };
+ }
+
+ step.session = {
+ ...step.session,
+ history: [...history, { content: JSON.stringify(structured), role: "assistant" }],
+ outputSchema: undefined,
+ };
+ await step.apply(finishTurn(step.view(), { result: structured }), step.session.history);
+ return { next: null, session: step.session, settledTurn: { output: structured } };
+}
+
+function createNextCompactionConfig(
+ current: CompactionConfig,
+ durablePromptMessageCount: number | undefined,
+ result: HarnessStepResult,
+): CompactionConfig {
+ const next: {
+ lastKnownInputTokens?: number;
+ lastKnownPromptMessageCount?: number;
+ recentWindowSize: number;
+ threshold: number;
+ thresholdPercent?: number;
+ } = {
+ recentWindowSize: current.recentWindowSize,
+ threshold: current.threshold,
+ thresholdPercent: current.thresholdPercent,
+ };
+
+ if (result.usage?.inputTokens !== undefined && durablePromptMessageCount !== undefined) {
+ next.lastKnownInputTokens = result.usage.inputTokens;
+ next.lastKnownPromptMessageCount = durablePromptMessageCount;
+ }
+
+ return next;
+}
diff --git a/packages/eve/src/harness/step/context.ts b/packages/eve/src/harness/step/context.ts
new file mode 100644
index 000000000..0f7ef622c
--- /dev/null
+++ b/packages/eve/src/harness/step/context.ts
@@ -0,0 +1,198 @@
+import type { ModelMessage } from "ai";
+
+import type { AlsContext } from "#context/container.js";
+import {
+ drainDynamicInstructionUserMessages,
+ prepareDynamicInstructionPreamble,
+} from "#context/dynamic-instruction-lifecycle.js";
+import { isDynamicModelSelectionError } from "#context/dynamic-model-lifecycle.js";
+import { ParentSessionKey, SessionCallbackKey } from "#context/keys.js";
+import { drainMemoryCommit, prepareMemoryPreamble } from "#context/memory-lifecycle.js";
+import { type HarnessModelMessage, validateHarnessModelMessages } from "#harness/messages.js";
+import {
+ applyTransition,
+ type Publish,
+ sessionView,
+ type Transition,
+} from "#harness/session-machine/commit.js";
+import type { StepProjection } from "#harness/session-machine/current.js";
+import { fail, receive } from "#harness/session-machine/transitions.js";
+import {
+ activeTurnId,
+ type SessionView,
+ turnPosition,
+ type TurnPosition,
+} from "#harness/session-machine/view.js";
+import { isTurnCancellation, throwIfTurnAborted } from "#harness/turn-cancellation.js";
+import type {
+ HarnessEmitFn,
+ HarnessSession,
+ StepFn,
+ StepInput,
+ StepResult,
+ ToolLoopHarnessConfig,
+} from "#harness/types.js";
+import type { InstrumentationStepScope } from "#instrumentation/runtime.js";
+import { createErrorId, createLogger } from "#internal/logging.js";
+import { toErrorMessage } from "#shared/errors.js";
+import type { createHistoryViewPreparer } from "#shared/history-view.js";
+
+type HistoryViewPreparer = ReturnType<typeof createHistoryViewPreparer>;
+
+const log = createLogger("harness.step");
+
+/**
+ * One harness step: the session it changes, and the machine it changes the session through.
+ * Every lifecycle change goes through `apply`, which publishes the transition's events and saves
+ * what it changed; `position` reads where those events left the session.
+ */
+export interface Step {
+ session: HarnessSession;
+ frameworkToolNames: ReadonlySet<string>;
+ readonly config: ToolLoopHarnessConfig;
+ /** The step's context; direct harness tests may run without one. */
+ readonly ctx: AlsContext | undefined;
+ readonly runStep: StepFn;
+ readonly publish: Publish;
+ /** The caller's event handler. Without one, a failure throws instead of being reported. */
+ readonly emit: HarnessEmitFn | undefined;
+ readonly instrumentation: InstrumentationStepScope<HarnessSession> | undefined;
+ /** A child's caller or a schedule hears only the turn's real end. */
+ readonly hasDelegatedCaller: boolean;
+ view(): SessionView;
+ position(): TurnPosition;
+ apply(transition: Transition, messages?: readonly ModelMessage[]): Promise<void>;
+ /** History as the model and hooks see it, under `state`, the session's by default. */
+ projectHistory(
+ messages: readonly ModelMessage[],
+ state?: HarnessSession["state"],
+ ): readonly ModelMessage[];
+}
+
+export function createStep(input: {
+ readonly config: ToolLoopHarnessConfig;
+ readonly ctx: AlsContext | undefined;
+ readonly emit: HarnessEmitFn | undefined;
+ readonly instrumentation: InstrumentationStepScope<HarnessSession> | undefined;
+ readonly live: StepProjection;
+ readonly prepareHistory: HistoryViewPreparer;
+ readonly publish: Publish;
+ readonly runStep: StepFn;
+ readonly session: HarnessSession;
+}): Step {
+ const { ctx, live } = input;
+ const step: Step = {
+ session: input.session,
+ frameworkToolNames: new Set(),
+ config: input.config,
+ ctx,
+ runStep: input.runStep,
+ publish: input.publish,
+ emit: input.emit,
+ instrumentation: input.instrumentation,
+ hasDelegatedCaller:
+ ctx?.get(ParentSessionKey) !== undefined || ctx?.get(SessionCallbackKey) !== undefined,
+ view: () => sessionView(live.read(), step.session.state),
+ position: () => turnPosition(live.read()),
+ async apply(transition, messages) {
+ step.session = await applyTransition(step.session, transition, input.publish, messages);
+ },
+ projectHistory: (messages, state = step.session.state) =>
+ input.prepareHistory(messages, state).messages,
+ };
+ return step;
+}
+
+/**
+ * Opens the turn, or joins the open one, with the preamble its hooks prepare: memory recall and
+ * dynamic instructions join history ahead of the turn's input. Returns the step's result when the
+ * preamble failed the session.
+ */
+export async function openTurn(
+ step: Step,
+ opened: {
+ readonly input: readonly HarnessModelMessage[];
+ readonly message?: StepInput["message"];
+ },
+): Promise<StepResult | undefined> {
+ const { config, ctx } = step;
+ if (ctx !== undefined) {
+ prepareDynamicInstructionPreamble(ctx, step.projectHistory(step.session.history));
+ prepareMemoryPreamble(ctx, {
+ history: step.session.history,
+ input: [...opened.input],
+ projector: config.historyProjector,
+ state: step.session.state,
+ });
+ }
+ let failure: { readonly error: unknown } | undefined;
+ try {
+ const position = step.position();
+ const trace = await step.instrumentation?.preparePreamble({
+ sequence: position.sequence,
+ sessionStarted: position.sessionStarted,
+ traceContext: step.instrumentation?.traceContext,
+ turnId: activeTurnId(position),
+ });
+ await step.apply(
+ receive(step.view(), { message: opened.message, runtime: config.runtimeIdentity, trace }),
+ step.projectHistory([...step.session.history, ...opened.input]),
+ );
+ } catch (error) {
+ failure = { error };
+ }
+ // The hooks' pending state drains even when the preamble failed.
+ const instructionMessages = ctx === undefined ? [] : drainDynamicInstructionUserMessages(ctx);
+ const memoryCommit = ctx === undefined ? undefined : drainMemoryCommit(ctx);
+ step.session = {
+ ...step.session,
+ history: validateHarnessModelMessages([
+ ...step.session.history,
+ ...(memoryCommit?.recalledMessages ?? []),
+ ...instructionMessages,
+ ]),
+ state: memoryCommit?.state ?? step.session.state,
+ };
+ if (failure !== undefined) return failBoundaryEvent(step, failure.error);
+ step.instrumentation?.setTurnId(step.position().turnId);
+ return undefined;
+}
+
+/** A lifecycle event failed to publish: only a dynamic model selection failure is reported. */
+export async function failBoundaryEvent(step: Step, error: unknown): Promise<StepResult> {
+ throwIfTurnAborted(step.config.abortSignal);
+ if (isTurnCancellation(error)) throw error;
+ if (isDynamicModelSelectionError(error)) return failModelSelection(step, error);
+ throw error;
+}
+
+/** No model can serve the turn: the session fails. */
+export async function failModelSelection(step: Step, error: unknown): Promise<StepResult> {
+ throwIfTurnAborted(step.config.abortSignal);
+ step.instrumentation?.recordError(error);
+ if (step.emit === undefined) throw error;
+
+ const errorId = createErrorId();
+ const message = toErrorMessage(error);
+ const { session } = step;
+ log.error("model selection failed terminally", {
+ error,
+ errorId,
+ sessionId: session.sessionId,
+ turnId: activeTurnId(step.position()),
+ });
+ await step.apply(
+ fail(step.view(), {
+ code: "MODEL_SELECTION_FAILED",
+ details: { errorId },
+ message,
+ terminal: { sessionId: session.sessionId },
+ }),
+ );
+ return {
+ next: step.hasDelegatedCaller
+ ? { done: true, isError: true, output: message }
+ : { done: true, output: "" },
+ session: step.session,
+ };
+}
diff --git a/packages/eve/src/harness/step/intake.ts b/packages/eve/src/harness/step/intake.ts
new file mode 100644
index 000000000..70f46900e
--- /dev/null
+++ b/packages/eve/src/harness/step/intake.ts
@@ -0,0 +1,117 @@
+import { stageAttachmentsToSandbox, stageToolResultMedia } from "#harness/attachment-staging.js";
+import { forgetFinishedRuns, runtimeResultCalls } from "#harness/coordination.js";
+import {
+ createFrameworkUserMessage,
+ createUserMessage,
+ frameworkMessageKindForStepInput,
+ type HarnessModelMessage,
+ normalizeUserContent,
+ TOOL_RESULT_BOUNDARY,
+ type UserModelMessage,
+} from "#harness/messages.js";
+import { finishRun, settle } from "#harness/session-machine/transitions.js";
+import { activeTurnId, runtimeWait } from "#harness/session-machine/view.js";
+import { getTurnClientContextState } from "#harness/turn-client-context.js";
+import type { StepInput } from "#harness/types.js";
+import { readClientContext } from "#internal/client-context.js";
+import { resolveRuntimeActionResultsForCallIds } from "#runtime/actions/results.js";
+import type { Step } from "./context.js";
+
+/**
+ * Settles the calls the runtime ran for parked steps. Returns `undefined` while some are still
+ * running: input queued behind them waits until they have. Otherwise returns the step's input
+ * without the results it settled, and whether the step waited on any.
+ */
+export async function settleRuntimeWork(
+ step: Step,
+ input: StepInput | undefined,
+): Promise<{ readonly input: StepInput | undefined; readonly waited: boolean } | undefined> {
+ const runtime = runtimeWait(step.session.state);
+ if (runtime === undefined) return { input, waited: false };
+ const ready = resolveRuntimeActionResultsForCallIds({
+ pendingCallIds: runtime.callIds,
+ results: input?.runtimeActionResults ?? [],
+ });
+ if (ready === undefined) return undefined;
+ const finished = forgetFinishedRuns(step.session, ready, runtime.event.turnId);
+ step.session = finished.session;
+ await step.apply(finishRun(step.view(), { requestIds: finished.requestIds }));
+ const results = await runtimeResultCalls(ready, step.config.tools);
+ const staged = await stageToolResultMedia([
+ { role: "tool", content: results.map(({ part }) => part) },
+ ]);
+ const parts = staged.flatMap((message) =>
+ message.role === "tool" ? message.content.filter((part) => part.type === "tool-result") : [],
+ );
+ await step.apply(
+ settle(step.view(), {
+ results: results.map((result, index) => ({ ...result, part: parts[index]! })),
+ }),
+ );
+ if (input === undefined) return { input, waited: true };
+ const { runtimeActionResults: _results, ...rest } = input;
+ return { input: rest, waited: true };
+}
+
+/** The turn's input as the model reads it. */
+export interface TurnInput {
+ readonly turnId: string;
+ /** Context the client sent for this turn, which never joins history. */
+ readonly clientContext: readonly string[] | undefined;
+ readonly storedClientContext: ReturnType<typeof getTurnClientContextState>;
+ readonly ephemeral: readonly UserModelMessage[];
+ /** The context entries and the message, in history order. */
+ readonly messages: readonly UserModelMessage[];
+ /** The input carries a user's message, which follows tool results across a boundary. */
+ readonly hasUserMessage: boolean;
+}
+
+/**
+ * Prepares the turn's input: client and context entries, and the message with its attachments
+ * staged to the sandbox. A message a plain-text answer consumed never reaches the model.
+ */
+export async function prepareTurnInput(
+ step: Step,
+ input: StepInput | undefined,
+ options: { readonly consumedMessage: boolean },
+): Promise<TurnInput> {
+ const turnId = activeTurnId(step.position());
+ const storedClientContext = getTurnClientContextState(step.session.state, turnId);
+ const clientContext = readClientContext(input);
+ const ephemeral =
+ (clientContext ?? storedClientContext?.messages)?.map((content) =>
+ createFrameworkUserMessage("context.instruction", content),
+ ) ?? [];
+ const messages: UserModelMessage[] = (input?.context ?? []).map((entry) =>
+ createFrameworkUserMessage("context.instruction", entry),
+ );
+ const kind = frameworkMessageKindForStepInput(input);
+ const content = normalizeUserContent(input?.message);
+ const staged =
+ content !== undefined && !options.consumedMessage
+ ? await stageAttachmentsToSandbox(content)
+ : undefined;
+ if (staged !== undefined) {
+ messages.push(
+ kind === undefined
+ ? createUserMessage("user", staged)
+ : createFrameworkUserMessage(kind, staged),
+ );
+ }
+ return {
+ clientContext,
+ ephemeral,
+ hasUserMessage: staged !== undefined && kind === undefined,
+ messages,
+ storedClientContext,
+ turnId,
+ };
+}
+
+/** The turn's input as it follows tool results: a user message needs a boundary before it. */
+export function followingToolResults(turn: TurnInput): HarnessModelMessage[] {
+ return [
+ ...(turn.hasUserMessage ? [{ content: TOOL_RESULT_BOUNDARY, role: "assistant" } as const] : []),
+ ...turn.messages,
+ ];
+}
diff --git a/packages/eve/src/harness/step/prompt.ts b/packages/eve/src/harness/step/prompt.ts
new file mode 100644
index 000000000..f66e64e22
--- /dev/null
+++ b/packages/eve/src/harness/step/prompt.ts
@@ -0,0 +1,140 @@
+import { appendTaskContext } from "#execution/tasks/model-step.js";
+import {
+ createFrameworkUserMessage,
+ followsToolResults,
+ type HarnessModelMessage,
+ normalizeModelMessages,
+ validateHarnessModelMessages,
+} from "#harness/messages.js";
+import { hasUnansweredToolCall } from "#harness/model-call/response.js";
+import {
+ getTurnClientContextState,
+ setTurnClientContextState,
+} from "#harness/turn-client-context.js";
+import type { Step } from "./context.js";
+import { followingToolResults, type TurnInput } from "./intake.js";
+
+type ClientContext = NonNullable<ReturnType<typeof getTurnClientContextState>>;
+
+/**
+ * What the model reads this step: durable history, with the task results and notes the step
+ * delivers and the turn's input, and the client's context for the turn, which keeps one position
+ * across the turn's steps and never joins history.
+ */
+export interface Prompt {
+ /** Durable messages. Compaction may rewrite them. */
+ messages: HarnessModelMessage[];
+ clientContext: ClientContext | undefined;
+}
+
+export async function buildPrompt(step: Step, turn: TurnInput): Promise<Prompt> {
+ const messages = validateHarnessModelMessages([...step.session.history]);
+ if (!hasUnansweredToolCall(messages)) {
+ const taskContext = await appendTaskContext({
+ messages,
+ projectHistory: step.projectHistory,
+ session: step.session,
+ tools: step.config.tools,
+ });
+ step.session = taskContext.session;
+ messages.push(...taskContext.messages);
+ }
+
+ const placed = placeTurnInput(step, messages, turn);
+ return {
+ clientContext: getTurnClientContextState(step.session.state, turn.turnId),
+ messages: placed,
+ };
+}
+
+/**
+ * The prompt a step starts on while approved calls wait to run: history and the turn's input,
+ * without the task results and the client context's position a prompt settles, which wait for
+ * the prompt the model reads once the calls have run.
+ */
+export function previewPrompt(step: Step, turn: TurnInput): Prompt {
+ const messages = validateHarnessModelMessages([...step.session.history]);
+ return {
+ clientContext: turnClientContext(messages, turn),
+ messages: withTurnInput(messages, turn),
+ };
+}
+
+/**
+ * The turn's input after `messages`, past a tool-result boundary when they end in tool results.
+ * The client's context takes its position here, and never joins the messages.
+ */
+export function placeTurnInput(
+ step: Step,
+ messages: readonly HarnessModelMessage[],
+ turn: TurnInput,
+): HarnessModelMessage[] {
+ const clientContext = turnClientContext(messages, turn);
+ if (clientContext !== undefined) {
+ step.session = setTurnClientContextState(step.session, clientContext);
+ }
+ return withTurnInput(messages, turn);
+}
+
+function turnClientContext(
+ messages: readonly HarnessModelMessage[],
+ turn: TurnInput,
+): ClientContext | undefined {
+ if (turn.clientContext === undefined) return turn.storedClientContext;
+ return {
+ insertionIndex: turn.storedClientContext?.insertionIndex ?? messages.length,
+ messages: turn.clientContext,
+ turnId: turn.turnId,
+ };
+}
+
+function withTurnInput(
+ messages: readonly HarnessModelMessage[],
+ turn: TurnInput,
+): HarnessModelMessage[] {
+ return [
+ ...messages,
+ ...(followsToolResults(messages) ? followingToolResults(turn) : turn.messages),
+ ];
+}
+
+/** `messages`, the prompt's by default, with the client's context at its position. */
+export function withClientContext(
+ prompt: Prompt,
+ messages: readonly HarnessModelMessage[] = prompt.messages,
+): HarnessModelMessage[] {
+ const { clientContext } = prompt;
+ if (clientContext === undefined || clientContext.messages.length === 0) return [...messages];
+ const insertionIndex = Math.min(Math.max(0, clientContext.insertionIndex), messages.length);
+ return [
+ ...messages.slice(0, insertionIndex),
+ ...clientContext.messages.map((content) =>
+ createFrameworkUserMessage("context.instruction", content),
+ ),
+ ...messages.slice(insertionIndex),
+ ];
+}
+
+/** The prompt as the model reads it: with the client's context, projected for its history view. */
+export function projectPrompt(step: Step, prompt: Prompt): HarnessModelMessage[] {
+ return validateHarnessModelMessages(
+ normalizeModelMessages(step.projectHistory(withClientContext(prompt))),
+ );
+}
+
+/**
+ * Compaction rewrote the durable messages: the client's context keeps its distance from the end,
+ * so it stays after the turn's input.
+ */
+export function compactPrompt(step: Step, prompt: Prompt, messages: HarnessModelMessage[]): void {
+ const { clientContext } = prompt;
+ if (clientContext !== undefined) {
+ const tail = Math.max(0, prompt.messages.length - clientContext.insertionIndex);
+ prompt.clientContext = {
+ ...clientContext,
+ insertionIndex: Math.max(0, messages.length - tail),
+ };
+ step.session = setTurnClientContextState(step.session, prompt.clientContext);
+ }
+ prompt.messages = messages;
+}
diff --git a/packages/eve/src/harness/tool-call-action.test.ts b/packages/eve/src/harness/tool-call-action.test.ts
new file mode 100644
index 000000000..8cefff2ca
--- /dev/null
+++ b/packages/eve/src/harness/tool-call-action.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+
+import { createRuntimeToolCallActionFromToolCall } from "#harness/tool-call-action.js";
+
+describe("createRuntimeToolCallActionFromToolCall", () => {
+ it("creates a tool-call action from a typed tool call", () => {
+ const result = createRuntimeToolCallActionFromToolCall({
+ toolCall: {
+ toolCallId: "call-123",
+ toolName: "bash",
+ input: { command: "ls -la" },
+ type: "tool-call",
+ } as never,
+ });
+
+ expect(result).toEqual({
+ callId: "call-123",
+ input: { command: "ls -la" },
+ kind: "tool-call",
+ toolName: "bash",
+ });
+ });
+
+ it("defaults to empty object when input is undefined", () => {
+ const result = createRuntimeToolCallActionFromToolCall({
+ toolCall: {
+ toolCallId: "call-456",
+ toolName: "read_file",
+ input: undefined,
+ type: "tool-call",
+ } as never,
+ });
+
+ expect(result.input).toEqual({});
+ });
+
+ it("omits undefined properties from tool call input objects", () => {
+ const result = createRuntimeToolCallActionFromToolCall({
+ toolCall: {
+ toolCallId: "call-789",
+ toolName: "read_file",
+ input: {
+ path: "/workspace/foo.txt",
+ startLine: undefined,
+ },
+ type: "tool-call",
+ } as never,
+ });
+
+ expect(result.input).toEqual({
+ path: "/workspace/foo.txt",
+ });
+ });
+
+ it("includes the tool name when tool call input is not a JSON object", () => {
+ expect(() =>
+ createRuntimeToolCallActionFromToolCall({
+ toolCall: {
+ toolCallId: "call-123",
+ toolName: "bash",
+ input: [],
+ type: "tool-call",
+ } as never,
+ }),
+ ).toThrow(
+ 'Failed to parse tool-call arguments for "bash" (call-123): Expected a JSON-serializable object.',
+ );
+ });
+});
diff --git a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
index 83abc37a9..0ae6bad01 100644
--- a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
+++ b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
@@ -2,7 +2,7 @@ import { getRequestEnvelopeTokens } from "#harness/request-envelope.js";
import { generateText, jsonSchema, type LanguageModel, ToolLoopAgent } from "ai";
import { afterEach, describe, expect, it, vi } from "vitest";
-import { appendPendingInputBatch } from "#harness/input-requests.js";
+import { withParkedStep } from "#internal/testing/session-machine.js";
import { validateHarnessModelMessages } from "#harness/messages.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import type { HarnessSession, StepFn, StepNext, ToolLoopHarnessConfig } from "#harness/types.js";
@@ -17,10 +17,10 @@ import {
// be written; the attribute contract is covered by emit.test.ts.
vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async () => {}) }));
-vi.mock("ai", () => ({
+vi.mock("ai", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("ai")>()),
generateText: vi.fn(),
ToolLoopAgent: vi.fn(),
- jsonSchema: vi.fn((schema: unknown) => schema),
isStepCount: vi.fn((value: number) => value),
tool: vi.fn((definition: unknown) => definition),
}));
@@ -330,7 +330,7 @@ describe("tool-loop structured compaction accounting", () => {
});
});
- it("counts synthesized pending-input tool responses when checking for compaction", async () => {
+ it("counts an approved call's committed step when checking for compaction", async () => {
vi.mocked(generateText).mockResolvedValue({
text: "summary",
} as Awaited<ReturnType<typeof generateText>>);
@@ -347,29 +347,23 @@ describe("tool-loop structured compaction accounting", () => {
},
]);
- const runStep = createToolLoopHarness(createTestConfig());
- const session = appendPendingInputBatch({
- requests: [
- {
- action: {
- callId: "call-1",
- input: { command: "pwd" },
- kind: "tool-call",
- toolName: "bash",
- },
- allowFreeform: false,
- display: "confirmation",
- kind: "tool-approval",
- options: [
- { id: "approve", label: "Yes" },
- { id: "cancel", label: "No" },
+ const runStep = createToolLoopHarness(
+ createTestConfig({
+ tools: new Map([
+ [
+ "bash",
+ {
+ description: "Run shell commands",
+ execute: vi.fn().mockResolvedValue("/workspace"),
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "bash",
+ },
],
- prompt: "Approve tool call: bash",
- requestId: "approval-1",
- },
- ],
- responseMessages: [],
- session: createTestSession({
+ ]),
+ }),
+ );
+ const session = withParkedStep(
+ createTestSession({
compaction: {
lastKnownInputTokens: 100,
lastKnownPromptMessageCount: 1,
@@ -378,7 +372,41 @@ describe("tool-loop structured compaction accounting", () => {
},
history: [{ content: "Previous exact prompt", kind: "user", role: "user" }],
}),
- });
+ {
+ messages: [
+ {
+ content: [
+ {
+ input: { command: "pwd" },
+ toolCallId: "call-1",
+ toolName: "bash",
+ type: "tool-call",
+ },
+ ],
+ role: "assistant",
+ },
+ ],
+ requests: [
+ {
+ action: {
+ callId: "call-1",
+ input: { command: "pwd" },
+ kind: "tool-call",
+ toolName: "bash",
+ },
+ allowFreeform: false,
+ display: "confirmation",
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Yes" },
+ { id: "cancel", label: "No" },
+ ],
+ prompt: "Approve tool call: bash",
+ requestId: "approval-1",
+ },
+ ],
+ },
+ );
const result = await runStep(session, {
inputResponses: [
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 3c1682e94..4622d8620 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
@@ -5,13 +5,9 @@ import {
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 } from "ai";
+import { jsonSchema, type LanguageModel, type ModelMessage, type Telemetry } from "ai";
import { MockLanguageModelV4 } from "ai/test";
+import type { InstrumentationAttemptScope } from "#instrumentation/lifecycle.js";
import { describe, expect, it, vi } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
import {
@@ -29,17 +25,40 @@ import {
TurnDynamicToolMetadataKey,
StepDynamicToolMetadataKey,
} from "#context/keys.js";
-import { setHarnessEmissionState } from "#harness/emission.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { InputRequest } from "#shared/input.js";
-import { appendPendingInputBatch, getApprovedTools } from "#harness/input-requests.js";
import type { HarnessModelMessage } from "#harness/messages.js";
-import { getPendingInputBatches } from "#harness/pending-input-batches.js";
-import { createToolLoopHarness } from "#harness/tool-loop.js";
+import { createToolLoopHarness as createHarness } from "#harness/tool-loop.js";
+import { enterSessionProjection } from "#harness/session-machine/current.js";
+import type { StepFn } from "#harness/types.js";
+import {
+ foldingHandler,
+ grantedKeys,
+ parkedSteps,
+ withOpenTurn,
+ withParkedStep,
+} from "#internal/testing/session-machine.js";
+
+/** Runs each harness call as a durable step: a context that enters, and folds, the projection. */
+function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
+ const harness = createHarness({ ...config, handleEvent: foldingHandler(config.handleEvent) });
+ const step: StepFn = async (session, input) => {
+ const ctx =
+ (contextStorage.getStore() as ContextContainer | undefined) ?? createApprovalContext();
+ enterSessionProjection(ctx, session.state);
+ const result = await contextStorage.run(ctx, () => harness(session, input));
+ return { ...result, next: typeof result.next === "function" ? step : result.next };
+ };
+ return step;
+}
+import { openInputs } from "#protocol/session-projection.js";
+import { storedProjection } from "#harness/session-machine/view.js";
import { setTurnUsageState } from "#harness/turn-tag-state.js";
import type { HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
import { once } from "#tools/approval/policies.js";
import { defineTool } from "#tools/definition.js";
+import { defineJsonSchema } from "#tools/schema.js";
+import { z } from "#compiled/zod/index.js";
import {
registerDurableDynamicCallback,
stampDurableDynamicCallback,
@@ -117,23 +136,20 @@ function createPendingApprovalSession(
history?: readonly HarnessModelMessage[],
responseAuthorization = false,
): HarnessSession {
- return appendPendingInputBatch({
+ return withParkedStep(createBaseSession(history), {
+ event: { sequence: 1, stepIndex: 0, turnId: "turn-1" },
+ messages: [{ content: [toolCall, approvalRequest], role: "assistant" }],
requests: [pendingApprovalInputRequest],
responseAuthRequiredRequestIds: responseAuthorization
? [approvalRequest.approvalId]
: undefined,
- responseMessages: [
- {
- content: [toolCall, approvalRequest],
- role: "assistant",
- },
- ],
- session: createBaseSession(history),
});
}
function createTwoPendingApprovalSession(): HarnessSession {
- return appendPendingInputBatch({
+ return withParkedStep(createPendingApprovalSession(), {
+ event: { sequence: 2, stepIndex: 0, turnId: "turn-2" },
+ messages: [{ content: [secondToolCall, secondApprovalRequest], role: "assistant" }],
requests: [
{
action: {
@@ -153,76 +169,12 @@ function createTwoPendingApprovalSession(): HarnessSession {
requestId: secondApprovalRequest.approvalId,
},
],
- responseMessages: [
- {
- content: [secondToolCall, secondApprovalRequest],
- role: "assistant",
- },
- ],
- session: createPendingApprovalSession(),
});
}
-/** Runs a `turn.started` memory recall and a user-role dynamic instruction, as in #3899. */
-function createMemoryInstructionPreamble(
- ctx: ContextContainer,
- recalledMessages: readonly { readonly content: string; readonly id: string }[],
-) {
- const recall = vi.fn(async () => ({ messages: [...recalledMessages] }));
- const instruction = vi.fn(() =>
- defineInstructions({
- content: "Current date and time: 2026-09-28T00:00:00.000Z (UTC).",
- role: "user",
- }),
- );
- const memories = [
- {
- ...defineMemory({
- namespace: "issue-3899",
- provider: { recall: { "turn.started": recall } },
- scope: "user-1",
- }),
- logicalPath: "memory/profile.ts",
- slot: "profile",
- sourceId: "memory/profile.ts",
- sourceKind: "module" as const,
- visibility: "scope" as const,
- },
- ];
- const resolvers = [
- {
- eventNames: ["turn.started"],
- events: { "turn.started": instruction },
- logicalPath: "instructions/timestamp.ts",
- slug: "timestamp",
- sourceId: "instructions/timestamp.ts",
- sourceKind: "module" as const,
- },
- ];
- const handleEvent: NonNullable<ToolLoopHarnessConfig["handleEvent"]> = async (
- event,
- messages,
- ) => {
- const lifecycleMessages = await dispatchMemoryLifecycleEvent({
- appRoot: "/app",
- ctx,
- event,
- memories: memories as never,
- messages,
- nodeId: "__root__",
- });
- await dispatchDynamicInstructionEvent({
- ctx,
- event,
- messages: lifecycleMessages,
- resolvers: resolvers as never,
- });
- };
- return { handleEvent, instruction, recall };
-}
-
function createModel(): MockLanguageModelV4 {
return new MockLanguageModelV4({
+ doStream: textStreamResult("The command returned /workspace."),
doGenerate: {
content: [{ text: "The command returned /workspace.", type: "text" }],
finishReason: { raw: undefined, unified: "stop" },
@@ -334,7 +286,7 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
);
expect(resolveStepDynamicTools).toHaveBeenCalledOnce();
- expect(getApprovedTools(result.session)).toEqual(new Set(["bash:pwd"]));
+ expect(grantedKeys(result.session)).toEqual(new Set(["bash:pwd"]));
expect(execute).toHaveBeenCalledOnce();
expect(staticExecute).not.toHaveBeenCalled();
},
@@ -453,14 +405,9 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
resolveModel: async (): Promise<LanguageModel> => model,
tools: new Map(),
} satisfies ToolLoopHarnessConfig;
- const session = setHarnessEmissionState(
+ const session = withOpenTurn(
createPendingApprovalSession(undefined, testCase.responseAuthorization),
- {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 1,
- turnId: "turn-1",
- },
+ { sequence: 1, stepIndex: 1, turnId: "turn-1" },
);
const runStep = createToolLoopHarness(config);
@@ -484,17 +431,26 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
expect(first.next).toBeNull();
}
+ // The approving step's tools are restored at its coordinates. The next model step starts and
+ // resolves its own, then the approved call runs with the approving step's persisted binding,
+ // where the AI SDK ran it: after the step started, before the model call.
expect(order).toEqual(
testCase.responseAuthorization
? [
- "resolve:turn-1:1",
+ "resolve:turn-1:0",
"authorize:persisted-response",
- "step.started:persisted-execute",
+ "resolve:turn-1:2",
+ "step.started:current-execute",
"execute:persisted-execute",
]
- : ["resolve:turn-1:1", "step.started:persisted-execute", "execute:persisted-execute"],
+ : [
+ "resolve:turn-1:0",
+ "resolve:turn-1:2",
+ "step.started:current-execute",
+ "execute:persisted-execute",
+ ],
);
- expect(handler).toHaveBeenCalledOnce();
+ expect(handler).toHaveBeenCalledTimes(2);
if (testCase.responseAuthorization) {
expect(approvalResponseCallback).toHaveBeenCalledWith(
{ version: "persisted-response" },
@@ -508,9 +464,10 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
toolCall.input,
expect.objectContaining({ callId: toolCall.toolCallId }),
);
+ // The model step that follows resolved its own step tools.
const metadata = ctx.get(StepDynamicToolMetadataKey) ?? [];
expect(metadata[0]?.callbacks?.execute).toEqual({
- closure: { version: "persisted-execute" },
+ closure: { version: "current-execute" },
});
});
@@ -571,10 +528,14 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
expect(execute).not.toHaveBeenCalled();
});
- it("executes two approvals delivered together exactly once each", async () => {
- const execute = vi.fn(async (input: unknown) =>
- (input as { command: string }).command === "pwd" ? "/workspace" : "eve",
- );
+ it("executes approved siblings concurrently and exactly once each", async () => {
+ const bothStarted = Promise.withResolvers<void>();
+ let started = 0;
+ const execute = vi.fn(async (input: unknown) => {
+ if (++started === 2) bothStarted.resolve();
+ await bothStarted.promise;
+ return (input as { command: string }).command === "pwd" ? "/workspace" : "eve";
+ });
const model = createModel();
const first = await createToolLoopHarness(createConfig(model, execute))(
@@ -586,12 +547,8 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
],
},
);
- if (typeof first.next !== "function") {
- throw new TypeError("Expected the deferred approval to schedule another harness step.");
- }
- const result = await first.next(first.session);
-
- expect(model.doGenerateCalls).toHaveLength(2);
+ const result = first;
+ expect(model.doStreamCalls).toHaveLength(1);
expect(execute).toHaveBeenCalledTimes(2);
expect(execute).toHaveBeenNthCalledWith(
1,
@@ -612,6 +569,116 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
expect(toolResultCallIds).toEqual([toolCall.toolCallId, secondToolCall.toolCallId]);
});
+ it("does not execute approved input rejected by the restored tool schema", async () => {
+ const execute = vi.fn(async () => "unexpected");
+ const model = createModel();
+ const config = createConfig(model, execute);
+ const definition = config.tools.get("bash")!;
+ const tools = new Map(config.tools);
+ tools.set("bash", {
+ ...definition,
+ inputSchema: defineJsonSchema({
+ type: "object",
+ required: ["command"],
+ properties: { command: { type: "number" } },
+ }),
+ });
+ const result = await createToolLoopHarness({ ...config, tools })(
+ createPendingApprovalSession(),
+ { inputResponses: [{ optionId: "approve", requestId: approvalRequest.approvalId }] },
+ );
+ expect(execute).not.toHaveBeenCalled();
+ const output = findPart(result.session.history, "tool-result");
+ expect(output).toMatchObject({
+ toolCallId: toolCall.toolCallId,
+ output: { type: "error-text", value: expect.stringContaining("no longer valid") },
+ });
+ });
+
+ it("does not execute approved input that fails a refinement of the restored tool schema", async () => {
+ const execute = vi.fn(async () => "unexpected");
+ const config = createConfig(createModel(), execute);
+ const tools = new Map(config.tools);
+ tools.set("bash", {
+ ...tools.get("bash")!,
+ inputSchema: z.strictObject({
+ command: z.string().refine((command) => !command.includes(".."), "Stay in the workspace."),
+ }),
+ });
+ const input = { command: "cat ../notes.txt" };
+ const session = withParkedStep(createBaseSession(), {
+ event: { sequence: 1, stepIndex: 0, turnId: "turn-1" },
+ messages: [{ content: [{ ...toolCall, input }, approvalRequest], role: "assistant" }],
+ requests: [
+ {
+ ...pendingApprovalInputRequest,
+ action: { ...pendingApprovalInputRequest.action, input },
+ },
+ ],
+ });
+ const result = await createToolLoopHarness({ ...config, tools })(session, {
+ inputResponses: [{ optionId: "approve", requestId: approvalRequest.approvalId }],
+ });
+ expect(execute).not.toHaveBeenCalled();
+ expect(findPart(result.session.history, "tool-result")).toMatchObject({
+ toolCallId: toolCall.toolCallId,
+ output: { type: "error-text", value: expect.stringContaining("no longer valid") },
+ });
+ });
+
+ it("keeps completed sibling results when another output mapper fails", async () => {
+ const execute = vi.fn(async (input: unknown) => (input as { command: string }).command);
+ const config = createConfig(createModel(), execute);
+ const tools = new Map(config.tools);
+ tools.set("bash", {
+ ...tools.get("bash")!,
+ toModelOutput: (output: unknown) => {
+ if (output === "whoami") throw new Error("Bob's output could not be formatted.");
+ return { type: "text", value: String(output) };
+ },
+ });
+ const session = withParkedStep(createBaseSession(), {
+ event: { sequence: 1, stepIndex: 0, turnId: "turn-1" },
+ messages: [
+ {
+ content: [toolCall, approvalRequest, secondToolCall, secondApprovalRequest],
+ role: "assistant",
+ },
+ ],
+ requests: [
+ pendingApprovalInputRequest,
+ {
+ ...pendingApprovalInputRequest,
+ action: {
+ ...pendingApprovalInputRequest.action,
+ callId: secondToolCall.toolCallId,
+ input: secondToolCall.input,
+ },
+ requestId: secondApprovalRequest.approvalId,
+ },
+ ],
+ });
+ const result = await createToolLoopHarness({ ...config, tools })(session, {
+ inputResponses: [
+ { optionId: "approve", requestId: approvalRequest.approvalId },
+ { optionId: "approve", requestId: secondApprovalRequest.approvalId },
+ ],
+ });
+ expect(execute).toHaveBeenCalledTimes(2);
+ const parts = result.session.history.flatMap((message) =>
+ message.role === "tool" ? message.content : [],
+ );
+ expect(parts).toContainEqual(
+ expect.objectContaining({ toolCallId: "call-1", output: { type: "text", value: "pwd" } }),
+ );
+ expect(parts).toContainEqual(
+ expect.objectContaining({
+ toolCallId: "call-2",
+ output: { type: "error-text", value: "Bob's output could not be formatted." },
+ }),
+ );
+ });
+
// Regression: approving one once()-gated call recorded the grant immediately,
// so a new same-tool call proposed on the resume step executed without a
// prompt while the other parked card was still visible to the user.
@@ -647,8 +714,8 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
);
expect(requested.map((request) => request.action.callId)).toEqual([thirdToolCall.toolCallId]);
expect(result.next).toBeNull();
- const pendingCallIds = getPendingInputBatches(result.session.state).flatMap((batch) =>
- batch.requests.map((request) => request.action.callId),
+ const pendingCallIds = parkedSteps(result.session).flatMap((step) =>
+ step.requests.map((request) => request.action.callId),
);
expect(pendingCallIds).toEqual([secondToolCall.toolCallId, thirdToolCall.toolCallId]);
});
@@ -660,13 +727,7 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
toolName: "bash",
};
const execute = vi.fn(async () => "/workspace");
- // Batches settle one per step, so the model is called between them. It
- // proposes the third call only once both pending prompts are gone.
- const responses = [
- textStreamResult("Ran pwd."),
- toolCallStreamResult(thirdToolCall),
- textStreamResult("All done."),
- ];
+ const responses = [toolCallStreamResult(thirdToolCall), textStreamResult("All done.")];
const model = new MockLanguageModelV4({
doStream: async () => {
const next = responses.shift();
@@ -694,10 +755,7 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
],
}),
);
- // The second batch's denial replays on a deferred step; drain until the turn settles.
- if (typeof first.next !== "function") {
- throw new TypeError("Expected the deferred approval response to schedule another step.");
- }
+
let result = first;
while (typeof result.next === "function") {
const { next, session } = result;
@@ -752,18 +810,22 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
message: "Then summarize it.",
});
+ // Over budget, the approved call waits for the grant, as the model call does.
expect(execute).not.toHaveBeenCalled();
- const [limitBatch] = limited.session.state?.["eve.runtime.pendingInputBatches"] as readonly {
- readonly requests: readonly { readonly requestId: string }[];
- }[];
const resumed = await runStep(limited.session, {
- inputResponses: [{ optionId: "continue", requestId: limitBatch!.requests[0]!.requestId }],
+ inputResponses: [
+ {
+ optionId: "continue",
+ requestId: openInputs(storedProjection(limited.session.state))[0]!.request.requestId,
+ },
+ ],
});
expect(execute).toHaveBeenCalledExactlyOnceWith(
toolCall.input,
expect.objectContaining({ toolCallId: toolCall.toolCallId }),
);
+ // The model reads the approved call's result first; the message replays in the next step.
expect(typeof resumed.next).toBe("function");
if (typeof resumed.next !== "function") {
throw new TypeError("Expected the deferred message to run after approval execution.");
@@ -778,6 +840,81 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
});
});
+ it("reports an approved call's execution within the step's first attempt, as the AI SDK did", async () => {
+ const execute = vi.fn(async () => "/workspace");
+ const model = new MockLanguageModelV4({
+ doStream: async () => textStreamResult("The command returned /workspace."),
+ modelId: "generate-approval-resume-model",
+ provider: "eve-integration-mock",
+ });
+ const reported: string[] = [];
+ const integration: Telemetry = {
+ onStart: () => {
+ reported.push("model operation");
+ },
+ onToolExecutionStart: (event) => {
+ reported.push(`start ${event.toolCall.toolCallId}`);
+ },
+ executeTool: async ({ execute: run, toolCallId }) => {
+ reported.push(`execute ${toolCallId}`);
+ return await run();
+ },
+ onToolExecutionEnd: (event) => {
+ reported.push(`end ${event.toolCall.toolCallId} ${event.toolOutput.type}`);
+ },
+ };
+ const resultAttempts: Array<number | undefined> = [];
+ const instrumentation: NonNullable<ToolLoopHarnessConfig["instrumentation"]> = {
+ installAiSdkWarningLogger: () => {},
+ runStep: async (input, run) =>
+ await run({
+ createHandleEvent:
+ ({ getAttemptScope }) =>
+ async (event) => {
+ if (event.type === "action.result")
+ resultAttempts.push(getAttemptScope?.()?.attemptIndex);
+ },
+ prepareAttempt: ({ attemptIndex, stepIndex, turnId }) => ({
+ complete: async () => {},
+ fail: async () => {},
+ scope: {
+ attemptId: `${turnId}:${stepIndex}:${attemptIndex}`,
+ attemptIndex,
+ sessionId: input.session.sessionId,
+ stepIndex,
+ turnId,
+ } as InstrumentationAttemptScope,
+ telemetry: { integrations: [integration], isEnabled: true },
+ }),
+ preparePreamble: async () => undefined,
+ publishInputResolutions: async () => {},
+ recordError: () => {},
+ resolveRuntimeContext: () => undefined,
+ session: input.session,
+ setTurnId: () => {},
+ telemetry: () => undefined,
+ }),
+ };
+
+ await contextStorage.run(createApprovalContext(), () =>
+ createToolLoopHarness({ ...createConfig(model, execute), instrumentation })(
+ createPendingApprovalSession(),
+ { inputResponses: [{ optionId: "approve", requestId: approvalRequest.approvalId }] },
+ ),
+ );
+
+ expect(execute).toHaveBeenCalledOnce();
+ // The AI SDK ran the call inside its model operation; it now runs just before, in the same
+ // attempt.
+ expect(reported).toEqual([
+ `start ${toolCall.toolCallId}`,
+ `execute ${toolCall.toolCallId}`,
+ `end ${toolCall.toolCallId} tool-result`,
+ "model operation",
+ ]);
+ expect(resultAttempts).toEqual([0]);
+ });
+
it("persists the approved pre-model tool result without an event handler", async () => {
const execute = vi.fn(async () => "/workspace");
const model = createModel();
@@ -789,14 +926,14 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
},
);
- expect(model.doGenerateCalls).toHaveLength(1);
- expect(model.doStreamCalls).toHaveLength(0);
+ expect(model.doGenerateCalls).toHaveLength(0);
+ expect(model.doStreamCalls).toHaveLength(1);
expect(execute).toHaveBeenCalledExactlyOnceWith(
toolCall.input,
expect.objectContaining({ toolCallId: toolCall.toolCallId }),
);
- const providerPrompt = model.doGenerateCalls[0]?.prompt ?? [];
+ const providerPrompt = model.doStreamCalls[0]?.prompt ?? [];
expect(findPart(providerPrompt, "tool-result")).toMatchObject({
output: { type: "text", value: "canonical:/workspace" },
toolCallId: toolCall.toolCallId,
@@ -804,17 +941,15 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
});
expect(result.session.history.map((message) => message.role)).toEqual([
+ "user",
+ // The notice the park committed.
"user",
"assistant",
"tool",
- "tool",
"assistant",
]);
expect(findPart(result.session.history, "tool-call")).toEqual(toolCall);
- expect(findPart(result.session.history, "tool-approval-response")).toMatchObject({
- approvalId: approvalRequest.approvalId,
- approved: true,
- });
+ expect(findPart(result.session.history, "tool-approval-response")).toBeUndefined();
expect(findPart(result.session.history, "tool-result")).toMatchObject({
output: { type: "text", value: "canonical:/workspace" },
toolCallId: toolCall.toolCallId,
@@ -845,14 +980,13 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
toolName: "bash",
type: "tool-result" as const,
};
- const session = appendPendingInputBatch({
- requests: [pendingApprovalInputRequest],
- // The parked shape when a gated call shares a step with an ungated one.
- responseMessages: [
+ // The parked shape when a gated call shares a step with an ungated one.
+ const session = withParkedStep(createBaseSession(), {
+ messages: [
{ content: [toolCall, approvalRequest, siblingCall], role: "assistant" },
{ content: [siblingResult], role: "tool" },
],
- session: createBaseSession(),
+ requests: [pendingApprovalInputRequest],
});
const ctx = new ContextContainer();
const runtimeContextAnnouncement = "Available skills\n- policy: Tenant policy";
@@ -863,7 +997,7 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
const result = await contextStorage.run(ctx, () =>
runStep(
- setHarnessEmissionState(
+ withOpenTurn(
restoredAnchor
? setTurnClientContextState(session, {
insertionIndex: 0,
@@ -871,12 +1005,7 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
turnId: "turn-1",
})
: session,
- {
- sequence: 1,
- sessionStarted: true,
- stepIndex: 1,
- turnId: "turn-1",
- },
+ { sequence: 1, stepIndex: 1, turnId: "turn-1" },
),
{ inputResponses: [{ optionId: "approve", requestId: approvalRequest.approvalId }] },
),
@@ -887,7 +1016,7 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
expect.objectContaining({ toolCallId: toolCall.toolCallId }),
);
- const providerPrompt = model.doGenerateCalls[0]?.prompt ?? [];
+ const providerPrompt = model.doStreamCalls[0]?.prompt ?? [];
const answered = new Set<string>();
const called: string[] = [];
for (const message of providerPrompt) {
@@ -899,8 +1028,10 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
}
expect(called).toEqual([toolCall.toolCallId, siblingCall.toolCallId]);
expect(called.filter((id) => !answered.has(id))).toEqual([]);
- expect(providerPrompt.at(-1)?.role).toBe("tool");
- expect(ctx.get(HistoryStateKey)).toEqual({});
+ expect(JSON.stringify(providerPrompt)).toContain("Tenant policy");
+ expect(ctx.get(HistoryStateKey)).toMatchObject({
+ availableSkills: runtimeContextAnnouncement,
+ });
expect(result.session.history.at(-1)).toMatchObject({
content: [{ text: "The command returned /workspace.", type: "text" }],
role: "assistant",
@@ -943,14 +1074,14 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
},
);
- expect(model.doGenerateCalls).toHaveLength(1);
+ expect(model.doStreamCalls).toHaveLength(1);
expect(execute).toHaveBeenCalledExactlyOnceWith(
toolCall.input,
expect.objectContaining({ toolCallId: toolCall.toolCallId }),
);
// The provider prompt keeps the intervening turn before the restored batch.
- const providerPrompt = model.doGenerateCalls[0]?.prompt ?? [];
+ const providerPrompt = model.doStreamCalls[0]?.prompt ?? [];
const interveningIndex = providerPrompt.findIndex(
(message) =>
message.role === "user" && JSON.stringify(message.content).includes("Any update"),
@@ -969,165 +1100,22 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
toolName: toolCall.toolName,
});
- // Committed history: intervening exchange first, then the restored batch, exactly once.
+ // Committed history: intervening exchange and the pending-approval notice first, then the
+ // restored batch, exactly once.
expect(result.session.history.map((message) => message.role)).toEqual([
"user",
"user",
"assistant",
+ "user",
"assistant",
"tool",
- "tool",
"assistant",
]);
expect(findPart(result.session.history, "tool-call")).toEqual(toolCall);
- expect(findPart(result.session.history, "tool-approval-response")).toMatchObject({
- approvalId: approvalRequest.approvalId,
- approved: true,
- });
+ expect(findPart(result.session.history, "tool-approval-response")).toBeUndefined();
expect(result.session.history.at(-1)).toMatchObject({
content: [{ text: "The command returned /workspace.", type: "text" }],
role: "assistant",
});
});
-
- it("keeps the approval response out of session history when the preamble fails", async () => {
- const ctx = createApprovalContext();
- const execute = vi.fn(async () => "/workspace");
- const preamble = createMemoryInstructionPreamble(ctx, [
- { content: "Remembered context", id: "memory-1" },
- ]);
- const model = new MockLanguageModelV4({
- doStream: textStreamResult("The command completed."),
- modelId: "generate-approval-resume-model",
- provider: "eve-integration-mock",
- });
- const runStep = createToolLoopHarness({
- ...createConfig(model, execute, {
- request: () => "user-approval",
- response: () => ({ status: "allowed" as const }),
- }),
- handleEvent: async (event, messages) => {
- await preamble.handleEvent(event, messages);
- if (event.type === "turn.started") {
- throw new DynamicModelSelectionError(new Error("model selection failed"));
- }
- },
- });
- let session = createPendingApprovalSession(undefined, true);
- let result = await contextStorage.run(ctx, () =>
- runStep(session, {
- attributedInputResponses: [
- {
- auth: ctx.require(AuthKey),
- response: { optionId: "approve", requestId: approvalRequest.approvalId },
- },
- ],
- }),
- );
- // The response-authorized approval runs its preamble on the continuation step.
- for (let index = 0; index < 3 && typeof result.next === "function"; index += 1) {
- const next = result.next;
- session = result.session;
- result = await contextStorage.run(ctx, () => next(session));
- }
-
- expect(preamble.recall).toHaveBeenCalledOnce();
- expect(preamble.instruction).toHaveBeenCalledOnce();
- expect(result.next).toEqual({ done: true, output: "" });
- expect(execute).not.toHaveBeenCalled();
- expect(model.doStreamCalls).toHaveLength(0);
- expect(result.session.history.slice(0, session.history.length)).toEqual(session.history);
- const preambleHistory = result.session.history.slice(session.history.length);
- expect(preambleHistory.map((message) => message.role)).toEqual(["user", "user"]);
- expect(JSON.stringify(preambleHistory[0]?.content)).toContain("Remembered context");
- expect(JSON.stringify(preambleHistory[1]?.content)).toContain("Current date and time");
- });
-
- it.each([
- { decision: "approve" as const, label: "empty recall", recalledMessages: [] },
- {
- decision: "approve" as const,
- label: "a recalled message",
- recalledMessages: [{ content: "Remembered context", id: "memory-1" }],
- },
- { decision: "cancel" as const, label: "empty recall", recalledMessages: [] },
- ])(
- "handles $decision after $label and a user instruction",
- async ({ decision, recalledMessages }) => {
- const ctx = createApprovalContext();
- const execute = vi.fn(async () => "/workspace");
- const { handleEvent, instruction, recall } = createMemoryInstructionPreamble(
- ctx,
- recalledMessages,
- );
- const model = new MockLanguageModelV4({
- doStream: textStreamResult("The command completed."),
- modelId: "generate-approval-resume-model",
- provider: "eve-integration-mock",
- });
- const runStep = createToolLoopHarness({
- ...createConfig(model, execute, {
- request: () => "user-approval",
- response: () => ({ status: "allowed" as const }),
- }),
- handleEvent,
- });
-
- let result = await contextStorage.run(ctx, () =>
- runStep(createPendingApprovalSession(undefined, true), {
- attributedInputResponses: [
- {
- auth: ctx.require(AuthKey),
- response: { optionId: decision, requestId: approvalRequest.approvalId },
- },
- ],
- }),
- );
- for (let index = 0; index < 3 && typeof result.next === "function"; index += 1) {
- const next = result.next;
- result = await contextStorage.run(ctx, () => next(result.session));
- }
-
- expect(recall).toHaveBeenCalledOnce();
- expect(instruction).toHaveBeenCalledOnce();
- if (decision === "approve") {
- expect(execute).toHaveBeenCalledExactlyOnceWith(
- toolCall.input,
- expect.objectContaining({ toolCallId: toolCall.toolCallId }),
- );
- } else {
- expect(execute).not.toHaveBeenCalled();
- }
- const providerPrompt = model.doStreamCalls[0]?.prompt ?? [];
- expect(providerPrompt).toContainEqual(
- expect.objectContaining({
- content: [
- expect.objectContaining({
- text: "Current date and time: 2026-09-28T00:00:00.000Z (UTC).",
- }),
- ],
- role: "user",
- }),
- );
- expect(
- providerPrompt.some((message) =>
- JSON.stringify(message.content).includes("Remembered context"),
- ),
- ).toBe(recalledMessages.length > 0);
- expect(
- result.session.history.some(
- (message) =>
- message.role === "user" &&
- JSON.stringify(message.content).includes("Current date and time"),
- ),
- ).toBe(true);
- if (decision === "approve") {
- expect(findPart(providerPrompt, "tool-result")).toMatchObject({
- output: { type: "text", value: "canonical:/workspace" },
- toolCallId: toolCall.toolCallId,
- toolName: toolCall.toolName,
- });
- }
- },
- );
});
diff --git a/packages/eve/src/harness/tool-loop-steering.integration.test.ts b/packages/eve/src/harness/tool-loop-steering.integration.test.ts
index b6e3e5da1..8705e0098 100644
--- a/packages/eve/src/harness/tool-loop-steering.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-steering.integration.test.ts
@@ -2,7 +2,7 @@ import { jsonSchema } from "ai";
import { MockLanguageModelV3 } from "ai/test";
import { describe, expect, it, vi } from "vitest";
import { createToolLoopHarness } from "#harness/tool-loop.js";
-import { getHarnessEmissionState, setHarnessEmissionState } from "#harness/emission-state.js";
+import { foldingHandler, positionOf, withOpenTurn } from "#internal/testing/session-machine.js";
import {
createFrameworkUserMessage,
createUserMessage,
@@ -136,10 +136,10 @@ describe("generation steering with the real AI SDK", () => {
],
]),
resolveModel: async () => model,
- handleEvent: async (event) => {
+ handleEvent: foldingHandler(async (event) => {
events.push(event);
if (event.type === boundary) steering.abort();
- },
+ }),
});
const ctx = new ContextContainer();
ctx.set(SessionKey, {
@@ -240,7 +240,7 @@ describe("generation steering with the real AI SDK", () => {
const interrupted = await running;
expect(providerSignal?.aborted).toBe(true);
expect(interrupted.steered).toBe(true);
- expect(getHarnessEmissionState(interrupted.session.state).turnId).toBe("turn_0");
+ expect(positionOf(interrupted.session).turnId).toBe("turn_0");
// The provider ignores abort and finishes its obsolete request anyway.
firstStream!.enqueue({
type: "tool-call",
@@ -398,7 +398,7 @@ describe("generation steering with the real AI SDK", () => {
},
}),
}));
- const heldTurn = setHarnessEmissionState(
+ const heldTurn = withOpenTurn(
{
...session(),
history: [
@@ -421,7 +421,7 @@ describe("generation steering with the real AI SDK", () => {
createFrameworkUserMessage("context.state", "Alice's reports are due Monday."),
],
},
- { sessionStarted: true, sequence: 0, stepIndex: 1, turnId: "turn_0" },
+ { sequence: 0, stepIndex: 1, turnId: "turn_0" },
);
await createToolLoopHarness({
handleEvent: async () => {},
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index da48332a6..cefdd7e26 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -46,30 +46,34 @@ import {
type ConversationContext,
} from "#shared/conversation-context.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
-import { compactMessages, shouldCompact } from "#harness/compaction.js";
+import { compactMessages, shouldCompact } from "#harness/compaction/engine.js";
import {
createFrameworkUserMessage,
createUserMessage,
type HarnessModelMessage,
} from "#harness/messages.js";
-import {
- getHarnessEmissionState,
- isHarnessBetweenTurns,
- setHarnessEmissionState,
-} from "#harness/emission.js";
import {
getPendingAuthorization,
modelFacingAuthorizationOutput,
requestAuthorization,
} from "#harness/authorization.js";
-import { hasPendingInputBatch, appendPendingInputBatch } from "#harness/input-requests.js";
-import { getPendingInputBatches } from "#harness/pending-input-batches.js";
-import { getPendingCoordinationBatch, pendingCoordinationCallIds } from "#harness/coordination.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { createAuthorizationRequiredEvent } from "#protocol/message.js";
+import { ownOpenRequestIds } from "#harness/session-machine/transitions.js";
+import { runtimeWait, storedProjection } from "#harness/session-machine/view.js";
+import {
+ foldingHandler,
+ parkedSteps,
+ positionOf,
+ withOpenTurn,
+ withPublished,
+ withParkedStep,
+} from "#internal/testing/session-machine.js";
import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import { stashToolInterrupt } from "#harness/tool-interrupts.js";
-import { appendMissingToolResultMessages, createToolLoopHarness } from "#harness/tool-loop.js";
-import { countRunUsage } from "#execution/agent-sessions/usage.js";
+import { appendMissingToolResultMessages } from "#harness/model-call/response.js";
+import { createToolLoopHarness } from "#harness/tool-loop.js";
import { createTask, writeTaskTable } from "#execution/tasks/table.js";
import { SessionLimitDeclinedError, TurnCancelledError } from "#harness/turn-cancellation.js";
import {
@@ -89,12 +93,14 @@ import {
} from "#instrumentation/runtime.js";
import type { RuntimeContextResolver } from "#tracing/otel-declaration.js";
import { captureLogRecords } from "#internal/testing/log-records.js";
+import { countRunUsage } from "#execution/agent-sessions/usage.js";
// The harness runs outside a workflow body here, where run attributes cannot
// be written; the attribute contract is covered by emit.test.ts.
vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async () => {}) }));
-vi.mock("ai", () => ({
+vi.mock("ai", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("ai")>()),
ToolLoopAgent: vi.fn(),
gateway: {
tools: {
@@ -102,7 +108,6 @@ vi.mock("ai", () => ({
parallelSearch: vi.fn(() => ({})),
},
},
- jsonSchema: vi.fn((s: unknown) => s),
isStepCount: vi.fn((n: number) => n),
tool: vi.fn((t: unknown) => t),
}));
@@ -237,7 +242,7 @@ function bindHookInstrumentation(
)!.prepareExecution();
}
-vi.mock("./compaction.js", () => ({
+vi.mock("#harness/compaction/engine.js", () => ({
compactMessages: vi.fn(),
estimateTokens: vi.fn().mockReturnValue(5000),
getInputTokenCount: vi.fn().mockReturnValue(5000),
@@ -283,7 +288,8 @@ function createTestConfig(
): ToolLoopHarnessConfig {
return {
capabilities: { requestInput: true },
- handleEvent: emit,
+ // The handler folds what it hears, as the publish sink does for a running session.
+ handleEvent: emit === undefined ? undefined : foldingHandler(emit),
instrumentation: declaredInstrumentation,
resolveModel: vi.fn().mockResolvedValue({} as LanguageModel),
tools: new Map([
@@ -334,17 +340,6 @@ function mockApprovalAlongsideWorkflowTask(): void {
],
},
responseMessages: [
- {
- content: [
- {
- output: { type: "text", value: "/workspace" },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- ],
- role: "tool",
- },
{
content: [
gateToolCall,
@@ -383,6 +378,22 @@ function createDelegationToolMap(): ToolLoopHarnessConfig["tools"] {
]);
}
+/** Adds the `bash` tool the pending approval fixtures ask to run. */
+function withBash(tools: ToolLoopHarnessConfig["tools"]): ToolLoopHarnessConfig["tools"] {
+ return new Map([
+ ...tools,
+ [
+ "bash",
+ {
+ description: "Run shell commands",
+ execute: vi.fn().mockResolvedValue("/workspace"),
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "bash",
+ },
+ ],
+ ]);
+}
+
/** A `task` workflow tool, so the agent can start tasks and gets the task tools. */
function createTaskToolMap(): ToolLoopHarnessConfig["tools"] {
const workflowId = "workflow//./agent/tools/research//task";
@@ -415,28 +426,6 @@ function setDelegatedParent(ctx: ContextContainer): void {
});
}
-const DELEGATED_SPEND = {
- cacheReadTokens: 0,
- cacheWriteTokens: 0,
- costUsd: 0.25,
- inputTokens: 100,
- outputTokens: 20,
-};
-
-/** A session whose delegated agents already spent {@link DELEGATED_SPEND}. */
-function withDelegatedSpend(overrides?: Parameters<typeof createTestSession>[0]): HarnessSession {
- return countRunUsage(createTestSession(overrides), DELEGATED_SPEND);
-}
-
-function lastSessionEvent<T extends "session.waiting" | "session.failed">(
- events: readonly UnstampedMessageStreamEvent[],
- type: T,
-): Extract<UnstampedMessageStreamEvent, { type: T }> | undefined {
- return events.findLast(
- (event): event is Extract<UnstampedMessageStreamEvent, { type: T }> => event.type === type,
- );
-}
-
function createEventCollector(): {
emit: HarnessEmitFn;
events: UnstampedMessageStreamEvent[];
@@ -737,8 +726,33 @@ function pendingBashApprovalResult(): Record<string, unknown> {
};
}
+/** A step parked on its approvals, as the machine parks one. */
+function parkedOnApproval(input: {
+ readonly event?: {
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+ };
+ readonly requests: Parameters<typeof withParkedStep>[1]["requests"];
+ readonly responseAuthRequiredRequestIds?: readonly string[];
+ readonly responseMessages: Parameters<typeof withParkedStep>[1]["messages"];
+ readonly session: HarnessSession;
+}): HarnessSession {
+ return withParkedStep(input.session, {
+ event: input.event,
+ messages: input.responseMessages,
+ requests: input.requests,
+ responseAuthRequiredRequestIds: input.responseAuthRequiredRequestIds,
+ });
+}
+
+/** What the session asks and still awaits. */
+function openRequestIds(session: Pick<HarnessSession, "state">): ReadonlySet<string> {
+ return ownOpenRequestIds(sessionView(storedProjection(session.state), session.state));
+}
+
function createPendingBashApprovalSession(): HarnessSession {
- return appendPendingInputBatch({
+ return parkedOnApproval({
requests: [
{
action: {
@@ -789,7 +803,7 @@ function createPendingBashApprovalSession(): HarnessSession {
}
function createPendingProtectedActionApprovalSessionWithSiblingCall(): HarnessSession {
- return appendPendingInputBatch({
+ return parkedOnApproval({
requests: [
{
action: {
@@ -832,6 +846,18 @@ function createPendingProtectedActionApprovalSessionWithSiblingCall(): HarnessSe
],
role: "assistant",
},
+ // The ungated sibling ran in the step that parked.
+ {
+ content: [
+ {
+ output: { type: "text", value: "sibling completed" },
+ toolCallId: "call-2",
+ toolName: "protected_action",
+ type: "tool-result",
+ },
+ ],
+ role: "tool",
+ },
],
session: createTestSession({
agent: {
@@ -897,7 +923,104 @@ function createGatewayModelCallError(input: {
});
}
+const DELEGATED_SPEND = {
+ cacheReadTokens: 0,
+ cacheWriteTokens: 0,
+ costUsd: 0.25,
+ inputTokens: 100,
+ outputTokens: 20,
+};
+
+/** A session whose delegated agents already spent {@link DELEGATED_SPEND}. */
+function withDelegatedSpend(overrides?: Parameters<typeof createTestSession>[0]): HarnessSession {
+ return countRunUsage(createTestSession(overrides), DELEGATED_SPEND);
+}
+
+function lastSessionEvent<T extends "session.waiting" | "session.failed">(
+ events: readonly UnstampedMessageStreamEvent[],
+ type: T,
+): Extract<UnstampedMessageStreamEvent, { type: T }> | undefined {
+ return events.findLast(
+ (event): event is Extract<UnstampedMessageStreamEvent, { type: T }> => event.type === type,
+ );
+}
+
describe("createToolLoopHarness", () => {
+ it("reports the session's running usage, delegated spend included, when the turn ends", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ providerMetadata: { gateway: { cost: "0.125" } },
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ usage: {
+ inputTokenDetails: { cacheReadTokens: 2, cacheWriteTokens: 1 },
+ inputTokens: 7,
+ outputTokens: 3,
+ },
+ });
+ const { emit, events } = createEventCollector();
+
+ await createToolLoopHarness(createTestConfig(emit))(withDelegatedSpend(), { message: "Hi" });
+
+ expect(lastSessionEvent(events, "session.waiting")?.data.usage).toEqual({
+ cacheReadTokens: 2,
+ cacheWriteTokens: 1,
+ costUsd: 0.375,
+ inputTokens: 107,
+ outputTokens: 23,
+ });
+ });
+
+ it("reports no session cost on session.waiting when no model call reported one", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ usage: { inputTokens: 7, outputTokens: 3 },
+ });
+ const { emit, events } = createEventCollector();
+
+ await createToolLoopHarness(createTestConfig(emit))(createTestSession(), { message: "Hi" });
+
+ expect(lastSessionEvent(events, "session.waiting")?.data.usage).toEqual({
+ cacheReadTokens: 0,
+ cacheWriteTokens: 0,
+ costUsd: undefined,
+ inputTokens: 7,
+ outputTokens: 3,
+ });
+ });
+
+ it("reports the session's usage on session.waiting when a failed model call parks the turn", async () => {
+ setupMockAgentError(new Error("Model blew up"));
+ const { emit, events } = createEventCollector();
+
+ await createToolLoopHarness(createTestConfig(emit))(withDelegatedSpend(), { message: "Hi" });
+
+ expect(lastSessionEvent(events, "session.waiting")?.data.usage).toEqual(DELEGATED_SPEND);
+ });
+
+ it("reports the session's usage on session.failed when model selection fails", async () => {
+ const emit: HarnessEmitFn = async (event) => {
+ events.push(event);
+ if (event.type === "turn.started") {
+ throw new DynamicModelSelectionError(new Error("flag service unavailable"));
+ }
+ };
+ const events: UnstampedMessageStreamEvent[] = [];
+
+ await createToolLoopHarness(createTestConfig(emit))(
+ withDelegatedSpend({ outputSchema: { type: "object" } }),
+ { message: "Hi" },
+ );
+
+ expect(lastSessionEvent(events, "session.failed")?.data.usage).toEqual(DELEGATED_SPEND);
+ });
+
it("uses one projected history view for step consumers while preserving raw history", async () => {
setupMockAgent({
finishReason: "stop",
@@ -1088,9 +1211,10 @@ describe("createToolLoopHarness", () => {
const first = await runStep(session, { message: "What's the weather in NY?" });
expect(typeof first.next).toBe("function");
- expect(getHarnessEmissionState(first.session.state)).toMatchObject({
+ // Between steps, the open turn's position is the step it last started.
+ expect(positionOf(first.session)).toMatchObject({
turnId: "turn_0",
- stepIndex: 1,
+ stepIndex: 0,
});
const second = await runStep(first.session, { message: "Use Fahrenheit." });
@@ -1104,7 +1228,7 @@ describe("createToolLoopHarness", () => {
kind: "user",
role: "user",
});
- expect(getHarnessEmissionState(second.session.state)).toMatchObject({
+ expect(positionOf(second.session)).toMatchObject({
sequence: 1,
stepIndex: 0,
turnId: "",
@@ -1535,7 +1659,7 @@ describe("createToolLoopHarness", () => {
toolName: "delegate",
}),
]);
- expect(getPendingCoordinationBatch(result.session.state)?.tasks).toEqual([
+ expect(runtimeWait(result.session.state)?.tasks).toEqual([
expect.objectContaining({
callId: "call-1",
input: { message: "delegate from child" },
@@ -1553,14 +1677,14 @@ describe("createToolLoopHarness", () => {
...delegation.get("add")!,
approval: { request: () => "user-approval", response: () => ({ status: "allowed" }) },
});
- const runStep = createToolLoopHarness(createTestConfig(undefined, { tools }));
+ const runStep = createToolLoopHarness(createTestConfig(undefined, { tools: withBash(tools) }));
const parked = await runStep(createPendingBashApprovalSession(), {
inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
});
- expect(getPendingCoordinationBatch(parked.session.state)).toBeDefined();
- expect(getPendingInputBatches(parked.session.state)).toEqual([
+ expect(runtimeWait(parked.session.state)).toBeDefined();
+ expect(parkedSteps(parked.session)).toEqual([
expect.objectContaining({ responseAuthRequiredRequestIds: ["approval-gate"] }),
]);
});
@@ -1570,7 +1694,7 @@ describe("createToolLoopHarness", () => {
const { emit, events } = createEventCollector();
const runStep = createToolLoopHarness(
- createTestConfig(emit, { tools: createDelegationToolMap() }),
+ createTestConfig(emit, { tools: withBash(createDelegationToolMap()) }),
);
const parked = await runStep(createPendingBashApprovalSession(), {
@@ -1578,10 +1702,10 @@ describe("createToolLoopHarness", () => {
});
expect(parked.next).toBeNull();
- expect(getPendingCoordinationBatch(parked.session.state)?.tasks).toEqual([
+ expect(runtimeWait(parked.session.state)?.tasks).toEqual([
expect.objectContaining({ callId: "delegate-1", kind: "workflow-task" }),
]);
- expect(hasPendingInputBatch(parked.session.state)).toBe(true);
+ expect(openRequestIds(parked.session).size > 0).toBe(true);
expect(events.filter((event) => event.type === "input.requested")).toHaveLength(1);
expect(
parked.session.history.flatMap((message) =>
@@ -1605,10 +1729,11 @@ describe("createToolLoopHarness", () => {
});
expect(reparked.next).toBeNull();
- expect(getPendingCoordinationBatch(reparked.session.state)).toBeUndefined();
- expect(hasPendingInputBatch(reparked.session.state)).toBe(true);
- const toolMessages = reparked.session.history.filter((message) => message.role === "tool");
- expect(JSON.stringify(toolMessages)).toContain("delegated-done");
+ expect(runtimeWait(reparked.session.state)).toBeUndefined();
+ expect(openRequestIds(reparked.session).size > 0).toBe(true);
+ // The delegated result waits with its step until the sibling approval is decided.
+ expect(JSON.stringify(parkedSteps(reparked.session)[0]?.messages)).toContain("delegated-done");
+ expect(JSON.stringify(reparked.session.history)).not.toContain("delegated-done");
expect(reparked.held).toEqual({ kind: "request" });
expect(events.at(-1)?.type).toBe("turn.waiting");
});
@@ -1642,20 +1767,7 @@ describe("createToolLoopHarness", () => {
content: assistantContent,
finishReason: "tool-calls",
response: { messages: [{ content: assistantContent, role: "assistant" }] },
- responseMessages: [
- {
- content: [
- {
- output: { type: "text", value: "/workspace" },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- ],
- role: "tool",
- },
- { content: assistantContent, role: "assistant" },
- ],
+ responseMessages: [{ content: assistantContent, role: "assistant" }],
text: "",
toolCalls: [gateToolCall, waitToolCall, invalidCancelToolCall],
toolResults: [],
@@ -1666,16 +1778,16 @@ describe("createToolLoopHarness", () => {
]);
const { emit } = createEventCollector();
- const runStep = createToolLoopHarness(createTestConfig(emit, { tools }));
+ const runStep = createToolLoopHarness(createTestConfig(emit, { tools: withBash(tools) }));
const parked = await runStep(createPendingBashApprovalSession(), {
inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
});
expect(parked.next).toBeNull();
- expect(hasPendingInputBatch(parked.session.state)).toBe(true);
- const batch = getPendingCoordinationBatch(parked.session.state);
+ expect(openRequestIds(parked.session).size > 0).toBe(true);
+ const batch = runtimeWait(parked.session.state);
expect(batch?.tasks).toEqual([]);
- expect(pendingCoordinationCallIds(batch!)).toEqual(["wait-1"]);
+ expect(batch!.callIds).toEqual(["wait-1"]);
});
it("forwards the agent reasoning effort to the model call", async () => {
@@ -1730,81 +1842,6 @@ describe("createToolLoopHarness", () => {
});
});
- it("reports the session's running usage, delegated spend included, when the turn ends", async () => {
- setupMockAgent({
- finishReason: "stop",
- providerMetadata: { gateway: { cost: "0.125" } },
- response: { messages: [{ content: "Hello!", role: "assistant" }] },
- text: "Hello!",
- toolCalls: [],
- toolResults: [],
- usage: {
- inputTokenDetails: { cacheReadTokens: 2, cacheWriteTokens: 1 },
- inputTokens: 7,
- outputTokens: 3,
- },
- });
- const { emit, events } = createEventCollector();
-
- await createToolLoopHarness(createTestConfig(emit))(withDelegatedSpend(), { message: "Hi" });
-
- expect(lastSessionEvent(events, "session.waiting")?.data.usage).toEqual({
- cacheReadTokens: 2,
- cacheWriteTokens: 1,
- costUsd: 0.375,
- inputTokens: 107,
- outputTokens: 23,
- });
- });
-
- it("reports no session cost on session.waiting when no model call reported one", async () => {
- setupMockAgent({
- finishReason: "stop",
- response: { messages: [{ content: "Hello!", role: "assistant" }] },
- text: "Hello!",
- toolCalls: [],
- toolResults: [],
- usage: { inputTokens: 7, outputTokens: 3 },
- });
- const { emit, events } = createEventCollector();
-
- await createToolLoopHarness(createTestConfig(emit))(createTestSession(), { message: "Hi" });
-
- expect(lastSessionEvent(events, "session.waiting")?.data.usage).toEqual({
- cacheReadTokens: 0,
- cacheWriteTokens: 0,
- costUsd: undefined,
- inputTokens: 7,
- outputTokens: 3,
- });
- });
-
- it("reports the session's usage on session.waiting when a failed model call parks the turn", async () => {
- setupMockAgentError(new Error("Model blew up"));
- const { emit, events } = createEventCollector();
-
- await createToolLoopHarness(createTestConfig(emit))(withDelegatedSpend(), { message: "Hi" });
-
- expect(lastSessionEvent(events, "session.waiting")?.data.usage).toEqual(DELEGATED_SPEND);
- });
-
- it("reports the session's usage on session.failed when model selection fails", async () => {
- const emit: HarnessEmitFn = async (event) => {
- events.push(event);
- if (event.type === "turn.started") {
- throw new DynamicModelSelectionError(new Error("flag service unavailable"));
- }
- };
- const events: UnstampedMessageStreamEvent[] = [];
-
- await createToolLoopHarness(createTestConfig(emit))(
- withDelegatedSpend({ outputSchema: { type: "object" } }),
- { message: "Hi" },
- );
-
- expect(lastSessionEvent(events, "session.failed")?.data.usage).toEqual(DELEGATED_SPEND);
- });
-
it.each([
{
details: {
@@ -2128,22 +2165,39 @@ describe("createToolLoopHarness", () => {
const runStep = createToolLoopHarness(createTestConfig(emit));
const parked = await runStep(createLimitReachedSession(), { message: "Hi again" });
+ const beforeQueued = events.length;
const reparked = await runStep(parked.session, { message: "also do this other thing" });
+ // The message is received into a real turn, which holds for the prompt.
+ expect(events.slice(beforeQueued).map((event) => event.type)).toEqual([
+ "turn.started",
+ "message.received",
+ "turn.waiting",
+ ]);
+ const waiting = events.at(-1);
+ expect(waiting).toMatchObject({ data: { on: "input" }, type: "turn.waiting" });
+ const turnId = waiting?.type === "turn.waiting" ? waiting.data.turnId : undefined;
+ expect(turnId).toMatch(/^turn_/);
+ expect(reparked.held).toEqual({ kind: "request" });
expect(vi.mocked(ToolLoopAgent)).not.toHaveBeenCalled();
- expect(reparked.next).toBeNull();
expect(events.filter((event) => event.type === "input.requested")).toHaveLength(1);
+ const asked = { content: "also do this other thing", kind: "user" as const, role: "user" };
+ expect(reparked.session.history).toContainEqual(asked);
+ const beforeGrant = events.length;
const resumed = await runStep(reparked.session, {
inputResponses: [{ optionId: "continue", requestId: LIMIT_REQUEST_ID }],
});
+ // The grant resumes that turn; the message was received once, and the model reads it once.
+ const resumedEvents = events.slice(beforeGrant);
+ expect(resumedEvents.some((event) => event.type === "turn.started")).toBe(false);
+ expect(resumedEvents.some((event) => event.type === "message.received")).toBe(false);
+ expect(resumedEvents.find((event) => event.type === "step.started")?.data.turnId).toBe(turnId);
expect(vi.mocked(ToolLoopAgent)).toHaveBeenCalledTimes(1);
- expect(resumed.session.history).toContainEqual({
- content: "also do this other thing",
- kind: "user" as const,
- role: "user",
- });
+ expect(
+ resumed.session.history.filter((message) => message.content === asked.content),
+ ).toHaveLength(1);
});
it("preserves approval gates on step-scoped dynamic tools", async () => {
@@ -3042,8 +3096,12 @@ describe("createToolLoopHarness", () => {
const { emit, events } = createEventCollector();
const runStep = createToolLoopHarness(createTestConfig(emit));
+ // A continuation step runs inside the turn an earlier step opened.
await runStep(
- createTestSession({ history: [{ content: "prior", kind: "user" as const, role: "user" }] }),
+ withOpenTurn(
+ createTestSession({ history: [{ content: "prior", kind: "user" as const, role: "user" }] }),
+ { sequence: 0, stepIndex: 0, turnId: "turn_0" },
+ ),
);
expect(getCompatibilityEventTypes(events)).toEqual([
@@ -3204,14 +3262,9 @@ describe("createToolLoopHarness", () => {
type: "input.requested",
});
expect(events.filter((event) => event.type === "turn.waiting").at(-1)).toMatchObject({
- data: {
- on: "input",
- sequence: 0,
- turnId: "turn_0",
- },
+ data: { on: "input", sequence: 0, turnId: "turn_0" },
type: "turn.waiting",
});
- expect(events.some((event) => event.type === "turn.completed")).toBe(false);
});
it.each(["", "Alice's inventory list is"])(
@@ -3861,20 +3914,15 @@ describe("createToolLoopHarness", () => {
const runStep = createToolLoopHarness(config);
const result = await runStep(createTestSession(), { message: "Go" });
- // Parked on the coordination batch.
+ // Parked on the runtime call.
expect(result.next).toBeNull();
- expect(result.session.state?.["eve.runtime.pendingCoordinationBatch"]).toBeDefined();
-
- // The parked session must carry the live turn's emission identity so
- // the resume turn is classified as a continuation, not a fresh turn.
- // Regression: the coordination park previously dropped the
- // post-preamble emission update, persisting the default `turnId: ""`,
- // which mis-routed the resume through the fresh-turn lifecycle path.
- const emission = getHarnessEmissionState(result.session.state);
- expect(emission.turnId).toBe("turn_0");
- expect(emission.stepIndex).toBe(1);
- expect(emission.sessionStarted).toBe(true);
- expect(isHarnessBetweenTurns(result.session)).toBe(false);
+ expect(runtimeWait(result.session.state)?.callIds).toEqual(["call-subagent"]);
+
+ // The turn stays open across the park, so the resume is a continuation, not a fresh turn.
+ const position = positionOf(result.session);
+ expect(position.turnId).toBe("turn_0");
+ expect(position.stepIndex).toBe(0);
+ expect(position.sessionStarted).toBe(true);
});
it("emits failed action.result from tool response messages when the stream and toolResults omit it", async () => {
@@ -4656,7 +4704,7 @@ describe("createToolLoopHarness", () => {
);
});
- it("parks a delegated turn held by its working tasks with turn.waiting and the session's usage", async () => {
+ it("parks a delegated turn held by its working tasks with turn.waiting", async () => {
setupMockAgent({
finishReason: "stop",
response: { messages: [{ content: "Checking now.", role: "assistant" }] },
@@ -4674,7 +4722,7 @@ describe("createToolLoopHarness", () => {
);
const result = await contextStorage.run(ctx, () =>
- runStep(writeTaskTable(withDelegatedSpend(), table), { message: "Delegated turn" }),
+ runStep(writeTaskTable(createTestSession(), table), { message: "Delegated turn" }),
);
expect(result.held).toBeDefined();
@@ -4685,7 +4733,7 @@ describe("createToolLoopHarness", () => {
}),
);
expect(events.at(-1)).toEqual({
- data: { on: "tasks", sequence: 0, turnId: "turn_0", usage: DELEGATED_SPEND },
+ data: { on: "tasks", sequence: 0, turnId: "turn_0", usage: expect.any(Object) },
type: "turn.waiting",
});
expect(events.map((event) => event.type)).not.toContain("session.waiting");
@@ -6230,6 +6278,50 @@ describe("createToolLoopHarness", () => {
]);
});
+ it("completes a connection's sign-in, then resumes the held turn's work", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Signed in; continuing.", role: "assistant" }] },
+ text: "Signed in; continuing.",
+ toolCalls: [],
+ toolResults: [],
+ });
+ const challenge = {
+ attemptId: "attempt-statuspage",
+ challenge: { url: "https://idp.example/authorize" },
+ hookUrl: "https://app.example/eve/v1/connections/statuspage/callback",
+ name: "statuspage",
+ };
+ // Alice's turn asked Bob's status page connection to sign in, and holds for it.
+ const session = withPublished(createTestSession(), [
+ { data: {}, type: "session.started" },
+ { data: { sequence: 0, turnId: "turn_0" }, type: "turn.started" },
+ createAuthorizationRequiredEvent({
+ attemptId: challenge.attemptId,
+ description: "Sign in to statuspage",
+ name: challenge.name,
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ webhookUrl: challenge.hookUrl,
+ }),
+ { data: { on: "input", sequence: 0, turnId: "turn_0" }, type: "turn.waiting" },
+ ] as UnstampedMessageStreamEvent[]);
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(
+ createTestConfig(emit, { signInCompletions: [challenge] as never }),
+ );
+
+ await runStep(session, undefined);
+
+ expect(
+ events.slice(0, 2).map((event) => [event.type, "turnId" in event.data! && event.data.turnId]),
+ ).toEqual([
+ ["authorization.completed", "turn_0"],
+ ["step.started", "turn_0"],
+ ]);
+ });
+
describe("authorization signal detection", () => {
function createAuthSignals() {
const full = requestAuthorization([
@@ -6351,11 +6443,9 @@ describe("createToolLoopHarness", () => {
webhookUrl: "https://app.example/callback",
});
+ // A sign-in interrupt is not a tool result on the v26 stream.
const actionResults = events.filter((event) => event.type === "action.result");
- expect(actionResults).toHaveLength(1);
- expect(actionResults[0]?.data).toMatchObject({
- result: { callId: "call-2", kind: "tool-result", toolName: "protected_action" },
- });
+ expect(actionResults).toHaveLength(0);
expect(
result.session.history.flatMap((message) =>
message.role === "tool"
@@ -6419,159 +6509,6 @@ describe("createToolLoopHarness", () => {
);
});
- it("persists the SDK's accumulated approval-resume messages into session history", async () => {
- /*
- * The real AI SDK contract is covered in
- * `ai-sdk-approval-resume.integration.test.ts`. This unit isolates Eve's
- * side of that contract: durable history must use the call-wide
- * `responseMessages`, even when event projection does not provide a
- * reconstructable tool-result.
- */
- const resumedToolResultMessage = {
- content: [
- {
- output: {
- type: "json",
- value: { exitCode: 0, stderr: "", stdout: "/workspace\n", truncated: false },
- },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- ],
- role: "tool",
- };
- const assistantMessage = { content: "`/workspace`", role: "assistant" };
- setupMockAgent({
- content: [],
- finishReason: "stop",
- fullStreamParts: [
- { id: "text-1", text: "`/workspace`", type: "text-delta" },
- { finishReason: "stop", type: "finish-step" },
- ],
- response: {
- messages: [assistantMessage],
- },
- responseMessages: [resumedToolResultMessage, assistantMessage],
- text: "`/workspace`",
- toolCalls: [],
- toolResults: [],
- });
-
- const { emit } = createEventCollector();
- const hidden = {
- content: "HIDE_FROM_APPROVAL_RESUME",
- kind: "user" as const,
- role: "user" as const,
- };
- const pendingSession = createPendingBashApprovalSession();
- const session = {
- ...pendingSession,
- history: [hidden, ...pendingSession.history],
- };
-
- const harness = createToolLoopHarness(
- createTestConfig(emit, {
- historyProjector: ({ messages }) => messages.filter((message) => message !== hidden),
- tools: new Map(),
- }),
- );
- const result = await contextStorage.run(new ContextContainer(), () =>
- harness(session, {
- inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
- }),
- );
-
- expect(result.session.history.map((msg) => msg.role)).toEqual([
- "user",
- "assistant",
- "tool",
- "tool",
- "assistant",
- ]);
- const agent = vi.mocked(ToolLoopAgent).mock.results[0]?.value;
- expect(vi.mocked(agent!.stream).mock.calls[0]?.[0].messages).not.toContain(hidden);
- const approvalMessage = result.session.history[2];
- expect(Array.isArray(approvalMessage?.content)).toBe(true);
- const approvalParts = approvalMessage?.content as Array<Record<string, unknown>>;
- expect(approvalParts).toHaveLength(1);
- expect(approvalParts[0]).toEqual({
- approvalId: "approval-1",
- approved: true,
- reason: undefined,
- type: "tool-approval-response",
- });
-
- const toolResultMessage = result.session.history[3];
- expect(Array.isArray(toolResultMessage?.content)).toBe(true);
- const toolResultParts = toolResultMessage?.content as Array<Record<string, unknown>>;
- expect(toolResultParts).toHaveLength(1);
- expect(toolResultParts[0]).toMatchObject({
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- });
- expect(result.session.history.at(-1)?.role).toBe("assistant");
- });
-
- it("persists approved tool results when event handling is disabled", async () => {
- const resumedToolResultMessage = {
- content: [
- {
- output: { type: "text", value: "/workspace" },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- ],
- role: "tool",
- };
- const assistantMessage = { content: "`/workspace`", role: "assistant" };
-
- // The final step contains only the assistant reply. The call-wide
- // GenerateTextResult also contains the approved pre-model tool result.
- setupMockAgent({
- content: [],
- finishReason: "stop",
- response: { messages: [assistantMessage] },
- responseMessages: [resumedToolResultMessage, assistantMessage],
- text: "`/workspace`",
- toolCalls: [],
- toolResults: [],
- });
-
- const harness = createToolLoopHarness(createTestConfig(undefined, { tools: new Map() }));
- const result = await harness(createPendingBashApprovalSession(), {
- inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
- });
-
- const agent = vi.mocked(ToolLoopAgent).mock.results.at(-1)?.value;
- if (agent === undefined) {
- throw new Error("ToolLoopAgent mock did not return an instance.");
- }
- expect(vi.mocked(agent.generate)).toHaveBeenCalledOnce();
- expect(vi.mocked(agent.stream)).not.toHaveBeenCalled();
- const assistantParts = result.session.history.flatMap((message) =>
- message.role === "assistant" && Array.isArray(message.content) ? message.content : [],
- );
- const toolParts = result.session.history.flatMap((message) =>
- message.role === "tool" ? message.content : [],
- );
- const toolCall = assistantParts.find(
- (part) => part.type === "tool-call" && part.toolCallId === "call-1",
- );
- const toolResult = toolParts.find(
- (part) => part.type === "tool-result" && part.toolCallId === "call-1",
- );
- expect([
- result.session.history[0]?.role,
- toolCall?.type,
- toolResult?.type,
- result.session.history.at(-1)?.role,
- ]).toEqual(["assistant", "tool-call", "tool-result", "assistant"]);
- expect(toolResult).toEqual(resumedToolResultMessage.content[0]);
- });
-
it("does not persist provider-executed deferred tool-results as generic tool messages", async () => {
const toolCallId = "srvtoolu_01HhTt9QAEancMSj7jE8CXN7";
const webSearchOutput = [
@@ -7055,11 +6992,7 @@ describe("createToolLoopHarness", () => {
{ message: "Search, then run the gated tool." },
);
- const pendingResponseMessages = (
- result.session.state?.["eve.runtime.pendingInputBatches"] as
- | readonly { responseMessages?: readonly ModelMessage[] }[]
- | undefined
- )?.[0]?.responseMessages;
+ const pendingResponseMessages = parkedSteps(result.session)[0]?.messages;
expect(result.next).toBeNull();
expect(pendingResponseMessages).toEqual([
@@ -7095,7 +7028,6 @@ describe("createToolLoopHarness", () => {
toolName: "add",
type: "tool-call",
},
- approvalRequest,
],
role: "assistant",
},
@@ -7382,122 +7314,6 @@ describe("createToolLoopHarness", () => {
]);
});
- it("preserves AI-SDK StepResult getter properties when storing accumulated messages", async () => {
- /*
- * AI SDK `StepResult` is a class with prototype getters for
- * `content`, `toolCalls`, `toolResults`, and `text`. The accumulated
- * response adapter must read those getters explicitly; rebuilding
- * it through object spread would copy only own enumerable properties,
- * silently turning all four getter-backed fields into `undefined`.
- */
- class FakeStepResult {
- response = {
- messages: [{ content: "`/workspace`", role: "assistant" as const }],
- };
- finishReason = "stop" as const;
- get content(): unknown[] {
- return [];
- }
- get text(): string {
- return "`/workspace`";
- }
- get toolCalls(): unknown[] {
- return [];
- }
- get toolResults(): unknown[] {
- return [];
- }
- get usage(): unknown {
- return undefined;
- }
- }
-
- setupMockAgent({
- finishReason: "stop",
- fullStreamParts: [
- {
- output: { ok: true },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- { id: "text-1", text: "`/workspace`", type: "text-delta" },
- { finishReason: "stop", type: "finish-step" },
- ],
- response: {
- messages: [{ content: "`/workspace`", role: "assistant" }],
- },
- text: "`/workspace`",
- toolCalls: [],
- toolResults: [],
- });
-
- /*
- * Override the agent mock so `onStepEnd` receives a class
- * instance — matching the AI SDK runtime shape — instead of the
- * plain object produced by `setupMockAgent`. This is what makes
- * the getter trap reachable from the test.
- */
- vi.mocked(ToolLoopAgent).mockImplementation(function (
- this: Record<string, unknown>,
- settings: MockAgentSettings,
- ) {
- const { onStepEnd } = settings;
- this.stream = vi.fn().mockImplementation(async () => {
- const stepInstance = new FakeStepResult();
- const fullStream = createExplicitMockFullStream([
- {
- output: { ok: true },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- { id: "text-1", text: "`/workspace`", type: "text-delta" },
- { finishReason: "stop", type: "finish-step" },
- ]);
- if (onStepEnd) {
- void Promise.resolve().then(() => onStepEnd(stepInstance as unknown));
- }
- return {
- fullStream,
- responseMessages: Promise.resolve([
- {
- content: [
- {
- output: { type: "json", value: { ok: true } },
- toolCallId: "call-1",
- toolName: "bash",
- type: "tool-result",
- },
- ],
- role: "tool",
- },
- ...stepInstance.response.messages,
- ]),
- steps: Promise.resolve([stepInstance]),
- };
- });
- this.generate = vi.fn().mockResolvedValue(new FakeStepResult());
- return this as unknown as ToolLoopAgent;
- } as unknown as MockAgentConstructor);
-
- const { emit } = createEventCollector();
- const session = createPendingBashApprovalSession();
-
- const harness = createToolLoopHarness(createTestConfig(emit, { tools: new Map() }));
- const result = await harness(session, {
- inputResponses: [{ optionId: "approve", requestId: "approval-1" }],
- });
-
- expect(result.session.history.filter((msg) => msg.role === "tool")).toHaveLength(2);
- expect(result.session.history.map((msg) => msg.role)).toEqual([
- "assistant",
- "tool",
- "tool",
- "assistant",
- ]);
- });
-
it("emits parallel tool calls incrementally and preserves stream result order", async () => {
setupMockAgent({
finishReason: "stop",
@@ -7815,7 +7631,7 @@ describe("createToolLoopHarness", () => {
expect(serializedProjection).toMatch(/pending/iu);
expect(serializedProjection).toContain("approval-1");
expect(serializedProjection).toContain("bash");
- expect(hasPendingInputBatch(result.session.state)).toBe(true);
+ expect(openRequestIds(result.session).size > 0).toBe(true);
expect(getCompatibilityEventTypes(events)).toEqual([
"session.started",
"turn.started",
@@ -7974,9 +7790,15 @@ describe("createToolLoopHarness", () => {
const result = await runStep(session, { message: "Delete the temp directory." });
expect(typeof result.next).toBe("function");
+ // eve decides approvals itself, so history keeps the call and its result, not the SDK's parts.
expect(result.session.history).toEqual([
{ content: "Delete the temp directory.", kind: "user" as const, role: "user" },
- ...responseMessages,
+ ...responseMessages.map((message) => ({
+ ...message,
+ content: message.content.filter(
+ (part) => part.type !== "tool-approval-request" && part.type !== "tool-approval-response",
+ ),
+ })),
]);
expect(events.filter((event) => event.type === "input.requested")).toEqual([]);
expect(events.filter((event) => event.type === "actions.requested")).toHaveLength(1);
@@ -8017,7 +7839,7 @@ describe("createToolLoopHarness", () => {
? (settings: S) => ToolLoopAgent
: never);
- const session = appendPendingInputBatch({
+ const session = parkedOnApproval({
requests: [
{
action: {
@@ -8086,7 +7908,13 @@ describe("createToolLoopHarness", () => {
await createToolLoopHarness(config)(session, { message: "approve" });
+ // The answer runs the call; the model reads its result, never the text that approved it.
expect(generateCalls[0]).toEqual([
+ {
+ content: expect.stringContaining("[Pending approvals]"),
+ kind: "context.state",
+ role: "user",
+ },
{
content: [
{
@@ -8095,21 +7923,16 @@ describe("createToolLoopHarness", () => {
toolName: "guarded_echo",
type: "tool-call",
},
- {
- approvalId: "approval-1",
- toolCallId: "call-1",
- type: "tool-approval-request",
- },
],
role: "assistant",
},
{
content: [
{
- approvalId: "approval-1",
- approved: true,
- reason: undefined,
- type: "tool-approval-response",
+ output: { type: "text", value: "ok" },
+ toolCallId: "call-1",
+ toolName: "guarded_echo",
+ type: "tool-result",
},
],
role: "tool",
@@ -8117,124 +7940,6 @@ describe("createToolLoopHarness", () => {
]);
});
- it("defers durable and ephemeral context past the approval-response model call", async () => {
- setupMockAgent({
- finishReason: "stop",
- response: { messages: [{ content: "Approved.", role: "assistant" }] },
- text: "Approved.",
- toolCalls: [],
- toolResults: [],
- });
-
- const readGenerateMessages = (index: number) => {
- const agent = vi.mocked(ToolLoopAgent).mock.results[index]?.value;
- if (agent === undefined) {
- throw new Error(`ToolLoopAgent mock did not return instance ${String(index)}.`);
- }
- const call = vi.mocked(agent.generate).mock.calls[0]?.[0];
- if (call === undefined) {
- throw new Error(`ToolLoopAgent instance ${String(index)} did not generate.`);
- }
- return call.messages;
- };
-
- const readPreparedMessages = async (index: number) => {
- const settings = vi.mocked(ToolLoopAgent).mock.calls[index]?.[0];
- if (settings === undefined) {
- throw new Error(`ToolLoopAgent mock did not receive settings ${String(index)}.`);
- }
- const messages = readGenerateMessages(index);
- const prepareStep = getPrepareStep<ModelMessage[], { messages?: ModelMessage[] }>(
- settings.prepareStep,
- );
- const prepared = await prepareStep({
- context: undefined,
- messages,
- model: settings.model,
- stepNumber: 0,
- steps: [],
- });
- return prepared.messages ?? [];
- };
-
- const config = createTestConfig(undefined, {
- resolveModel: vi.fn().mockResolvedValue(
- new MockLanguageModelV3({
- modelId: "claude-sonnet-4-5",
- provider: "anthropic.messages",
- }),
- ),
- tools: new Map([
- [
- "bash",
- {
- description: "Run shell commands",
- execute: vi.fn().mockResolvedValue("ok"),
- inputSchema: jsonSchema({ type: "object" }),
- name: "bash",
- },
- ],
- ]),
- });
- const harness = createToolLoopHarness(config);
- const context = "<linear_context>issue metadata</linear_context>";
- const ephemeralContext = "Client context:\ncurrent page";
-
- const firstResult = await harness(
- createPendingBashApprovalSession(),
- attachClientContext(
- {
- context: [context],
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- },
- [ephemeralContext],
- ),
- );
-
- const firstMessages = readGenerateMessages(0);
- expect(typeof firstResult.next).toBe("function");
- expect(firstMessages.at(-1)?.role).toBe("tool");
- expect(firstMessages).not.toContainEqual({
- content: context,
- kind: "user" as const,
- role: "user",
- });
- expect(firstMessages).not.toContainEqual({
- content: ephemeralContext,
- kind: "user" as const,
- role: "user",
- });
- expect((await readPreparedMessages(0)).at(-1)).toMatchObject({
- providerOptions: {
- anthropic: { cacheControl: { type: "ephemeral" } },
- },
- role: "tool",
- });
-
- const secondResult = await harness(firstResult.session);
-
- const secondMessages = readGenerateMessages(1);
- expect(secondResult.next).toBeNull();
- expect(secondMessages.slice(0, firstMessages.length)).toEqual(firstMessages);
- expect(secondMessages.slice(-2)).toEqual([
- { content: ephemeralContext, kind: "context.instruction", role: "user" },
- { content: context, kind: "context.instruction", role: "user" },
- ]);
- expect((await readPreparedMessages(1)).at(-1)).toMatchObject({
- content: context,
- kind: "context.instruction",
- providerOptions: {
- anthropic: { cacheControl: { type: "ephemeral" } },
- },
- role: "user",
- });
- expect(secondResult.session.history).not.toContainEqual({
- content: ephemeralContext,
- kind: "user" as const,
- role: "user",
- });
- });
-
it("emits compaction.requested and compaction.completed when compaction triggers", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
vi.mocked(compactMessages).mockResolvedValue([
@@ -8530,7 +8235,8 @@ describe("createToolLoopHarness", () => {
const result = await runStep(session);
expect(result.next).toBeNull();
- expect(result.session).toBe(session);
+ // Only the lifecycle the step published joins the session.
+ expect({ ...result.session, state: session.state }).toEqual(session);
expect(getCompatibilityEventTypes(events)).toEqual(["session.waiting"]);
expect(ToolLoopAgent).not.toHaveBeenCalled();
expect(compactMessages).not.toHaveBeenCalled();
@@ -8557,7 +8263,8 @@ describe("createToolLoopHarness", () => {
const result = await contextStorage.run(ctx, () => runStep(session));
expect(result.next).toBeNull();
- expect(result.session).toBe(session);
+ // Only the lifecycle the step published joins the session.
+ expect({ ...result.session, state: session.state }).toEqual(session);
expect(ctx.get(HistoryStateKey)).toEqual({ availableSkills: "old message" });
expect(getCompatibilityEventTypes(events)).toEqual(["compaction.requested", "session.waiting"]);
expect(ToolLoopAgent).not.toHaveBeenCalled();
@@ -8582,7 +8289,8 @@ describe("createToolLoopHarness", () => {
const result = await runStep(session);
expect(result.next).toBeNull();
- expect(result.session).toBe(session);
+ // Only the lifecycle the step published joins the session.
+ expect({ ...result.session, state: session.state }).toEqual(session);
expect(getCompatibilityEventTypes(events)).toEqual(["session.waiting"]);
expect(compactMessages).not.toHaveBeenCalled();
expect(ToolLoopAgent).not.toHaveBeenCalled();
@@ -8952,7 +8660,7 @@ describe("createToolLoopHarness", () => {
providerOptions: structuredClone(prepared.providerOptions),
tools: Object.entries(settings.tools ?? {}).map(([name, tool]) => ({
description: structuredClone(tool.description),
- inputSchema: structuredClone(tool.inputSchema),
+ inputSchema: structuredClone((tool.inputSchema as { jsonSchema: unknown }).jsonSchema),
name,
providerOptions: structuredClone(tool.providerOptions),
})),
@@ -10858,7 +10566,7 @@ describe("createToolLoopHarness", () => {
});
it("keeps files a workflow tool projects for the model out of history", async () => {
- const { setPendingCoordinationBatch } = await import("#harness/coordination.js");
+ const { withParkedStep } = await import("#internal/testing/session-machine.js");
const { toolOutput, toolOutputPart } = await import("#tools/model-output.js");
setupMockAgent({
finishReason: "stop",
@@ -10883,9 +10591,9 @@ describe("createToolLoopHarness", () => {
},
],
]);
- const parked = setPendingCoordinationBatch({
+ const parked = withParkedStep(createTestSession(), {
event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
- responseMessages: [
+ messages: [
{
content: [
{ input: {}, toolCallId: "shot-1", toolName: "screenshot", type: "tool-call" },
@@ -10893,7 +10601,6 @@ describe("createToolLoopHarness", () => {
role: "assistant",
},
],
- session: createTestSession(),
tasks: [
{
callId: "shot-1",
@@ -11232,14 +10939,14 @@ describe("createToolLoopHarness", () => {
: undefined,
}),
);
- const initial = setHarnessEmissionState(
+ const initial = withOpenTurn(
createTestSession({
history: [
{ role: "user", content: "Previous request", kind: "user" as const },
{ role: "assistant", content: "Previous answer" },
],
}),
- { sessionStarted: true, sequence: 1, stepIndex: 0, turnId: "turn_1" },
+ { sequence: 1, stepIndex: 0, turnId: "turn_1" },
);
const input = { context: ["Current channel context"], message: "Add 20 and 22." };
const first = await contextStorage.run(ctx, () =>
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 3538508cf..0145ad51e 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -1,466 +1,48 @@
-import { declinedSignInEvents, withdrawHeldSignIns } from "#harness/held-requests.js";
-import { setTimeout as delay } from "node:timers/promises";
-import { GenerationSteering } from "#harness/generation-steering.js";
-import { interruptStreamOnFailure } from "#harness/interruptible-stream.js";
-import {
- isStepCount,
- type LanguageModelCallEndEvent,
- type LanguageModel,
- type ModelMessage,
- type ProviderMetadata,
- type SystemModelMessage,
- type TelemetryOptions,
- ToolLoopAgent,
- type ToolSet,
- type TypedToolCall,
- type TypedToolError,
- type TypedToolResult,
-} from "ai";
-import type { SessionAuthContext } from "#channel/types.js";
-import { resolveInstalledPackageInfo } from "#internal/application/package.js";
-import { readClientContext } from "#internal/client-context.js";
-import { resolveModelProvider, resolveProviderHeaders } from "#internal/gateway.js";
-import { createErrorId, createLogger, formatError, logError } from "#internal/logging.js";
-import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
import { contextStorage } from "#context/container.js";
-import {
- estimateRequestEnvelope,
- getRequestEnvelopeTokens,
- setRequestEnvelopeTokens,
-} from "#harness/request-envelope.js";
-import {
- AuthKey,
- HistoryStateKey,
- ParentSessionKey,
- ScheduleIdKey,
- SessionCallbackKey,
- StaticModelReferenceKey,
-} from "#context/keys.js";
-import {
- buildDynamicInstructionMessages,
- drainDynamicInstructionUserMessages,
- prepareDynamicInstructionPreamble,
-} from "#context/dynamic-instruction-lifecycle.js";
-import {
- drainMemoryCommit,
- prepareMemoryCompaction,
- prepareMemoryPreamble,
-} from "#context/memory-lifecycle.js";
-import { isDynamicModelSelectionError } from "#context/dynamic-model-lifecycle.js";
-import { getEffectiveModelSelection } from "#context/effective-model.js";
-import {
- buildDynamicTools,
- buildResponseAuthorizationTools,
-} from "#context/build-dynamic-tools.js";
-import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
-import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
-import { getPendingAnnouncements } from "#harness/announcements.js";
-import { toErrorMessage } from "#shared/errors.js";
-import {
- createActionResultEvent,
- createApprovalCandidateEvent,
- createApprovalSettledEvent,
- createCompactionCompletedEvent,
- createCompactionRequestedEvent,
- createContextClearedEvent,
- createInputResolvedEvent,
- createInputRequestedEvent,
- createResultCompletedEvent,
- createSessionWaitingEvent,
- createTurnWaitingEvent,
- type UnstampedMessageStreamEvent,
-} from "#protocol/message.js";
-import type { RuntimeTraceContext } from "#protocol/message.js";
-import type { HarnessToolDefinition } from "#harness/execute-tool.js";
-import type { InputRequest } from "#shared/input.js";
-import {
- hydrateSandboxAttachments,
- moveToolResultFilesToUserMessages,
- stageAttachmentsToSandbox,
- stageToolResultMedia,
-} from "#harness/attachment-staging.js";
-import {
- compactMessages,
- getInputTokenCount,
- resolveCompactionModel,
- shouldCompact,
-} from "#harness/compaction.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,
- getSessionUsage,
- getTurnUsageState,
- setTurnUsageState,
- type TokenUsageDelta,
-} from "#harness/turn-tag-state.js";
-import type { TokenUsage } from "#shared/token-usage.js";
-import {
- applySessionLimitContinuation,
- enforceSessionUsageLimit,
-} from "#harness/session-limit-enforcement.js";
-import { setEveAttributes } from "#runtime/attributes/emit.js";
-import {
- advanceStep,
- emitFailedStep,
- emitRecoverableFailedTurn,
- emitStepStarted,
- emitStreamContent,
- emitTurnEpilogue,
- emitTurnPreamble,
- getHarnessEmissionState,
- setHarnessEmissionState,
-} from "#harness/emission.js";
-import { extractToolApprovalInputRequests } from "#harness/input-extraction.js";
-import {
- renderPendingApprovalsInstruction,
- renderPendingApprovalsSnippet,
-} from "#harness/hitl/approval-prompt.js";
-import {
- createToolResultMessagePartFromToolError,
- isToolResultError,
-} from "#harness/action-result-helpers.js";
-import { activeTurnId } from "#harness/active-turn-id.js";
-import {
- clearTurnClientContextState,
- getTurnClientContextState,
- setTurnClientContextState,
-} from "#harness/turn-client-context.js";
-import {
- getApprovalAuditState,
- markApprovalCandidateHistoryEventEmitted,
- markApprovalCandidatePendingEventEmitted,
- markApprovalSettlementEventEmitted,
-} from "#harness/approval-candidates.js";
-import { coordinateApprovalDelivery } from "#harness/approval-delivery-coordinator.js";
-import type { InstrumentationAttempt, InstrumentationStepScope } from "#instrumentation/runtime.js";
-import {
- answerSessionLimitFromText,
- consumeDeferredStepInput,
- getApprovedTools,
- getPendingInputRequestIds,
- hasRunnableDeferredStepInput,
- hasStepInput,
- resolvePendingInput,
- selectApprovalReplayBatch,
- appendPendingInputBatch,
-} from "#harness/input-requests.js";
-import {
- getPendingInputBatches,
- queueDeferredStepInput,
- type PendingInputBatchEvent,
-} from "#harness/pending-input-batches.js";
-import {
- convertStaleResponsesToUserMessage,
- dropStaleSessionLimitContinuationResponses,
-} from "#harness/stale-input-responses.js";
-import {
- createFrameworkUserMessage,
- createUserMessage,
- frameworkMessageKindForStepInput,
- normalizeModelMessages,
- normalizeUserContent,
- followsToolResults,
- resolveAssistantStepText,
- TOOL_RESULT_BOUNDARY,
- type HarnessModelMessage,
- type UserModelMessage,
- validateHarnessModelMessages,
-} from "#harness/messages.js";
-import { normalizeProviderToolHistory } from "#harness/provider-tool-history.js";
-import { authorizationEventFields } from "#harness/authorization-event-fields.js";
-import {
- getPendingAuthorization,
- getSupersededAuthorizationChallenges,
- setPendingAuthorization,
-} from "#harness/authorization.js";
-import { resolveInlineAuthorizationInterrupt } from "#harness/inline-tool-authorization.js";
-import {
- createAuthorizationCompletedEvent,
- createAuthorizationRequiredEvent,
- createMessageCompletedEvent,
- createStepCompletedEvent,
- createStepStartedEvent,
-} from "#protocol/message.js";
-import {
- appendTaskContext,
- isTaskTool,
- taskSystemMessages,
- withTaskTools,
- workingTaskIds,
-} from "#execution/tasks/model-step.js";
-import { renderFinalOutputWhileWorkingError } from "#execution/tasks/render.js";
-import { setApprovedCallCallers } from "#harness/approved-call-callers.js";
-import {
- classifyModelCallError,
- ContentFilteredModelResponseError,
- EmptyModelResponseError,
- extractModelCallErrorDetails,
- extractUnsupportedProviderToolTypes,
- isNoOutputGeneratedError,
- type UpstreamRejectionSummary,
- extractUpstreamRejectionMessage,
-} from "#harness/model-call-error.js";
-import { summarizeKnownError, type SemanticErrorSummary } from "#harness/semantic-errors/index.js";
-import { isTurnCancellation, throwIfTurnAborted } from "#harness/turn-cancellation.js";
-import type { JsonObject, JsonValue } from "#shared/json.js";
-import { extractWorkflowStreamWriteErrorDetails } from "#harness/workflow-stream-error.js";
-import { getAdvertisedTools } from "#harness/advertised-tools.js";
-import {
- applyLastToolCacheBreakpoint,
- applySystemCacheBreakpoint,
- detectPromptCachePath,
- getAnthropicCacheMarker,
-} from "#harness/prompt-cache.js";
-import { resolveFrameworkToolFromUpstreamType } from "#harness/provider-tools.js";
-import {
- getPendingCoordinationBatch,
- resolvePendingCoordination,
- setPendingCoordinationBatch,
-} from "#harness/coordination.js";
-import {
- getInvalidToolCallInputError,
- isInvalidToolCall,
-} from "#harness/tool-call-input-errors.js";
-import {
- buildStepHooks,
- emitStepActions,
- readGatewayGenerationId,
- type HarnessStepResult,
-} from "#harness/step-hooks.js";
-import { resolveCallProviderOptions } from "#harness/provider-safety.js";
-import { resolveConversationId } from "#shared/conversation-identity.js";
-import {
- buildToolApproval,
- buildToolSetFromDefinitions,
- buildToolSetWithProviderTools,
-} from "#harness/tools.js";
-import { buildFinalOutputTool, FINAL_OUTPUT_TOOL_NAME } from "#harness/final-output.js";
-import { toModelSchema } from "#tools/schema.js";
-import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
-import { createHistoryViewPreparer, type HistoryViewProjector } from "#shared/history-view.js";
-import {
- canonicalizeMemoryRecords,
- clearMemorySessionState,
- shouldCanonicalizeMemory,
-} from "#shared/memory-state.js";
-import {
- type CompactionConfig,
- type HarnessSession,
- type HarnessToolMap,
- requireSessionModelReference,
- type SettledTurn,
- type StepFn,
- type StepInput,
- type StepResult,
- type ToolLoopHarnessConfig,
+import { ScheduleIdKey, StaticModelReferenceKey } from "#context/keys.js";
+import { GenerationSteering } from "#harness/generation-steering.js";
+import { compactHistory, replaceSessionHistory } from "#harness/compaction/step.js";
+import { runModelStep } from "#harness/model-call/run.js";
+import { handleStepResult } from "#harness/step/after-model.js";
+import type { Publish } from "#harness/session-machine/commit.js";
+import {
+ saveProjection,
+ stepProjection,
+ type StepProjection,
+} from "#harness/session-machine/current.js";
+import {
+ acceptHumanInput,
+ admitApprovedWork,
+ discardClearedHumanInput,
+} from "#harness/hitl/index.js";
+import { clear } from "#harness/session-machine/transitions.js";
+import { activeTurnId, turnPosition } from "#harness/session-machine/view.js";
+import { createStep, openTurn, type Step } from "#harness/step/context.js";
+import { prepareTurnInput, settleRuntimeWork } from "#harness/step/intake.js";
+import type {
+ HarnessSession,
+ StepFn,
+ StepInput,
+ StepResult,
+ ToolLoopHarnessConfig,
} from "#harness/types.js";
+import type { InstrumentationAttempt, InstrumentationStepScope } from "#instrumentation/runtime.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { createHistoryViewPreparer } from "#shared/history-view.js";
+import { clearMemorySessionState } from "#shared/memory-state.js";
-/**
- * Creates a tool-loop harness step function backed by AI SDK `ToolLoopAgent`.
- */
-
-/**
- * Builds the `telemetry` value for the AI SDK from authored settings.
- *
- * Destination runtime context and eve-specific identifiers such as
- * `eve.session.id` are flowed through.
- * Bound instrumentation supplies custom context because AI SDK v7 surfaces
- * per-call attributes via `runtimeContext`, not a dedicated metadata field on
- * `TelemetryOptions`.
- */
const environment = process.env.NODE_ENV ?? "unknown";
const eveVersion = resolveInstalledPackageInfo().version;
-const log = createLogger("harness.tool-loop");
-
-/**
- * Wired as the agent's `onToolExecutionEnd`. On the `tool-error` branch
- * the `error` is still the original throwable (stack/cause intact),
- * unlike the message-only `tool-error` part the model later sees.
- */
-function logToolExecutionError(event: {
- readonly toolCall: { readonly toolName: string; readonly toolCallId: string };
- readonly toolOutput: { readonly type: string; readonly error?: unknown };
-}): void {
- // A tool unwinding because its turn was cancelled is the expected outcome
- // of a user action, not a failure worth an error log.
- if (event.toolOutput.type !== "tool-error" || isTurnCancellation(event.toolOutput.error)) {
- return;
- }
- logError(log, "tool execution failed", event.toolOutput.error, {
- toolName: event.toolCall.toolName,
- toolCallId: event.toolCall.toolCallId,
- });
-}
-
-/**
- * Max attempts (1 original + N retries) for transient model-call
- * failures before the harness gives up and falls back to the
- * recoverable/terminal emission path. Kept small on purpose — every
- * attempt costs a round-trip plus prompt tokens, and the dominant
- * use case (429 / 502) clears quickly or not at all.
- */
-const MODEL_CALL_MAX_ATTEMPTS = 3;
-
-/**
- * Base delay (ms) between model-call retries. Doubled each attempt,
- * plus a small random jitter to avoid thundering-herd behavior when
- * a provider incident clears.
- */
-const MODEL_CALL_RETRY_BASE_DELAY_MS = 500;
-
-function mergeSystemInstructions(
- instructions: readonly SystemModelMessage[],
-): SystemModelMessage | undefined {
- if (instructions.length === 0) {
- return undefined;
- }
-
- if (instructions.length === 1) {
- return { ...instructions[0]! };
- }
-
- let providerOptions: SystemModelMessage["providerOptions"] | undefined;
- for (const instruction of instructions) {
- if (instruction.providerOptions !== undefined) {
- providerOptions = {
- ...providerOptions,
- ...instruction.providerOptions,
- };
- }
- }
-
- const merged: SystemModelMessage = {
- role: "system",
- content: instructions.map((instruction) => instruction.content).join("\n\n"),
- };
- if (providerOptions !== undefined) {
- merged.providerOptions = providerOptions;
- }
- return merged;
-}
-
/**
- * Builds AI Gateway app attribution headers when the model is gateway-routed.
+ * Creates the harness step: one step of a session, backed by the AI SDK's `ToolLoopAgent`.
*
- * Bare model ids and `gateway.*` model instances route through AI Gateway.
- * Direct-provider model instances receive no Gateway-specific headers.
+ * A step settles what earlier steps parked and takes its delivery's answers, opens or joins the
+ * turn, runs the work those answers approved, then makes one model step and acts on its response.
+ * Every lifecycle change goes through the session machine (`Step.apply`).
*/
-function buildGatewayAttributionHeaders(
- model: LanguageModel,
- runtimeIdentity: ToolLoopHarnessConfig["runtimeIdentity"],
-): Record<string, string> | undefined {
- const providerHeaders = resolveProviderHeaders(model);
- if (providerHeaders === undefined) return undefined;
-
- const title = runtimeIdentity?.agentName ?? runtimeIdentity?.agentId;
- const deploymentHost = process.env.VERCEL_PROJECT_PRODUCTION_URL || process.env.VERCEL_URL;
- const referer = deploymentHost ? `https://${deploymentHost}` : undefined;
-
- const headers: Record<string, string> = { ...providerHeaders };
- if (title) headers["x-title"] = title;
- if (referer) headers["http-referer"] = referer;
- return headers;
-}
-
-async function resolveEffectiveRuntimeModel(input: {
- readonly config: ToolLoopHarnessConfig;
- readonly ctx: ReturnType<typeof contextStorage.getStore>;
- readonly session: HarnessSession;
-}): Promise<{
- readonly model: LanguageModel;
- readonly session: HarnessSession;
-}> {
- if (input.ctx === undefined) {
- const reference = input.session.agent.modelReference;
- if (reference === undefined) {
- throw new Error("Dynamic model selection is unavailable outside an eve runtime context.");
- }
- return {
- model: await input.config.resolveModel(reference),
- session: input.session,
- };
- }
-
- const selected = getEffectiveModelSelection(input.ctx);
-
- if (selected === null) {
- throw new Error(
- "Dynamic model selection is required before model-dependent work begins. Add a matching resolver handler that returns a concrete model.",
- );
- }
-
- return {
- model:
- selected.model !== undefined
- ? selected.model
- : await input.config.resolveModel(selected.reference),
- session: updateSessionModelReference(input.session, selected.reference),
- };
-}
-
-function updateSessionModelReference(
- session: HarnessSession,
- modelReference: RuntimeModelReference,
-): HarnessSession {
- if (session.agent.modelReference === modelReference) return session;
- return {
- ...session,
- agent: {
- ...session.agent,
- modelReference,
- },
- compaction: updateCompactionThresholdForModelReference({
- compaction: session.compaction,
- modelReference,
- }),
- };
-}
-
-function updateCompactionThresholdForModelReference(input: {
- readonly compaction: CompactionConfig;
- readonly modelReference: RuntimeModelReference;
-}): CompactionConfig {
- if (input.modelReference.contextWindowTokens === undefined) {
- return input.compaction;
- }
-
- return {
- ...input.compaction,
- threshold: Math.max(
- 1,
- Math.floor(
- input.modelReference.contextWindowTokens * (input.compaction.thresholdPercent ?? 0.9),
- ),
- ),
- };
-}
-
-function buildHarnessToolsWithDynamicSubagents(
- tools: HarnessToolMap,
- ctx: Parameters<typeof buildDynamicSubagentTools>[0] | undefined,
-): HarnessToolMap {
- const effectiveTools = new Map(tools);
- if (ctx === undefined) {
- return effectiveTools;
- }
-
- for (const dynamicSubagent of buildDynamicSubagentTools(ctx)) {
- if (effectiveTools.has(dynamicSubagent.name)) {
- throw new Error(
- `Dynamic subagent "${dynamicSubagent.name}" collides with another runtime-visible tool name.`,
- );
- }
- effectiveTools.set(dynamicSubagent.name, dynamicSubagent);
- }
- return effectiveTools;
-}
-
export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
config.instrumentation?.installAiSdkWarningLogger();
- const baseEmit = config.handleEvent;
async function runStep(
initialSession: Readonly<Parameters<StepFn>[0]>,
@@ -468,2987 +50,124 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
): Promise<StepResult> {
const executeStep = async (scope?: InstrumentationStepScope<HarnessSession>) => {
const current = scope?.session ?? initialSession;
+ const live = stepProjection(contextStorage.getStore(), current.state);
const generation = new GenerationSteering({
abortSignal: config.abortSignal,
steeringSignal: config.steeringSignal,
- outputStarted: getHarnessEmissionState(current.state).assistantOutputStarted,
+ outputStarted: turnPosition(live.read()).assistantOutputStarted,
});
try {
- return await executeStepBody(current, generation, input, scope);
+ const result = await executeStepBody(current, generation, live, input, scope);
+ // The step saves the lifecycle it published with the state that follows it.
+ return { ...result, session: saveProjection(result.session, live.read()) };
} finally {
generation.dispose();
}
};
return (
config.instrumentation?.runStep(
- {
- environment,
- eveVersion,
- hasInput: hasStepInput(input),
- session: initialSession,
- },
+ { environment, eveVersion, hasInput: hasStepInput(input), session: initialSession },
executeStep,
) ?? executeStep()
);
}
async function executeStepBody(
- initialSession: Readonly<Parameters<StepFn>[0]>,
+ initialSession: HarnessSession,
generation: GenerationSteering,
- input?: StepInput,
- stepInstrumentation?: InstrumentationStepScope<HarnessSession>,
+ live: StepProjection,
+ input: StepInput | undefined,
+ instrumentation: InstrumentationStepScope<HarnessSession> | undefined,
): Promise<StepResult> {
- let session = initialSession;
const prepareHistory = createHistoryViewPreparer({
previous: config.historyView,
projector: config.historyProjector,
});
- prepareHistory(session.history, session.state);
- const projectHistory = (
- messages: readonly ModelMessage[],
- state: HarnessSession["state"],
- ): readonly ModelMessage[] => prepareHistory(messages, state).messages;
-
- let emissionState = getHarnessEmissionState(session.state);
- const store = contextStorage.getStore();
- if (store !== undefined && !store.has(StaticModelReferenceKey)) {
- store.setVirtualContext(
+ prepareHistory(initialSession.history, initialSession.state);
+ const ctx = contextStorage.getStore();
+ if (ctx !== undefined && !ctx.has(StaticModelReferenceKey)) {
+ ctx.setVirtualContext(
StaticModelReferenceKey,
- session.agent.dynamicModel === true ? null : (session.agent.modelReference ?? null),
- );
- }
- const parent = store?.get(ParentSessionKey);
- const callback = store?.get(SessionCallbackKey);
- const hasDelegatedCaller = parent !== undefined || callback !== undefined;
- // A child's caller and a schedule hear only the turn's real end, so a held
- // turn's text isn't posted as their reply. A person reads a root session.
- const hidesHeldText = hasDelegatedCaller || store?.get(ScheduleIdKey) !== undefined;
- let activeAttemptScope: InstrumentationAttempt | undefined;
- let frameworkToolNames = new Set<string>();
- const instrumentedEmit =
- stepInstrumentation?.createHandleEvent({
- getAttemptScope: () => activeAttemptScope,
- isFrameworkTool: (name) => frameworkToolNames.has(name),
- handleEvent: baseEmit,
- turnId: activeTurnId(emissionState),
- }) ?? baseEmit;
- const emit: typeof instrumentedEmit =
- instrumentedEmit === undefined
- ? undefined
- : async (event, messages) => {
- generation.beforeEvent(event);
- await instrumentedEmit(event, messages);
- };
- const failModelSelection = async (
- error: unknown,
- failureState: ReturnType<typeof getHarnessEmissionState>,
- ): Promise<StepResult> => {
- throwIfTurnAborted(config.abortSignal);
- stepInstrumentation?.recordError(error);
- if (!emit) {
- throw error;
- }
-
- const errorId = createErrorId();
- const message = toErrorMessage(error);
- log.error("model selection failed terminally", {
- error,
- errorId,
- sessionId: session.sessionId,
- turnId: failureState.turnId,
- });
- await emitFailedStep(emit, failureState, {
- code: "MODEL_SELECTION_FAILED",
- details: { errorId },
- message,
- sessionId: session.sessionId,
- usage: getSessionUsage(session),
- });
-
- return {
- next: hasDelegatedCaller
- ? { done: true, isError: true, output: message }
- : { done: true, output: "" },
- session,
- };
- };
- const failBoundaryEvent = async (
- error: unknown,
- failureState: ReturnType<typeof getHarnessEmissionState>,
- ): Promise<StepResult> => {
- throwIfTurnAborted(config.abortSignal);
- if (isTurnCancellation(error)) throw error;
- if (isDynamicModelSelectionError(error)) return failModelSelection(error, failureState);
- throw error;
- };
- const preparePreambleTrace = async (): Promise<RuntimeTraceContext | undefined> => {
- return await stepInstrumentation?.preparePreamble({
- sequence: emissionState.sequence,
- sessionStarted: emissionState.sessionStarted,
- traceContext: stepInstrumentation?.traceContext,
- turnId: activeTurnId(emissionState),
- });
- };
-
- if (config.clearOnly === true) {
- session = {
- ...session,
- state: clearMemorySessionState(session.state),
- };
- session = replaceSessionHistory(session, []);
- await emit?.(
- createContextClearedEvent({
- sequence: emissionState.sequence,
- sessionId: session.sessionId,
- turnId: activeTurnId(emissionState),
- }),
- );
- await emit?.(createSessionWaitingEvent(getSessionUsage(session)));
- return { next: null, session };
- }
-
- if (config.compactOnly === true) {
- if (session.history.length > 0) {
- try {
- const ctx = contextStorage.getStore();
- const resolvedModel = await resolveEffectiveRuntimeModel({ config, ctx, session });
- session = resolvedModel.session;
-
- const compacted = await maybeCompact({
- abortSignal: config.abortSignal,
- auth: ctx?.get(AuthKey) ?? null,
- emit,
- emissionState: {
- ...emissionState,
- turnId: activeTurnId(emissionState),
- },
- force: true,
- historyProjector: config.historyProjector,
- messages: [...session.history],
- model: resolvedModel.model,
- requestEnvelopeTokens: getRequestEnvelopeTokens(session),
- resolveModel: config.resolveModel,
- runtimeIdentity: config.runtimeIdentity,
- session,
- telemetry: stepInstrumentation?.telemetry(),
- });
-
- session = compacted.session;
- } catch (error) {
- logError(log, "manual session compaction failed", error, {
- sessionId: session.sessionId,
- });
- }
- }
-
- await emit?.(createSessionWaitingEvent(getSessionUsage(session)));
- return { next: null, session };
- }
-
- // Resolve deferred input, task/control coordination, then HITL input; each stage
- // may park when its resume payload has not arrived.
-
- 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: answerSessionLimitFromText(session, input), session })
- : { input, session };
- session = stepInput.session;
- const coordination = await resolvePendingCoordination({
- emit,
- session,
- stepInput: stepInput.input,
- tools: config.tools,
- });
- // Workflow tool results join history here, so their files leave as refs too.
- const resolvedCoordination =
- coordination.outcome === "resolved"
- ? { ...coordination, messages: await stageToolResultMedia(coordination.messages) }
- : coordination;
- if (resolvedCoordination.outcome === "unresolved") {
- return { next: null, session: resolvedCoordination.session };
- }
- session = resolvedCoordination.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: resolvedCoordination.messages,
- pendingRequestIds,
- stepInput: dropStaleSessionLimitContinuationResponses({
- pendingRequestIds,
- stepInput: stepInput.input,
- }),
- });
- let effectiveStepInput = staleConversion.stepInput;
- // A new message reaching an open turn steers it: the turn moves past the
- // sign-ins it waits on, and its unanswered approvals resolve below.
- if (input?.message !== undefined || staleConversion.kind === "converted") {
- const withdrawal = withdrawHeldSignIns(session.state, {
- completedAt: Date.now(),
- reason: STEERED_SIGN_IN_REASON,
- });
- session = { ...session, state: withdrawal.state };
- if (withdrawal.withdrawn.length > 0) {
- if (emit) {
- for (const event of declinedSignInEvents(
- withdrawal.withdrawn,
- STEERED_SIGN_IN_REASON,
- emissionState,
- )) {
- await emit(event);
- }
- }
- const names = [...new Set(withdrawal.withdrawn.map((challenge) => challenge.name))];
- effectiveStepInput = {
- ...effectiveStepInput,
- context: [
- ...(effectiveStepInput?.context ?? []),
- `Sign-in to ${names.join(", ")} was cancelled because the user sent a new message instead. Ask to sign in again only if the new message still needs it.`,
- ],
- };
- }
- }
- const preambleStepInput =
- staleConversion.kind === "converted"
- ? { ...effectiveStepInput, message: staleConversion.displayMessage }
- : effectiveStepInput;
-
- const approvalContext = contextStorage.getStore();
- const prepareApprovalTools = async (
- batch: { readonly event?: PendingInputBatchEvent } | undefined,
- ) => {
- if (batch?.event !== undefined) await config.prepareApprovalTurn?.(batch.event);
- if (approvalContext !== undefined) {
- await config.resolveStepDynamicTools?.({
- ctx: approvalContext,
- event: createStepStartedEvent({
- modelId: session.agent.modelReference?.id ?? "dynamic",
- ...(batch?.event ?? emissionState),
- }),
- messages: projectHistory(resolvedCoordination.messages, session.state),
- });
- }
- return buildResponseAuthorizationTools({
- authoredTools: config.tools,
- context: approvalContext,
- });
- };
- const pendingApprovalChallenges = getPendingAuthorization(session.state)?.challenges ?? [];
- const coordinated = await coordinateApprovalDelivery({
- session,
- stepInput: effectiveStepInput,
- tools: config.tools,
- prepareTools: async (request) => {
- const batch = getPendingInputBatches(session.state).find((batch) =>
- batch.requests.some((entry) => entry.requestId === request.requestId),
- );
- return await prepareApprovalTools(batch);
- },
- });
- session = coordinated.session;
- if (emit) {
- for (const message of coordinated.feedback) {
- await emit(
- createMessageCompletedEvent({
- message,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
- const audit = getApprovalAuditState(session.state);
- for (const challenge of pendingApprovalChallenges) {
- if (
- !audit.candidateHistory.some(
- (candidate) =>
- candidate.candidateId === challenge.candidateId &&
- candidate.status === "timed-out" &&
- candidate.eventEmitted !== true,
- )
- )
- continue;
- await emit(
- createAuthorizationCompletedEvent({
- ...authorizationEventFields(challenge),
- outcome: "failed",
- reason: "The approval response expired. Please submit a new response.",
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
- for (const candidate of audit.activeCandidates.filter(
- (entry) => entry.pendingEventEmitted !== true,
- )) {
- await emit(
- createApprovalCandidateEvent({
- candidateId: candidate.candidateId,
- outcome: "pending",
- requestId: candidate.requestId,
- responderPrincipalId: candidate.responder.principalId,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- session = {
- ...session,
- state: markApprovalCandidatePendingEventEmitted({
- candidateId: candidate.candidateId,
- state: session.state,
- }),
- };
- }
- for (const candidate of audit.candidateHistory.filter(
- (entry) => entry.eventEmitted !== true && entry.status !== "allowed",
- )) {
- await emit(
- createApprovalCandidateEvent({
- candidateId: candidate.candidateId,
- outcome: candidate.status as Exclude<
- typeof candidate.status,
- "allowed" | "authorization-required"
- >,
- requestId: candidate.requestId,
- responderPrincipalId: candidate.responder.principalId,
- reason: candidate.reason,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- session = {
- ...session,
- state: markApprovalCandidateHistoryEventEmitted({
- candidateId: candidate.candidateId,
- state: session.state,
- }),
- };
- }
- for (const settlement of audit.settlements.filter((entry) => entry.eventEmitted !== true)) {
- await emit(
- createApprovalSettledEvent({
- outcome: settlement.outcome === "allowed" ? "approved" : "cancelled",
- requestId: settlement.requestId,
- responderPrincipalId: settlement.actor.principalId,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- session = {
- ...session,
- state: markApprovalSettlementEventEmitted({
- requestId: settlement.requestId,
- state: session.state,
- }),
- };
- }
- }
- if (coordinated.kind === "park") return { next: null, session };
- if (coordinated.kind === "continue-coordination") {
- const continuedSession =
- coordinated.stepInput === undefined
- ? session
- : queueDeferredStepInput(session, coordinated.stepInput);
- return { next: runStep, session: continuedSession };
- }
- if (coordinated.challenges.length > 0) {
- // A responder's sign-in for the turn's approval holds the turn.
- if (emit) {
- for (const challenge of coordinated.challenges) {
- await emit(
- createAuthorizationRequiredEvent({
- ...authorizationEventFields(challenge),
- description:
- challenge.challenge.instructions ?? `Authorization required for ${challenge.name}`,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- webhookUrl: challenge.hookUrl,
- }),
- );
- }
- emissionState = await holdTurnForRequest(emit, emissionState, session);
- }
- const parkedSession =
- coordinated.stepInput === undefined
- ? session
- : queueDeferredStepInput(session, coordinated.stepInput);
- const challengeSession = setHarnessEmissionState(
- {
- ...parkedSession,
- state: setPendingAuthorization(parkedSession.state, {
- challenges: coordinated.challenges,
- }),
- },
- emissionState,
- );
- return { held: { kind: "request" }, next: null, session: challengeSession };
- }
-
- // 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({
- history: resolvedCoordination.messages,
- resolveApprovalKey: resolveApprovalKeyFromTools(responseAuthorizationTools),
- session,
- stepInput: coordinated.stepInput,
- });
- if (pending.outcome === "unresolved") {
- // The coordination batch owns the assistant messages. Once that batch
- // resolves, commit its results before the still-pending HITL batch parks.
- let parkedSession =
- resolvedCoordination.outcome === "resolved"
- ? {
- ...pending.session,
- history: validateHarnessModelMessages(resolvedCoordination.messages),
- }
- : pending.session;
-
- // The turn's request is still open (a partial answer, a refused responder,
- // or a message waiting behind a budget prompt), so the turn stays held.
- if (emit) {
- emissionState = await holdTurnForRequest(emit, emissionState, parkedSession);
- parkedSession = setHarnessEmissionState(parkedSession, emissionState);
- }
- return { held: { kind: "request" }, next: null, session: parkedSession };
- }
-
- if (pending.resolvedInputs !== undefined) {
- for (const batch of pending.resolvedInputs) {
- await stepInstrumentation?.publishInputResolutions({
- batch,
- sessionId: session.sessionId,
- });
- if (emit) {
- await emit(
- createInputResolvedEvent({
- resolutions: batch.inputs.map((resolved) => {
- const resolution = {
- kind: resolved.request.kind,
- outcome: resolved.outcome,
- requestId: resolved.request.requestId,
- };
- if (resolved.response === undefined) return resolution;
- return { ...resolution, response: resolved.response };
- }),
- sequence: batch.event.sequence,
- stepIndex: batch.event.stepIndex,
- turnId: batch.event.turnId,
- }),
- );
- }
- }
- }
-
- // Surface denied tool-call approvals as rejected `action.result` events.
- // The denial otherwise lives only in model history, so consumers (e.g.
- // observability) never see the tool call resolve. Attributed to the turn
- // that requested approval via the parked batch's emit coordinates.
- if (emit && pending.rejectedActions) {
- for (const rejectedBatch of pending.rejectedActions) {
- for (const result of rejectedBatch.results) {
- await emit(
- createActionResultEvent({
- rejected: true,
- result,
- sequence: rejectedBatch.event.sequence,
- stepIndex: rejectedBatch.event.stepIndex,
- turnId: rejectedBatch.event.turnId,
- }),
- );
- }
- }
- }
-
- // --- Turn preamble ------------------------------------------------------
-
- const turnId = activeTurnId(emissionState);
- const storedClientContext = getTurnClientContextState(pending.session.state, turnId);
- const clientContext =
- pending.deferredContext === true ? undefined : readClientContext(effectiveStepInput);
- const activeClientContext = clientContext ?? storedClientContext?.messages;
- const ephemeralContextMessages: UserModelMessage[] =
- activeClientContext?.map((content) =>
- createFrameworkUserMessage("context.instruction", content),
- ) ?? [];
- const preparedTurnInput: UserModelMessage[] = [];
- if (effectiveStepInput?.context !== undefined && pending.deferredContext !== true) {
- for (const entry of effectiveStepInput.context) {
- preparedTurnInput.push(createFrameworkUserMessage("context.instruction", entry));
- }
- }
- const frameworkMessageKind = frameworkMessageKindForStepInput(effectiveStepInput);
- const normalizedTurnContent = normalizeUserContent(effectiveStepInput?.message);
- const stagedTurnContent =
- normalizedTurnContent !== undefined && !pending.deferredMessage && !pending.consumedMessage
- ? await stageAttachmentsToSandbox(normalizedTurnContent)
- : undefined;
- if (stagedTurnContent !== undefined) {
- preparedTurnInput.push(
- frameworkMessageKind === undefined
- ? createUserMessage("user", stagedTurnContent)
- : createFrameworkUserMessage(frameworkMessageKind, stagedTurnContent),
- );
- }
-
- let instructionMessages: UserModelMessage[] = [];
- let memoryCommit: ReturnType<typeof drainMemoryCommit> = undefined;
- if (emit && (hasStepInput(effectiveStepInput) || hasStepInput(coordinated.stepInput))) {
- if (store !== undefined) {
- prepareDynamicInstructionPreamble(
- store,
- projectHistory(pending.session.history, pending.session.state),
- );
- prepareMemoryPreamble(store, {
- history: pending.messages,
- input: [...ephemeralContextMessages, ...preparedTurnInput],
- projector: config.historyProjector,
- state: pending.session.state,
- });
- }
- try {
- const traceContext = await preparePreambleTrace();
- emissionState = await emitTurnPreamble(
- emit,
- // A deferred message replays on a later step, which announces it then.
- pending.deferredMessage === true
- ? { ...preambleStepInput, message: undefined }
- : (preambleStepInput ?? {}),
- emissionState,
- projectHistory(
- [...pending.messages, ...ephemeralContextMessages, ...preparedTurnInput],
- pending.session.state,
- ),
- config.runtimeIdentity,
- traceContext,
- );
- } catch (error) {
- instructionMessages = store === undefined ? [] : drainDynamicInstructionUserMessages(store);
- memoryCommit = store === undefined ? undefined : drainMemoryCommit(store);
- session = {
- ...pending.session,
- history: validateHarnessModelMessages([
- ...pending.session.history,
- ...(memoryCommit?.recalledMessages ?? []),
- ...instructionMessages,
- ]),
- state: memoryCommit?.state ?? pending.session.state,
- };
- return failBoundaryEvent(error, {
- sessionStarted: true,
- sequence: emissionState.sequence,
- stepIndex: 0,
- turnId: activeTurnId(emissionState),
- });
- }
- instructionMessages = store === undefined ? [] : drainDynamicInstructionUserMessages(store);
- memoryCommit = store === undefined ? undefined : drainMemoryCommit(store);
-
- stepInstrumentation?.setTurnId(emissionState.turnId);
- }
-
- const historyLength = pending.session.history.length;
- const preambleMessages = [...(memoryCommit?.recalledMessages ?? []), ...instructionMessages];
- session = setHarnessEmissionState(
- {
- ...pending.session,
- history: validateHarnessModelMessages([...pending.session.history, ...preambleMessages]),
- state: memoryCommit?.state ?? pending.session.state,
- },
- emissionState,
- );
- // Preamble messages go before the pending transcript so an approval
- // response stays in the final tool message, where the AI SDK reads it.
- let messages: HarnessModelMessage[] = validateHarnessModelMessages([
- ...pending.messages.slice(0, historyLength),
- ...preambleMessages,
- ...pending.messages.slice(historyLength),
- ]);
-
- // A resolved session-limit continuation prompt grants a fresh token
- // budget or ends the session; see session-limit-enforcement.
- const continuation = await applySessionLimitContinuation({
+ initialSession.agent.dynamicModel === true
+ ? null
+ : (initialSession.agent.modelReference ?? null),
+ );
+ }
+ let attemptScope: InstrumentationAttempt | undefined;
+ const emit =
+ instrumentation?.createHandleEvent({
+ getAttemptScope: () => attemptScope,
+ isFrameworkTool: (name) => step.frameworkToolNames.has(name),
+ handleEvent: config.handleEvent,
+ turnId: activeTurnId(turnPosition(live.read())),
+ }) ?? config.handleEvent;
+ const publish: Publish = async (event, messages) => {
+ generation.beforeEvent(event);
+ // The publish sink folds what it publishes; without a sink, the step does, so lifecycle
+ // never depends on whether a caller listens.
+ if (emit !== undefined) await emit(event, messages);
+ if (emit === undefined || ctx === undefined) live.record(event);
+ };
+ const step = createStep({
config,
+ ctx,
emit,
- emissionState,
- limitContinuation: pending.limitContinuation,
- session,
+ instrumentation,
+ live,
+ prepareHistory,
+ publish,
+ runStep,
+ session: initialSession,
+ });
+
+ if (config.clearOnly === true) return clearContext(step);
+ if (config.compactOnly === true) return compactHistory(step);
+
+ const runtime = await settleRuntimeWork(step, input);
+ if (runtime === undefined) return { next: null, session: step.session };
+ const intake = await acceptHumanInput(step, runtime.input, { takeQueued: !runtime.waited });
+ if (intake.kind === "stop") return intake.result;
+ const turn = await prepareTurnInput(step, intake.input, {
+ consumedMessage: intake.consumedMessage,
+ });
+ if (intake.opensTurn) {
+ const failed = await openTurn(step, {
+ input: [...turn.ephemeral, ...turn.messages],
+ message: intake.message,
+ });
+ if (failed !== undefined) return failed;
+ }
+ await admitApprovedWork(step, intake.approved);
+
+ return runModelStep(step, {
+ approved: intake.approved,
+ onResponse: (response) => handleStepResult(step, response),
+ generation,
+ // A child's caller and a schedule hear only the turn's real end, so a held turn's text
+ // isn't posted as their reply. A person reads a root session.
+ hidesHeldText: step.hasDelegatedCaller || ctx?.get(ScheduleIdKey) !== undefined,
+ setAttemptScope: (scope) => {
+ attemptScope = scope;
+ },
+ turn,
});
- if (continuation.result !== null) {
- return continuation.result;
- }
- session = continuation.session;
-
- if (!hasUnansweredToolCall(messages)) {
- const taskContext = await appendTaskContext({
- messages,
- projectHistory,
- session,
- tools: config.tools,
- });
- session = taskContext.session;
- messages.push(...taskContext.messages);
- }
-
- // Keep ephemeral client context at the same position across durable steps.
- let turnClientContext = storedClientContext;
- if (clientContext !== undefined) {
- turnClientContext = {
- insertionIndex: storedClientContext?.insertionIndex ?? messages.length,
- messages: clientContext,
- turnId,
- };
- }
- if (turnClientContext !== undefined) {
- session = setTurnClientContextState(session, turnClientContext);
- }
-
- const separatesToolResults =
- stagedTurnContent !== undefined &&
- frameworkMessageKind === undefined &&
- followsToolResults(messages);
- messages = [
- ...messages,
- ...(separatesToolResults
- ? [{ content: TOOL_RESULT_BOUNDARY, role: "assistant" } as const]
- : []),
- ...preparedTurnInput,
- ];
-
- const createModelMessages = (
- durableMessages: readonly HarnessModelMessage[],
- ): HarnessModelMessage[] => {
- if (turnClientContext === undefined || turnClientContext.messages.length === 0) {
- return [...durableMessages];
- }
-
- const insertionIndex = Math.min(
- Math.max(0, turnClientContext.insertionIndex),
- durableMessages.length,
- );
- return [
- ...durableMessages.slice(0, insertionIndex),
- ...turnClientContext.messages.map((content) =>
- createFrameworkUserMessage("context.instruction", content),
- ),
- ...durableMessages.slice(insertionIndex),
- ];
- };
- let projectedMessages = validateHarnessModelMessages(
- projectHistory(createModelMessages(messages), session.state),
- );
-
- // --- Model + tools ------------------------------------------------------
-
- // Direct harness unit tests may run without an ambient context.
- const ctx = store;
- let resolvedModel: Awaited<ReturnType<typeof resolveEffectiveRuntimeModel>>;
- try {
- if (ctx !== undefined && config.dispatchDynamicModelEvent !== undefined) {
- await config.dispatchDynamicModelEvent({
- ctx,
- event: {
- data: {
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: activeTurnId(emissionState),
- },
- type: "step.started",
- } as UnstampedMessageStreamEvent,
- messages: projectedMessages,
- });
- }
- resolvedModel = await resolveEffectiveRuntimeModel({
- config,
- ctx,
- session,
- });
- } catch (error) {
- return failModelSelection(error, emissionState);
- }
- session = resolvedModel.session;
- const model = resolvedModel.model;
-
- const cachePath = detectPromptCachePath(model);
- const marker = cachePath.kind === "anthropic-direct" ? getAnthropicCacheMarker() : undefined;
-
- const attributionHeaders = buildGatewayAttributionHeaders(model, config.runtimeIdentity);
- projectedMessages = validateHarnessModelMessages(
- normalizeModelMessages(projectHistory(createModelMessages(messages), session.state)),
- );
-
- if (emit) {
- try {
- await emitStepStarted(
- emit,
- emissionState,
- requireSessionModelReference(session).id,
- projectedMessages,
- );
- } catch (error) {
- return failBoundaryEvent(error, emissionState);
- }
- }
- const replayRequests = (pending.resolvedInputs ?? []).flatMap((batch) =>
- batch.inputs.filter((input) => input.outcome === "approved"),
- );
- setApprovedCallCallers(pending.resolvedInputs, session.state);
- if (replayRequests.length > 0) {
- const replayTools = buildResponseAuthorizationTools({
- authoredTools: config.tools,
- context: ctx,
- });
- for (const { request } of replayRequests) {
- if (!replayTools.has(request.action.toolName)) {
- throw new Error(
- "The approved tool is no longer available. Request a new tool call and approval.",
- );
- }
- }
- }
- const approvedTools = getApprovedTools(
- session,
- resolveApprovalKeyFromTools(
- buildResponseAuthorizationTools({ authoredTools: config.tools, context: ctx }),
- ),
- );
-
- // --- Execute via ToolLoopAgent ------------------------------------------
-
- /*
- * The `onError` override suppresses the AI SDK's default
- * `console.error(error)` handler inside `streamText`. Errors are
- * handled by the harness catch block and emitted as stream events.
- */
- // The tools advertised to the latest model call; they decide which tool calls defer.
- let modelCallCoordinationTools = config.tools;
- let modelCallEndsTurnTools: EndsTurnTools = new Map();
- const createRequestMessages = () => {
- // Persist framework announcements before the new input, or after earlier
- // tool results on a continuation, so later requests retain the full prefix.
- const currentMessages = createCurrentMessages(messages, {
- historyState: ctx?.get(HistoryStateKey),
- currentTurnMessages: preparedTurnInput,
- projectedMessages,
- });
- if (ctx !== undefined) {
- currentMessages.addSystem(buildDynamicInstructionMessages(ctx));
- }
- currentMessages.addSystem(
- taskSystemMessages(modelCallCoordinationTools, { finalReplyOnly: hidesHeldText }),
- );
- currentMessages.addAnnouncements({
- availableSkills: ctx?.get(PendingSkillAnnouncementKey),
- keyed: getPendingAnnouncements(ctx),
- });
- const pendingApprovals = renderPendingApprovalsInstruction(
- getPendingInputBatches(session.state).flatMap((batch) => batch.requests),
- );
- if (pendingApprovals !== undefined) {
- currentMessages.add(pendingApprovals, "context.state", {
- cacheFriendly: false,
- });
- }
- return currentMessages;
- };
- let currentMessages = createRequestMessages();
- let interruptedUsage: TokenUsageDelta | undefined;
- const finishSteeredStep = async (): Promise<StepResult> => {
- throwIfTurnAborted(config.abortSignal);
- ctx?.set(HistoryStateKey, currentMessages.historyState);
- if (interruptedUsage !== undefined) {
- session = setTurnUsageState(
- session,
- accumulateTurnUsage({
- previous: getTurnUsageState(session.state),
- turnId: emissionState.turnId,
- usage: interruptedUsage,
- }),
- );
- }
- // The superseded step already published `step.started`. `emit` refuses
- // events once generation is interrupted, so close the step directly.
- await instrumentedEmit?.(
- createStepCompletedEvent({
- finishReason: "other",
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- usage: interruptedUsage,
- }),
- );
- return {
- steered: true,
- next: runStep,
- session: setHarnessEmissionState(
- { ...session, history: [...currentMessages.history] },
- advanceStep(emissionState),
- ),
- };
- };
-
- // Hydrate `eve-sandbox:` ref FileParts into inline bytes for the model call
- // only. Session history remains ref-only across future step boundaries.
- let modelMessages: ModelMessage[] = [];
-
- const withTrailingUserNote = (
- messages: readonly ModelMessage[],
- note?: string,
- ): ModelMessage[] =>
- note ? [...messages, createFrameworkUserMessage("execution.retry", note)] : [...messages];
-
- const prepareModelInstructions = (extraSystemNote?: string) => {
- const extraSystemEntry: SystemModelMessage[] = extraSystemNote
- ? [{ role: "system" as const, content: extraSystemNote }]
- : [];
- const baseSystemEntry: SystemModelMessage[] = session.agent.system
- ? [{ role: "system" as const, content: session.agent.system }]
- : [];
- const rawInstructions =
- currentMessages.systemMessages.length > 0 || extraSystemEntry.length > 0
- ? [...extraSystemEntry, ...baseSystemEntry, ...currentMessages.systemMessages]
- : undefined;
- const markedInstructions =
- rawInstructions !== undefined && marker
- ? applySystemCacheBreakpoint(rawInstructions, marker)
- : rawInstructions;
- const instructions =
- markedInstructions !== undefined
- ? mergeSystemInstructions(markedInstructions)
- : (session.agent.system ?? undefined);
-
- return instructions;
- };
-
- const prepareModelCallInput = (extraSystemNote?: string) => {
- const instructions = prepareModelInstructions(extraSystemNote);
- return {
- instructions,
- telemetryRuntimeContext: stepInstrumentation?.resolveRuntimeContext({
- eveVersion,
- emissionState,
- environment,
- modelInput: {
- instructions,
- messages: modelMessages,
- },
- session,
- }),
- };
- };
-
- /**
- * Assembles the effective toolset and ToolLoopAgent for one attempt
- * of this step, then runs the model call.
- *
- * Re-invoked for every transient attempt so an earlier stream cannot
- * resolve the retry's one-shot step hooks with stale partial output.
- * Recovery stages also use it to alter the call shape: unsupported-tool
- * recovery drops the offending tool, while empty-response recovery adds
- * its retry telemetry and follow-up note.
- */
- type ModelCallOptions = {
- disabledProviderTools?: ReadonlySet<string>;
- extraSystemNote?: string;
- retryReason?: "empty-response";
- suppressStepStartedEmission?: boolean;
- trailingUserNote?: string;
- };
- let requestEnvelopeTokens = 0;
- let compactionFailure: { readonly error: unknown } | undefined;
- const throwIfCompactionFailed = () => {
- if (compactionFailure !== undefined) throw compactionFailure.error;
- };
-
- const prepareModelTools = async (opts: ModelCallOptions) => {
- const harnessTools = buildHarnessToolsWithDynamicSubagents(config.tools, ctx);
- const advertisedHarnessTools = withTaskTools(
- getAdvertisedTools({
- session,
- tools: harnessTools,
- }),
- );
- modelCallCoordinationTools = advertisedHarnessTools;
-
- const flatTools = await buildToolSetWithProviderTools({
- approvedTools,
- disabledProviderTools: opts.disabledProviderTools,
- modelReference: requireSessionModelReference(session),
- modelProvider: resolveModelProvider(model),
- tools: advertisedHarnessTools,
- });
-
- // Stream emitters resolve label callbacks by tool name, so they need the
- // dynamic tools the model can call, not only the authored ones.
- const presentationTools = new Map(advertisedHarnessTools);
- if (ctx !== undefined) {
- const dynamicTools = getAdvertisedTools({
- session,
- tools: buildDynamicTools(ctx),
- });
- const dynamicToolSet = buildToolSetFromDefinitions({
- approvedTools,
- disabledProviderTools: opts.disabledProviderTools,
- tools: dynamicTools,
- });
- // Dynamic tools override a same-named authored tool.
- for (const [name, toolDefinition] of Object.entries(dynamicToolSet)) {
- const advertised = advertisedHarnessTools.get(name);
- if (advertised?.workflowId !== undefined) {
- throw new Error(
- `Dynamic tool "${name}" collides with a coordination-visible deferred tool.`,
- );
- }
- flatTools[name] = toolDefinition;
- }
- // Match `buildToolSetFromDefinitions`: the first dynamic definition of a
- // name (step, then turn, then session) wins, and still overrides authored.
- const presentedDynamicNames = new Set<string>();
- for (const tool of dynamicTools) {
- if (presentedDynamicNames.has(tool.name)) continue;
- presentedDynamicNames.add(tool.name);
- presentationTools.set(tool.name, tool);
- }
- }
-
- if (session.outputSchema !== undefined) {
- flatTools[FINAL_OUTPUT_TOOL_NAME] = buildFinalOutputTool(session.outputSchema);
- }
-
- const advertisedModelTools = await getAdvertisedTools({
- modelTools: flatTools,
- session,
- tools: advertisedHarnessTools,
- });
- session = advertisedModelTools.session;
- const modelTools = advertisedModelTools.modelTools;
- // `endsTurn` applies only in root, unstructured turns. Only a literal
- // `true` is described to the model; a function decides from each result.
- const endsTurnTools = new Map<string, NonNullable<HarnessToolDefinition["endsTurn"]>>();
- if (!hasDelegatedCaller && session.outputSchema === undefined) {
- for (const [name, modelTool] of Object.entries(modelTools)) {
- const endsTurn = presentationTools.get(name)?.endsTurn;
- if (modelTool.type === "provider" || endsTurn === undefined || endsTurn === false) {
- continue;
- }
- endsTurnTools.set(name, endsTurn);
- if (endsTurn === true) {
- modelTool.description =
- `${modelTool.description ?? ""}\n\n${ENDS_TURN_TOOL_NOTE}`.trimStart();
- }
- }
- }
- modelCallEndsTurnTools = endsTurnTools;
-
- const effectiveTools = marker ? applyLastToolCacheBreakpoint(modelTools, marker) : modelTools;
- for (const tool of Object.values(effectiveTools)) {
- // Whatever produced this tool, the AI SDK must only receive its own
- // schema type; see toModelSchema.
- tool.inputSchema = toModelSchema(tool.inputSchema, "input");
- if (tool.outputSchema !== undefined) {
- tool.outputSchema = toModelSchema(tool.outputSchema, "output");
- }
- const execute = tool.execute;
- if (execute !== undefined)
- tool.execute = (...args) => {
- generation.protectToolExecution();
- return execute(...args);
- };
- }
-
- frameworkToolNames = new Set(
- [...presentationTools]
- .filter(([, tool]) => tool.frameworkTool === true)
- .map(([name]) => name),
- );
- return { effectiveTools, modelTools, presentationTools };
- };
-
- const runSingleModelCall = async (
- opts: ModelCallOptions & { readonly attemptIndex: number },
- ): Promise<HarnessStepResult> => {
- let { effectiveTools, modelTools, presentationTools } = await prepareModelTools(opts);
- currentMessages = createRequestMessages();
- requestEnvelopeTokens = await estimateRequestEnvelope({
- history: projectedMessages,
- instructions: prepareModelInstructions(opts.extraSystemNote),
- messages: withTrailingUserNote(currentMessages.nonSystemMessages, opts.trailingUserNote),
- tools: effectiveTools,
- });
- const clientContextTailLength =
- turnClientContext === undefined
- ? undefined
- : Math.max(0, messages.length - turnClientContext.insertionIndex);
- const compaction = await (async () => {
- try {
- return await maybeCompact({
- abortSignal: config.abortSignal,
- auth: ctx?.get(AuthKey) ?? null,
- emit,
- emissionState,
- historyProjector: config.historyProjector,
- messages: [...messages],
- model,
- promptMessages: createModelMessages(messages),
- requestEnvelopeTokens,
- resolveModel: config.resolveModel,
- runtimeIdentity: config.runtimeIdentity,
- session,
- telemetry: stepInstrumentation?.telemetry(),
- });
- } catch (error) {
- compactionFailure = { error };
- throw error;
- }
- })();
- session = compaction.session;
- if (compaction.compacted) {
- messages = compaction.messages;
- if (turnClientContext !== undefined && clientContextTailLength !== undefined) {
- turnClientContext = {
- ...turnClientContext,
- insertionIndex: Math.max(0, messages.length - clientContextTailLength),
- };
- session = setTurnClientContextState(session, turnClientContext);
- }
- session = {
- ...session,
- compaction: {
- recentWindowSize: session.compaction.recentWindowSize,
- threshold: session.compaction.threshold,
- thresholdPercent: session.compaction.thresholdPercent,
- },
- };
- projectedMessages = validateHarnessModelMessages(
- normalizeModelMessages(projectHistory(createModelMessages(messages), session.state)),
- );
- currentMessages = createRequestMessages();
- ({ effectiveTools, modelTools, presentationTools } = await prepareModelTools(opts));
- requestEnvelopeTokens = await estimateRequestEnvelope({
- history: projectedMessages,
- instructions: prepareModelInstructions(opts.extraSystemNote),
- messages: withTrailingUserNote(currentMessages.nonSystemMessages, opts.trailingUserNote),
- tools: effectiveTools,
- });
- }
- // New announcements join durable history, so they must not inflate the
- // envelope baseline and hide instruction growth on the next step.
- requestEnvelopeTokens = Math.max(
- 0,
- requestEnvelopeTokens -
- (estimateTokens(currentMessages.history) - estimateTokens(messages)),
- );
- generation.begin();
- modelMessages = await hydrateSandboxAttachments(currentMessages.nonSystemMessages);
- if (sendsToolResultFilesAsText(model)) {
- modelMessages = moveToolResultFilesToUserMessages(modelMessages);
- }
- const { instructions, telemetryRuntimeContext = {} } = prepareModelCallInput(
- opts.extraSystemNote,
- );
- // Label the reissued call's telemetry; without this a retry is only
- // visible as a second LLM span under one step.
- if (opts.retryReason) {
- telemetryRuntimeContext["eve.retry.reason"] = opts.retryReason;
- }
- // Trailing rather than an extraSystemNote prepend: keeps the provider's
- // cached prompt prefix valid, and handleStepResult rebuilds history
- // from the step's prompt messages, so the note exists only on this
- // call's wire request.
- const callMessages = withTrailingUserNote(modelMessages, opts.trailingUserNote);
-
- const instrumentationTurnId = activeTurnId(emissionState);
- const attempt = stepInstrumentation?.prepareAttempt({
- isFrameworkTool: (name) => frameworkToolNames.has(name),
- attemptIndex: opts.attemptIndex,
- runtimeContext: telemetryRuntimeContext,
- stepIndex: emissionState.stepIndex,
- turnId: instrumentationTurnId,
- });
- const attemptScope = attempt?.scope;
- activeAttemptScope = attemptScope;
-
- const hooks = buildStepHooks({
- auth: ctx?.get(AuthKey) ?? null,
- cachePath,
- emit,
- emissionState,
- emitStepStarted: opts.suppressStepStartedEmission !== true,
- marker,
- session,
- });
+ }
- const agentSettings = {
- headers: attributionHeaders,
- instructions,
- model,
- onLanguageModelCallEnd(event: LanguageModelCallEndEvent) {
- if (generation.interrupted) return;
- interruptedUsage = extractTokenUsageDelta({
- usage: event.usage,
- costUsd: extractGatewayCostUsd(event.providerMetadata),
- });
- },
- onToolExecutionEnd: logToolExecutionError,
- // Replaces the AI SDK's default `console.error`; the harness still
- // emits stream events, this just keeps the raw error from being silent.
- onError(event: { error: unknown }) {
- if (generation.interrupted) return;
- // Recognized configuration failures (gateway auth, missing API key)
- // skip the raw inspector dump — its stack points at the harness, not
- // the fix, and the terminal-failure path logs the one-line summary
- // and emits the structured step.failed. Unrecognized errors keep
- // the full dump so they stay loud.
- if (summarizeKnownError(event.error)?.tags.includes("config") === true) return;
- logError(log, "tool-loop stream error", event.error);
- },
- onStepEnd: hooks.onStepEnd,
- onStepStart: hooks.onStepStart,
- prepareStep: hooks.prepareStep,
- reasoning: session.agent.modelReference?.reasoning ?? session.agent.reasoning,
- runtimeContext: telemetryRuntimeContext,
- stopWhen: isStepCount(1),
- telemetry: attempt?.telemetry,
- toolApproval: buildToolApproval(modelTools, generation.signal),
- tools: effectiveTools,
- };
- const agent = new ToolLoopAgent(agentSettings);
+ return runStep;
+}
- const executeModelCall = async (): Promise<HarnessStepResult> => {
- if (emit) {
- const excludedActionToolNames = new Set([FINAL_OUTPUT_TOOL_NAME]);
- const streamResult = await agent.stream({
- abortSignal: generation.signal,
- messages: callMessages,
- });
- const {
- emittedActionCallIds,
- handledInlineToolResultCallIds,
- invalidInputToolCallIds,
- inlineAuthorizationResults,
- trailingInlineToolResultParts,
- } = await emitStreamContent(
- emit,
- emissionState,
- interruptStreamOnFailure(streamResult.fullStream, generation.signal),
- {
- excludedActionToolNames,
- hidesHeldText: hidesHeldText && workingTaskIds(session).length > 0,
- tools: presentationTools,
- },
- );
- throwIfTurnAborted(config.abortSignal);
- generation.check();
- const [stepResult, accumulatedResponseMessages] = await Promise.all([
- hooks.stepResult,
- streamResult.responseMessages,
- ]);
- if (stepResult.finishReason === "content-filter") {
- throw new ContentFilteredModelResponseError(
- readGatewayGenerationId(stepResult.providerMetadata),
- );
- }
- if (
- isEmptyModelResponse(stepResult) &&
- extractToolResultCallIds(accumulatedResponseMessages).size === 0 &&
- inlineAuthorizationResults.length === 0 &&
- trailingInlineToolResultParts.length === 0
- ) {
- throw new EmptyModelResponseError();
- }
- const skippedToolResults = answerSkippedToolCalls(stepResult, effectiveTools);
- // Settle skipped calls with the step's other results, before step.completed.
- await emitStepActions(
- emit,
- emissionState,
- skippedToolResults.length === 0
- ? stepResult
- : withAccumulatedResponseMessages({
- responseMessages: appendMissingToolResultMessages({
- append: skippedToolResults,
- responseMessages: stepResult.response.messages,
- }),
- stepResult,
- }),
- {
- emittedActionCallIds,
- excludedActionCallIds: invalidInputToolCallIds,
- excludedActionToolNames,
- handledInlineToolResultCallIds,
- tools: presentationTools,
- },
- );
- const existingToolResults = stepResult.toolResults as TypedToolResult<ToolSet>[];
- const toolResultsByCallId = new Map(
- existingToolResults.map((toolResult) => [toolResult.toolCallId, toolResult]),
- );
- for (const toolResult of inlineAuthorizationResults) {
- toolResultsByCallId.set(toolResult.toolCallId, toolResult);
- }
- return withAccumulatedResponseMessages({
- invalidInputToolCallIds,
- responseMessages: appendMissingToolResultMessages({
- append: [...trailingInlineToolResultParts, ...skippedToolResults],
- responseMessages: accumulatedResponseMessages,
- }),
- stepResult,
- toolResults: [...toolResultsByCallId.values()],
- });
- }
- const generateResult = await agent.generate({
- abortSignal: generation.signal,
- messages: callMessages,
- });
- throwIfTurnAborted(config.abortSignal);
- generation.check();
- const stepResult = await hooks.stepResult;
- if (stepResult.finishReason === "content-filter") {
- throw new ContentFilteredModelResponseError(
- readGatewayGenerationId(stepResult.providerMetadata),
- );
- }
- if (
- isEmptyModelResponse(stepResult) &&
- extractToolResultCallIds(generateResult.responseMessages).size === 0
- ) {
- throw new EmptyModelResponseError();
- }
- return withAccumulatedResponseMessages({
- responseMessages: appendMissingToolResultMessages({
- append: answerSkippedToolCalls(stepResult, effectiveTools),
- responseMessages: generateResult.responseMessages,
- }),
- stepResult,
- });
- };
+/** `session.clear()`: the machine withdraws what the cleared history asked, and history empties. */
+async function clearContext(step: Step): Promise<StepResult> {
+ await step.apply(clear(step.view(), { sessionId: step.session.sessionId }));
+ const cleared = discardClearedHumanInput({
+ ...step.session,
+ state: clearMemorySessionState(step.session.state),
+ });
+ return { next: null, session: replaceSessionHistory(cleared, []) };
+}
- try {
- const result = await executeModelCall();
- await attempt?.complete();
- return result;
- } catch (error) {
- if (generation.interrupted) await attempt?.complete();
- else await attempt?.fail(error);
- generation.check();
- return rethrowNoOutputAsEmptyResponse(error);
- }
- };
-
- let nextModelAttemptIndex = 0;
- const runOneModelCall = async (opts: ModelCallOptions): Promise<HarnessStepResult> =>
- runModelCallWithRetries(
- (attempt) =>
- runSingleModelCall({
- ...opts,
- attemptIndex: nextModelAttemptIndex++,
- suppressStepStartedEmission: attempt === 1 ? opts.suppressStepStartedEmission : true,
- }),
- {
- sessionId: session.sessionId,
- turnId: emissionState.turnId,
- canRetry: () => compactionFailure === undefined,
- },
- 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,
- emissionState,
- messages: projectedMessages,
- session,
- });
- if (limitResult !== null) {
- return limitResult;
- }
-
- let result: HarnessStepResult;
- try {
- result = await runOneModelCall({
- suppressStepStartedEmission: true,
- });
- } catch (error) {
- throwIfCompactionFailed();
- throwIfTurnAborted(config.abortSignal);
-
- if (generation.interrupted) {
- return finishSteeredStep();
- }
-
- // Stage order: drop a gateway-rejected provider tool first, then
- // reissue an empty response; see runModelCallRecoveryPipeline for
- // the skip/act semantics.
- const recoveryResult = await runModelCallRecoveryPipeline({
- error,
- stages: [
- (current) =>
- attemptUnsupportedProviderToolRecovery({
- error: current.error,
- runOneModelCall,
- sessionId: session.sessionId,
- turnId: emissionState.turnId,
- }),
- (current) =>
- attemptEmptyResponseRecovery({
- error: current.error,
- retryCallOptions: current.retryCallOptions,
- runOneModelCall,
- sessionId: session.sessionId,
- turnId: emissionState.turnId,
- }),
- ],
- });
- throwIfCompactionFailed();
- throwIfTurnAborted(config.abortSignal);
-
- if (generation.interrupted) return finishSteeredStep();
-
- if (recoveryResult.outcome === "recovered") {
- result = recoveryResult.result;
- } else {
- // Surface the full cause chain + upstream responseBody to OTel
- // via the turn span. The AI SDK's automatic
- // `span.recordException(err)` on its own `ai.streamText` span
- // only captures `error.stack` and does not traverse `cause`,
- // so the gateway-wrapped upstream 4xx body would otherwise be
- // invisible to OTel providers.
- const finalError = recoveryResult.error;
- stepInstrumentation?.recordError(finalError);
-
- if (!emit) {
- // Internal harness callers without an emit fn (tests, task-only
- // code paths) get the raw throw. Only runtime-connected harness
- // calls go through the structured failure path below.
- throw finalError;
- }
-
- // A durable event-stream write failure reaches this catch only
- // because `emitStreamContent` runs inside the model-call
- // try/catch — the model call itself may have succeeded. Label it
- // as the workflow-infrastructure failure it is instead of
- // misattributing it to the model provider, and surface the
- // failing endpoint + platform error code as evidence.
- const streamWriteDetails = extractWorkflowStreamWriteErrorDetails(finalError);
- if (streamWriteDetails !== null) {
- const errorId = createErrorId();
- log.error("workflow stream write failed — parking session for retry by the user", {
- ...streamWriteDetails,
- errorId,
- error: finalError,
- sessionId: session.sessionId,
- turnId: emissionState.turnId,
- });
- emissionState = await emitRecoverableFailedTurn(emit, emissionState, {
- code: "WORKFLOW_STREAM_WRITE_FAILED",
- continuationToken: session.continuationToken,
- usage: getSessionUsage(session),
- details: { ...streamWriteDetails, errorId },
- message: toErrorMessage(finalError),
- });
- const parkedSession = setHarnessEmissionState(session, emissionState);
- return { next: null, session: parkedSession };
- }
-
- const classification = classifyModelCallError(finalError);
- const errorId = createErrorId();
- const catalogSummary = summarizeKnownError(finalError);
- const upstreamRejection =
- catalogSummary === null ? extractUpstreamRejectionMessage(finalError) : null;
- const errorMessage =
- catalogSummary?.message ?? upstreamRejection?.message ?? toErrorMessage(finalError);
- // Task failures surface as the parent agent's tool-result text, so
- // the remediation rides along in prose — the parent can act on it
- // or relay it. Event payloads keep hint structured in details.
- const taskFailureOutput =
- catalogSummary?.hint === undefined
- ? errorMessage
- : `${errorMessage} ${catalogSummary.hint}`;
- const modelCallDetails = extractModelCallErrorDetails(finalError);
- const details = buildModelCallFailureDetails({
- catalogSummary,
- error: finalError,
- errorId,
- modelCallDetails,
- upstreamRejection,
- });
- const modelCallLogFields = buildModelCallFailureLogFields({
- error: finalError,
- errorId,
- modelCallDetails,
- recognized: catalogSummary !== null || upstreamRejection !== null,
- sessionId: session.sessionId,
- turnId: emissionState.turnId,
- });
-
- if (classification === "terminal") {
- if (catalogSummary !== null) {
- // Recognized configuration failure: log a concise single line
- // and skip the structured SDK dump so the user sees an
- // actionable hint instead of a wall of inspector output.
- log.error(`${catalogSummary.name}: ${catalogSummary.message}`, {
- errorId,
- hint: catalogSummary.hint,
- sessionId: session.sessionId,
- turnId: emissionState.turnId,
- });
- } else {
- log.error(
- upstreamRejection?.message ?? "model call failed terminally",
- modelCallLogFields,
- );
- }
- await emitFailedStep(emit, emissionState, {
- code: "MODEL_CALL_FAILED",
- details,
- message: errorMessage,
- sessionId: session.sessionId,
- usage: getSessionUsage(session),
- });
- // Delegated runs need a failed terminal result so their caller sees a
- // failed `subagent-result`; top-level conversation failures already
- // emit `session.failed` here.
- return {
- next: hasDelegatedCaller
- ? { done: true, isError: true, output: taskFailureOutput }
- : { done: true, output: "" },
- session,
- };
- }
-
- log.error(
- upstreamRejection?.message ?? "model call failed — parking session for retry by the user",
- modelCallLogFields,
- );
- emissionState = await emitRecoverableFailedTurn(emit, emissionState, {
- code: "MODEL_CALL_FAILED",
- continuationToken: session.continuationToken,
- usage: getSessionUsage(session),
- details,
- message: errorMessage,
- });
- const settledTurn = { isError: true, output: taskFailureOutput } satisfies SettledTurn;
- session = { ...session, outputSchema: undefined };
- return {
- next: null,
- session: setHarnessEmissionState(session, emissionState),
- settledTurn,
- };
- }
- }
-
- // --- Step-side observability tags ---------------------------------------
- //
- // Tag the **turn workflow run** (the current `"use step"` is hosted by
- // that workflow, so `setAttributes` writes to its
- // attributes table) with the model id and per-turn cumulative token
- // counts. Per-turn totals are accumulated on `session.state` because
- // each tool-loop iteration is a fresh `"use step"` and the workflow
- // runtime's last-write-wins per-key semantics mean only the running
- // total — not the per-step delta — should reach the dashboard.
- //
- // Best-effort: `setEveAttributes` swallows runtime failures so a
- // broken tag emit can never break the agent loop.
- const nextTurnUsage = accumulateTurnUsage({
- previous: getTurnUsageState(session.state),
- turnId: emissionState.turnId,
- usage: extractTokenUsageDelta({
- costUsd: extractGatewayCostUsd(result.providerMetadata),
- usage: result.usage,
- }),
- });
- session = setTurnUsageState(session, nextTurnUsage);
- interruptedUsage = undefined;
- // `formatLanguageModelGatewayId` requires `model.provider` to be a string;
- // mock models in tests omit it, so guard the lookup so a missing field
- // becomes `undefined` and is dropped by `setEveAttributes` instead of
- // throwing into the tool loop.
- let modelTag: string | undefined;
- try {
- modelTag = formatLanguageModelGatewayId(model);
- } catch {
- modelTag = undefined;
- }
- await setEveAttributes({
- "$eve.model": modelTag,
- "$eve.input_tokens": nextTurnUsage.inputTokens,
- "$eve.output_tokens": nextTurnUsage.outputTokens,
- "$eve.cache_read_tokens": nextTurnUsage.cacheReadTokens,
- "$eve.cache_write_tokens": nextTurnUsage.cacheWriteTokens,
- "$eve.cost_usd": nextTurnUsage.sawCost ? nextTurnUsage.costUsd : undefined,
- "$eve.tool_count": config.tools.size,
- });
-
- // --- Handle result ------------------------------------------------------
-
- let stepResult: StepResult;
- try {
- generation.check();
- stepResult = await handleStepResult({
- config,
- emit,
- emissionState: generation.outputStarted
- ? { ...emissionState, assistantOutputStarted: true }
- : emissionState,
- requestEnvelopeTokens,
- durableModelPromptMessageCount:
- turnClientContext === undefined || turnClientContext.messages.length === 0
- ? modelMessages.length
- : undefined,
- promptMessages: currentMessages.history,
- result,
- runStep,
- session,
- coordinationTools: modelCallCoordinationTools,
- endsTurnTools: modelCallEndsTurnTools,
- });
- } catch (error) {
- throwIfTurnAborted(config.abortSignal);
- if (generation.interrupted) return finishSteeredStep();
- throw error;
- }
- // The returned session now owns these messages; persist their baseline with it.
- ctx?.set(HistoryStateKey, currentMessages.historyState);
- return stepResult;
- }
-
- return runStep;
-}
-
-function extractTokenUsageDelta(input: {
- readonly costUsd: number | undefined;
- readonly usage: HarnessStepResult["usage"] | undefined;
-}): TokenUsageDelta | undefined {
- const usage = input.usage;
- if (usage === undefined && input.costUsd === undefined) {
- return undefined;
- }
-
- return {
- cacheReadTokens: usage?.inputTokenDetails?.cacheReadTokens,
- cacheWriteTokens: usage?.inputTokenDetails?.cacheWriteTokens,
- costUsd: input.costUsd,
- inputTokens: usage?.inputTokens,
- outputTokens: usage?.outputTokens,
- };
-}
-
-function extractGatewayCostUsd(providerMetadata: ProviderMetadata | undefined): number | undefined {
- const gateway = readGatewayMetadata(providerMetadata);
- const cost = gateway?.cost;
- if (typeof cost === "number" && Number.isFinite(cost)) {
- return cost;
- }
- if (typeof cost === "string") {
- const parsed = Number(cost);
- return Number.isFinite(parsed) ? parsed : undefined;
- }
- return undefined;
-}
-
-function readGatewayMetadata(
- providerMetadata: ProviderMetadata | undefined,
-): ProviderMetadata[string] | undefined {
- const gateway = providerMetadata?.gateway;
- return gateway && typeof gateway === "object" && !Array.isArray(gateway) ? gateway : undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Model-call failure projection
-// ---------------------------------------------------------------------------
-
-/**
- * Projects a model-call failure into the `step.failed` / `turn.failed`
- * `details` payload. Three mutually exclusive branches:
- *
- * 1. Catalog match → the rule's curated `name`/`message`/`hint` plus its
- * registered `semanticErrorId`, no SDK inspector dump.
- * 2. Upstream rejection → raw error `message` with the extracted upstream
- * identity, no inspector dump. No `semanticErrorId`: the message is
- * arbitrary provider prose, not a registered failure shape.
- * 3. Fallback → full {@link formatError} projection (cause chain via
- * `util.inspect`) so unrecognized failures still carry the upstream
- * stack to log aggregators.
- *
- * All branches merge {@link extractModelCallErrorDetails} on top so the
- * compact gateway diagnostics (`statusCode`, `upstreamMessage`,
- * `responseBodySnippet`, ...) always show up next to the message.
- */
-function buildModelCallFailureDetails(input: {
- readonly catalogSummary: SemanticErrorSummary | null;
- readonly error: unknown;
- readonly errorId: string;
- readonly modelCallDetails: JsonObject;
- readonly upstreamRejection: UpstreamRejectionSummary | null;
-}): JsonObject {
- const { catalogSummary, error, errorId, modelCallDetails, upstreamRejection } = input;
-
- if (catalogSummary !== null) {
- const details: Record<string, JsonValue> = {
- errorId,
- message: catalogSummary.message,
- name: catalogSummary.name,
- semanticErrorId: catalogSummary.id,
- ...modelCallDetails,
- };
- if (catalogSummary.hint !== undefined) details.hint = catalogSummary.hint;
- return details;
- }
-
- if (upstreamRejection !== null) {
- return {
- errorId,
- message: toErrorMessage(error),
- name: upstreamRejection.name,
- ...modelCallDetails,
- };
- }
-
- return { ...formatError(error, errorId), ...modelCallDetails };
-}
-
-/**
- * Builds the structured log fields for a model-call failure. When the
- * failure was recognized (catalog match or extracted upstream rejection),
- * attach the compact `details` payload and *omit* the raw `error` so the
- * logger's `util.inspect` of the cause chain (which would render
- * `[object Object]` for upstream `APICallError` shapes) is bypassed.
- * Otherwise fall back to the raw error so unrecognized failures keep
- * their full stack in logs.
- */
-function buildModelCallFailureLogFields(input: {
- readonly error: unknown;
- readonly errorId: string;
- readonly modelCallDetails: JsonObject;
- readonly recognized: boolean;
- readonly sessionId: string;
- readonly turnId: string;
-}): Record<string, unknown> {
- const base = {
- errorId: input.errorId,
- sessionId: input.sessionId,
- turnId: input.turnId,
- };
- if (input.recognized) {
- return { ...base, details: input.modelCallDetails };
- }
- return { ...base, error: input.error };
-}
-
-// ---------------------------------------------------------------------------
-// Unsupported provider tool recovery
-// ---------------------------------------------------------------------------
-
-/**
- * Call options a failing recovery retry used. A subsequent recovery
- * repeats the same call shape instead of silently restoring state the
- * earlier recovery removed (e.g. a provider tool the gateway rejected).
- */
-type RecoveryRetryCallOptions = {
- readonly disabledProviderTools?: ReadonlySet<string>;
- readonly extraSystemNote?: string;
-};
-
-/**
- * The slice of `runOneModelCall` a recovery stage may use for its retry.
- */
-type RecoveryModelCallFn = (
- opts: RecoveryRetryCallOptions & {
- readonly retryReason?: "empty-response";
- readonly suppressStepStartedEmission?: boolean;
- readonly trailingUserNote?: string;
- },
-) => Promise<HarnessStepResult>;
-
-/**
- * Shared arms of a recovery outcome, and what
- * {@link runModelCallRecoveryPipeline} resolves to.
- *
- * - `recovered`: the retry call succeeded and the wrapped result should
- * flow into the normal post-step handling.
- * - `failed`: the recovery acted and its retry also failed. The wrapped
- * error replaces the current error; `retryCallOptions`, when present,
- * is the call shape the failing retry used.
- */
-type ModelCallRecoveryBase =
- | { readonly outcome: "recovered"; readonly result: HarnessStepResult }
- | {
- readonly outcome: "failed";
- readonly error: unknown;
- readonly retryCallOptions?: RecoveryRetryCallOptions;
- };
-
-/**
- * Outcome of a single recovery stage
- * ({@link attemptUnsupportedProviderToolRecovery},
- * {@link attemptEmptyResponseRecovery}): the shared arms plus `skipped`,
- * returned when the error does not match the stage's trigger so the
- * pipeline passes the current error on unchanged.
- */
-type ModelCallRecoveryResult = ModelCallRecoveryBase | { readonly outcome: "skipped" };
-
-/**
- * One stage of {@link runModelCallRecoveryPipeline}: receives the current
- * error plus the call shape of the previous stage's failing retry.
- */
-type ModelCallRecoveryStage = (current: {
- readonly error: unknown;
- readonly retryCallOptions?: RecoveryRetryCallOptions;
-}) => Promise<ModelCallRecoveryResult>;
-
-/**
- * Runs the model-call recovery stages in order against the current error.
- *
- * Each stage checks its own trigger and returns `skipped` for errors it
- * does not handle, leaving the current error for the next stage. A stage
- * that acts either ends the pipeline with `recovered` or replaces the
- * current error with its retry's failure, so a later stage can match the
- * transformed error (a tool-drop retry can itself come back empty). The
- * trigger check stays inside the stage because it can be multi-phase: the
- * tool recovery also skips when no rejected type maps to a known framework
- * tool. `retryCallOptions` carries the failing retry's call shape to the
- * next stage so a reissue repeats what that retry sent.
- */
-async function runModelCallRecoveryPipeline(input: {
- readonly error: unknown;
- readonly stages: readonly ModelCallRecoveryStage[];
-}): Promise<ModelCallRecoveryBase> {
- let error = input.error;
- let retryCallOptions: RecoveryRetryCallOptions | undefined;
- for (const stage of input.stages) {
- const outcome = await stage({ error, retryCallOptions });
- if (outcome.outcome === "recovered") {
- return outcome;
- }
- if (outcome.outcome === "failed") {
- error = outcome.error;
- retryCallOptions = outcome.retryCallOptions;
- }
- }
- return { outcome: "failed", error };
-}
-
-type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
-type ToolResultPart = Extract<ToolResponsePart, { type: "tool-result" }>;
-type StepResponseMessage = HarnessStepResult["response"]["messages"][number];
-
-function withAccumulatedResponseMessages(input: {
- readonly invalidInputToolCallIds?: ReadonlySet<string>;
- readonly responseMessages: readonly StepResponseMessage[];
- readonly stepResult: HarnessStepResult;
- readonly toolResults?: readonly TypedToolResult<ToolSet>[];
-}): HarnessStepResult {
- const { stepResult } = input;
-
- /*
- * AI SDK `StepResult` fields are prototype getters, so spreading the
- * instance drops them. Materialize each field while replacing the final
- * step's messages with the SDK's accumulated response, which also contains
- * approval-resume results created before the model step.
- */
- return {
- content: stepResult.content,
- finishReason: stepResult.finishReason,
- ...(input.invalidInputToolCallIds === undefined
- ? {}
- : { invalidInputToolCallIds: input.invalidInputToolCallIds }),
- providerMetadata: stepResult.providerMetadata,
- response: {
- ...stepResult.response,
- messages: [...input.responseMessages],
- },
- text: stepResult.text,
- toolCalls: stepResult.toolCalls,
- toolResults: input.toolResults === undefined ? stepResult.toolResults : [...input.toolResults],
- usage: stepResult.usage,
- };
-}
-
-/**
- * Appends synthesized tool results for calls that have no result anywhere in
- * the step's response messages. Exported for its dedupe contract: a call
- * already answered — including provider-executed results the SDK keeps
- * inline in the assistant message — must never receive a second
- * `tool-result`, or the next Anthropic call rejects the history with
- * "each tool_use must have a single result".
- */
-export function appendMissingToolResultMessages(input: {
- readonly append: readonly ToolResultPart[];
- readonly responseMessages: readonly StepResponseMessage[];
-}): StepResponseMessage[] {
- const existingCallIds = extractToolResultCallIds(input.responseMessages);
- const append = input.append.filter((part) => !existingCallIds.has(part.toolCallId));
-
- return [
- ...input.responseMessages,
- ...(append.length > 0 ? [{ role: "tool" as const, content: [...append] }] : []),
- ] satisfies StepResponseMessage[];
-}
-
-function getInvalidToolCallInputErrors(input: {
- readonly toolCalls: readonly TypedToolCall<ToolSet>[];
-}): readonly TypedToolError<ToolSet>[] {
- const errors: TypedToolError<ToolSet>[] = [];
-
- for (const toolCall of input.toolCalls) {
- if (toolCall.toolName === FINAL_OUTPUT_TOOL_NAME) {
- continue;
- }
-
- const toolError = getInvalidToolCallInputError({ toolCall });
- if (toolError !== undefined) {
- errors.push(toolError);
- }
- }
-
- return errors;
-}
-
-/**
- * The AI SDK runs tools only when a step finishes with `stop` or `tool-calls`.
- * A step cut short, such as at the output token limit, leaves the calls it
- * would have run unanswered, and the next model call rejects that history.
- * Answer each with an error so the model can call the tool again. Calls the
- * SDK never runs (deferred tools, `final_output`) keep their usual handling.
- */
-function answerSkippedToolCalls(step: HarnessStepResult, tools: ToolSet): ToolResultPart[] {
- const { finishReason } = step;
- if (finishReason === "stop" || finishReason === "tool-calls") return [];
-
- const answeredCallIds = extractToolResultCallIds(step.response.messages);
- const pendingApprovalCallIds = new Set(
- (step.content ?? []).flatMap((part) =>
- part.type === "tool-approval-request" && part.isAutomatic !== true
- ? [part.toolCall.toolCallId]
- : [],
- ),
- );
- const value = `The tool did not run because the model response ended early (finish reason: ${finishReason}). Call the tool again if you still need its result.`;
- return ((step.toolCalls ?? []) as TypedToolCall<ToolSet>[])
- .filter(
- (toolCall) =>
- tools[toolCall.toolName]?.execute !== undefined &&
- toolCall.providerExecuted !== true &&
- !isInvalidToolCall(toolCall) &&
- getInvalidToolCallInputError({ toolCall }) === undefined &&
- !answeredCallIds.has(toolCall.toolCallId) &&
- !pendingApprovalCallIds.has(toolCall.toolCallId),
- )
- .map((toolCall) => ({
- output: { type: "error-text", value },
- toolCallId: toolCall.toolCallId,
- toolName: toolCall.toolName,
- type: "tool-result",
- }));
-}
-
-/**
- * CallIds answered anywhere in the response messages. Scans every message
- * role: provider-executed tool results arrive inline in the *assistant*
- * message (the SDK only moves them to a `tool` message during provider
- * 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 ModelMessage[]): ReadonlySet<string> {
- const callIds = new Set<string>();
-
- for (const message of messages) {
- if (!Array.isArray(message.content)) {
- continue;
- }
-
- for (const part of message.content) {
- if (typeof part === "object" && part !== null && part.type === "tool-result") {
- callIds.add(part.toolCallId);
- }
- }
- }
-
- return callIds;
-}
-
-/** True when provider history still owes a result for any assistant tool call. */
-function hasUnansweredToolCall(messages: readonly ModelMessage[]): boolean {
- const callIds = new Set<string>();
- const resultIds = new Set<string>();
-
- for (const message of messages) {
- if (!Array.isArray(message.content)) continue;
- for (const part of message.content) {
- if (typeof part !== "object" || part === null) continue;
- if (part.type === "tool-call") callIds.add(part.toolCallId);
- if (part.type === "tool-result") resultIds.add(part.toolCallId);
- }
- }
-
- for (const callId of callIds) {
- if (!resultIds.has(callId)) return true;
- }
- return false;
-}
-
-/**
- * Inspects a model-call failure for the "tool type 'X' is not supported"
- * provider-attempt rejection that AI Gateway returns when a fallback
- * provider cannot serve a provider-specific tool. On a match, retries the
- * step once with the offending tool dropped and a one-shot system note
- * telling the model which capability has been removed.
- *
- * Returns `recovered` when the retry succeeded so the caller can hand
- * the result off to the usual post-step handler. Returns `failed`
- * (with the original error, or the retry's error if the retry also
- * threw) otherwise so the caller's existing terminal/recoverable
- * cascade still runs.
- *
- * Recovery is intentionally scoped to known provider tools — entries in
- * {@link UPSTREAM_TOOL_TYPE_TO_FRAMEWORK_NAME} — so an unrelated
- * upstream rejection cannot accidentally drop a user-authored tool.
- */
-async function attemptUnsupportedProviderToolRecovery(input: {
- readonly error: unknown;
- readonly runOneModelCall: RecoveryModelCallFn;
- readonly sessionId: string;
- readonly turnId: string;
-}): Promise<ModelCallRecoveryResult> {
- const unsupportedTypes = extractUnsupportedProviderToolTypes(input.error);
- if (unsupportedTypes.length === 0) {
- return { outcome: "skipped" };
- }
-
- const toolsToDisable: string[] = [];
- for (const type of unsupportedTypes) {
- const frameworkName = resolveFrameworkToolFromUpstreamType(type);
- if (frameworkName !== null && !toolsToDisable.includes(frameworkName)) {
- toolsToDisable.push(frameworkName);
- }
- }
-
- if (toolsToDisable.length === 0) {
- return { outcome: "skipped" };
- }
-
- log.warn("disabling unsupported provider tool(s); retrying step once", {
- disabled: toolsToDisable,
- sessionId: input.sessionId,
- turnId: input.turnId,
- upstreamTypes: unsupportedTypes,
- });
-
- const retryCallOptions: RecoveryRetryCallOptions = {
- disabledProviderTools: new Set(toolsToDisable),
- extraSystemNote: buildDisabledToolNote(toolsToDisable),
- };
- try {
- const result = await input.runOneModelCall({
- ...retryCallOptions,
- suppressStepStartedEmission: true,
- });
- return { outcome: "recovered", result };
- } catch (retryError) {
- return { outcome: "failed", error: retryError, retryCallOptions };
- }
-}
-
-/**
- * Builds the one-shot system note prepended to the recovery retry's
- * instructions so the model has explicit context for why a capability
- * disappeared mid-turn.
- */
-function buildDisabledToolNote(toolNames: readonly string[]): string {
- const list = toolNames.join(", ");
- const noun = toolNames.length === 1 ? "tool is" : "tools are";
- return (
- `The following ${noun} not available with the current model and ` +
- `has been removed: ${list}. Proceed using the remaining tools or your ` +
- `training knowledge.`
- );
-}
-
-/**
- * True when a step produced no assistant text and no tool calls. A blank
- * response is ambiguous and must be retried instead of silently dropping a
- * HITL reply.
- */
-function isEmptyModelResponse(step: HarnessStepResult): boolean {
- return (
- step.toolCalls.length === 0 &&
- step.toolResults.length === 0 &&
- resolveAssistantStepText(step.response.messages, step.text) === null
- );
-}
-
-/**
- * Rethrows the AI SDK's `NoOutputGeneratedError` as
- * {@link EmptyModelResponseError}. Since `[email protected]`
- * (vercel/ai#15938) a stream that closes after metadata without output or
- * a finish chunk rejects — the SDK enqueues the error onto `fullStream`
- * (so `emitStreamContent` throws it) and never emits `finish-step`, so
- * `onStepEnd` does not fire and the step hooks' `stepResult` promise
- * would never settle. The same condition previously completed as an empty
- * step caught by {@link isEmptyModelResponse}; normalizing here funnels
- * both shapes into the one-shot empty-response reissue.
- */
-function rethrowNoOutputAsEmptyResponse(error: unknown): never {
- if (isNoOutputGeneratedError(error)) {
- throw new EmptyModelResponseError({ cause: error });
- }
- throw error;
-}
-
-/**
- * Wire-only note the empty-response reissue appends to its retry. Reads may
- * be refreshed when earlier results are stale; completed writes and other
- * side effects must not be repeated. Each recovery stage declares its own
- * follow-up text: tool recovery prepends {@link buildDisabledToolNote} as
- * a system note (its toolset change busts the prompt cache anyway), while
- * this one trails as a user note to keep the cached prefix valid.
- */
-const EMPTY_RESPONSE_NUDGE =
- "Your previous reply was empty and was not delivered. Continue the current user request. Reuse completed results when they satisfy the request. If existing results are stale or insufficient, use the appropriate read tools to get fresh results. Do not repeat writes or other side effects that already completed. Do not mention this notice.";
-
-/**
- * Recovers a model call that completed without content (see
- * {@link EmptyModelResponseError}) by reissuing the same call once, with
- * {@link EMPTY_RESPONSE_NUDGE} appended to the wire request. If the
- * reissue also fails, the caller's failure floor takes over.
- *
- * The reissue goes through `runOneModelCall` so it gets fresh step hooks;
- * the previous attempt's one-shot `stepResult` promise has already resolved
- * and would feed a same-hooks retry the stale empty result. The reissue
- * stays within the current step: the empty attempt emitted no step.completed
- * (an approval-resume step may have surfaced inline action results before
- * the throw), and `suppressStepStartedEmission` avoids a duplicate
- * step.started. When the empty response came from another recovery's retry,
- * `retryCallOptions` repeats that call's shape so the reissue does not
- * restore what the earlier recovery removed.
- */
-async function attemptEmptyResponseRecovery(input: {
- readonly error: unknown;
- readonly retryCallOptions?: RecoveryRetryCallOptions;
- readonly runOneModelCall: RecoveryModelCallFn;
- readonly sessionId: string;
- readonly turnId: string;
-}): Promise<ModelCallRecoveryResult> {
- if (!(input.error instanceof EmptyModelResponseError)) {
- return { outcome: "skipped" };
- }
-
- log.warn("empty model response; reissuing the model call once", {
- sessionId: input.sessionId,
- turnId: input.turnId,
- });
-
- try {
- const result = await input.runOneModelCall({
- ...input.retryCallOptions,
- retryReason: "empty-response",
- suppressStepStartedEmission: true,
- trailingUserNote: EMPTY_RESPONSE_NUDGE,
- });
- return { outcome: "recovered", result };
- } catch (retryError) {
- return { outcome: "failed", error: retryError, retryCallOptions: input.retryCallOptions };
- }
-}
-
-// ---------------------------------------------------------------------------
-// Post-step result handling
-// ---------------------------------------------------------------------------
-
-/**
- * Processes the step result: extracts input requests, decides whether to
- * park, continue the tool loop, or terminate.
- */
-async function handleStepResult(input: {
- readonly config: ToolLoopHarnessConfig;
- readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
- readonly durableModelPromptMessageCount?: number;
- readonly requestEnvelopeTokens?: number;
- readonly promptMessages: readonly HarnessModelMessage[];
- readonly result: HarnessStepResult;
- readonly runStep: StepFn;
- readonly coordinationTools: HarnessToolMap;
- /** Tools that can end the turn in this step, with their `endsTurn` option. */
- readonly endsTurnTools: EndsTurnTools;
- readonly session: HarnessSession;
-}): Promise<StepResult> {
- const { config, emit, promptMessages, result, runStep } = input;
- let { emissionState, session } = input;
-
- const stepOutput = resolveAssistantStepText(result.response.messages, result.text);
- const invalidInputToolErrors = getInvalidToolCallInputErrors({
- toolCalls: result.toolCalls as TypedToolCall<ToolSet>[],
- });
- // Unions every invalid-input signal: SDK-marked invalid calls (which get
- // SDK-synthesized tool errors), non-object inputs caught by
- // getInvalidToolCallInputErrors, and ids the stream consumer observed.
- const invalidInputToolCallIds = new Set([
- ...(result.invalidInputToolCallIds ?? []),
- ...result.toolCalls.filter(isInvalidToolCall).map((toolCall) => toolCall.toolCallId),
- ...invalidInputToolErrors.map((toolError) => toolError.toolCallId),
- ]);
- const rawResponseMessages = appendMissingToolResultMessages({
- append: invalidInputToolErrors.map((toolError) =>
- createToolResultMessagePartFromToolError(toolError),
- ),
- responseMessages: result.response.messages,
- });
-
- const providerExecutedOutcomeIds = new Set<string>();
- for (const part of [...(result.content ?? []), ...(result.toolResults ?? [])]) {
- if (
- (part.type === "tool-result" || part.type === "tool-error") &&
- part.providerExecuted === true
- ) {
- providerExecutedOutcomeIds.add(part.toolCallId);
- }
- }
- const normalizedProviderHistory = normalizeProviderToolHistory({
- messages: rawResponseMessages,
- providerExecutedOutcomeIds,
- });
- const responseMessages = await stageToolResultMedia(normalizedProviderHistory.messages);
-
- const baseSession = setRequestEnvelopeTokens(
- {
- ...session,
- compaction: createNextCompactionConfig(
- session.compaction,
- input.durableModelPromptMessageCount,
- result,
- ),
- },
- result.usage?.inputTokens !== undefined && input.durableModelPromptMessageCount !== undefined
- ? input.requestEnvelopeTokens
- : undefined,
- );
-
- const approvalRequests = extractToolApprovalInputRequests({
- content: result.content ?? [],
- excludedCallIds: invalidInputToolCallIds,
- });
- const inputRequests: InputRequest[] = approvalRequests;
- const pendingApprovals = renderPendingApprovalsSnippet(approvalRequests);
- // Keep outcomes from resumed work ahead of the framework pending-approval
- // message; only the unresolved assistant response belongs to the parked batch.
- const pendingResponseStart = responseMessages.findIndex((message) => message.role !== "tool");
- const committedResponseMessages =
- pendingResponseStart === -1
- ? responseMessages
- : responseMessages.slice(0, pendingResponseStart);
- const pendingResponseMessages = responseMessages.slice(committedResponseMessages.length);
- const parkedInputHistory: HarnessModelMessage[] = validateHarnessModelMessages([
- ...promptMessages,
- ...committedResponseMessages,
- ...(pendingApprovals === undefined
- ? []
- : [createFrameworkUserMessage("context.state", pendingApprovals)]),
- ]);
- const advertisedCoordinationTools = getAdvertisedTools({
- 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))) {
- return true;
- }
- log.warn("deferred tool call blocked because tool is not advertised", {
- callId: toolCall.toolCallId,
- sessionId: baseSession.sessionId,
- toolName: toolCall.toolName,
- });
- return false;
- });
- const deferred = collectDeferredCalls({
- session: baseSession,
- toolCalls: deferredToolCalls,
- tools: advertisedCoordinationTools,
- turnId: emissionState.turnId,
- });
- const tasks = deferred.workflowRequests;
-
- if (deferredToolCalls.length > 0) {
- // Stamp the live emission state onto the parked session so the
- // resume turn is classified as a continuation (turnId set), not a
- // fresh turn. Every other park path does this; without it the
- // parked session carries the default emission state (turnId ""),
- // because the post-preamble `setHarnessEmissionState` is dropped by
- // the later `session = pending.session` / `maybeCompact` rebinds.
- if (inputRequests.length === 0) {
- return {
- next: null,
- session: setHarnessEmissionState(
- setPendingCoordinationBatch({
- tasks,
- event: {
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- },
- responseMessages,
- session: { ...deferred.session, history: validateHarnessModelMessages(promptMessages) },
- }),
- advanceStep(emissionState),
- ),
- };
- }
-
- let parkedSession = setPendingCoordinationBatch({
- tasks,
- event: {
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- },
- responseMessages: pendingResponseMessages,
- session: { ...deferred.session, history: parkedInputHistory },
- });
-
- // The coordination batch already owns the shared assistant response.
- parkedSession = appendPendingInputBatch({
- event: {
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- },
- requests: inputRequests,
- responseAuthRequiredRequestIds: responsePolicyRequestIds(config, approvalRequests),
- responseMessages: [],
- session: parkedSession,
- });
-
- if (emit) {
- await emit(
- createInputRequestedEvent({
- requests: inputRequests,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
-
- return {
- next: null,
- session: setHarnessEmissionState(parkedSession, advanceStep(emissionState)),
- };
- }
-
- // --- Park on input requests -----------------------------------------------
-
- if (inputRequests.length > 0) {
- let parkedSession = appendPendingInputBatch({
- event: {
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- },
- requests: inputRequests,
- responseAuthRequiredRequestIds: responsePolicyRequestIds(config, approvalRequests),
- responseMessages: pendingResponseMessages,
- session: { ...baseSession, history: parkedInputHistory },
- });
-
- const runsDeferredInput = hasRunnableDeferredStepInput(parkedSession);
- if (emit) {
- await emit(
- createInputRequestedEvent({
- requests: inputRequests,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- if (!runsDeferredInput) {
- emissionState = await holdTurnForRequest(emit, emissionState, parkedSession);
- parkedSession = setHarnessEmissionState(parkedSession, emissionState);
- }
- }
-
- if (runsDeferredInput) return { next: runStep, session: parkedSession };
- return { held: { kind: "request" }, next: null, session: parkedSession };
- }
-
- // --- Park on authorization request ------------------------------------------
-
- const authorizationInterrupt = resolveInlineAuthorizationInterrupt({
- messages: [...promptMessages, ...responseMessages],
- toolResults: result.toolResults,
- });
- if (authorizationInterrupt) {
- const { challenges, history: authorizationHistory } = authorizationInterrupt;
-
- if (emit) {
- for (const superseded of getSupersededAuthorizationChallenges(
- baseSession.state,
- challenges,
- )) {
- await emit(
- createAuthorizationCompletedEvent({
- ...authorizationEventFields(superseded),
- outcome: "failed",
- reason: "Superseded by a newer authorization attempt.",
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
- for (const ch of challenges) {
- await emit(
- createAuthorizationRequiredEvent({
- ...authorizationEventFields(ch),
- description: ch.challenge.instructions ?? `Authorization required for ${ch.name}`,
- webhookUrl: ch.hookUrl,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- }
-
- emissionState = await holdTurnForRequest(emit, emissionState, baseSession);
- }
-
- return {
- held: { kind: "request" },
- next: null,
- session: setHarnessEmissionState(
- {
- ...baseSession,
- history: validateHarnessModelMessages(authorizationHistory),
- state: setPendingAuthorization(baseSession.state, { challenges }),
- },
- emissionState,
- ),
- };
- }
-
- // --- Continue or terminate ------------------------------------------------
-
- // History grows by append only; nothing rewrites earlier messages mid-turn,
- // so the prompt prefix stays stable and the provider's prompt cache keeps
- // hitting across steps. Compaction is the sole mechanism that ever rewrites
- // history, and it runs before the model call (see `maybeCompact`).
- const continuationMessages = responseMessages;
- const updatedHistory: HarnessModelMessage[] = validateHarnessModelMessages([
- ...promptMessages,
- ...continuationMessages,
- ]);
- let nextSession: HarnessSession = { ...baseSession, history: updatedHistory };
-
- // A `final_output` call is terminal even when the model emits it alongside
- // executing tools: continuing the loop would leave the no-execute call as a
- // dangling tool_use the next provider call rejects, and drop the result.
- const calledFinalOutput =
- nextSession.outputSchema !== undefined && extractFinalOutput(result) !== undefined;
- const workingTasks = workingTaskIds(nextSession);
- const finalOutputRejected = calledFinalOutput && workingTasks.length > 0;
- let responseTail: readonly ModelMessage[] = continuationMessages;
- if (finalOutputRejected) {
- responseTail = rejectFinalOutput(continuationMessages, result, workingTasks);
- nextSession = {
- ...nextSession,
- history: validateHarnessModelMessages([...promptMessages, ...responseTail]),
- };
- }
-
- const endsTurn = await stepEndsTurn(result, continuationMessages, input.endsTurnTools);
- const continueLoop =
- (!calledFinalOutput || finalOutputRejected) &&
- ((responseTail.at(-1)?.role === "tool" && !endsTurn) ||
- normalizedProviderHistory.outcomeEndsResponse ||
- hasRunnableDeferredStepInput(nextSession));
- const holdsTurn = !continueLoop && workingTasks.length > 0;
- if (continueLoop || holdsTurn) {
- if (emit) {
- emissionState = advanceStep(emissionState);
- nextSession = setHarnessEmissionState(nextSession, emissionState);
- }
- // The turn rule: no turn ends while its tasks work. The session waits for
- // one to settle, then calls the model again in the same turn. The turn
- // stays open, so it parks with `turn.waiting` rather than completing.
- if (holdsTurn) {
- if (emit) {
- await emit(
- createTurnWaitingEvent({
- on: "tasks",
- sequence: emissionState.sequence,
- turnId: emissionState.turnId,
- usage: getSessionUsage(nextSession),
- }),
- );
- }
- return { held: { kind: "tasks", taskIds: workingTasks }, next: null, session: nextSession };
- }
- return { next: runStep, session: nextSession };
- }
-
- return finishTurn({
- emissionState,
- emit,
- history: promptMessages,
- result,
- schema: nextSession.outputSchema,
- session: nextSession,
- // Text written before an `endsTurn` call was narration, not the reply.
- stepOutput: endsTurn ? null : stepOutput,
- });
-}
-
-/**
- * A sign-in or tool approval the turn raised holds it open, as a task or
- * `ctx.ask` does: the turn reports `turn.waiting` and resumes in the same turn
- * once the person answers, steers, or cancels.
- */
-async function holdTurnForRequest(
- emit: NonNullable<ToolLoopHarnessConfig["handleEvent"]>,
- emissionState: ReturnType<typeof getHarnessEmissionState>,
- session: HarnessSession,
-): Promise<ReturnType<typeof getHarnessEmissionState>> {
- const next = advanceStep(emissionState);
- await emit(
- createTurnWaitingEvent({
- on: "input",
- sequence: next.sequence,
- turnId: next.turnId,
- usage: getSessionUsage(session),
- }),
- );
- return next;
-}
-
-const STEERED_SIGN_IN_REASON = "Cancelled because a new message arrived.";
-
-/** Appended to the model-facing description of every tool with `endsTurn: true`. */
-const ENDS_TURN_TOOL_NOTE =
- "Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.";
-
-type EndsTurnTools = ReadonlyMap<string, NonNullable<HarnessToolDefinition["endsTurn"]>>;
-
-/**
- * Whether the step ends the turn: every tool call targets a tool that can end
- * the turn and succeeded, and each `endsTurn` function accepts its call's
- * `execute` output. A failed or invalid call lets the model recover instead.
- */
-async function stepEndsTurn(
- result: HarnessStepResult,
- responseMessages: readonly ModelMessage[],
- endsTurnTools: EndsTurnTools,
-): Promise<boolean> {
- const toolCalls = result.toolCalls ?? [];
- if (toolCalls.length === 0) return false;
- const outputs = new Map<string, ToolResultPart["output"]>();
- for (const message of responseMessages) {
- if (message.role !== "tool") continue;
- for (const part of message.content) {
- if (part.type === "tool-result") outputs.set(part.toolCallId, part.output);
- }
- }
- const succeeded = toolCalls.every((toolCall) => {
- const output = outputs.get(toolCall.toolCallId);
- return (
- endsTurnTools.has(toolCall.toolName) && output !== undefined && !isToolResultError(output)
- );
- });
- if (!succeeded) return false;
- const executeOutputs = new Map(
- (result.toolResults ?? []).map((toolResult) => [toolResult.toolCallId, toolResult.output]),
- );
- for (const toolCall of toolCalls) {
- const endsTurn = endsTurnTools.get(toolCall.toolName);
- if (typeof endsTurn !== "function") continue;
- if (!(await callEndsTurn(endsTurn, executeOutputs.get(toolCall.toolCallId), toolCall))) {
- return false;
- }
- }
- return true;
-}
-
-/** A throwing `endsTurn` function keeps the turn going rather than failing it. */
-async function callEndsTurn(
- endsTurn: (output: unknown) => boolean | Promise<boolean>,
- output: unknown,
- toolCall: { readonly toolCallId: string; readonly toolName: string },
-): Promise<boolean> {
- try {
- return (await endsTurn(output)) === true;
- } catch (error) {
- log.warn("endsTurn threw; continuing the turn", {
- callId: toolCall.toolCallId,
- error,
- toolName: toolCall.toolName,
- });
- return false;
- }
-}
-
-function isDeferredHarnessTool(tool: HarnessToolDefinition | undefined): boolean {
- return tool?.workflowId !== undefined || isTaskTool(tool);
-}
-
-/** Answers a `final_output` call made while tasks work with an error naming them. */
-function rejectFinalOutput(
- responseMessages: readonly ModelMessage[],
- result: HarnessStepResult,
- workingTasks: readonly string[],
-): ModelMessage[] {
- const call = (result.toolCalls ?? []).find(
- (toolCall) => toolCall.toolName === FINAL_OUTPUT_TOOL_NAME,
- );
- if (call === undefined) return [...responseMessages];
- const rejection: ToolResultPart = {
- output: { type: "error-text", value: renderFinalOutputWhileWorkingError(workingTasks) },
- toolCallId: call.toolCallId,
- toolName: FINAL_OUTPUT_TOOL_NAME,
- type: "tool-result",
- };
- return [...responseMessages, { content: [rejection], role: "tool" }];
-}
-
-const OUTPUT_SCHEMA_NOT_FULFILLED = {
- code: "OUTPUT_SCHEMA_NOT_FULFILLED",
- message: "The agent could not produce a result matching the requested schema.",
-} as const;
-
-/**
- * The structured value the model delivered by calling the framework
- * `final_output` tool, or `undefined` when the terminal turn ended in prose.
- */
-function extractFinalOutput(result: HarnessStepResult): JsonValue | undefined {
- return (result.toolCalls ?? []).find(
- (call) => call.toolName === FINAL_OUTPUT_TOOL_NAME && !isInvalidToolCall(call),
- )?.input as JsonValue | undefined;
-}
-
-/**
- * Persists the structured value as the assistant turn rather than the
- * un-executed `final_output` call, which would be a dangling tool_use on the
- * next turn. Clearing the run-scoped schema keeps it scoped to this turn.
- */
-function persistStructuredAssistantTurn(
- session: HarnessSession,
- history: readonly HarnessModelMessage[],
- structured: JsonValue,
-): HarnessSession {
- return {
- ...session,
- history: [...history, { content: JSON.stringify(structured), role: "assistant" }],
- outputSchema: undefined,
- };
-}
-
-/** Emits `result.completed` followed by the turn epilogue. */
-async function emitStructuredResult(
- emit: NonNullable<ToolLoopHarnessConfig["handleEvent"]>,
- emissionState: ReturnType<typeof getHarnessEmissionState>,
- structured: JsonValue,
- history: readonly HarnessModelMessage[],
- usage: TokenUsage,
-): Promise<ReturnType<typeof getHarnessEmissionState>> {
- await emit(
- createResultCompletedEvent({
- result: structured,
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- );
- return emitTurnEpilogue(emit, emissionState, history, usage);
-}
-
-/**
- * Closes a terminal turn. An unmet output schema fails the turn recoverably;
- * otherwise the structured value (or prose) ends the turn and the session
- * waits for the next message.
- */
-async function finishTurn(input: {
- readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
- readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly history: readonly HarnessModelMessage[];
- readonly result: HarnessStepResult;
- readonly schema: JsonObject | undefined;
- readonly session: HarnessSession;
- readonly stepOutput: string | null;
-}): Promise<StepResult> {
- const { emit, history, result, schema, stepOutput } = input;
- let { emissionState, session } = input;
- session = clearTurnClientContextState(session);
-
- if (schema === undefined) {
- if (emit) {
- emissionState = await emitTurnEpilogue(
- emit,
- emissionState,
- session.history,
- getSessionUsage(session),
- );
- session = setHarnessEmissionState(session, emissionState);
- }
- const settledTurn = { output: stepOutput ?? "" } satisfies SettledTurn;
- return { next: null, session, settledTurn };
- }
-
- const structured = extractFinalOutput(result);
- if (structured === undefined) {
- // The schema belongs to the settled turn. A later conversation turn that
- // omits outputSchema must not inherit a failed turn's contract.
- session = { ...session, outputSchema: undefined };
- if (emit) {
- emissionState = await emitRecoverableFailedTurn(emit, emissionState, {
- ...OUTPUT_SCHEMA_NOT_FULFILLED,
- continuationToken: session.continuationToken,
- usage: getSessionUsage(session),
- });
- session = setHarnessEmissionState(session, emissionState);
- }
- const settledTurn = {
- isError: true,
- output: OUTPUT_SCHEMA_NOT_FULFILLED.message,
- } satisfies SettledTurn;
- return { next: null, session, settledTurn };
- }
-
- session = persistStructuredAssistantTurn(session, history, structured);
- if (emit) {
- emissionState = await emitStructuredResult(
- emit,
- emissionState,
- structured,
- session.history,
- getSessionUsage(session),
- );
- session = setHarnessEmissionState(session, emissionState);
- }
- const settledTurn = { output: structured } satisfies SettledTurn;
- return { next: null, session, settledTurn };
-}
-
-/** Chat Completions models receive `content` tool outputs as JSON text. */
-function sendsToolResultFilesAsText(model: LanguageModel): boolean {
- return (
- typeof model !== "string" &&
- typeof model.provider === "string" &&
- model.provider.endsWith(".chat")
- );
-}
-
-function createNextCompactionConfig(
- current: CompactionConfig,
- durablePromptMessageCount: number | undefined,
- result: HarnessStepResult,
-): CompactionConfig {
- const next: {
- lastKnownInputTokens?: number;
- lastKnownPromptMessageCount?: number;
- recentWindowSize: number;
- threshold: number;
- thresholdPercent?: number;
- } = {
- recentWindowSize: current.recentWindowSize,
- threshold: current.threshold,
- thresholdPercent: current.thresholdPercent,
- };
-
- if (result.usage?.inputTokens !== undefined && durablePromptMessageCount !== undefined) {
- next.lastKnownInputTokens = result.usage.inputTokens;
- next.lastKnownPromptMessageCount = durablePromptMessageCount;
- }
-
- return next;
-}
-
-function replaceSessionHistory(
- session: HarnessSession,
- history: HarnessModelMessage[],
-): HarnessSession {
- contextStorage.getStore()?.delete(HistoryStateKey);
- return {
- ...session,
- history,
- compaction: {
- recentWindowSize: session.compaction.recentWindowSize,
- threshold: session.compaction.threshold,
- thresholdPercent: session.compaction.thresholdPercent,
- },
- };
-}
-
-/**
- * Runs the compaction pipeline once if the session's input-token estimate
- * is over the configured threshold. Mutates neither input; returns the new
- * messages array and (possibly updated) session.
- *
- * Kept in the tool-loop (rather than the AI SDK's `prepareStep` hook) so
- * the compacted messages flow through the same `messages` variable the
- * harness uses to rebuild `session.history` after the step.
- */
-async function maybeCompact(input: {
- readonly abortSignal?: AbortSignal;
- readonly auth: SessionAuthContext | null;
- readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
- readonly force?: boolean;
- readonly historyProjector?: HistoryViewProjector;
- readonly messages: HarnessModelMessage[];
- readonly model: LanguageModel;
- /** Model-visible prompt used only to decide whether durable history needs compaction. */
- readonly promptMessages?: readonly HarnessModelMessage[];
- readonly requestEnvelopeTokens?: number;
- readonly resolveModel: ToolLoopHarnessConfig["resolveModel"];
- readonly runtimeIdentity?: ToolLoopHarnessConfig["runtimeIdentity"];
- readonly session: HarnessSession;
- readonly telemetry?: TelemetryOptions;
-}): Promise<{
- readonly compacted: boolean;
- readonly messages: HarnessModelMessage[];
- readonly session: HarnessSession;
-}> {
- const { emit, emissionState } = input;
- let messages = input.messages;
- let session = input.session;
- const promptMessages = input.promptMessages ?? messages;
- const projectedPromptMessages = validateHarnessModelMessages(
- input.historyProjector?.({ messages: promptMessages, state: session.state }) ?? promptMessages,
- );
- const needsSummary =
- input.force === true ||
- shouldCompact(
- projectedPromptMessages,
- session.compaction,
- input.requestEnvelopeTokens,
- getRequestEnvelopeTokens(session),
- );
- const needsMemoryCanonicalization = shouldCanonicalizeMemory(messages);
-
- if (!needsSummary && !needsMemoryCanonicalization) {
- return { compacted: false, messages, session };
- }
-
- const compaction = await resolveCompactionModel({
- compactionModelReference: session.agent.compactionModelReference,
- model: input.model,
- modelReference: requireSessionModelReference(session),
- resolveModel: input.resolveModel,
- });
- const compactionModelReference =
- session.agent.compactionModelReference ?? requireSessionModelReference(session);
- const providerOptions = resolveCallProviderOptions({
- auth: input.auth,
- conversationId: resolveConversationId(session.rootSessionId ?? session.sessionId),
- model: compaction.model,
- modelReference: compactionModelReference,
- providerOptions: compaction.providerOptions,
- }) as Parameters<typeof compactMessages>[3];
-
- if (emit) {
- const ctx = contextStorage.getStore();
- if (ctx !== undefined) {
- prepareMemoryCompaction(ctx, { history: messages, state: session.state });
- }
- await emit(
- createCompactionRequestedEvent({
- modelId: formatLanguageModelGatewayId(compaction.model),
- sequence: emissionState.sequence,
- sessionId: session.sessionId,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- usageInputTokens: getInputTokenCount(
- projectedPromptMessages,
- session.compaction,
- input.requestEnvelopeTokens,
- getRequestEnvelopeTokens(session),
- ),
- }),
- projectedPromptMessages,
- );
- }
-
- const canonical = canonicalizeMemoryRecords(messages);
- const ordinary = validateHarnessModelMessages(
- input.historyProjector?.({ messages: canonical.ordinary, state: session.state }) ??
- canonical.ordinary,
- );
- const requestEnvelopeTokens = input.requestEnvelopeTokens ?? 0;
- const historyCompaction: CompactionConfig = {
- ...session.compaction,
- threshold: Math.max(1, session.compaction.threshold - requestEnvelopeTokens),
- lastKnownInputTokens:
- session.compaction.lastKnownInputTokens === undefined
- ? undefined
- : Math.max(
- 0,
- session.compaction.lastKnownInputTokens -
- Math.min(getRequestEnvelopeTokens(session) ?? 0, requestEnvelopeTokens),
- ),
- };
- const compactedOrdinary = needsSummary
- ? await compactMessages(
- [...ordinary],
- compaction.model,
- historyCompaction,
- providerOptions,
- input.telemetry,
- buildGatewayAttributionHeaders(compaction.model, input.runtimeIdentity),
- input.abortSignal,
- input.force === true,
- input.requestEnvelopeTokens === undefined
- ? undefined
- : Math.max(
- 0,
- getInputTokenCount(
- projectedPromptMessages,
- session.compaction,
- requestEnvelopeTokens,
- getRequestEnvelopeTokens(session),
- ) - requestEnvelopeTokens,
- ),
- )
- : [...ordinary];
- messages = validateHarnessModelMessages([...canonical.memory, ...compactedOrdinary]);
-
- if (emit) {
- const ctx = contextStorage.getStore();
- if (ctx !== undefined) {
- prepareMemoryCompaction(ctx, { history: messages, state: session.state });
- }
- await emit(
- createCompactionCompletedEvent({
- modelId: formatLanguageModelGatewayId(compaction.model),
- sequence: emissionState.sequence,
- sessionId: session.sessionId,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- input.historyProjector?.({ messages, state: session.state }) ?? messages,
- );
- if (ctx !== undefined) {
- const commit = drainMemoryCommit(ctx);
- if (commit !== undefined) {
- messages = validateHarnessModelMessages([...messages, ...commit.recalledMessages]);
- session = { ...session, state: commit.state };
- }
- }
- }
-
- return { compacted: true, messages, session: replaceSessionHistory(session, messages) };
-}
-
-/**
- * The approvals whose tool defines a response policy. Every park path records
- * them, so no Approve or Cancel of such an approval skips the policy.
- */
-function responsePolicyRequestIds(
- config: ToolLoopHarnessConfig,
- requests: readonly InputRequest[],
-): readonly string[] {
- const tools = buildResponseAuthorizationTools({
- authoredTools: config.tools,
- context: contextStorage.getStore(),
- });
- return requests
- .filter((request) => {
- const approval = tools.get(request.action.toolName)?.approval;
- return (
- approval !== undefined && typeof approval !== "function" && approval.response !== undefined
- );
- })
- .map((request) => request.requestId);
-}
-
-/**
- * Creates an approval-key resolver from the tool map. The resolver computes
- * compound keys at recording time instead of pre-computing and persisting
- * them on the pending batch.
- */
-function resolveApprovalKeyFromTools(
- tools: HarnessToolMap,
-): (request: InputRequest) => string | undefined {
- return (request) => {
- const toolDef = tools.get(request.action.toolName);
- if (toolDef?.approvalKey === undefined) {
- return undefined;
- }
- return toolDef.approvalKey(request.action.input);
- };
-}
-
-/**
- * Retries `fn` with exponential backoff while the thrown error is
- * classified as `"retry"`. Rethrows the last error once attempts are
- * exhausted or the error is classified as something other than
- * transient.
- */
-async function runModelCallWithRetries<T>(
- fn: (attempt: number) => Promise<T>,
- diag: {
- readonly sessionId: string;
- readonly turnId: string;
- readonly canRetry?: () => boolean;
- },
- signal: AbortSignal,
-): Promise<T> {
- for (let attempt = 1; ; attempt++) {
- signal.throwIfAborted();
- try {
- return await fn(attempt);
- } catch (error) {
- signal.throwIfAborted();
- if (
- diag.canRetry?.() === false ||
- attempt === MODEL_CALL_MAX_ATTEMPTS ||
- classifyModelCallError(error) !== "retry"
- ) {
- throw error;
- }
- const delayMs =
- MODEL_CALL_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 250);
- log.warn("model call failed transiently — retrying", {
- attempt,
- delayMs,
- sessionId: diag.sessionId,
- turnId: diag.turnId,
- error,
- });
- await delay(delayMs, undefined, { signal });
- }
- }
+/** Whether the input carries user-facing turn input. */
+function hasStepInput(input: StepInput | undefined): boolean {
+ if (input === undefined) return false;
+ return input.message !== undefined || (input.inputResponses?.length ?? 0) > 0;
}
diff --git a/packages/eve/src/harness/tools.ts b/packages/eve/src/harness/tools.ts
index b091bd870..479de028c 100644
--- a/packages/eve/src/harness/tools.ts
+++ b/packages/eve/src/harness/tools.ts
@@ -16,7 +16,7 @@ import { normalizeToolJsonOutput } from "#harness/tool-model-output.js";
import { toolCallModelOutput } from "#harness/tool-call-io.js";
import type { ToolExecuteOptions } from "#tools/definition.js";
import { isAsyncIterable } from "#shared/async-iterable.js";
-import { iterateAsApprover, runAsApprover } from "#harness/approved-call-callers.js";
+import { iterateAsApprover, runAsApprover } from "#harness/hitl/approved-call-callers.js";
type NativeApprovalStatus = Exclude<ApprovalStatus, boolean>;
@@ -250,6 +250,32 @@ function buildApprovalFn(
};
}
+/**
+ * Re-runs a tool's approval policy for a call a person approved, just before eve runs it, so the
+ * policy can still refuse it, as when the connection it was approved against changed.
+ */
+export async function recheckApprovedCall(
+ definition: HarnessToolDefinition,
+ call: {
+ readonly callId: string;
+ readonly input: unknown;
+ readonly abortSignal?: AbortSignal;
+ readonly approvedTools?: ReadonlySet<string>;
+ },
+): Promise<{ readonly denied: boolean; readonly reason?: string }> {
+ const status = await buildApprovalFn(definition, { approvedTools: call.approvedTools })(
+ call.input,
+ call.callId,
+ call.abortSignal,
+ true,
+ );
+ if (status === "denied") return { denied: true };
+ if (typeof status === "object" && status !== null && status.type === "denied") {
+ return { denied: true, reason: status.reason };
+ }
+ return { denied: false };
+}
+
/** Builds the AI SDK 7 call-level approval policy for an assembled tool set. */
export function buildToolApproval(
tools: ToolSet,
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 863d16a39..63f514c52 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -1,3 +1,4 @@
+import type { AuthorizationChallenge } from "#harness/authorization.js";
import type { LanguageModel, ModelMessage, UserContent } from "ai";
import type { SessionAuthContext, SessionCapabilities } from "#channel/types.js";
@@ -303,6 +304,11 @@ export interface ToolLoopHarnessConfig {
* Omitted in production until an instrumentation runtime opts in.
*/
readonly instrumentation?: SessionInstrumentation;
+ /**
+ * Sign-in callbacks the step's delivery carried. Each completes before anything else runs, and
+ * a connection's sign-in resumes the turn that asked for it.
+ */
+ readonly signInCompletions?: readonly AuthorizationChallenge[];
/** Restores runtime resources for the originating turn before approval work. */
readonly prepareApprovalTurn?: (event: {
readonly sequence: number;
diff --git a/packages/eve/src/harness/workflow-approval-resume.integration.test.ts b/packages/eve/src/harness/workflow-approval-resume.integration.test.ts
index 5ddb17c84..527b4d2f9 100644
--- a/packages/eve/src/harness/workflow-approval-resume.integration.test.ts
+++ b/packages/eve/src/harness/workflow-approval-resume.integration.test.ts
@@ -5,13 +5,13 @@ 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 { applyTransition, sessionView } from "#harness/session-machine/commit.js";
+import { cancel } from "#harness/session-machine/transitions.js";
+import { runtimeWait, storedProjection } from "#harness/session-machine/view.js";
+import { withPublished } from "#internal/testing/session-machine.js";
+import { openInputs } from "#protocol/session-projection.js";
+import { createProjectionRecorder } from "#internal/testing/session-projection-recorder.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";
@@ -63,14 +63,21 @@ function setup(
modelId: "approval-model",
provider: "eve-integration-mock",
});
+ const recorder = createProjectionRecorder();
+ const listen: NonNullable<ToolLoopHarnessConfig["handleEvent"]> =
+ overrides.handleEvent ??
+ (async (event) => {
+ events.push(event);
+ });
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,
+ handleEvent: async (event, messages) => {
+ recorder.record(event);
+ await listen(event, messages);
+ },
};
const session: HarnessSession = {
agent: {
@@ -87,14 +94,32 @@ function setup(
session: HarnessSession,
input?: Parameters<ReturnType<typeof createToolLoopHarness>>[1],
) =>
- contextStorage.run(createApprovalContext(), () =>
+ contextStorage.run(recorder.enter(createApprovalContext()), () =>
createToolLoopHarness(config)(session, input),
);
- return { events, config, model, step, session };
+ return { events, config, model, recorder, step, session };
}
+/** What the session asks and still awaits. */
function requests(session: HarnessSession) {
- return getPendingInputBatches(session.state).flatMap((batch) => batch.requests);
+ return openInputs(storedProjection(session.state)).map((input) => input.request);
+}
+
+/** `session.cancel()`, through the machine's transition. */
+async function cancelTurn(
+ session: HarnessSession,
+ record: (event: UnstampedMessageStreamEvent) => void,
+): Promise<HarnessSession> {
+ const published: UnstampedMessageStreamEvent[] = [];
+ const cancelled = await applyTransition(
+ session,
+ cancel(sessionView(storedProjection(session.state), session.state)),
+ async (event) => {
+ published.push(event);
+ record(event);
+ },
+ );
+ return withPublished(cancelled, published);
}
function workflowResult(callId = "call-0") {
@@ -117,7 +142,7 @@ describe("workflow approval resume (real AI SDK)", () => {
it("resumes the held 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();
+ expect(runtimeWait(initial.session.state)).toBeUndefined();
const [request] = requests(initial.session);
expect(request).toBeDefined();
const start = fixture.events.length;
@@ -125,19 +150,20 @@ describe("workflow approval resume (real AI SDK)", () => {
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"]);
+ expect(runtimeWait(approved.session.state)?.tasks.map((task) => task.callId)).toEqual([
+ "call-0",
+ ]);
// The approval held its turn, so answering it resumes that turn.
- const resumedTurn = getHarnessEmissionState(approved.session.state).turnId;
- expect(resumedTurn).toBe(getHarnessEmissionState(initial.session.state).turnId);
- expect(resumedTurn).not.toBe("");
+ const resumedTurn = fixture.recorder.position.turnId;
+ expect(resumedTurn).toBe("turn_0");
expect(
fixture.events.slice(start).filter((event) => event.type === "turn.started"),
).toHaveLength(0);
const completed = await fixture.step(approved.session, workflowResult());
expect(resultCallIds(completed.session)).toEqual(["call-0"]);
expect(fixture.model.doStreamCalls).toHaveLength(2);
+ // The step that dispatches the approved workflow starts but calls no model; the next reads
+ // its result, and the input that came with the approval replays after it.
expect(
fixture.events.slice(start).filter((event) => event.type === "step.started"),
).toMatchObject([{ data: { turnId: resumedTurn } }, { data: { turnId: resumedTurn } }]);
@@ -182,7 +208,7 @@ describe("workflow approval resume (real AI SDK)", () => {
requestId: request.requestId,
})),
});
- expect(getPendingCoordinationBatch(approved.session.state)?.tasks).toHaveLength(1);
+ expect(runtimeWait(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(
@@ -199,14 +225,14 @@ describe("workflow approval resume (real AI SDK)", () => {
requestId: request.requestId,
})),
});
- expect(getPendingCoordinationBatch(cancelled.session.state)).toBeUndefined();
+ expect(runtimeWait(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(runtimeWait(initial.session.state)).toBeUndefined();
expect(requests(initial.session)).toEqual([]);
expect(resultCallIds(initial.session)).toEqual(["call-0"]);
});
@@ -220,9 +246,9 @@ describe("workflow approval resume (real AI SDK)", () => {
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"]);
+ expect(runtimeWait(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" },
@@ -234,12 +260,12 @@ describe("workflow approval resume (real AI SDK)", () => {
requestId: request.requestId,
})),
});
- expect(
- getPendingCoordinationBatch(approved.session.state)?.tasks.map((task) => task.callId),
- ).toEqual(["call-0"]);
+ expect(runtimeWait(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();
+ expect(runtimeWait(completed.session.state)).toBeUndefined();
});
it("restores an approved dynamic sibling on a cold workflow continuation", async () => {
@@ -290,13 +316,14 @@ describe("workflow approval resume (real AI SDK)", () => {
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 origin = openInputs(storedProjection(initial.session.state))[0]!.turnId;
const approved = await fixture.step(initial.session, {
inputResponses: requests(initial.session).map((request) => ({
optionId: "approve",
requestId: request.requestId,
})),
});
+ // The approved workflow runs first; its sibling waits for its result.
expect(execute).not.toHaveBeenCalled();
clearDurableDynamicCallbacks(initial.session.sessionId);
const completed = await fixture.step(
@@ -336,9 +363,9 @@ describe("workflow approval resume (real AI SDK)", () => {
requestId: request.requestId,
})),
});
- expect(
- getPendingCoordinationBatch(approved.session.state)?.tasks.map((task) => task.callId),
- ).toEqual(["call-0"]);
+ expect(runtimeWait(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);
@@ -372,7 +399,7 @@ describe("workflow approval resume (real AI SDK)", () => {
requestId: request.requestId,
})),
});
- const cancelled = commitCancelledCoordinationBatch(approved.session);
+ const cancelled = await cancelTurn(approved.session, fixture.recorder.record);
expect(resultCallIds(cancelled).sort()).toEqual(["call-0", "call-1"]);
await fixture.step(cancelled, {
message: "Alice cancelled the release. Summarize the status.",
diff --git a/packages/eve/src/harness/workflow-dispatch.ts b/packages/eve/src/harness/workflow-dispatch.ts
deleted file mode 100644
index 9834a0565..000000000
--- a/packages/eve/src/harness/workflow-dispatch.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import type { ModelMessage } from "ai";
-import type { SessionAuthContext } from "#channel/types.js";
-import { approverOfRequest } from "#harness/approval-candidates.js";
-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,
- });
- const approvers: Record<string, SessionAuthContext> = {};
- for (const { request } of approved) {
- const approver = approverOfRequest(input.session.state, request.requestId);
- if (approver !== undefined) approvers[request.action.callId] = approver;
- }
- return setPendingCoordinationBatch({
- approvers,
- 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/instrumentation/native-events.ts b/packages/eve/src/instrumentation/native-events.ts
index b340034da..3d17a93d3 100644
--- a/packages/eve/src/instrumentation/native-events.ts
+++ b/packages/eve/src/instrumentation/native-events.ts
@@ -26,7 +26,7 @@ import {
takeInstrumentationActionScopeForCall,
takeInstrumentationInputScope,
} from "#instrumentation/state.js";
-import type { ResolvedInputBatch } from "#harness/input-requests.js";
+import type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";
import type { HandleEventFn } from "#harness/types.js";
import {
diff --git a/packages/eve/src/instrumentation/runtime-context.test.ts b/packages/eve/src/instrumentation/runtime-context.test.ts
index 90b7755cb..25ee7b83d 100644
--- a/packages/eve/src/instrumentation/runtime-context.test.ts
+++ b/packages/eve/src/instrumentation/runtime-context.test.ts
@@ -3,7 +3,7 @@ import { describe, expect, it } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
import { AuthKey, ChannelInstrumentationKey } from "#context/keys.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import {
buildTelemetryRuntimeContext,
type BuildTelemetryRuntimeContextInput,
@@ -25,7 +25,7 @@ const session: HarnessSession = {
sessionId: "test-session",
};
-const emissionState: HarnessEmissionState = {
+const emissionState: TurnPosition = {
sessionStarted: true,
sequence: 2,
stepIndex: 1,
diff --git a/packages/eve/src/instrumentation/runtime-context.ts b/packages/eve/src/instrumentation/runtime-context.ts
index 4d8b47121..9107430b1 100644
--- a/packages/eve/src/instrumentation/runtime-context.ts
+++ b/packages/eve/src/instrumentation/runtime-context.ts
@@ -13,7 +13,7 @@ import {
InitiatorAuthKey,
ParentSessionKey,
} from "#context/keys.js";
-import type { HarnessEmissionState } from "#harness/emission.js";
+import type { TurnPosition } from "#harness/session-machine/view.js";
import type { HarnessSession } from "#harness/types.js";
import type { RuntimeContextResolver } from "#tracing/otel-declaration.js";
import {
@@ -34,7 +34,7 @@ export interface BuildTelemetryRuntimeContextInput {
readonly capturesContent: boolean;
readonly context?: InstrumentationRuntimeContextSnapshot;
readonly eveVersion: string;
- readonly emissionState: HarnessEmissionState;
+ readonly emissionState: TurnPosition;
readonly environment: string;
readonly modelInput: {
readonly instructions: string | SystemModelMessage | undefined;
diff --git a/packages/eve/src/instrumentation/runtime.ts b/packages/eve/src/instrumentation/runtime.ts
index 02348942c..b97ee4628 100644
--- a/packages/eve/src/instrumentation/runtime.ts
+++ b/packages/eve/src/instrumentation/runtime.ts
@@ -29,7 +29,7 @@ import {
publishInputResolutions,
type CreateInstrumentationHandleEventInput,
} from "#instrumentation/native-events.js";
-import type { ResolvedInputBatch } from "#harness/input-requests.js";
+import type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
import type { HandleEventFn } from "#harness/types.js";
import {
instrumentChannelDelivery,
diff --git a/packages/eve/src/internal/structural-tests/runtime-boundary.test.ts b/packages/eve/src/internal/structural-tests/runtime-boundary.test.ts
index 234094263..44b904318 100644
--- a/packages/eve/src/internal/structural-tests/runtime-boundary.test.ts
+++ b/packages/eve/src/internal/structural-tests/runtime-boundary.test.ts
@@ -11,11 +11,6 @@ const WORKFLOW_PRIMITIVE_SPECIFIERS = new Set([
"#compiled/@workflow/core/index.js",
"#compiled/@workflow/core/runtime.js",
]);
-// Existing reachability debt through ContextKey serialization. This set should only shrink.
-const WORKFLOW_REACHABILITY_ALLOWLIST = new Set([
- "harness/attachment-staging.ts",
- "harness/tool-loop.ts",
-]);
const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"] as const;
@@ -28,11 +23,9 @@ interface SourceModule {
describe("runtime boundary structure", () => {
it("keeps channel and harness code transitively workflow-agnostic", async () => {
const modules = await buildSourceGraph();
- const { staleAllowlist, violations } = findWorkflowReachabilityViolations(modules);
+ const violations = findWorkflowReachabilityViolations(modules);
- if (violations.length > 0 || staleAllowlist.length > 0) {
- throw new Error(formatReachabilityFailure({ staleAllowlist, violations }));
- }
+ if (violations.length > 0) throw new Error(formatReachabilityFailure(violations));
});
});
@@ -168,31 +161,14 @@ function moduleResolutionCandidates(importRoot: string): string[] {
return candidates;
}
-function findWorkflowReachabilityViolations(modules: Map<string, SourceModule>): {
- staleAllowlist: string[];
- violations: string[][];
-} {
+function findWorkflowReachabilityViolations(modules: Map<string, SourceModule>): string[][] {
const violations: string[][] = [];
- const observedAllowlist = new Set<string>();
-
for (const file of modules.keys()) {
if (!DISALLOWED_ENTRYPOINT_PREFIXES.some((prefix) => file.startsWith(prefix))) continue;
-
const path = findPathToWorkflowPrimitive({ file, modules, seen: new Set() });
- if (path !== undefined) {
- if (WORKFLOW_REACHABILITY_ALLOWLIST.has(file)) {
- observedAllowlist.add(file);
- } else {
- violations.push(path);
- }
- }
+ if (path !== undefined) violations.push(path);
}
-
- const staleAllowlist = [...WORKFLOW_REACHABILITY_ALLOWLIST].filter(
- (file) => !observedAllowlist.has(file),
- );
-
- return { staleAllowlist, violations };
+ return violations;
}
function findPathToWorkflowPrimitive({
@@ -224,36 +200,15 @@ function findPathToWorkflowPrimitive({
return undefined;
}
-function formatReachabilityFailure({
- staleAllowlist,
- violations,
-}: {
- staleAllowlist: string[];
- violations: string[][];
-}): string {
- const sections = [
+function formatReachabilityFailure(violations: string[][]): string {
+ return [
"Channel and harness production code must stay workflow-agnostic.",
"A channel or harness file can transitively reach vendored Workflow primitives.",
"Move the workflow primitive call behind a runtime/execution-owned helper, then have the channel or harness depend on that eve-owned boundary instead.",
- ];
-
- if (violations.length > 0) {
- sections.push(
- "",
- "New transitive workflow reachability paths:",
- ...violations.map((path) => ` - ${path.join(" -> ")}`),
- );
- }
-
- if (staleAllowlist.length > 0) {
- sections.push(
- "",
- "Remove stale allowlist entries whose workflow reachability has been fixed:",
- ...staleAllowlist.map((file) => ` - ${file}`),
- );
- }
-
- return sections.join("\n");
+ "",
+ "Transitive workflow reachability paths:",
+ ...violations.map((path) => ` - ${path.join(" -> ")}`),
+ ].join("\n");
}
function toPosix(path: string): string {
diff --git a/packages/eve/src/internal/testing/events.test.ts b/packages/eve/src/internal/testing/events.test.ts
index 2090ff7cf..789e1a404 100644
--- a/packages/eve/src/internal/testing/events.test.ts
+++ b/packages/eve/src/internal/testing/events.test.ts
@@ -115,7 +115,7 @@ describe("captureTurnEvents", () => {
const encoder = new TextEncoder();
const run = createStaticRun(
encoder.encode(
- JSON.stringify({ type: "turn.started" }) +
+ JSON.stringify({ type: "turn.started", data: { sequence: 0, turnId: "turn_0" } }) +
"\n" +
JSON.stringify({ type: "session.waiting", data: { nextTokens: [] } }) +
"\n",
diff --git a/packages/eve/src/internal/testing/events.ts b/packages/eve/src/internal/testing/events.ts
index 31ae2b272..32c20907c 100644
--- a/packages/eve/src/internal/testing/events.ts
+++ b/packages/eve/src/internal/testing/events.ts
@@ -1,5 +1,6 @@
import type { UnstampedMessageStreamEvent, MessageStreamEvent } from "#protocol/message.js";
import { TurnSegment } from "#client/session-utils.js";
+import { createSessionContract } from "#internal/testing/session-contract.js";
/**
* Minimal, duck-typed handle to one workflow `Run`'s readable stream.
@@ -54,13 +55,25 @@ export function captureTurnEvents(
const state: StreamState = { buffer: "" };
const decoder = options.decoder ?? new TextDecoder();
let disposed = false;
+ // Every stream a test reads is held to the session contract readers rely on.
+ const contract = createSessionContract();
+ let index = 0;
const readUntil = async (matches: (event: MessageStreamEvent) => boolean) => {
if (disposed) {
throw new Error("CapturedTurnStream: stream already disposed.");
}
- return await readUntilMatch(reader, state, decoder, matches);
+ return await readUntilMatch(reader, state, decoder, (event) => {
+ const [violation] = contract.observe(event);
+ if (violation !== undefined) {
+ throw new Error(
+ `Session stream contract (${violation.rule}) at event ${index}: ${violation.message}`,
+ );
+ }
+ index += 1;
+ return matches(event);
+ });
};
return {
diff --git a/packages/eve/src/internal/testing/session-contract.ts b/packages/eve/src/internal/testing/session-contract.ts
new file mode 100644
index 000000000..b771f10f8
--- /dev/null
+++ b/packages/eve/src/internal/testing/session-contract.ts
@@ -0,0 +1,112 @@
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import {
+ foldSession,
+ initialSessionProjection,
+ openInputs,
+ openSignIns,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+
+// A test oracle for what every reader of a session stream relies on. It folds the stream with
+// the projection readers use and checks each event against what came before. eve doesn't ship
+// it: tests run it where they read a session's stream.
+
+export interface SessionContractViolation {
+ readonly rule: "turn-order" | "resolved-twice" | "open-after-owner" | "unsettled-call";
+ readonly message: string;
+ readonly event: UnstampedMessageStreamEvent;
+}
+
+const TURN_CONTENT: ReadonlySet<UnstampedMessageStreamEvent["type"]> = new Set([
+ "step.started",
+ "message.appended",
+ "reasoning.appended",
+ "actions.requested",
+]);
+
+/** Checks a session stream event by event; `observe` returns the event's violations. */
+export function createSessionContract() {
+ let projection: SessionProjection = initialSessionProjection();
+ const resolved = new Set<string>();
+ const cancelledTurns = new Set<string>();
+ let cleared = false;
+ // A reader that joins mid-stream can't know the turn its first events belong to.
+ let joined = false;
+
+ return {
+ get projection(): SessionProjection {
+ return projection;
+ },
+ observe(event: UnstampedMessageStreamEvent): readonly SessionContractViolation[] {
+ const violations: SessionContractViolation[] = [];
+ const violate = (rule: SessionContractViolation["rule"], message: string) =>
+ violations.push({ event, message, rule });
+ const before = projection;
+
+ if (before.ended) violate("turn-order", `${event.type} after the session ended`);
+ if (event.type === "turn.started" && before.activeTurnId !== undefined) {
+ violate(
+ "turn-order",
+ `turn ${event.data.turnId} started while ${before.activeTurnId} is open`,
+ );
+ }
+ if (event.type === "turn.started" || event.type === "session.started") joined = true;
+ if (joined && TURN_CONTENT.has(event.type) && before.activeTurnId === undefined) {
+ violate("turn-order", `${event.type} outside a turn`);
+ }
+ if (event.type === "input.resolved") {
+ for (const { requestId } of event.data.resolutions) {
+ if (resolved.has(requestId))
+ violate("resolved-twice", `request ${requestId} resolved twice`);
+ resolved.add(requestId);
+ }
+ }
+ // v26 cancellation ends unfinished calls without publishing synthetic tool results.
+ if (event.type === "turn.completed") {
+ for (const call of Object.values(before.calls)) {
+ if (call.turnId !== event.data.turnId || call.taskId !== undefined) continue;
+ if (call.status === "running") {
+ violate("unsettled-call", `${event.type} left call ${call.callId} running`);
+ }
+ }
+ }
+ if (event.type === "turn.cancelled") cancelledTurns.add(event.data.turnId);
+ if (event.type === "context.cleared") cleared = true;
+
+ projection = foldSession(projection, event);
+
+ if (event.type === "session.waiting" || event.type === "session.completed") {
+ for (const input of openInputs(projection)) {
+ const relayed = input.callId !== undefined || input.taskId !== undefined;
+ if (cancelledTurns.has(input.turnId) || (cleared && !relayed)) {
+ violate("open-after-owner", `request ${input.request.requestId} outlived its owner`);
+ }
+ }
+ for (const attempt of openSignIns(projection)) {
+ if (cancelledTurns.has(attempt.turnId) || cleared) {
+ violate("open-after-owner", `sign-in ${attempt.attemptId} outlived its owner`);
+ }
+ }
+ if (event.type === "session.completed" && openInputs(projection).length > 0) {
+ violate("open-after-owner", "requests are open when the session completed");
+ }
+ cancelledTurns.clear();
+ cleared = false;
+ }
+ return violations;
+ },
+ };
+}
+
+/** Throws on the first event that breaks the contract, naming the rule. */
+export function assertSessionContract(events: readonly UnstampedMessageStreamEvent[]): void {
+ const contract = createSessionContract();
+ for (const [index, event] of events.entries()) {
+ const [violation] = contract.observe(event);
+ if (violation !== undefined) {
+ throw new Error(
+ `Session stream contract (${violation.rule}) at event ${index}: ${violation.message}`,
+ );
+ }
+ }
+}
diff --git a/packages/eve/src/internal/testing/session-machine.ts b/packages/eve/src/internal/testing/session-machine.ts
new file mode 100644
index 000000000..0819aa21f
--- /dev/null
+++ b/packages/eve/src/internal/testing/session-machine.ts
@@ -0,0 +1,174 @@
+import type { ModelMessage } from "ai";
+
+import { contextStorage } from "#context/container.js";
+import { grantedApprovalKeys, parkOnApprovals } from "#harness/hitl/approvals.js";
+import { suspendStep } from "#harness/session-machine/transitions.js";
+import { withoutApprovalParts } from "#harness/step/after-model.js";
+import { sessionView } from "#harness/session-machine/commit.js";
+import { readTurnState, writeTurnState } from "#harness/session-machine/state.js";
+import {
+ ensureSessionProjection,
+ recordPublishedEvent,
+ saveProjection,
+} from "#harness/session-machine/current.js";
+import {
+ SESSION_PROJECTION_STATE_KEY,
+ storedProjection,
+ suspendedSteps,
+ turnPosition,
+ type StepCoordinates,
+ type SuspendedStep,
+ type TurnPosition,
+} from "#harness/session-machine/view.js";
+import type { HarnessEmitFn, HarnessSession, SessionStateMap, StepInput } from "#harness/types.js";
+import {
+ createSessionStartedEvent,
+ createStepStartedEvent,
+ createTurnStartedEvent,
+ type UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
+import { foldSession, initialSessionProjection } from "#protocol/session-projection.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import type { InputRequest } from "#shared/input.js";
+
+// Fixtures for tests that start a session part-way through its lifecycle. They reach that
+// state the way a session does, by folding what it would have published and by the machine's
+// own transitions, so a test never seeds a shape the machine can't produce.
+
+/** The session as publishing `events` leaves it. */
+export function withPublished(
+ session: HarnessSession,
+ events: readonly UnstampedMessageStreamEvent[],
+): HarnessSession {
+ return saveProjection(session, events.reduce(foldSession, storedProjection(session.state)));
+}
+
+/** The session with `position`'s turn open, at its step. */
+export function withOpenTurn(
+ session: HarnessSession,
+ position: { readonly sequence: number; readonly turnId: string; readonly stepIndex?: number },
+): HarnessSession {
+ const projection = storedProjection(session.state);
+ const events: UnstampedMessageStreamEvent[] = [];
+ if (projection.started !== true) events.push(createSessionStartedEvent());
+ if (projection.activeTurnId !== position.turnId) {
+ events.push(createTurnStartedEvent({ sequence: position.sequence, turnId: position.turnId }));
+ }
+ if (position.stepIndex !== undefined) {
+ events.push(
+ createStepStartedEvent({
+ modelId: "test-model",
+ sequence: position.sequence,
+ stepIndex: position.stepIndex,
+ turnId: position.turnId,
+ }),
+ );
+ }
+ return withPublished(session, events);
+}
+
+/**
+ * The session parked as a model step parks: its response waits on approvals, runtime calls, or
+ * both. An approval-only park ends its turn.
+ */
+export function withParkedStep(
+ session: HarnessSession,
+ step: {
+ readonly event?: StepCoordinates;
+ readonly messages?: readonly ModelMessage[];
+ readonly requests?: readonly InputRequest[];
+ readonly tasks?: readonly RuntimeWorkflowTaskRequest[];
+ readonly responseAuthRequiredRequestIds?: readonly string[];
+ readonly requester?: SuspendedStep["requester"];
+ },
+): HarnessSession {
+ const event = step.event ?? { sequence: 1, stepIndex: 0, turnId: "turn-1" };
+ const opened = withOpenTurn(session, event);
+ const view = sessionView(storedProjection(opened.state), opened.state);
+ // A response parks without the SDK's approval parts, as the step normalizes it.
+ const parkedStep = {
+ event,
+ messages: withoutApprovalParts(step.messages ?? []),
+ tasks: step.tasks ?? [],
+ };
+ const transition =
+ (step.requests ?? []).length === 0
+ ? suspendStep(view, parkedStep)
+ : parkOnApprovals(view, {
+ ...parkedStep,
+ requester: step.requester,
+ requests: step.requests ?? [],
+ responseAuthRequiredRequestIds: step.responseAuthRequiredRequestIds,
+ });
+ const parked = writeTurnState(
+ {
+ ...opened,
+ history: [...opened.history, ...(transition.commit ?? [])] as typeof opened.history,
+ },
+ transition.turn,
+ );
+ return withPublished(parked, transition.events);
+}
+
+/**
+ * Wraps a test's event handler so the harness's events fold into the step's projection, as the
+ * publish sink does in a running session.
+ */
+export function foldingHandler(handleEvent?: HarnessEmitFn): HarnessEmitFn {
+ return async (event, messages) => {
+ const ctx = contextStorage.getStore();
+ if (ctx !== undefined) {
+ ensureSessionProjection(ctx, undefined);
+ recordPublishedEvent(ctx, event);
+ }
+ await handleEvent?.(event, messages);
+ };
+}
+
+/**
+ * Session state whose projection sits at `position`: inside its open turn, or between turns when
+ * `turnId` is empty, with `sequence` the next turn's.
+ */
+export function positionState(position: {
+ readonly sequence: number;
+ readonly stepIndex?: number;
+ readonly turnId: string;
+}): SessionStateMap {
+ if (position.turnId !== "") {
+ return withOpenTurn({ state: undefined } as HarnessSession, position).state ?? {};
+ }
+ return {
+ [SESSION_PROJECTION_STATE_KEY]: {
+ ...initialSessionProjection(),
+ nextSequence: position.sequence,
+ started: true,
+ },
+ };
+}
+
+/** The session holding `input` until it can run. */
+export function withQueuedInput<T extends Pick<HarnessSession, "state">>(
+ session: T,
+ input: StepInput,
+): T {
+ return writeTurnState(session, { ...readTurnState(session.state), queued: input });
+}
+
+export function parkedSteps(session: Pick<HarnessSession, "state">): readonly SuspendedStep[] {
+ return suspendedSteps(session.state);
+}
+
+export function positionOf(session: Pick<HarnessSession, "state">): TurnPosition {
+ return turnPosition(storedProjection(session.state));
+}
+
+/** The approval keys `once()` approvals granted that no pending approval still asks about. */
+export function grantedKeys(
+ session: Pick<HarnessSession, "state">,
+ approvalKey: (request: InputRequest) => string | undefined = () => undefined,
+): ReadonlySet<string> {
+ return grantedApprovalKeys(
+ sessionView(storedProjection(session.state), session.state),
+ approvalKey,
+ );
+}
diff --git a/packages/eve/src/internal/testing/session-projection-recorder.ts b/packages/eve/src/internal/testing/session-projection-recorder.ts
new file mode 100644
index 000000000..eac119932
--- /dev/null
+++ b/packages/eve/src/internal/testing/session-projection-recorder.ts
@@ -0,0 +1,38 @@
+import { contextStorage, type ContextContainer } from "#context/container.js";
+import { enterSessionProjection, recordPublishedEvent } from "#harness/session-machine/current.js";
+import { SESSION_PROJECTION_STATE_KEY } from "#harness/session-machine/view.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
+import { turnPosition, type TurnPosition } from "#harness/session-machine/view.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import {
+ foldSession,
+ initialSessionProjection,
+ type SessionProjection,
+} from "#protocol/session-projection.js";
+
+/**
+ * Stands in for the publish sink in tests that drive the harness with their own `handleEvent`:
+ * folds each event into the session projection, which survives the fresh context each step gets.
+ */
+export function createProjectionRecorder(initial = initialSessionProjection()) {
+ let projection: SessionProjection = initial;
+ return {
+ /** Call from the harness's `handleEvent`. */
+ record(event: UnstampedMessageStreamEvent): void {
+ projection = foldSession(projection, event);
+ const ctx = contextStorage.getStore();
+ if (ctx !== undefined) recordPublishedEvent(ctx, event as MessageStreamEvent);
+ },
+ /** Seeds a step's context with the projection so far. */
+ enter(ctx: ContextContainer): ContextContainer {
+ enterSessionProjection(ctx, { [SESSION_PROJECTION_STATE_KEY]: projection });
+ return ctx;
+ },
+ get projection(): SessionProjection {
+ return projection;
+ },
+ get position(): TurnPosition {
+ return turnPosition(projection);
+ },
+ };
+}
diff --git a/packages/eve/src/internal/testing/session-state.ts b/packages/eve/src/internal/testing/session-state.ts
index 11b91b0a5..bad903344 100644
--- a/packages/eve/src/internal/testing/session-state.ts
+++ b/packages/eve/src/internal/testing/session-state.ts
@@ -2,15 +2,19 @@ import {
DURABLE_SESSION_VERSION,
type DurableSessionState,
} from "#execution/durable-session-store.js";
+import { positionState } from "#internal/testing/session-machine.js";
-/** Complete session checkpoint for tests that exercise workflow coordination. */
+/**
+ * Complete session checkpoint for tests that exercise workflow coordination. `position` seeds the
+ * projection: inside an open turn, or between turns when `turnId` is empty.
+ */
export function createTestSessionState(
overrides: Partial<DurableSessionState> = {},
+ position?: { readonly sequence: number; readonly stepIndex?: number; readonly turnId: string },
): DurableSessionState {
return {
continuationToken: overrides.continuationToken ?? "test-token",
sessionId: overrides.sessionId ?? "test-session",
- emissionState: { sequence: 0, sessionStarted: false, stepIndex: 0, turnId: "" },
hasProxyInputRequests: false,
version: DURABLE_SESSION_VERSION,
snapshot: {
@@ -18,6 +22,7 @@ export function createTestSessionState(
agent: { system: "" },
continuationToken: overrides.continuationToken ?? "test-token",
sessionId: overrides.sessionId ?? "test-session",
+ ...(position !== undefined && { state: positionState(position) }),
},
},
...overrides,
diff --git a/packages/eve/src/protocol/message.test.ts b/packages/eve/src/protocol/message.test.ts
index e8f6a0eba..2696670b9 100644
--- a/packages/eve/src/protocol/message.test.ts
+++ b/packages/eve/src/protocol/message.test.ts
@@ -516,6 +516,25 @@ describe("message stream protocol", () => {
});
});
+ it("preserves the failed wire status for an automatic policy denial", () => {
+ const event = createActionResultEvent({
+ result: {
+ callId: "call_1",
+ isError: true,
+ kind: "tool-result",
+ output: { code: "TOOL_EXECUTION_DENIED", message: "Tool execution was denied." },
+ toolName: "deploy",
+ },
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ });
+ expect(event.data).toMatchObject({
+ error: { code: "TOOL_EXECUTION_DENIED" },
+ status: "failed",
+ });
+ });
+
it("marks denied action results as rejected", () => {
const event = createActionResultEvent({
rejected: true,
diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.ts
index 71108e3bf..a3147452a 100644
--- a/packages/eve/src/protocol/message.ts
+++ b/packages/eve/src/protocol/message.ts
@@ -287,6 +287,12 @@ export interface ApprovalSettledStreamEvent {
*/
export interface InputRequestedStreamEvent {
data: {
+ /**
+ * The call a relayed request serves: the task or workflow call whose run, or whose child
+ * session, asks. The request retains its origin coordinates. Absent for the
+ * session's own requests, whose approvals name their call in `request.action`.
+ */
+ callId?: string;
requests: readonly InputRequest[];
sequence: number;
stepIndex: number;
@@ -1358,6 +1364,7 @@ export function createApprovalSettledEvent(
* Creates the `input.requested` event for one pending HITL batch.
*/
export function createInputRequestedEvent(input: {
+ readonly callId?: string;
readonly requests: readonly InputRequest[];
readonly sequence: number;
readonly stepIndex: number;
@@ -1370,6 +1377,7 @@ export function createInputRequestedEvent(input: {
stepIndex: input.stepIndex,
turnId: input.turnId,
};
+ if (input.callId !== undefined) data.callId = input.callId;
if (input.taskId !== undefined) data.taskId = input.taskId;
return { data, type: "input.requested" };
}
@@ -1892,7 +1900,11 @@ export function stampMessageStreamEvent(
event: UnstampedMessageStreamEvent,
deliveryIds?: readonly string[],
): MessageStreamEvent {
- const meta: { at: string; id: string; deliveryIds?: readonly string[] } = {
+ const meta: {
+ at: string;
+ id: string;
+ deliveryIds?: readonly string[];
+ } = {
at: new Date().toISOString(),
id: createEventId(),
};
@@ -1914,6 +1926,7 @@ function normalizeActionResultOutcome(result: RuntimeActionResult): {
readonly error?: ActionResultError;
readonly status: ActionResultStatus;
} {
+ const outputError = readActionResultOutputError(result.output);
if (result.isError === true) {
return {
error: buildActionResultError(result),
@@ -1921,7 +1934,6 @@ function normalizeActionResultOutcome(result: RuntimeActionResult): {
};
}
- const outputError = readActionResultOutputError(result.output);
if (outputError !== undefined) {
return {
error: outputError,
diff --git a/packages/eve/src/protocol/session-projection.test.ts b/packages/eve/src/protocol/session-projection.test.ts
new file mode 100644
index 000000000..efab57f55
--- /dev/null
+++ b/packages/eve/src/protocol/session-projection.test.ts
@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import {
+ callStatus,
+ foldSession,
+ initialSessionProjection,
+ pruneSessionProjection,
+ turnCoordinates,
+} from "#protocol/session-projection.js";
+
+const at = { sequence: 0, stepIndex: 0, turnId: "turn_0" };
+const fold = (events: readonly UnstampedMessageStreamEvent[]) =>
+ events.reduce(foldSession, initialSessionProjection());
+const turnStarted: UnstampedMessageStreamEvent = {
+ type: "turn.started",
+ data: { sequence: 0, turnId: "turn_0" },
+};
+const toolCall = (callId: string, toolName = "deploy"): UnstampedMessageStreamEvent => ({
+ type: "actions.requested",
+ data: { ...at, actions: [{ callId, input: {}, kind: "tool-call", toolName }] },
+});
+
+describe("foldSession", () => {
+ it("reads a failed subagent's outcome from task.settled, not its receipt", () => {
+ const projection = fold([
+ turnStarted,
+ toolCall("call_1", "researcher"),
+ {
+ type: "task.started",
+ data: {
+ callId: "call_1",
+ kind: "agent",
+ name: "researcher",
+ taskId: "t1",
+ turnId: "turn_0",
+ },
+ },
+ {
+ type: "action.result",
+ data: {
+ ...at,
+ result: {
+ callId: "call_1",
+ kind: "tool-result",
+ output: "started",
+ toolName: "researcher",
+ },
+ status: "completed",
+ },
+ } as UnstampedMessageStreamEvent,
+ { type: "turn.completed", data: { sequence: 0, turnId: "turn_0" } },
+ ]);
+ expect(callStatus(projection, "call_1")).toBe("running");
+ const settled = foldSession(projection, {
+ type: "task.settled",
+ data: {
+ callId: "call_1",
+ error: { message: "boom" },
+ status: "failed",
+ taskId: "t1",
+ turnId: "turn_0",
+ },
+ });
+ expect(callStatus(settled, "call_1")).toBe("failed");
+ });
+
+ it("reads a policy's denial as rejected", () => {
+ const projection = fold([
+ turnStarted,
+ toolCall("call_1"),
+ {
+ type: "action.result",
+ data: {
+ ...at,
+ error: { code: "TOOL_EXECUTION_DENIED", message: "denied" },
+ result: {
+ callId: "call_1",
+ isError: true,
+ kind: "tool-result",
+ output: "",
+ toolName: "deploy",
+ },
+ status: "failed",
+ },
+ } as UnstampedMessageStreamEvent,
+ ]);
+ expect(callStatus(projection, "call_1")).toBe("rejected");
+ });
+
+ it("reads a call its cancelled turn left without a result as interrupted", () => {
+ const projection = fold([
+ turnStarted,
+ toolCall("call_1"),
+ { type: "turn.cancelled", data: { sequence: 0, turnId: "turn_0" } },
+ ]);
+ expect(callStatus(projection, "call_1")).toBe("interrupted");
+ expect(pruneSessionProjection(projection)).toMatchObject({ calls: {}, turns: {} });
+ expect(turnCoordinates(projection)).toEqual({ sequence: 1, stepIndex: 0, turnId: "turn_1" });
+ });
+
+ it("retains live task work but forgets inline calls after clear", () => {
+ const projection = fold([
+ turnStarted,
+ toolCall("inline"),
+ toolCall("background", "researcher"),
+ {
+ type: "task.started",
+ data: {
+ callId: "background",
+ taskId: "task_1",
+ kind: "agent",
+ name: "researcher",
+ turnId: "turn_0",
+ },
+ },
+ { type: "context.cleared", data: { sequence: 0, sessionId: "session_1", turnId: "turn_0" } },
+ ]);
+ expect(callStatus(projection, "inline")).toBeUndefined();
+ expect(callStatus(projection, "background")).toBe("running");
+ const pruned = pruneSessionProjection(projection);
+ expect(Object.keys(pruned.calls)).toEqual(["background"]);
+ expect(pruned.tasks.task_1?.calls.background?.status).toBe("working");
+ });
+
+ it("reads a responder's declined approval as denied, not withdrawn", () => {
+ const request = {
+ action: { callId: "call_1", input: {}, kind: "tool-call" as const, toolName: "deploy" },
+ kind: "tool-approval" as const,
+ prompt: "Deploy?",
+ requestId: "req_1",
+ };
+ const projection = fold([
+ turnStarted,
+ toolCall("call_1"),
+ { type: "input.requested", data: { ...at, requests: [request] } },
+ {
+ type: "approval.settled",
+ data: { ...at, outcome: "cancelled", requestId: "req_1", responderPrincipalId: "bob" },
+ },
+ {
+ type: "input.resolved",
+ data: {
+ ...at,
+ resolutions: [{ kind: "tool-approval", outcome: "denied", requestId: "req_1" }],
+ },
+ },
+ ]);
+ expect(projection.inputs.req_1).toMatchObject({ outcome: "denied", status: "settled" });
+ expect(callStatus(projection, "call_1")).toBe("rejected");
+ });
+
+ it("names a call whose result arrives unannounced", () => {
+ const projection = fold([
+ turnStarted,
+ {
+ type: "action.result",
+ data: {
+ ...at,
+ result: { callId: "call_1", kind: "tool-result", output: "done", toolName: "deploy" },
+ status: "completed",
+ },
+ },
+ ]);
+ expect(projection.calls.call_1).toMatchObject({ name: "deploy", status: "completed" });
+ });
+
+ it("does not let a relayed approval settle a same-ID local call", () => {
+ const request = {
+ action: { callId: "call_1", input: {}, kind: "tool-call" as const, toolName: "child-deploy" },
+ kind: "tool-approval" as const,
+ prompt: "Approve Alice's deployment?",
+ requestId: "child-request",
+ };
+ const projection = fold([
+ turnStarted,
+ toolCall("call_1", "local-report"),
+ { type: "input.requested", data: { ...at, callId: "parent-agent", requests: [request] } },
+ {
+ type: "input.resolved",
+ data: {
+ ...at,
+ resolutions: [{ kind: "tool-approval", outcome: "denied", requestId: "child-request" }],
+ },
+ },
+ ]);
+ expect(projection.calls.call_1).toMatchObject({ name: "local-report", status: "running" });
+ expect(projection.inputs["child-request"]).toMatchObject({
+ status: "settled",
+ outcome: "denied",
+ });
+ });
+
+ it("tracks an approval from request to decision", () => {
+ const request = {
+ action: { callId: "call_1", input: {}, kind: "tool-call" as const, toolName: "deploy" },
+ kind: "tool-approval" as const,
+ prompt: "Deploy?",
+ requestId: "req_1",
+ };
+ const asked = fold([
+ turnStarted,
+ toolCall("call_1"),
+ { type: "input.requested", data: { ...at, requests: [request] } },
+ { type: "turn.completed", data: { sequence: 0, turnId: "turn_0" } },
+ {
+ type: "session.waiting",
+ data: { continuationToken: "s", wait: "next-user-message" },
+ },
+ ]);
+ expect(callStatus(asked, "call_1")).toBe("awaiting-input");
+ const denied = foldSession(asked, {
+ type: "input.resolved",
+ data: {
+ ...at,
+ resolutions: [{ kind: "tool-approval", outcome: "denied", requestId: "req_1" }],
+ },
+ });
+ expect(callStatus(denied, "call_1")).toBe("rejected");
+ expect(pruneSessionProjection(denied)).toMatchObject({ calls: {}, inputs: {}, turns: {} });
+ });
+});
diff --git a/packages/eve/src/protocol/session-projection.ts b/packages/eve/src/protocol/session-projection.ts
new file mode 100644
index 000000000..d9a0c3350
--- /dev/null
+++ b/packages/eve/src/protocol/session-projection.ts
@@ -0,0 +1,685 @@
+import type {
+ ActionResultError,
+ ApprovalCandidateOutcome,
+ AuthorizationOutcome,
+ InputResolutionOutcome,
+ UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
+import type { RuntimeActionRequest, RuntimeActionResult } from "#shared/action-types.js";
+import type { InputRequest, InputResponse } from "#shared/input.js";
+import type { JsonValue } from "#shared/json.js";
+
+// The one fold from a session's stream events to its lifecycle: turns, requests, calls, tasks,
+// and sign-ins. Server and client readers are meant to share it, so it reads only the public
+// protocol and must stay free of runtime dependencies, which also lets workflow bodies import it.
+
+export interface SessionTurn {
+ readonly turnId: string;
+ readonly sequence: number;
+ readonly status: "active" | "completed" | "cancelled" | "failed";
+ /** The open turn is parked, holding on its tasks or on a person: a sign-in, approval, or question. */
+ readonly waiting?: boolean;
+ /** The step the turn's latest `step.started` opened; absent before its first. */
+ readonly stepIndex?: number;
+ /** The turn streamed assistant output, so steering can no longer restart it. */
+ readonly outputStarted?: boolean;
+}
+
+export interface SessionInput {
+ readonly request: InputRequest;
+ readonly sequence: number;
+ readonly turnId: string;
+ readonly stepIndex: number;
+ /** The task whose run asks, when a task asks. */
+ readonly taskId?: string;
+ /** The call a relayed request serves. */
+ readonly callId?: string;
+ /** `responded` is client-only: an answer this client sent that the stream hasn't settled. */
+ readonly status: "open" | "responded" | "settled";
+ readonly response?: InputResponse;
+ readonly outcome?: string;
+}
+
+/** One call that started or reached a task, settled by its `task.settled`. */
+export interface ConversationTaskCall {
+ readonly callId: string;
+ readonly turnId: string;
+ readonly status: "working" | "completed" | "failed" | "cancelled";
+ /** The call's result; present only when `status` is `"completed"`. */
+ readonly output?: JsonValue;
+ /** Why the call failed; present only when `status` is `"failed"`. */
+ readonly error?: { readonly message: string };
+}
+
+export interface ConversationTask {
+ readonly taskId: string;
+ /** The tool whose call started the task. */
+ readonly name: string;
+ /**
+ * `"agent"` when a subagent's tool, local or remote, started the task; `"tool"` for an authored
+ * tool, including one that opens sessions with `ctx.agent`.
+ */
+ readonly kind: "agent" | "tool";
+ /** Calls in the order they started or reached the task. */
+ readonly calls: Readonly<Record<string, ConversationTaskCall>>;
+}
+
+/**
+ * Where a call stands, as the stream reports it. A task call runs until its `task.settled`,
+ * not until the receipt the model reads.
+ */
+export type SessionCallStatus =
+ | "running"
+ | "awaiting-input"
+ | "completed"
+ | "failed"
+ | "rejected"
+ | "cancelled";
+
+interface SessionCallFields {
+ readonly callId: string;
+ /** The tool, subagent, or skill the call invokes. */
+ readonly name: string;
+ readonly turnId: string;
+ readonly stepIndex: number;
+ /** The approval request the call awaits, or awaited. */
+ readonly requestId?: string;
+}
+
+/**
+ * One call the session made. A call that started or reached a task keeps only the link to it:
+ * the task's call record is where it stands, so the projection holds each outcome once.
+ */
+export type SessionCall = SessionCallFields &
+ (
+ | {
+ readonly status: SessionCallStatus;
+ readonly error?: ActionResultError;
+ readonly taskId?: undefined;
+ }
+ | { readonly taskId: string; readonly status?: undefined; readonly error?: undefined }
+ );
+
+/** A call the session settles from its own results, not through a task. */
+type LocalCall = Extract<SessionCall, { readonly status: SessionCallStatus }>;
+
+export interface SessionAuthorization {
+ /** The attempt's `attemptId`, or its connection name from a writer that sent none. */
+ readonly attemptId: string;
+ readonly name: string;
+ readonly sequence: number;
+ readonly turnId: string;
+ readonly stepIndex: number;
+ readonly taskId?: string;
+ readonly principalId?: string;
+ /** The approval candidate whose responder signs in. */
+ readonly candidateId?: string;
+ readonly status: "required" | AuthorizationOutcome;
+ /** The sign-in resumes its work through a callback, rather than inline. */
+ readonly awaitsCallback?: true;
+}
+
+/** One responder's decision on an approval, as `approval.candidate` reports it. */
+export interface SessionApprovalCandidate {
+ readonly candidateId: string;
+ readonly requestId: string;
+ readonly outcome: ApprovalCandidateOutcome;
+}
+
+export interface SessionProjection {
+ /** `session.started` was published. */
+ readonly started?: true;
+ /** The session ended with `session.completed` or `session.failed`. */
+ readonly ended?: true;
+ readonly activeTurnId?: string;
+ /** The sequence the next turn takes. */
+ readonly nextSequence: number;
+ readonly turns: Readonly<Record<string, SessionTurn>>;
+ /** By `requestId`. */
+ readonly inputs: Readonly<Record<string, SessionInput>>;
+ /** By `taskId`. */
+ readonly tasks: Readonly<Record<string, ConversationTask>>;
+ /** By `callId`. */
+ readonly calls: Readonly<Record<string, SessionCall>>;
+ /** By `attemptId`. */
+ readonly authorizations: Readonly<Record<string, SessionAuthorization>>;
+ /** By `candidateId`. */
+ readonly candidates: Readonly<Record<string, SessionApprovalCandidate>>;
+}
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+export function initialSessionProjection(): SessionProjection {
+ return {
+ authorizations: {},
+ calls: {},
+ candidates: {},
+ inputs: {},
+ nextSequence: 0,
+ tasks: {},
+ turns: {},
+ };
+}
+
+function updateTurn<S extends SessionProjection>(
+ state: S,
+ turnId: string,
+ update: (turn: SessionTurn) => SessionTurn,
+): S {
+ const turn = state.turns[turnId];
+ if (turn === undefined) return state;
+ const next = update(turn);
+ return next === turn ? state : { ...state, turns: { ...state.turns, [turnId]: next } };
+}
+
+function putTask<S extends SessionProjection>(state: S, task: ConversationTask): S {
+ return state.tasks[task.taskId] === task
+ ? state
+ : { ...state, tasks: { ...state.tasks, [task.taskId]: task } };
+}
+
+function putTaskCall(task: ConversationTask, call: ConversationTaskCall): ConversationTask {
+ return task.calls[call.callId] === call
+ ? task
+ : { ...task, calls: { ...task.calls, [call.callId]: call } };
+}
+
+function putCall<S extends SessionProjection>(state: S, call: SessionCall): S {
+ return state.calls[call.callId] === call
+ ? state
+ : { ...state, calls: { ...state.calls, [call.callId]: call } };
+}
+
+function updateTask<S extends SessionProjection>(
+ state: S,
+ taskId: string,
+ update: (task: ConversationTask) => ConversationTask,
+): S {
+ const task = state.tasks[taskId];
+ if (task === undefined) return state;
+ const next = update(task);
+ return putTask(state, next);
+}
+
+function updateCall<S extends SessionProjection>(
+ state: S,
+ callId: string,
+ update: (call: SessionCall) => SessionCall,
+): S {
+ const call = state.calls[callId];
+ if (call === undefined) return state;
+ const next = update(call);
+ return putCall(state, next);
+}
+
+const SETTLED_CALL_STATUSES: ReadonlySet<SessionCallStatus> = new Set([
+ "completed",
+ "failed",
+ "rejected",
+ "cancelled",
+]);
+
+export function isSettledCallStatus(status: SessionCallStatus): boolean {
+ return SETTLED_CALL_STATUSES.has(status);
+}
+
+function settleCall(call: SessionCall, status: SessionCallStatus, error?: ActionResultError) {
+ if (call.taskId !== undefined || isSettledCallStatus(call.status)) return call;
+ const { requestId: _requestId, error: _error, ...rest } = call;
+ const settled: Mutable<LocalCall> = { ...rest, status };
+ if (call.requestId !== undefined) settled.requestId = call.requestId;
+ if (error !== undefined) settled.error = error;
+ return settled;
+}
+
+function actionName(action: RuntimeActionRequest): string {
+ switch (action.kind) {
+ case "load-skill":
+ return "load_skill";
+ case "subagent-call":
+ case "remote-agent-call":
+ return action.name;
+ case "tool-call":
+ case "workflow-tool-call":
+ return action.toolName;
+ }
+}
+
+function resultName(result: RuntimeActionResult): string {
+ switch (result.kind) {
+ case "load-skill-result":
+ return "load_skill";
+ case "subagent-result":
+ return result.subagentName;
+ default:
+ return result.toolName;
+ }
+}
+
+/** The status an approval's resolution leaves its call in. */
+function callStatusAfterApproval(outcome: InputResolutionOutcome | "approved" | "cancelled") {
+ switch (outcome) {
+ case "approved":
+ return "running";
+ case "denied":
+ return "rejected";
+ case "cancelled":
+ return "cancelled";
+ default:
+ return undefined;
+ }
+}
+
+/** A policy's automatic denial, which writers before `rejected` reported as a failure. */
+const TOOL_EXECUTION_DENIED = "TOOL_EXECUTION_DENIED";
+
+/**
+ * Folds one stream event into a session's lifecycle. Events this fold doesn't track, and
+ * client-only events, return `state` unchanged, so callers may pass any event through it.
+ */
+export function foldSession<S extends SessionProjection>(
+ state: S,
+ event: UnstampedMessageStreamEvent | { readonly type: string },
+): S {
+ const typed = event as UnstampedMessageStreamEvent;
+ switch (typed.type) {
+ case "session.started":
+ return state.started ? state : { ...state, started: true };
+ case "turn.started": {
+ const { sequence, turnId } = typed.data;
+ const turn: SessionTurn = { turnId, sequence, status: "active" };
+ return {
+ ...state,
+ activeTurnId: turnId,
+ nextSequence: Math.max(state.nextSequence, sequence + 1),
+ turns: {
+ ...state.turns,
+ [turnId]: turn,
+ },
+ };
+ }
+ case "step.started":
+ return updateTurn(state, typed.data.turnId, (turn) => {
+ if (!turn.waiting && turn.stepIndex === typed.data.stepIndex) return turn;
+ const { waiting: _waiting, ...rest } = turn;
+ return { ...rest, stepIndex: typed.data.stepIndex };
+ });
+ case "turn.waiting":
+ return updateTurn(state, typed.data.turnId, (turn) =>
+ turn.status === "active" && !turn.waiting ? { ...turn, waiting: true } : turn,
+ );
+ case "message.appended":
+ case "message.completed":
+ case "result.completed": {
+ const output =
+ typed.type === "message.appended"
+ ? typed.data.messageDelta.length > 0
+ : typed.type === "message.completed"
+ ? (typed.data.message?.length ?? 0) > 0
+ : true;
+ if (!output) return state;
+ return updateTurn(state, typed.data.turnId, (turn) =>
+ turn.outputStarted ? turn : { ...turn, outputStarted: true },
+ );
+ }
+ case "turn.completed":
+ case "turn.cancelled":
+ case "turn.failed": {
+ const { turnId } = typed.data;
+ const status =
+ typed.type === "turn.completed"
+ ? "completed"
+ : typed.type === "turn.failed"
+ ? "failed"
+ : "cancelled";
+ const turn = state.turns[turnId];
+ const { waiting: _waiting, ...rest } = turn ?? { turnId, sequence: typed.data.sequence };
+ return {
+ ...state,
+ activeTurnId: state.activeTurnId === turnId ? undefined : state.activeTurnId,
+ turns: { ...state.turns, [turnId]: { ...rest, status } },
+ };
+ }
+ case "context.cleared":
+ return {
+ ...state,
+ calls: Object.fromEntries(
+ Object.entries(state.calls).filter(([, call]) => call.taskId !== undefined),
+ ),
+ };
+ // Only a turn's end reaches a session boundary, so no turn stays open across one.
+ case "session.waiting":
+ return state.activeTurnId === undefined ? state : { ...state, activeTurnId: undefined };
+ case "session.completed":
+ case "session.failed": {
+ const { activeTurnId: _activeTurnId, ...rest } = state;
+ return { ...rest, ended: true } as S;
+ }
+ case "actions.requested": {
+ let calls: Record<string, SessionCall> | undefined;
+ for (const action of typed.data.actions) {
+ if (state.calls[action.callId] !== undefined) continue;
+ calls ??= { ...state.calls };
+ calls[action.callId] = {
+ callId: action.callId,
+ name: actionName(action),
+ turnId: typed.data.turnId,
+ stepIndex: typed.data.stepIndex,
+ status: "running",
+ };
+ }
+ return calls === undefined ? state : { ...state, calls };
+ }
+ case "action.result": {
+ const { result, status, error } = typed.data;
+ const call = state.calls[result.callId];
+ // A task call's result is the receipt the model reads; its outcome is its task.settled.
+ if (call?.taskId !== undefined) return state;
+ const settled =
+ status === "rejected" || error?.code === TOOL_EXECUTION_DENIED
+ ? "rejected"
+ : status === "failed" || result.isError === true
+ ? "failed"
+ : "completed";
+ if (call === undefined) {
+ // A result whose call wasn't announced, such as an approved call resuming.
+ const unannounced: Mutable<LocalCall> = {
+ callId: result.callId,
+ name: resultName(result),
+ turnId: typed.data.turnId,
+ stepIndex: typed.data.stepIndex,
+ status: settled,
+ };
+ if (error !== undefined) unannounced.error = error;
+ return putCall(state, unannounced);
+ }
+ return updateCall(state, result.callId, (current) => settleCall(current, settled, error));
+ }
+ case "task.started": {
+ const { callId, kind, name, taskId, turnId } = typed.data;
+ const task = state.tasks[taskId] ?? { taskId, name, kind, calls: {} };
+ let next: S = state;
+ if (task.calls[callId] === undefined) {
+ next = putTask(next, putTaskCall(task, { callId, turnId, status: "working" }));
+ }
+ const call = next.calls[callId];
+ if (call?.taskId === taskId) return next;
+ const linked: Mutable<SessionCall> = {
+ callId,
+ name: call?.name ?? name,
+ stepIndex: call?.stepIndex ?? 0,
+ taskId,
+ turnId: call?.turnId ?? turnId,
+ };
+ if (call?.requestId !== undefined) linked.requestId = call.requestId;
+ return putCall(next, linked);
+ }
+ case "task.settled": {
+ const { callId, error, output, status, taskId } = typed.data;
+ return updateTask(state, taskId, (task) => {
+ const call = task.calls[callId];
+ if (call === undefined || call.status !== "working") return task;
+ const settled = { callId, turnId: call.turnId, status };
+ return putTaskCall(
+ task,
+ status === "completed" && output !== undefined
+ ? { ...settled, output }
+ : status === "failed" && error !== undefined
+ ? { ...settled, error }
+ : settled,
+ );
+ });
+ }
+ case "input.requested": {
+ const inputs = { ...state.inputs };
+ let calls: Record<string, SessionCall> | undefined;
+ for (const request of typed.data.requests) {
+ if (inputs[request.requestId] !== undefined) continue;
+ const input: Mutable<SessionInput> = {
+ request,
+ sequence: typed.data.sequence,
+ turnId: typed.data.turnId,
+ stepIndex: typed.data.stepIndex,
+ status: "open",
+ };
+ if (typed.data.taskId !== undefined) input.taskId = typed.data.taskId;
+ if (typed.data.callId !== undefined) input.callId = typed.data.callId;
+ inputs[request.requestId] = input;
+ // A relayed request's action is the child's call, not one this session made.
+ if (request.kind !== "tool-approval" || isRelayed(typed.data)) continue;
+ const { callId, toolName } = request.action;
+ calls ??= { ...state.calls };
+ const call = calls[callId];
+ if (call?.taskId !== undefined) continue;
+ if (call !== undefined && isSettledCallStatus(call.status)) continue;
+ calls[callId] = {
+ ...(call ?? {
+ callId,
+ name: toolName,
+ turnId: typed.data.turnId,
+ stepIndex: typed.data.stepIndex,
+ }),
+ requestId: request.requestId,
+ status: "awaiting-input",
+ };
+ }
+ return calls === undefined ? { ...state, inputs } : { ...state, calls, inputs };
+ }
+ case "approval.candidate": {
+ const { candidateId, outcome, requestId } = typed.data;
+ state = {
+ ...state,
+ candidates: { ...state.candidates, [candidateId]: { candidateId, outcome, requestId } },
+ };
+ const current = state.inputs[typed.data.requestId];
+ if (current === undefined || current.status === "settled") return state;
+ if (typed.data.outcome === "pending" || current.status === "open") return state;
+ const { response: _response, ...rest } = current;
+ return {
+ ...state,
+ inputs: { ...state.inputs, [typed.data.requestId]: { ...rest, status: "open" } },
+ };
+ }
+ case "approval.settled": {
+ const current = state.inputs[typed.data.requestId];
+ if (current === undefined || current.status === "settled") return state;
+ // A responder's `cancelled` declines the call: the approval is denied, not withdrawn.
+ const outcome = typed.data.outcome === "approved" ? "approved" : "denied";
+ const next = {
+ ...state,
+ inputs: {
+ ...state.inputs,
+ [typed.data.requestId]: { ...current, status: "settled", outcome },
+ },
+ } as S;
+ return settleApprovalCall(next, current, outcome);
+ }
+ case "input.resolved": {
+ let next: S = state;
+ for (const resolution of typed.data.resolutions) {
+ const current = next.inputs[resolution.requestId];
+ if (current === undefined || current.status === "settled") continue;
+ const response = resolution.response ?? current.response;
+ const settled: Mutable<SessionInput> = {
+ ...current,
+ status: "settled",
+ outcome: resolution.outcome,
+ };
+ if (response !== undefined) settled.response = response;
+ next = { ...next, inputs: { ...next.inputs, [resolution.requestId]: settled } };
+ next = settleApprovalCall(next, current, resolution.outcome);
+ }
+ return next;
+ }
+ case "authorization.required": {
+ const attemptId = typed.data.attemptId ?? typed.data.name;
+ const authorization: Mutable<SessionAuthorization> = {
+ attemptId,
+ name: typed.data.name,
+ sequence: typed.data.sequence,
+ turnId: typed.data.turnId,
+ stepIndex: typed.data.stepIndex,
+ status: "required",
+ };
+ if (typed.data.taskId !== undefined) authorization.taskId = typed.data.taskId;
+ if (typed.data.principalId !== undefined) authorization.principalId = typed.data.principalId;
+ if (typed.data.candidateId !== undefined) authorization.candidateId = typed.data.candidateId;
+ if (typed.data.webhookUrl !== undefined) authorization.awaitsCallback = true;
+ return { ...state, authorizations: { ...state.authorizations, [attemptId]: authorization } };
+ }
+ case "authorization.completed": {
+ const attemptId = typed.data.attemptId ?? typed.data.name;
+ const current = state.authorizations[attemptId];
+ const completed: SessionAuthorization = {
+ ...(current ?? {
+ attemptId,
+ name: typed.data.name,
+ sequence: typed.data.sequence,
+ turnId: typed.data.turnId,
+ stepIndex: typed.data.stepIndex,
+ }),
+ status: typed.data.outcome,
+ };
+ return { ...state, authorizations: { ...state.authorizations, [attemptId]: completed } };
+ }
+ default:
+ return state;
+ }
+}
+
+function isRelayed(request: { readonly callId?: string; readonly taskId?: string }): boolean {
+ return request.callId !== undefined || request.taskId !== undefined;
+}
+
+function settleApprovalCall<S extends SessionProjection>(
+ state: S,
+ input: SessionInput,
+ outcome: InputResolutionOutcome | "approved" | "cancelled",
+): S {
+ if (input.request.kind !== "tool-approval" || isRelayed(input)) return state;
+ const status = callStatusAfterApproval(outcome);
+ if (status === undefined) return state;
+ return updateCall(state, input.request.action.callId, (call) => {
+ if (call.status !== "awaiting-input" || call.requestId !== input.request.requestId) return call;
+ return status === "running" ? { ...call, status } : settleCall(call, status);
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Selectors
+// ---------------------------------------------------------------------------
+
+/** The coordinates the active turn's events carry, or the next turn's when none is open. */
+export function turnCoordinates(state: SessionProjection): {
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+} {
+ const turn = state.activeTurnId === undefined ? undefined : state.turns[state.activeTurnId];
+ if (turn !== undefined) {
+ return { sequence: turn.sequence, stepIndex: turn.stepIndex ?? 0, turnId: turn.turnId };
+ }
+ return { sequence: state.nextSequence, stepIndex: 0, turnId: `turn_${state.nextSequence}` };
+}
+
+/** Inputs awaiting an answer, including requests introduced in earlier turns. */
+export function openInputs(state: SessionProjection): readonly SessionInput[] {
+ return Object.values(state.inputs).filter((input) => input.status !== "settled");
+}
+
+/** Sign-ins the session still waits on. */
+export function openSignIns(state: SessionProjection): readonly SessionAuthorization[] {
+ return Object.values(state.authorizations).filter((attempt) => attempt.status === "required");
+}
+
+/** Task calls whose run hasn't settled them. */
+export function workingTaskCalls(state: SessionProjection): readonly ConversationTaskCall[] {
+ return Object.values(state.tasks).flatMap((task) =>
+ Object.values(task.calls).filter((call) => call.status === "working"),
+ );
+}
+
+/**
+ * A call's status for a reader. A call still running when its turn ended, or when the reader's
+ * stream stopped (`streaming: false`), reads as `interrupted`; a task call runs past its turn.
+ */
+export function callStatus(
+ state: SessionProjection,
+ callId: string,
+ options: { readonly streaming?: boolean } = {},
+): SessionCallStatus | "interrupted" | undefined {
+ const call = state.calls[callId];
+ if (call === undefined) return undefined;
+ const status = reportedCallStatus(state, call);
+ // A task outlives its turn, so only a call the session runs itself is interrupted.
+ if (status !== "running" || call.taskId !== undefined) return status;
+ const turn = state.turns[call.turnId];
+ if (options.streaming === false || (turn !== undefined && turn.status !== "active")) {
+ return "interrupted";
+ }
+ return status;
+}
+
+/** A call's status as the stream reported it: a task call's is its task call's. */
+export function reportedCallStatus(state: SessionProjection, call: SessionCall): SessionCallStatus {
+ if (call.taskId === undefined) return call.status;
+ const status = state.tasks[call.taskId]?.calls[call.callId]?.status;
+ return status === undefined || status === "working" ? "running" : status;
+}
+
+/**
+ * Drops what closed, so a long-lived session's stored projection stays proportional to its
+ * open work. `keep` names closed requests and calls that execution state still references.
+ */
+export function pruneSessionProjection(
+ state: SessionProjection,
+ keep: { readonly requestIds?: Iterable<string>; readonly callIds?: Iterable<string> } = {},
+): SessionProjection {
+ const keptRequests = new Set(keep.requestIds);
+ const keptCalls = new Set(keep.callIds);
+ const calls = Object.fromEntries(
+ Object.entries(state.calls).filter(
+ ([callId, call]) =>
+ (!isSettledCallStatus(reportedCallStatus(state, call)) &&
+ callStatus(state, callId) !== "interrupted") ||
+ keptCalls.has(callId) ||
+ (call.requestId !== undefined && keptRequests.has(call.requestId)),
+ ),
+ );
+ // A kept call keeps the decision on its approval.
+ for (const call of Object.values(calls)) {
+ if (call.requestId !== undefined) keptRequests.add(call.requestId);
+ }
+ const inputs = Object.fromEntries(
+ Object.entries(state.inputs).filter(
+ ([requestId, input]) => input.status !== "settled" || keptRequests.has(requestId),
+ ),
+ );
+ // A kept call keeps the task call record that says where it stands.
+ const linkedCalls = new Set(
+ Object.values(calls).flatMap((call) => (call.taskId === undefined ? [] : [call.callId])),
+ );
+ const tasks: Record<string, ConversationTask> = {};
+ for (const [taskId, task] of Object.entries(state.tasks)) {
+ const retained = Object.entries(task.calls).filter(
+ ([callId, call]) => call.status === "working" || linkedCalls.has(callId),
+ );
+ if (retained.length > 0) tasks[taskId] = { ...task, calls: Object.fromEntries(retained) };
+ }
+ const authorizations = Object.fromEntries(
+ Object.entries(state.authorizations).filter(([, attempt]) => attempt.status === "required"),
+ );
+ const referencedTurns = new Set<string>([
+ ...(state.activeTurnId === undefined ? [] : [state.activeTurnId]),
+ ...Object.values(inputs).map((input) => input.turnId),
+ ...Object.values(calls).map((call) => call.turnId),
+ ...Object.values(authorizations).map((attempt) => attempt.turnId),
+ ]);
+ const turns = Object.fromEntries(
+ Object.entries(state.turns).filter(([turnId]) => referencedTurns.has(turnId)),
+ );
+ const candidates = Object.fromEntries(
+ Object.entries(state.candidates).filter(([, candidate]) => candidate.requestId in inputs),
+ );
+ return { ...state, authorizations, calls, candidates, inputs, tasks, turns };
+}
diff --git a/packages/eve/src/react/index.ts b/packages/eve/src/react/index.ts
index f0b62804e..131311577 100644
--- a/packages/eve/src/react/index.ts
+++ b/packages/eve/src/react/index.ts
@@ -16,6 +16,8 @@ export {
} from "#client/reducer.js";
export { conversationReducer } from "#client/conversation-reducer.js";
export { openConversationInputs } from "#client/conversation-state.js";
+export { toolCallState, type ToolCallState, type ToolCallStatus } from "#client/tool-call-state.js";
+
export type {
AgentObservation,
ConversationAgentSession,
diff --git a/packages/eve/src/subagents/adapter.ts b/packages/eve/src/subagents/adapter.ts
index 97a36f48e..404ef04ba 100644
--- a/packages/eve/src/subagents/adapter.ts
+++ b/packages/eve/src/subagents/adapter.ts
@@ -1,5 +1,3 @@
-import { resumeHook } from "#internal/workflow/runtime.js";
-
import type { ChannelAdapter, ChannelAdapterContext } from "#channel/adapter.js";
import type {
SubagentAuthorizationEvent,
@@ -93,7 +91,7 @@ async function forwardSubagentAuthorizationEventStep(input: {
"use step";
try {
- await resumeHook(input.parentContinuationToken, input.hookPayload);
+ await resumeParentHook(input.parentContinuationToken, input.hookPayload);
} catch (error) {
const errorId = createErrorId();
log.warn("failed to forward subagent authorization event to parent", {
@@ -120,7 +118,7 @@ async function forwardSubagentInputRequestStep(input: {
"use step";
try {
- await resumeHook(input.parentContinuationToken, input.hookPayload);
+ await resumeParentHook(input.parentContinuationToken, input.hookPayload);
} catch (error) {
const errorId = createErrorId();
log.warn("failed to forward proxied HITL batch to parent", {
@@ -135,3 +133,12 @@ async function forwardSubagentInputRequestStep(input: {
throw error;
}
}
+
+/**
+ * Resumes the parent's hook. The workflow runtime loads only when a child forwards, so the
+ * channel adapters every session context restores stay free of it.
+ */
+async function resumeParentHook(token: string, payload: unknown): Promise<void> {
+ const { resumeHook } = await import("#internal/workflow/runtime.js");
+ await resumeHook(token, payload);
+}
diff --git a/packages/eve/src/subagents/auth-proxy.integration.test.ts b/packages/eve/src/subagents/auth-proxy.integration.test.ts
index 1ae8ac4fa..10e57e1ff 100644
--- a/packages/eve/src/subagents/auth-proxy.integration.test.ts
+++ b/packages/eve/src/subagents/auth-proxy.integration.test.ts
@@ -9,7 +9,7 @@ import { ContextContainer } from "#context/container.js";
import { AuthKey, ContinuationTokenKey, SessionIdKey } from "#context/keys.js";
import { emitProxiedSubagentEvent } from "#subagents/event-proxy-step.js";
import { projectToDurableSession } from "#execution/session.js";
-import { setHarnessEmissionState } from "#harness/emission-state.js";
+import { positionOf, withOpenTurn } from "#internal/testing/session-machine.js";
import type { HarnessSession } from "#harness/types.js";
import type { MessageStreamEvent } from "#protocol/message.js";
import type { StreamEventHook } from "#public/definitions/hook.js";
@@ -213,7 +213,7 @@ describe("subagent authorization proxy", () => {
it("parks the parent's open turn on a sign-in without ending it", async () => {
const parentSessionId = "parent-session";
const openTurn = { sessionStarted: true, sequence: 3, stepIndex: 1, turnId: "parent-turn" };
- const session = setHarnessEmissionState(createSession(parentSessionId), openTurn);
+ const session = withOpenTurn(createSession(parentSessionId), openTurn);
const { bundle, ctx, hook } = buildContext({
adapter: authorizationAdapter,
sessionId: parentSessionId,
@@ -280,7 +280,7 @@ describe("subagent authorization proxy", () => {
{ data: { sequence: 3, turnId: "parent-turn" }, type: "turn.waiting" },
completedEvent,
]);
- expect(completed.sessionState.emissionState).toMatchObject(openTurn);
+ expect(positionOf(completed.sessionState.snapshot.session)).toMatchObject(openTurn);
expect(hook.mock.calls.map(([event]) => event)).toEqual(chunks.map(decodeEvent));
expect(hook.mock.calls.every(([, ctx]) => ctx.session.id === parentSessionId)).toBe(true);
});
diff --git a/packages/eve/src/subagents/event-proxy-step.integration.test.ts b/packages/eve/src/subagents/event-proxy-step.integration.test.ts
index 0b5a77067..2d1e7ef98 100644
--- a/packages/eve/src/subagents/event-proxy-step.integration.test.ts
+++ b/packages/eve/src/subagents/event-proxy-step.integration.test.ts
@@ -13,7 +13,9 @@ import {
} from "#context/keys.js";
import type { DurableSession } from "#execution/durable-session-store.js";
import { openSessionEventPublisher } from "#execution/publish-session-events.js";
-import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
+import { enterSessionProjection } from "#harness/session-machine/current.js";
+import { positionOf, withOpenTurn } from "#internal/testing/session-machine.js";
+import { createSessionLimitContinuationRequest } from "#harness/hitl/budget-request.js";
import { getProxyInputRequests } from "#harness/proxy-input-requests.js";
import { createAuthorizationRequiredEvent, type MessageStreamEvent } from "#protocol/message.js";
import type { HookContext } from "#public/definitions/hook.js";
@@ -76,15 +78,18 @@ function fixture() {
agent: { system: "" },
continuationToken: "http:parent",
sessionId: "parent-session",
- state: {
- "eve.harness.emission": {
- turnId: "parent-turn",
- sequence: 1,
- stepIndex: 0,
- sessionStarted: true,
+ state: withOpenTurn(
+ {
+ agent: { dynamicModel: true, system: "", tools: [] },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "http:parent",
+ history: [],
+ sessionId: "parent-session",
},
- },
+ { sequence: 1, stepIndex: 0, turnId: "parent-turn" },
+ ).state,
};
+ enterSessionProjection(ctx, durableSession.state);
const request = createSessionLimitContinuationRequest({
sessionId: "child-session",
turnSequence: 0,
@@ -148,7 +153,10 @@ describe("proxied stream hooks", () => {
});
expect(result.sessionState.continuationToken).toBe("http:parent-thread");
expect(result.sessionState.hasProxyInputRequests).toBe(true);
- expect(result.sessionState.emissionState).toMatchObject({ sequence: 1, turnId: "parent-turn" });
+ expect(positionOf(result.sessionState.snapshot.session)).toMatchObject({
+ sequence: 1,
+ turnId: "parent-turn",
+ });
const routed = routeDeliverPayload({
payload: { inputResponses: [{ requestId: f.request.requestId, optionId: "continue" }] },
state: result.sessionState.snapshot.session.state,
diff --git a/packages/eve/src/subagents/event-proxy-step.ts b/packages/eve/src/subagents/event-proxy-step.ts
index 72e6e9315..24ed85fec 100644
--- a/packages/eve/src/subagents/event-proxy-step.ts
+++ b/packages/eve/src/subagents/event-proxy-step.ts
@@ -13,8 +13,14 @@ import {
withSessionStateDelta,
type SessionStateTransition,
} from "#execution/session/state-delta.js";
-import { emitProxiedAuthorizationEvent, emitProxiedInputRequest } from "#subagents/hitl-proxy.js";
-import { upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
+import {
+ getProxyInputRequests,
+ toProxyInputRequestEntries,
+ upsertProxyInputRequests,
+} from "#harness/proxy-input-requests.js";
+import { currentProjection } from "#harness/session-machine/current.js";
+import { applyTransition, sessionView } from "#harness/session-machine/commit.js";
+import { relay } from "#harness/session-machine/transitions.js";
import type { WorkflowAskRoute } from "#harness/proxy-input-requests.js";
type SubagentEventHookPayload =
@@ -53,7 +59,7 @@ export async function emitProxiedSubagentEvent(
readonly hookPayload: SubagentEventHookPayload;
},
): Promise<PublishedSessionEvents> {
- const { hookPayload, runId, workflowAsk } = input;
+ const { ctx, hookPayload, runId, workflowAsk } = input;
const { published } = await publishFromSessionStep(input, {
origin: "relayed",
inputSource:
@@ -61,19 +67,40 @@ export async function emitProxiedSubagentEvent(
? JSON.stringify([hookPayload.childContinuationToken, hookPayload.inputSource ?? null])
: undefined,
async publish(emit, session) {
- if (hookPayload.kind === "subagent-authorization-event") {
- await emitProxiedAuthorizationEvent({ emit, hookPayload, session });
- return undefined;
- }
- return await emitProxiedInputRequest({ emit, hookPayload, session });
+ const view = sessionView(currentProjection(ctx), session.state);
+ const routes =
+ hookPayload.kind === "subagent-input-request"
+ ? toProxyInputRequestEntries(hookPayload)
+ : undefined;
+ // A child's fresh batch replaces its prior one, whose routes stop working, so readers
+ // must stop offering what it held.
+ const incoming = new Set(routes?.map(([requestId]) => requestId));
+ const replaced =
+ hookPayload.kind !== "subagent-input-request"
+ ? []
+ : [...getProxyInputRequests(session.state)]
+ .filter(
+ ([requestId, route]) =>
+ route.childContinuationToken === hookPayload.childContinuationToken &&
+ route.inputSource === hookPayload.inputSource &&
+ !incoming.has(requestId),
+ )
+ .map(([requestId]) => requestId);
+ // A relay changes no execution state, only what the session reports.
+ await applyTransition(
+ session,
+ relay(view, { payload: hookPayload, replacedRequestIds: replaced }),
+ emit,
+ );
+ return routes;
},
- updateSession(session, entries) {
- if (entries === undefined || hookPayload.kind !== "subagent-input-request") {
+ updateSession(session, routes) {
+ if (routes === undefined || hookPayload.kind !== "subagent-input-request") {
return { session };
}
return {
session: upsertProxyInputRequests({
- entries: entries.map(([requestId, route]) => [
+ entries: routes.map(([requestId, route]) => [
requestId,
{
...route,
diff --git a/packages/eve/src/subagents/hitl-proxy.integration.test.ts b/packages/eve/src/subagents/hitl-proxy.integration.test.ts
index 52e044a99..7fa5fbd3b 100644
--- a/packages/eve/src/subagents/hitl-proxy.integration.test.ts
+++ b/packages/eve/src/subagents/hitl-proxy.integration.test.ts
@@ -1,3 +1,4 @@
+import { toProxyInputRequestEntries } from "#harness/proxy-input-requests.js";
import { describe, expect, it } from "vitest";
import type { ChannelAdapter, ChannelAdapterContext } from "#channel/adapter.js";
@@ -9,7 +10,10 @@ import { ContextContainer } from "#context/container.js";
import type { CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { serializeContext } from "#context/serialize.js";
-import { setHarnessEmissionState } from "#harness/emission-state.js";
+import { applyTransition, sessionView } from "#harness/session-machine/commit.js";
+import { relay } from "#harness/session-machine/transitions.js";
+import { storedProjection } from "#harness/session-machine/view.js";
+import { withOpenTurn } from "#internal/testing/session-machine.js";
import { hasProxyInputRequests, upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { HarnessEmitFn, HarnessSession } from "#harness/types.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
@@ -18,7 +22,7 @@ import { createRuntimeAdapterRegistry } from "#runtime/channels/registry.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { createRuntimeHookRegistry } from "#runtime/hooks/registry.js";
import type { ResolvedChannelDefinition } from "#runtime/types.js";
-import { emitProxiedInputRequest, routeDeliverPayload } from "#subagents/hitl-proxy.js";
+import { routeDeliverPayload } from "#subagents/hitl-proxy.js";
/**
* Integration coverage for subagent HITL proxy emission and routing.
@@ -166,14 +170,24 @@ function buildEmptySession(continuationToken: string, sessionId: string): Harnes
}
function buildOpenTurnSession(continuationToken: string, sessionId: string): HarnessSession {
- return setHarnessEmissionState(buildEmptySession(continuationToken, sessionId), {
- sessionStarted: true,
+ return withOpenTurn(buildEmptySession(continuationToken, sessionId), {
sequence: 3,
stepIndex: 1,
turnId: "turn_3",
});
}
+/** Relays a child's batch through the parent's machine, returning the routes it leaves. */
+async function emitProxiedInputRequest(input: {
+ readonly emit: HarnessEmitFn;
+ readonly hookPayload: Parameters<typeof toProxyInputRequestEntries>[0];
+ readonly session: HarnessSession;
+}) {
+ const view = sessionView(storedProjection(input.session.state), input.session.state);
+ await applyTransition(input.session, relay(view, { payload: input.hookPayload }), input.emit);
+ return toProxyInputRequestEntries(input.hookPayload);
+}
+
/**
* Builds an adapter-aware emit helper and a captured-events sink
* paired to one parent context. The returned `emit` mirrors the
diff --git a/packages/eve/src/subagents/hitl-proxy.ts b/packages/eve/src/subagents/hitl-proxy.ts
index 21718ab82..d5113dd7d 100644
--- a/packages/eve/src/subagents/hitl-proxy.ts
+++ b/packages/eve/src/subagents/hitl-proxy.ts
@@ -1,84 +1,15 @@
import type { SessionInboxAddress } from "#execution/session-inbox/address.js";
-import { getSessionUsage } from "#harness/turn-tag-state.js";
-import type {
- DeliverPayload,
- SubagentAuthorizationEventHookPayload,
- SubagentInputRequestHookPayload,
-} from "#channel/types.js";
-import { getHarnessEmissionState } from "#harness/emission.js";
+import type { DeliverPayload } from "#channel/types.js";
import { resolveInputOutcome } from "#harness/input-request-resolution.js";
-import type { PendingInputBatchEvent } from "#harness/pending-input-batches.js";
-import {
- getProxyInputRequests,
- toProxyInputRequestEntries,
-} from "#harness/proxy-input-requests.js";
+import type { StepCoordinates as PendingInputBatchEvent } from "#harness/session-machine/view.js";
+import { getProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { WorkflowAskRoute, ProxyInputRequest } from "#harness/proxy-input-requests.js";
-import type { HarnessEmitFn, HarnessSessionBase, SessionStateMap } from "#harness/types.js";
-import {
- createInputRequestedEvent,
- createTurnWaitingEvent,
- type InputResolution,
-} from "#protocol/message.js";
+import type { SessionStateMap } from "#harness/types.js";
+import type { InputResolution } from "#protocol/message.js";
import type { InputResponse } from "#shared/input.js";
import { resolveTextToResponse } from "#channel/resolve-text.js";
import { inputTextKey, readAnswerText } from "#internal/input-text.js";
-import { SESSION_LIMIT_STOP_OPTION_ID } from "#harness/session-limit-continuation.js";
-
-// ---------------------------------------------------------------------------
-// Upward proxy emission
-// ---------------------------------------------------------------------------
-
-/**
- * Runs the parent-side work for a `subagent-input-request`: emits the request,
- * then `turn.waiting` for the parent's open turn. The call that asked is still
- * running, so the turn stays open until the answer lets that call settle. The
- * returned proxy entries route the eventual response back down to the asker.
- */
-export async function emitProxiedInputRequest(input: {
- readonly emit: HarnessEmitFn;
- readonly hookPayload: SubagentInputRequestHookPayload;
- readonly session: HarnessSessionBase;
-}): Promise<readonly (readonly [requestId: string, route: ProxyInputRequest])[]> {
- await input.emit(
- createInputRequestedEvent({
- requests: input.hookPayload.event.requests,
- sequence: input.hookPayload.event.sequence,
- stepIndex: input.hookPayload.event.stepIndex,
- taskId: input.hookPayload.event.taskId,
- turnId: input.hookPayload.event.turnId,
- }),
- );
- await input.emit(createTurnWaitingOnInputEvent(input.session));
- return toProxyInputRequestEntries(input.hookPayload);
-}
-
-/**
- * Runs the parent-side work for a `subagent-authorization-event`: re-emits the
- * event, and after `authorization.required` parks the parent's open turn with
- * `turn.waiting`. The sign-in completes on the asker's own callback while the
- * call keeps running, so the parent's turn neither ends nor resets.
- */
-export async function emitProxiedAuthorizationEvent(input: {
- readonly emit: HarnessEmitFn;
- readonly hookPayload: SubagentAuthorizationEventHookPayload;
- readonly session: HarnessSessionBase;
-}): Promise<void> {
- await input.emit(input.hookPayload.event);
- if (input.hookPayload.event.type === "authorization.required") {
- await input.emit(createTurnWaitingOnInputEvent(input.session));
- }
-}
-
-/** The `turn.waiting` that parks the session's open turn while a person must act. */
-export function createTurnWaitingOnInputEvent(session: Pick<HarnessSessionBase, "state">) {
- const turn = getHarnessEmissionState(session.state);
- return createTurnWaitingEvent({
- on: "input",
- sequence: turn.sequence,
- turnId: turn.turnId,
- usage: getSessionUsage(session),
- });
-}
+import { SESSION_LIMIT_STOP_OPTION_ID } from "#harness/hitl/budget-request.js";
// ---------------------------------------------------------------------------
// Downward deliver routing
diff --git a/packages/eve/src/svelte/index.ts b/packages/eve/src/svelte/index.ts
index 3f3ba35a7..8c4e87afa 100644
--- a/packages/eve/src/svelte/index.ts
+++ b/packages/eve/src/svelte/index.ts
@@ -16,6 +16,13 @@ export {
} from "#client/reducer.js";
export { conversationReducer } from "#client/conversation-reducer.js";
export { openConversationInputs } from "#client/conversation-state.js";
+export { toolCallState, type ToolCallState, type ToolCallStatus } from "#client/tool-call-state.js";
+export type {
+ SessionAuthorization,
+ SessionCall,
+ SessionCallStatus,
+ SessionProjection,
+} from "#protocol/session-projection.js";
export type {
AgentObservation,
ConversationAgentSession,
diff --git a/packages/eve/src/vue/index.ts b/packages/eve/src/vue/index.ts
index db669c69c..dda7f8f86 100644
--- a/packages/eve/src/vue/index.ts
+++ b/packages/eve/src/vue/index.ts
@@ -16,6 +16,13 @@ export {
} from "#client/reducer.js";
export { conversationReducer } from "#client/conversation-reducer.js";
export { openConversationInputs } from "#client/conversation-state.js";
+export { toolCallState, type ToolCallState, type ToolCallStatus } from "#client/tool-call-state.js";
+export type {
+ SessionAuthorization,
+ SessionCall,
+ SessionCallStatus,
+ SessionProjection,
+} from "#protocol/session-projection.js";
export type {
AgentObservation,
ConversationAgentSession,
diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjs
index 53887f968..873ee05dd 100644
--- a/scripts/guard-invariants.mjs
+++ b/scripts/guard-invariants.mjs
@@ -123,6 +123,19 @@
* directory removes protocol 1 without a search.
* rule 49 — Provided tool definitions carry a framework tool flag,
* so telemetry ownership survives renamed and namespaced tools.
+ * rule 50 — The human-in-the-loop lifecycle in `harness/hitl/` is
+ * reached only through its `index.ts`, its request vocabulary
+ * (`approval-prompt`, `budget-request`), and the approvers that
+ * approved calls run as (`approved-call-callers`), so replacing it
+ * changes one seam.
+ * rule 51 — Only the session machine (`harness/session-machine/`) and the
+ * human-in-the-loop lifecycle it delegates to
+ * (`harness/hitl/`) build lifecycle events and read the
+ * machine's private state. Every change to a turn, request,
+ * sign-in, task, or call outcome is a transition that returns its
+ * events, so nothing changes without readers hearing it. The model
+ * step's streamed content (its calls and their inline results) is
+ * built where it streams.
*
* Baselines for rules with pre-existing violations live in
* `guard-invariants-baseline.json`. Counts and allowlists in that file
@@ -242,6 +255,8 @@ function isTsLike(relPath) {
* rule46: Violation[];
* rule47: Violation[];
* rule48: Violation[];
+ * rule50: Violation[];
+ * rule51: Violation[];
* symlinks: string[];
* }} state
*/
@@ -275,6 +290,8 @@ async function scanRepo(state) {
checkRule46(posix, lines, state.rule46);
checkRule47(posix, lines, state.rule47);
checkRule48(posix, lines, state.rule48);
+ checkRule50(posix, lines, state.rule50);
+ checkRule51(posix, lines, state.rule51);
}
}
@@ -481,6 +498,85 @@ function checkRule47(posix, lines, violations) {
});
}
+// ---------- Rule 50: the human-in-the-loop lifecycle has one seam ----------
+
+const HUMAN_INPUT_DIR = "packages/eve/src/harness/hitl/";
+const HUMAN_INPUT_PRIVATE_IMPORT_RE =
+ /["'](?:#harness\/|(?:\.\.?\/)+)hitl\/(?!(?:index|approval-prompt|approved-call-callers|budget-request)\.js["'])/;
+
+/** @param {string} posix @param {string[]} lines @param {Violation[]} violations */
+function checkRule50(posix, lines, violations) {
+ if (
+ !posix.startsWith("packages/eve/src/") ||
+ posix.startsWith(HUMAN_INPUT_DIR) ||
+ posix.startsWith("packages/eve/src/internal/testing/") ||
+ /\.(?:test|integration\.test|scenario\.test)\.ts$/.test(posix)
+ )
+ return;
+ lines.forEach((line, idx) => {
+ if (!HUMAN_INPUT_PRIVATE_IMPORT_RE.test(line)) return;
+ violations.push({
+ rule: 50,
+ file: posix,
+ line: idx + 1,
+ message:
+ "imports the human-in-the-loop lifecycle's internals. Reach it through `#harness/hitl/index.js`, the one seam the rest of eve meets it at.",
+ });
+ });
+}
+
+// ---------- Rule 51: the session machine owns lifecycle ----------
+
+const SESSION_MACHINE_DIR = "packages/eve/src/harness/session-machine/";
+const LIFECYCLE_EVENT_BUILDER_RE =
+ /\bcreate(?:Session(?:Started|Waiting|Failed|Completed)|Turn(?:Started|Completed|Failed|Cancelled|Waiting)|MessageReceived|Step(?:Started|Failed)|Input(?:Requested|Resolved)|Authorization(?:Required|Completed)|Approval(?:Candidate|Settled)|Task(?:Started|Settled)|ContextCleared|ResultCompleted)Event\b/;
+const CALL_EVENT_BUILDER_RE = /\bcreateAction(?:Result|sRequested)Event\b/;
+/** Where the model step streams its calls, their inline results, and the calls they made. */
+const STREAM_CONTENT_FILES = new Set([
+ "packages/eve/src/harness/emission.ts",
+ "packages/eve/src/harness/nested-actions.ts",
+ "packages/eve/src/harness/step-hooks.ts",
+ "packages/eve/src/harness/stream-actions.ts",
+]);
+const MACHINE_PRIVATE_IMPORT_RE = /["']#harness\/session-machine\/(?:state|events)\.js["']/;
+
+/** @param {string} posix @param {string[]} lines @param {Violation[]} violations */
+function checkRule51(posix, lines, violations) {
+ if (
+ !posix.startsWith("packages/eve/src/") ||
+ posix.startsWith(SESSION_MACHINE_DIR) ||
+ posix.startsWith(HUMAN_INPUT_DIR) ||
+ posix.startsWith("packages/eve/src/protocol/") ||
+ posix.startsWith("packages/eve/src/internal/testing/") ||
+ posix.endsWith(".test.ts") ||
+ posix.includes("/test/")
+ )
+ return;
+ lines.forEach((line, idx) => {
+ const builder = LIFECYCLE_EVENT_BUILDER_RE.exec(line)?.[0];
+ const callBuilder = STREAM_CONTENT_FILES.has(posix)
+ ? undefined
+ : CALL_EVENT_BUILDER_RE.exec(line)?.[0];
+ if (builder !== undefined || callBuilder !== undefined) {
+ violations.push({
+ rule: 51,
+ file: posix,
+ line: idx + 1,
+ message: `uses ${builder ?? callBuilder} outside harness/session-machine/. Only the session machine builds lifecycle events: return them from a transition and publish what it returns with \`applyTransition\`.`,
+ });
+ }
+ if (MACHINE_PRIVATE_IMPORT_RE.test(line)) {
+ violations.push({
+ rule: 51,
+ file: posix,
+ line: idx + 1,
+ message:
+ "imports the session machine's private state or event builders. Read execution state through `#harness/session-machine/view.js`; change it with a transition.",
+ });
+ }
+ });
+}
+
// ---------- Rule 48: remote agent protocol 1 stays compartmentalized ----------
const LEGACY_REMOTE_AGENT_DIR = "packages/eve/src/execution/legacy-remote-agent/";
@@ -1604,6 +1700,8 @@ async function main() {
rule46: /** @type {Violation[]} */ ([]),
rule47: /** @type {Violation[]} */ ([]),
rule48: /** @type {Violation[]} */ ([]),
+ rule50: /** @type {Violation[]} */ ([]),
+ rule51: /** @type {Violation[]} */ ([]),
symlinks: /** @type {string[]} */ ([]),
};
@@ -1719,6 +1817,8 @@ async function main() {
violations.push(...state.rule47);
violations.push(...state.rule48);
violations.push(...(await checkFrameworkActionIdentity()));
+ violations.push(...state.rule50);
+ violations.push(...state.rule51);
if (violations.length === 0) {
process.stdout.write("[eve:guard:invariants] ok — all mechanical lints passed.\n");