eve 0.68.0 → 0.70.0

package/dist/src/execution/settle-cancelled-turn-step.d.ts

@@ -1,18 +1,31 @@
-import { type DurableSessionState } from "#execution/durable-session-store.js";
+import type { DurableSessionState } from "#execution/durable-session-store.js";
+import { type SessionHistoryStepState } from "#execution/publish-session-events.js";
+import { type WithSessionStateDelta } from "#execution/session/state-delta.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
 import type { TokenUsage } from "#shared/token-usage.js";
 export interface CancelledTurnSettleResult {
     readonly serializedContext: Record<string, unknown>;
     readonly sessionState: DurableSessionState;
+    readonly history: HarnessModelMessage[];
+    /** What the session spent since its caller's last report, when asked to report it. */
     readonly usage?: TokenUsage;
 }
+/** Takes the history because the turn's pending calls move into it, each answered as cancelled. */
+interface CancelledTurnSettleInput extends SessionHistoryStepState {
+    /**
+     * Whether a caller receives the turn's usage. Only then is it marked
+     * reported; otherwise the next settled turn reports it.
+     */
+    readonly reportUsage: boolean;
+}
 /**
- * Settles one cancelled turn: emits `turn.cancelled` → `session.waiting`,
- * drops pending coordination state, and persists the between-turns
- * session. Runs in the owner, whose wake sources exclude the
- * cancel hook, so a queued cancel wake cannot re-dispatch it.
+ * Settles one cancelled turn: relays `input.resolved` for every request the
+ * session proxies, emits `turn.cancelled` → `session.waiting`, drops pending
+ * coordination state, and persists the between-turns session. Runs in the
+ * owner, whose wake sources exclude the cancel hook, so a queued cancel wake
+ * cannot re-dispatch it.
  */
-export declare function settleCancelledTurnStep(input: {
-    readonly sessionWritable: WritableStream<Uint8Array>;
-    readonly serializedContext: Record<string, unknown>;
-    readonly sessionState: DurableSessionState;
-}): Promise<CancelledTurnSettleResult>;
+export declare function settleCancelledTurnStep(input: CancelledTurnSettleInput): Promise<WithSessionStateDelta<CancelledTurnSettleResult>>;
+/** {@link settleCancelledTurnStep} for a caller that is already a step and adopts the whole state. */
+export declare function settleCancelledTurn(input: CancelledTurnSettleInput): Promise<CancelledTurnSettleResult>;
+export {};

package/dist/src/execution/settle-cancelled-turn-step.js

@@ -1 +1 @@
-import{TurnDeliveryIdsKey}from"#context/keys.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{getHarnessEmissionState,isHarnessBetweenTurns,setHarnessEmissionState}from"#harness/emission.js";import{clearPendingCoordinationBatch,getPendingCoordinationBatch}from"#harness/coordination.js";import{deserializeContext,serializeContext}from"#context/serialize.js";import{createDurableSessionState,readDurableSession}from"#execution/durable-session-store.js";import{getBlockingWorkflowToolRuns,removeBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{resolveEffectiveAgentRuntime}from"#execution/effective-agent-config.js";import{hydrateDurableSession}from"#execution/session.js";import{buildAdapterContext}from"#channel/adapter-context.js";import{withContextScope}from"#context/run-step.js";import{activeTurnId}from"#harness/active-turn-id.js";import{clearAllProxyInputRequests,getProxyInputRequests,hasProxyInputRequests}from"#harness/proxy-input-requests.js";import{publishChannelEvent}from"#execution/publish-channel-event.js";import{observeSessionActivity}from"#execution/session-activity-projection.js";import{getTurnUsageState,toUsage}from"#harness/turn-tag-state.js";import{clearPendingSessionLimitPrompt}from"#harness/input-requests.js";import{bindSessionInstrumentation}from"#instrumentation/runtime.js";import{reconcileSessionContinuationToken}from"#execution/reconcile-session-continuation-token.js";import{emitCancelledTurn}from"#harness/cancelled-turn-emission.js";import{abandonAgentInvocationOwners,abandonRunningAgentTurns}from"#subagents/handles/transitions.js";async function settleCancelledTurnStep(e){"use step";let t=readDurableSession(e.sessionState),n=await deserializeContext(e.serializedContext),r=n.require(ChannelKey),i=buildAdapterContext(r,n),a=n.require(BundleKey),o=resolveEffectiveAgentRuntime(a,n),s=hydrateDurableSession({compactionOverrides:{thresholdPercent:o.thresholdPercent},durable:t,turnAgent:o.turnAgent}),c=bindSessionInstrumentation({agentName:o.turnAgent.id,ctx:n,rootSessionId:s.rootSessionId??s.sessionId,sessionId:s.sessionId}),l=getHarnessEmissionState(t.state),u=[...getProxyInputRequests(t.state).values()].some(e=>e.kind===`session-limit`);if(!(isHarnessBetweenTurns(s)&&hasProxyInputRequests(t.state)&&!u)){let t=e.sessionWritable.getWriter();try{let e=await withContextScope(n,s,async e=>{let baseEmit=async e=>{let a=await publishChannelEvent({adapter:r,adapterCtx:i,ctx:n,writer:t,event:e,deliveryIds:n.get(TurnDeliveryIdsKey)});observeSessionActivity({ctx:n,event:a,sessionId:s.sessionId})},a=c?.createHandleEvent({handleEvent:baseEmit,turnId:activeTurnId(l)})??baseEmit;return{result:await emitCancelledTurn(a,l),session:e}});l=e.result,s=e.session}finally{await c?.flush(),t.releaseLock()}}let d=getPendingCoordinationBatch(s.state)?.event.turnId??e.sessionState.emissionState.turnId,f=getBlockingWorkflowToolRuns(s.state,d);s=abandonAgentInvocationOwners(s,new Set(f.map(e=>e.address.runId)));let p=reconcileSessionContinuationToken(n,setHarnessEmissionState(clearPendingSessionLimitPrompt(clearAllProxyInputRequests(clearPendingCoordinationBatch(removeBlockingWorkflowToolRuns(abandonRunningAgentTurns({...s,outputSchema:void 0}),d)))),l)),m=getTurnUsageState(s.state)?.session,h={serializedContext:serializeContext(n),sessionState:createDurableSessionState({session:p})};return m===void 0?h:{...h,usage:toUsage(m)}}export{settleCancelledTurnStep};
+import{createInputResolvedEvent}from"#protocol/message.js";import{getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";import{getSessionUsage,getTurnUsageState,takeSessionUsageDelta}from"#harness/turn-tag-state.js";import{commitCancelledCoordinationBatch,getPendingCoordinationBatch}from"#harness/coordination.js";import{removeBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{publishFromSessionStep,restoreSessionStep}from"#execution/publish-session-events.js";import{withSessionStateDelta}from"#execution/session/state-delta.js";import{clearPendingSessionLimitPrompt}from"#harness/input-requests.js";import{relayWithdrawnRequests}from"#execution/tools/workflow/withdraw-step.js";import{emitCancelledTurn}from"#harness/cancelled-turn-emission.js";import{declinedSignInEvents,withdrawHeldSignIns}from"#harness/held-requests.js";import{cancelApprovalInputBatches,getPendingApprovalRequests}from"#harness/hitl/approval-input-requests.js";const CANCELLED_REASON=`Cancelled.`;async function settleCancelledTurnStep(e){"use step";return await withSessionStateDelta(e,settleCancelledTurn)}async function settleCancelledTurn(e){let t=await relayWithdrawnRequests(e,()=>!0),n={...await restoreSessionStep({...t,sessionWritable:e.sessionWritable}),history:e.history},r=n.durableSession.state,i={completedAt:Date.now(),reason:CANCELLED_REASON},a=withdrawHeldSignIns(r,i),o=getPendingApprovalRequests(r),{published:s,result:c}=await publishFromSessionStep(n,{origin:`own`,async publish(e){let t=getHarnessEmissionState(r);for(let n of declinedSignInEvents(a.withdrawn,CANCELLED_REASON,t))await e(n);return o.length>0&&await e(createInputResolvedEvent({resolutions:o.map(e=>({kind:e.kind,outcome:`cancelled`,requestId:e.requestId})),sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId})),await emitCancelledTurn(e,t,getSessionUsage(n.durableSession))},updateSession(t,n){let r={...t,state:withdrawHeldSignIns(t.state,i).state},a=getPendingCoordinationBatch(r.state)?.event.turnId??e.sessionState.emissionState.turnId,o=setHarnessEmissionState(clearPendingSessionLimitPrompt(cancelApprovalInputBatches(commitCancelledCoordinationBatch(removeBlockingWorkflowToolRuns({...r,outputSchema:void 0},a)))),n);if(!e.reportUsage||getTurnUsageState(r.state)===void 0)return{session:o};let s=takeSessionUsageDelta(o);return{result:s.delta,session:s.session}}});return c===void 0?s:{...s,usage:c}}export{settleCancelledTurn,settleCancelledTurnStep};

package/dist/src/execution/stable-workflow-names.d.ts

@@ -1,5 +1,4 @@
 export declare const WORKFLOW_ENTRY_NAME = "workflowEntry";
 export declare const SESSION_TIMEOUT_WORKFLOW_NAME = "sessionTimeoutWorkflow";
 export declare const WORKFLOW_TOOL_RUN_WORKFLOW_NAME = "workflowToolRunWorkflow";
-export declare const ACTIVITY_COLLECTOR_WORKFLOW_NAME = "activityCollectorWorkflow";
 export declare const STABLE_WORKFLOW_NAMES: ReadonlySet<string>;

package/dist/src/execution/stable-workflow-names.js

@@ -1 +1 @@
-const WORKFLOW_ENTRY_NAME=`workflowEntry`,SESSION_TIMEOUT_WORKFLOW_NAME=`sessionTimeoutWorkflow`,WORKFLOW_TOOL_RUN_WORKFLOW_NAME=`workflowToolRunWorkflow`,ACTIVITY_COLLECTOR_WORKFLOW_NAME=`activityCollectorWorkflow`,STABLE_WORKFLOW_NAMES=new Set([WORKFLOW_ENTRY_NAME,`turnWorkflow`,SESSION_TIMEOUT_WORKFLOW_NAME,WORKFLOW_TOOL_RUN_WORKFLOW_NAME,ACTIVITY_COLLECTOR_WORKFLOW_NAME]);export{ACTIVITY_COLLECTOR_WORKFLOW_NAME,SESSION_TIMEOUT_WORKFLOW_NAME,STABLE_WORKFLOW_NAMES,WORKFLOW_ENTRY_NAME,WORKFLOW_TOOL_RUN_WORKFLOW_NAME};
+const WORKFLOW_ENTRY_NAME=`workflowEntry`,SESSION_TIMEOUT_WORKFLOW_NAME=`sessionTimeoutWorkflow`,WORKFLOW_TOOL_RUN_WORKFLOW_NAME=`workflowToolRunWorkflow`,STABLE_WORKFLOW_NAMES=new Set([WORKFLOW_ENTRY_NAME,`turnWorkflow`,SESSION_TIMEOUT_WORKFLOW_NAME,WORKFLOW_TOOL_RUN_WORKFLOW_NAME]);export{SESSION_TIMEOUT_WORKFLOW_NAME,STABLE_WORKFLOW_NAMES,WORKFLOW_ENTRY_NAME,WORKFLOW_TOOL_RUN_WORKFLOW_NAME};

package/dist/src/execution/tasks/calls.d.ts

@@ -0,0 +1,42 @@
+import type { ModelMessage } from "ai";
+import type { RuntimeToolResultActionResult } from "#shared/action-types.js";
+import type { JsonValue } from "#shared/json.js";
+/**
+ * Calls to the task tools. They defer out of the model step like
+ * workflow tool calls; the session answers them instead of a workflow run.
+ */
+export type TaskToolCall = {
+    readonly callId: string;
+    readonly kind: "task_wait";
+    readonly timeoutMs?: number;
+} | {
+    readonly callId: string;
+    readonly kind: "task_cancel";
+    readonly taskId: string;
+};
+/**
+ * The task tool calls a parked step's response still waits on. The response
+ * is the one record of these calls: a call without a result is pending, and
+ * a call with invalid input already carries its error result. The names are
+ * reserved, so no authored tool's call matches.
+ */
+export declare function pendingTaskToolCalls(messages: readonly ModelMessage[]): TaskToolCall[];
+/** Why a `task_wait` call, or a held turn, stopped waiting. */
+export type TaskWaitResult = {
+    readonly status: "settled";
+    /** Tasks whose results follow; both lists are empty when nothing was working. */
+    readonly settled: readonly {
+        readonly id: string;
+        readonly status: "completed" | "failed";
+    }[];
+    readonly working: readonly string[];
+} | {
+    readonly status: "timeout" | "interrupt";
+    readonly working: readonly string[];
+};
+export interface TaskCancelResult {
+    readonly resumable: boolean;
+    readonly status: "cancelled" | "already_finished";
+    readonly tool: string;
+}
+export declare function taskToolResult(callId: string, toolName: string, output: JsonValue): RuntimeToolResultActionResult;

package/dist/src/execution/tasks/calls.js

@@ -0,0 +1 @@
+import{TASK_CANCEL_TOOL_NAME,TASK_WAIT_TOOL_NAME}from"#protocol/task-tools.js";function pendingTaskToolCalls(e){let t=new Set;for(let n of e)if(typeof n.content!=`string`)for(let e of n.content)e.type===`tool-result`&&t.add(e.toolCallId);let n=[];for(let r of e)if(r.role===`assistant`&&typeof r.content!=`string`)for(let e of r.content){if(e.type!==`tool-call`||t.has(e.toolCallId))continue;let r=typeof e.input==`object`&&e.input!==null?e.input:{};if(e.toolName===TASK_CANCEL_TOOL_NAME){let t=String(Reflect.get(r,`taskId`));n.push({callId:e.toolCallId,kind:`task_cancel`,taskId:t})}else if(e.toolName===TASK_WAIT_TOOL_NAME){let t=Reflect.get(r,`timeoutSeconds`);n.push(typeof t==`number`?{callId:e.toolCallId,kind:`task_wait`,timeoutMs:t*1e3}:{callId:e.toolCallId,kind:`task_wait`})}}return n}function taskToolResult(e,t,n){return{callId:e,kind:`tool-result`,output:n,toolName:t}}export{pendingTaskToolCalls,taskToolResult};

package/dist/src/execution/tasks/model-step.d.ts

@@ -0,0 +1,58 @@
+import type { ModelMessage, SystemModelMessage } from "ai";
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import { type HarnessModelMessage } from "#harness/messages.js";
+import type { HarnessSession, HarnessToolMap } from "#harness/types.js";
+import type { WorkflowToolCallEntry } from "#shared/action-types.js";
+import type { JsonObject } from "#shared/json.js";
+export declare function isTaskTool(definition: HarnessToolDefinition | undefined): boolean;
+/** Whether the agent can start tasks, so the task tools and system block are offered. */
+export declare function offersTasks(tools: HarnessToolMap): boolean;
+/** Adds `task_wait` and `task_cancel` to a tool set that can start tasks. */
+export declare function withTaskTools(tools: HarnessToolMap): HarnessToolMap;
+/**
+ * The task block, when the agent can start tasks. `finalReplyOnly` is set for a
+ * child or schedule session, which hides a held turn's text, so a reply before
+ * a result would reach no one.
+ */
+export declare function taskSystemMessages(tools: HarnessToolMap, options: {
+    readonly finalReplyOnly: boolean;
+}): SystemModelMessage[];
+/** A deferred call as the model made it, before the session knows what it enters. */
+export interface DeferredCall {
+    readonly callId: string;
+    readonly definition: HarnessToolDefinition | undefined;
+    /** The call's model input. */
+    readonly input: JsonObject;
+    readonly toolName: string;
+    readonly turnId: string;
+}
+/** How a deferred call enters its workflow, with the tool's own input. */
+export interface CommittedCallEntry {
+    readonly entry: WorkflowToolCallEntry;
+    readonly input: JsonObject;
+    readonly session: HarnessSession;
+}
+/**
+ * How a deferred call enters its workflow. A call that starts a task commits
+ * the task's record alongside the call, so the run starts with its id; a
+ * `serve` tool's call with `taskId` goes to that task's `receive()`, which the
+ * session checks when it sends the call.
+ */
+export declare function commitCallEntry(session: HarnessSession, call: DeferredCall): CommittedCallEntry;
+export declare function workingTaskIds(session: HarnessSession): readonly string[];
+/**
+ * The messages a model step appends for tasks, before any new input: one
+ * `task.result` message with every settled result, then the
+ * `[Tasks]` note when the listing changed. The results are marked delivered
+ * in the same step. The message lives only in the model's history: clients
+ * read outcomes from `task.settled`.
+ */
+export declare function appendTaskContext(input: {
+    readonly messages: readonly HarnessModelMessage[];
+    readonly projectHistory: (messages: readonly ModelMessage[], state: HarnessSession["state"]) => readonly ModelMessage[];
+    readonly session: HarnessSession;
+    readonly tools: HarnessToolMap;
+}): Promise<{
+    readonly messages: readonly HarnessModelMessage[];
+    readonly session: HarnessSession;
+}>;

package/dist/src/execution/tasks/model-step.js

@@ -0,0 +1 @@
+import{TASK_CANCEL_TOOL_NAME,TASK_WAIT_TOOL_NAME}from"#protocol/task-tools.js";import{createFrameworkUserMessage}from"#harness/messages.js";import{FINAL_REPLY_TASK_SYSTEM_BLOCK,TASKS_NOTE_LABEL,TASK_SYSTEM_BLOCK,renderModelOutputText,renderTaskResults,renderTasksNote}from"#execution/tasks/render.js";import{createTask,idleTasks,readTaskTable,takeTaskResults,workingTasks,writeTaskTable}from"#execution/tasks/table.js";import{splitTaskIdInput}from"#execution/tasks/task-id-input.js";import{entryPointOf,isAgentTool,startsTasks}from"#execution/tasks/tool-entry-point.js";import{taskCancelTool}from"#tools/provided/task-cancel.js";import{taskWaitTool}from"#tools/provided/task-wait.js";function isTaskTool(e){return e?.frameworkAction===`task-wait`||e?.frameworkAction===`task-cancel`}function offersTasks(e){for(let t of e.values())if(startsTasks(t))return!0;return!1}function withTaskTools(e){return offersTasks(e)?new Map([...e,[TASK_WAIT_TOOL_NAME,taskWaitTool],[TASK_CANCEL_TOOL_NAME,taskCancelTool]]):e}function taskSystemMessages(e,t){return offersTasks(e)?[{content:t.finalReplyOnly?FINAL_REPLY_TASK_SYSTEM_BLOCK:TASK_SYSTEM_BLOCK,role:`system`}]:[]}function commitCallEntry(e,t){let n=entryPointOf(t.definition);switch(n){case`execute`:return{entry:{entryPoint:n},input:t.input,session:e};case`task`:return commitTask(e,t,n,t.input);case`serve`:{let{input:r,taskId:i}=splitTaskIdInput(t.input);return i===void 0?commitTask(e,t,n,r):{entry:{entryPoint:`receive`,taskId:i},input:r,session:e}}}}function commitTask(e,t,n,r){let i=createTask(readTaskTable(e.state),{callId:t.callId,kind:isAgentTool(t.definition)?`agent`:`tool`,name:t.toolName,resumable:n===`serve`,turnId:t.turnId});return{entry:{entryPoint:n,taskId:i.taskId},input:r,session:writeTaskTable(e,i.table)}}function workingTaskIds(e){return workingTasks(readTaskTable(e.state)).map(e=>e.id)}async function appendTaskContext(e){let t=[],n=await deliverTaskResults(e);n.message!==void 0&&t.push(createFrameworkUserMessage(`task.result`,n.message));let r=resolveTasksNote({messages:e.projectHistory([...e.messages,...t],n.session.state),session:n.session});return r!==void 0&&t.push(createFrameworkUserMessage(`context.state`,r)),{messages:t,session:n.session}}async function deliverTaskResults(e){let{table:t,taken:n}=takeTaskResults(readTaskTable(e.session.state));if(n.length===0)return{session:e.session};let r=[];for(let t of n)for(let n of t.results)r.push(await toResultBlock(t,n,e.tools.get(t.name)));return{message:renderTaskResults(r),session:writeTaskTable(e.session,t)}}async function toResultBlock(e,t,n){let r={taskId:e.id,tool:e.name};return t.status===`failed`?{...r,body:t.error,status:`failed`}:{...r,body:await projectOutput(t.output,n),status:`completed`}}async function projectOutput(e,t){if(t?.toModelOutput===void 0)return renderModelOutputText(e);try{return renderModelOutputText(await t.toModelOutput(e))}catch{return renderModelOutputText(e)}}function resolveTasksNote(e){let t=readTaskTable(e.session.state),n=workingTasks(t).map(toListedTask),r=idleTasks(t).map(toListedTask),i=e.messages.findLast(isTasksNote);if(i===void 0&&n.length===0&&r.length===0)return;let a=renderTasksNote({idle:r,working:n});return i?.content===a?void 0:a}function toListedTask(e){return{id:e.id,tool:e.name}}function isTasksNote(e){return e.role===`user`&&typeof e.content==`string`&&e.content.startsWith(TASKS_NOTE_LABEL)}export{appendTaskContext,commitCallEntry,isTaskTool,offersTasks,taskSystemMessages,withTaskTools,workingTaskIds};

package/dist/src/execution/tasks/render.d.ts

@@ -0,0 +1,66 @@
+import type { TaskCancelResult, TaskWaitResult } from "#execution/tasks/calls.js";
+export declare const TASK_WAIT_DESCRIPTION = "Call task_wait sparingly, only when you deliberately want to withhold a message from the user while waiting for a task result. Tasks keep running and their results reach you without calling task_wait. If the user should hear from you now, reply instead. Wait silently until any of your tasks has a result, a new message arrives, or timeoutSeconds pass. It returns after the first result, which follows in a <task_result> message; wait again only if you still want to withhold a reply until another result arrives. Waiting never stops a task.";
+export declare const TASK_WAIT_TIMEOUT_DESCRIPTION = "Optional. Seconds to wait before returning without a result. Omit it to wait for a result or a new message, which is almost always right. Don't use short timeouts to check on tasks: results reach you without checking.";
+export declare const TASK_CANCEL_DESCRIPTION = "Stop a task's current work. That work never reports back; if it already had a result, that result is still delivered. An agent, or any task that accepts more input, stays available: call its tool with its taskId to give it new work.";
+export declare const TASK_CANCEL_TASK_ID_DESCRIPTION = "The id of the task to stop, copied from its \"Started task\" receipt or the [Tasks] note.";
+/** The task block for a session a person reads, where a reply before a result is posted. */
+export declare const TASK_SYSTEM_BLOCK: string;
+/** The task block for a child or schedule session, whose caller reads only the final reply. */
+export declare const FINAL_REPLY_TASK_SYSTEM_BLOCK: string;
+/** Appended to a `serve` tool's description. */
+export declare const SERVE_TOOL_DESCRIPTION = "To send this task more input, call this tool again with its taskId; without taskId, each call starts a new task.";
+/** Appended to an agent tool's description, in place of the `serve` tool sentence. */
+export declare const AGENT_SERVE_TOOL_DESCRIPTION = "It does not see this conversation, so put everything it needs in message. To correct or continue an agent task, call this tool again with its taskId; without taskId, each call starts a new agent.";
+/** Describes the `taskId` eve adds to a `serve` tool's model input. */
+export declare const TASK_ID_INPUT_DESCRIPTION = "The id of a task this tool started, copied from its \"Started task\" receipt or the [Tasks] note, to send it this input. Omit it to start a new task.";
+/** Labels the `context.state` note that lists the turn's tasks. */
+export declare const TASKS_NOTE_LABEL = "[Tasks]";
+/** Opens every block of a `task.result` message. */
+export declare const TASK_RESULT_TAG = "<task_result";
+/** The failure a task reports when its record could not be decoded. */
+export declare const UNREADABLE_TASK_ERROR = "The task's state could not be read.";
+/** The receipt for a call that starts a task; a resumable task's says how to reach it again. */
+export declare function renderTaskReceipt(task: {
+    readonly id: string;
+    readonly resumable: boolean;
+    readonly tool: string;
+}): string;
+/** The receipt for a call that reaches a resumable task by its `taskId`. */
+export declare function renderTaskSentReceipt(taskId: string): string;
+export declare function renderUnknownTaskError(taskId: string, tool: string): string;
+export declare function renderUnknownCancelTaskError(taskId: string): string;
+/** What the model reads when `task_cancel` answers. */
+export declare function renderTaskCancelResult(taskId: string, result: TaskCancelResult): string;
+export declare function renderTooManyTasksError(max: number, workingIds: readonly string[]): string;
+export declare function renderFinalOutputWhileWorkingError(workingIds: readonly string[]): string;
+/** What the model reads when `task_wait` returns after waiting `waitedMs`. */
+export declare function renderTaskWaitResult(result: TaskWaitResult, waitedMs: number): string;
+/** One `<task_result>` block of a `task.result` message. */
+export interface TaskResultBlock {
+    readonly body: string;
+    readonly status: "completed" | "failed";
+    readonly taskId: string;
+    readonly tool: string;
+}
+/**
+ * The `task.result` message: one `<task_result>` block per result. All
+ * bodies share one size budget; a body past it is cut and marked.
+ */
+export declare function renderTaskResults(results: readonly TaskResultBlock[]): string;
+/**
+ * The blocks of a `task.result` message, in order, as a deterministic mock
+ * model reads them back; empty for any other text.
+ */
+export declare function readTaskResults(message: string): TaskResultBlock[];
+/** The text of a tool's `toModelOutput` result, or of a raw output without one. */
+export declare function renderModelOutputText(output: unknown): string;
+/** A task as the `[Tasks]` note lists it. */
+export interface ListedTask {
+    readonly id: string;
+    readonly tool: string;
+}
+/** The `[Tasks]` note: working tasks, then idle resumable tasks when there are any. */
+export declare function renderTasksNote(input: {
+    readonly idle: readonly ListedTask[];
+    readonly working: readonly ListedTask[];
+}): string;

package/dist/src/execution/tasks/render.js

@@ -0,0 +1,8 @@
+import{formatDuration}from"#shared/format-duration.js";const TASK_WAIT_DESCRIPTION=`Call task_wait sparingly, only when you deliberately want to withhold a message from the user while waiting for a task result. Tasks keep running and their results reach you without calling task_wait. If the user should hear from you now, reply instead. Wait silently until any of your tasks has a result, a new message arrives, or timeoutSeconds pass. It returns after the first result, which follows in a <task_result> message; wait again only if you still want to withhold a reply until another result arrives. Waiting never stops a task.`,TASK_WAIT_TIMEOUT_DESCRIPTION=`Optional. Seconds to wait before returning without a result. Omit it to wait for a result or a new message, which is almost always right. Don't use short timeouts to check on tasks: results reach you without checking.`,TASK_CANCEL_DESCRIPTION=`Stop a task's current work. That work never reports back; if it already had a result, that result is still delivered. An agent, or any task that accepts more input, stays available: call its tool with its taskId to give it new work.`,TASK_ID_SOURCE=`copied from its "Started task" receipt or the [Tasks] note`,TASK_CANCEL_TASK_ID_DESCRIPTION=`The id of the task to stop, ${TASK_ID_SOURCE}.`,TASK_SYSTEM_BLOCK_OPENING=[`Tasks`,`- A call that returns "Started task <id>" is a task: it keeps working while you continue. Every agent call is a task.`,`- Each result arrives once, in a <task_result> message. Until then you know nothing about it, so don't guess or report its result.`,`- Ending your reply doesn't end your turn. While tasks work, eve holds your turn and calls you again with each result.`],TASK_SYSTEM_BLOCK_CLOSING=[`- Don't redo work you delegated. Never use sleep or shell commands to wait for a task.`,`- To correct or continue an agent, or any task that accepts more input, call its tool again with its taskId. A new message never stops your tasks: answer it if it asks you something, decide whether it changes the work, then keep each task, correct an agent by taskId, or stop a task with task_cancel.`],TASK_SYSTEM_BLOCK=[...TASK_SYSTEM_BLOCK_OPENING,`- If you have nothing to tell the person until a result arrives, call task_wait. Start every independent task first, then wait.`,`- If the person should hear from you now, for example to confirm work is underway when they don't need the result yet, reply. When results arrive, report them without repeating yourself.`,...TASK_SYSTEM_BLOCK_CLOSING].join(`
+`),FINAL_REPLY_TASK_SYSTEM_BLOCK=[...TASK_SYSTEM_BLOCK_OPENING,`- Only your final reply reaches your caller. While tasks work, call task_wait instead of replying. Start every independent task first, then wait.`,...TASK_SYSTEM_BLOCK_CLOSING].join(`
+`),SERVE_TOOL_DESCRIPTION=`To send this task more input, call this tool again with its taskId; without taskId, each call starts a new task.`,AGENT_SERVE_TOOL_DESCRIPTION=`It does not see this conversation, so put everything it needs in message. To correct or continue an agent task, call this tool again with its taskId; without taskId, each call starts a new agent.`,TASK_ID_INPUT_DESCRIPTION=`The id of a task this tool started, ${TASK_ID_SOURCE}, to send it this input. Omit it to start a new task.`,TASKS_NOTE_LABEL=`[Tasks]`,TASK_RESULT_TAG=`<task_result`,UNREADABLE_TASK_ERROR=`The task's state could not be read.`;function renderTaskReceipt(e){let t=`Started task ${e.id}. Its result will arrive in a <task_result> message.`;return e.resumable?`${t} To send it another message, call ${e.tool} again with taskId ${e.id}.`:t}function renderTaskSentReceipt(e){return`Sent to task ${e}. Its reply will arrive in a <task_result> message.`}function renderUnknownTaskError(e,t){return`No task "${e}" is available to ${t}: it may have ended or belong to another tool. Start a new one by calling ${t} without taskId.`}function renderUnknownCancelTaskError(e){return`No task "${e}" is in this session. Copy an id from a "Started task" receipt or the [Tasks] note.`}function renderTaskCancelResult(e,t){return t.status===`already_finished`?`${e} had no work to stop.`:t.resumable?`Stopped ${e}'s current work; it won't report back. To give it new work, call ${t.tool} again with taskId ${e}.`:`Stopped ${e}; it won't report back.`}function renderTooManyTasksError(e,t){return`${String(e)} tasks are already working (${t.join(`, `)}). Wait with task_wait or stop one with task_cancel, then try again.`}function renderFinalOutputWhileWorkingError(e){return`You can't give your final output while tasks you started are working (${e.join(`, `)}). Wait for their results with task_wait, or stop a task with task_cancel, then call final_output.`}function renderTaskWaitResult(e,t){switch(e.status){case`settled`:return renderSettledWait(e.settled,e.working);case`timeout`:return`Stopped waiting after ${formatDuration(t)}; ${countWorking(e.working)}. ${resultsArriveLater(e.working.length)}`;case`interrupt`:return`A new message arrived, so the wait ended after ${formatDuration(t)}; ${countWorking(e.working)}. Read the message, answer it if it asks you something, and decide whether it changes this work: ${interruptChoices(e.working.length)}`}}function renderSettledWait(e,t){if(e.length===0&&t.length===0)return`No tasks are working.`;let n=[];if(e.length>0){let t=e.map(e=>`${e.id} ${e.status}`),r=e.length===1?`its result follows`:`their results follow`;n.push(`${joinList(t)}; ${r}.`)}return t.length>0&&n.push(`${capitalize(countWorking(t))}: ${t.join(`, `)}.`),n.join(` `)}function countWorking(e){return e.length===1?`1 task is still working`:`${String(e.length)} tasks are still working`}function resultsArriveLater(e){return e===1?`Its result arrives before your turn ends; wait again only if you need it now.`:`Their results arrive before your turn ends; wait again only if you need them now.`}function interruptChoices(e){return`${e===1?`keep the task`:`keep the tasks`}, call an agent again with its taskId to correct it, or stop a task with task_cancel.`}function renderTaskResults(e){let t={bytes:51200,lines:2e3};return e.map(e=>{let n=fitToBudget(escapeTaskResultBody(e.body),t),r=`id="${escapeAttribute(e.taskId)}" tool="${escapeAttribute(e.tool)}" status="${e.status}"`;return`${TASK_RESULT_TAG} ${r}>${n}</task_result>`}).join(`
+`)}const TASK_RESULT_BLOCK=RegExp(`${TASK_RESULT_TAG} id="([^"]*)" tool="([^"]*)" status="(completed|failed)">([\\s\\S]*?)</task_result>`,`g`);function readTaskResults(e){return[...e.matchAll(TASK_RESULT_BLOCK)].map(([,e,t,n,r])=>({body:r.replaceAll(`<\\/task_result`,`</task_result`),status:n,taskId:e,tool:t}))}function fitToBudget(e,t){let n=new TextEncoder,r=e.split(`
+`),i=[];for(let e of r){let r=n.encode(e).byteLength+1;if(t.lines===0||r>t.bytes){i.push(`[truncated]`),t.lines=0,t.bytes=0;break}i.push(e),--t.lines,t.bytes-=r}return i.join(`
+`)}function escapeTaskResultBody(e){return e.replaceAll(`</task_result`,`<\\/task_result`)}function renderModelOutputText(e){if(typeof e==`string`)return e;if(isModelOutput(e))switch(e.type){case`text`:return String(e.value);case`json`:return JSON.stringify(e.value);case`content`:return renderContentParts(e.value)}return JSON.stringify(e??null)}function renderContentParts(e){return Array.isArray(e)?e.map(e=>e.type===`text`?String(e.text):`[file: ${typeof e.filename==`string`?e.filename:String(e.mediaType)}]`).join(`
+`):``}function isModelOutput(e){if(typeof e!=`object`||!e)return!1;let t=Reflect.get(e,`type`);return(t===`text`||t===`json`||t===`content`)&&`value`in e}function renderTasksNote(e){let t=[TASKS_NOTE_LABEL,`<tasks>`];for(let n of e.working)t.push(`<task ${listedTaskAttributes(n)} status="working"/>`);if(t.push(`</tasks>`),e.idle.length>0){t.push(`<idle>`);for(let n of e.idle)t.push(`<task ${listedTaskAttributes(n)}/>`);t.push(`</idle>`)}return t.join(`
+`)}function listedTaskAttributes(e){return`id="${escapeAttribute(e.id)}" tool="${escapeAttribute(e.tool)}"`}function joinList(e){return e.length<=1?e.join(``):`${e.slice(0,-1).join(`, `)} and ${e.at(-1)}`}function capitalize(e){return e.charAt(0).toUpperCase()+e.slice(1)}function escapeAttribute(e){return e.replaceAll(`&`,`&amp;`).replaceAll(`"`,`&quot;`).replaceAll(`<`,`&lt;`).replaceAll(`>`,`&gt;`)}export{AGENT_SERVE_TOOL_DESCRIPTION,FINAL_REPLY_TASK_SYSTEM_BLOCK,SERVE_TOOL_DESCRIPTION,TASKS_NOTE_LABEL,TASK_CANCEL_DESCRIPTION,TASK_CANCEL_TASK_ID_DESCRIPTION,TASK_ID_INPUT_DESCRIPTION,TASK_RESULT_TAG,TASK_SYSTEM_BLOCK,TASK_WAIT_DESCRIPTION,TASK_WAIT_TIMEOUT_DESCRIPTION,UNREADABLE_TASK_ERROR,readTaskResults,renderFinalOutputWhileWorkingError,renderModelOutputText,renderTaskCancelResult,renderTaskReceipt,renderTaskResults,renderTaskSentReceipt,renderTaskWaitResult,renderTasksNote,renderTooManyTasksError,renderUnknownCancelTaskError,renderUnknownTaskError};

package/dist/src/execution/tasks/session.d.ts

@@ -0,0 +1,19 @@
+import type { SessionStateCursor } from "#execution/session/state-cursor.js";
+import { type TaskToolCall } from "#execution/tasks/calls.js";
+import { type TaskRunMessage } from "#execution/tasks/steps.js";
+import { type TaskTable } from "#execution/tasks/table.js";
+import type { WorkflowToolRunMessage } from "#execution/tools/workflow/messages.js";
+import type { TaskCancelReason } from "#protocol/message.js";
+import type { RuntimeActionResult } from "#shared/action-types.js";
+/** Whether a run's message changes a task record. */
+export declare function isTaskRunMessage(message: WorkflowToolRunMessage): message is TaskRunMessage;
+/** The session's task table as the workflow body last committed it. */
+export declare function sessionTaskTable(cursor: SessionStateCursor): TaskTable;
+/**
+ * Cancels every working task: `session.cancel()` stops them, and a turn that
+ * ends anyway, such as by failing, cancels the tasks it held on.
+ */
+export declare function cancelWorkingTasks(cursor: SessionStateCursor, reason: Exclude<TaskCancelReason, "task_cancel">): Promise<void>;
+export declare function answerTaskCancel(cursor: SessionStateCursor, call: Extract<TaskToolCall, {
+    readonly kind: "task_cancel";
+}>): Promise<RuntimeActionResult>;

package/dist/src/execution/tasks/session.js

@@ -0,0 +1 @@
+import{TASK_CANCEL_TOOL_NAME,UNKNOWN_TASK_CODE}from"#protocol/task-tools.js";import{renderTaskCancelResult,renderUnknownCancelTaskError}from"#execution/tasks/render.js";import{readTaskTable,taskCancelResult,workingTasks}from"#execution/tasks/table.js";import{taskToolResult}from"#execution/tasks/calls.js";import{cancelTasksStep}from"#execution/tasks/steps.js";function isTaskRunMessage(e){return e.from.taskId===void 0?!1:e.kind===`started`||e.kind===`reply`||e.kind===`usage`||e.kind===`outcome`}function sessionTaskTable(e){return readTaskTable(e.sessionState.snapshot.session.state)}async function cancelWorkingTasks(e,t){let n=workingTasks(sessionTaskTable(e)).map(e=>e.id);n.length!==0&&await e.advance(e=>cancelTasksStep({...e,reason:t,taskIds:n}))}async function answerTaskCancel(e,t){let n=taskCancelResult(sessionTaskTable(e),t.taskId);if(n===void 0){let e={code:UNKNOWN_TASK_CODE,message:renderUnknownCancelTaskError(t.taskId)};return{...taskToolResult(t.callId,TASK_CANCEL_TOOL_NAME,e),isError:!0}}return n.status===`cancelled`&&await e.advance(e=>cancelTasksStep({...e,reason:`task_cancel`,taskIds:[t.taskId]})),taskToolResult(t.callId,TASK_CANCEL_TOOL_NAME,renderTaskCancelResult(t.taskId,n))}export{answerTaskCancel,cancelWorkingTasks,isTaskRunMessage,sessionTaskTable};

package/dist/src/execution/tasks/start.d.ts

@@ -0,0 +1,34 @@
+import { type StartWorkflowTaskInput } from "#execution/tools/workflow/start.js";
+import type { HarnessSessionBase } from "#harness/types.js";
+import { type TaskStartedStreamEvent } from "#protocol/message.js";
+import type { RuntimeToolResultActionResult, WorkflowToolRunEntry } from "#shared/action-types.js";
+type TaskDispatchInput = StartWorkflowTaskInput & {
+    readonly taskId: string;
+};
+/** The call's answer, and the `task.started` event the dispatch step publishes for it. */
+interface TaskDispatchResult {
+    readonly result: RuntimeToolResultActionResult;
+    readonly session: HarnessSessionBase;
+    readonly started?: TaskStartedStreamEvent;
+}
+/** The entry of a run that does a task's work. */
+type TaskRunEntry = Extract<WorkflowToolRunEntry, {
+    readonly taskId: string;
+}>;
+/**
+ * Starts the run for a task its model step committed, once, and answers the
+ * call with its receipt and the `task.started` event the dispatch step
+ * publishes. Runs inside that step, where the task's cap is enforced: past
+ * it, the record is dropped and the call fails.
+ */
+export declare function startTaskRun(input: StartWorkflowTaskInput & {
+    readonly entry: TaskRunEntry;
+}): Promise<TaskDispatchResult>;
+/**
+ * Sends a call to the `serve` task it names by `taskId`. The task must be
+ * available to the tool, and a call that makes an idle task work again
+ * counts toward the cap. The call is recorded, reported as started, and sent
+ * to the task's run, whose body receives it from `receive()`.
+ */
+export declare function sendToTask(input: TaskDispatchInput): Promise<TaskDispatchResult>;
+export {};

package/dist/src/execution/tasks/start.js

@@ -0,0 +1 @@
+import{createLogger,logError}from"#internal/logging.js";import{TOO_MANY_TASKS_CODE,UNKNOWN_TASK_CODE}from"#protocol/task-tools.js";import{createTaskStartedEvent}from"#protocol/message.js";import{renderTaskReceipt,renderTaskSentReceipt,renderTooManyTasksError,renderUnknownTaskError}from"#execution/tasks/render.js";import{MAX_WORKING_TASKS,findTask,isTaskAvailable,isTaskWorking,readTaskTable,recordTaskCall,recordTaskRun,removeTask,workingTasks,writeTaskTable}from"#execution/tasks/table.js";import{startFailureResult,startWorkflowToolCallRun}from"#execution/tools/workflow/start.js";import{sendTaskRunCommands}from"#execution/tasks/steps.js";import{createRuntimeToolResultFromValue}from"#harness/action-result-helpers.js";const log=createLogger(`execution.tasks`);async function startTaskRun(e){let{entry:t,session:n,task:r}=e,{taskId:i}=t,a={...e,taskId:i},o=startReceipt(a,t.entryPoint===`serve`),s=readTaskTable(n.state),c=findTask(s,i);if(c===void 0||!isTaskWorking(c))return{result:o,session:n};let l=tooManyTasks(a,s);if(l!==void 0)return{result:l,session:writeTaskTable(n,removeTask(s,i))};let u;try{u=await startWorkflowToolCallRun(e,t)}catch(e){return logError(log,`task run failed to start`,e,{taskId:i,toolName:r.toolName}),{result:startFailureResult(r,e),session:writeTaskTable(n,removeTask(s,i))}}return{result:o,session:writeTaskTable(n,recordTaskRun(s,i,u)),started:taskStartedEvent(a,c)}}async function sendToTask(e){let{session:t,task:n,taskId:r}=e,i=readTaskTable(t.state),a=findTask(i,r);if(!isTaskAvailable(a,n.toolName))return{result:unknownTaskResult(e),session:t};if(!isTaskWorking(a)){let n=tooManyTasks(e,i);if(n!==void 0)return{result:n,session:t}}let o=recordTaskCall(i,r,{agentContext:e.agentContext,auth:e.auth,callId:n.callId,executeInput:n.executeInput,input:n.input,sequence:e.batchEvent.sequence,stepIndex:e.batchEvent.stepIndex,turnId:e.batchEvent.turnId});return o.send!==void 0&&await sendTaskRunCommands(o.send),{result:toolResult(e,renderTaskSentReceipt(r)),session:writeTaskTable(t,o.table),started:taskStartedEvent(e,a)}}function tooManyTasks(e,t){let n=workingTasks(t).filter(e=>e.run!==void 0);if(n.length<MAX_WORKING_TASKS)return;let r=n.map(e=>e.id);return createRuntimeToolResultFromValue({callId:e.task.callId,isError:!0,output:{code:TOO_MANY_TASKS_CODE,message:renderTooManyTasksError(MAX_WORKING_TASKS,r)},toolName:e.task.toolName})}function unknownTaskResult(e){return createRuntimeToolResultFromValue({callId:e.task.callId,isError:!0,output:{code:UNKNOWN_TASK_CODE,message:renderUnknownTaskError(e.taskId,e.task.toolName)},toolName:e.task.toolName})}function taskStartedEvent(e,t){return createTaskStartedEvent({callId:e.task.callId,kind:t.kind,name:e.task.toolName,taskId:e.taskId,turnId:e.batchEvent.turnId})}function startReceipt(e,t){return toolResult(e,renderTaskReceipt({id:e.taskId,resumable:t,tool:e.task.toolName}))}function toolResult(e,t){return createRuntimeToolResultFromValue({callId:e.task.callId,output:t,toolName:e.task.toolName})}export{sendToTask,startTaskRun};

package/dist/src/execution/tasks/steps.d.ts

@@ -0,0 +1,31 @@
+import { type TaskRunCommands } from "#execution/tasks/table.js";
+import { type SessionStepState } from "#execution/publish-session-events.js";
+import { type SessionStateTransition } from "#execution/session/state-delta.js";
+import type { WorkflowToolRunMessage } from "#execution/tools/workflow/messages.js";
+import { type TaskCancelReason } from "#protocol/message.js";
+/** The messages a task's run sends that change its record. */
+export type TaskRunMessage = Extract<WorkflowToolRunMessage, {
+    readonly kind: "outcome" | "reply" | "started" | "usage";
+}>;
+/** Applies one message from a task's run: started, a reply, usage no reply carried, or the run's outcome. */
+export declare function applyTaskRunMessageStep(input: SessionStepState & {
+    readonly message: TaskRunMessage;
+}): Promise<SessionStateTransition>;
+/**
+ * Cancels tasks: their calls settle as cancelled and their runs are told to
+ * stop. A run ends itself within its cleanup deadline and reports cancelled.
+ * A `task()` run's cancel settles every request it relayed, so the session
+ * withdraws them in the same step and accepts no answer after it. A `serve()`
+ * run withdraws its stretch's questions itself, and the session decides each one.
+ */
+export declare function cancelTasksStep(input: SessionStepState & TaskCancellationInput): Promise<SessionStateTransition>;
+interface TaskCancellationInput {
+    readonly reason: TaskCancelReason;
+    readonly taskIds: readonly string[];
+}
+/**
+ * Sends commands to a task's run, in order. A run that already finished takes
+ * none; its outcome settles any call still waiting.
+ */
+export declare function sendTaskRunCommands(commands: TaskRunCommands): Promise<void>;
+export {};

package/dist/src/execution/tasks/steps.js

@@ -0,0 +1 @@
+import{createTaskSettledEvent}from"#protocol/message.js";import{cancelTask,findTask,finishTaskRun,markTaskRunStarted,readTaskTable,recordTaskRunUsage,settleRemainingTaskCalls,settleTaskCalls,writeTaskTable}from"#execution/tasks/table.js";import{readDurableSession,replaceDurableSessionSnapshot}from"#execution/durable-session-store.js";import{publishSessionEvents,relaySessionEvents}from"#execution/publish-session-events.js";import{withSessionStateDelta}from"#execution/session/state-delta.js";import{withdrawProxyInputRequests}from"#harness/proxy-input-requests.js";import{resumeHook}from"#internal/workflow/runtime.js";import{countRunUsage}from"#execution/agent-sessions/usage.js";import{workflowToolRunFailureOutput}from"#execution/tools/workflow/owner-inbox.js";import{ignoreGoneTarget}from"#execution/tasks/workflow-target.js";async function applyTaskRunMessageStep(e){"use step";return await withSessionStateDelta(e,applyTaskRunMessage)}async function applyTaskRunMessage(e){let{message:t}=e,n=t.from.taskId,r=readDurableSession(e.sessionState);if(n===void 0)return{serializedContext:e.serializedContext,sessionState:e.sessionState};let i=readTaskTable(r.state),a=[],o=[];switch(t.kind){case`started`:{let e=markTaskRunStarted(i,n,t.from.runId);i=e.table,e.held!==void 0&&await sendTaskRunCommands(e.held);break}case`reply`:{({session:r,table:i}=countTaskRunUsage(r,i,n,t));let e={output:t.output,status:`completed`},o=findTask(i,n),s=settleTaskCalls(i,{callIds:t.callIds,outcome:e,taskId:n});i=s.table,a.push(...taskSettledEvents(o,s.settled,e));break}case`usage`:({session:r,table:i}=countTaskRunUsage(r,i,n,t));break;case`outcome`:{({session:r,table:i}=countTaskRunUsage(r,i,n,t));let e=toOutcome(t),s=findTask(i,n),c=settleRemainingTaskCalls(i,n,e);a.push(...taskSettledEvents(s,c.settled,e)),i=finishTaskRun(c.table,n,t.from.runId),{events:o,session:r}=withdrawProxyInputRequests(r,(e,n)=>n.runId===t.from.runId);break}}let s=await relaySessionEvents({...e,sessionState:saveTable(e.sessionState,r,i)},o);return await publishSessionEvents({...e,...s},a)}async function cancelTasksStep(e){"use step";return await withSessionStateDelta(e,cancelTasks)}async function cancelTasks(e){let t=readDurableSession(e.sessionState),n=readTaskTable(t.state),r=[],i=new Set,a={reason:e.reason,status:`cancelled`};for(let t of e.taskIds){let e=findTask(n,t),o=cancelTask(n,t);n=o.table,r.push(...taskSettledEvents(e,o.settled,a)),o.send!==void 0&&(e?.resumable===!1&&i.add(o.send.run.runId),await sendTaskRunCommands(o.send))}let o=withdrawProxyInputRequests(t,(e,t)=>t.runId!==void 0&&i.has(t.runId)),s=await relaySessionEvents({...e,sessionState:saveTable(e.sessionState,o.session,n)},o.events);return await publishSessionEvents({...e,...s},r)}function taskSettledEvents(e,t,n){return e===void 0?[]:t.map(t=>taskSettledEvent(e,t,n))}function taskSettledEvent(e,t,n){let r={callId:t.callId,kind:e.kind,name:e.name,taskId:e.id,turnId:t.turnId};switch(n.status){case`completed`:return createTaskSettledEvent({...r,output:n.output,status:`completed`});case`failed`:return createTaskSettledEvent({...r,error:{message:n.error},status:`failed`});case`cancelled`:return createTaskSettledEvent(n.reason===void 0?{...r,status:`cancelled`}:{...r,cancel:{reason:n.reason},status:`cancelled`})}}async function sendTaskRunCommands(e){for(let t of e.commands)await ignoreGoneTarget(resumeHook(e.run.hookToken,toControlMessage(t)))}function toControlMessage(e){switch(e.kind){case`cancel`:return{kind:`cancel`,reason:`The task was cancelled.`};case`call`:return{call:e.call,kind:`call`}}}function toOutcome(e){switch(e.result.status){case`completed`:return{output:e.result.output,status:`completed`};case`failed`:return{error:failureMessage(e),status:`failed`};case`cancelled`:return{status:`cancelled`}}}function failureMessage(e){let t=workflowToolRunFailureOutput(e);if(typeof t==`string`)return t;let n=typeof t==`object`&&t?Reflect.get(t,`message`):void 0;return typeof n==`string`?n:JSON.stringify(t)}function countTaskRunUsage(e,t,n,r){let i=findTask(t,n)?.run;return r.usage===void 0||i?.runId!==r.from.runId?{session:e,table:t}:{session:countRunUsage(e,r.usage,i.usage),table:recordTaskRunUsage(t,n,r.usage)}}function saveTable(e,t,n){return replaceDurableSessionSnapshot({session:writeTaskTable(t,n),state:e})}export{applyTaskRunMessageStep,cancelTasksStep,sendTaskRunCommands};

package/dist/src/execution/tasks/table.d.ts

@@ -0,0 +1,192 @@
+import type { TaskCancelResult, TaskWaitResult } from "#execution/tasks/calls.js";
+import type { WorkflowToolRunCall } from "#execution/tools/workflow/messages.js";
+import type { SessionStateMap } from "#harness/types.js";
+import type { JsonValue } from "#shared/json.js";
+import type { TokenUsage } from "#shared/token-usage.js";
+import type { TaskCancelReason, TaskStartedStreamEvent } from "#protocol/message.js";
+/** At most this many tasks work at once in one session: a backstop normal use shouldn't reach. */
+export declare const MAX_WORKING_TASKS = 32;
+export interface TaskRunAddress {
+    readonly hookToken: string;
+    readonly runId: string;
+}
+/** The workflow run doing a task's work. `started` once its control hook can take commands. */
+export interface TaskRun extends TaskRunAddress {
+    readonly started: boolean;
+    /** The run's delegated spend the session counted so far, which later totals count from. */
+    readonly usage?: TokenUsage;
+}
+/** A call the task admitted and hasn't settled, with the turn that made it. */
+export interface TaskCall {
+    readonly callId: string;
+    readonly turnId: string;
+}
+/**
+ * A command for a task's run. Commands go over the run's one control hook, so
+ * the run sees calls and cancels in the order the session issued them.
+ */
+export type TaskRunCommand = {
+    readonly kind: "cancel";
+} | {
+    readonly call: WorkflowToolRunCall;
+    readonly kind: "call";
+};
+/** Commands for one run, to send in order. */
+export interface TaskRunCommands {
+    readonly commands: readonly TaskRunCommand[];
+    readonly run: TaskRunAddress;
+}
+/** How a task call ended, as `task.settled` reports it. */
+export type TaskOutcome = {
+    readonly output: JsonValue;
+    readonly status: "completed";
+} | {
+    readonly error: string;
+    readonly status: "failed";
+} | {
+    readonly reason?: TaskCancelReason;
+    readonly status: "cancelled";
+};
+/**
+ * An outcome the model receives, one per reply or run end, however many calls
+ * it settled. Cancelled work never reports back.
+ */
+export type TaskResult = Exclude<TaskOutcome, {
+    readonly status: "cancelled";
+}>;
+export interface TaskRecord {
+    readonly id: string;
+    /** Whether the tool is an agent's, as `task.started` reports it. */
+    readonly kind: TaskStartedStreamEvent["data"]["kind"];
+    /** The tool whose call started the task. */
+    readonly name: string;
+    /** A `serve` tool's task: it takes more calls by its id, and is idle between results. */
+    readonly resumable: boolean;
+    /** Calls without a result. The task is working while any remain. */
+    readonly calls: readonly TaskCall[];
+    /** Results not yet delivered to the model. */
+    readonly results: readonly TaskResult[];
+    /** The task's run, from its start until it finishes. */
+    readonly run?: TaskRun;
+    /** Commands issued before the run could take them, sent in order once it reports started. */
+    readonly held?: readonly TaskRunCommand[];
+}
+export interface TaskTable {
+    readonly tasks: readonly TaskRecord[];
+}
+export declare function readTaskTable(state: SessionStateMap | undefined): TaskTable;
+export declare function writeTaskTable<T extends {
+    readonly state?: SessionStateMap;
+}>(session: T, table: TaskTable): T;
+export declare function findTask(table: TaskTable, taskId: string): TaskRecord | undefined;
+export declare function isTaskWorking(record: TaskRecord): boolean;
+export declare function workingTasks(table: TaskTable): readonly TaskRecord[];
+/**
+ * The most recently used idle resumable tasks, oldest first. The table keeps
+ * records in order of use, so the last ones are the most recent.
+ */
+export declare function idleTasks(table: TaskTable): readonly TaskRecord[];
+/**
+ * Whether a call may reach the task by its id: the task is resumable and
+ * unfinished, and was started by this tool.
+ */
+export declare function isTaskAvailable(record: TaskRecord | undefined, toolName: string): record is TaskRecord & {
+    readonly run: TaskRun;
+};
+/** Tasks whose results the model has not received yet. */
+export declare function tasksWithResults(table: TaskTable): readonly TaskRecord[];
+/**
+ * What a wait on the turn's tasks returns now, or `undefined` to keep
+ * waiting. A waiting result, or nothing left working, ends it first;
+ * cancelled work never does.
+ */
+export declare function taskWaitResult(table: TaskTable, wake: {
+    readonly interrupted: boolean;
+    readonly timedOut: boolean;
+}): TaskWaitResult | undefined;
+/**
+ * What `task_cancel` answers, or `undefined` for a task that doesn't exist.
+ * `cancelled` means the caller cancels the working task.
+ */
+export declare function taskCancelResult(table: TaskTable, taskId: string): TaskCancelResult | undefined;
+/** Runs that may still be doing work, including cancelled runs that haven't confirmed yet. */
+export declare function liveTaskRuns(table: TaskTable): readonly TaskRunAddress[];
+/** Records a task for a call the model just made, with a new id. */
+export declare function createTask(table: TaskTable, input: {
+    readonly callId: string;
+    readonly kind: TaskRecord["kind"];
+    readonly name: string;
+    readonly resumable: boolean;
+    readonly turnId: string;
+}): {
+    readonly table: TaskTable;
+    readonly taskId: string;
+};
+/** Drops a task that never started, such as one past the cap. */
+export declare function removeTask(table: TaskTable, taskId: string): TaskTable;
+export declare function recordTaskRun(table: TaskTable, taskId: string, run: TaskRunAddress): TaskTable;
+/**
+ * The run can take commands now. Commands issued before this were held on the
+ * record; they are returned, in order, so the caller sends them.
+ */
+export declare function markTaskRunStarted(table: TaskTable, taskId: string, runId: string): {
+    readonly held?: TaskRunCommands;
+    readonly table: TaskTable;
+};
+/**
+ * Records a call that reaches an available task by its id: the task is
+ * working until the call has a result. The call goes to a started run now, or
+ * is held until the run reports started. The record moves to the end of the
+ * table, which keeps records in order of use.
+ */
+export declare function recordTaskCall(table: TaskTable, taskId: string, call: WorkflowToolRunCall): {
+    readonly send?: TaskRunCommands;
+    readonly table: TaskTable;
+};
+/**
+ * Settles calls that share one outcome, as one reply does, in one step. Each
+ * call settles once, with its own `task.settled`; the first outcome wins, so a
+ * call already settled, including one its owner cancelled, is dropped. The
+ * model receives the outcome once, since every call it settles would repeat it.
+ */
+export declare function settleTaskCalls(table: TaskTable, input: {
+    readonly callIds: readonly string[];
+    readonly outcome: TaskOutcome;
+    readonly taskId: string;
+}): {
+    readonly settled: readonly TaskCall[];
+    readonly table: TaskTable;
+};
+/**
+ * Settles every call still without a result with one outcome, as a run's
+ * return or failure does: a task's one call, or every call a resumable task
+ * received, or never received, since its last reply.
+ */
+export declare function settleRemainingTaskCalls(table: TaskTable, taskId: string, outcome: TaskOutcome): {
+    readonly settled: readonly TaskCall[];
+    readonly table: TaskTable;
+};
+/** Records the run's delegated spend the session just counted. */
+export declare function recordTaskRunUsage(table: TaskTable, taskId: string, usage: TokenUsage): TaskTable;
+/** The task's run finished; nothing is left to cancel. */
+export declare function finishTaskRun(table: TaskTable, taskId: string, runId: string): TaskTable;
+/** What cancelling a task changed, and the command to send its run, if any. */
+export interface TaskCancellation {
+    readonly send?: TaskRunCommands;
+    readonly settled: readonly TaskCall[];
+    readonly table: TaskTable;
+}
+/**
+ * Cancels a task's current work: its calls settle as cancelled and never
+ * report back, and a live run is told to stop. A run that hasn't started
+ * holds the cancel. A resumable task stays available and becomes idle.
+ */
+export declare function cancelTask(table: TaskTable, taskId: string): TaskCancellation;
+/**
+ * Hands every undelivered result to the model, which receives each
+ * once: `taken` is each record with its results, before they were cleared.
+ */
+export declare function takeTaskResults(table: TaskTable): {
+    readonly taken: readonly TaskRecord[];
+    readonly table: TaskTable;
+};

package/dist/src/execution/tasks/table.js

@@ -0,0 +1 @@
+import{isNonEmptyString,isObject}from"#shared/guards.js";import{UNREADABLE_TASK_ERROR}from"#execution/tasks/render.js";const TASK_TABLE_STATE_KEY=`eve.taskTable`,MAX_WORKING_TASKS=32,EMPTY_TABLE={tasks:[]};function readTaskTable(e){let t=e?.[TASK_TABLE_STATE_KEY];return!isObject(t)||t.version!==1||!Array.isArray(t.tasks)?EMPTY_TABLE:{tasks:Array.from(t.tasks).flatMap(e=>{let t=decodeTaskRecord(e);return t===void 0?[]:[t]})}}function writeTaskTable(e,t){let n=pruneFinishedRecords(t.tasks);if(n.length===0){let t={...e.state};return delete t[TASK_TABLE_STATE_KEY],{...e,state:Object.keys(t).length===0?void 0:t}}let r={tasks:n,version:1};return{...e,state:{...e.state,[TASK_TABLE_STATE_KEY]:r}}}function findTask(e,t){return e.tasks.find(e=>e.id===t)}function isTaskWorking(e){return e.calls.length>0}function workingTasks(e){return e.tasks.filter(isTaskWorking)}function idleTasks(e){return e.tasks.filter(isResumableTaskIdle).slice(-10)}function isTaskAvailable(e,t){return e!==void 0&&e.resumable&&e.run!==void 0&&e.name===t}function tasksWithResults(e){return e.tasks.filter(e=>e.results.length>0)}function taskWaitResult(e,t){let n=tasksWithResults(e).map(e=>({id:e.id,status:e.results.at(-1).status})),r=workingTasks(e).map(e=>e.id);if(n.length>0||r.length===0)return{settled:n,status:`settled`,working:r};if(t.interrupted)return{status:`interrupt`,working:r};if(t.timedOut)return{status:`timeout`,working:r}}function taskCancelResult(e,t){let n=findTask(e,t);if(n!==void 0)return{resumable:n.resumable,status:isTaskWorking(n)?`cancelled`:`already_finished`,tool:n.name}}function liveTaskRuns(e){return e.tasks.flatMap(e=>e.run===void 0?[]:[toRunAddress(e.run)])}function createTask(e,t){let n=createTaskId(e,t.name),r={calls:[{callId:t.callId,turnId:t.turnId}],id:n,kind:t.kind,name:t.name,results:[],resumable:t.resumable};return{table:{...e,tasks:[...e.tasks,r]},taskId:n}}function removeTask(e,t){return{...e,tasks:e.tasks.filter(e=>e.id!==t)}}function recordTaskRun(e,t,n){return updateTask(e,t,e=>({...e,run:{...n,started:!1}}))}function markTaskRunStarted(e,t,n){let r=findTask(e,t);if(r?.run===void 0||r.run.runId!==n||r.run.started)return{table:e};let i={...r.run,started:!0},a=updateTask(e,t,e=>{let{held:t,...n}=e;return{...n,run:i}});return r.held===void 0?{table:a}:{held:{commands:r.held,run:toRunAddress(i)},table:a}}function recordTaskCall(e,t,n){let r=findTask(e,t);if(r?.run===void 0)return{table:e};let i={call:n,kind:`call`},a=r.run,o={callId:n.callId,turnId:n.turnId},s={...r,calls:[...r.calls,o]};a.started||(s={...s,held:[...r.held??[],i]});let c={...e,tasks:[...removeTask(e,t).tasks,s]};return a.started?{send:{commands:[i],run:toRunAddress(a)},table:c}:{table:c}}function settleTaskCalls(e,t){let n=new Set(t.callIds),r=(findTask(e,t.taskId)?.calls??[]).filter(e=>n.has(e.callId));if(r.length===0)return{settled:r,table:e};let{outcome:i}=t;return{settled:r,table:updateTask(e,t.taskId,e=>({...e,calls:e.calls.filter(e=>!n.has(e.callId)),results:i.status===`cancelled`?e.results:[...e.results,i]}))}}function settleRemainingTaskCalls(e,t,n){return settleTaskCalls(e,{callIds:findTask(e,t)?.calls.map(e=>e.callId)??[],outcome:n,taskId:t})}function recordTaskRunUsage(e,t,n){return updateTask(e,t,e=>e.run===void 0?e:{...e,run:{...e.run,usage:n}})}function finishTaskRun(e,t,n){return updateTask(e,t,e=>{if(e.run?.runId!==n)return e;let{held:t,run:r,...i}=e;return i})}function cancelTask(e,t){let n=findTask(e,t);if(n===void 0)return{settled:[],table:e};if(n.resumable)return cancelResumableTask(e,n);let r=cancelledCalls(n),i=n.run,a=updateTask(e,t,e=>{let t={...e,calls:[]};return i===void 0||i.started?t:{...t,held:[{kind:`cancel`}]}});return i===void 0||!i.started?{settled:r,table:a}:{send:cancelCommand(i),settled:r,table:a}}function cancelResumableTask(e,t){let n=t.run;if(n===void 0||!isTaskWorking(t))return{settled:[],table:e};let r=cancelledCalls(t),i=updateTask(e,t.id,e=>{let t={...e,calls:[]};return n.started?t:{...t,held:[{kind:`cancel`}]}});return n.started?{send:cancelCommand(n),settled:r,table:i}:{settled:r,table:i}}function cancelCommand(e){return{commands:[{kind:`cancel`}],run:toRunAddress(e)}}function takeTaskResults(e){let t=tasksWithResults(e),n=e.tasks.map(e=>t.includes(e)?{...e,results:[]}:e);return{table:{...e,tasks:n},taken:t}}function updateTask(e,t,n){return{...e,tasks:e.tasks.map(e=>e.id===t?n(e):e)}}function cancelledCalls(e){return e.run===void 0?[]:e.calls}function toRunAddress(e){return{hookToken:e.hookToken,runId:e.runId}}function createTaskId(e,t){for(;;){let n=crypto.getRandomValues(new Uint8Array(6)),r=`${t}-${Array.from(n,e=>`0123456789abcdefghjkmnpqrstvwxyz`[e%32]).join(``)}`;if(findTask(e,r)===void 0)return r}}function isResumableTaskIdle(e){return e.resumable&&e.run!==void 0&&!isTaskWorking(e)}function isFinishedRecord(e){return e.calls.length===0&&e.results.length===0&&e.run===void 0}function pruneFinishedRecords(e){let t=e.filter(isFinishedRecord),n=t.length-100;if(n<=0)return e;let r=new Set(t.slice(0,n));return e.filter(e=>!r.has(e))}function decodeTaskRecord(e){if(isTaskRecord(e))return e;if(isObject(e)&&isNonEmptyString(e.id)&&isNonEmptyString(e.name))return{calls:[],id:e.id,kind:e.kind===`agent`?`agent`:`tool`,name:e.name,results:[{error:UNREADABLE_TASK_ERROR,status:`failed`}],resumable:!1}}function isTaskRecord(e){return isObject(e)&&isNonEmptyString(e.id)&&isNonEmptyString(e.name)&&(e.kind===`agent`||e.kind===`tool`)&&typeof e.resumable==`boolean`&&Array.isArray(e.calls)&&Array.from(e.calls).every(isTaskCall)&&Array.isArray(e.results)&&Array.from(e.results).every(isTaskResult)&&(e.run===void 0||isTaskRun(e.run))&&(e.held===void 0||Array.isArray(e.held)&&Array.from(e.held).every(isTaskRunCommand))}function isTaskRunCommand(e){return isObject(e)?e.kind===`cancel`||e.kind===`call`&&isObject(e.call)&&isNonEmptyString(e.call.callId):!1}function isTaskResult(e){return isObject(e)?e.status===`completed`?`output`in e:e.status===`failed`&&typeof e.error==`string`:!1}function isTaskRun(e){return isObject(e)&&isNonEmptyString(e.runId)&&isNonEmptyString(e.hookToken)&&typeof e.started==`boolean`&&(e.usage===void 0||isObject(e.usage))}function isTaskCall(e){return isObject(e)&&isNonEmptyString(e.callId)&&typeof e.turnId==`string`}export{MAX_WORKING_TASKS,cancelTask,createTask,findTask,finishTaskRun,idleTasks,isTaskAvailable,isTaskWorking,liveTaskRuns,markTaskRunStarted,readTaskTable,recordTaskCall,recordTaskRun,recordTaskRunUsage,removeTask,settleRemainingTaskCalls,settleTaskCalls,takeTaskResults,taskCancelResult,taskWaitResult,tasksWithResults,workingTasks,writeTaskTable};