eve 0.50.0 → 0.51.0

package/dist/src/execution/tools/subagent/invoke-agent.d.ts

@@ -0,0 +1,51 @@
+import type { RuntimeActionResultHookPayload, SubagentAuthorizationEventHookPayload, SubagentInputRequestHookPayload } from "#channel/types.js";
+import type { RuntimeSubagentChildResult, RuntimeSubagentResult } from "#shared/action-types.js";
+import type { JsonValue } from "#shared/json.js";
+import type { JsonObject } from "#shared/json.js";
+import type { ToolContext } from "#tools/definition.js";
+import type { TaskInboundUpdate } from "#tasks/types.js";
+export type InternalAgentInput = {
+    readonly agentId?: string;
+    readonly message: string;
+    readonly outputSchema?: JsonObject;
+    readonly target: string;
+};
+export interface AgentInput {
+    readonly agentId?: string;
+    readonly key: string;
+    readonly message: string;
+    readonly outputSchema?: JsonObject;
+    readonly target: string;
+}
+/**
+ * Asks the owning session to spawn an agent for a workflow tool run. Spawning
+ * needs owner-held material (auth, capabilities, admission, the agent handle
+ * store) that a workflow tool body never has.
+ */
+export interface AgentInvocationRequest {
+    readonly input: InternalAgentInput;
+    readonly invocationId: string;
+    readonly kind: "agent-invoke";
+}
+/**
+ * Tells the owning session that an owner-spawned agent replied to the run, so
+ * the owner can release the handle it reserved for `agent-invoke`.
+ */
+export interface AgentSettlementRequest {
+    readonly kind: "agent-settled";
+    readonly result: RuntimeSubagentChildResult;
+}
+export type AgentInvocationEvent = SubagentAuthorizationEventHookPayload | SubagentInputRequestHookPayload;
+export type AgentInvocationReply = AgentInvocationEvent | RuntimeActionResultHookPayload | TaskInboundUpdate;
+/** Invokes an agent from a task-owned background workflow tool. */
+export declare function agent(ctx: ToolContext, input: AgentInput): Promise<JsonValue>;
+/** Invokes an agent with a framework-selected replay-stable invocation id. */
+export declare function invokeAgent(ctx: ToolContext, input: InternalAgentInput, options: {
+    readonly invocationId: string;
+    readonly returnResult: true;
+}): Promise<JsonValue | RuntimeSubagentResult>;
+export declare function invokeAgent(ctx: ToolContext, input: InternalAgentInput, options: {
+    readonly invocationId: string;
+    readonly returnResult?: false;
+}): Promise<JsonValue>;
+export declare function validateAgentInput(input: InternalAgentInput | AgentInput, requireKey: boolean): void;

package/dist/src/execution/tools/subagent/invoke-agent.js

@@ -0,0 +1 @@
+import{createHook}from"#compiled/@workflow/core/index.js";import{claimHookOwnership,disposeHook}from"#execution/hook-ownership.js";import{readWorkflowToolRunAdmission,readWorkflowToolRunOwner,readWorkflowToolRunRef}from"#execution/tools/workflow/ask.js";import{resumeHookStep}from"#execution/tools/workflow/resume-hook-step.js";const AGENT_INVOCATION_IDS=Symbol.for(`eve.workflow-tool-run.agent-invocation-ids`);async function agent(e,t){return validateAgentInput(t,!0),await invokeAgent(e,{agentId:t.agentId,message:t.message,outputSchema:t.outputSchema,target:t.target},{invocationId:`${e.callId}:${t.key}`})}async function invokeAgent(i,a,o){validateAgentInput(a,!1);let s=readWorkflowToolRunRef(i),c=readWorkflowToolRunOwner(i),l=readWorkflowToolRunAdmission(i);claimInvocationId(i,o.invocationId);let u=createHook(),d=!1;try{if(await claimHookOwnership(u),d=!0,l!==void 0){let e=await l;if(e.status===`rejected`)throw Error(e.reason)}await resumeHookStep(c.request,{from:s,replyTo:u.token,request:{input:a,invocationId:o.invocationId,kind:`agent-invoke`}});let e=u[Symbol.asyncIterator]();for(;;){let t=await nextAgentReply(e,i.abortSignal);if(t.done)break;let n=t.value;if(n.kind===`runtime-action-result`){let e=n.results.find(e=>e.kind===`subagent-result`&&e.callId===o.invocationId);if(e!==void 0){if(e.origin===`child`&&await resumeHookStep(c.request,{from:s,replyTo:u.token,request:{kind:`agent-settled`,result:e}}),o.returnResult===!0&&s.execution===`blocking`)return e;if(e.isError===!0)throw e.output;return e.output}continue}if(n.kind===`subagent-input-request`){await resumeHookStep(c.request,{from:s,replyTo:n.childContinuationToken,request:{kind:`input-batch`,requests:n.event.requests},requestCoordinates:{sequence:n.event.sequence,stepIndex:n.event.stepIndex,turnId:n.event.turnId}});continue}if(n.kind===`task-update`){await resumeHookStep(c.report,{from:s,update:n.message});continue}await resumeHookStep(c.request,{from:s,replyTo:u.token,request:{event:n,kind:`authorization-request`}})}}finally{if(d)try{await disposeHook(u)}catch{}}throw Error(`Agent "${a.target}" closed without a result.`)}async function nextAgentReply(e,t){if(t===void 0)return await e.next();if(t.aborted)throw t.reason;let n,r=new Promise((e,t)=>{n=t}),abort=()=>n?.(t.reason);t.addEventListener(`abort`,abort,{once:!0});try{return await Promise.race([e.next(),r])}finally{t.removeEventListener(`abort`,abort)}}function validateAgentInput(e,t){if(t&&(typeof e.key!=`string`||e.key.trim()===``))throw TypeError("agent() requires a non-empty `key`.");if(typeof e.target!=`string`||e.target.trim()===``)throw TypeError("agent() requires a non-empty `target`.");if(typeof e.message!=`string`||e.message.trim()===``)throw TypeError("agent() requires a non-empty `message`.")}function claimInvocationId(e,t){let n=e,r=n[AGENT_INVOCATION_IDS]??new Set;if(r.has(t)){let e=t.lastIndexOf(`:`),n=e<0?t:t.slice(e+1);throw TypeError(`agent() invocation key "${n}" was already used in this run; keys must be unique per run.`)}r.add(t),n[AGENT_INVOCATION_IDS]===void 0&&Object.defineProperty(n,AGENT_INVOCATION_IDS,{enumerable:!1,value:r})}export{agent,invokeAgent,validateAgentInput};

package/dist/src/execution/tools/subagent/invoke-preparation.d.ts

@@ -0,0 +1,37 @@
+import type { ContextReader } from "#context/key.js";
+import { type PreparedCoordinationDispatch } from "#execution/coordination-dispatch-shared.js";
+import { type DurableSessionState } from "#execution/durable-session-store.js";
+import type { RuntimeAgentDispatchRequest } from "#shared/action-types.js";
+import type { RuntimeSubagentDispatchFailure } from "#shared/action-types.js";
+import type { AgentInvocationRequest } from "#execution/tools/subagent/invoke-agent.js";
+import { type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
+import type { DynamicRemoteAgentConfig } from "#runtime/subagents/dynamic-remote-agent-config.js";
+import { type RuntimeAgentHandleAction, type RuntimeSession } from "#subagents/handle-dispatch.js";
+import type { SubagentStartTarget } from "#execution/tools/subagent/start.js";
+export type OwnerAgentDispatchPlanEntry = {
+    readonly kind: "resume";
+    readonly action: RuntimeAgentHandleAction;
+    readonly agentId: string;
+    readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
+} | {
+    readonly kind: "reject";
+    readonly result: RuntimeSubagentDispatchFailure;
+} | {
+    readonly kind: "start";
+    readonly target: SubagentStartTarget;
+};
+/** Prepares one workflow-owner agent invocation from durable inputs. */
+export declare function prepareOwnerAgentInvocation(input: {
+    readonly invocation: AgentInvocationRequest["input"];
+    readonly invocationId: string;
+    readonly knownAgentIds?: readonly string[];
+    readonly serializedContext: Record<string, unknown>;
+    readonly sessionState: DurableSessionState;
+}): Promise<Omit<PreparedCoordinationDispatch<OwnerAgentDispatchPlanEntry>, "sessionState">>;
+export declare function planAgentDispatch(input: {
+    readonly action: RuntimeAgentDispatchRequest;
+    readonly bundle: CompiledBundle;
+    readonly ctx: ContextReader;
+    readonly knownAgentIds?: readonly string[];
+    readonly session: RuntimeSession;
+}): OwnerAgentDispatchPlanEntry;

package/dist/src/execution/tools/subagent/invoke-preparation.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{SessionDynamicSubagentSelectionsKey,TurnDynamicSubagentSelectionsKey}from"#context/keys.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{getHarnessEmissionState}from"#harness/emission.js";import{deserializeContext}from"#context/serialize.js";import{readDurableSession}from"#execution/durable-session-store.js";import{getAgentHandleStore}from"#subagents/handles/store.js";import{getDynamicSubagentSelection}from"#context/dynamic-subagent-lifecycle.js";import{activeTurnId}from"#harness/active-turn-id.js";import{prepareActionDispatch}from"#execution/coordination-dispatch-shared.js";import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{AGENT_TOOL_DESCRIPTION,AGENT_TOOL_NAME}from"#tools/framework/agent-contract.js";import{isAgentHandleAction}from"#subagents/handle-dispatch.js";import{createRecursiveAgentRootOnlyResult,createUnavailableDynamicSubagentResult,getSubagentName}from"#execution/dispatch-action-failures.js";const log=createLogger(`execution.agent-invocation`);async function prepareOwnerAgentInvocation(e){let t=await readDurableSession(e.sessionState),n=await deserializeContext(e.serializedContext),r=getHarnessEmissionState(t.state),s=resolveAgentInvocationAction({ctx:n,input:e.invocation,invocationId:e.invocationId});return await prepareActionDispatch({batch:{requests:[s],event:{...r,turnId:activeTurnId(r)}},ctx:n,durableSession:t,fanoutSize:1,plan:({bundle:t,ctx:n,session:r})=>[planAgentDispatch({action:s,bundle:t,ctx:n,knownAgentIds:e.knownAgentIds,session:r})],planSharesSandbox:({bundle:e,plan:t})=>ownerPlanSharesSandbox({bundle:e,plan:t}),serializedContext:e.serializedContext})}function planAgentDispatch(e){let t=new Set(e.knownAgentIds??(getAgentHandleStore(e.session.state)?.handles??[]).map(e=>e.identity.id)),n=e.action.input.agentId,r=typeof n==`string`&&n.trim()!==``?n:void 0;if(r!==void 0&&isAgentHandleAction(e.action)){if(t.has(r)){let t=e.bundle.subagentRegistry.dynamicNodeIds?.has(e.action.nodeId)===!0?getDynamicSubagentSelection(e.ctx,e.action.nodeId):void 0;return{action:e.action,agentId:r,dynamicRemoteAgent:e.action.kind===`remote-agent-call`&&t?.kind===`remote`?t.remoteAgent:void 0,kind:`resume`}}log.warn(`unknown agentId on subagent call; starting a new agent`,{agentId:r,callId:e.action.callId})}return classifyFreshStart(e)}function classifyFreshStart(e){let{action:t}=e,n=e.bundle.subagentRegistry.subagentsByNodeId,r=e.bundle.subagentRegistry.dynamicNodeIds?.has(t.nodeId)===!0,i=r?getDynamicSubagentSelection(e.ctx,t.nodeId):void 0;if(r&&(i===void 0||t.kind===`subagent-call`&&i.kind!==`subagent`||t.kind===`remote-agent-call`&&i.kind!==`remote`))return log.warn(`dynamic subagent call blocked after availability changed`,{callId:t.callId,nodeId:t.nodeId,subagentName:getSubagentName(t)}),{kind:`reject`,result:createUnavailableDynamicSubagentResult(t)};if(isRecursiveAgentAction(t,n)&&e.session.rootSessionId!==void 0)return log.warn(`recursive agent call blocked outside the root session`,{callId:t.callId,nodeId:t.nodeId,rootSessionId:e.session.rootSessionId,subagentName:t.subagentName}),{kind:`reject`,result:createRecursiveAgentRootOnlyResult(t)};if(t.kind===`remote-agent-call`)return{kind:`start`,target:{action:t,dynamicRemoteAgent:i?.kind===`remote`?i.remoteAgent:void 0,kind:`remote`}};let a=i?.kind===`subagent`?i.agentConfig:void 0,o=n.get(t.nodeId),s=a?.description??(o?.definition.kind===`subagent`?o.definition.description:void 0);return{kind:`start`,target:{action:t,dynamicSubagentAgentConfig:a,kind:`local`,source:s===void 0?{outputSchema:e.bundle.turnAgent.outputSchema,type:`runtime`}:{description:s,outputSchema:a?.outputSchema??e.bundle.graph?.nodesByNodeId.get(t.nodeId)?.turnAgent?.outputSchema,type:`local`}}}}function ownerPlanSharesSandbox(e){return e.plan.some(t=>{if(t.kind!==`start`||t.target.kind!==`local`)return!1;let n=t.target.action;return n.subagentName===`agent`&&!e.bundle.subagentRegistry.subagentsByNodeId.has(n.nodeId)||e.bundle.graph?.nodesByNodeId.get(n.nodeId)?.sandboxRegistry.sandbox.definition.inheritsParent===!0})}function isRecursiveAgentAction(e,t){return e.kind===`subagent-call`&&e.subagentName===`agent`&&!t.has(e.nodeId)}function resolveAgentInvocationAction(e){let i=e.ctx.require(BundleKey),a=i.subagentRegistry.subagentsByName.get(e.input.target),o=a===void 0?Object.values({...e.ctx.get(SessionDynamicSubagentSelectionsKey),...e.ctx.get(TurnDynamicSubagentSelectionsKey)}).find(t=>t!==null&&t.prepared?.name===e.input.target):void 0,s=a?.definition??o?.prepared??(e.input.target===AGENT_TOOL_NAME&&i.nodeId===void 0?{description:AGENT_TOOL_DESCRIPTION,kind:`subagent`,name:AGENT_TOOL_NAME,nodeId:ROOT_RUNTIME_AGENT_NODE_ID}:void 0);if(s===void 0)throw Error(`Agent target "${e.input.target}" is not available to this agent.`);let c={message:e.input.message};e.input.agentId!==void 0&&(c.agentId=e.input.agentId),e.input.outputSchema!==void 0&&(c.outputSchema=e.input.outputSchema);let l={callId:e.invocationId,description:s.description??``,input:c,name:s.name,nodeId:s.nodeId};return s.kind===`remote`?{...l,kind:`remote-agent-call`,remoteAgentName:s.name}:{...l,kind:`subagent-call`,subagentName:s.name}}export{planAgentDispatch,prepareOwnerAgentInvocation};

package/dist/src/execution/tools/subagent/invoke-step.d.ts

@@ -0,0 +1,55 @@
+import type { AgentInvocationRequest } from "#execution/tools/subagent/invoke-agent.js";
+import type { RuntimeSubagentResult } from "#shared/action-types.js";
+import type { HandleEventFn } from "#harness/types.js";
+import { type SubagentCalledStreamEvent } from "#protocol/message.js";
+import { type DurableSessionState } from "#execution/durable-session-store.js";
+import type { RuntimeSubagentChildResult } from "#shared/action-types.js";
+export type AgentInvocationDispatchResult = {
+    readonly kind: "dispatched";
+    readonly agentId: string;
+    readonly event: SubagentCalledStreamEvent;
+    readonly sessionState: DurableSessionState;
+} | {
+    readonly kind: "failed";
+    readonly result: RuntimeSubagentResult;
+    readonly sessionState: DurableSessionState;
+};
+export type TaskAgentInvocationDispatchResult = {
+    readonly kind: "not-admitted";
+    readonly sessionState: DurableSessionState;
+} | AgentInvocationDispatchResult;
+/** Dispatches one owner-scoped local or remote agent invocation. */
+export declare function dispatchAgentInvocation(input: {
+    readonly callbackBaseUrl: string;
+    readonly emit?: HandleEventFn;
+    readonly replyTo: string;
+    readonly request: AgentInvocationRequest;
+    readonly serializedContext: Record<string, unknown>;
+    readonly sessionState: DurableSessionState;
+    readonly ownerId: string;
+    readonly taskId?: string | undefined;
+}): Promise<AgentInvocationDispatchResult>;
+/**
+ * Dispatches one agent request after any task-owned invocation is admitted.
+ * The callback origin is parent-owned, so it is derived from this workflow's
+ * own metadata rather than accepted from the inbound request.
+ */
+export declare function dispatchTaskAgentInvocationStep(input: Omit<Parameters<typeof dispatchAgentInvocation>[0], "callbackBaseUrl" | "emit">): Promise<TaskAgentInvocationDispatchResult>;
+/** Applies an owner-scoped child settlement to the parent session's canonical state. */
+export declare function settleTaskAgentInvocationStep(input: {
+    readonly accumulateUsage?: boolean;
+    readonly ownerId: string;
+    readonly result: RuntimeSubagentChildResult;
+    readonly sessionState: DurableSessionState;
+    readonly taskId?: string | undefined;
+}): Promise<{
+    readonly sessionState: DurableSessionState;
+}>;
+/** Releases any child leases still owned by a completed workflow-tool run. */
+export declare function releaseAgentInvocationOwnerStep(input: {
+    readonly cancelled?: boolean;
+    readonly ownerId: string;
+    readonly sessionState: DurableSessionState;
+}): Promise<{
+    readonly sessionState: DurableSessionState;
+}>;

package/dist/src/execution/tools/subagent/invoke-step.js

@@ -0,0 +1 @@
+import{createSubagentCalledEvent}from"#protocol/message.js";import{workflowEntryReference}from"#execution/workflow-runtime.js";import{getWorkflowMetadata}from"#compiled/@workflow/core/index.js";import{deriveAgentOperationId}from"#subagents/handles/operation-id.js";import{readDurableSession,replaceDurableSessionSnapshot}from"#execution/durable-session-store.js";import{getAgentHandleStore,writeHandles}from"#subagents/handles/store.js";import{projectToDurableSession}from"#execution/session.js";import{AGENT_BUSY,AGENT_MISMATCH,AGENT_UNREACHABLE,formatAgentBusyMessage}from"#subagents/agent-handle-errors.js";import{clearProxyInputRequestsForChild,clearProxyInputRequestsForTask}from"#harness/proxy-input-requests.js";import{readLatestTaskView}from"#execution/tasks/parent/run-parent.js";import{findSessionTaskEntry}from"#tasks/session-index.js";import{abandonAgentInvocationOwners,applyTaskAgentHandleCommand}from"#subagents/handles/transitions.js";import{accumulateSessionUsage,getTurnUsageState,setTurnUsageState}from"#harness/turn-tag-state.js";import{isTerminalTaskStatus}from"#tasks/types.js";import{resolveWorkflowCallbackBaseUrl}from"#execution/workflow-callback-url.js";import{createSubagentReceiptIdentity}from"#execution/tools/subagent/receipt-identity.js";import{createAgentErrorResult,dispatchToClaimedAgentAddress}from"#subagents/handle-dispatch.js";import{createAgentContinuationBundle}from"#subagents/continuation-bundle.js";import{startSubagent}from"#execution/tools/subagent/start.js";import{prepareOwnerAgentInvocation}from"#execution/tools/subagent/invoke-preparation.js";async function dispatchAgentInvocation(n){let a=getAgentHandleStore((await readDurableSession(n.sessionState)).state)?.handles??[],s=await prepareOwnerAgentInvocation({invocation:n.request.input,invocationId:n.request.invocationId,knownAgentIds:a.map(e=>e.identity.id),serializedContext:n.serializedContext,sessionState:n.sessionState}),c=s.plan[0];if(c===void 0)throw Error(`Agent invocation produced no executable plan entry.`);let l=s.session,currentAgentHandles=()=>getAgentHandleStore(l.state)?.handles??[],sessionState=()=>replaceDurableSessionSnapshot({session:projectToDurableSession(l),state:n.sessionState}),applyHandleCommand=e=>{let t=applyTaskAgentHandleCommand(l,e);return l=t.session,t.result};if(c.kind===`reject`)return{kind:`failed`,result:c.result,sessionState:sessionState()};let u,d;if(c.kind===`resume`){let e=currentAgentHandles().filter(e=>e.phase===`claimed`&&e.ownerId===n.ownerId&&e.callId===c.action.callId&&e.identity.id===c.agentId);if(e.length>1)throw Error(`Invocation owner "${n.ownerId}" has multiple claims for "${c.action.callId}".`);let t=e[0];if(t===void 0){let e=deriveAgentOperationId({callId:c.action.callId,parentSessionId:s.session.sessionId,parentTurnId:s.batch.event.turnId}),i=applyHandleCommand({agentId:c.agentId,callId:c.action.callId,expectedTarget:c.action.kind===`remote-agent-call`?`remote`:`local`,invokedName:c.action.kind===`remote-agent-call`?c.action.remoteAgentName:c.action.subagentName,kind:`claim`,operationId:e,ownerId:n.ownerId});if(t=readClaimedHandle(i),t===void 0)return{kind:`failed`,result:createTaskClaimError(c.action,c.agentId,i),sessionState:sessionState()}}let i=createAgentContinuationBundle({action:c.action,bundle:s.bundle,dynamicRemoteAgent:c.dynamicRemoteAgent});u=await dispatchToClaimedAgentAddress({action:c.action,auth:s.auth,bundle:i,currentSession:l,parentToken:n.replyTo,handle:t,taskId:n.taskId}),u.kind===`error`&&u.deliveryPermanent===!0&&applyHandleCommand({agentId:c.agentId,kind:`remove`,ownerId:n.ownerId}),d=t.identity.id}else{let e=c.target.action,t=currentAgentHandles().filter(t=>t.phase===`reserved`&&t.ownerId===n.ownerId&&t.callId===e.callId&&t.identity.name===e.name&&t.identity.nodeId===e.nodeId),r=t.length===1?{identity:t[0].identity,operation:{id:t[0].operationId}}:createSubagentReceiptIdentity({callId:e.callId,subagentName:e.kind===`remote-agent-call`?e.remoteAgentName:e.subagentName,nodeId:e.nodeId,parentSessionId:s.session.sessionId,parentTurnId:s.batch.event.turnId});if(t.length>1)throw Error(`Invocation owner "${n.ownerId}" has multiple reservations for "${e.callId}".`);if(t.length===0&&applyHandleCommand({identity:r.identity,callId:e.callId,kind:`reserve`,operationId:r.operation.id,ownerId:n.ownerId}).kind!==`ready`)throw Error(`Agent handle store rejected start operation "${r.operation.id}".`);if(u=await startSubagent({auth:s.auth,batchEvent:s.batch.event,bundle:s.bundle,callbackBaseUrl:n.callbackBaseUrl,capabilities:s.capabilities,channelMetadata:s.channelMetadata,currentSession:l,fanoutSize:s.fanoutSize,initiatorAuth:s.initiatorAuth,localDevRequest:s.localDevRequest,parentContinuationToken:n.replyTo,parentTraceContext:s.parentTraceContext,sandboxSessionId:s.sandboxSessionId,serializedContext:s.serializedContext,session:l,taskId:n.taskId,target:c.target}),d=r.identity.id,u.kind===`error`)applyHandleCommand({agentId:d,kind:`remove`,ownerId:n.ownerId});else if(readClaimedHandle(applyHandleCommand({address:u.address,kind:`confirm`,operationId:r.operation.id,ownerId:n.ownerId}))===void 0)throw Error(`Agent handle store could not confirm start operation "${r.operation.id}".`)}if(u.kind===`error`)return{kind:`failed`,result:u.result,sessionState:sessionState()};let f=c.kind===`resume`?c.action:c.target.action,p=c.kind===`resume`?c.dynamicRemoteAgent:c.target.kind===`remote`?c.target.dynamicRemoteAgent:void 0,m=createSubagentCalledEvent({agentId:d,callId:u.callId,childSessionId:u.address.sessionId,name:u.name,remote:u.address.kind===`agent/remote`?{resolverId:p===void 0?f.nodeId:p.credentialsStepId,url:u.address.url}:void 0,sequence:s.batch.event.sequence,sessionId:s.session.sessionId,toolName:u.toolName,turnId:s.batch.event.turnId,workflowId:workflowEntryReference.workflowId});return n.emit!==void 0&&await n.emit(m),{kind:`dispatched`,agentId:d,event:m,sessionState:sessionState()}}async function dispatchTaskAgentInvocationStep(e){"use step";if(e.taskId!==void 0){let t=findSessionTaskEntry((await readDurableSession(e.sessionState)).state,e.taskId);if(t===void 0)return{kind:`not-admitted`,sessionState:e.sessionState};let n=await readLatestTaskView({taskRunId:t.taskRunId});if(n===void 0||isTerminalTaskStatus(n.status))return{kind:`not-admitted`,sessionState:e.sessionState}}return await dispatchAgentInvocation({...e,callbackBaseUrl:resolveWorkflowCallbackBaseUrl(getWorkflowMetadata().url)})}async function settleTaskAgentInvocationStep(e){"use step";let t=await readDurableSession(e.sessionState),n=getAgentHandleStore(t.state)?.handles??[],r=n.filter(t=>t.phase===`claimed`&&t.ownerId===e.ownerId),o=r.find(t=>t.phase===`claimed`&&t.callId===e.result.callId)??(r.length===1?r[0]:void 0);if(o?.phase!==`claimed`)return{sessionState:e.sessionState};let s=writeHandles(t,e.result.outcome.kind===`terminal`?n.filter(e=>e!==o):n.map(t=>t===o?e.result.outcome.result.kind===`cancelled`?{address:o.address,identity:o.identity,lastStatus:`(cancelled)`,phase:`parked`}:{address:o.address,identity:o.identity,phase:`available`}:t));return e.result.outcome.kind===`terminal`&&(s=e.taskId===void 0?`continuationToken`in o.address?clearProxyInputRequestsForChild(s,o.address.continuationToken):s:clearProxyInputRequestsForTask(s,e.taskId)),e.accumulateUsage!==!1&&(s=setTurnUsageState(s,accumulateSessionUsage({previous:getTurnUsageState(s.state),usage:e.result.outcome.usageDelta}))),{sessionState:replaceDurableSessionSnapshot({session:s,state:e.sessionState})}}async function releaseAgentInvocationOwnerStep(e){"use step";let t=await readDurableSession(e.sessionState),n=e.cancelled?abandonAgentInvocationOwners(t,new Set([e.ownerId])):applyTaskAgentHandleCommand(t,{kind:`release-owner`,ownerId:e.ownerId}).session;return{sessionState:n===t?e.sessionState:replaceDurableSessionSnapshot({session:n,state:e.sessionState})}}function readClaimedHandle(e){let t=e.kind===`ready`?e.handle:void 0;return t?.phase===`claimed`?t:void 0}function createTaskClaimError(e,t,n){return n.kind===`mismatch`?createAgentErrorResult({action:e,code:AGENT_MISMATCH,message:`Agent "${t}" no longer matches this subagent definition. Start a new agent instead.`}):n.kind===`busy`?createAgentErrorResult({action:e,code:AGENT_BUSY,message:formatAgentBusyMessage({agentId:t,agentName:n.handle.identity.name,ownerId:`ownerId`in n.handle?n.handle.ownerId:void 0})}):createAgentErrorResult({action:e,code:AGENT_UNREACHABLE,message:`Agent with id "${t}" is no longer reachable.`})}export{dispatchAgentInvocation,dispatchTaskAgentInvocationStep,releaseAgentInvocationOwnerStep,settleTaskAgentInvocationStep};

package/dist/src/execution/tools/subagent/receipt-identity.d.ts

@@ -0,0 +1,11 @@
+/** Derives the one deterministic identity shared by subagent receipts and dispatch. */
+export declare function createSubagentReceiptIdentity(input: {
+    readonly callId: string;
+    readonly parentSessionId: string;
+    readonly parentTurnId: string;
+    readonly subagentName: string;
+    readonly nodeId: string;
+}): {
+    readonly identity: import("../../../subagents/handles/store.ts").AgentIdentity;
+    readonly operation: import("../../../subagents/handles/store.ts").StartOperation;
+};

package/dist/src/execution/tools/subagent/receipt-identity.js

@@ -0,0 +1 @@
+import{mintStartOperation}from"#execution/dispatch-start-operation.js";function createSubagentReceiptIdentity(e){return mintStartOperation({callId:e.callId,name:e.subagentName,nodeId:e.nodeId,parentSessionId:e.parentSessionId,parentTurnId:e.parentTurnId})}export{createSubagentReceiptIdentity};

package/dist/src/execution/{dispatch-runtime-actions-start.d.ts → tools/subagent/start.d.ts}

@@ -1,10 +1,22 @@
 import type { ActivityObserverConfig } from "#channel/types.js";
 import type { LocalDevRequestProvenance } from "#context/keys.js";
-import type { DispatchOutcome, RuntimeSession } from "#execution/agent-handle-dispatch.js";
-import type { DispatchStartTarget } from "#execution/dispatch-runtime-actions-shared.js";
-import { buildSubagentRunInput } from "#execution/subagent-tool.js";
 import type { ActivityWorkIdentityV1 } from "#protocol/activity.js";
+import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
+import type { DynamicRemoteAgentConfig } from "#runtime/subagents/dynamic-remote-agent-config.js";
 import type { CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
+import type { RuntimeRemoteAgentDispatchRequest, RuntimeSubagentDispatchRequest } from "#shared/action-types.js";
+import type { DispatchOutcome, RuntimeSession } from "#subagents/handle-dispatch.js";
+import { buildSubagentRunInput, type SubagentInputSource } from "#subagents/tool.js";
+export type SubagentStartTarget = {
+    readonly kind: "local";
+    readonly action: RuntimeSubagentDispatchRequest;
+    readonly dynamicSubagentAgentConfig?: DynamicSubagentAgentConfig;
+    readonly source: SubagentInputSource;
+} | {
+    readonly kind: "remote";
+    readonly action: RuntimeRemoteAgentDispatchRequest;
+    readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
+};
 /** Starts one planned fresh child against its local or remote target. */
 export declare function startSubagent(input: {
     readonly auth: Parameters<typeof buildSubagentRunInput>[0]["auth"];
@@ -28,6 +40,6 @@ export declare function startSubagent(input: {
     readonly sandboxSessionId: string;
     readonly serializedContext: Record<string, unknown>;
     readonly session: RuntimeSession;
-    readonly taskOwned: boolean;
-    readonly target: DispatchStartTarget;
+    readonly taskId?: string;
+    readonly target: SubagentStartTarget;
 }): Promise<DispatchOutcome>;

package/dist/src/execution/tools/subagent/start.js

@@ -0,0 +1 @@
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{applyLiveDeliveryAudienceCeiling,readForwardedTraceAssertion}from"#shared/forwarded-trace-policy.js";import"#subagents/tool.js";import{readActionTraceContext}from"#tracing/agent-trace-context-store.js";import{startLocalSubagent}from"#subagents/start-local.js";import{startRemoteSubagent}from"#subagents/start-remote.js";async function startSubagent(e){let t=readActionTraceContext(e.serializedContext,e.session.sessionId,e.batchEvent.turnId,e.target.action.callId)??e.parentTraceContext,n=readForwardedTraceAssertion(t?.forwardedTracePolicy),r=normalizeChannelAudience(e.channelMetadata?.metadata.audience),i=t?.decision===void 0?t:{...t,decision:applyLiveDeliveryAudienceCeiling(t.decision,r,n)};switch(e.target.kind){case`local`:return startLocalSubagent({action:e.target.action,auth:e.auth,batchEvent:e.batchEvent,bundle:e.bundle,capabilities:e.capabilities,channelMetadata:e.channelMetadata,currentSession:e.currentSession,dynamicSubagentAgentConfig:e.target.dynamicSubagentAgentConfig,fanoutSize:e.fanoutSize,initiatorAuth:e.initiatorAuth,localDevRequest:e.localDevRequest,parentContinuationToken:e.parentContinuationToken,parentTraceContext:i,activityObserver:e.activityObserver,sandboxSessionId:e.sandboxSessionId,session:e.session,source:e.target.source,taskId:e.taskId});case`remote`:return startRemoteSubagent({action:e.target.action,auth:e.auth,batchEvent:e.batchEvent,bundle:e.bundle,callbackBaseUrl:e.callbackBaseUrl,originAudience:n?.originAudience??r,currentSession:e.currentSession,dynamicRemoteAgent:e.target.dynamicRemoteAgent,initiatorAuth:e.initiatorAuth,parentContinuationToken:e.parentContinuationToken,parentTraceContext:i,activityObserver:e.activityObserver,session:e.session,taskId:e.taskId});default:return e.target}}export{startSubagent};

package/dist/src/execution/tools/subagent/task-agent-requests.d.ts

@@ -0,0 +1,24 @@
+import type { DurableSessionState } from "#execution/durable-session-store.js";
+import type { TaskAgentRequestDelivery } from "#tasks/types.js";
+export interface AgentRequestDelivery {
+    readonly accumulateUsage?: boolean;
+    readonly ownerId: string;
+    readonly replyTo: TaskAgentRequestDelivery["replyTo"];
+    readonly request: TaskAgentRequestDelivery["request"];
+    readonly taskId?: string;
+}
+export interface TaskAgentRequestContext {
+    readonly parentWritable: WritableStream<Uint8Array>;
+    readonly serializedContext: Record<string, unknown>;
+    readonly sessionState: DurableSessionState;
+}
+export interface AppliedTaskAgentRequest {
+    readonly serializedContext: Record<string, unknown>;
+    readonly sessionState: DurableSessionState;
+}
+/**
+ * Applies one workflow-owned agent request to the parent session: `agent-invoke`
+ * spawns the child with parent-owned material and `agent-settled` releases the
+ * handle. Child authorization and HITL ride their own task envelope arms.
+ */
+export declare function applyTaskAgentRequest(delivery: AgentRequestDelivery, ctx: TaskAgentRequestContext): Promise<AppliedTaskAgentRequest>;

package/dist/src/execution/tools/subagent/task-agent-requests.js

@@ -0,0 +1 @@
+import{resumeHookStep}from"#execution/tools/workflow/resume-hook-step.js";import{emitTaskSubagentCalledStep}from"#execution/tools/subagent/emit-called-step.js";import{dispatchTaskAgentInvocationStep,settleTaskAgentInvocationStep}from"#execution/tools/subagent/invoke-step.js";async function applyTaskAgentRequest(n,r){let{request:i}=n;switch(i.kind){case`agent-settled`:{let e=await settleTaskAgentInvocationStep({accumulateUsage:n.accumulateUsage,ownerId:n.ownerId,result:i.result,sessionState:r.sessionState,taskId:n.taskId});return{serializedContext:r.serializedContext,sessionState:e.sessionState}}case`agent-invoke`:{let t=await dispatchTaskAgentInvocationStep({ownerId:n.ownerId,replyTo:n.replyTo,request:i,serializedContext:r.serializedContext,sessionState:r.sessionState,taskId:n.taskId});switch(t.kind){case`dispatched`:return{serializedContext:(await emitTaskSubagentCalledStep({event:t.event,parentWritable:r.parentWritable,serializedContext:r.serializedContext})).serializedContext,sessionState:t.sessionState};case`failed`:return await resumeHookStep(n.replyTo,{kind:`runtime-action-result`,results:[t.result]}),{serializedContext:r.serializedContext,sessionState:t.sessionState};case`not-admitted`:return{serializedContext:r.serializedContext,sessionState:t.sessionState}}}}}export{applyTaskAgentRequest};

package/dist/src/execution/tools/subagent/task-cancel.d.ts

@@ -0,0 +1,10 @@
+import type { TaskExecutorCancel } from "#execution/tasks/parent/task-cancel.js";
+import { type DurableSessionState } from "#execution/durable-session-store.js";
+/** Cancels the active child turn owned by a background subagent task. */
+export declare const cancelBackgroundAgentTask: TaskExecutorCancel;
+/** Cancels a child turn still claimed by a completed workflow-tool run. */
+export declare function cancelAgentInvocationOwnerStep(input: {
+    readonly ownerId: string;
+    readonly serializedContext: Record<string, unknown>;
+    readonly sessionState: DurableSessionState;
+}): Promise<void>;

package/dist/src/execution/tools/subagent/task-cancel.js

@@ -0,0 +1 @@
+import{createLogger,logError}from"#internal/logging.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{requestWorkflowTurnCancellation}from"#execution/workflow-runtime.js";import{deserializeContext}from"#context/serialize.js";import{readDurableSession}from"#execution/durable-session-store.js";import{cancelRemoteAgentTurn,resolveRemoteAgentForAction}from"#subagents/remote-dispatch.js";import{getAgentHandleStore}from"#subagents/handles/store.js";import{getDynamicSubagentSelection}from"#context/dynamic-subagent-lifecycle.js";const log=createLogger(`execution.agent-invocation-cancel`),cancelBackgroundAgentTask=async e=>{if(e.session===void 0||e.serializedContext===void 0)return;let t=e.session,i=getAgentHandleStore(t.state)?.handles.find(t=>t.phase===`claimed`&&t.ownerId===e.entry.taskId);if(i===void 0||i.phase!==`claimed`)return;if(i.address.kind!==`agent/remote`){await requestWorkflowTurnCancellation({sessionId:i.address.sessionId});return}let a=await deserializeContext(e.serializedContext),o=a.require(BundleKey),s=getDynamicSubagentSelection(a,i.identity.nodeId);await cancelRemoteAgentTurn({remote:{...resolveRemoteAgentForAction({dynamicRemoteAgent:s?.kind===`remote`?s.remoteAgent:void 0,nodeId:i.identity.nodeId,registry:o.subagentRegistry.subagentsByNodeId,remoteAgentName:i.identity.name}),url:i.address.url},sessionId:i.address.sessionId})};async function cancelAgentInvocationOwnerStep(e){"use step";let o=(getAgentHandleStore((await readDurableSession(e.sessionState)).state)?.handles??[]).filter(t=>t.phase===`claimed`&&t.ownerId===e.ownerId);if(o.length===0)return;let s=o.some(e=>e.address.kind===`agent/remote`)?await deserializeContext(e.serializedContext):void 0;await Promise.all(o.map(async r=>{try{if(r.address.kind!==`agent/remote`){await requestWorkflowTurnCancellation({sessionId:r.address.sessionId});return}let e=s.require(BundleKey),t=getDynamicSubagentSelection(s,r.identity.nodeId);await cancelRemoteAgentTurn({remote:{...resolveRemoteAgentForAction({dynamicRemoteAgent:t?.kind===`remote`?t.remoteAgent:void 0,nodeId:r.identity.nodeId,registry:e.subagentRegistry.subagentsByNodeId,remoteAgentName:r.identity.name}),url:r.address.url},sessionId:r.address.sessionId})}catch(n){logError(log,`failed to cancel workflow-owned agent turn`,n,{agentId:r.identity.id,childSessionId:r.address.sessionId,ownerId:e.ownerId})}}))}export{cancelAgentInvocationOwnerStep,cancelBackgroundAgentTask};

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

@@ -0,0 +1,10 @@
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+/**
+ * Builds harness definitions for the compiled framework task tools.
+ */
+export declare function createTaskToolHarnessDefinitions(): readonly HarnessToolDefinition[];
+/**
+ * Authored tools with the same name shadow these framework definitions,
+ * and `disableTool(name)` removes individual controls. advertised-tools
+ * evaluates their selected availability against persisted session metadata.
+ */

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

@@ -0,0 +1 @@
+import{TASK_CANCEL_INPUT_SCHEMA,TASK_CANCEL_TOOL_NAME,TASK_UPDATE_INPUT_SCHEMA,TASK_UPDATE_TOOL_NAME,TASK_VIEWS_OUTPUT_SCHEMA}from"#tools/framework/task-contract.js";function createTaskToolHarnessDefinitions(){return[{description:`Request cooperative cancellation of one or more background tasks. Cancellation is final: a task that finishes after you cancel it stays cancelled. Cancelling an already-finished task changes nothing.`,inputSchema:TASK_CANCEL_INPUT_SCHEMA,name:TASK_CANCEL_TOOL_NAME,outputSchema:TASK_VIEWS_OUTPUT_SCHEMA,runtimeAction:{kind:`task-control`}},{description:`Briefly tell the parent agent what this background task is currently doing. Report activity, not preliminary findings or results.`,inputSchema:TASK_UPDATE_INPUT_SCHEMA,name:TASK_UPDATE_TOOL_NAME,runtimeAction:{kind:`task-control`}}]}export{createTaskToolHarnessDefinitions};

package/dist/src/execution/{tool-run → tools/workflow}/answer.d.ts

@@ -1,3 +1,3 @@
 import type { InputResponse } from "#shared/input.js";
 /** Resumed with the bare response, not a session-inbox delivery, so the body can race the hook. */
-export declare function resumeToolRunAnswers(answerToken: string, responses: readonly InputResponse[] | undefined): Promise<void>;
+export declare function resumeWorkflowToolRunAnswers(answerToken: string, responses: readonly InputResponse[] | undefined): Promise<void>;

package/dist/src/execution/tools/workflow/answer.js

@@ -0,0 +1 @@
+import{resumeHook}from"#internal/workflow/runtime.js";async function resumeWorkflowToolRunAnswers(e,t){for(let n of t??[])await resumeHook(e,{optionId:n.optionId,text:n.text})}export{resumeWorkflowToolRunAnswers};

package/dist/src/execution/tools/workflow/ask.d.ts

@@ -0,0 +1,22 @@
+import { type Hook } from "#compiled/@workflow/core/index.js";
+import type { WorkflowToolRunOwner, WorkflowToolRunRef } from "#execution/tools/workflow/messages.js";
+import type { ToolContext, ToolInputRequest, ToolInputResponse } from "#tools/definition.js";
+interface WorkflowToolRunContext {
+    /** Compatibility for already-started two-run background workflows. */
+    readonly admission?: Promise<{
+        readonly status: "accepted";
+    } | {
+        readonly status: "rejected";
+        readonly reason: string;
+    }>;
+    answerSeq: number;
+    readonly from: WorkflowToolRunRef;
+    readonly owner: WorkflowToolRunOwner;
+}
+export declare function attachWorkflowToolRunContext(ctx: ToolContext, context: Omit<WorkflowToolRunContext, "answerSeq">): void;
+export declare function readWorkflowToolRunRef(ctx: ToolContext): WorkflowToolRunRef;
+export declare function readWorkflowToolRunOwner(ctx: ToolContext): WorkflowToolRunOwner;
+export declare function readWorkflowToolRunAdmission(ctx: ToolContext): WorkflowToolRunContext["admission"];
+/** Returns an answer hook which may be awaited or raced with another workflow operation. */
+export declare function ask(ctx: ToolContext, request: ToolInputRequest): Hook<ToolInputResponse>;
+export {};

package/dist/src/execution/tools/workflow/ask.js

@@ -0,0 +1 @@
+import{createHook}from"#compiled/@workflow/core/index.js";import{workflowToolRunAnswerToken}from"#harness/workflow-tool-runs.js";import{resumeHookStep}from"#execution/tools/workflow/resume-hook-step.js";const WORKFLOW_TOOL_RUN_CONTEXT=Symbol.for(`eve.workflow-tool-run.context`);function attachWorkflowToolRunContext(e,t){Object.defineProperty(e,WORKFLOW_TOOL_RUN_CONTEXT,{enumerable:!1,value:{...t,answerSeq:0}})}function readWorkflowToolRunContext(e){let t=e[WORKFLOW_TOOL_RUN_CONTEXT];if(t===void 0)throw Error(`This function must be called with the context of a workflow tool body ("use workflow").`);return t}function readWorkflowToolRunRef(e){return readWorkflowToolRunContext(e).from}function readWorkflowToolRunOwner(e){return readWorkflowToolRunContext(e).owner}function readWorkflowToolRunAdmission(e){return readWorkflowToolRunContext(e).admission}function ask(n,r){let i=readWorkflowToolRunContext(n),a=createHook({token:workflowToolRunAnswerToken(i.from.runId,i.answerSeq++)});return resumeHookStep(i.owner.request,{from:i.from,replyTo:a.token,request:{kind:`ask`,request:r}}),a}export{ask,attachWorkflowToolRunContext,readWorkflowToolRunAdmission,readWorkflowToolRunOwner,readWorkflowToolRunRef};

package/dist/src/execution/tools/workflow/background.d.ts

@@ -0,0 +1,18 @@
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";
+import { parseJsonObject, type JsonValue } from "#shared/json.js";
+export interface WorkflowToolHarnessDefinitionInput {
+    readonly definition: HarnessToolDefinition;
+    readonly executeInput?: (input: unknown) => JsonValue;
+    readonly nodeId?: string;
+    readonly resultKind?: "subagent" | "tool";
+    readonly workflowId: string;
+}
+export declare function createWorkflowToolHarnessDefinition(input: WorkflowToolHarnessDefinitionInput): HarnessToolDefinition;
+export declare function createPreparedWorkflowToolHarnessDefinition(tool: PreparedRuntimeTool): HarnessToolDefinition;
+/** Returns a task receipt after the background scope starts the owning run. */
+export declare function createWorkflowToolBackgroundExecute(input: {
+    readonly toolName: string;
+    readonly workflowId: string;
+}): NonNullable<HarnessToolDefinition["execute"]>;
+export declare function parseWorkflowToolInput(toolInput: unknown, toolName: string): ReturnType<typeof parseJsonObject>;

package/dist/src/execution/tools/workflow/background.js

@@ -0,0 +1 @@
+import{UNSPECIFIED_INPUT_SCHEMA,toInputSchema,toOutputSchema}from"#tools/schema.js";import{parseJsonObject}from"#shared/json.js";function createWorkflowToolHarnessDefinition(e){let t=e.definition,n={executeInput:e.executeInput,nodeId:e.nodeId,resultKind:e.resultKind,workflowId:e.workflowId};return t.execution===`background`?{...t,...n,execute:createWorkflowToolBackgroundExecute({toolName:t.name,workflowId:e.workflowId})}:{...t,...n,execute:void 0}}function createPreparedWorkflowToolHarnessDefinition(r){if(r.task===void 0)throw Error(`Prepared tool "${r.name}" is not backed by a workflow task.`);return createWorkflowToolHarnessDefinition({definition:{behavior:r.behavior,description:r.description,execution:r.execution,inputSchema:toInputSchema(r.inputSchema)??UNSPECIFIED_INPUT_SCHEMA,name:r.name,outputSchema:toOutputSchema(r.outputSchema),rootOnly:r.rootOnly},nodeId:r.task.nodeId,resultKind:r.task.resultKind,workflowId:r.task.workflowId})}function createWorkflowToolBackgroundExecute(e){return(t,n,r)=>{throw Error(`Background workflow tool "${e.toolName}" must be started by the task runtime (${e.workflowId}).`)}}function parseWorkflowToolInput(e,t){try{return parseJsonObject(e)}catch(e){throw TypeError(`Tool "${t}" is a workflow, so its parsed input must be a JSON object.`,{cause:e})}}export{createPreparedWorkflowToolHarnessDefinition,createWorkflowToolBackgroundExecute,createWorkflowToolHarnessDefinition,parseWorkflowToolInput};

package/dist/src/execution/tools/workflow/body.d.ts

@@ -0,0 +1,25 @@
+import type { SessionContext } from "#context/session-context.js";
+import { type WorkflowToolRunOutcome, type WorkflowToolRunOwner, type WorkflowToolRunRef } from "#execution/tools/workflow/messages.js";
+import type { JsonObject, JsonValue } from "#shared/json.js";
+export interface WorkflowBodyDefinition {
+    readonly callId: string;
+    readonly executeInput?: JsonValue;
+    readonly input: JsonObject;
+    readonly resultKind?: "subagent" | "tool";
+    readonly session: SessionContext["session"];
+    readonly stepIndex: number;
+    readonly toolName: string;
+    readonly workflowId: string;
+}
+export interface WorkflowBodyInput extends WorkflowBodyDefinition {
+    readonly owner: WorkflowToolRunOwner;
+}
+/** Executes one registered workflow body and reports progress to its owner. */
+export declare function executeWorkflowBody(input: WorkflowBodyInput & {
+    readonly execution: "background" | "blocking";
+    readonly runId?: string;
+}, signal: AbortSignal): Promise<WorkflowToolRunOutcome>;
+export declare function createWorkflowBodyRef(input: WorkflowBodyDefinition & {
+    readonly execution: "background" | "blocking";
+    readonly runId?: string;
+}): WorkflowToolRunRef;

package/dist/src/execution/tools/workflow/body.js

@@ -0,0 +1 @@
+import{getWorkflowMetadata}from"#compiled/@workflow/core/index.js";import"#execution/tools/workflow/messages.js";import{attachWorkflowToolRunContext}from"#execution/tools/workflow/ask.js";import{resumeHookStep}from"#execution/tools/workflow/resume-hook-step.js";import{normalizeSerializableError}from"#execution/workflow-errors.js";import{readRegisteredWorkflow}from"#execution/workflow-registry.js";async function executeWorkflowBody(e,i){let a=createWorkflowBodyRef(e),o=createWorkflowBodyContext(e,i);attachWorkflowToolRunContext(o,{from:a,owner:e.owner});try{let t=resolveWorkflowToolExecute(e)(e.executeInput??e.input,o),r;if(!isAsyncIterable(t))r=await t;else{let i=t[Symbol.asyncIterator](),o,s=await i.next();for(;s.done!==!0;){o=s.value;let t={from:a,update:s.value};await resumeHookStep(e.owner.report,t),s=await i.next()}r=s.value??o??null}return{output:r,status:`completed`}}catch(e){return i.aborted?{reason:i.reason instanceof Error?i.reason.message:String(i.reason??``),status:`cancelled`}:{error:normalizeSerializableError(e),status:`failed`}}}function createWorkflowBodyRef(t){return{callId:t.callId,execution:t.execution,input:t.input,resultKind:t.resultKind,runId:t.runId??getWorkflowMetadata().workflowRunId,sequence:t.session.turn.sequence,stepIndex:t.stepIndex,toolName:t.toolName,turnId:t.session.turn.id}}function resolveWorkflowToolExecute(e){let t=readRegisteredWorkflow(e.workflowId);if(typeof t!=`function`)throw Error(`Tool "${e.toolName}" is not registered as a workflow in this deployment (${e.workflowId}). The tool was renamed or removed after this run started.`);return t}function createWorkflowBodyContext(e,t){let unavailable=(t,n)=>{throw Error(`ctx.${t} is not available inside a workflow tool; ${n}. Tool "${e.toolName}" runs as a durable workflow body, which only replays deterministic code.`)};return{abortSignal:t,callId:e.callId,getSandbox:()=>unavailable(`getSandbox()`,`the session sandbox belongs to the turn`),getSkill:()=>unavailable(`getSkill()`,`skills are read through the session sandbox`),getToken:()=>unavailable(`getToken()`,`read credentials from the environment inside a "use step" helper`),requireAuth:()=>unavailable(`requireAuth()`,`a workflow body cannot park on authorization`),session:e.session,toolName:e.toolName}}function isAsyncIterable(e){return typeof e==`object`&&!!e&&typeof e[Symbol.asyncIterator]==`function`}export{createWorkflowBodyRef,executeWorkflowBody};

package/dist/src/execution/tools/workflow/cancel.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowToolRunAddress } from "#execution/tools/workflow/types.js";
+/**
+ * Asks the run to cancel itself; cancels it outright only if the message cannot
+ * be delivered. Failures are logged, not thrown: the caller has already
+ * committed the cancellation the run was serving.
+ */
+export declare function cancelWorkflowToolRun(run: WorkflowToolRunAddress, reason: string): Promise<void>;
+export declare function cancelWorkflowToolRunStep(input: {
+    readonly reason: string;
+    readonly run: WorkflowToolRunAddress;
+}): Promise<void>;

package/dist/src/execution/tools/workflow/cancel.js

@@ -0,0 +1 @@
+import{createLogger,logError}from"#internal/logging.js";import{cancelRun,getWorld,resumeHook}from"#internal/workflow/runtime.js";import{isTaskWorkflowTargetGone}from"#execution/tasks/workflow-target.js";const log=createLogger(`execution.workflow-tool-run`);async function cancelWorkflowToolRun(e,n){let r={kind:`cancel`,reason:n};try{await resumeHook(e.hookToken,r);return}catch(t){if(isTaskWorkflowTargetGone(t))return;logError(log,`failed to signal a workflow tool run to cancel; cancelling it outright`,t,{runId:e.runId})}try{await cancelRun(await getWorld(),e.runId,{cancelReason:n})}catch(t){if(isTaskWorkflowTargetGone(t))return;logError(log,`failed to cancel workflow tool run; it may run to completion`,t,{runId:e.runId})}}async function cancelWorkflowToolRunStep(e){"use step";await cancelWorkflowToolRun(e.run,e.reason)}export{cancelWorkflowToolRun,cancelWorkflowToolRunStep};

package/dist/src/execution/tools/workflow/emit-workflow-tool-run-report-step.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowToolRunRef } from "#execution/tools/workflow/messages.js";
+import type { JsonValue } from "#shared/json.js";
+export declare function emitWorkflowToolRunReportStep(input: {
+    readonly from: WorkflowToolRunRef;
+    readonly parentWritable: WritableStream<Uint8Array>;
+    readonly update: JsonValue;
+}): Promise<void>;

package/dist/src/execution/tools/workflow/emit-workflow-tool-run-report-step.js

@@ -0,0 +1 @@
+import{createActionPartialEvent,encodeMessageStreamEvent,stampMessageStreamEvent}from"#protocol/message.js";import{createRuntimeToolResultFromValue}from"#harness/action-result-helpers.js";async function emitWorkflowToolRunReportStep(e){"use step";let t=createActionPartialEvent({result:createRuntimeToolResultFromValue({callId:e.from.callId,output:e.update,toolName:e.from.toolName}),sequence:e.from.sequence,stepIndex:e.from.stepIndex,turnId:e.from.turnId}),n=e.parentWritable.getWriter();try{await n.write(encodeMessageStreamEvent(stampMessageStreamEvent(t)))}finally{n.releaseLock()}}export{emitWorkflowToolRunReportStep};

package/dist/src/execution/tools/workflow/messages.d.ts

@@ -0,0 +1,88 @@
+import type { SubagentAuthorizationEventHookPayload } from "#channel/types.js";
+import type { AgentInvocationRequest, AgentSettlementRequest } from "#execution/tools/subagent/invoke-agent.js";
+import type { InputRequest } from "#shared/input.js";
+import type { JsonObject, JsonValue } from "#shared/json.js";
+import type { ToolInputRequest } from "#tools/definition.js";
+export interface WorkflowToolRunOwner {
+    readonly admission: string;
+    readonly outcome: string;
+    readonly report: string;
+    readonly request: string;
+}
+/**
+ * Requests the owner must apply on the run's behalf because they touch
+ * owner-held state: spawning an agent and releasing its handle afterwards.
+ */
+export type WorkflowToolAgentRequest = AgentInvocationRequest | AgentSettlementRequest;
+/**
+ * A child authorization event the owner should display. Unlike input requests
+ * it has no answer: the authorization callback completes against the child
+ * directly, so the owner only re-emits it.
+ */
+export interface WorkflowToolAuthorizationRequest {
+    readonly event: SubagentAuthorizationEventHookPayload;
+    readonly kind: "authorization-request";
+}
+/** A question authored with `ask()` from `eve/workflow`, before owner normalization. */
+export interface WorkflowToolAskRequest {
+    readonly kind: "ask";
+    readonly request: ToolInputRequest;
+}
+/**
+ * A child subagent's pending input requests for one step, forwarded as a unit
+ * so the owner resolves them against the same child step they came from.
+ */
+export interface WorkflowToolInputRequestBatch {
+    readonly kind: "input-batch";
+    readonly requests: readonly InputRequest[];
+}
+export type WorkflowToolRequest = WorkflowToolAgentRequest | WorkflowToolAuthorizationRequest | WorkflowToolAskRequest | InputRequest | WorkflowToolInputRequestBatch;
+/** Identifies the sending workflow tool run to an owner shared by many runs. */
+export interface WorkflowToolRunRef {
+    readonly callId: string;
+    readonly execution: "background" | "blocking";
+    readonly input: JsonObject;
+    readonly resultKind?: "subagent" | "tool";
+    readonly runId: string;
+    readonly sequence: number;
+    readonly stepIndex: number;
+    readonly toolName: string;
+    readonly turnId: string;
+}
+export type WorkflowToolRunOutcome = {
+    readonly status: "completed";
+    readonly output: JsonValue;
+} | {
+    readonly status: "failed";
+    readonly error: unknown;
+} | {
+    readonly status: "cancelled";
+    readonly reason?: string;
+};
+export interface WorkflowToolRunReport {
+    readonly from: WorkflowToolRunRef;
+    readonly update: JsonValue;
+}
+export interface WorkflowToolRunRequestMessage {
+    readonly from: WorkflowToolRunRef;
+    readonly replyTo: string;
+    readonly request: WorkflowToolRequest;
+    readonly requestCoordinates?: {
+        readonly sequence: number;
+        readonly stepIndex: number;
+        readonly turnId: string;
+    };
+}
+export interface WorkflowToolRunOutcomeMessage {
+    readonly from: WorkflowToolRunRef;
+    readonly result: WorkflowToolRunOutcome;
+}
+export declare const workflowToolRunReportHook: import("#compiled/@workflow/core/index.js").TypedHook<WorkflowToolRunReport, WorkflowToolRunReport>;
+export declare const workflowToolRunRequestHook: import("#compiled/@workflow/core/index.js").TypedHook<WorkflowToolRunRequestMessage, WorkflowToolRunRequestMessage>;
+export declare const workflowToolRunOutcomeHook: import("#compiled/@workflow/core/index.js").TypedHook<WorkflowToolRunOutcomeMessage, WorkflowToolRunOutcomeMessage>;
+export declare function deriveWorkflowToolRunOwner(inboxToken: string): WorkflowToolRunOwner;
+export type WorkflowToolRunControlMessage = {
+    readonly kind: "cancel";
+    readonly reason: string;
+};
+export declare function isWorkflowToolRunControlMessage(value: unknown): value is WorkflowToolRunControlMessage;

package/dist/src/execution/tools/workflow/messages.js

@@ -0,0 +1 @@
+import{defineHook}from"#compiled/@workflow/core/index.js";const workflowToolRunReportHook=defineHook(),workflowToolRunRequestHook=defineHook(),workflowToolRunOutcomeHook=defineHook();function deriveWorkflowToolRunOwner(e){return{admission:`${e}:admission`,outcome:`${e}:outcome`,report:`${e}:report`,request:`${e}:request`}}function isWorkflowToolRunControlMessage(e){if(typeof e!=`object`||!e)return!1;let{kind:t,reason:n}=e;return t===`cancel`&&typeof n==`string`}export{deriveWorkflowToolRunOwner,isWorkflowToolRunControlMessage,workflowToolRunOutcomeHook,workflowToolRunReportHook,workflowToolRunRequestHook};

package/dist/src/execution/tools/workflow/owner-inbox.d.ts

@@ -0,0 +1,13 @@
+import type { SubagentInputRequestHookPayload } from "#channel/types.js";
+import type { WorkflowToolRunOutcomeMessage, WorkflowToolRunReport, WorkflowToolRunRequestMessage } from "#execution/tools/workflow/messages.js";
+import type { RuntimeToolResultActionResult } from "#shared/action-types.js";
+import type { RuntimeSubagentResult } from "#shared/action-types.js";
+import type { WorkflowToolRunTaskInputRequest } from "#execution/tasks/child/workflow.js";
+import type { TaskCommand, TaskInboundUpdate } from "#tasks/types.js";
+export declare function workflowToolRunOutcomeToToolResult(message: WorkflowToolRunOutcomeMessage): RuntimeToolResultActionResult;
+/** Reads a blocking agent result returned through an ordinary run outcome. */
+export declare function workflowToolRunOutcomeToSubagentResult(message: WorkflowToolRunOutcomeMessage): RuntimeSubagentResult;
+export declare function workflowToolRunOutcomeToTaskCommand(message: WorkflowToolRunOutcomeMessage): TaskCommand;
+export declare function workflowToolRunReportToTaskUpdate(report: WorkflowToolRunReport, taskId: string, updateIndex: number): TaskInboundUpdate;
+export declare function workflowToolRunRequestToInputRequestPayload(message: WorkflowToolRunRequestMessage): SubagentInputRequestHookPayload;
+export declare function workflowToolRunRequestToTaskInputRequest(message: WorkflowToolRunRequestMessage): WorkflowToolRunTaskInputRequest;

package/dist/src/execution/tools/workflow/owner-inbox.js

@@ -0,0 +1 @@
+import{parseJsonValue}from"#shared/json.js";import{SUBAGENT_EXECUTION_FAILED}from"#subagents/agent-handle-errors.js";function workflowToolRunOutcomeToToolResult(e){let{from:t,result:n}=e;return n.status===`completed`?{callId:t.callId,kind:`tool-result`,output:n.output,toolName:t.toolName}:{callId:t.callId,isError:!0,kind:`tool-result`,output:n.status===`failed`?errorMessage(n.error):n.reason??`The workflow tool run was cancelled.`,toolName:t.toolName}}function workflowToolRunOutcomeToSubagentResult(e){if(e.result.status===`completed`&&isRuntimeSubagentResult(e.result.output))return e.result.output;let t=e.result.status===`failed`?errorMessage(e.result.error):e.result.status===`cancelled`?e.result.reason??`The agent invocation was cancelled.`:`The agent invocation returned an invalid result.`;return{callId:e.from.callId,isError:!0,kind:`subagent-result`,origin:`dispatch`,output:t,subagentName:e.from.toolName}}function workflowToolRunOutcomeToTaskCommand(e){return e.result.status===`completed`?{data:e.result.output,kind:`complete`}:e.result.status===`failed`?{data:e.from.resultKind===`subagent`?subagentFailureOutput(e.result.error):errorMessage(e.result.error),kind:`fail`}:{kind:`cancel`}}function subagentFailureOutput(e){let n=parseJsonValueOrUndefined(e);return n!==void 0&&typeof n==`object`&&n&&!Array.isArray(n)&&typeof Reflect.get(n,`code`)==`string`?n:{code:SUBAGENT_EXECUTION_FAILED,message:errorMessage(e)}}function workflowToolRunReportToTaskUpdate(e,t,n){return{callId:e.from.callId,kind:`task-update`,message:typeof e.update==`string`?e.update:JSON.stringify(e.update),updateEpoch:t,updateIndex:n}}function isRuntimeSubagentResult(e){if(typeof e!=`object`||!e)return!1;let t=Reflect.get(e,`origin`);return Reflect.get(e,`kind`)===`subagent-result`&&(t===`child`||t===`dispatch`)}function errorMessage(e){if(typeof e==`object`&&e&&`message`in e){let t=e.message;if(typeof t==`string`)return t}return String(e)}function parseJsonValueOrUndefined(t){try{return parseJsonValue(t)}catch{return}}function workflowToolRunRequestToInputRequestPayload(e){let{from:t,replyTo:n,request:r,requestCoordinates:i}=e;return{callId:t.callId,childContinuationToken:n,childSessionId:t.runId,event:{requests:r.kind===`input-batch`?r.requests:[normalizeInputRequest(r,t,n)],sequence:i?.sequence??t.sequence,stepIndex:i?.stepIndex??t.stepIndex,turnId:i?.turnId??t.turnId},kind:`subagent-input-request`,subagentName:t.toolName}}function workflowToolRunRequestToTaskInputRequest(e){let{from:t,replyTo:n,request:r,requestCoordinates:i}=e,a={kind:`task-input-request`,replyTo:n,sequence:i?.sequence??t.sequence,stepIndex:i?.stepIndex??t.stepIndex,turnId:i?.turnId??t.turnId};return r.kind===`input-batch`?{...a,requests:r.requests}:{...a,request:normalizeInputRequest(r,t,n)}}function normalizeInputRequest(e,t,n){switch(e.kind){case`agent-invoke`:case`agent-settled`:throw TypeError(`A workflow agent request cannot be normalized as human input.`);case`authorization-request`:throw TypeError(`A workflow authorization event cannot be normalized as human input.`);case`ask`:return normalizeAskRequest(e.request,t,n);default:return e}}function normalizeAskRequest(e,t,n){if(typeof e.prompt!=`string`||e.prompt.length===0)throw TypeError("A workflow tool run request needs a non-empty `prompt`.");let r={action:{callId:t.callId,input:t.input,kind:`tool-call`,toolName:t.toolName},kind:`question`,prompt:e.prompt,requestId:n};return e.allowFreeform!==void 0&&(r.allowFreeform=e.allowFreeform),e.display!==void 0&&(r.display=e.display),e.options!==void 0&&(r.options=[...e.options]),r}export{workflowToolRunOutcomeToSubagentResult,workflowToolRunOutcomeToTaskCommand,workflowToolRunOutcomeToToolResult,workflowToolRunReportToTaskUpdate,workflowToolRunRequestToInputRequestPayload,workflowToolRunRequestToTaskInputRequest};

package/dist/src/execution/tools/workflow/owner.d.ts

@@ -0,0 +1,13 @@
+import { type WorkflowToolRunOutcomeMessage, type WorkflowToolRunReport, type WorkflowToolRunRequestMessage } from "#execution/tools/workflow/messages.js";
+import { type ChannelReader } from "#execution/tools/workflow/owner-channels.js";
+/** In read priority: what a workflow tool run said before its outcome lands first. */
+export type WorkflowToolRunOwnerReaders = readonly [
+    ChannelReader<"report", WorkflowToolRunReport>,
+    ChannelReader<"request", WorkflowToolRunRequestMessage>,
+    ChannelReader<"outcome", WorkflowToolRunOutcomeMessage>
+];
+export interface WorkflowToolRunOwnerChannels {
+    readonly readers: WorkflowToolRunOwnerReaders;
+    dispose(): Promise<void>;
+}
+export declare function openWorkflowToolRunOwnerChannels(inboxToken: string): WorkflowToolRunOwnerChannels;

package/dist/src/execution/tools/workflow/owner.js

@@ -0,0 +1 @@
+import{disposeHook}from"#execution/hook-ownership.js";import{deriveWorkflowToolRunOwner,workflowToolRunOutcomeHook,workflowToolRunReportHook,workflowToolRunRequestHook}from"#execution/tools/workflow/messages.js";import{createChannelReader}from"#execution/tools/workflow/owner-channels.js";function openWorkflowToolRunOwnerChannels(e){let t=deriveWorkflowToolRunOwner(e),n=workflowToolRunReportHook.create({token:t.report}),r=workflowToolRunRequestHook.create({token:t.request}),i=workflowToolRunOutcomeHook.create({token:t.outcome});return{readers:[createChannelReader(`report`,n),createChannelReader(`request`,r),createChannelReader(`outcome`,i)],async dispose(){await disposeHook(n),await disposeHook(r),await disposeHook(i)}}}export{openWorkflowToolRunOwnerChannels};

package/dist/src/execution/tools/workflow/run-control.d.ts

@@ -0,0 +1,18 @@
+import { type Hook } from "#compiled/@workflow/core/index.js";
+import { type WorkflowToolRunControlMessage } from "#execution/tools/workflow/messages.js";
+/**
+ * The run's control inbox. An unawaited hook read is not scheduled under
+ * replay, so `cancelled` must be raced for a cancel to be observed at all.
+ */
+export interface WorkflowToolRunControlInbox {
+    readonly hook: Hook<WorkflowToolRunControlMessage>;
+    readonly signal: AbortSignal;
+    /** Rejects with {@link WorkflowToolRunCancelledError} when a cancel message arrives; never resolves. */
+    readonly cancelled: Promise<never>;
+    reason(): string | undefined;
+}
+/** Opens without claiming, so a losing duplicate start never trips the signal. */
+export declare function openWorkflowToolRunControlInbox(hookToken: string): WorkflowToolRunControlInbox;
+export declare class WorkflowToolRunCancelledError extends Error {
+    constructor(reason: string);
+}

package/dist/src/execution/tools/workflow/run-control.js

@@ -0,0 +1 @@
+import{createHook}from"#compiled/@workflow/core/index.js";import{isWorkflowToolRunControlMessage}from"#execution/tools/workflow/messages.js";function openWorkflowToolRunControlInbox(t){let n=createHook({token:t}),r=n[Symbol.asyncIterator](),i=new AbortController,a,o=consumeCancel(r,e=>{a=e,i.abort(new WorkflowToolRunCancelledError(e))});return o.catch(()=>{}),{cancelled:o,hook:n,reason:()=>a,signal:i.signal}}async function consumeCancel(e,n){for(;;){let r;try{r=await e.next()}catch{return await new Promise(()=>{})}if(r.done===!0)return await new Promise(()=>{});if(isWorkflowToolRunControlMessage(r.value))throw n(r.value.reason),new WorkflowToolRunCancelledError(r.value.reason)}}var WorkflowToolRunCancelledError=class extends Error{constructor(e){super(e),this.name=`WorkflowToolRunCancelledError`}};export{WorkflowToolRunCancelledError,openWorkflowToolRunControlInbox};