eve 0.41.0 → 0.43.0

package/dist/src/tasks/delivery-context.d.ts

@@ -0,0 +1,12 @@
+import type { SessionStateMap } from "#harness/types.js";
+export declare const TASK_DELIVERY_CONTEXT_LABEL = "[Task state]";
+export declare const TASK_DELIVERY_PENDING_INSTRUCTION = "Background task control: incomplete cohort\nThis framework-authored instruction overrides any earlier instruction to report, summarize, acknowledge, or otherwise handle background results.\n\nThe accompanying [Task state] message is runtime-authored and lists tasks started by the same parent turn. At least one of those tasks is still pending, so the combined report is not ready.\n\nAction:\n- You may call tools only if the newly delivered task result requires immediate action.\n- Otherwise, take no action.\n\nDelivery:\n- Do not report completed tasks or partial results.\n- Do not provide progress, status, an acknowledgement, or a waiting message.\n- After any necessary tool calls, your entire final text response must be exactly <eve-empty-delivery/> and no other text.\n\nIncorrect: \"Two of three tasks have completed.\"\nIncorrect: \"Still waiting for the remaining task.\"\nCorrect: <eve-empty-delivery/>";
+export declare const TASK_DELIVERY_SETTLED_INSTRUCTION = "Background task reporting\nThis turn was triggered by background task activity. The accompanying [Task state] message is runtime-authored and lists tasks started by the same parent turn, all settled, with every available terminal output. Do not reply with <eve-empty-delivery/>. Send one user-facing response that combines their useful results.";
+/** Returns model context and cohort phase for tasks started by the same parent turn as this delivery. */
+export declare function resolveTaskDeliveryContext(input: {
+    readonly state: SessionStateMap | undefined;
+    readonly taskDeliveryId: string;
+}): {
+    readonly context: string;
+    readonly phase: "pending" | "settled";
+} | undefined;

package/dist/src/tasks/delivery-context.js

@@ -0,0 +1,17 @@
+import{getSessionTaskIndex}from"#tasks/session-index.js";import{EMPTY_DELIVERY_SENTINEL}from"#shared/empty-delivery.js";const TASK_DELIVERY_CONTEXT_LABEL=`[Task state]`,TASK_DELIVERY_PENDING_INSTRUCTION=`Background task control: incomplete cohort
+This framework-authored instruction overrides any earlier instruction to report, summarize, acknowledge, or otherwise handle background results.
+
+The accompanying ${TASK_DELIVERY_CONTEXT_LABEL} message is runtime-authored and lists tasks started by the same parent turn. At least one of those tasks is still pending, so the combined report is not ready.
+
+Action:
+- You may call tools only if the newly delivered task result requires immediate action.
+- Otherwise, take no action.
+
+Delivery:
+- Do not report completed tasks or partial results.
+- Do not provide progress, status, an acknowledgement, or a waiting message.
+- After any necessary tool calls, your entire final text response must be exactly ${EMPTY_DELIVERY_SENTINEL} and no other text.
+
+Incorrect: "Two of three tasks have completed."
+Incorrect: "Still waiting for the remaining task."
+Correct: ${EMPTY_DELIVERY_SENTINEL}`,TASK_DELIVERY_SETTLED_INSTRUCTION=`Background task reporting\nThis turn was triggered by background task activity. The accompanying ${TASK_DELIVERY_CONTEXT_LABEL} message is runtime-authored and lists tasks started by the same parent turn, all settled, with every available terminal output. Do not reply with ${EMPTY_DELIVERY_SENTINEL}. Send one user-facing response that combines their useful results.`;function resolveTaskDeliveryContext(t){let n=getSessionTaskIndex(t.state),r=n.find(e=>t.taskDeliveryId.startsWith(`${e.taskId}:`));if(r===void 0)return;let i=n.filter(e=>e.createdByTurnId===r.createdByTurnId),a=i.every(e=>e.terminalView!==void 0),o=i.map(e=>({name:e.metadata.name,output:a?e.terminalView?.lastOutput:void 0,status:e.terminalView?.status??`pending`,taskId:e.taskId}));return{context:`${TASK_DELIVERY_CONTEXT_LABEL}\n${JSON.stringify({tasks:o})}`,phase:a?`settled`:`pending`}}export{TASK_DELIVERY_CONTEXT_LABEL,TASK_DELIVERY_PENDING_INSTRUCTION,TASK_DELIVERY_SETTLED_INSTRUCTION,resolveTaskDeliveryContext};

package/dist/src/tasks/json.d.ts

@@ -3,7 +3,7 @@ import type { JsonValue } from "#shared/json.js";
 import type { TaskView } from "#tasks/types.js";
 /** Model-visible task shape. Unlisted private fields are stripped by zod. */
 declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    metadata: z.ZodObject<{
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
         agentId: z.ZodString;
         kind: z.ZodLiteral<"subagent">;
         mode: z.ZodEnum<{
@@ -11,11 +11,14 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             remote: "remote";
         }>;
         name: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>]>;
     taskId: z.ZodString;
     status: z.ZodLiteral<"working">;
 }, z.core.$strip>, z.ZodObject<{
-    metadata: z.ZodObject<{
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
         agentId: z.ZodString;
         kind: z.ZodLiteral<"subagent">;
         mode: z.ZodEnum<{
@@ -23,12 +26,15 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             remote: "remote";
         }>;
         name: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>]>;
     taskId: z.ZodString;
     inputRequests: z.ZodReadonly<z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
     status: z.ZodLiteral<"input_required">;
 }, z.core.$strip>, z.ZodObject<{
-    metadata: z.ZodObject<{
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
         agentId: z.ZodString;
         kind: z.ZodLiteral<"subagent">;
         mode: z.ZodEnum<{
@@ -36,7 +42,10 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             remote: "remote";
         }>;
         name: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>]>;
     taskId: z.ZodString;
     lastOutput: z.ZodObject<{
         data: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -44,7 +53,7 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     status: z.ZodLiteral<"completed">;
 }, z.core.$strip>, z.ZodObject<{
-    metadata: z.ZodObject<{
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
         agentId: z.ZodString;
         kind: z.ZodLiteral<"subagent">;
         mode: z.ZodEnum<{
@@ -52,7 +61,10 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             remote: "remote";
         }>;
         name: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>]>;
     taskId: z.ZodString;
     lastOutput: z.ZodObject<{
         data: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -60,7 +72,7 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     status: z.ZodLiteral<"failed">;
 }, z.core.$strip>, z.ZodObject<{
-    metadata: z.ZodObject<{
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
         agentId: z.ZodString;
         kind: z.ZodLiteral<"subagent">;
         mode: z.ZodEnum<{
@@ -68,7 +80,10 @@ declare const taskViewJsonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             remote: "remote";
         }>;
         name: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>]>;
     taskId: z.ZodString;
     status: z.ZodLiteral<"cancelled">;
 }, z.core.$strip>], "status">;

package/dist/src/tasks/json.js

@@ -1 +1 @@
-import{z}from"#compiled/zod/index.js";import{jsonValueSchema}from"#shared/json-schemas.js";const taskMetadataJsonSchema=z.object({agentId:z.string(),kind:z.literal(`subagent`),mode:z.enum([`local`,`remote`]),name:z.string()}),taskOutputJsonSchema=z.object({data:jsonValueSchema,type:z.enum([`result`,`error`])}),taskViewJsonBaseShape={metadata:taskMetadataJsonSchema,taskId:z.string()},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`)})]);function taskViewToJson(e){return taskViewJsonSchema.parse(e)}function taskViewsToJson(e){return{tasks:e.map(e=>taskViewToJson(e))}}export{taskViewToJson,taskViewsToJson};
+import{z}from"#compiled/zod/index.js";import{jsonValueSchema}from"#shared/json-schemas.js";import{readSubagentTaskMetadata}from"#tasks/types.js";const taskMetadataJsonSchema=z.union([z.object({agentId:z.string(),kind:z.literal(`subagent`),mode:z.enum([`local`,`remote`]),name:z.string()}),z.object({kind:z.string(),name:z.string()})]),taskOutputJsonSchema=z.object({data:jsonValueSchema,type:z.enum([`result`,`error`])}),taskViewJsonBaseShape={metadata:taskMetadataJsonSchema,taskId:z.string()},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`)})]);function taskViewToJson(e){let t=readSubagentTaskMetadata(e),n=t===void 0?e.metadata:{agentId:t.agentId,kind:t.kind,mode:t.mode,name:t.name};return taskViewJsonSchema.parse({...e,metadata:n})}function taskViewsToJson(e){return{tasks:e.map(e=>taskViewToJson(e))}}export{taskViewToJson,taskViewsToJson};

package/dist/src/tasks/session-index.d.ts

@@ -1,5 +1,6 @@
 import type { HarnessSession, SessionStateMap } from "#harness/types.js";
-import type { TaskMetadata, TaskView } from "#tasks/types.js";
+import type { TaskExecutorBinding } from "#shared/tool-task.js";
+import { type DurableTaskMetadata, type TaskView } from "#tasks/types.js";
 /**
  * Session-state key for the parent's live-task index.
  *
@@ -27,8 +28,9 @@ export interface SessionTaskIndexEntry {
     readonly taskInboxToken: string;
     readonly createdByStepIndex?: number;
     readonly createdByTurnId: string;
-    readonly metadata: TaskMetadata;
-    readonly operationId: string;
+    readonly executor?: TaskExecutorBinding;
+    readonly metadata: DurableTaskMetadata;
+    readonly operationId?: string;
 }
 /**
  * Reads and validates the task index from session state.

package/dist/src/tasks/session-index.js

@@ -1 +1 @@
-import{z}from"#compiled/zod/index.js";const SESSION_TASKS_STATE_KEY=`eve.tasks`,taskMetadataSchema=z.strictObject({agentId:z.string().min(1),kind:z.literal(`subagent`),mode:z.enum([`local`,`remote`]),name:z.string().min(1)}),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()},taskViewSchema=z.discriminatedUnion(`status`,[z.strictObject({...taskViewBaseShape,lastOutput:z.strictObject({data:z.custom(),type:z.literal(`result`)}),status:z.literal(`completed`)}),z.strictObject({...taskViewBaseShape,lastOutput:z.strictObject({data:z.custom(),type:z.literal(`error`)}),status:z.literal(`failed`)}),z.strictObject({...taskViewBaseShape,status:z.literal(`cancelled`)})]),sessionTaskIndexEntrySchema=z.strictObject({taskInboxToken: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),terminalView:taskViewSchema.optional()}),sessionTaskIndexSchema=z.strictObject({tasks:z.array(sessionTaskIndexEntrySchema)}).refine(e=>new Set(e.tasks.map(e=>e.taskId)).size===e.tasks.length,{message:`Task ids must be unique.`}).refine(e=>e.tasks.every(e=>e.terminalView===void 0||e.terminalView.taskId===e.taskId&&sameTaskMetadata(e.terminalView.metadata,e.metadata)),{message:`Cached terminal views must match their task index entry.`});function getSessionTaskIndex(e){let n=e?.[SESSION_TASKS_STATE_KEY];if(n===void 0)return[];let r=sessionTaskIndexSchema.safeParse(n);if(!r.success)throw Error(`Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}": ${r.error.message}`);return r.data.tasks}function cacheTerminalTaskView(e,n){if(!isValidTerminalView(n))throw Error(`Cannot cache invalid terminal task "${n.taskId}".`);let r=getSessionTaskIndex(e),i=r.findIndex(e=>e.taskId===n.taskId);if(i<0)return e;if(!sameTaskMetadata(r[i].metadata,n.metadata))throw Error(`Task view metadata does not match index entry "${n.taskId}".`);let a=[...r];return a[i]={...a[i],terminalView:n},{...e,[SESSION_TASKS_STATE_KEY]:{tasks:a}}}function isValidTerminalView(e){if(e.inputRequests!==void 0)return!1;switch(e.status){case`completed`:return e.lastOutput?.type===`result`;case`failed`:return e.lastOutput?.type===`error`;case`cancelled`:return e.lastOutput===void 0;case`working`:return!1}}function sameTaskMetadata(e,t){return e.agentId===t.agentId&&e.kind===t.kind&&e.mode===t.mode&&e.name===t.name}function findSessionTaskEntry(e,t){return getSessionTaskIndex(e).find(e=>e.taskId===t)}function recordSessionTask(e,n){let r=[...getSessionTaskIndex(e.state).filter(e=>e.taskId!==n.taskId),n];return{...e,state:{...e.state,[SESSION_TASKS_STATE_KEY]:{tasks:r}}}}export{SESSION_TASKS_STATE_KEY,cacheTerminalTaskView,findSessionTaskEntry,getSessionTaskIndex,recordSessionTask};
+import{z}from"#compiled/zod/index.js";import{sameTaskMetadata}from"#tasks/types.js";const SESSION_TASKS_STATE_KEY=`eve.tasks`,taskMetadataSchema=z.union([z.strictObject({agentId:z.string().min(1),kind:z.literal(`subagent`),mode:z.enum([`local`,`remote`]),name:z.string().min(1)}),z.strictObject({kind:z.string().min(1),name:z.string().min(1)})]),taskViewBaseShape={executor:z.strictObject({binding:z.strictObject({data:z.record(z.string(),z.custom()),kind:z.string().min(1)}).optional(),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()},taskViewSchema=z.discriminatedUnion(`status`,[z.strictObject({...taskViewBaseShape,lastOutput:z.strictObject({data:z.custom(),type:z.literal(`result`)}),status:z.literal(`completed`)}),z.strictObject({...taskViewBaseShape,lastOutput:z.strictObject({data:z.custom(),type:z.literal(`error`)}),status:z.literal(`failed`)}),z.strictObject({...taskViewBaseShape,status:z.literal(`cancelled`)})]),sessionTaskIndexEntrySchema=z.strictObject({taskInboxToken:z.string().min(1),createdByStepIndex:z.number().int().nonnegative().optional(),createdByTurnId:z.string().min(1),executor:z.strictObject({data:z.record(z.string(),z.custom()),kind:z.string().min(1)}).optional(),metadata:taskMetadataSchema,operationId:z.string().min(1).optional(),taskId:z.string().min(1),taskRunId:z.string().min(1),terminalView:taskViewSchema.optional()}),sessionTaskIndexSchema=z.strictObject({tasks:z.array(sessionTaskIndexEntrySchema)}).refine(e=>new Set(e.tasks.map(e=>e.taskId)).size===e.tasks.length,{message:`Task ids must be unique.`}).refine(e=>e.tasks.every(e=>e.terminalView===void 0||e.terminalView.taskId===e.taskId&&sameTaskMetadata(e.terminalView.metadata,e.metadata)),{message:`Cached terminal views must match their task index entry.`});function getSessionTaskIndex(e){let t=e?.[SESSION_TASKS_STATE_KEY];if(t===void 0)return[];let n=sessionTaskIndexSchema.safeParse(t);if(!n.success)throw Error(`Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}": ${n.error.message}`);return n.data.tasks}function cacheTerminalTaskView(e,n){if(!isValidTerminalView(n))throw Error(`Cannot cache invalid terminal task "${n.taskId}".`);let r=getSessionTaskIndex(e),i=r.findIndex(e=>e.taskId===n.taskId);if(i<0)return e;if(!sameTaskMetadata(r[i].metadata,n.metadata))throw Error(`Task view metadata does not match index entry "${n.taskId}".`);let a=[...r];return a[i]={...a[i],terminalView:n},{...e,[SESSION_TASKS_STATE_KEY]:{tasks:a}}}function isValidTerminalView(e){if(e.inputRequests!==void 0)return!1;switch(e.status){case`completed`:return e.lastOutput?.type===`result`;case`failed`:return e.lastOutput?.type===`error`;case`cancelled`:return e.lastOutput===void 0;case`working`:return!1}}function findSessionTaskEntry(e,t){return getSessionTaskIndex(e).find(e=>e.taskId===t)}function recordSessionTask(e,t){let n=[...getSessionTaskIndex(e.state).filter(e=>e.taskId!==t.taskId),t];return{...e,state:{...e.state,[SESSION_TASKS_STATE_KEY]:{tasks:n}}}}export{SESSION_TASKS_STATE_KEY,cacheTerminalTaskView,findSessionTaskEntry,getSessionTaskIndex,recordSessionTask};

package/dist/src/tasks/transitions.d.ts

@@ -1,23 +1,58 @@
 import type { TaskCommand, TaskView } from "#tasks/types.js";
 /**
- * Outcome of applying one command to a task view.
+ * Action taken on one command applied to a task view.
  *
- * - `accepted`: the state changed; the new view must be appended.
+ * - `accepted`: the view 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.
  */
 type TaskTransitionResult = {
-    readonly outcome: "accepted";
+    readonly action: "accepted";
     readonly view: TaskView;
 } | {
-    readonly outcome: "noop";
+    readonly action: "noop";
     readonly view: TaskView;
 } | {
-    readonly outcome: "rejected";
+    readonly action: "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.
+ *
+ * Orthogonal to the status, the view carries private executor state
+ * (`TaskExecutorState`) with its own lifecycle. These commands move
+ * executor fields, never the status above:
+ *
+ * ```text
+ * binding:  unset --bind-------> bound            (replay noop, conflict rejected)
+ * address:  unset --start-turn-> session pinned   (turn id updated per delivery)
+ * verdict:  unset --complete/fail/cancel/settle-executor-> parked | terminal
+ * ```
+ *
+ * - `bind` writes the executor binding exactly once: replaying the
+ *   same binding is a noop, a different one is rejected.
+ * - `start-turn` records the child session/turn ids used to address
+ *   the executor, rejecting a child-session mismatch.
+ * - Terminal commands and a late `settle-executor` record the child's
+ *   lifecycle verdict: `parked` means the child session survived and
+ *   can take another delivery, `terminal` means it ended with the turn.
+ */
 export declare function applyTaskTransition(view: TaskView, command: TaskCommand): TaskTransitionResult;
 export {};

package/dist/src/tasks/transitions.js

@@ -1 +1 @@
-import{isTerminalTaskStatus,readTaskInputRequestId}from"#tasks/types.js";function terminalView(e,t,n){let r={executor:t.lifecycle===void 0?e.executor:{...e.executor,lifecycle:t.lifecycle},metadata:e.metadata,taskId:e.taskId};switch(t.usage!==void 0&&(r.usage=t.usage),n.status){case`completed`:return{...r,lastOutput:n.lastOutput,status:`completed`};case`failed`:return{...r,lastOutput:n.lastOutput,status:`failed`};case`cancelled`:return{...r,status:`cancelled`}}}function applyTaskTransition(n,r){if(isTerminalTaskStatus(n.status)){if(r.kind===`settle-executor`){let e={...n.executor,lifecycle:`terminal`};if(sameUsage(n.usage,r.usage)&&n.executor?.lifecycle===`terminal`)return{outcome:`noop`,view:n};let t={...n,executor:e};return{outcome:`accepted`,view:r.usage===void 0?t:{...t,usage:r.usage}}}return r.kind===`cancel`&&n.status===`cancelled`?{outcome:`noop`,view:n}:{outcome:`rejected`,reason:`Task "${n.taskId}" is already ${n.status}; "${r.kind}" cannot change a terminal task.`,view:n}}switch(r.kind){case`complete`:return{outcome:`accepted`,view:terminalView(n,r,{lastOutput:{data:r.data,type:`result`},status:`completed`})};case`fail`:case`reject-dispatch`:return{outcome:`accepted`,view:terminalView(n,r,{lastOutput:{data:r.data,type:`error`},status:`failed`})};case`cancel`:return{outcome:`accepted`,view:terminalView(n,r,{status:`cancelled`})};case`settle-executor`:return{outcome:`rejected`,reason:`Task "${n.taskId}" is not terminal; usage settles with its terminal command.`,view:n};case`require-authorization`:{let e={blockedOn:`authorization`,requestId:r.requestId};return n.status===`input_required`?n.inputRequests.some(e=>readTaskInputRequestId(e)===r.requestId)?{outcome:`noop`,view:n}:{outcome:`accepted`,view:{...n,inputRequests:[...n.inputRequests,e]}}:{outcome:`accepted`,view:{inputRequests:[e],executor:n.executor,metadata:n.metadata,status:`input_required`,taskId:n.taskId}}}case`require-input`:return isValidInputRequestBatch(r.inputRequests)?{outcome:`accepted`,view:{inputRequests:r.inputRequests,executor:n.executor,metadata:n.metadata,status:`input_required`,taskId:n.taskId}}:{outcome:`rejected`,reason:`Task "${n.taskId}" received an invalid input request batch.`,view:n};case`ready`:return{outcome:`accepted`,view:n};case`answered`:{if(n.status!==`input_required`)return{outcome:`noop`,view:n};let e=new Set(r.requestIds),i=n.inputRequests,a=i.filter(n=>{let r=readTaskInputRequestId(n);return r===void 0||!e.has(r)});return a.length===i.length?{outcome:`noop`,view:n}:a.length>0?{outcome:`accepted`,view:{inputRequests:a,executor:n.executor,metadata:n.metadata,status:`input_required`,taskId:n.taskId}}:{outcome:`accepted`,view:{executor:n.executor,metadata:n.metadata,status:`working`,taskId:n.taskId}}}case`start-turn`:return r.taskId===n.taskId?n.executor?.childSessionId!==void 0&&n.executor.childSessionId!==r.childSessionId?{outcome:`rejected`,reason:`Task child session "${r.childSessionId}" does not match "${n.executor.childSessionId}".`,view:n}:n.executor?.childSessionId===r.childSessionId&&n.executor.childTurnId===r.childTurnId?{outcome:`noop`,view:n}:{outcome:`accepted`,view:{...n,executor:{...n.executor,childSessionId:r.childSessionId,childTurnId:r.childTurnId}}}:{outcome:`rejected`,reason:`Task turn identity "${r.taskId}" does not match "${n.taskId}".`,view:n}}}function isValidInputRequestBatch(e){if(e.length===0)return!1;let n=e.map(readTaskInputRequestId);return n.every(e=>e!==void 0&&e.length>0)&&new Set(n).size===n.length}function sameUsage(e,t){return e===void 0||t===void 0?e===t:e?.cacheReadTokens===t.cacheReadTokens&&e.cacheWriteTokens===t.cacheWriteTokens&&e.inputTokens===t.inputTokens&&e.outputTokens===t.outputTokens}export{applyTaskTransition};
+import{jsonValuesEqual}from"#shared/json.js";import{isTerminalTaskStatus,readTaskInputRequestId}from"#tasks/types.js";function terminalView(e,t,n){let r={executor:t.lifecycle===void 0?e.executor:{...e.executor,lifecycle:t.lifecycle},metadata:e.metadata,taskId:e.taskId};switch(t.usage!==void 0&&(r.usage=t.usage),n.status){case`completed`:return{...r,lastOutput:n.lastOutput,status:`completed`};case`failed`:return{...r,lastOutput:n.lastOutput,status:`failed`};case`cancelled`:return{...r,status:`cancelled`}}}function applyTaskTransition(r,i){if(i.kind===`bind`){let t=r.executor?.binding;return t!==void 0&&t.kind===i.executor.kind&&jsonValuesEqual(t.data,i.executor.data)?{action:`noop`,view:r}:t===void 0?{action:`accepted`,view:{...r,executor:{...r.executor,binding:i.executor}}}:{action:`rejected`,reason:`Task "${r.taskId}" already has an executor binding.`,view:r}}if(isTerminalTaskStatus(r.status)){if(i.kind===`settle-executor`){let e={...r.executor,lifecycle:`terminal`};if(sameUsage(r.usage,i.usage)&&r.executor?.lifecycle===`terminal`)return{action:`noop`,view:r};let t={...r,executor:e};return{action:`accepted`,view:i.usage===void 0?t:{...t,usage:i.usage}}}return i.kind===`cancel`&&r.status===`cancelled`?{action:`noop`,view:r}:{action:`rejected`,reason:`Task "${r.taskId}" is already ${r.status}; "${i.kind}" cannot change a terminal task.`,view:r}}switch(i.kind){case`complete`:return{action:`accepted`,view:terminalView(r,i,{lastOutput:{data:i.data,type:`result`},status:`completed`})};case`fail`:case`reject-dispatch`:return{action:`accepted`,view:terminalView(r,i,{lastOutput:{data:i.data,type:`error`},status:`failed`})};case`cancel`:return{action:`accepted`,view:terminalView(r,i,{status:`cancelled`})};case`settle-executor`:return{action:`rejected`,reason:`Task "${r.taskId}" is not terminal; usage settles with its terminal command.`,view:r};case`require-authorization`:{let e={blockedOn:`authorization`,requestId:i.requestId};return r.status===`input_required`?r.inputRequests.some(e=>readTaskInputRequestId(e)===i.requestId)?{action:`noop`,view:r}:{action:`accepted`,view:{...r,inputRequests:[...r.inputRequests,e]}}:{action:`accepted`,view:{inputRequests:[e],executor:r.executor,metadata:r.metadata,status:`input_required`,taskId:r.taskId}}}case`require-input`:return isValidInputRequestBatch(i.inputRequests)?{action:`accepted`,view:{inputRequests:i.inputRequests,executor:r.executor,metadata:r.metadata,status:`input_required`,taskId:r.taskId}}:{action:`rejected`,reason:`Task "${r.taskId}" received an invalid input request batch.`,view:r};case`ready`:return{action:`accepted`,view:r};case`answered`:{if(r.status!==`input_required`)return{action:`noop`,view:r};let e=new Set(i.requestIds),t=r.inputRequests,a=t.filter(t=>{let r=readTaskInputRequestId(t);return r===void 0||!e.has(r)});return a.length===t.length?{action:`noop`,view:r}:a.length>0?{action:`accepted`,view:{inputRequests:a,executor:r.executor,metadata:r.metadata,status:`input_required`,taskId:r.taskId}}:{action:`accepted`,view:{executor:r.executor,metadata:r.metadata,status:`working`,taskId:r.taskId}}}case`start-turn`:return i.taskId===r.taskId?r.executor?.childSessionId!==void 0&&r.executor.childSessionId!==i.childSessionId?{action:`rejected`,reason:`Task child session "${i.childSessionId}" does not match "${r.executor.childSessionId}".`,view:r}:r.executor?.childSessionId===i.childSessionId&&r.executor.childTurnId===i.childTurnId?{action:`noop`,view:r}:{action:`accepted`,view:{...r,executor:{...r.executor,childSessionId:i.childSessionId,childTurnId:i.childTurnId}}}:{action:`rejected`,reason:`Task turn identity "${i.taskId}" does not match "${r.taskId}".`,view:r}}}function isValidInputRequestBatch(e){if(e.length===0)return!1;let t=e.map(readTaskInputRequestId);return t.every(e=>e!==void 0&&e.length>0)&&new Set(t).size===t.length}function sameUsage(e,t){return e===void 0||t===void 0?e===t:e?.cacheReadTokens===t.cacheReadTokens&&e.cacheWriteTokens===t.cacheWriteTokens&&e.inputTokens===t.inputTokens&&e.outputTokens===t.outputTokens}export{applyTaskTransition};

package/dist/src/tasks/types.d.ts

@@ -1,4 +1,6 @@
-import type { JsonValue } from "#shared/json.js";
+import type { AgentAddress, AgentIdentity } from "#harness/handles/store.js";
+import { type JsonValue } from "#shared/json.js";
+import type { TaskExecutorBinding } from "#shared/tool-task.js";
 import type { SubagentAuthorizationEvent } from "#channel/types.js";
 /**
  * Task lifecycle contract for `experimental.tasks`.
@@ -33,10 +35,45 @@ export interface TaskMetadata {
     /** Authored subagent name the parent dispatched. */
     readonly name: string;
 }
+export type SubagentTaskMetadata = TaskMetadata;
+/** Executor-neutral metadata retained by a non-subagent durable task. */
+export interface BackgroundTaskMetadata {
+    readonly kind: string;
+    readonly name: string;
+}
+export type DurableTaskMetadata = BackgroundTaskMetadata | TaskMetadata;
+export declare function createSubagentTaskMetadata(metadata: Omit<SubagentTaskMetadata, "kind" | "name"> & {
+    readonly name: string;
+}): SubagentTaskMetadata;
+export declare function readSubagentTaskMetadata(task: {
+    readonly executor?: TaskExecutorBinding | TaskExecutorState;
+    readonly metadata: DurableTaskMetadata;
+}): SubagentTaskMetadata | undefined;
+/**
+ * Durable subagent executor binding payload: the child's stable identity and
+ * private delivery address, copied from the parent's agent handle store at
+ * delegation time. Every field derives deterministically from the
+ * originating call (operation-hashed id, dispatch-chosen continuation
+ * token), so a replayed delegation produces a deep-equal binding — the
+ * equality the task run's `bind` replay check compares.
+ */
+export interface SubagentExecutorData {
+    readonly address: AgentAddress;
+    readonly identity: AgentIdentity;
+}
+export declare function createSubagentExecutorBinding(executor: SubagentExecutorData): TaskExecutorBinding;
+export declare function readSubagentExecutor(executor: TaskExecutorBinding | TaskExecutorState | undefined): SubagentExecutorData | undefined;
+export declare function sameTaskMetadata(left: DurableTaskMetadata, right: DurableTaskMetadata): boolean;
 /** Private executor state retained for cancellation and address reconciliation. */
 export interface TaskExecutorState {
+    /** Write-once executor address recorded by the `bind` command. */
+    readonly binding?: TaskExecutorBinding;
     readonly childSessionId?: string;
     readonly childTurnId?: string;
+    /**
+     * Child-session verdict from the last settled turn: `parked` survived
+     * and can take another delivery, `terminal` ended with the turn.
+     */
     readonly lifecycle?: "parked" | "terminal";
 }
 /**
@@ -92,7 +129,7 @@ export declare function readTaskInputRequestId(request: TaskInputRequest): strin
 /** Fields shared by every durable task view. */
 interface TaskViewBase {
     readonly taskId: string;
-    readonly metadata: TaskMetadata;
+    readonly metadata: DurableTaskMetadata;
     /** Private executor state; deliberately excluded from model-visible JSON. */
     readonly executor?: TaskExecutorState;
     /**
@@ -140,6 +177,9 @@ export type TaskView = TaskViewBase & ({
 });
 /** Commands accepted by the durable task run's transition function. */
 export type TaskCommand = {
+    readonly executor: TaskExecutorBinding;
+    readonly kind: "bind";
+} | {
     readonly kind: "complete";
     readonly data: JsonValue;
     readonly lifecycle?: "parked" | "terminal";
@@ -260,8 +300,10 @@ export interface TaskInboundTurnStarted {
 /** Intermediate progress sent by a running child to its parent agent. */
 export interface TaskInboundUpdate {
     readonly callId: string;
-    readonly childStepIndex: number;
-    readonly childTurnId: string;
+    /** Executor-neutral monotonic index within {@link updateEpoch}. */
+    readonly updateIndex: number;
+    /** Executor-neutral epoch id used with {@link updateIndex} for update dedupe. */
+    readonly updateEpoch: string;
     readonly kind: "task-update";
     readonly message: string;
 }

package/dist/src/tasks/types.js

@@ -1 +1 @@
-function readTaskUsage(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=readUsageAxis(e,`cacheReadTokens`),n=readUsageAxis(e,`cacheWriteTokens`),r=readUsageAxis(e,`inputTokens`),i=readUsageAxis(e,`outputTokens`);if(!(t===void 0||n===void 0||r===void 0||i===void 0))return{cacheReadTokens:t,cacheWriteTokens:n,inputTokens:r,outputTokens:i}}function readUsageAxis(e,t){let n=Reflect.get(e,t);return typeof n==`number`&&Number.isFinite(n)&&n>=0?n:void 0}const TASK_AUTHORIZATION_REQUEST_ID_PREFIX=`task:authorization`;function taskAuthorizationRequestId(t){return t.type===`approval.candidate`||t.type===`approval.settled`?`${TASK_AUTHORIZATION_REQUEST_ID_PREFIX}:${t.data.requestId}`:`${TASK_AUTHORIZATION_REQUEST_ID_PREFIX}:${t.data.attemptId??t.data.name}`}function readTaskInputRequestId(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=Reflect.get(e,`requestId`);return typeof t==`string`?t:void 0}const TASK_VIEW_STREAM_NAMESPACE=`eve.task`;function isTerminalTaskStatus(e){return e===`completed`||e===`failed`||e===`cancelled`}function isReadyTaskStatus(e){return e===`input_required`||isTerminalTaskStatus(e)}export{TASK_VIEW_STREAM_NAMESPACE,isReadyTaskStatus,isTerminalTaskStatus,readTaskInputRequestId,readTaskUsage,taskAuthorizationRequestId};
+import{isJsonObjectValue}from"#shared/json.js";function createSubagentTaskMetadata(e){return{...e,kind:`subagent`}}function readSubagentTaskMetadata(e){if(e.metadata.kind===`subagent`&&`agentId`in e.metadata)return e.metadata;let t=readSubagentExecutor(e.executor);if(t!==void 0)return{agentId:t.identity.id,kind:`subagent`,mode:t.address.kind===`agent/remote`?`remote`:`local`,name:t.identity.name}}function createSubagentExecutorBinding(e){let{address:t,identity:n}=e;return{data:{address:{...t},identity:{id:n.id,name:n.name,nodeId:n.nodeId}},kind:`subagent`}}function readSubagentExecutor(e){let t=e!==void 0&&`kind`in e?e:e?.binding;if(t?.kind!==`subagent`)return;let n=readAgentIdentity(t.data.identity),r=readAgentAddress(t.data.address);return n===void 0||r===void 0?void 0:{address:r,identity:n}}function readAgentIdentity(t){if(t===void 0||!isJsonObjectValue(t))return;let{id:n,name:r,nodeId:i}=t;return typeof n==`string`&&typeof r==`string`&&typeof i==`string`?{id:n,name:r,nodeId:i}:void 0}function readAgentAddress(t){if(t===void 0||!isJsonObjectValue(t))return;let{callbackBaseUrl:n,continuationToken:r,kind:i,sessionId:a,url:o}=t;if(typeof a==`string`){if(i===`agent/local`||i===`agent/self`)return typeof r==`string`?{continuationToken:r,kind:i,sessionId:a}:void 0;if(i===`agent/remote`)return typeof o==`string`&&typeof n==`string`?{callbackBaseUrl:n,kind:i,sessionId:a,url:o}:void 0}}function sameTaskMetadata(e,t){if(e.kind!==t.kind||e.name!==t.name)return!1;let n=`agentId`in e,r=`agentId`in t;return n===r&&(!n||!r||e.agentId===t.agentId&&e.mode===t.mode)}function readTaskUsage(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=readUsageAxis(e,`cacheReadTokens`),n=readUsageAxis(e,`cacheWriteTokens`),r=readUsageAxis(e,`inputTokens`),i=readUsageAxis(e,`outputTokens`);if(!(t===void 0||n===void 0||r===void 0||i===void 0))return{cacheReadTokens:t,cacheWriteTokens:n,inputTokens:r,outputTokens:i}}function readUsageAxis(e,t){let n=Reflect.get(e,t);return typeof n==`number`&&Number.isFinite(n)&&n>=0?n:void 0}const TASK_AUTHORIZATION_REQUEST_ID_PREFIX=`task:authorization`;function taskAuthorizationRequestId(e){return e.type===`approval.candidate`||e.type===`approval.settled`?`${TASK_AUTHORIZATION_REQUEST_ID_PREFIX}:${e.data.requestId}`:`${TASK_AUTHORIZATION_REQUEST_ID_PREFIX}:${e.data.attemptId??e.data.name}`}function readTaskInputRequestId(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=Reflect.get(e,`requestId`);return typeof t==`string`?t:void 0}const TASK_VIEW_STREAM_NAMESPACE=`eve.task`;function isTerminalTaskStatus(e){return e===`completed`||e===`failed`||e===`cancelled`}function isReadyTaskStatus(e){return e===`input_required`||isTerminalTaskStatus(e)}export{TASK_VIEW_STREAM_NAMESPACE,createSubagentExecutorBinding,createSubagentTaskMetadata,isReadyTaskStatus,isTerminalTaskStatus,readSubagentExecutor,readSubagentTaskMetadata,readTaskInputRequestId,readTaskUsage,sameTaskMetadata,taskAuthorizationRequestId};

package/docs/channels/custom.mdx

@@ -111,6 +111,18 @@ await session.reset({ reason: "Retire this session" });
 await session.getEventStream({ startIndex: 12 });
 ```
 
+`respond()` accepts exact response literals directly. If responses have already
+been widened to `InputResponse[]`—for example, after decoding a platform
+payload—validate them with eve's strict schema before delivery. The validated
+type preserves that proof across channel wrappers:
+
+```ts
+import { parseInputResponses } from "eve/client";
+
+const inputResponses = parseInputResponses(decodedResponses);
+await source.respond(inputResponses, { auth });
+```
+
 Message sends use the channel's `turnPolicy`, which defaults to `"steer"`. An accepted message arriving during an active turn is durably buffered before eve cancels that turn and starts the message as a replacement turn. Configure `turnPolicy: "queue"` on `defineChannel(...)` when active turns should finish in order, or override one send:
 
 ```ts

package/docs/channels/linq.mdx

@@ -5,7 +5,7 @@ description: Connect an eve agent to iMessage and SMS through Linq.
 
 Use `linqChannel` to receive and reply to iMessage and SMS conversations through Linq.
 
-Run `eve add channel/linq` to choose Vercel Connect or portable credentials. With Vercel Connect, eve signs you in and creates or links a Vercel project when needed. Then choose whether to create a managed Linq account and line or connect an existing Linq account with its partner API token and phone numbers. eve configures the connector and webhook through Connect:
+Run `eve add channel/linq` to choose Vercel Connect or portable credentials. With Vercel Connect, eve signs you in and creates or links a Vercel project when needed. Then choose whether to create a managed Linq account and line or connect an existing account with its partner API token. eve fetches the phone numbers assigned to that account, and you select the numbers for the agent. eve configures the connector and webhook through Connect:
 
 ```ts title="agent/channels/linq.ts"
 import { connectLinqCredentials } from "@vercel/connect/eve";

package/docs/getting-started.mdx

@@ -24,13 +24,7 @@ Run `eve init` with a project name:
 npx eve@latest init my-agent
 ```
 
-The command creates the project, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
-
-Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
-
-```bash
-npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
-```
+The command creates the project, installs dependencies, and initializes Git. After scaffolding, eve offers to start the development server or, if a supported coding agent is installed, to open the project in the coding agent.
 
 To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
 
@@ -40,15 +34,23 @@ npx eve@latest init .
 
 eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
 
+### Customize initialization
+
+To initialize the agent with a different AI Gateway model or reasoning effort, pass `--model` or `--reasoning`:
+
+```bash
+npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
+```
+
 ## Run the agent
 
-If the development server is not already running, start it from the project root:
+Choose **Start eve dev** after scaffolding, or run this from the project root:
 
 ```bash
 npm run dev
 ```
 
-The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command.
+This starts an interactive session where you can send messages to your agent.
 
 ## Project layout
 
@@ -56,7 +58,7 @@ eve builds an agent by walking the filesystem under `agent/`. Each directory is
 
 ### Naming from paths
 
-Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
+eve derives names from file paths, so you do not configure them separately.
 
 | Path                                  | Resolves to           |
 | ------------------------------------- | --------------------- |
@@ -65,7 +67,7 @@ Identity comes from the path. You never write a `name` or `id` field on a `defin
 | `agent/skills/summarize.md`           | skill `summarize`     |
 | `agent/subagents/researcher/agent.ts` | subagent `researcher` |
 
-The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory.
+The root agent uses its `package.json` `name`, or its app directory name if none is set. A subagent uses its directory name.
 
 ### Recommended layout
 
@@ -93,31 +95,29 @@ my-agent/
 
 Evals live beside `agent/`, not inside it.
 
-### Authored slots
-
-The Subagents column states whether a local subagent (`subagents/<id>/`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots.
-
-| Path                                                    | Description                               | Subagents | Notes                                                                                                                                                                             |
-| ------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent.ts`                                              | Runtime config                            | Yes       | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config).                                                                                 |
-| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Optional  | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents.         |
-| `instrumentation.ts`                                    | Telemetry config                          | No        | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only.                                                                                     |
-| `channels/`                                             | HTTP and messaging entry points           | No        | Root-only.                                                                                                                                                                        |
-| `connections/`                                          | External MCP and OpenAPI services         | Yes       | One connection per file; its name comes from the filename.                                                                                                                        |
-| `hooks/`                                                | Lifecycle and stream-event subscribers    | Yes       | Module-backed only. Recursive directories are supported.                                                                                                                          |
-| `skills/`                                               | On-demand procedures and capability packs | Yes       | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback.                         |
-| `lib/`                                                  | Shared authored helper code               | Yes       | Import-only; not mounted into the workspace.                                                                                                                                      |
-| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                | Yes       | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
-| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes       | Mirrored into `/workspace/` when a session starts.                                                                                                                                |
-| `tools/`                                                | Typed executable integrations             | Yes       | Module-backed only.                                                                                                                                                               |
-| `schedules/`                                            | Recurring jobs                            | No        | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only.                              |
-| `subagents/`                                            | Specialist child agents                   | Yes       | Each child is a local package under `subagents/<id>/`. Nested subagents are supported.                                                                                            |
-
-### Runtime files and source files
-
-eve does not mount the whole authored tree into the runtime sandbox. Files under `agent/sandbox/workspace/**` land in `/workspace/` when a session starts.
-
-Skill package files land outside the workspace under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback when `$HOME` is unavailable. Everything in `lib/` remains import-only source code.
+### Agent files and directories
+
+Each path under `agent/` has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked **Yes**.
+
+| Path                                                    | Use                                       | Available to subagents | Notes                                                                                                                                                                             |
+| ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts`                                              | Runtime config                            | Yes                    | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config).                                                                                 |
+| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Optional               | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents.         |
+| `instrumentation.ts`                                    | Telemetry config                          | No                     | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only.                                                                                     |
+| `channels/`                                             | HTTP and messaging entry points           | No                     | Root-only.                                                                                                                                                                        |
+| `connections/`                                          | External MCP and OpenAPI services         | Yes                    | One connection per file; its name comes from the filename.                                                                                                                        |
+| `hooks/`                                                | Lifecycle and stream-event subscribers    | Yes                    | Module-backed only. Recursive directories are supported.                                                                                                                          |
+| `skills/`                                               | On-demand procedures and capability packs | Yes                    | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback.                         |
+| `lib/`                                                  | Shared authored helper code               | Yes                    | Import-only; not mounted into the workspace.                                                                                                                                      |
+| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                | Yes                    | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
+| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes                    | Mirrored into `/workspace/` when a session starts.                                                                                                                                |
+| `tools/`                                                | Typed executable integrations             | Yes                    | Module-backed only.                                                                                                                                                               |
+| `schedules/`                                            | Recurring jobs                            | No                     | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only.                              |
+| `subagents/`                                            | Specialist child agents                   | Yes                    | Each child is a local package under `subagents/<id>/`. Nested subagents are supported.                                                                                            |
+
+### Files available in the sandbox
+
+Files under `agent/` define your agent; only files in `agent/sandbox/workspace/` are copied to `/workspace/` when a session starts.
 
 ### Local subagents
 

package/docs/guides/auth-and-route-protection.md

@@ -223,7 +223,7 @@ Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment va
 
 ## Accepting forwarded identity from another deployment
 
-A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) asserts its end user's principal on the create-session request as a `forwardedPrincipal` body field. By default every such assertion is rejected with `403` — accepting someone else's word for who the user is requires naming exactly which forwarders you trust. Do that with `trustedForwarders` on `eveChannel`:
+A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) asserts its end user's principal on create and continuation requests as a `forwardedPrincipal` body field. By default every such assertion is rejected with `403` — accepting someone else's word for who the user is requires naming exactly which forwarders you trust. Do that with `trustedForwarders` on `eveChannel`:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
@@ -239,7 +239,11 @@ export default eveChannel({
 
 The predicate authorizes the _forwarder_ (the verified route-auth principal — who is asserting), not the forwarded principal (what is asserted). Match it precisely: a permissive predicate like `() => true` lets any caller that passes route auth assert any principal, including preview deployments of your own project when `vercelOidc()` is in the walk. `trustedForwarders` exists only on your authored channel — the framework default channel never accepts a forwarded principal, so a receiving deployment must author `agent/channels/eve.ts`.
 
-When the predicate accepts, the forwarded principal replaces the session principal: `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly, so user-scoped connections, local subagents, and further `forwardPrincipal` hops all see that user. The forwarder is recorded on the accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller. The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+
+> ⚠️ Both deployments must support continuation forwarding before you resume persistent remote sessions. A create-only receiver rejects a forwarded continuation with HTTP 400; the sender does not fall back to service authority. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity) for the upgrade behavior.
+
+Persistent sessions do not preserve caller authority between turns. Every accepted follow-up replaces `auth.current`, including replacing it with no authenticated caller on internal local delivery; per-user connection lookup is then keyed from that current principal. This prevents a later caller from resolving a prior caller's OAuth grant. It does not hide the persistent session's conversation history or artifacts from a caller who is otherwise allowed to continue that session; session ownership remains an application policy.
 
 ## What reaches `ctx.session.auth`
 

package/docs/guides/dynamic-capabilities.md

@@ -132,7 +132,7 @@ approval checks.
 
 ## Dynamic tools
 
-Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. The wrapper stamps them so their `execute` functions survive workflow step boundaries.
+Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. eve records durable descriptors for `execute`, approval request and response policies, and `toModelOutput`, so a parked call can reconstruct the same callbacks in a fresh process.
 
 Dynamic tool executors receive the same `ToolContext` as static authored tools, including inline provider auth through `ctx.getToken(provider)` and `ctx.requireAuth(provider)`.
 
@@ -160,11 +160,13 @@ export default defineDynamic({
 });
 ```
 
-### Prefer an inline `execute` function
+### Author replayable callbacks
 
-Write `execute` as an inline function expression, arrow, or method shorthand placed directly as the property value. The bundler transform stores the function and its closure variables for durable replay without rerunning the resolver.
+Write callback properties as inline function expressions, arrows, method shorthand, or module-level function references. eve transforms authored modules that import `defineTool`, including helper modules outside `agent/tools/`, and stores each callback's referenced closure values independently.
 
-The transform does not detect `execute: myFn`, `execute: makeFn()`, or executors created inside an imported dependency. For a `session.started` tool, eve can reconstruct these live functions by rerunning the owning resolver after a durable resume. Keep session resolvers idempotent and avoid unnecessary side effects. A `turn.started` tool still requires an inline executor to survive a fresh runtime.
+Closure values must be JSON-serializable. Plain objects, arrays, strings, finite numbers, booleans, and `null` are supported; `undefined` object properties are omitted. Functions, class instances, `Date`, `Map`, symbols, non-finite numbers, and cyclic values fail resolution with the tool name and callback phase instead of being serialized lossily.
+
+Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve-provided factories may also supply pre-registered callbacks. eve rejects a dynamic tool if any present callback lacks durable metadata, and replay never reruns the current resolver to recover one.
 
 ### Naming
 
@@ -181,13 +183,13 @@ A dynamic tool or skill whose name matches an **authored** one **overrides** it
 
 ### Events
 
-| Event             | Resolver runs                              | Tools available for             |
-| ----------------- | ------------------------------------------ | ------------------------------- |
-| `session.started` | At session start; sometimes after a pause¹ | Every model call in the session |
-| `turn.started`    | Once per turn                              | Every model call in the turn    |
-| `step.started`    | Before each model call                     | That model call                 |
+| Event             | Resolver runs                                         | Tools available for             |
+| ----------------- | ----------------------------------------------------- | ------------------------------- |
+| `session.started` | At session start; may be redelivered during recovery¹ | Every model call in the session |
+| `turn.started`    | Once per turn                                         | Every model call in the turn    |
+| `step.started`    | Before each model call                                | That model call                 |
 
-¹ If a session pauses to wait for approval or other input, eve may run the resolver again when the session continues. Design session resolvers so they can safely run more than once. They do not run before every model call.
+¹ Workflow recovery can redeliver a resolver event, so keep resolvers idempotent. Replaying a parked callback does not depend on running the resolver again.
 
 ### Execution order