Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add the inert task kernel in its final shape (#1804)

Ruif79184e5ce2e
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index 129bda700..044bd6b6a 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -8,6 +8,7 @@ import type { InputRequest, InputResponse } from "#runtime/input/types.js";
import type { ChannelAdapter } from "#channel/adapter.js";
import type { AgentLimitsDefinition } from "#shared/agent-definition.js";
import type { JsonObject } from "#shared/json.js";
+import type { TaskView } from "#tasks/types.js";
export type { ContextAccessor } from "#context/key.js";
export type { ChannelInstrumentationProjection } from "#channel/instrumentation.js";
@@ -22,6 +23,8 @@ export type RunSessionLimits = Pick<
/** Identifies the session turn to cancel. */
export interface CancelTurnInput {
readonly sessionId: string;
+ /** Framework task whose queued child deliveries should be discarded. */
+ readonly taskId?: string;
/** Limits the request to the turn the caller observed. */
readonly turnId?: string;
}
@@ -135,6 +138,8 @@ export type EventEmitFn = (event: UnstampedMessageStreamEvent) => Promise<void>;
export interface TurnCaller {
readonly callId: string;
readonly subagentName: string;
+ /** Present when this turn is the executor for a durable background task. */
+ readonly taskId?: string;
readonly replyTo:
| { readonly kind: "hook"; readonly token: string }
| { readonly kind: "callback"; readonly url: string };
@@ -157,6 +162,21 @@ export interface DeliverPayload {
readonly message?: string | UserContent;
readonly context?: readonly string[];
readonly outputSchema?: JsonObject;
+ /** Framework-only task envelopes consumed before adapter/model delivery. */
+ readonly task?: {
+ /** Task HITL input-request batches for the parent's pre-model router. */
+ readonly inputRequests?: readonly {
+ readonly hookPayload: SubagentInputRequestHookPayload;
+ readonly taskId: string;
+ }[];
+ /** Task authorization events projected through the parent channel. */
+ readonly authorizationEvents?: readonly {
+ readonly hookPayload: SubagentAuthorizationEventHookPayload;
+ readonly taskId: string;
+ }[];
+ /** Terminal snapshots cached before task-run retention expires. */
+ readonly snapshots?: readonly TaskView[];
+ };
readonly [key: string]: unknown;
}
@@ -175,9 +195,15 @@ export type SessionCommand =
readonly payload: DeliverPayload;
readonly delivery?: ChannelDeliveryMetadata;
readonly requestId?: string;
+ /**
+ * Replay-stable identity for one task-owned child delivery; lets the
+ * parent inbox dedupe retried durable-step deliveries. See
+ * {@link DeliverHookPayload.taskDeliveryId}.
+ */
+ readonly taskDeliveryId?: string;
readonly turnPolicy?: TurnPolicy;
}
- | { readonly kind: "cancel"; readonly turnId?: string }
+ | { readonly kind: "cancel"; readonly taskId?: string; readonly turnId?: string }
| { readonly kind: "compact" }
| { readonly kind: "clear" }
| { readonly kind: "reset"; readonly reason?: string };
@@ -230,6 +256,13 @@ export interface DeliverHookPayload {
readonly deliveryMetadata?: readonly ChannelDeliveryMetadataEntry[];
/** Inbound channel request id used only for workflow attributes. */
readonly requestId?: string;
+ /**
+ * Replay-stable identity for one task-owned child delivery. Task-run steps
+ * derive it from deterministic inputs (task id, event kind, sequence) so the
+ * parent inbox can drop the duplicate when a durable step retries after
+ * `resumeHook` already succeeded.
+ */
+ readonly taskDeliveryId?: string;
readonly kind: "deliver";
readonly payloads: readonly DeliverPayload[];
readonly turnPolicy?: TurnPolicy;
@@ -341,6 +374,7 @@ export type HookPayload =
export interface SessionCallback {
readonly callId: string;
readonly subagentName: string;
+ readonly taskId?: string;
readonly token: string;
readonly url: string;
}
diff --git a/packages/eve/src/execution/tasks/run-parent.ts b/packages/eve/src/execution/tasks/run-parent.ts
new file mode 100644
index 000000000..a08e47f1c
--- /dev/null
+++ b/packages/eve/src/execution/tasks/run-parent.ts
@@ -0,0 +1,217 @@
+import {
+ EntityConflictError,
+ HookNotFoundError,
+ RunExpiredError,
+ WorkflowRunNotFoundError,
+} from "#compiled/@workflow/errors/index.js";
+
+import type { TaskRunWorkflowInput } from "#execution/tasks/run-task-workflow.js";
+import {
+ startWorkflowPreferLatest,
+ taskRunWorkflowReference,
+} from "#execution/workflow-runtime.js";
+import { getRun, resumeHook } from "#internal/workflow/runtime.js";
+import { walkCauseChain } from "#shared/errors.js";
+import {
+ TASK_SNAPSHOT_STREAM_NAMESPACE,
+ isReadyTaskStatus,
+ type TaskCommand,
+ type TaskCommandHookPayload,
+ type TaskRunInboundPayload,
+ type TaskView,
+} from "#tasks/types.js";
+
+const TASK_SNAPSHOT_READ_TIMEOUT_MS = 10_000;
+
+/**
+ * Node-side controls for durable task runs. Every export must be called
+ * from inside a `"use step"` body; none of these are steps themselves so
+ * dispatch and tool steps can compose them inside one durable boundary.
+ */
+
+/** Starts the durable run owning one task's lifecycle. */
+export async function startTaskRun(
+ input: TaskRunWorkflowInput,
+): Promise<{ readonly runId: string }> {
+ const run = await startWorkflowPreferLatest(taskRunWorkflowReference, [input]);
+ return { runId: run.runId };
+}
+
+/**
+ * Submits one command to a task run.
+ *
+ * `unreachable` means the hook is not resumable — either the run
+ * already finished and disposed it (the task is terminal; read the
+ * final snapshot) or, right after creation, the freshly started run has
+ * not registered it yet. Senders racing that startup window pass
+ * `retryUnreachable`; senders addressing an established task treat
+ * `unreachable` as the terminal signal.
+ */
+export async function sendTaskCommand(input: {
+ readonly command: TaskCommand;
+ readonly continuationToken: string;
+ readonly retryUnreachable?: { readonly attempts: number; readonly delayMs: number };
+}): Promise<"delivered" | "unreachable"> {
+ return (await sendTaskCommandToOwner(input)) === undefined ? "unreachable" : "delivered";
+}
+
+/** Delivers one command and returns the accepting task workflow's run id. */
+export async function sendTaskCommandToOwner(input: {
+ readonly command: TaskCommand;
+ readonly continuationToken: string;
+ readonly retryUnreachable?: { readonly attempts: number; readonly delayMs: number };
+}): Promise<{ readonly runId: string } | undefined> {
+ const payload: TaskCommandHookPayload = { command: input.command, kind: "task-command" };
+ const attempts = Math.max(1, input.retryUnreachable?.attempts ?? 1);
+ for (let attempt = 0; ; attempt += 1) {
+ try {
+ const owner = await resumeHook(input.continuationToken, payload);
+ if (
+ typeof owner !== "object" ||
+ owner === null ||
+ !("runId" in owner) ||
+ typeof owner.runId !== "string"
+ ) {
+ throw new Error(
+ `Task continuation hook "${input.continuationToken}" returned no owner run id.`,
+ );
+ }
+ return { runId: owner.runId };
+ } catch (error) {
+ if (!isFinishedTaskRunTarget(error)) {
+ throw error;
+ }
+ if (attempt + 1 >= attempts) {
+ return undefined;
+ }
+ await new Promise((resolve) => setTimeout(resolve, input.retryUnreachable?.delayMs ?? 250));
+ }
+ }
+}
+
+/**
+ * Hands one non-command inbound payload to a task run.
+ *
+ * Used for payloads the run must act on before it may record them —
+ * today only answered input batches, which it forwards to the child
+ * first. `unreachable` means the task already finished and disposed its
+ * hook, so the payload is stale by definition.
+ */
+export async function sendTaskInboundPayload(input: {
+ readonly continuationToken: string;
+ readonly payload: TaskRunInboundPayload;
+}): Promise<"delivered" | "unreachable"> {
+ try {
+ await resumeHook(input.continuationToken, input.payload);
+ return "delivered";
+ } catch (error) {
+ if (!isFinishedTaskRunTarget(error)) {
+ throw error;
+ }
+ return "unreachable";
+ }
+}
+
+/**
+ * Reads the latest snapshot a task run has published, or `undefined`
+ * when the run has not committed its first snapshot yet (the caller
+ * already holds the creation receipt, which is `working`).
+ *
+ * Snapshots are trusted without re-validation: the task run is the
+ * single writer and every write passed the transition function.
+ */
+export async function readLatestTaskSnapshot(input: {
+ readonly taskRunId: string;
+}): Promise<TaskView | undefined> {
+ const stream = getRun<unknown>(input.taskRunId).getReadable<TaskView>({
+ namespace: TASK_SNAPSHOT_STREAM_NAMESPACE,
+ startIndex: -1,
+ });
+ const tailIndex = await stream.getTailIndex();
+ const reader = stream.getReader();
+ try {
+ if (tailIndex < 0) {
+ return undefined;
+ }
+ const result = await readWithTimeout(reader, "latest task snapshot");
+ return result;
+ } finally {
+ await reader.cancel("eve task snapshot read complete").catch(() => {});
+ reader.releaseLock();
+ }
+}
+
+/**
+ * Waits until a task run publishes a ready snapshot — terminal or
+ * `input_required` — starting from the latest published state. Returns
+ * immediately when the task is already ready.
+ *
+ * Unlike {@link readLatestTaskSnapshot} this read has no timeout; the
+ * caller owns cancellation by racing this promise (for example against
+ * turn cancellation) and abandoning it.
+ */
+export async function waitForReadyTaskSnapshot(input: {
+ readonly taskRunId: string;
+}): Promise<TaskView> {
+ const stream = getRun<unknown>(input.taskRunId).getReadable<TaskView>({
+ namespace: TASK_SNAPSHOT_STREAM_NAMESPACE,
+ startIndex: -1,
+ });
+ const reader = stream.getReader();
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done || value === undefined) {
+ throw new Error(
+ `Task run "${input.taskRunId}" closed its snapshot stream without a ready snapshot.`,
+ );
+ }
+ if (isReadyTaskStatus(value.status)) {
+ return value;
+ }
+ }
+ } finally {
+ await reader.cancel("eve task snapshot wait complete").catch(() => {});
+ reader.releaseLock();
+ }
+}
+
+async function readWithTimeout(
+ reader: ReadableStreamDefaultReader<TaskView>,
+ what: string,
+): Promise<TaskView | undefined> {
+ let timeout: ReturnType<typeof setTimeout> | undefined;
+ try {
+ const result = await Promise.race([
+ reader.read().then((read) => ({ kind: "read" as const, read })),
+ new Promise<{ readonly kind: "timeout" }>((resolve) => {
+ timeout = setTimeout(() => resolve({ kind: "timeout" }), TASK_SNAPSHOT_READ_TIMEOUT_MS);
+ }),
+ ]);
+ if (result.kind === "timeout") {
+ throw new Error(`Timed out reading ${what} after ${TASK_SNAPSHOT_READ_TIMEOUT_MS}ms.`);
+ }
+ if (result.read.done) {
+ return undefined;
+ }
+ return result.read.value;
+ } finally {
+ if (timeout !== undefined) {
+ clearTimeout(timeout);
+ }
+ }
+}
+
+export function isFinishedTaskRunTarget(error: unknown): boolean {
+ for (const candidate of walkCauseChain(error)) {
+ if (
+ HookNotFoundError.is(candidate) ||
+ WorkflowRunNotFoundError.is(candidate) ||
+ RunExpiredError.is(candidate) ||
+ EntityConflictError.is(candidate)
+ ) {
+ return true;
+ }
+ }
+ return false;
+}
diff --git a/packages/eve/src/execution/tasks/run-task-workflow.test.ts b/packages/eve/src/execution/tasks/run-task-workflow.test.ts
new file mode 100644
index 000000000..280284ad1
--- /dev/null
+++ b/packages/eve/src/execution/tasks/run-task-workflow.test.ts
@@ -0,0 +1,484 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createHook, type Hook } from "#compiled/@workflow/core/index.js";
+
+import { claimHookOwnership, disposeHook } from "#execution/hook-ownership.js";
+import {
+ appendTaskSnapshotStep,
+ deliverTaskInputResponsesStep,
+ wakeTaskAuthorizationParentStep,
+ wakeTaskInputRequestParentStep,
+ wakeTaskParentStep,
+} from "#execution/tasks/run-task.js";
+import { taskRunWorkflow } from "#execution/tasks/run-task-workflow.js";
+import type {
+ TaskCommandHookPayload,
+ TaskInboundAnswerInput,
+ TaskRunInboundPayload,
+ TaskView,
+} from "#tasks/types.js";
+
+vi.mock("#compiled/@workflow/core/index.js", () => ({
+ createHook: vi.fn(),
+}));
+
+vi.mock("../hook-ownership.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../hook-ownership.js")>()),
+ claimHookOwnership: vi.fn(),
+ disposeHook: vi.fn(),
+}));
+
+vi.mock("./run-task.js", () => ({
+ appendTaskSnapshotStep: vi.fn(),
+ deliverTaskInputResponsesStep: vi.fn(),
+ wakeTaskAuthorizationParentStep: vi.fn(),
+ wakeTaskInputRequestParentStep: vi.fn(),
+ wakeTaskParentStep: vi.fn(),
+}));
+
+afterEach(() => {
+ vi.resetAllMocks();
+});
+
+function createWorkingView(): TaskView {
+ return {
+ metadata: {
+ agentId: "ag_research:abcdef123456",
+ kind: "subagent",
+ mode: "local",
+ name: "research",
+ },
+ status: "working",
+ taskId: "task_abc123",
+ };
+}
+
+function mockCommandHook(payloads: readonly TaskRunInboundPayload[]): void {
+ const queue = [...payloads];
+ const hook = {
+ [Symbol.asyncIterator]: () => ({
+ next: async () =>
+ queue.length > 0
+ ? { done: false as const, value: queue.shift() as TaskCommandHookPayload }
+ : { done: true as const, value: undefined },
+ }),
+ token: "task-token",
+ } as Hook<TaskRunInboundPayload>;
+ vi.mocked(createHook).mockReturnValue(hook);
+}
+
+function appendedStatuses(): readonly string[] {
+ return vi.mocked(appendTaskSnapshotStep).mock.calls.map(([input]) => input.view.status);
+}
+
+describe("taskRunWorkflow", () => {
+ it("publishes the initial snapshot, applies commands, and stops at terminal", async () => {
+ mockCommandHook([
+ {
+ command: {
+ inputRequests: [{ question: "which?", requestId: "req-1" }],
+ kind: "require-input",
+ },
+ kind: "task-command",
+ },
+ { command: { kind: "answered", requestIds: ["req-1"] }, kind: "task-command" },
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ // Never consumed: the run stops at the terminal transition.
+ { command: { kind: "cancel" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working", "input_required", "working", "completed"]);
+ expect(disposeHook).toHaveBeenCalledTimes(1);
+ });
+
+ it("skips snapshots for rejected and noop commands", async () => {
+ mockCommandHook([
+ { command: { kind: "answered", requestIds: ["req-1"] }, kind: "task-command" }, // noop on working
+ { command: { kind: "cancel" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working", "cancelled"]);
+ });
+
+ it("exits without touching the lifecycle when the hook claim conflicts", async () => {
+ mockCommandHook([]);
+ vi.mocked(claimHookOwnership).mockRejectedValue(
+ Object.assign(new Error("Hook token in use"), { name: "HookConflictError" }),
+ );
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendTaskSnapshotStep).not.toHaveBeenCalled();
+ expect(disposeHook).not.toHaveBeenCalled();
+ });
+
+ it("disposes its hook when the command stream closes early", async () => {
+ mockCommandHook([
+ { command: { inputRequests: [], kind: "require-input" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working"]);
+ expect(disposeHook).toHaveBeenCalledTimes(1);
+ });
+
+ it("translates a settled child turn from the wire and wakes the parent once ready", async () => {
+ const ZERO = { cacheReadTokens: 0, cacheWriteTokens: 0, inputTokens: 0, outputTokens: 0 };
+ mockCommandHook([
+ {
+ kind: "runtime-action-result",
+ results: [
+ {
+ outcome: {
+ kind: "parked",
+ result: { kind: "succeeded", output: "answer" },
+ usageDelta: ZERO,
+ },
+ output: "answer",
+ },
+ ],
+ },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: {
+ ...createWorkingView(),
+ metadata: {
+ agentId: "ag_research:abcdef123456",
+ kind: "subagent",
+ mode: "local",
+ name: "research",
+ },
+ },
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working", "completed"]);
+ expect(wakeTaskParentStep).toHaveBeenCalledTimes(1);
+ expect(vi.mocked(wakeTaskParentStep).mock.calls[0]?.[0]).toMatchObject({
+ token: "parent-session-token",
+ view: { status: "completed", taskId: "task_abc123" },
+ });
+ });
+
+ it("keeps a fast terminal task hook alive until dispatch acknowledgement", async () => {
+ mockCommandHook([
+ {
+ kind: "runtime-action-result",
+ results: [
+ {
+ outcome: {
+ kind: "parked",
+ result: { kind: "succeeded", output: "fast" },
+ },
+ output: "fast",
+ },
+ ],
+ },
+ { command: { kind: "ready" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working", "completed"]);
+ expect(disposeHook).toHaveBeenCalledTimes(1);
+ });
+
+ it("releases a fast input request when the readiness barrier arrives", async () => {
+ mockCommandHook([
+ {
+ callId: "call-task",
+ childContinuationToken: "child-token",
+ childSessionId: "child-session",
+ event: {
+ requests: [
+ {
+ action: { callId: "call-q", input: {}, kind: "tool-call", toolName: "ask" },
+ kind: "question",
+ prompt: "Which?",
+ requestId: "q1",
+ },
+ ],
+ sequence: 1,
+ stepIndex: 2,
+ turnId: "turn-child",
+ },
+ kind: "subagent-input-request",
+ subagentName: "research",
+ },
+ { command: { kind: "ready" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(wakeTaskInputRequestParentStep).toHaveBeenCalledTimes(1);
+ expect(wakeTaskParentStep).not.toHaveBeenCalled();
+ });
+
+ it("holds a fast authorization event until the readiness barrier", async () => {
+ mockCommandHook([
+ {
+ callId: "call-task",
+ childSessionId: "child-session",
+ event: {
+ data: {
+ description: "Authorize GitHub",
+ name: "github",
+ sequence: 1,
+ stepIndex: 2,
+ turnId: "turn-child",
+ },
+ type: "authorization.required",
+ },
+ kind: "authorization-event",
+ subagentName: "research",
+ },
+ { command: { kind: "ready" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working", "input_required", "input_required"]);
+ expect(wakeTaskAuthorizationParentStep).toHaveBeenCalledTimes(1);
+ expect(vi.mocked(wakeTaskAuthorizationParentStep).mock.invocationCallOrder[0]).toBeGreaterThan(
+ vi.mocked(appendTaskSnapshotStep).mock.invocationCallOrder[2] ?? 0,
+ );
+ });
+
+ it("never wakes twice for one blocked child", async () => {
+ mockCommandHook([
+ {
+ command: { inputRequests: [{ q: 1, requestId: "q1" }], kind: "require-input" },
+ kind: "task-command",
+ },
+ {
+ command: { inputRequests: [{ q: 2, requestId: "q2" }], kind: "require-input" },
+ kind: "task-command",
+ },
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ // input_required wakes once; the second require-input replaces the
+ // batch without leaving the ready state, while terminal settlement
+ // still wakes independently after direct HITL responses.
+ expect(wakeTaskParentStep).toHaveBeenCalledTimes(2);
+ });
+
+ it("commits and forwards every exact local task HITL batch before terminal wake", async () => {
+ const request = (requestId: string) => ({
+ action: {
+ callId: `call-${requestId}`,
+ input: {},
+ kind: "tool-call" as const,
+ toolName: "ask",
+ },
+ kind: "question" as const,
+ prompt: requestId,
+ requestId,
+ });
+ const inbound = (requestId: string): TaskRunInboundPayload => ({
+ callId: "call-task",
+ childContinuationToken: "child-token",
+ childSessionId: "child-session-1",
+ event: { requests: [request(requestId)], sequence: 1, stepIndex: 2, turnId: "turn_child" },
+ kind: "subagent-input-request",
+ subagentName: "research",
+ });
+ mockCommandHook([
+ { command: { kind: "ready" }, kind: "task-command" },
+ inbound("q1"),
+ inbound("q2"),
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(wakeTaskInputRequestParentStep).toHaveBeenCalledTimes(2);
+ expect(
+ vi.mocked(wakeTaskInputRequestParentStep).mock.calls.map(([input]) => {
+ const request = input.request.event.requests[0];
+ return request !== null && typeof request === "object"
+ ? Reflect.get(request, "requestId")
+ : undefined;
+ }),
+ ).toEqual(["q1", "q2"]);
+ expect(wakeTaskParentStep).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ view: expect.objectContaining({ status: "completed" }) }),
+ );
+ const firstInputWakeOrder =
+ vi.mocked(wakeTaskInputRequestParentStep).mock.invocationCallOrder[0] ?? 0;
+ const firstInputAppendOrder =
+ vi.mocked(appendTaskSnapshotStep).mock.invocationCallOrder[2] ?? 0;
+ expect(firstInputAppendOrder).toBeLessThan(firstInputWakeOrder);
+ });
+});
+
+describe("taskRunWorkflow answered input", () => {
+ function requireInput(...requestIds: readonly string[]): TaskRunInboundPayload {
+ return {
+ command: {
+ inputRequests: requestIds.map((requestId) => ({ prompt: requestId, requestId })),
+ kind: "require-input",
+ },
+ kind: "task-command",
+ };
+ }
+
+ function answer(...requestIds: readonly string[]): TaskInboundAnswerInput {
+ return {
+ childContinuationToken: "child-token",
+ inputResponses: requestIds.map((requestId) => ({ requestId, text: "answer" })),
+ kind: "input-response",
+ taskId: "task_abc123",
+ };
+ }
+
+ it("forwards the answer to the child before recording it as unblocked", async () => {
+ vi.mocked(deliverTaskInputResponsesStep).mockResolvedValue("delivered");
+ mockCommandHook([
+ requireInput("q1"),
+ answer("q1"),
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(deliverTaskInputResponsesStep).toHaveBeenCalledWith({
+ answer: answer("q1"),
+ requestIds: ["q1"],
+ });
+ expect(appendedStatuses()).toEqual(["working", "input_required", "working", "completed"]);
+ const deliveryOrder = vi.mocked(deliverTaskInputResponsesStep).mock.invocationCallOrder[0] ?? 0;
+ const unblockOrder = vi.mocked(appendTaskSnapshotStep).mock.invocationCallOrder[2] ?? 0;
+ expect(deliveryOrder).toBeLessThan(unblockOrder);
+ });
+
+ it("never lets an answer to a superseded batch reach the child", async () => {
+ vi.mocked(deliverTaskInputResponsesStep).mockResolvedValue("delivered");
+ mockCommandHook([
+ requireInput("q1"),
+ requireInput("q2"),
+ answer("q1"),
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(deliverTaskInputResponsesStep).not.toHaveBeenCalled();
+ expect(appendedStatuses()).toEqual([
+ "working",
+ "input_required",
+ "input_required",
+ "completed",
+ ]);
+ });
+
+ it("stays blocked on the requests an answer did not cover", async () => {
+ vi.mocked(deliverTaskInputResponsesStep).mockResolvedValue("delivered");
+ mockCommandHook([
+ requireInput("q1", "q2"),
+ answer("q1", "unknown"),
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(deliverTaskInputResponsesStep).toHaveBeenCalledWith({
+ answer: answer("q1", "unknown"),
+ requestIds: ["q1"],
+ });
+ const blockedAgain = vi.mocked(appendTaskSnapshotStep).mock.calls[2]?.[0].view;
+ expect(blockedAgain?.status).toBe("input_required");
+ expect(blockedAgain?.inputRequests).toEqual([{ prompt: "q2", requestId: "q2" }]);
+ });
+
+ it("keeps the task blocked when the child never received the answer", async () => {
+ vi.mocked(deliverTaskInputResponsesStep).mockResolvedValue("unreachable");
+ mockCommandHook([
+ requireInput("q1"),
+ answer("q1"),
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(appendedStatuses()).toEqual(["working", "input_required", "completed"]);
+ });
+
+ it("ignores an answer addressed to a different task", async () => {
+ vi.mocked(deliverTaskInputResponsesStep).mockResolvedValue("delivered");
+ mockCommandHook([
+ requireInput("q1"),
+ { ...answer("q1"), taskId: "task_other" },
+ { command: { data: "done", kind: "complete" }, kind: "task-command" },
+ ]);
+
+ await taskRunWorkflow({
+ continuationToken: "task-token",
+ initialView: createWorkingView(),
+ parentContinuationToken: "parent-session-token",
+ });
+
+ expect(deliverTaskInputResponsesStep).not.toHaveBeenCalled();
+ expect(appendedStatuses()).toEqual(["working", "input_required", "completed"]);
+ });
+});
diff --git a/packages/eve/src/execution/tasks/run-task-workflow.ts b/packages/eve/src/execution/tasks/run-task-workflow.ts
new file mode 100644
index 000000000..6cf94e9c9
--- /dev/null
+++ b/packages/eve/src/execution/tasks/run-task-workflow.ts
@@ -0,0 +1,190 @@
+import { createHook } from "#compiled/@workflow/core/index.js";
+
+import { claimHookOwnership, disposeHook, isHookConflictError } from "#execution/hook-ownership.js";
+import {
+ appendTaskSnapshotStep,
+ deliverTaskInputResponsesStep,
+ wakeTaskAuthorizationParentStep,
+ wakeTaskInputRequestParentStep,
+ wakeTaskParentStep,
+} from "#execution/tasks/run-task.js";
+import { applyTaskTransition } from "#tasks/transitions.js";
+import { translateTaskInboundPayload } from "#tasks/wire.js";
+import {
+ isReadyTaskStatus,
+ isTerminalTaskStatus,
+ readTaskInputRequestId,
+ readTaskUsage,
+ type TaskCommand,
+ type TaskInboundAnswerInput,
+ type TaskInboundAuthorizationEvent,
+ type TaskInboundInputRequest,
+ type TaskRunInboundPayload,
+ type TaskView,
+} from "#tasks/types.js";
+
+/** Input for one durable task run. */
+export interface TaskRunWorkflowInput {
+ /** Private continuation token; a routing credential, never model-visible. */
+ readonly continuationToken: string;
+ /** The creation snapshot, normally `working`. */
+ readonly initialView: TaskView;
+ /** Parent session delivery token used to wake the task's owning parent. */
+ readonly parentContinuationToken: string;
+}
+
+function isTaskRunFinished(view: TaskView, dispatchAcknowledged: boolean): boolean {
+ if (!isTerminalTaskStatus(view.status) || !dispatchAcknowledged) return false;
+
+ // Cancellation makes the task terminal before the child executor has
+ // necessarily unwound. Keep its hook open until the final result settles it.
+ return view.status !== "cancelled" || view.executor?.lifecycle === "terminal";
+}
+
+/**
+ * The durable task run: single writer for one task's lifecycle.
+ *
+ * Consumes commands and child wire payloads over its private hook,
+ * applies the pure transition function, and appends a full `TaskView`
+ * snapshot per accepted command to its `eve.task` run stream. Competing
+ * completion, cancellation, and input transitions serialize here;
+ * rejected commands (for example a late child result after `cancelled`)
+ * change nothing.
+ *
+ * Wake policy: a transition into a ready status — terminal or
+ * `input_required` — delivers a framework notification to the parent
+ * session. A parked parent starts a turn; an active turn observes the
+ * delivery at its next safe boundary. Nothing else wakes the parent.
+ *
+ * The run ends when the task reaches a terminal status. Its snapshot
+ * stream stays readable, so terminal tasks remain peekable; the
+ * disposed hook makes any later command fail loudly instead of queueing
+ * against a finished task.
+ */
+export async function taskRunWorkflow(input: TaskRunWorkflowInput): Promise<void> {
+ "use workflow";
+
+ const commands = createHook<TaskRunInboundPayload>({ token: input.continuationToken });
+ // The iterator shares the hook's durable cursor; create it before
+ // claiming so conflict replay is consumed by getConflict(), not a
+ // later iterator read.
+ const iterator = commands[Symbol.asyncIterator]();
+ let ownsHook = false;
+
+ try {
+ try {
+ await claimHookOwnership(commands);
+ ownsHook = true;
+ } catch (error) {
+ // A duplicate start for the same task (crash between the start
+ // side effect and its step commit) loses the claim and exits;
+ // the surviving run owns the lifecycle.
+ if (isHookConflictError(error)) return;
+ throw error;
+ }
+
+ let view = input.initialView;
+ let pendingInputRequest: TaskInboundInputRequest | undefined;
+ let pendingAuthorizationEvent: TaskInboundAuthorizationEvent | undefined;
+ let dispatchAcknowledged = false;
+ await appendTaskSnapshotStep({ view });
+
+ while (!isTaskRunFinished(view, dispatchAcknowledged)) {
+ const next = await iterator.next();
+ if (next.done === true) return;
+ if (next.value.kind === "task-command") dispatchAcknowledged = true;
+ if (next.value.kind === "subagent-input-request") {
+ pendingInputRequest = next.value;
+ }
+ if (next.value.kind === "authorization-event") {
+ pendingAuthorizationEvent = next.value;
+ }
+ const payload = next.value;
+ const isExecutorResultAfterCancellation =
+ view.status === "cancelled" && payload.kind === "runtime-action-result";
+ const isTaskInputAnswer = payload.kind === "input-response";
+ let command: TaskCommand | undefined;
+
+ if (isExecutorResultAfterCancellation) {
+ command = {
+ kind: "settle-executor",
+ usage: readTaskUsage(payload.results[0]?.outcome?.usageDelta),
+ };
+ } else if (isTaskInputAnswer) {
+ if (view.status !== "input_required") continue;
+ command = await resolveAnsweredCommand(view, payload);
+ } else {
+ command = translateTaskInboundPayload(payload);
+ }
+ if (command === undefined) continue;
+ const result = applyTaskTransition(view, command);
+ if (result.outcome !== "accepted") continue;
+ const becameTerminal =
+ !isTerminalTaskStatus(view.status) && isTerminalTaskStatus(result.view.status);
+ const becameReady = !isReadyTaskStatus(view.status) && isReadyTaskStatus(result.view.status);
+ view = result.view;
+ await appendTaskSnapshotStep({ view });
+ if (pendingAuthorizationEvent !== undefined && dispatchAcknowledged) {
+ await wakeTaskAuthorizationParentStep({
+ request: pendingAuthorizationEvent,
+ taskId: view.taskId,
+ token: input.parentContinuationToken,
+ });
+ pendingAuthorizationEvent = undefined;
+ }
+ const routableInputRequest =
+ pendingInputRequest !== undefined &&
+ dispatchAcknowledged &&
+ view.status === "input_required";
+ if (routableInputRequest) {
+ await wakeTaskInputRequestParentStep({
+ request: pendingInputRequest as TaskInboundInputRequest,
+ taskId: view.taskId,
+ token: input.parentContinuationToken,
+ });
+ pendingInputRequest = undefined;
+ } else if (becameTerminal || (becameReady && pendingInputRequest === undefined)) {
+ await wakeTaskParentStep({ token: input.parentContinuationToken, view });
+ }
+ // An unrouted request cannot outlive the block it described, or a
+ // later block would replay it to the parent as if it were new.
+ if (view.status !== "input_required") pendingInputRequest = undefined;
+ }
+ } finally {
+ // Dispose-only teardown: `iterator.return()` would await a pending
+ // durable read that never settles, leaving this run `running`
+ // forever and its hook unswept.
+ if (ownsHook) await disposeHook(commands);
+ }
+}
+
+/**
+ * Forwards one human answer to the blocked child and reports which
+ * requests it cleared.
+ *
+ * Delivery is attempted only for requests the run still lists as
+ * outstanding, and the resulting command names exactly those ids. That
+ * ordering is the point: answers to a superseded batch never reach the
+ * child, and a child whose hook is already gone leaves the task blocked
+ * instead of moving to `working` with nothing listening.
+ */
+async function resolveAnsweredCommand(
+ view: Extract<TaskView, { status: "input_required" }>,
+ answer: TaskInboundAnswerInput,
+): Promise<TaskCommand | undefined> {
+ if (answer.taskId !== view.taskId) return undefined;
+
+ const outstanding = new Set(
+ view.inputRequests.flatMap((request) => {
+ const requestId = readTaskInputRequestId(request);
+ return requestId === undefined ? [] : [requestId];
+ }),
+ );
+ const requestIds = answer.inputResponses
+ .map((response) => response.requestId)
+ .filter((requestId) => outstanding.has(requestId));
+ if (requestIds.length === 0) return undefined;
+
+ const delivery = await deliverTaskInputResponsesStep({ answer, requestIds });
+ return delivery === "delivered" ? { kind: "answered", requestIds } : undefined;
+}
diff --git a/packages/eve/src/execution/tasks/run-task.ts b/packages/eve/src/execution/tasks/run-task.ts
new file mode 100644
index 000000000..b241f7e81
--- /dev/null
+++ b/packages/eve/src/execution/tasks/run-task.ts
@@ -0,0 +1,231 @@
+import { getWritable } from "#compiled/@workflow/core/index.js";
+import {
+ EntityConflictError,
+ HookNotFoundError,
+ RunExpiredError,
+ WorkflowRunNotFoundError,
+} from "#compiled/@workflow/errors/index.js";
+
+import type {
+ SessionAuthContext,
+ SessionCommand,
+ SubagentAuthorizationEventHookPayload,
+ SubagentInputRequestHookPayload,
+} from "#channel/types.js";
+import { resumeHook } from "#internal/workflow/runtime.js";
+import { createLogger } from "#internal/logging.js";
+import { walkCauseChain } from "#shared/errors.js";
+import {
+ isTerminalTaskStatus,
+ TASK_SNAPSHOT_STREAM_NAMESPACE,
+ type TaskInboundAnswerInput,
+ type TaskInboundAuthorizationEvent,
+ type TaskInboundInputRequest,
+ type TaskView,
+} from "#tasks/types.js";
+
+const log = createLogger("execution.tasks.run");
+
+/**
+ * Appends one full task snapshot to the owning task run's `eve.task`
+ * stream. Only the task run workflow calls this, which is what makes
+ * the run the single writer readers can trust without re-validating.
+ */
+export async function appendTaskSnapshotStep(input: { readonly view: TaskView }): Promise<void> {
+ "use step";
+
+ const writable = getWritable<TaskView>({ namespace: TASK_SNAPSHOT_STREAM_NAMESPACE });
+ const writer = writable.getWriter();
+ try {
+ await writer.write(input.view);
+ } finally {
+ writer.releaseLock();
+ }
+}
+
+/** Re-emits a task-owned child authorization event through the parent channel. */
+export async function wakeTaskAuthorizationParentStep(input: {
+ readonly request: TaskInboundAuthorizationEvent;
+ readonly taskId: string;
+ readonly token: string;
+}): Promise<void> {
+ "use step";
+
+ const hookPayload: SubagentAuthorizationEventHookPayload = {
+ callId: input.request.callId,
+ childSessionId: input.request.childSessionId,
+ event: input.request.event,
+ kind: "subagent-authorization-event",
+ subagentName: input.request.subagentName,
+ };
+ const eventId =
+ input.request.event.type === "approval.candidate" ||
+ input.request.event.type === "approval.settled"
+ ? input.request.event.data.requestId
+ : input.request.event.data.name;
+ const data = input.request.event.data;
+ const payload: {
+ message?: string;
+ task: {
+ authorizationEvents: {
+ hookPayload: SubagentAuthorizationEventHookPayload;
+ taskId: string;
+ }[];
+ };
+ } = { task: { authorizationEvents: [{ hookPayload, taskId: input.taskId }] } };
+ if (input.request.event.type === "authorization.required") {
+ payload.message = `Background task ${input.taskId} needs authorization.`;
+ }
+ const command: SessionCommand = {
+ kind: "send",
+ payload,
+ taskDeliveryId: `${input.taskId}:authorization:${input.request.event.type}:${data.turnId}:${data.stepIndex}:${data.sequence}:${eventId}`,
+ };
+ try {
+ await resumeHook(input.token, command);
+ } catch (error) {
+ if (isGoneParentTarget(error)) return;
+ throw error;
+ }
+}
+
+/**
+ * Wakes the parent session with a framework task notification.
+ *
+ * Rides the ordinary session delivery path: a parked parent starts a
+ * turn carrying this message, while an active turn observes it at the
+ * next safe boundary through the driver's normal delivery routing. A
+ * parent whose session already ended is a tolerated no-op.
+ */
+export async function wakeTaskParentStep(input: {
+ readonly token: string;
+ readonly view: TaskView;
+}): Promise<void> {
+ "use step";
+
+ const payload: { message: string; task?: { snapshots: readonly TaskView[] } } = {
+ message: formatTaskNotification(input.view),
+ };
+ if (isTerminalTaskStatus(input.view.status)) payload.task = { snapshots: [input.view] };
+ const command: SessionCommand = {
+ kind: "send",
+ payload,
+ taskDeliveryId: `${input.view.taskId}:ready:${input.view.status}`,
+ };
+ try {
+ await resumeHook(input.token, command);
+ } catch (error) {
+ if (isGoneParentTarget(error)) {
+ log.warn("task wake target is gone; the parent session already ended", {
+ status: input.view.status,
+ taskId: input.view.taskId,
+ });
+ return;
+ }
+ throw error;
+ }
+}
+
+/** Sends an exact local-task HITL batch to the parent's pre-model router. */
+export async function wakeTaskInputRequestParentStep(input: {
+ readonly request: TaskInboundInputRequest;
+ readonly taskId: string;
+ readonly token: string;
+}): Promise<void> {
+ "use step";
+
+ const command: SessionCommand = {
+ kind: "send",
+ payload: {
+ task: {
+ inputRequests: [
+ {
+ hookPayload: input.request as SubagentInputRequestHookPayload,
+ taskId: input.taskId,
+ },
+ ],
+ },
+ },
+ taskDeliveryId: `${input.taskId}:input:${input.request.event.turnId}:${input.request.event.stepIndex}:${input.request.event.sequence}`,
+ };
+ try {
+ await resumeHook(input.token, command);
+ } catch (error) {
+ if (isGoneParentTarget(error)) return;
+ throw error;
+ }
+}
+
+/**
+ * Forwards answered input to the blocked child.
+ *
+ * The task run performs this itself so the child unblocks and the
+ * snapshot leaves `input_required` under one durable decision. Returns
+ * `unreachable` when the child hook is already gone, which leaves the
+ * outstanding batch untouched rather than reporting a task as working
+ * when nothing received the answer.
+ */
+export async function deliverTaskInputResponsesStep(input: {
+ readonly answer: TaskInboundAnswerInput;
+ readonly requestIds: readonly string[];
+}): Promise<"delivered" | "unreachable"> {
+ "use step";
+
+ const answered = new Set(input.requestIds);
+ const command: SessionCommand = {
+ auth: input.answer.auth as SessionAuthContext | null | undefined,
+ kind: "send",
+ payload: {
+ inputResponses: input.answer.inputResponses.filter((response) =>
+ answered.has(response.requestId),
+ ),
+ },
+ taskDeliveryId: `${input.answer.taskId}:${[...input.requestIds].sort().join(",")}`,
+ };
+ try {
+ if (input.answer.childResponseUrl !== undefined) {
+ const response = await fetch(input.answer.childResponseUrl, {
+ body: JSON.stringify({ inputResponses: command.payload.inputResponses }),
+ headers: { "content-type": "application/json" },
+ method: "POST",
+ redirect: "error",
+ });
+ if (response.status === 404) return "unreachable";
+ if (!response.ok)
+ throw new Error(`Remote task input delivery failed with HTTP ${response.status}.`);
+ } else {
+ await resumeHook(input.answer.childContinuationToken, command);
+ }
+ return "delivered";
+ } catch (error) {
+ if (isGoneParentTarget(error)) {
+ log.warn("task input answer target is gone; the child turn already ended", {
+ taskId: input.answer.taskId,
+ });
+ return "unreachable";
+ }
+ throw error;
+ }
+}
+
+function formatTaskNotification(view: TaskView): string {
+ const subject = `Background task ${view.taskId} (${view.metadata.name})`;
+ if (view.status === "input_required") {
+ return `${subject} needs input. Use task_peek to inspect the outstanding requests.`;
+ }
+ return `${subject} is ${view.status}. Use task_peek to read its output.`;
+}
+
+function isGoneParentTarget(error: unknown): boolean {
+ for (const candidate of walkCauseChain(error)) {
+ if (
+ HookNotFoundError.is(candidate) ||
+ WorkflowRunNotFoundError.is(candidate) ||
+ RunExpiredError.is(candidate) ||
+ EntityConflictError.is(candidate)
+ ) {
+ return true;
+ }
+ }
+ return false;
+}
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 3d8dbd1d9..ba03b8e5f 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -56,6 +56,7 @@ import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agen
const WORKFLOW_ENTRY_NAME = "workflowEntry";
const TURN_WORKFLOW_NAME = "turnWorkflow";
const SESSION_TIMEOUT_WORKFLOW_NAME = "sessionTimeoutWorkflow";
+const TASK_RUN_WORKFLOW_NAME = "taskRunWorkflow";
const EVE_PACKAGE_INFO = resolveInstalledPackageInfo();
const COMMAND_HOOK_READY_TIMEOUT_MS = 30_000;
@@ -76,6 +77,7 @@ export const STABLE_WORKFLOW_NAMES: ReadonlySet<string> = new Set([
WORKFLOW_ENTRY_NAME,
TURN_WORKFLOW_NAME,
SESSION_TIMEOUT_WORKFLOW_NAME,
+ TASK_RUN_WORKFLOW_NAME,
]);
const STABLE_ID_BASE = EVE_PACKAGE_INFO.name;
@@ -112,6 +114,11 @@ export const sessionTimeoutWorkflowReference = {
workflowId: `workflow//${STABLE_ID_BASE}//${SESSION_TIMEOUT_WORKFLOW_NAME}`,
};
+/** Stable workflow reference for durable task runs (`experimental.tasks`). */
+export const taskRunWorkflowReference = {
+ workflowId: `workflow//${STABLE_ID_BASE}//${TASK_RUN_WORKFLOW_NAME}`,
+};
+
/**
* Creates a workflow-backed runtime whose long-lived driver owns the
* event stream and dispatches each turn as a child workflow run.
diff --git a/packages/eve/src/protocol/routes.ts b/packages/eve/src/protocol/routes.ts
index 3b8cef40d..9bd97b9e6 100644
--- a/packages/eve/src/protocol/routes.ts
+++ b/packages/eve/src/protocol/routes.ts
@@ -37,6 +37,11 @@ export const EVE_SESSION_RESET_ROUTE_PATTERN = `${EVE_SESSION_ROUTE_PATH}/:sessi
/** Stable event-stream route pattern for one exact session ID. */
export const EVE_SESSION_STREAM_ROUTE_PATTERN = `${EVE_SESSION_ROUTE_PATH}/:sessionId/stream`;
+/**
+ * Parent-origin proxy route for one remotely executed child session stream.
+ */
+export const EVE_SUBAGENT_STREAM_ROUTE_PATTERN = `${EVE_SESSION_ROUTE_PATH}/:parentSessionId/subagents/:callId/:childSessionId/stream`;
+
/**
* Framework-owned route pattern for dispatching one authored schedule
* exactly once from the dev server.
@@ -110,6 +115,9 @@ export const EVE_LEGACY_CONNECTION_CALLBACK_ROUTE_PATTERN = `${EVE_ROUTE_PREFIX}
*/
export const EVE_CALLBACK_ROUTE_PATTERN = `${EVE_ROUTE_PREFIX}/callback/:token`;
+/** Capability route used by a parent task to answer a remote child HITL batch. */
+export const EVE_TASK_INPUT_ROUTE_PATTERN = `${EVE_ROUTE_PREFIX}/task-input/:token`;
+
/** Builds the ID-addressed message route for one session. */
export function createEveSessionRoutePath(sessionId: string): string {
return `${EVE_SESSION_ROUTE_PATH}/${encodeURIComponent(sessionId)}`;
@@ -120,6 +128,15 @@ export function createEveSessionCancelRoutePath(sessionId: string): string {
return `${EVE_SESSION_ROUTE_PATH}/${encodeURIComponent(sessionId)}/cancel`;
}
+/** Builds the parent-origin stream path for one remote child session. */
+export function createEveSubagentStreamRoutePath(input: {
+ readonly callId: string;
+ readonly childSessionId: string;
+ readonly parentSessionId: string;
+}): string {
+ return `${EVE_SESSION_ROUTE_PATH}/${encodeURIComponent(input.parentSessionId)}/subagents/${encodeURIComponent(input.callId)}/${encodeURIComponent(input.childSessionId)}/stream`;
+}
+
/** Builds the ID-addressed compact route for one session. */
export function createEveSessionCompactRoutePath(sessionId: string): string {
return `${EVE_SESSION_ROUTE_PATH}/${encodeURIComponent(sessionId)}/compact`;
@@ -164,3 +181,8 @@ export function createEveConnectionCallbackRoutePath(
export function createEveCallbackRoutePath(token: string): string {
return `${EVE_ROUTE_PREFIX}/callback/${encodeURIComponent(token)}`;
}
+
+/** Builds the capability path used to answer one remote child turn. */
+export function createEveTaskInputRoutePath(token: string): string {
+ return `${EVE_ROUTE_PREFIX}/task-input/${encodeURIComponent(token)}`;
+}
diff --git a/packages/eve/src/tasks/json.test.ts b/packages/eve/src/tasks/json.test.ts
new file mode 100644
index 000000000..bb9f4b1e8
--- /dev/null
+++ b/packages/eve/src/tasks/json.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import { taskViewToJson } from "#tasks/json.js";
+import type { TaskView } from "#tasks/types.js";
+
+describe("taskViewToJson", () => {
+ it("projects only the model-visible task fields", () => {
+ const view: TaskView = {
+ executor: {
+ childSessionId: "child-session-1",
+ childTurnId: "child-turn-1",
+ lifecycle: "terminal",
+ },
+ lastOutput: { data: { answer: 42 }, type: "result" },
+ metadata: {
+ agentId: "agent-1",
+ kind: "subagent",
+ mode: "local",
+ name: "researcher",
+ },
+ status: "completed",
+ taskId: "task-1",
+ usage: {
+ cacheReadTokens: 1,
+ cacheWriteTokens: 2,
+ inputTokens: 3,
+ outputTokens: 4,
+ },
+ };
+
+ expect(taskViewToJson(view)).toEqual({
+ lastOutput: { data: { answer: 42 }, type: "result" },
+ metadata: {
+ agentId: "agent-1",
+ kind: "subagent",
+ mode: "local",
+ name: "researcher",
+ },
+ status: "completed",
+ taskId: "task-1",
+ });
+ });
+});
diff --git a/packages/eve/src/tasks/json.ts b/packages/eve/src/tasks/json.ts
new file mode 100644
index 000000000..2ec1a9d96
--- /dev/null
+++ b/packages/eve/src/tasks/json.ts
@@ -0,0 +1,65 @@
+import { z } from "#compiled/zod/index.js";
+
+import { jsonValueSchema } from "#shared/json-schemas.js";
+import type { JsonValue } from "#shared/json.js";
+import type { TaskView } from "#tasks/types.js";
+
+const taskMetadataJsonSchema = z.object({
+ agentId: z.string(),
+ kind: z.literal("subagent"),
+ mode: z.enum(["local", "remote"]),
+ name: z.string(),
+});
+
+const taskOutputJsonSchema = z.object({
+ data: jsonValueSchema,
+ type: z.enum(["result", "error"]),
+});
+
+const taskViewJsonBaseShape = {
+ metadata: taskMetadataJsonSchema,
+ taskId: z.string(),
+};
+
+/** Model-visible task shape. Unlisted private fields are stripped by zod. */
+const taskViewJsonSchema = z.discriminatedUnion("status", [
+ z.object({ ...taskViewJsonBaseShape, status: z.literal("working") }),
+ z.object({
+ ...taskViewJsonBaseShape,
+ inputRequests: z.array(jsonValueSchema).readonly(),
+ status: z.literal("input_required"),
+ }),
+ z.object({
+ ...taskViewJsonBaseShape,
+ lastOutput: taskOutputJsonSchema.extend({ type: z.literal("result") }),
+ status: z.literal("completed"),
+ }),
+ z.object({
+ ...taskViewJsonBaseShape,
+ lastOutput: taskOutputJsonSchema.extend({ type: z.literal("error") }),
+ status: z.literal("failed"),
+ }),
+ z.object({ ...taskViewJsonBaseShape, status: z.literal("cancelled") }),
+]);
+
+/**
+ * Model-visible task snapshot, inferred from {@link taskViewJsonSchema}.
+ *
+ * This is the public projection of `TaskView` (#tasks/types.js), not a
+ * replacement for it: the durable snapshot additionally carries private
+ * `executor` and `usage`, and its module must stay zod-free because it is
+ * bundled into workflow bodies.
+ */
+export type TaskViewJson = z.infer<typeof taskViewJsonSchema>;
+
+/** Projects a task snapshot into the JSON value carried by tool results. */
+export function taskViewToJson(view: TaskView): TaskViewJson {
+ // `satisfies` couples the schema to `TaskView` at compile time; the runtime
+ // parse strips the private fields structural typing would let through.
+ return taskViewJsonSchema.parse(view satisfies TaskViewJson);
+}
+
+/** Projects many snapshots into one `{ tasks }` tool output. */
+export function taskViewsToJson(views: readonly TaskView[]): JsonValue {
+ return { tasks: views.map((view) => taskViewToJson(view)) };
+}
diff --git a/packages/eve/src/tasks/session-index.test.ts b/packages/eve/src/tasks/session-index.test.ts
new file mode 100644
index 000000000..536ae9815
--- /dev/null
+++ b/packages/eve/src/tasks/session-index.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+
+import type { HarnessSession } from "#harness/types.js";
+import {
+ SESSION_TASKS_STATE_KEY,
+ findSessionTaskEntry,
+ getSessionTaskIndex,
+ recordSessionTask,
+} from "#tasks/session-index.js";
+import { deriveTaskId } from "#tasks/task-id.js";
+function createSession(state?: HarnessSession["state"]): HarnessSession {
+ return {
+ agent: {
+ modelReference: { id: "model_test" },
+ system: "",
+ tools: [],
+ },
+ compaction: { recentWindowSize: 4, threshold: 1_000_000 },
+ continuationToken: "continuation_test",
+ history: [],
+ sessionId: "session_parent",
+ state,
+ };
+}
+
+describe("session task index", () => {
+ const metadata = {
+ agentId: "ag_research:abcdef123456",
+ kind: "subagent" as const,
+ mode: "local" as const,
+ name: "research",
+ };
+ it("returns an empty index when the key is absent", () => {
+ expect(getSessionTaskIndex({})).toEqual([]);
+ expect(getSessionTaskIndex(undefined)).toEqual([]);
+ });
+
+ it("records a task and finds it by id", () => {
+ const session = recordSessionTask(createSession(), {
+ continuationToken: "task:token-1",
+ createdByTurnId: "turn-1",
+ metadata,
+ operationId: "operation-1",
+ taskId: "task_a",
+ taskRunId: "run-1",
+ });
+
+ expect(findSessionTaskEntry(session.state, "task_a")).toEqual({
+ continuationToken: "task:token-1",
+ createdByTurnId: "turn-1",
+ metadata,
+ operationId: "operation-1",
+ taskId: "task_a",
+ taskRunId: "run-1",
+ });
+ expect(findSessionTaskEntry(session.state, "task_other")).toBeUndefined();
+ });
+
+ it("replaces the entry on replayed creation instead of duplicating it", () => {
+ let session = recordSessionTask(createSession(), {
+ continuationToken: "task:token-1",
+ createdByTurnId: "turn-1",
+ metadata,
+ operationId: "operation-1",
+ taskId: "task_a",
+ taskRunId: "run-1",
+ });
+ session = recordSessionTask(session, {
+ continuationToken: "task:token-2",
+ createdByTurnId: "turn-1",
+ metadata,
+ operationId: "operation-1",
+ taskId: "task_a",
+ taskRunId: "run-2",
+ });
+
+ const entries = getSessionTaskIndex(session.state);
+ expect(entries).toHaveLength(1);
+ expect(entries[0]?.taskRunId).toBe("run-2");
+ });
+
+ it("retains only terminal snapshots as expired-run fallbacks", () => {
+ const base = {
+ continuationToken: "task:token-1",
+ createdByTurnId: "turn-1",
+ metadata,
+ operationId: "operation-1",
+ taskId: "task_a",
+ taskRunId: "run-1",
+ };
+ const terminalSnapshot = {
+ lastOutput: { data: "done", type: "result" as const },
+ metadata,
+ status: "completed" as const,
+ taskId: "task_a",
+ };
+
+ const session = recordSessionTask(createSession(), { ...base, terminalSnapshot });
+ expect(findSessionTaskEntry(session.state, "task_a")?.terminalSnapshot).toEqual(
+ terminalSnapshot,
+ );
+ for (const invalidSnapshot of [
+ { metadata, status: "working", taskId: "task_a" },
+ { metadata, status: "completed", taskId: "task_a" },
+ {
+ lastOutput: { data: "wrong", type: "result" },
+ metadata,
+ status: "failed",
+ taskId: "task_a",
+ },
+ {
+ lastOutput: { data: "wrong", type: "result" },
+ metadata,
+ status: "cancelled",
+ taskId: "task_a",
+ },
+ {
+ inputRequests: [{ requestId: "stale" }],
+ lastOutput: { data: "done", type: "result" },
+ metadata,
+ status: "completed",
+ taskId: "task_a",
+ },
+ { ...terminalSnapshot, taskId: "task_other" },
+ ]) {
+ expect(() =>
+ getSessionTaskIndex({
+ [SESSION_TASKS_STATE_KEY]: {
+ tasks: [{ ...base, terminalSnapshot: invalidSnapshot }],
+ },
+ }),
+ ).toThrow(`Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}"`);
+ }
+ });
+
+ it("throws on a corrupt index instead of treating it as absent", () => {
+ expect(() =>
+ getSessionTaskIndex({ [SESSION_TASKS_STATE_KEY]: { tasks: [{ taskId: 42 }] } }),
+ ).toThrow(`Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}"`);
+ });
+});
+
+describe("deriveTaskId", () => {
+ it("is deterministic for the same originating call and distinct otherwise", () => {
+ const input = { callId: "call-1", parentSessionId: "session-1", parentTurnId: "turn-1" };
+
+ expect(deriveTaskId(input)).toBe(deriveTaskId(input));
+ expect(deriveTaskId(input)).toMatch(/^task_[0-9a-f]{24}$/);
+ expect(deriveTaskId({ ...input, callId: "call-2" })).not.toBe(deriveTaskId(input));
+ });
+});
diff --git a/packages/eve/src/tasks/session-index.ts b/packages/eve/src/tasks/session-index.ts
new file mode 100644
index 000000000..77de570c8
--- /dev/null
+++ b/packages/eve/src/tasks/session-index.ts
@@ -0,0 +1,212 @@
+import { z } from "#compiled/zod/index.js";
+
+import type { HarnessSession, SessionStateMap } from "#harness/types.js";
+import type { JsonValue } from "#shared/json.js";
+import type { TaskMetadata, TaskView } from "#tasks/types.js";
+
+/**
+ * Session-state key for the parent's live-task index.
+ *
+ * The parent session stores only this index; the mutable task record
+ * lives in the dedicated durable task run. The PR #1190 spike found the
+ * session-state boundary unworkable for task state itself: session state
+ * threads through step results, while callback routes and child
+ * executors must update tasks without holding the current snapshot.
+ */
+export const SESSION_TASKS_STATE_KEY = "eve.tasks";
+
+/**
+ * One task owned by this session. Immutable model-safe metadata keeps the
+ * task-to-agent join available before the task run publishes its first view.
+ *
+ * `continuationToken` is the private routing credential for the task run's
+ * inbound hook. It must never render into model context, history, task
+ * snapshots, or compaction summaries — the model addresses tasks by
+ * `taskId` only, and lookup verifies ownership through this index.
+ */
+export interface SessionTaskIndexEntry {
+ readonly taskId: string;
+ readonly taskRunId: string;
+ /** Immutable fallback once the owning workflow run expires. */
+ readonly terminalSnapshot?: TaskView;
+ readonly continuationToken: string;
+ readonly createdByStepIndex?: number;
+ readonly createdByTurnId: string;
+ readonly metadata: TaskMetadata;
+ readonly operationId: string;
+}
+
+const taskMetadataSchema: z.ZodType<TaskMetadata> = z.strictObject({
+ agentId: z.string().min(1),
+ kind: z.literal("subagent"),
+ mode: z.enum(["local", "remote"]),
+ name: z.string().min(1),
+});
+
+const taskViewBaseShape = {
+ executor: z
+ .strictObject({
+ childSessionId: z.string().min(1).optional(),
+ childTurnId: z.string().min(1).optional(),
+ lifecycle: z.enum(["parked", "terminal"]).optional(),
+ })
+ .optional(),
+ metadata: taskMetadataSchema,
+ taskId: z.string().min(1),
+ usage: z
+ .strictObject({
+ cacheReadTokens: z.number().nonnegative(),
+ cacheWriteTokens: z.number().nonnegative(),
+ inputTokens: z.number().nonnegative(),
+ outputTokens: z.number().nonnegative(),
+ })
+ .optional(),
+};
+
+/**
+ * Terminal snapshots only, on purpose: the index caches a snapshot solely as
+ * the expired-run fallback, and the discriminated arms encode the terminal
+ * status/output invariants structurally (strict objects reject
+ * `inputRequests` and mismatched outputs).
+ */
+const taskViewSchema: z.ZodType<TaskView> = z.discriminatedUnion("status", [
+ z.strictObject({
+ ...taskViewBaseShape,
+ lastOutput: z.strictObject({ data: z.custom<JsonValue>(), type: z.literal("result") }),
+ status: z.literal("completed"),
+ }),
+ z.strictObject({
+ ...taskViewBaseShape,
+ lastOutput: z.strictObject({ data: z.custom<JsonValue>(), type: z.literal("error") }),
+ status: z.literal("failed"),
+ }),
+ z.strictObject({ ...taskViewBaseShape, status: z.literal("cancelled") }),
+]);
+
+const sessionTaskIndexEntrySchema: z.ZodType<SessionTaskIndexEntry> = z.strictObject({
+ continuationToken: z.string().min(1),
+ createdByStepIndex: z.number().int().nonnegative().optional(),
+ createdByTurnId: z.string().min(1),
+ metadata: taskMetadataSchema,
+ operationId: z.string().min(1),
+ taskId: z.string().min(1),
+ taskRunId: z.string().min(1),
+ terminalSnapshot: taskViewSchema.optional(),
+});
+
+const sessionTaskIndexSchema = z
+ .strictObject({
+ tasks: z.array(sessionTaskIndexEntrySchema),
+ })
+ .refine(
+ (index) => new Set(index.tasks.map((entry) => entry.taskId)).size === index.tasks.length,
+ {
+ message: "Task ids must be unique.",
+ },
+ )
+ .refine(
+ (index) =>
+ index.tasks.every(
+ (entry) =>
+ entry.terminalSnapshot === undefined ||
+ (entry.terminalSnapshot.taskId === entry.taskId &&
+ sameTaskMetadata(entry.terminalSnapshot.metadata, entry.metadata)),
+ ),
+ { message: "Cached terminal snapshots must match their task index entry." },
+ );
+
+interface SessionTaskIndex {
+ readonly tasks: readonly SessionTaskIndexEntry[];
+}
+
+/**
+ * Reads and validates the task index from session state.
+ *
+ * A present but invalid index throws: treating corruption as absence
+ * would silently orphan every live task's routing credential.
+ */
+export function getSessionTaskIndex(
+ state: SessionStateMap | undefined,
+): readonly SessionTaskIndexEntry[] {
+ const raw = state?.[SESSION_TASKS_STATE_KEY];
+ if (raw === undefined) {
+ return [];
+ }
+ const parsed = sessionTaskIndexSchema.safeParse(raw);
+ if (!parsed.success) {
+ throw new Error(
+ `Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}": ${parsed.error.message}`,
+ );
+ }
+ return parsed.data.tasks;
+}
+
+/** Caches one terminal snapshot beside its task-run address. */
+export function cacheTerminalTaskSnapshot(
+ state: SessionStateMap | undefined,
+ snapshot: TaskView,
+): SessionStateMap | undefined {
+ if (!isValidTerminalSnapshot(snapshot)) {
+ throw new Error(`Cannot cache invalid terminal task "${snapshot.taskId}".`);
+ }
+ const entries = getSessionTaskIndex(state);
+ const index = entries.findIndex((entry) => entry.taskId === snapshot.taskId);
+ if (index < 0) return state;
+ if (!sameTaskMetadata(entries[index]!.metadata, snapshot.metadata)) {
+ throw new Error(`Task snapshot metadata does not match index entry "${snapshot.taskId}".`);
+ }
+ const tasks = [...entries];
+ tasks[index] = { ...tasks[index]!, terminalSnapshot: snapshot };
+ return { ...state, [SESSION_TASKS_STATE_KEY]: { tasks } };
+}
+
+function isValidTerminalSnapshot(view: TaskView): boolean {
+ if (view.inputRequests !== undefined) return false;
+ switch (view.status) {
+ case "completed":
+ return view.lastOutput?.type === "result";
+ case "failed":
+ return view.lastOutput?.type === "error";
+ case "cancelled":
+ return view.lastOutput === undefined;
+ // "input_required" is already excluded: its arm requires `inputRequests`.
+ case "working":
+ return false;
+ }
+}
+
+function sameTaskMetadata(left: TaskMetadata, right: TaskMetadata): boolean {
+ return (
+ left.agentId === right.agentId &&
+ left.kind === right.kind &&
+ left.mode === right.mode &&
+ left.name === right.name
+ );
+}
+
+/** Finds one owned task; `undefined` enforces parent-session ownership. */
+export function findSessionTaskEntry(
+ state: SessionStateMap | undefined,
+ taskId: string,
+): SessionTaskIndexEntry | undefined {
+ return getSessionTaskIndex(state).find((entry) => entry.taskId === taskId);
+}
+
+/**
+ * Records one task, replacing any entry with the same id so replayed
+ * creation for the same originating call stays idempotent.
+ */
+export function recordSessionTask(
+ session: HarnessSession,
+ entry: SessionTaskIndexEntry,
+): HarnessSession {
+ const existing = getSessionTaskIndex(session.state);
+ const tasks = [...existing.filter((candidate) => candidate.taskId !== entry.taskId), entry];
+ return {
+ ...session,
+ state: {
+ ...session.state,
+ [SESSION_TASKS_STATE_KEY]: { tasks } satisfies SessionTaskIndex,
+ },
+ };
+}
diff --git a/packages/eve/src/tasks/task-id.ts b/packages/eve/src/tasks/task-id.ts
new file mode 100644
index 000000000..eda19f5bb
--- /dev/null
+++ b/packages/eve/src/tasks/task-id.ts
@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+
+import { deriveAgentOperationId } from "#harness/handles/operation-id.js";
+
+/**
+ * Derives the stable task id for one originating subagent call.
+ *
+ * Reuses the agent-handle operation-id derivation —
+ * `hash(parentSessionId, parentTurnId, callId)` — so replayed creation
+ * for the same call yields the same task without new machinery, and a
+ * task can never be confused with a child session id or continuation
+ * token.
+ *
+ * Lives apart from the pure task modules because the derivation needs
+ * `node:crypto`, which workflow bodies reject; ids are only ever minted
+ * inside dispatch steps.
+ */
+export function deriveTaskId(input: {
+ readonly callId: string;
+ readonly parentSessionId: string;
+ readonly parentTurnId: string;
+}): string {
+ return `task_${deriveAgentOperationId(input).slice(0, 24)}`;
+}
+
+/**
+ * Derives the task run's private continuation token.
+ *
+ * Deterministic on purpose: a durable replay of the dispatch step must
+ * re-derive the same token so the duplicate task run loses the hook
+ * claim and exits instead of splitting the lifecycle across two runs.
+ * Unguessable in practice: the parent session's continuation token is
+ * itself a private capability, and the derived token never renders to
+ * the model.
+ */
+export function deriveTaskContinuationToken(input: {
+ readonly parentContinuationToken: string;
+ readonly taskId: string;
+}): string {
+ return `task:${input.taskId}:${createHash("sha256")
+ .update(`${input.taskId}\0${input.parentContinuationToken}`)
+ .digest("hex")
+ .slice(0, 32)}`;
+}
+
+/** Reads the non-secret task id embedded in a private task continuation token. */
+export function readTaskIdFromContinuationToken(token: string): string | undefined {
+ const match = /^task:(task_[^:]+):[a-f0-9]{32}$/.exec(token);
+ return match?.[1];
+}
diff --git a/packages/eve/src/tasks/transitions.test.ts b/packages/eve/src/tasks/transitions.test.ts
new file mode 100644
index 000000000..7a92f5151
--- /dev/null
+++ b/packages/eve/src/tasks/transitions.test.ts
@@ -0,0 +1,283 @@
+import { describe, expect, it } from "vitest";
+
+import { applyTaskTransition } from "#tasks/transitions.js";
+import type { TaskCommand, TaskStatus, TaskView } from "#tasks/types.js";
+
+function createView(status: TaskStatus, overrides: Partial<TaskView> = {}): TaskView {
+ // Cast on purpose: tests probe the transition function's runtime guards
+ // with shapes the TaskView union already forbids (e.g. terminal, no output).
+ return {
+ metadata: {
+ agentId: "ag_research:abcdef123456",
+ kind: "subagent",
+ mode: "local",
+ name: "research",
+ },
+ status,
+ taskId: "task_abc123",
+ ...overrides,
+ } as TaskView;
+}
+
+const TERMINAL_STATUSES: readonly TaskStatus[] = ["completed", "failed", "cancelled"];
+const ALL_COMMANDS: readonly TaskCommand[] = [
+ { data: { answer: 42 }, kind: "complete" },
+ { data: { message: "boom" }, kind: "fail" },
+ { kind: "cancel" },
+ { inputRequests: [{ question: "which?" }], kind: "require-input" },
+ { kind: "ready" },
+ { kind: "answered", requestIds: ["req-1"] },
+];
+
+describe("applyTaskTransition", () => {
+ it("completes a working task with a result output", () => {
+ const result = applyTaskTransition(createView("working"), {
+ data: { answer: 42 },
+ kind: "complete",
+ });
+
+ expect(result.outcome).toBe("accepted");
+ expect(result.view.status).toBe("completed");
+ expect(result.view.lastOutput).toEqual({ data: { answer: 42 }, type: "result" });
+ });
+
+ it("retains reported child usage on the terminal snapshot only", () => {
+ const usage = { cacheReadTokens: 1, cacheWriteTokens: 2, inputTokens: 300, outputTokens: 40 };
+ for (const command of [
+ { data: "done", kind: "complete", usage },
+ { data: "boom", kind: "fail", usage },
+ { kind: "cancel", usage },
+ ] as const) {
+ const result = applyTaskTransition(createView("working"), command);
+ expect(result.outcome).toBe("accepted");
+ expect(result.view.usage).toEqual(usage);
+ }
+
+ const withoutUsage = applyTaskTransition(createView("working"), {
+ data: "done",
+ kind: "complete",
+ });
+ expect(withoutUsage.view.usage).toBeUndefined();
+
+ const blocked = applyTaskTransition(createView("working"), {
+ inputRequests: [{ question: "which?", requestId: "req-1" }],
+ kind: "require-input",
+ });
+ expect(blocked.view.usage).toBeUndefined();
+ });
+
+ it("fails a working task and carries the error as its output", () => {
+ const result = applyTaskTransition(createView("working"), {
+ data: { message: "boom" },
+ kind: "fail",
+ });
+
+ expect(result.outcome).toBe("accepted");
+ expect(result.view.status).toBe("failed");
+ expect(result.view.lastOutput).toEqual({ data: { message: "boom" }, type: "error" });
+ });
+
+ it("moves working to input_required carrying the outstanding batch", () => {
+ const result = applyTaskTransition(createView("working"), {
+ inputRequests: [{ question: "which region?", requestId: "req-1" }],
+ kind: "require-input",
+ });
+
+ expect(result.outcome).toBe("accepted");
+ expect(result.view.status).toBe("input_required");
+ expect(result.view.inputRequests).toEqual([{ question: "which region?", requestId: "req-1" }]);
+ });
+
+ it("rejects empty, unidentified, and duplicate input request batches", () => {
+ for (const inputRequests of [
+ [],
+ [{ question: "missing id" }],
+ [
+ { question: "first", requestId: "same" },
+ { question: "second", requestId: "same" },
+ ],
+ ]) {
+ const result = applyTaskTransition(createView("working"), {
+ inputRequests,
+ kind: "require-input",
+ });
+ expect(result.outcome).toBe("rejected");
+ expect(result.view.status).toBe("working");
+ }
+ });
+
+ it("returns input_required to working once the whole batch is answered", () => {
+ const blocked = applyTaskTransition(createView("working"), {
+ inputRequests: [{ question: "which region?", requestId: "req-1" }],
+ kind: "require-input",
+ });
+ expect(blocked.outcome).toBe("accepted");
+
+ const result = applyTaskTransition(blocked.view, { kind: "answered", requestIds: ["req-1"] });
+
+ expect(result.outcome).toBe("accepted");
+ expect(result.view.status).toBe("working");
+ expect(result.view.inputRequests).toBeUndefined();
+ });
+
+ it("keeps the task blocked on the remainder of a partly answered batch", () => {
+ const blocked = applyTaskTransition(createView("working"), {
+ inputRequests: [
+ { question: "which region?", requestId: "req-1" },
+ { question: "which size?", requestId: "req-2" },
+ ],
+ kind: "require-input",
+ });
+ expect(blocked.outcome).toBe("accepted");
+
+ const result = applyTaskTransition(blocked.view, { kind: "answered", requestIds: ["req-1"] });
+
+ expect(result.outcome).toBe("accepted");
+ expect(result.view.status).toBe("input_required");
+ expect(result.view.inputRequests).toEqual([{ question: "which size?", requestId: "req-2" }]);
+ });
+
+ it("ignores an answer to a batch that was already replaced", () => {
+ const first = applyTaskTransition(createView("working"), {
+ inputRequests: [{ question: "first", requestId: "req-1" }],
+ kind: "require-input",
+ });
+ const second = applyTaskTransition(first.view, {
+ inputRequests: [{ question: "second", requestId: "req-2" }],
+ kind: "require-input",
+ });
+ expect(second.outcome).toBe("accepted");
+
+ const stale = applyTaskTransition(second.view, { kind: "answered", requestIds: ["req-1"] });
+
+ expect(stale.outcome).toBe("noop");
+ expect(stale.view.status).toBe("input_required");
+ expect(stale.view.inputRequests).toEqual([{ question: "second", requestId: "req-2" }]);
+ });
+
+ it("replaces the outstanding batch on repeated require-input", () => {
+ const first = applyTaskTransition(createView("working"), {
+ inputRequests: [{ question: "first", requestId: "req-1" }],
+ kind: "require-input",
+ });
+ expect(first.outcome).toBe("accepted");
+
+ const second = applyTaskTransition(first.view, {
+ inputRequests: [{ question: "second", requestId: "req-2" }],
+ kind: "require-input",
+ });
+
+ expect(second.outcome).toBe("accepted");
+ expect(second.view.inputRequests).toEqual([{ question: "second", requestId: "req-2" }]);
+ });
+
+ it("completes and cancels an input_required task", () => {
+ const blocked = applyTaskTransition(createView("working"), {
+ inputRequests: [{ question: "which?", requestId: "req-1" }],
+ kind: "require-input",
+ });
+ expect(blocked.outcome).toBe("accepted");
+
+ const completed = applyTaskTransition(blocked.view, { data: "done", kind: "complete" });
+ expect(completed.outcome).toBe("accepted");
+ expect(completed.view.status).toBe("completed");
+
+ const cancelled = applyTaskTransition(blocked.view, { kind: "cancel" });
+ expect(cancelled.outcome).toBe("accepted");
+ expect(cancelled.view.status).toBe("cancelled");
+ });
+
+ it("treats an answer to a working task as a noop", () => {
+ const result = applyTaskTransition(createView("working"), {
+ kind: "answered",
+ requestIds: ["req-1"],
+ });
+
+ expect(result.outcome).toBe("noop");
+ expect(result.view.status).toBe("working");
+ });
+
+ it("rejects a late completion after cancellation", () => {
+ const cancelled = applyTaskTransition(createView("working"), { kind: "cancel" });
+ expect(cancelled.outcome).toBe("accepted");
+
+ const late = applyTaskTransition(cancelled.view, { data: "too late", kind: "complete" });
+
+ expect(late.outcome).toBe("rejected");
+ expect(late.view.status).toBe("cancelled");
+ expect(late.view.lastOutput).toBeUndefined();
+ });
+
+ it("treats repeated cancellation as an idempotent noop", () => {
+ const cancelled = applyTaskTransition(createView("working"), { kind: "cancel" });
+ expect(cancelled.outcome).toBe("accepted");
+
+ const again = applyTaskTransition(cancelled.view, { kind: "cancel" });
+
+ expect(again.outcome).toBe("noop");
+ expect(again.view.status).toBe("cancelled");
+ });
+
+ it.each(TERMINAL_STATUSES)("keeps %s final against every non-cancel command", (status) => {
+ const view = createView(status);
+ for (const command of ALL_COMMANDS) {
+ if (command.kind === "cancel" && status === "cancelled") continue;
+ const result = applyTaskTransition(view, command);
+ expect(result.outcome).toBe("rejected");
+ expect(result.view).toBe(view);
+ }
+ });
+
+ it("rejects cancel on completed and failed tasks", () => {
+ for (const status of ["completed", "failed"] as const) {
+ const result = applyTaskTransition(createView(status), { kind: "cancel" });
+ expect(result.outcome).toBe("rejected");
+ }
+ });
+
+ it("is deterministic for replayed commands", () => {
+ const view = createView("working");
+ const command: TaskCommand = { data: { answer: 1 }, kind: "complete" };
+
+ const first = applyTaskTransition(view, command);
+ const second = applyTaskTransition(view, command);
+
+ expect(first).toEqual(second);
+ });
+
+ it("never rebinds a task turn to a different child session", () => {
+ const result = applyTaskTransition(
+ createView("working", {
+ executor: { childSessionId: "child-session-1" },
+ metadata: {
+ agentId: "ag_research:abcdef123456",
+ kind: "subagent",
+ mode: "local",
+ name: "research",
+ },
+ }),
+ {
+ childSessionId: "other-child",
+ childTurnId: "turn_9",
+ kind: "start-turn",
+ taskId: "task_abc123",
+ },
+ );
+
+ expect(result.outcome).toBe("rejected");
+ expect(result.view.executor?.childSessionId).toBe("child-session-1");
+ });
+
+ it("retains late usage on a terminal task without reviving it", () => {
+ const usage = { cacheReadTokens: 1, cacheWriteTokens: 2, inputTokens: 300, outputTokens: 40 };
+ const cancelled = applyTaskTransition(createView("working"), { kind: "cancel" });
+ if (cancelled.outcome !== "accepted") throw new Error("Expected cancellation to commit.");
+
+ const result = applyTaskTransition(cancelled.view, { kind: "settle-executor", usage });
+
+ expect(result).toEqual({
+ outcome: "accepted",
+ view: { ...cancelled.view, executor: { lifecycle: "terminal" }, usage },
+ });
+ });
+});
diff --git a/packages/eve/src/tasks/transitions.ts b/packages/eve/src/tasks/transitions.ts
new file mode 100644
index 000000000..c8bcac98b
--- /dev/null
+++ b/packages/eve/src/tasks/transitions.ts
@@ -0,0 +1,247 @@
+import type {
+ TaskCommand,
+ TaskInputRequest,
+ TaskOutput,
+ TaskUsage,
+ TaskView,
+} from "#tasks/types.js";
+import { isTerminalTaskStatus, readTaskInputRequestId } from "#tasks/types.js";
+
+/**
+ * Outcome of applying one command to a task snapshot.
+ *
+ * - `accepted`: the state changed; the new view must be appended.
+ * - `noop`: the command is recognized and benign (idempotent cancel,
+ * stale answer); nothing changed and nothing is appended.
+ * - `rejected`: the command is invalid for the current status; the
+ * reason is diagnostic only.
+ */
+export type TaskTransitionResult =
+ | { readonly outcome: "accepted"; readonly view: TaskView }
+ | { readonly outcome: "noop"; readonly view: TaskView }
+ | { readonly outcome: "rejected"; readonly view: TaskView; readonly reason: string };
+
+/**
+ * Pure transition function for the task lifecycle:
+ *
+ * ```text
+ * working <-> input_required
+ * | |
+ * +-----> completed
+ * +-----> failed
+ * +-----> cancelled
+ * ```
+ *
+ * Terminal states are final: a late child result can never revive a
+ * cancelled task, and repeated cancellation is idempotent. The durable
+ * task run is the only caller that persists accepted views, which is
+ * what serializes competing completion, cancellation, and input
+ * transitions.
+ */
+/**
+ * Builds the settled snapshot for one terminal command, carrying the
+ * child's lifecycle verdict and reported usage when present. Usage is
+ * retention-only: nothing folds it into parent budgets yet.
+ */
+function terminalView(
+ view: TaskView,
+ command: Extract<TaskCommand, { kind: "complete" | "fail" | "cancel" }>,
+ settled:
+ | {
+ readonly lastOutput: Extract<TaskOutput, { type: "result" }>;
+ readonly status: "completed";
+ }
+ | { readonly lastOutput: Extract<TaskOutput, { type: "error" }>; readonly status: "failed" }
+ | { readonly status: "cancelled" },
+): TaskView {
+ const base: Pick<TaskView, "executor" | "metadata" | "taskId"> & { usage?: TaskUsage } = {
+ executor:
+ command.lifecycle === undefined
+ ? view.executor
+ : { ...view.executor, lifecycle: command.lifecycle },
+ metadata: view.metadata,
+ taskId: view.taskId,
+ };
+ if (command.usage !== undefined) base.usage = command.usage;
+ switch (settled.status) {
+ case "completed":
+ return { ...base, lastOutput: settled.lastOutput, status: "completed" };
+ case "failed":
+ return { ...base, lastOutput: settled.lastOutput, status: "failed" };
+ case "cancelled":
+ return { ...base, status: "cancelled" };
+ }
+}
+
+export function applyTaskTransition(view: TaskView, command: TaskCommand): TaskTransitionResult {
+ if (isTerminalTaskStatus(view.status)) {
+ if (command.kind === "settle-executor") {
+ const executor = { ...view.executor, lifecycle: "terminal" as const };
+ if (sameUsage(view.usage, command.usage) && view.executor?.lifecycle === "terminal") {
+ return { outcome: "noop", view };
+ }
+ const next = { ...view, executor };
+ return {
+ outcome: "accepted",
+ view: command.usage === undefined ? next : { ...next, usage: command.usage },
+ };
+ }
+ if (command.kind === "cancel" && view.status === "cancelled") {
+ return { outcome: "noop", view };
+ }
+
+ return {
+ outcome: "rejected",
+ reason: `Task "${view.taskId}" is already ${view.status}; "${command.kind}" cannot change a terminal task.`,
+ view,
+ };
+ }
+
+ switch (command.kind) {
+ case "complete":
+ return {
+ outcome: "accepted",
+ view: terminalView(view, command, {
+ lastOutput: { data: command.data, type: "result" },
+ status: "completed",
+ }),
+ };
+ case "fail":
+ return {
+ outcome: "accepted",
+ view: terminalView(view, command, {
+ lastOutput: { data: command.data, type: "error" },
+ status: "failed",
+ }),
+ };
+ case "cancel":
+ return {
+ outcome: "accepted",
+ view: terminalView(view, command, { status: "cancelled" }),
+ };
+ case "settle-executor":
+ return {
+ outcome: "rejected",
+ reason: `Task "${view.taskId}" is not terminal; usage settles with its terminal command.`,
+ view,
+ };
+ case "require-input":
+ if (!isValidInputRequestBatch(command.inputRequests)) {
+ return {
+ outcome: "rejected",
+ reason: `Task "${view.taskId}" received an invalid input request batch.`,
+ view,
+ };
+ }
+ return {
+ outcome: "accepted",
+ view: {
+ inputRequests: command.inputRequests,
+ executor: view.executor,
+ metadata: view.metadata,
+ status: "input_required",
+ taskId: view.taskId,
+ },
+ };
+ case "ready":
+ // The readiness command is also the barrier that releases a fast,
+ // pre-acknowledgement HITL batch, so the workflow must observe it.
+ return { outcome: "accepted", view };
+ case "answered": {
+ if (view.status !== "input_required") {
+ return { outcome: "noop", view };
+ }
+
+ const answered = new Set(command.requestIds);
+ const outstanding = view.inputRequests ?? [];
+ const remaining = outstanding.filter((request) => {
+ const requestId = readTaskInputRequestId(request);
+ return requestId === undefined || !answered.has(requestId);
+ });
+ // An answer that matches nothing outstanding is stale: the batch
+ // it was written against was already cleared or replaced. Leaving
+ // the current batch intact is what stops it from unblocking a
+ // question the human never saw.
+ if (remaining.length === outstanding.length) {
+ return { outcome: "noop", view };
+ }
+ if (remaining.length > 0) {
+ return {
+ outcome: "accepted",
+ view: {
+ inputRequests: remaining,
+ executor: view.executor,
+ metadata: view.metadata,
+ status: "input_required",
+ taskId: view.taskId,
+ },
+ };
+ }
+
+ return {
+ outcome: "accepted",
+ view: {
+ executor: view.executor,
+ metadata: view.metadata,
+ status: "working",
+ taskId: view.taskId,
+ },
+ };
+ }
+ case "start-turn": {
+ if (command.taskId !== view.taskId) {
+ return {
+ outcome: "rejected",
+ reason: `Task turn identity "${command.taskId}" does not match "${view.taskId}".`,
+ view,
+ };
+ }
+ if (
+ view.executor?.childSessionId !== undefined &&
+ view.executor.childSessionId !== command.childSessionId
+ ) {
+ return {
+ outcome: "rejected",
+ reason: `Task child session "${command.childSessionId}" does not match "${view.executor.childSessionId}".`,
+ view,
+ };
+ }
+ if (
+ view.executor?.childSessionId === command.childSessionId &&
+ view.executor.childTurnId === command.childTurnId
+ ) {
+ return { outcome: "noop", view };
+ }
+ return {
+ outcome: "accepted",
+ view: {
+ ...view,
+ executor: {
+ ...view.executor,
+ childSessionId: command.childSessionId,
+ childTurnId: command.childTurnId,
+ },
+ },
+ };
+ }
+ }
+}
+
+function isValidInputRequestBatch(requests: readonly TaskInputRequest[]): boolean {
+ if (requests.length === 0) return false;
+ const ids = requests.map(readTaskInputRequestId);
+ return (
+ ids.every((id): id is string => id !== undefined && id.length > 0) &&
+ new Set(ids).size === ids.length
+ );
+}
+
+function sameUsage(left: TaskUsage | undefined, right: TaskUsage | undefined): boolean {
+ if (left === undefined || right === undefined) return left === right;
+ return (
+ left?.cacheReadTokens === right.cacheReadTokens &&
+ left.cacheWriteTokens === right.cacheWriteTokens &&
+ left.inputTokens === right.inputTokens &&
+ left.outputTokens === right.outputTokens
+ );
+}
diff --git a/packages/eve/src/tasks/types.ts b/packages/eve/src/tasks/types.ts
new file mode 100644
index 000000000..f765ea3ac
--- /dev/null
+++ b/packages/eve/src/tasks/types.ts
@@ -0,0 +1,336 @@
+import type { JsonValue } from "#shared/json.js";
+import type { SubagentAuthorizationEvent } from "#channel/types.js";
+
+/**
+ * Task lifecycle contract for `experimental.tasks`.
+ *
+ * A task is one durable unit of delegated work owned by a parent session.
+ * The durable task run is the single writer for lifecycle transitions
+ * (see `#execution/tasks/run-task-workflow.js`); every other path submits
+ * commands and reads snapshots. This module is dependency-free on
+ * purpose: it is bundled into workflow bodies, which reject Node.js
+ * builtins and heavyweight validators.
+ */
+
+/**
+ * Task lifecycle status.
+ *
+ * `completed`, `failed`, and `cancelled` are terminal and final.
+ * `input_required` is not terminal but is ready for parent action; the
+ * child must wake its parent rather than deadlock while waiting for input.
+ */
+export type TaskStatus = "working" | "input_required" | "completed" | "failed" | "cancelled";
+
+/**
+ * Immutable identity of the delegated work behind a task.
+ *
+ * `agentId` is parent-controlled and exists before the child acknowledges its
+ * private address, so the durable task can bind to persistent identity before
+ * the dispatch side effect runs.
+ */
+export interface TaskMetadata {
+ /** Stable model-visible identity of the persistent child session. */
+ readonly agentId: string;
+ readonly kind: "subagent";
+ readonly mode: "local" | "remote";
+ /** Authored subagent name the parent dispatched. */
+ readonly name: string;
+}
+
+/** Private executor state retained for cancellation and address reconciliation. */
+export interface TaskExecutorState {
+ readonly childSessionId?: string;
+ readonly childTurnId?: string;
+ readonly lifecycle?: "parked" | "terminal";
+}
+
+/**
+ * Terminal task output. Failure is the state (`failed`); the `error`
+ * output is its consequence — a `failed` task always carries one.
+ * This intentionally diverges from MCP, which reserves `failed` for
+ * protocol-level errors.
+ */
+export type TaskOutput =
+ | { readonly type: "result"; readonly data: JsonValue }
+ | { readonly type: "error"; readonly data: JsonValue };
+
+/**
+ * One outstanding request forwarded from a blocked child. Carried
+ * opaquely: the task layer routes the batch, the input contract owns
+ * its shape.
+ */
+export type TaskInputRequest = JsonValue;
+
+/**
+ * Provider token usage a child turn reported. Structural on purpose: it
+ * mirrors `TokenUsage` (#shared/token-usage.js) without importing its
+ * zod-backed module into a workflow-bundled file.
+ */
+export interface TaskUsage {
+ readonly cacheReadTokens: number;
+ readonly cacheWriteTokens: number;
+ readonly inputTokens: number;
+ readonly outputTokens: number;
+}
+
+/**
+ * Validates one wire-carried usage value into {@link TaskUsage}.
+ * Anything malformed is dropped rather than rejected: retention is
+ * best-effort and must never fail a lifecycle transition.
+ */
+export function readTaskUsage(value: unknown): TaskUsage | undefined {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+ const cacheReadTokens = readUsageAxis(value, "cacheReadTokens");
+ const cacheWriteTokens = readUsageAxis(value, "cacheWriteTokens");
+ const inputTokens = readUsageAxis(value, "inputTokens");
+ const outputTokens = readUsageAxis(value, "outputTokens");
+ if (
+ cacheReadTokens === undefined ||
+ cacheWriteTokens === undefined ||
+ inputTokens === undefined ||
+ outputTokens === undefined
+ ) {
+ return undefined;
+ }
+ return { cacheReadTokens, cacheWriteTokens, inputTokens, outputTokens };
+}
+
+function readUsageAxis(value: object, key: string): number | undefined {
+ const field = Reflect.get(value, key);
+ return typeof field === "number" && Number.isFinite(field) && field >= 0 ? field : undefined;
+}
+
+/**
+ * One human answer to an outstanding request. Structural on purpose: it
+ * mirrors the input contract's `InputResponse` without importing its
+ * zod-backed module into a workflow-bundled file.
+ */
+export interface TaskInputResponse {
+ readonly optionId?: string;
+ readonly requestId: string;
+ readonly text?: string;
+}
+
+/**
+ * Request id of the synthetic entry that blocks a task while its child
+ * waits for authorization. Giving the block an id keeps its release
+ * bound to the same entry, so completing authorization can never clear
+ * an unrelated request batch the child raised in the meantime.
+ */
+export const TASK_AUTHORIZATION_REQUEST_ID = "task:authorization";
+
+/** Reads the `requestId` of one opaque outstanding request. */
+export function readTaskInputRequestId(request: TaskInputRequest): string | undefined {
+ if (request === null || typeof request !== "object" || Array.isArray(request)) return undefined;
+ const requestId = Reflect.get(request, "requestId");
+ return typeof requestId === "string" ? requestId : undefined;
+}
+
+/** Fields shared by every durable task snapshot. */
+interface TaskViewBase {
+ readonly taskId: string;
+ readonly metadata: TaskMetadata;
+ /** Private executor state; deliberately excluded from model-visible JSON. */
+ readonly executor?: TaskExecutorState;
+ /**
+ * Provider usage the child reported at settlement; present when the
+ * terminal command carried it. Retained for later accounting only —
+ * budgets stay best-effort until a reservation model lands — and
+ * deliberately excluded from model-visible task views (tasks/json.ts).
+ */
+ readonly usage?: TaskUsage;
+}
+
+/**
+ * Full durable task snapshot discriminated by lifecycle status.
+ *
+ * The task run appends one per accepted command; readers always observe a
+ * complete view, never a delta. A snapshot never contains routing credentials,
+ * continuation tokens, or authorization capabilities.
+ *
+ * Completed and failed tasks carry their corresponding output, cancelled
+ * tasks carry no output, and only input-required tasks carry requests.
+ */
+export type TaskView = TaskViewBase &
+ (
+ | {
+ readonly status: "working";
+ readonly inputRequests?: never;
+ readonly lastOutput?: never;
+ }
+ | {
+ readonly status: "input_required";
+ readonly inputRequests: readonly TaskInputRequest[];
+ readonly lastOutput?: never;
+ }
+ | {
+ readonly status: "completed";
+ readonly inputRequests?: never;
+ readonly lastOutput: Extract<TaskOutput, { type: "result" }>;
+ }
+ | {
+ readonly status: "failed";
+ readonly inputRequests?: never;
+ readonly lastOutput: Extract<TaskOutput, { type: "error" }>;
+ }
+ | {
+ readonly status: "cancelled";
+ readonly inputRequests?: never;
+ readonly lastOutput?: never;
+ }
+ );
+
+/** Commands accepted by the durable task run's transition function. */
+export type TaskCommand =
+ | {
+ readonly kind: "complete";
+ readonly data: JsonValue;
+ readonly lifecycle?: "parked" | "terminal";
+ readonly usage?: TaskUsage;
+ }
+ | {
+ readonly kind: "fail";
+ readonly data: JsonValue;
+ readonly lifecycle?: "parked" | "terminal";
+ readonly usage?: TaskUsage;
+ }
+ | {
+ readonly kind: "cancel";
+ readonly lifecycle?: "parked" | "terminal";
+ readonly usage?: TaskUsage;
+ }
+ /** Retains a late executor settlement without changing task terminal status. */
+ | { readonly kind: "settle-executor"; readonly usage?: TaskUsage }
+ | { readonly kind: "require-input"; readonly inputRequests: readonly TaskInputRequest[] }
+ | { readonly kind: "ready" }
+ /**
+ * Clears the listed requests from the outstanding batch. Bound to
+ * ids rather than unbound like the former `resume`, so an answer can
+ * only ever release the batch it was written against.
+ */
+ | { readonly kind: "answered"; readonly requestIds: readonly string[] }
+ | {
+ readonly kind: "start-turn";
+ readonly childSessionId: string;
+ readonly childTurnId: string;
+ readonly taskId: string;
+ };
+
+/** Hook payload envelope commanding a durable task run. */
+export interface TaskCommandHookPayload {
+ readonly kind: "task-command";
+ readonly command: TaskCommand;
+}
+
+/**
+ * Structural shapes of the child wire payloads a task run consumes.
+ *
+ * These mirror the existing parent-notification contracts (the local
+ * `notifyDelegatedParentStep`, the subagent adapter's HITL forwarding,
+ * and the remote callback route) without importing their zod-backed
+ * modules: this file is bundled into workflow bodies. The wire itself
+ * is unchanged — delegated dispatch only points it at the task run's
+ * hook instead of the parent turn's inbox.
+ */
+export interface TaskInboundChildResult {
+ readonly kind: "runtime-action-result";
+ readonly results: readonly {
+ readonly isError?: boolean;
+ readonly outcome?: {
+ readonly kind: "parked" | "terminal";
+ readonly result:
+ | { readonly kind: "succeeded"; readonly output: JsonValue }
+ | { readonly error: JsonValue; readonly kind: "failed" }
+ | { readonly kind: "cancelled" };
+ /**
+ * Provider usage this turn added. Retained on the terminal task
+ * snapshot ({@link TaskView.usage}); folding it into parent
+ * budgets is deferred until a reservation model lands.
+ */
+ readonly usageDelta?: unknown;
+ };
+ readonly output: JsonValue;
+ }[];
+}
+
+/**
+ * Arrives when the delegated child emits `input.requested`. After dispatch is
+ * acknowledged, the task run exposes the batch in an `input_required`
+ * snapshot and forwards the request to the parent session.
+ */
+export interface TaskInboundInputRequest {
+ readonly callId: string;
+ readonly childContinuationToken: string;
+ readonly childSessionId: string;
+ readonly kind: "subagent-input-request";
+ readonly event: {
+ readonly requests: readonly TaskInputRequest[];
+ readonly sequence: number;
+ readonly stepIndex: number;
+ readonly turnId: string;
+ };
+ readonly subagentName: string;
+}
+
+/**
+ * Arrives when a delegated child turn starts and its session and turn ids are
+ * known. The task run records those ids for executor addressing; this payload
+ * does not itself make the task ready or wake the parent.
+ */
+export interface TaskInboundTurnStarted {
+ readonly childSessionId: string;
+ readonly childTurnId: string;
+ readonly kind: "turn-started";
+ readonly taskId: string;
+}
+
+/**
+ * Arrives when the delegated child emits `authorization.required` or
+ * `authorization.completed`. The former exposes an authorization blocker in
+ * the task snapshot; the latter clears it. The event is forwarded separately
+ * to the parent and is never copied into the snapshot.
+ */
+export interface TaskInboundAuthorizationEvent {
+ readonly callId: string;
+ readonly childSessionId: string;
+ readonly kind: "authorization-event";
+ readonly event: SubagentAuthorizationEvent;
+ readonly subagentName: string;
+}
+
+/**
+ * Human answers routed to the task run rather than straight to the
+ * child. The run owns both the delivery and the state change, so the
+ * batch it clears is exactly the batch it forwarded — the parent can no
+ * longer unblock the child while the run still believes it is blocked.
+ */
+export interface TaskInboundAnswerInput {
+ readonly auth?: unknown;
+ readonly childContinuationToken: string;
+ readonly childResponseUrl?: string;
+ readonly inputResponses: readonly TaskInputResponse[];
+ readonly kind: "input-response";
+ readonly taskId: string;
+}
+
+/** Everything a task run's inbound continuation hook may receive. */
+export type TaskRunInboundPayload =
+ | TaskCommandHookPayload
+ | TaskInboundChildResult
+ | TaskInboundInputRequest
+ | TaskInboundTurnStarted
+ | TaskInboundAuthorizationEvent
+ | TaskInboundAnswerInput;
+
+/** Namespaced run stream carrying `TaskView` snapshots. */
+export const TASK_SNAPSHOT_STREAM_NAMESPACE = "eve.task";
+
+/** True when the status can never change again. */
+export function isTerminalTaskStatus(status: TaskStatus): boolean {
+ return status === "completed" || status === "failed" || status === "cancelled";
+}
+
+/** True when a transition into this status should wake the parent. */
+export function isReadyTaskStatus(status: TaskStatus): boolean {
+ return status === "input_required" || isTerminalTaskStatus(status);
+}
diff --git a/packages/eve/src/tasks/wire.test.ts b/packages/eve/src/tasks/wire.test.ts
new file mode 100644
index 000000000..2f104069b
--- /dev/null
+++ b/packages/eve/src/tasks/wire.test.ts
@@ -0,0 +1,198 @@
+import { describe, expect, it } from "vitest";
+
+import { TASK_AUTHORIZATION_REQUEST_ID } from "#tasks/types.js";
+import { translateTaskInboundPayload } from "#tasks/wire.js";
+
+const ZERO_USAGE = { cacheReadTokens: 0, cacheWriteTokens: 0, inputTokens: 0, outputTokens: 0 };
+const USAGE = { cacheReadTokens: 1, cacheWriteTokens: 2, inputTokens: 300, outputTokens: 40 };
+
+describe("translateTaskInboundPayload", () => {
+ it("passes explicit task commands through", () => {
+ expect(
+ translateTaskInboundPayload({ command: { kind: "cancel" }, kind: "task-command" }),
+ ).toEqual({ kind: "cancel" });
+ });
+
+ it("completes on a succeeded child turn outcome, parked or terminal", () => {
+ for (const kind of ["parked", "terminal"] as const) {
+ expect(
+ translateTaskInboundPayload({
+ kind: "runtime-action-result",
+ results: [
+ {
+ outcome: {
+ kind,
+ result: { kind: "succeeded", output: "answer" },
+ usageDelta: ZERO_USAGE,
+ },
+ output: "answer",
+ },
+ ],
+ }),
+ ).toEqual({ data: "answer", kind: "complete", lifecycle: kind, usage: ZERO_USAGE });
+ }
+ });
+
+ it("retains nonzero child usage on complete, fail, and cancel commands", () => {
+ const outcomes = [
+ {
+ expected: { data: "done", kind: "complete" },
+ result: { kind: "succeeded", output: "done" },
+ },
+ { expected: { data: "done", kind: "fail" }, result: { error: "boom", kind: "failed" } },
+ { expected: { kind: "cancel" }, result: { kind: "cancelled" } },
+ ] as const;
+ for (const { expected, result } of outcomes) {
+ expect(
+ translateTaskInboundPayload({
+ kind: "runtime-action-result",
+ results: [{ outcome: { kind: "terminal", result, usageDelta: USAGE }, output: "done" }],
+ }),
+ ).toEqual({ ...expected, lifecycle: "terminal", usage: USAGE });
+ }
+ });
+
+ it("drops malformed usage rather than failing the transition command", () => {
+ for (const usageDelta of [null, "n/a", { inputTokens: -1 }, { inputTokens: 1 }]) {
+ expect(
+ translateTaskInboundPayload({
+ kind: "runtime-action-result",
+ results: [
+ {
+ outcome: {
+ kind: "terminal",
+ result: { kind: "succeeded", output: "ok" },
+ usageDelta,
+ },
+ output: "ok",
+ },
+ ],
+ }),
+ ).toEqual({ data: "ok", kind: "complete", lifecycle: "terminal" });
+ }
+ });
+
+ it("fails on a failed outcome and cancels on a cancelled outcome", () => {
+ expect(
+ translateTaskInboundPayload({
+ kind: "runtime-action-result",
+ results: [
+ {
+ outcome: {
+ kind: "terminal",
+ result: { error: { message: "boom" }, kind: "failed" },
+ usageDelta: ZERO_USAGE,
+ },
+ output: { message: "boom" },
+ },
+ ],
+ }),
+ ).toEqual({
+ data: { message: "boom" },
+ kind: "fail",
+ lifecycle: "terminal",
+ usage: ZERO_USAGE,
+ });
+
+ expect(
+ translateTaskInboundPayload({
+ kind: "runtime-action-result",
+ results: [
+ {
+ outcome: { kind: "terminal", result: { kind: "cancelled" }, usageDelta: ZERO_USAGE },
+ output: null,
+ },
+ ],
+ }),
+ ).toEqual({ kind: "cancel", lifecycle: "terminal", usage: ZERO_USAGE });
+ });
+
+ it("ignores results without an explicit lifecycle outcome", () => {
+ expect(
+ translateTaskInboundPayload({
+ kind: "runtime-action-result",
+ results: [{ isError: true, output: "broken" }],
+ }),
+ ).toBeUndefined();
+ expect(
+ translateTaskInboundPayload({ kind: "runtime-action-result", results: [{ output: "ok" }] }),
+ ).toBeUndefined();
+ });
+
+ it("ignores empty result payloads", () => {
+ expect(
+ translateTaskInboundPayload({ kind: "runtime-action-result", results: [] }),
+ ).toBeUndefined();
+ });
+
+ it("marks the task input_required on a forwarded HITL batch", () => {
+ expect(
+ translateTaskInboundPayload({
+ callId: "call-1",
+ childContinuationToken: "child-token",
+ childSessionId: "child-session",
+ event: {
+ requests: [{ prompt: "Which region?" }],
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ },
+ kind: "subagent-input-request",
+ subagentName: "research",
+ }),
+ ).toEqual({ inputRequests: [{ prompt: "Which region?" }], kind: "require-input" });
+ });
+
+ it("blocks authorization under a reserved id that only its completion clears", () => {
+ expect(
+ translateTaskInboundPayload({
+ callId: "call-1",
+ childSessionId: "child-session",
+ event: {
+ data: {
+ description: "Authorize GitHub",
+ name: "github",
+ sequence: 1,
+ stepIndex: 2,
+ turnId: "turn-1",
+ },
+ type: "authorization.required",
+ },
+ kind: "authorization-event",
+ subagentName: "research",
+ }),
+ ).toEqual({
+ inputRequests: [{ blockedOn: "authorization", requestId: TASK_AUTHORIZATION_REQUEST_ID }],
+ kind: "require-input",
+ });
+ expect(
+ translateTaskInboundPayload({
+ callId: "call-1",
+ childSessionId: "child-session",
+ event: {
+ data: {
+ name: "github",
+ outcome: "authorized",
+ sequence: 2,
+ stepIndex: 2,
+ turnId: "turn-1",
+ },
+ type: "authorization.completed",
+ },
+ kind: "authorization-event",
+ subagentName: "research",
+ }),
+ ).toEqual({ kind: "answered", requestIds: [TASK_AUTHORIZATION_REQUEST_ID] });
+ });
+
+ it("leaves answered input to the run, which must deliver before recording it", () => {
+ expect(
+ translateTaskInboundPayload({
+ childContinuationToken: "child-token",
+ inputResponses: [{ requestId: "req-1", text: "west" }],
+ kind: "input-response",
+ taskId: "task-1",
+ }),
+ ).toBeUndefined();
+ });
+});
diff --git a/packages/eve/src/tasks/wire.ts b/packages/eve/src/tasks/wire.ts
new file mode 100644
index 000000000..b26238b8a
--- /dev/null
+++ b/packages/eve/src/tasks/wire.ts
@@ -0,0 +1,87 @@
+import type { TaskCommand, TaskRunInboundPayload, TaskUsage } from "#tasks/types.js";
+import { TASK_AUTHORIZATION_REQUEST_ID, readTaskUsage } from "#tasks/types.js";
+
+/**
+ * Translates one inbound hook payload into a lifecycle command.
+ *
+ * The child wire is unchanged by `experimental.tasks`; delegated
+ * dispatch hands children the task run's hook token, so the payloads
+ * that used to resume the parent turn arrive here instead:
+ *
+ * - a settled child turn (local notification or remote callback)
+ * carries an explicit outcome — its result status decides
+ * `complete`, `fail`, or `cancel`;
+ * - a forwarded HITL batch marks the task `input_required` with the
+ * outstanding requests;
+ * - `authorization.required` also blocks the task (the child cannot
+ * proceed without the parent's user) under a reserved request id, and
+ * `authorization.completed` clears exactly that id. Authorization
+ * payloads never enter the snapshot — only the fact that the child is
+ * blocked does.
+ *
+ * `input-response` is deliberately absent: the run must forward the
+ * answers to the child before it may record them, so it builds that
+ * command itself rather than translating one here.
+ *
+ * Returns `undefined` for unrecognized payloads, which the run ignores.
+ */
+export function translateTaskInboundPayload(
+ payload: TaskRunInboundPayload,
+): TaskCommand | undefined {
+ switch (payload.kind) {
+ case "task-command":
+ return payload.command;
+ case "runtime-action-result": {
+ const result = payload.results[0];
+ if (result === undefined) return undefined;
+ if (result.outcome !== undefined) {
+ // Usage retention: the settled outcome's `usageDelta` survives into
+ // the terminal command so the snapshot keeps the child's spend.
+ const usage = readTaskUsage(result.outcome.usageDelta);
+ switch (result.outcome.result.kind) {
+ case "succeeded":
+ return withUsage(
+ { data: result.output, kind: "complete", lifecycle: result.outcome.kind },
+ usage,
+ );
+ case "failed":
+ return withUsage(
+ { data: result.output, kind: "fail", lifecycle: result.outcome.kind },
+ usage,
+ );
+ case "cancelled":
+ return withUsage({ kind: "cancel", lifecycle: result.outcome.kind }, usage);
+ }
+ }
+ return undefined;
+ }
+ case "subagent-input-request":
+ return { inputRequests: payload.event.requests, kind: "require-input" };
+ case "turn-started":
+ return {
+ childSessionId: payload.childSessionId,
+ childTurnId: payload.childTurnId,
+ kind: "start-turn",
+ taskId: payload.taskId,
+ };
+ case "authorization-event":
+ return payload.event.type === "authorization.required"
+ ? {
+ inputRequests: [
+ { blockedOn: "authorization", requestId: TASK_AUTHORIZATION_REQUEST_ID },
+ ],
+ kind: "require-input",
+ }
+ : { kind: "answered", requestIds: [TASK_AUTHORIZATION_REQUEST_ID] };
+ default:
+ return undefined;
+ }
+}
+
+function withUsage(
+ command: Extract<TaskCommand, { kind: "complete" | "fail" | "cancel" }>,
+ usage: TaskUsage | undefined,
+): TaskCommand {
+ if (usage === undefined) return command;
+ return { ...command, usage };
+}
diff --git a/research/subagents-as-tasks-implementation.md b/research/subagents-as-tasks-implementation.md
index 0f09b3b48..5836d7814 100644
--- a/research/subagents-as-tasks-implementation.md
+++ b/research/subagents-as-tasks-implementation.md
@@ -138,13 +138,13 @@ originating call returns the same task and never dispatches twice.
Carry the six flows over the task contract for local and remote children alike, then let
`experimental.tasks` route the two subagent runtime-action kinds into delegated execution:
-| Flow | Carrier |
-| -------------------------- | ----------------------------------------------------------------- |
-| Terminal result or failure | `task.update` command to the task run, terminal snapshot |
-| Input request / approval | `task.update` with `input_required` plus the outstanding batch |
-| Authorization event | `task.authorization` through the task binding |
-| Input response | Parent-session HITL proxy, routed directly to the blocked child |
-| Cancellation | `task_cancel`: commit `cancelled`, then propagate executor abort |
+| Flow | Carrier |
+| -------------------------- | ---------------------------------------------------------------- |
+| Terminal result or failure | `task.update` command to the task run, terminal snapshot |
+| Input request / approval | `task.update` with `input_required` plus the outstanding batch |
+| Authorization event | `task.authorization` through the task binding |
+| Input response | Parent-session HITL proxy, routed directly to the blocked child |
+| Cancellation | `task_cancel`: commit `cancelled`, then propagate executor abort |
Concretely: