eve 0.68.0 → 0.69.0

package/dist/src/eve-channel/request.js

@@ -1,4 +1,4 @@
-import{isInputResponse}from"#shared/input.js";import{hasInternalRefScheme}from"#internal/attachments/url-refs.js";import{parseJsonObject}from"#shared/json.js";import{EVE_MESSAGE_STREAM_CONTENT_TYPE,EVE_MESSAGE_STREAM_FORMAT,EVE_MESSAGE_STREAM_VERSION,EVE_SESSION_ID_HEADER,EVE_STREAM_CONTROL_VERSION,EVE_STREAM_CONTROL_VERSION_QUERY,EVE_STREAM_FORMAT_HEADER,EVE_STREAM_LEASE_ENDED_CONTROL,EVE_STREAM_TAIL_INDEX_HEADER,EVE_STREAM_VERSION_HEADER}from"#protocol/message.js";import{collectUploadPolicyViolations,formatUploadPolicyViolation}from"#public/channels/upload-policy.js";import{parseSessionCallback}from"#channel/session-callback.js";import{parseActivityObserverField,validateActivityObserverBinding}from"#eve-channel/activity-observer-request.js";import{parseTaskDeliveryPolicyField,parseTurnPolicyField}from"#eve-channel/delivery-policy-request.js";import{validateMessageFreeCreate}from"#eve-channel/create-request.js";async function deriveOperationContinuationToken(e){let t=JSON.stringify([`eve:create-session:v1`,e.auth.authenticator,e.auth.issuer??null,e.auth.principalType,e.auth.principalId,e.operationId]),n=await crypto.subtle.digest(`SHA-256`,new TextEncoder().encode(t));return`eve:op:${Array.from(new Uint8Array(n),e=>e.toString(16).padStart(2,`0`)).join(``).slice(0,32)}`}function parseCreateBody(e){if(e.inputResponses!==void 0)return Response.json({error:`'inputResponses' is only accepted for an existing session.`,ok:!1},{status:400});let t=parseMessageField(e.message);if(t instanceof Response)return t;let n=parseClientContextField(e.clientContext);if(n instanceof Response)return n;let r=parseCallbackField(e.callback);if(r instanceof Response)return r;let i=parseCapabilitiesField(e.capabilities);if(i instanceof Response)return i;let a=parseActivityObserverField(e.activityObserver);if(a instanceof Response)return a;if(a!==void 0){let e=validateActivityObserverBinding(a,r);if(e!==void 0)return e}let o=parseTaskDeliveryPolicyField(e.taskDeliveryPolicy,t);if(o instanceof Response)return o;let s=parseOutputSchemaField(e.outputSchema);if(s instanceof Response)return s;let c=validateMessageFreeCreate({activityObserver:a,callback:r,hasClientContext:e.clientContext!==void 0,hasMessageField:`message`in e,message:t,outputSchema:s});if(c!==void 0)return c;let l=e.operationId;if(l!==void 0&&(typeof l!=`string`||!l))return Response.json({error:`Expected 'operationId' to be a non-empty string.`,ok:!1},{status:400});let u={taskDeliveryPolicy:o,activityObserver:a,callback:r,capabilities:i,context:n,outputSchema:s};return t!==void 0&&(u.message=t),typeof l==`string`&&(u.operationId=l),u}function parseSessionMessageBody(e){let t=rejectSessionContinuationToken(e);if(t!==null)return t;let n=parseMessageField(e.message);if(n instanceof Response)return n;let r=parseCallbackField(e.callback);if(r instanceof Response)return r;let i=parseActivityObserverField(e.activityObserver);if(i instanceof Response)return i;if(i!==void 0){let e=validateActivityObserverBinding(i,r);if(e!==void 0)return e}let a=parseInputResponses$1(e.inputResponses);if(a instanceof Response)return a;let o=parseClientContextField(e.clientContext);if(o instanceof Response)return o;let s=parseTaskDeliveryPolicyField(e.taskDeliveryPolicy,n);if(s instanceof Response)return s;let c=parseOutputSchemaField(e.outputSchema);if(c instanceof Response)return c;let l=parseTurnPolicyField(e.turnPolicy);return l instanceof Response?l:n===void 0&&a===void 0?Response.json({error:`Expected a non-empty 'message' or a non-empty 'inputResponses' array.`,ok:!1},{status:400}):n!==void 0&&a!==void 0?Response.json({error:`'message' and 'inputResponses' are mutually exclusive.`,ok:!1},{status:400}):{activityObserver:i,callback:r,message:n,inputResponses:a,context:o,outputSchema:c,turnPolicy:l,taskDeliveryPolicy:s}}async function parseCancelTurnBody(e){let t=await parseOptionalJsonRequest(e);if(t instanceof Response)return t;let n=rejectSessionContinuationToken(t);if(n!==null)return n;let r=t.turnId,i=t.taskId,a=t.tasks;if(r!==void 0&&(typeof r!=`string`||r.length===0))return Response.json({error:`Expected 'turnId' to be a non-empty string.`,ok:!1},{status:400});if(a!==void 0&&typeof a!=`boolean`)return Response.json({error:`Expected 'tasks' to be a boolean.`,ok:!1},{status:400});if(i!==void 0&&(typeof i!=`string`||i.length===0))return Response.json({error:`Expected 'taskId' to be a non-empty string.`,ok:!1},{status:400});let o={};return typeof i==`string`&&(o.taskId=i),typeof a==`boolean`&&(o.tasks=a),typeof r==`string`&&(o.turnId=r),o}async function parseJsonRequest(e){let t;try{t=await e.json()}catch{return Response.json({error:`Invalid JSON body.`,ok:!1},{status:400})}return typeof t!=`object`||!t||Array.isArray(t)?Response.json({error:`Expected a JSON object.`,ok:!1},{status:400}):t}async function parseResetBody(e){let t=await parseOptionalJsonRequest(e);if(t instanceof Response)return t;let n=rejectSessionContinuationToken(t);if(n!==null)return n;let r=t.reason;return r!==void 0&&(typeof r!=`string`||r.length===0)?Response.json({error:`Expected 'reason' to be a non-empty string.`,ok:!1},{status:400}):r===void 0?{}:{reason:r}}async function parseSessionControlBody(e){let t=await parseOptionalJsonRequest(e);return t instanceof Response?t:rejectSessionContinuationToken(t)??t}async function parseOptionalJsonRequest(e){let t;try{t=await e.text()}catch{return Response.json({error:`Unreadable request body.`,ok:!1},{status:400})}if(t.trim().length===0)return{};let n;try{n=JSON.parse(t)}catch{return Response.json({error:`Invalid JSON body.`,ok:!1},{status:400})}return typeof n!=`object`||!n||Array.isArray(n)?Response.json({error:`Expected a JSON object.`,ok:!1},{status:400}):n}function rejectSessionContinuationToken(e){return`continuationToken`in e?Response.json({error:`Session-ID routes do not accept 'continuationToken'.`,ok:!1},{status:400}):null}function requireSessionId(e){return e.sessionId||Response.json({error:`Missing session id.`,ok:!1},{status:400})}async function createSessionStreamResponse(e,t){let n=parseStartIndex(e);if(n instanceof Response)return n;let r=parseIncludeTailIndex(e);try{let i=r?await t.getStreamTailIndex():void 0,a=await t.getEventStream({startIndex:n}),o=new URL(e.url).searchParams.get(EVE_STREAM_CONTROL_VERSION_QUERY)===EVE_STREAM_CONTROL_VERSION?EVE_STREAM_CONTROL_VERSION:void 0,s=new Headers({"cache-control":`no-store, no-transform`,"content-type":EVE_MESSAGE_STREAM_CONTENT_TYPE,"x-accel-buffering":`no`,[EVE_SESSION_ID_HEADER]:t.id,[EVE_STREAM_FORMAT_HEADER]:EVE_MESSAGE_STREAM_FORMAT,[EVE_STREAM_VERSION_HEADER]:EVE_MESSAGE_STREAM_VERSION});return i!==void 0&&s.set(EVE_STREAM_TAIL_INDEX_HEADER,String(i)),new Response(serializeAsNdjson(a,e.signal,streamEventLimit(n,i),o!==void 0),{headers:s})}catch{return Response.json({error:`Session not found.`,ok:!1},{status:404})}}function parseOutputSchemaField(e){if(e!==void 0)try{return parseJsonObject(e)}catch{return Response.json({error:`Expected 'outputSchema' to be a JSON-serializable object.`,ok:!1},{status:400})}}function parseCallbackField(e){if(e===void 0)return;let t=parseSessionCallback(e);return t.ok?t.callback:Response.json({error:t.message,ok:!1},{status:400})}function parseCapabilitiesField(e){if(e===void 0)return;if(typeof e!=`object`||!e||Array.isArray(e))return Response.json({error:`Expected 'capabilities' to be an object.`,ok:!1},{status:400});let t=Object.keys(e),n=Reflect.get(e,`requestInput`);return t.some(e=>e!==`requestInput`)||n!==void 0&&typeof n!=`boolean`?Response.json({error:`Expected 'capabilities.requestInput' to be a boolean when provided.`,ok:!1},{status:400}):n===void 0?{}:{requestInput:n}}function parseMessageField(e){if(e===void 0)return;if(typeof e==`string`)return e.length>0?e:void 0;if(!Array.isArray(e))return Response.json({error:`Expected 'message' to be a string or an array of text/file parts.`,ok:!1},{status:400});if(e.length===0)return;let t=[];for(let n of e){let e=parseMessagePart(n);if(e instanceof Response)return e;t.push(e)}return t}function parseMessagePart(e){if(typeof e!=`object`||!e)return Response.json({error:`Expected each message part to be an object.`,ok:!1},{status:400});let t=e;if(t.type===`text`)return typeof t.text!=`string`||t.text.length===0?Response.json({error:`Text parts require a non-empty 'text' string.`,ok:!1},{status:400}):{type:`text`,text:t.text};if(t.type===`file`){if(typeof t.mediaType!=`string`||t.mediaType.length===0)return Response.json({error:`File parts require a non-empty 'mediaType' string.`,ok:!1},{status:400});if(typeof t.data!=`string`)return Response.json({error:`File parts require a 'data' string (base64, data URL, or URL).`,ok:!1},{status:400});if(hasInternalRefScheme(t.data))return Response.json({error:`File part 'data' must not use a framework-internal ref scheme.`,ok:!1},{status:400});let e={type:`file`,mediaType:t.mediaType,data:t.data};return typeof t.filename==`string`&&t.filename.length>0&&(e.filename=t.filename),e}return Response.json({error:`Unsupported message part type "${String(t.type)}". Use 'text' or 'file'.`,ok:!1},{status:400})}function checkUploadPolicy(e,t){if(!e.message)return null;let n=collectUploadPolicyViolations(e.message,t);if(n.length===0)return null;let[r]=n;if(!r)return null;let i=r.kind===`too-large`?413:415;return Response.json({error:formatUploadPolicyViolation(r),ok:!1,violations:n.map(e=>e.kind===`too-large`?{byteLength:e.byteLength,filename:e.filename,kind:e.kind,limit:e.limit,mediaType:e.mediaType}:{allowedMediaTypes:e.allowedMediaTypes,filename:e.filename,kind:e.kind,mediaType:e.mediaType})},{status:i})}function parseInputResponses$1(e){if(e===void 0)return;if(!Array.isArray(e)||e.length===0)return Response.json({error:`Expected 'inputResponses' to be a non-empty array.`,ok:!1},{status:400});let t=e.filter(isInputResponse);return t.length===e.length?t:Response.json({error:`Expected every 'inputResponses' entry to match the HITL response schema.`,ok:!1},{status:400})}function parseClientContextField(e){if(e!==void 0){if(typeof e==`string`)return e.length>0?[toClientContextMessage(e)]:void 0;if(Array.isArray(e))return e.length===0?void 0:e.every(e=>typeof e==`string`&&e.length>0)?e.map(e=>toClientContextMessage(e)):Response.json({error:`Expected 'clientContext' array entries to be non-empty strings.`,ok:!1},{status:400});if(typeof e!=`object`||!e)return Response.json({error:`Expected 'clientContext' to be a string, string array, or JSON object.`,ok:!1},{status:400});try{let t=parseJsonObject(e);return[toClientContextMessage(JSON.stringify(t))]}catch{return Response.json({error:`Expected 'clientContext' to be a JSON-serializable object.`,ok:!1},{status:400})}}}function toClientContextMessage(e){return`Client context:
+import{isInputResponse}from"#shared/input.js";import{hasInternalRefScheme}from"#internal/attachments/url-refs.js";import{EVE_MESSAGE_STREAM_CONTENT_TYPE,EVE_MESSAGE_STREAM_FORMAT,EVE_MESSAGE_STREAM_VERSION,EVE_SESSION_ID_HEADER,EVE_STREAM_CONTROL_VERSION,EVE_STREAM_CONTROL_VERSION_QUERY,EVE_STREAM_FORMAT_HEADER,EVE_STREAM_LEASE_ENDED_CONTROL,EVE_STREAM_TAIL_INDEX_HEADER,EVE_STREAM_VERSION_HEADER}from"#protocol/message.js";import{parseJsonObject}from"#shared/json.js";import{LEGACY_REMOTE_AGENT_PROTOCOL_VERSION,splitLegacyTaskFields}from"#execution/legacy-remote-agent/protocol.js";import{collectUploadPolicyViolations,formatUploadPolicyViolation}from"#public/channels/upload-policy.js";import{parseSessionCallback}from"#channel/session-callback.js";import{REMOTE_AGENT_PROTOCOL_MISMATCH,REMOTE_AGENT_PROTOCOL_VERSION,readRemoteAgentProtocolVersion}from"#protocol/remote-agent-protocol.js";import{parseTurnPolicyField}from"#eve-channel/turn-policy-request.js";import{validateMessageFreeCreate}from"#eve-channel/create-request.js";async function deriveOperationContinuationToken(e){let t=JSON.stringify([`eve:create-session:v1`,e.auth.authenticator,e.auth.issuer??null,e.auth.principalType,e.auth.principalId,e.operationId]),n=await crypto.subtle.digest(`SHA-256`,new TextEncoder().encode(t));return`eve:op:${Array.from(new Uint8Array(n),e=>e.toString(16).padStart(2,`0`)).join(``).slice(0,32)}`}function parseCreateBody(e){let t=splitLegacyTaskFields(e),{payload:n}=t;if(n.inputResponses!==void 0)return Response.json({error:`'inputResponses' is only accepted for an existing session.`,ok:!1},{status:400});let r=parseMessageField(n.message);if(r instanceof Response)return r;let i=parseClientContextField(n.clientContext);if(i instanceof Response)return i;let a=parseCallbackField(n.callback);if(a instanceof Response)return a;let o=a===void 0?void 0:parseProtocolVersionField(n.protocolVersion);if(o instanceof Response)return o;let s=parseCapabilitiesField(n.capabilities);if(s instanceof Response)return s;let c=parseOutputSchemaField(n.outputSchema);if(c instanceof Response)return c;let l=validateMessageFreeCreate({callback:a,hasClientContext:n.clientContext!==void 0,hasMessageField:`message`in n,message:r,outputSchema:c});if(l!==void 0)return l;let u=n.operationId;if(u!==void 0&&(typeof u!=`string`||!u))return Response.json({error:`Expected 'operationId' to be a non-empty string.`,ok:!1},{status:400});let d={callback:a,capabilities:s,context:i,outputSchema:c};return r!==void 0&&(d.message=r),typeof u==`string`&&(d.operationId=u),o!==void 0&&(d.protocolVersion=o),o===LEGACY_REMOTE_AGENT_PROTOCOL_VERSION&&(d.legacyRemoteAgentCaller=t.taskId===void 0?{}:{taskId:t.taskId}),d}function parseSessionMessageBody(e){let{payload:t}=splitLegacyTaskFields(e),n=rejectSessionContinuationToken(t);if(n!==null)return n;let r=parseMessageField(t.message);if(r instanceof Response)return r;let i=parseCallbackField(t.callback);if(i instanceof Response)return i;let a=parseInputResponses$1(t.inputResponses);if(a instanceof Response)return a;let o=parseClientContextField(t.clientContext);if(o instanceof Response)return o;let s=parseOutputSchemaField(t.outputSchema);if(s instanceof Response)return s;let c=parseTurnPolicyField(t.turnPolicy);return c instanceof Response?c:r===void 0&&a===void 0?Response.json({error:`Expected a non-empty 'message' or a non-empty 'inputResponses' array.`,ok:!1},{status:400}):r!==void 0&&a!==void 0?Response.json({error:`'message' and 'inputResponses' are mutually exclusive.`,ok:!1},{status:400}):{callback:i,message:r,inputResponses:a,context:o,outputSchema:s,turnPolicy:c}}async function parseCancelTurnBody(e){let t=await parseOptionalJsonRequest(e);if(t instanceof Response)return t;let n=rejectSessionContinuationToken(t);if(n!==null)return n;let r=t.turnId;return r!==void 0&&(typeof r!=`string`||r.length===0)?Response.json({error:`Expected 'turnId' to be a non-empty string.`,ok:!1},{status:400}):typeof r==`string`?{turnId:r}:{}}async function parseJsonRequest(e){let t;try{t=await e.json()}catch{return Response.json({error:`Invalid JSON body.`,ok:!1},{status:400})}return typeof t!=`object`||!t||Array.isArray(t)?Response.json({error:`Expected a JSON object.`,ok:!1},{status:400}):t}async function parseResetBody(e){let t=await parseOptionalJsonRequest(e);if(t instanceof Response)return t;let n=rejectSessionContinuationToken(t);if(n!==null)return n;let r=t.reason;return r!==void 0&&(typeof r!=`string`||r.length===0)?Response.json({error:`Expected 'reason' to be a non-empty string.`,ok:!1},{status:400}):r===void 0?{}:{reason:r}}async function parseSessionControlBody(e){let t=await parseOptionalJsonRequest(e);return t instanceof Response?t:rejectSessionContinuationToken(t)??t}async function parseOptionalJsonRequest(e){let t;try{t=await e.text()}catch{return Response.json({error:`Unreadable request body.`,ok:!1},{status:400})}if(t.trim().length===0)return{};let n;try{n=JSON.parse(t)}catch{return Response.json({error:`Invalid JSON body.`,ok:!1},{status:400})}return typeof n!=`object`||!n||Array.isArray(n)?Response.json({error:`Expected a JSON object.`,ok:!1},{status:400}):n}function rejectSessionContinuationToken(e){return`continuationToken`in e?Response.json({error:`Session-ID routes do not accept 'continuationToken'.`,ok:!1},{status:400}):null}function requireSessionId(e){return e.sessionId||Response.json({error:`Missing session id.`,ok:!1},{status:400})}async function createSessionStreamResponse(e,t){let n=parseStartIndex(e);if(n instanceof Response)return n;let r=parseIncludeTailIndex(e);try{let i=r?await t.getStreamTailIndex():void 0,a=await t.getEventStream({startIndex:n}),o=new URL(e.url).searchParams.get(EVE_STREAM_CONTROL_VERSION_QUERY)===EVE_STREAM_CONTROL_VERSION?EVE_STREAM_CONTROL_VERSION:void 0,s=new Headers({"cache-control":`no-store, no-transform`,"content-type":EVE_MESSAGE_STREAM_CONTENT_TYPE,"x-accel-buffering":`no`,[EVE_SESSION_ID_HEADER]:t.id,[EVE_STREAM_FORMAT_HEADER]:EVE_MESSAGE_STREAM_FORMAT,[EVE_STREAM_VERSION_HEADER]:EVE_MESSAGE_STREAM_VERSION});return i!==void 0&&s.set(EVE_STREAM_TAIL_INDEX_HEADER,String(i)),new Response(serializeAsNdjson(a,e.signal,streamEventLimit(n,i),o!==void 0),{headers:s})}catch{return Response.json({error:`Session not found.`,ok:!1},{status:404})}}function parseOutputSchemaField(e){if(e!==void 0)try{return parseJsonObject(e)}catch{return Response.json({error:`Expected 'outputSchema' to be a JSON-serializable object.`,ok:!1},{status:400})}}function parseCallbackField(e){if(e===void 0)return;let t=parseSessionCallback(e);return t.ok?t.callback:Response.json({error:t.message,ok:!1},{status:400})}function parseProtocolVersionField(e){if(e!==void 0&&typeof e!=`number`)return Response.json({error:`Expected 'protocolVersion' to be a number.`,ok:!1},{status:400});let t=readRemoteAgentProtocolVersion(e);return t===REMOTE_AGENT_PROTOCOL_VERSION||t===LEGACY_REMOTE_AGENT_PROTOCOL_VERSION?t:Response.json({code:REMOTE_AGENT_PROTOCOL_MISMATCH,error:`This deployment speaks eve remote agent protocol ${String(REMOTE_AGENT_PROTOCOL_VERSION)}, but the caller speaks protocol ${String(t)}. Upgrade both deployments to the same eve release.`,ok:!1,protocolVersion:REMOTE_AGENT_PROTOCOL_VERSION},{status:409})}function parseCapabilitiesField(e){if(e===void 0)return;if(typeof e!=`object`||!e||Array.isArray(e))return Response.json({error:`Expected 'capabilities' to be an object.`,ok:!1},{status:400});let t=Object.keys(e),n=Reflect.get(e,`requestInput`);return t.some(e=>e!==`requestInput`)||n!==void 0&&typeof n!=`boolean`?Response.json({error:`Expected 'capabilities.requestInput' to be a boolean when provided.`,ok:!1},{status:400}):n===void 0?{}:{requestInput:n}}function parseMessageField(e){if(e===void 0)return;if(typeof e==`string`)return e.length>0?e:void 0;if(!Array.isArray(e))return Response.json({error:`Expected 'message' to be a string or an array of text/file parts.`,ok:!1},{status:400});if(e.length===0)return;let t=[];for(let n of e){let e=parseMessagePart(n);if(e instanceof Response)return e;t.push(e)}return t}function parseMessagePart(e){if(typeof e!=`object`||!e)return Response.json({error:`Expected each message part to be an object.`,ok:!1},{status:400});let t=e;if(t.type===`text`)return typeof t.text!=`string`||t.text.length===0?Response.json({error:`Text parts require a non-empty 'text' string.`,ok:!1},{status:400}):{type:`text`,text:t.text};if(t.type===`file`){if(typeof t.mediaType!=`string`||t.mediaType.length===0)return Response.json({error:`File parts require a non-empty 'mediaType' string.`,ok:!1},{status:400});if(typeof t.data!=`string`)return Response.json({error:`File parts require a 'data' string (base64, data URL, or URL).`,ok:!1},{status:400});if(hasInternalRefScheme(t.data))return Response.json({error:`File part 'data' must not use a framework-internal ref scheme.`,ok:!1},{status:400});let e={type:`file`,mediaType:t.mediaType,data:t.data};return typeof t.filename==`string`&&t.filename.length>0&&(e.filename=t.filename),e}return Response.json({error:`Unsupported message part type "${String(t.type)}". Use 'text' or 'file'.`,ok:!1},{status:400})}function checkUploadPolicy(e,t){if(!e.message)return null;let n=collectUploadPolicyViolations(e.message,t);if(n.length===0)return null;let[r]=n;if(!r)return null;let i=r.kind===`too-large`?413:415;return Response.json({error:formatUploadPolicyViolation(r),ok:!1,violations:n.map(e=>e.kind===`too-large`?{byteLength:e.byteLength,filename:e.filename,kind:e.kind,limit:e.limit,mediaType:e.mediaType}:{allowedMediaTypes:e.allowedMediaTypes,filename:e.filename,kind:e.kind,mediaType:e.mediaType})},{status:i})}function parseInputResponses$1(e){if(e===void 0)return;if(!Array.isArray(e)||e.length===0)return Response.json({error:`Expected 'inputResponses' to be a non-empty array.`,ok:!1},{status:400});let t=e.filter(isInputResponse);return t.length===e.length?t:Response.json({error:`Expected every 'inputResponses' entry to match the HITL response schema.`,ok:!1},{status:400})}function parseClientContextField(e){if(e!==void 0){if(typeof e==`string`)return e.length>0?[toClientContextMessage(e)]:void 0;if(Array.isArray(e))return e.length===0?void 0:e.every(e=>typeof e==`string`&&e.length>0)?e.map(e=>toClientContextMessage(e)):Response.json({error:`Expected 'clientContext' array entries to be non-empty strings.`,ok:!1},{status:400});if(typeof e!=`object`||!e)return Response.json({error:`Expected 'clientContext' to be a string, string array, or JSON object.`,ok:!1},{status:400});try{let t=parseJsonObject(e);return[toClientContextMessage(JSON.stringify(t))]}catch{return Response.json({error:`Expected 'clientContext' to be a JSON-serializable object.`,ok:!1},{status:400})}}}function toClientContextMessage(e){return`Client context:
 ${e}`}function parseIncludeTailIndex(e){let t=new URL(e.url).searchParams.get(`includeTailIndex`);return t===`1`||t===`true`}function parseStartIndex(e){let t=new URL(e.url).searchParams.get(`startIndex`);if(t===null)return;let n=Number(t);return!/^-?\d+$/.test(t)||!Number.isSafeInteger(n)?Response.json({error:`Expected startIndex to be an integer.`,ok:!1},{status:400}):n}function streamEventLimit(e,t){if(t===void 0)return;let n=e===void 0?0:e<0?Math.max(0,t+1+e):e;return Math.max(0,t-n+1)}function serializeAsNdjson(e,t,n,r=!1){let i=new TextEncoder,a=0,o,s,clearTimers=()=>{clearTimeout(o),clearTimeout(s),o=void 0,s=void 0},scheduleHeartbeat=e=>{clearTimeout(o),o=setTimeout(()=>{try{e.enqueue(i.encode(`
 `)),scheduleHeartbeat(e)}catch{clearTimers()}},1e4)},startLease=e=>{scheduleHeartbeat(e),s=setTimeout(()=>{clearTimers();try{e.enqueue(i.encode(`${JSON.stringify(EVE_STREAM_LEASE_ENDED_CONTROL)}\n`)),e.terminate()}catch{}},6e4)},c=new TransformStream({start(e){e.enqueue(i.encode(`
 `)),n===0?e.terminate():r&&startLease(e)},transform(e,t){t.enqueue(i.encode(`${JSON.stringify(e)}\n`)),a+=1,a===n?(clearTimers(),t.terminate()):r&&scheduleHeartbeat(t)},flush(){clearTimers()}});return e.pipeTo(c.writable,{signal:t}).catch(()=>{}).finally(clearTimers),c.readable}export{checkUploadPolicy,createSessionStreamResponse,deriveOperationContinuationToken,parseCancelTurnBody,parseCreateBody,parseIncludeTailIndex,parseJsonRequest,parseOptionalJsonRequest,parseResetBody,parseSessionControlBody,parseSessionMessageBody,parseStartIndex,rejectSessionContinuationToken,requireSessionId};

package/dist/src/eve-channel/support.d.ts

@@ -1,21 +1,30 @@
 import type { UserContent } from "ai";
 import type { SessionAuthContext } from "#channel/types.js";
-import type { MessageStreamEvent, SubagentCalledStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
 import type { ChannelCors } from "#public/definitions/channel.js";
-import { type EveChannelCors, type EveChannelInput } from "#eve-channel/types.js";
+import { type EveChannelCors, type EveChannelInput, type EveHandle } from "#eve-channel/types.js";
 export declare function healthResponse(): Response;
-export declare function findRemoteSubagentBinding(input: {
+/** Where a remote child the parent session recorded runs, and its credential key. */
+export interface RemoteAgentBinding {
+    readonly forwardPrincipal?: boolean;
+    readonly name: string;
+    readonly resolverId?: string;
+    readonly url: string;
+}
+interface RemoteAgentStreamCoordinates {
     readonly callId: string;
     readonly childSessionId: string;
     readonly childStreamPath: string;
-    readonly parentSessionId: string;
+}
+/** Finds the remote child the parent session recorded for one proxy route, from its `agent.started` event. */
+export declare function findRemoteAgentBinding(input: RemoteAgentStreamCoordinates & {
     readonly parent: {
         getEventStream(options?: {
             startIndex?: number;
         }): Promise<ReadableStream<MessageStreamEvent>>;
         getStreamTailIndex(): Promise<number>;
     };
-}): Promise<SubagentCalledStreamEvent | undefined>;
+}): Promise<RemoteAgentBinding | undefined>;
 export declare function normalizeEveCors(cors: EveChannelCors | undefined): ChannelCors;
 interface OnMessageOutcome {
     readonly auth: SessionAuthContext | null;
@@ -25,6 +34,7 @@ interface OnMessageOutcome {
 export declare function resolveOnMessage(input: {
     readonly auth: SessionAuthContext | null;
     readonly config: EveChannelInput;
+    readonly invocation?: EveHandle["invocation"];
     readonly message: string | UserContent;
     readonly request: Request;
     readonly sessionId?: string;

package/dist/src/eve-channel/support.js

@@ -1 +1 @@
-import{createLogger,logError}from"#internal/logging.js";import{defaultEveAuth}from"#eve-channel/types.js";import{workflowEntryReference}from"#execution/workflow-runtime.js";const log=createLogger(`eve.channel`);function healthResponse(){return Response.json({ok:!0,status:`ready`,workflowId:workflowEntryReference.workflowId})}async function findRemoteSubagentBinding(e){let t=await e.parent.getStreamTailIndex();if(t<0)return;let n=(await e.parent.getEventStream({startIndex:0})).getReader(),r;try{for(let i=0;i<=t;i+=1){let t=await n.read();if(t.done)break;let i=t.value;i.type===`subagent.called`&&i.data.sessionId===e.parentSessionId&&i.data.callId===e.callId&&i.data.childSessionId===e.childSessionId&&i.data.childStreamPath===e.childStreamPath&&i.data.remote!==void 0&&(r=i)}}finally{await n.cancel().catch(()=>{})}return r}function normalizeEveCors(e){if(e===void 0||e===!1)return!1;if(e===!0)return!0;let t={};return e.origin!==void 0&&(t.origin=normalizeEveCorsOrigin(e.origin)),e.methods!==void 0&&(t.methods=e.methods),e.allowedHeaders!==void 0&&(t.allowHeaders=e.allowedHeaders),e.exposedHeaders!==void 0&&(t.exposeHeaders=e.exposedHeaders),e.credentials!==void 0&&(t.credentials=e.credentials),e.maxAge!==void 0&&(t.maxAge=e.maxAge),e.preflightStatus!==void 0&&(t.preflight={statusCode:e.preflightStatus}),t}function normalizeEveCorsOrigin(e){return e===`*`||e===`null`?e:typeof e==`string`?[e]:e}async function resolveOnMessage(e){let t=e.config.onMessage??defaultOnMessage,n;try{if(n=await t({eve:e.sessionId===void 0?{caller:e.auth,request:e.request}:{caller:e.auth,request:e.request,sessionId:e.sessionId}},e.message),n==null)throw TypeError(`eveChannel onMessage must return an auth result.`)}catch(t){let n=logError(log,`onMessage handler failed`,t,{sessionId:e.sessionId});return Response.json({error:`onMessage handler failed.`,errorId:n,ok:!1},{status:500})}return{auth:n.auth,context:n.context,title:n.title}}function defaultOnMessage(e){return{auth:defaultEveAuth(e)}}export{findRemoteSubagentBinding,healthResponse,normalizeEveCors,resolveOnMessage};
+import{createLogger,logError}from"#internal/logging.js";import{defaultEveAuth}from"#eve-channel/types.js";import{workflowEntryReference}from"#execution/workflow-runtime.js";const log=createLogger(`eve.channel`);function healthResponse(){return Response.json({ok:!0,status:`ready`,workflowId:workflowEntryReference.workflowId})}async function findRemoteAgentBinding(e){let t=await e.parent.getStreamTailIndex();if(t<0)return;let n=(await e.parent.getEventStream({startIndex:0})).getReader(),r;try{for(let i=0;i<=t;i+=1){let t=await n.read();if(t.done)break;r=readRemoteAgentBinding(t.value,e)??r}}finally{await n.cancel().catch(()=>{})}return r}function readRemoteAgentBinding(e,t){if(e.type!==`agent.started`)return;let{data:n}=e;if(n.callId===t.callId&&n.sessionId===t.childSessionId&&n.streamPath===t.childStreamPath&&n.remote!==void 0)return{name:n.name,...n.remote}}function normalizeEveCors(e){if(e===void 0||e===!1)return!1;if(e===!0)return!0;let t={};return e.origin!==void 0&&(t.origin=normalizeEveCorsOrigin(e.origin)),e.methods!==void 0&&(t.methods=e.methods),e.allowedHeaders!==void 0&&(t.allowHeaders=e.allowedHeaders),e.exposedHeaders!==void 0&&(t.exposeHeaders=e.exposedHeaders),e.credentials!==void 0&&(t.credentials=e.credentials),e.maxAge!==void 0&&(t.maxAge=e.maxAge),e.preflightStatus!==void 0&&(t.preflight={statusCode:e.preflightStatus}),t}function normalizeEveCorsOrigin(e){return e===`*`||e===`null`?e:typeof e==`string`?[e]:e}async function resolveOnMessage(e){let t=e.config.onMessage??defaultOnMessage,n;try{let r={caller:e.auth,request:e.request};if(n=await t({eve:e.sessionId===void 0?e.invocation===void 0?r:{...r,invocation:e.invocation}:{...r,sessionId:e.sessionId}},e.message),n==null)throw TypeError(`eveChannel onMessage must return an auth result.`)}catch(t){let n=logError(log,`onMessage handler failed`,t,{sessionId:e.sessionId});return Response.json({error:`onMessage handler failed.`,errorId:n,ok:!1},{status:500})}return{auth:n.auth,context:n.context,title:n.title}}function defaultOnMessage(e){return{auth:defaultEveAuth(e)}}export{findRemoteAgentBinding,healthResponse,normalizeEveCors,resolveOnMessage};

package/dist/src/eve-channel/turn-policy-request.d.ts

@@ -0,0 +1,2 @@
+import type { TurnPolicy } from "#channel/types.js";
+export declare function parseTurnPolicyField(value: unknown): TurnPolicy | Response | undefined;

package/dist/src/eve-channel/turn-policy-request.js

@@ -0,0 +1 @@
+function parseTurnPolicyField(e){if(e!==void 0)return e===`queue`||e===`steer`?e:Response.json({error:`Expected 'turnPolicy' to be either 'queue' or 'steer'.`,ok:!1},{status:400})}export{parseTurnPolicyField};

package/dist/src/eve-channel/types.d.ts

@@ -42,6 +42,10 @@ export type EveChannelCors = boolean | EveChannelCorsOptions;
 export interface EveHandle {
     /** Route-auth result for the request; `onMessage` chooses session auth by returning `{ auth }`. */
     readonly caller: SessionAuthContext | null;
+    /** Replay-stable identity of a trusted remote-subagent create operation. */
+    readonly invocation?: {
+        readonly operationId: string;
+    };
     readonly request: Request;
     /** Existing runtime session id for follow-up requests. */
     readonly sessionId?: string;

package/dist/src/execution/agent-sessions/context.d.ts

@@ -0,0 +1,60 @@
+import type { ChannelInstrumentationProjection, RunSessionLimits, SessionCapabilities, SessionParent } from "#channel/types.js";
+import type { LocalDevRequestProvenance } from "#context/keys.js";
+import type { DynamicSubagentSelections } from "#execution/agent-sessions/target.js";
+import type { PreparedCoordinationDispatch } from "#execution/coordination-dispatch-shared.js";
+import { type DurableCompiledArtifactsSource } from "#runtime/durable-compiled-artifacts-source.js";
+import type { SandboxState } from "#sandbox/state.js";
+import type { ConversationContext } from "#shared/conversation-context.js";
+import type { WorkflowAgentMetadata } from "#tools/workflow-definition.js";
+import { type AgentChildTraceDispatch } from "#tracing/agent-invocation-coordinator.js";
+/**
+ * What a workflow run needs to open `ctx.agent` sessions for its caller,
+ * captured from the calling session for one call: the run's start input
+ * carries it for the call that started the run, and each later call to a
+ * `serve` task carries its own. The run never reads the session again:
+ * opening, sending to, and ending its sessions never pass through the caller.
+ *
+ * It is a session's lineage, bound when the session opens. Auth is not part
+ * of it: each message carries the auth of the call that sends it.
+ */
+export interface AgentSessionContext {
+    /** The agents the call may open, by name, which `ctx.agents` lists. */
+    readonly agents: Readonly<Record<string, WorkflowAgentMetadata>>;
+    readonly bundle: AgentSessionBundle;
+    /** Forwarded unchanged, so a session asks a person only when its caller can. */
+    readonly capabilities?: SessionCapabilities;
+    readonly channelMetadata?: ChannelInstrumentationProjection;
+    readonly conversation?: ConversationContext;
+    /** Dynamic agents the calling turn selected, by node id. */
+    readonly dynamicSelections: DynamicSubagentSelections;
+    /** The token budget each session inherits: its share of the caller's remaining quota. */
+    readonly limits: RunSessionLimits;
+    readonly localDevRequest?: LocalDevRequestProvenance;
+    /** The calling session, turn, and tool call, recorded as each session's lineage. */
+    readonly parent: SessionParent;
+    readonly sandbox: AgentSessionSandbox;
+    readonly trace: AgentChildTraceDispatch;
+}
+/** The compiled agent that owns the tool, which resolves agent names. */
+export interface AgentSessionBundle {
+    readonly nodeId?: string;
+    readonly source: DurableCompiledArtifactsSource;
+}
+/** The caller's sandbox, which agents declared with a parent sandbox share. */
+export interface AgentSessionSandbox {
+    readonly sessionId: string;
+    readonly state?: SandboxState;
+}
+type CallerDispatch = Pick<PreparedCoordinationDispatch<unknown>, "batch" | "bundle" | "capabilities" | "channelMetadata" | "dynamicSubagentSelections" | "inheritedConversation" | "localDevRequest" | "sandboxSessionId" | "serializedContext" | "session" | "workflowAgents">;
+/**
+ * The token budget every session a model step's calls open inherits: the
+ * caller's remaining quota split evenly across the agent tasks the step
+ * starts, local or remote, so those tasks are bounded by the remainder
+ * together. Sessions a workflow tool opens with `ctx.agent` get the same
+ * share without dividing it further. A call to a running task starts none,
+ * so it takes no share.
+ */
+export declare function resolveStepAgentLimits(caller: Pick<PreparedCoordinationDispatch, "plan" | "session">): RunSessionLimits;
+/** Captures the agent session context for one workflow tool call, in the step that admits it. */
+export declare function captureAgentSessionContext(caller: CallerDispatch, callId: string, limits: RunSessionLimits): AgentSessionContext;
+export {};

package/dist/src/execution/agent-sessions/context.js

@@ -0,0 +1 @@
+import{serializeDurableCompiledArtifactsSource}from"#runtime/durable-compiled-artifacts-source.js";import{findTask,readTaskTable}from"#execution/tasks/table.js";import{resolveRemainingSessionTokenLimits}from"#subagents/token-budget.js";import{resolveToolCallAgentTrace}from"#tracing/agent-invocation-coordinator.js";function resolveStepAgentLimits(e){let t=readTaskTable(e.session.state),n=e.plan.filter(({entry:e})=>e.entryPoint===`serve`&&findTask(t,e.taskId)?.kind===`agent`).length;return resolveRemainingSessionTokenLimits(e.session,n)}function captureAgentSessionContext(e,t,n){let{batch:r,session:i}=e;return{agents:e.workflowAgents,bundle:{nodeId:e.bundle.nodeId,source:serializeDurableCompiledArtifactsSource(e.bundle.compiledArtifactsSource)},capabilities:e.capabilities,channelMetadata:e.channelMetadata,conversation:e.inheritedConversation,dynamicSelections:e.dynamicSubagentSelections,limits:n,localDevRequest:e.localDevRequest,parent:{callId:t,rootSessionId:i.rootSessionId??i.sessionId,sessionId:i.sessionId,turn:{id:r.event.turnId,sequence:r.event.sequence}},sandbox:{sessionId:e.sandboxSessionId,state:i.sandboxState},trace:resolveToolCallAgentTrace({callId:t,conversation:e.inheritedConversation,serializedContext:e.serializedContext,sessionId:i.sessionId,turnId:r.event.turnId})}}export{captureAgentSessionContext,resolveStepAgentLimits};

package/dist/src/{subagents/remote-dispatch.d.ts → execution/agent-sessions/remote.d.ts}

@@ -1,5 +1,5 @@
 import { type ResetResponse } from "#protocol/reset-session.js";
-import type { ActivityObserverConfig, CancelTurnResult, SessionAuthContext } from "#channel/types.js";
+import type { CancelTurnResult, SessionAuthContext, SessionCapabilities } from "#channel/types.js";
 import type { ChannelAudience } from "#shared/channel-audience.js";
 import { type SubagentParentContext } from "#subagents/invocation.js";
 import type { HarnessSession } from "#harness/types.js";
@@ -7,6 +7,8 @@ import type { RuntimeRemoteAgentDispatchRequest } from "#shared/action-types.js"
 import type { RuntimeSubagentRegistry } from "#runtime/subagents/registry.js";
 import type { DynamicRemoteAgentConfig } from "#runtime/subagents/dynamic-remote-agent-config.js";
 import type { CompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
+import type { RemoteAgentBinding } from "#eve-channel/support.js";
+import type { InputResponse } from "#shared/input.js";
 import type { ResolvedRuntimeRemoteAgentNode } from "#runtime/types.js";
 import type { JsonObject } from "#shared/json.js";
 type RemoteAgentSessionCoordinates = {
@@ -17,8 +19,8 @@ export declare function startRemoteAgentSession(input: {
     /** The dispatching turn's session principal, forwarded when `remote.forwardPrincipal` is set. */
     readonly auth?: SessionAuthContext | null;
     readonly callbackBaseUrl: string | undefined;
+    readonly capabilities?: SessionCapabilities;
     readonly originAudience?: ChannelAudience;
-    readonly activityObserver?: ActivityObserverConfig;
     /** The root initiator's principal, forwarded alongside {@link auth}. */
     readonly initiatorAuth?: SessionAuthContext | null;
     /**
@@ -31,18 +33,23 @@ export declare function startRemoteAgentSession(input: {
         readonly lineage?: SubagentParentContext["lineage"];
     };
     readonly remote: ResolvedRuntimeRemoteAgentNode;
-    readonly session: HarnessSession;
-    readonly taskId?: string;
+    readonly session: Pick<HarnessSession, "continuationToken">;
 }): Promise<RemoteAgentSessionCoordinates>;
+export declare function respondToRemoteAgentSession(input: {
+    readonly remote: RemoteAgentBinding & {
+        readonly sessionId: string;
+    };
+    readonly headers: Record<string, string>;
+    readonly auth: SessionAuthContext | null | undefined;
+    readonly responses: readonly InputResponse[];
+}): Promise<void>;
 /** Continues one remote-agent session by its immutable session ID. */
 export declare function continueRemoteAgentSession(input: {
-    readonly activityObserver?: ActivityObserverConfig;
     /** The dispatching turn's session principal, forwarded when `remote.forwardPrincipal` is set. */
     readonly auth: SessionAuthContext | null;
-    readonly callback?: {
+    readonly callback: {
         readonly callId: string;
         readonly subagentName: string;
-        readonly taskId?: string;
         readonly token: string;
         readonly url: string;
     };
@@ -51,46 +58,16 @@ export declare function continueRemoteAgentSession(input: {
     readonly remote: ResolvedRuntimeRemoteAgentNode;
     readonly sessionId: string;
 }): Promise<void>;
-/**
- * Failure of a continue-session request, classified at the HTTP boundary.
- * Exported so tests can exercise {@link isRetryableRemoteAgentContinueError}
- * with real instances instead of re-encoding the classification.
- */
-export declare class RemoteAgentContinueRequestError extends Error {
-    readonly deliveryAmbiguous: boolean;
-    readonly retryable: boolean;
-    constructor(message: string, options: {
-        readonly deliveryAmbiguous: boolean;
-        readonly retryable: boolean;
-    });
-}
-/**
- * Returns true when a failed continue request may be retried. Only a
- * session that no longer exists (404 / SESSION_NOT_RESUMABLE) is permanent;
- * transient HTTP and network failures stay retryable so the dispatch step
- * keeps the agent handle and surfaces a retryable error instead of
- * discarding it — the model decides whether to try the same agentId again
- * (the step itself never re-sends: the callee may have accepted a delivery
- * whose response was lost).
- */
-export declare function isRetryableRemoteAgentContinueError(error: unknown): boolean;
-/** Whether the callee may have accepted the continuation before delivery failed. */
-export declare function isAmbiguousRemoteAgentContinueError(error: unknown): boolean;
 export declare function cancelRemoteAgentTurn(input: {
-    readonly headers?: Record<string, string>;
     readonly remote: Pick<ResolvedRuntimeRemoteAgentNode, "auth" | "headers" | "name" | "url">;
     readonly sessionId: string;
-    readonly taskId?: string;
-    readonly tasks?: boolean;
-    readonly turnId?: string;
 }): Promise<CancelTurnResult>;
 /** Retires one exact remote child session through eve's authenticated reset route. */
 export declare function resetRemoteAgentSession(input: {
-    readonly headers?: Record<string, string>;
+    readonly reason: string;
     readonly remote: Pick<ResolvedRuntimeRemoteAgentNode, "auth" | "headers" | "name" | "url">;
     readonly sessionId: string;
 }): Promise<ResetResponse>;
-export declare function isRetryableRemoteAgentCancelError(error: unknown): boolean;
 export declare function resolveRemoteAgentForAction(input: {
     readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
     readonly nodeId: string;
@@ -100,8 +77,8 @@ export declare function resolveRemoteAgentForAction(input: {
 /**
  * Resolves authored outbound headers for a server-authored remote child event.
  *
- * `resolverId` is the key persisted on the `subagent.called` event (see
- * `SubagentCalledStreamEvent`): it identifies the authored credential
+ * `resolverId` is the key persisted on the `agent.started` event (see
+ * `AgentStartedStreamEvent`): it identifies the authored credential
  * functions, never their resolved values. Lookup order mirrors how dispatch
  * chose the key — first as a subagent node id (static remote definition),
  * then as a `credentialsStepId` in the step registry (dynamic remote

package/dist/src/execution/agent-sessions/remote.js

@@ -0,0 +1 @@
+import{z}from"#compiled/zod/index.js";import{decisionToTraceContentCeiling}from"#shared/forwarded-trace-policy.js";import{expectFunction,expectObjectRecord}from"#internal/authored-module.js";import{createEveCallbackRoutePath,createEveSessionCancelRoutePath,createEveSessionResetRoutePath,createEveSessionRoutePath}from"#protocol/routes.js";import{CancelTurnResponseSchema}from"#protocol/cancel-turn.js";import{ResetResponseSchema}from"#protocol/reset-session.js";import{formatTraceparent,writeAgentDispatchTracestate}from"#protocol/traceparent.js";import{writeForwardedAudienceBaggage,writeForwardedParentSessionBaggage}from"#protocol/baggage.js";import{writeConversationBaggage}from"#tracing/conversation-context.js";import{REMOTE_AGENT_PROTOCOL_MISMATCH,REMOTE_AGENT_PROTOCOL_VERSION,formatRemoteAgentProtocolMismatch,readRemoteAgentProtocolVersion}from"#protocol/remote-agent-protocol.js";import{FatalError}from"#compiled/@workflow/core/index.js";import{createWorkflowCallbackUrl}from"#execution/workflow-callback-url.js";import{createRemoteAgentRouteUrl}from"#subagents/remote-route-url.js";import{formatSubagentInput}from"#subagents/invocation.js";const CreateSessionResponseSchema=z.object({ok:z.literal(!0),protocolVersion:z.number().optional(),sessionId:z.string().min(1),status:z.literal(`accepted`)});async function startRemoteAgentSession(e){let t=e.parent?.continuationToken??e.session.continuationToken;if(!t)throw Error(`Cannot dispatch remote agent without a parent continuation token.`);if(!e.callbackBaseUrl)throw Error(`Cannot dispatch remote agent without a callback base URL.`);let n=buildForwardedPrincipalField(e),r={capabilities:e.capabilities??{},callback:{callId:e.action.callId,subagentName:e.action.remoteAgentName,token:t,url:createWorkflowCallbackUrl(e.callbackBaseUrl,createEveCallbackRoutePath(t))},message:formatRemoteAgentCallInputMessage({action:e.action,remote:e.remote}),outputSchema:e.action.input.outputSchema,protocolVersion:REMOTE_AGENT_PROTOCOL_VERSION};n!==void 0&&(r.forwardedPrincipal=n),e.operationId!==void 0&&(r.operationId=e.operationId);let i=await resolveRemoteAgentRequestHeaders(e.remote),a=formatTraceparent(e.parent?.traceContext);a!==void 0&&setHeader(i,`traceparent`,a),setHeader(i,`tracestate`,writeAgentDispatchTracestate(readHeader(i,`tracestate`),e.parent?.traceContext));let o=writeForwardedAudienceBaggage(readHeader(i,`baggage`),buildForwardedTraceAssertion({forwardedPrincipal:n,originAudience:e.originAudience,parentTraceContext:e.parent?.traceContext,traceparent:a})),s=writeConversationBaggage(o,e.parent?.conversationId);setHeader(i,`baggage`,writeForwardedParentSessionBaggage(s,e.parent?.lineage));let c=await fetch(createRemoteAgentSessionUrl(e.remote),{body:JSON.stringify(r),headers:{"content-type":`application/json`,...i},method:`POST`});if(!c.ok)throw await throwIfRemoteAgentProtocolMismatch(c,e.action.remoteAgentName),Error(`Remote agent "${e.action.remoteAgentName}" create-session request failed with HTTP ${c.status}.`);let l;try{l=await c.json()}catch{throw Error(`Remote agent "${e.action.remoteAgentName}" create-session response was not valid JSON.`)}let u=CreateSessionResponseSchema.safeParse(l);if(!u.success)throw Error(`Remote agent "${e.action.remoteAgentName}" create-session response was invalid.`);let d=readRemoteAgentProtocolVersion(u.data.protocolVersion);if(d!==REMOTE_AGENT_PROTOCOL_VERSION)throw new FatalError(formatRemoteAgentProtocolMismatch({name:e.action.remoteAgentName,receiverVersion:d}));return{sessionId:u.data.sessionId}}async function throwIfRemoteAgentProtocolMismatch(e,t){let n;try{n=await e.json()}catch{return}if(typeof n!=`object`||!n||Reflect.get(n,`code`)!==REMOTE_AGENT_PROTOCOL_MISMATCH)return;let r=readRemoteAgentProtocolVersion(Reflect.get(n,`protocolVersion`));throw new FatalError(formatRemoteAgentProtocolMismatch({name:t,receiverVersion:r}))}function buildForwardedTraceAssertion(e){let t=decisionToTraceContentCeiling(e.parentTraceContext?.decision);if(e.forwardedPrincipal!==void 0&&e.parentTraceContext!==void 0&&(e.parentTraceContext.traceFlags&1)==1&&e.traceparent!==void 0&&t!==void 0)return{ceiling:t,originAudience:e.originAudience??`unknown`}}async function respondToRemoteAgentSession(e){let t=await fetch(createRemoteAgentRouteUrl(e.remote.url,createEveSessionRoutePath(e.remote.sessionId)),{body:JSON.stringify({inputResponses:e.responses,...e.remote.forwardPrincipal===!0&&e.auth!=null&&{forwardedPrincipal:{current:e.auth}}}),headers:{"content-type":`application/json`,...e.headers},method:`POST`,redirect:`error`});if(!t.ok)throw Error(`Remote agent "${e.remote.name}" input answer failed with HTTP ${t.status}.`)}async function continueRemoteAgentSession(e){let t=buildForwardedPrincipalField(e),n={callback:e.callback,message:e.message,outputSchema:e.outputSchema};t!==void 0&&(n.forwardedPrincipal=t);let r=await fetch(createRemoteAgentContinueUrl(e.remote,e.sessionId),{body:JSON.stringify(n),headers:{"content-type":`application/json`,...await resolveRemoteAgentRequestHeaders(e.remote)},method:`POST`});if(!r.ok){let n=r.status===400&&t!==void 0?` The receiver may support forwarded principals only on session creation; upgrade it before retrying.`:``;throw Error(`Remote agent "${e.remote.name}" continue-session request failed with HTTP ${r.status}.${n}`)}}function buildForwardedPrincipalField(e){if(e.remote.forwardPrincipal!==!0||e.auth===null||e.auth===void 0)return;let t={current:e.auth};return e.initiatorAuth!==null&&e.initiatorAuth!==void 0&&(t.initiator=e.initiatorAuth),t}async function cancelRemoteAgentTurn(e){let t=await fetch(createRemoteAgentCancelTurnUrl(e.remote,e.sessionId),{headers:await resolveRemoteAgentRequestHeaders(e.remote),method:`POST`});if(!t.ok)throw Error(`Remote agent "${e.remote.name}" cancel-turn request failed with HTTP ${t.status}.`);let n;try{n=await t.json()}catch{throw Error(`Remote agent "${e.remote.name}" cancel-turn response was not valid JSON.`)}let r=CancelTurnResponseSchema.safeParse(n);if(!r.success||r.data.status===`accepted`&&r.data.sessionId!==e.sessionId)throw Error(`Remote agent "${e.remote.name}" cancel-turn response was invalid.`);return r.data.status===`accepted`?{sessionId:r.data.sessionId,status:`accepted`}:{status:`no_active_turn`}}function readHeader(e,t){let n=Object.keys(e).find(e=>e.toLowerCase()===t);return n===void 0?void 0:e[n]}function setHeader(e,t,n){for(let n of Object.keys(e))n.toLowerCase()===t&&delete e[n];n!==void 0&&(e[t]=n)}async function resetRemoteAgentSession(e){let t=await resolveRemoteAgentRequestHeaders(e.remote),n=await fetch(createRemoteAgentRouteUrl(e.remote.url,createEveSessionResetRoutePath(e.sessionId)),{body:JSON.stringify({reason:e.reason}),headers:{"content-type":`application/json`,...t},method:`POST`});if(!n.ok)throw Error(`Remote agent "${e.remote.name}" reset-session request failed with HTTP ${n.status}.`);let r=ResetResponseSchema.safeParse(await n.json());if(!r.success||r.data.status===`reset`&&r.data.previousSessionId!==e.sessionId)throw Error(`Remote agent "${e.remote.name}" reset-session response was invalid.`);return r.data}function resolveRemoteAgentForAction(e){let t=e.registry.get(e.nodeId)?.definition;if(e.dynamicRemoteAgent!==void 0){if(t===void 0)throw new FatalError(`Missing remote agent "${e.remoteAgentName}" in runtime registry.`);let n=resolveDynamicRemoteAgentCredentials(e.dynamicRemoteAgent),r=e.dynamicRemoteAgent,i={description:r.description,kind:`remote`,logicalPath:t.logicalPath,name:e.remoteAgentName,nodeId:e.nodeId,path:r.path,sourceId:t.sourceId,sourceKind:`module`,url:r.url};return r.forwardPrincipal!==void 0&&(i.forwardPrincipal=r.forwardPrincipal),n.auth!==void 0&&(i.auth=n.auth),n.headers!==void 0&&(i.headers=n.headers),i}if(t?.kind!==`remote`)throw new FatalError(`Missing remote agent "${e.remoteAgentName}" in runtime registry.`);return t}async function resolveRemoteAgentStreamHeaders(e){if(e.resolverId===void 0)return{};let t=new Set([e.bundle.graph.root,...e.bundle.graph.nodesByNodeId.values()]);for(let n of t){let t=n.subagentRegistry.subagentsByNodeId.get(e.resolverId)?.definition;if(t!==void 0){if(t.kind!==`remote`||t.name!==e.name||t.url!==e.url)throw Error(`Remote child stream resolver does not match the authored remote agent.`);return await resolveRemoteAgentRequestHeaders(t)}}return await resolveRemoteAgentRequestHeaders(resolveDynamicRemoteAgentCredentials({credentialsStepId:e.resolverId,description:``,path:``,url:e.url}))}function resolveDynamicRemoteAgentCredentials(e){if(e.credentialsStepId===void 0)return{};let t=getStepRegistry().get(e.credentialsStepId);if(t===void 0)throw Error(`Dynamic remote subagent credentials function "${e.credentialsStepId}" is not registered.`);let n=expectObjectRecord(t(),`Dynamic remote subagent credentials are invalid.`),r={};return n.auth!==void 0&&(r.auth=expectFunction(n.auth,`Dynamic remote subagent auth is invalid.`)),n.headers!==void 0&&(r.headers=resolveDynamicRemoteAgentHeaders(n.headers)),r}function resolveDynamicRemoteAgentHeaders(e){if(typeof e==`function`)return e;let t=expectObjectRecord(e,`Dynamic remote subagent headers are invalid.`);for(let e of Object.values(t))if(typeof e!=`string`)throw Error(`Dynamic remote subagent headers are invalid.`);return t}function getStepRegistry(){let e=Symbol.for(`@workflow/core//registeredSteps`),t=globalThis,n=t[e];return n===void 0&&(n=new Map,t[e]=n),n}function createRemoteAgentSessionUrl(e){return createRemoteAgentRouteUrl(e.url,e.path)}function createRemoteAgentCancelTurnUrl(e,t){return createRemoteAgentRouteUrl(e.url,createEveSessionCancelRoutePath(t))}function createRemoteAgentContinueUrl(e,t){return createRemoteAgentRouteUrl(e.url,createEveSessionRoutePath(t))}async function resolveRemoteAgentRequestHeaders(e){let t={};return e.headers!==void 0&&Object.assign(t,typeof e.headers==`function`?await e.headers():e.headers),e.auth!==void 0&&Object.assign(t,(await e.auth()).headers),t}function formatRemoteAgentCallInputMessage(e){let t=typeof e.action.input.message==`string`?e.action.input.message:``;return formatSubagentInput({description:e.remote.description,message:t,name:e.action.remoteAgentName,type:`remote`}).message}export{cancelRemoteAgentTurn,continueRemoteAgentSession,resetRemoteAgentSession,resolveRemoteAgentForAction,resolveRemoteAgentStreamHeaders,respondToRemoteAgentSession,startRemoteAgentSession};

package/dist/src/execution/agent-sessions/requests.d.ts

@@ -0,0 +1,20 @@
+import type { SubagentAuthorizationEventHookPayload, SubagentInputRequestHookPayload } from "#channel/types.js";
+import type { WorkflowToolRunRef } from "#execution/tools/workflow/messages.js";
+import type { WorkflowToolRunInbox } from "#execution/tools/workflow/owner.js";
+import type { RemoteAgentBinding } from "#eve-channel/support.js";
+/** A child's question or sign-in, which only a person at the root can answer. */
+export type AgentSessionRequest = SubagentAuthorizationEventHookPayload | SubagentInputRequestHookPayload;
+/**
+ * Sends a child's question or sign-in to the session that owns the run, which
+ * proxies it up the owner chain to the root. Answers route back down to the
+ * child by request id.
+ */
+export declare function forwardAgentSessionRequest(input: {
+    readonly from: WorkflowToolRunRef;
+    readonly owner: WorkflowToolRunInbox;
+    readonly replyTo: string;
+    readonly request: AgentSessionRequest;
+    readonly remote?: RemoteAgentBinding & {
+        readonly sessionId: string;
+    };
+}): Promise<void>;

package/dist/src/execution/agent-sessions/requests.js

@@ -0,0 +1 @@
+async function forwardAgentSessionRequest(e){let{from:t,request:n}=e;if(n.kind===`subagent-authorization-event`){await e.owner.send({from:t,kind:`request`,replyTo:e.replyTo,request:{event:n,kind:`authorization-request`}});return}await e.owner.send({from:t,inputSource:n.inputSource,remote:e.remote,kind:`request`,replyTo:n.childContinuationToken,childSessionInbox:n.childSessionInbox?.sessionId===n.childSessionId?n.childSessionInbox:void 0,request:{kind:`input-batch`,requests:n.event.requests},requestCoordinates:{sequence:n.event.sequence,stepIndex:n.event.stepIndex,turnId:n.event.turnId}})}export{forwardAgentSessionRequest};

package/dist/src/execution/agent-sessions/session.d.ts

@@ -0,0 +1,12 @@
+import type { RunUsageTally } from "#execution/agent-sessions/usage.js";
+import type { WorkflowToolRunContext } from "#execution/tools/workflow/ask.js";
+import type { AgentSession } from "#tools/workflow-definition.js";
+/**
+ * Opens `ctx.agent` sessions for a workflow run. A handle's position in the
+ * run names its session, so replay reaches the same one, and `close` ends
+ * every session the run opened, cancelling any turn still running.
+ */
+export declare function createAgentSessions(run: WorkflowToolRunContext, usage: RunUsageTally): {
+    readonly close: () => Promise<void>;
+    readonly open: (name: string) => AgentSession;
+};

package/dist/src/execution/agent-sessions/session.js

@@ -0,0 +1 @@
+import{toErrorMessage}from"#shared/errors.js";import{createHook}from"#compiled/@workflow/core/index.js";import{normalizeRequestedOutputSchema}from"#subagents/invocation.js";import{forwardAgentSessionRequest}from"#execution/agent-sessions/requests.js";import{cancelAgentSessionTurnStep,endAgentSessionsStep,openAgentSessionStep,sendAgentSessionMessageStep}from"#execution/agent-sessions/steps.js";import{disposeHook}from"#execution/hook-ownership.js";import{serializeOutputSchema}from"#tools/schema-emission.js";function createAgentSessions(e,t){let n=[],r=0;return{open:i=>{if(typeof i!=`string`||i.trim()===``)throw TypeError(`ctx.agent() requires a non-empty agent name.`);let a=`${e.from.runId}:${String(r)}`;return r+=1,new RunAgentSession({key:a,name:i,run:e,sessions:n,usage:t})},close:async()=>{n.length!==0&&await endAgentSessionsStep({sessions:n})}}}var RunAgentSession=class{#e;#t;#n;#r;#i;#a;#o=[];constructor(e){this.#e=e.key,this.#t=e.name,this.#n=e.run,this.#r=e.sessions,this.#i=e.usage}async send(e,t={}){if(typeof e!=`string`||e.trim()===``)throw TypeError(`ctx.agent("${this.#t}").send() requires a non-empty message.`);let n=normalizeRequestedOutputSchema(serializeOutputSchema(t.outputSchema)),r=this.#s(n!==void 0);try{await this.#u({auth:this.#n.auth,message:e,outputSchema:n,replyTo:r.hook.token})}catch(e){throw this.#o.splice(this.#o.indexOf(r),1),await releaseHook(r.hook),e}return t.signal!==void 0&&this.#f(r,t.signal),{result:()=>r.ended.then(unwrapTurnEnd)}}#s(e){let t=createHook(),settle=()=>{},n={ended:new Promise(e=>{settle=e}),hook:t,settle};return this.#o.push(n),this.#c(t,e).then(e=>this.#l(n,e)),n}async#c(e,t){try{for await(let n of e){if(n.kind!==`runtime-action-result`){await forwardAgentSessionRequest({from:this.#n.from,owner:this.#n.owner,replyTo:e.token,request:n,remote:this.#a===void 0?void 0:await this.#a.then(({address:e})=>e.kind===`remote`?{forwardPrincipal:e.forwardPrincipal,name:e.name,resolverId:e.resolverId,url:e.url,sessionId:e.sessionId}:void 0)});continue}let r=n.results.find(e=>e.kind===`subagent-result`);if(r!==void 0)return r.origin===`child`&&this.#i.record(r.outcome.usageDelta),{kind:`ended`,result:toAgentMessageResult(r,t)}}return{error:Error(`Agent "${this.#t}" stopped reporting before its turn ended.`),kind:`failed`}}catch(e){return{error:e,kind:`failed`}}}async#l(e,t){let n=this.#o.indexOf(e);if(!(n<0))for(let e of this.#o.splice(0,n+1))e.settle(t),await releaseHook(e.hook)}async#u(e){if(this.#a===void 0){this.#a=this.#d(e),await this.#a;return}let t=await this.#a;await sendAgentSessionMessageStep({...e,...t})}async#d(e){let{agentContext:t,from:n}=this.#n;try{let r=await openAgentSessionStep({...e,context:t,key:this.#e,name:this.#t}),i={address:r,context:t,key:this.#e};return this.#r.push(i),await this.#n.owner.send({from:n,kind:`agent-started`,session:r}),i}catch(e){throw this.#a=void 0,e}}#f(e,t){let cancel=()=>{this.#o.includes(e)&&this.#a!==void 0&&this.#a.then(e=>cancelAgentSessionTurnStep(e)).catch(()=>{})};if(t.aborted){cancel();return}t.addEventListener(`abort`,cancel,{once:!0})}};async function releaseHook(e){try{await disposeHook(e)}catch{}}function unwrapTurnEnd(e){if(e.kind===`failed`)throw e.error;return e.result}const NO_REPLY={data:void 0,message:void 0};function failedTurn(e){return{...NO_REPLY,error:{message:toErrorMessage(e)},status:`failed`}}function toAgentMessageResult(e,t){if(e.origin!==`child`)return failedTurn(e.output);let{outcome:n}=e;switch(n.result.kind){case`failed`:return failedTurn(n.result.error);case`cancelled`:return{...NO_REPLY,status:`waiting`};case`succeeded`:{let{output:e}=n.result,r=n.kind===`terminal`?`completed`:`waiting`;return t?{data:e,message:void 0,status:r}:{data:void 0,message:typeof e==`string`?e:void 0,status:r}}}}export{createAgentSessions};

package/dist/src/execution/agent-sessions/steps.d.ts

@@ -0,0 +1,59 @@
+import type { SessionAuth } from "#context/session-context.js";
+import type { AgentSessionContext } from "#execution/agent-sessions/context.js";
+import type { JsonObject } from "#shared/json.js";
+/** Where a session a run opened lives, for its later sends, cancels, and end. */
+export type AgentSessionAddress = {
+    readonly kind: "local";
+    readonly name: string;
+    readonly nodeId: string;
+    readonly sessionId: string;
+} | {
+    readonly callbackBaseUrl: string;
+    readonly kind: "remote";
+    readonly forwardPrincipal?: boolean;
+    readonly name: string;
+    readonly nodeId: string;
+    /** Keys the authored credential functions, as on `agent.started`. */
+    readonly resolverId?: string;
+    readonly sessionId: string;
+    readonly url: string;
+};
+/** A session a run opened, with the context of the call that opened it: its lineage. */
+export interface OpenedAgentSession {
+    readonly address: AgentSessionAddress;
+    readonly context: AgentSessionContext;
+    /** Names the session within its run, as when it opened. */
+    readonly key: string;
+}
+/**
+ * One message to a session, as the call that sends it: the session runs the
+ * message with that call's auth. Its turn's result and questions arrive on
+ * `replyTo`.
+ */
+export interface AgentSessionMessage {
+    readonly auth: SessionAuth;
+    readonly message: string;
+    readonly outputSchema?: JsonObject;
+    readonly replyTo: string;
+}
+/**
+ * Opens a run's session with its first message, as a child of the call whose
+ * `context` it binds. `key` names the handle within the run, so a retried step
+ * reaches the same session instead of a second one.
+ */
+export declare function openAgentSessionStep(input: AgentSessionMessage & {
+    readonly context: AgentSessionContext;
+    readonly key: string;
+    readonly name: string;
+}): Promise<AgentSessionAddress>;
+/**
+ * Sends a later message; it joins the session's running turn or starts the
+ * next. It keeps the session's lineage and carries its own auth.
+ */
+export declare function sendAgentSessionMessageStep(input: AgentSessionMessage & OpenedAgentSession): Promise<void>;
+/** Cancels a session's running turn; the turn still reports, as cancelled. */
+export declare function cancelAgentSessionTurnStep(input: OpenedAgentSession): Promise<void>;
+/** Ends a run's sessions when the run finishes, cancelling any turn still running. */
+export declare function endAgentSessionsStep(input: {
+    readonly sessions: readonly OpenedAgentSession[];
+}): Promise<void>;

package/dist/src/execution/agent-sessions/steps.js

@@ -0,0 +1 @@
+import{createLogger,logError}from"#internal/logging.js";import{sessionInboxHookToken}from"#execution/session-inbox/address.js";import{ContextContainer,contextStorage}from"#context/container.js";import{createEveCallbackRoutePath}from"#protocol/routes.js";import{createWorkflowRuntime,dispatchWorkflowSessionCommand,requestWorkflowTurnCancellation,waitForCommandHookOwner}from"#execution/workflow-runtime.js";import{resolveDurableCompiledArtifactsSource}from"#runtime/durable-compiled-artifacts-source.js";import{getWorkflowMetadata}from"#compiled/@workflow/core/index.js";import{createWorkflowCallbackUrl,resolveWorkflowCallbackBaseUrl}from"#execution/workflow-callback-url.js";import{resolveAgentAction,resolveAgentStartTarget}from"#execution/agent-sessions/target.js";import{getCompiledRuntimeAgentBundle}from"#runtime/sessions/compiled-agent-cache.js";import{cancelRemoteAgentTurn,continueRemoteAgentSession,resetRemoteAgentSession,resolveRemoteAgentForAction,startRemoteAgentSession}from"#execution/agent-sessions/remote.js";import{buildSubagentRunInput}from"#subagents/tool.js";import{resolveConversationId}from"#shared/conversation-identity.js";const log=createLogger(`execution.agent-sessions`),RUN_FINISHED_REASON=`The workflow run that opened this session finished.`;async function openAgentSessionStep(e){"use step";let{context:t}=e,n=await loadAgentSessionBundle(t),r=resolveAgentAction({bundle:n,callId:t.parent.callId,dynamicSelections:t.dynamicSelections,input:{message:e.message,outputSchema:e.outputSchema,target:e.name}}),i=resolveAgentStartTarget({action:r,bundle:n,dynamicSelections:t.dynamicSelections,isRootSession:t.parent.rootSessionId===t.parent.sessionId}),a={auth:e.auth,bundle:n,context:t,key:e.key,replyTo:e.replyTo};return i.kind===`remote`?await startRemoteSession({...a,target:i}):await startLocalSession({...a,target:i})}async function sendAgentSessionMessageStep(e){"use step";let{address:t,context:n}=e;if(t.kind===`remote`){let r=await resolveSessionRemote(n,t);await continueRemoteAgentSession({auth:e.auth.current,callback:{callId:n.parent.callId,subagentName:t.name,token:e.replyTo,url:createWorkflowCallbackUrl(t.callbackBaseUrl,createEveCallbackRoutePath(e.replyTo))},message:e.message,outputSchema:e.outputSchema,remote:r,sessionId:t.sessionId});return}if((await dispatchWorkflowSessionCommand({command:{auth:e.auth.current,caller:{callId:n.parent.callId,replyTo:{kind:`hook`,token:e.replyTo},subagentName:t.name},kind:`send`,payload:{message:e.message,outputSchema:e.outputSchema}},sessionId:t.sessionId})).status!==`accepted`)throw Error(`Agent "${t.name}" can no longer receive messages; its session ended.`)}async function cancelAgentSessionTurnStep(e){"use step";let{address:t}=e;try{if(t.kind===`remote`){let n=await resolveSessionRemote(e.context,t);await cancelRemoteAgentTurn({remote:n,sessionId:t.sessionId});return}await requestWorkflowTurnCancellation({sessionId:t.sessionId})}catch(e){logError(log,`failed to cancel an agent session turn`,e,{name:t.name,sessionId:t.sessionId})}}async function endAgentSessionsStep(e){"use step";await Promise.all(e.sessions.map(endAgentSession))}async function endAgentSession({address:e,context:t}){try{if(e.kind===`remote`){let n=await resolveSessionRemote(t,e);await resetRemoteAgentSession({reason:RUN_FINISHED_REASON,remote:n,sessionId:e.sessionId});return}await dispatchWorkflowSessionCommand({command:{kind:`reset`,reason:RUN_FINISHED_REASON},sessionId:e.sessionId})}catch(t){logError(log,`failed to end an agent session`,t,{name:e.name,sessionId:e.sessionId})}}async function startLocalSession(e){let{auth:t,bundle:n,context:r,target:i}=e,{action:a}=i,{childContinuationToken:o,runInput:s}=buildSubagentRunInput({action:a,auth:t.current,capabilities:r.capabilities,channelMetadata:r.channelMetadata,continuationKey:e.key,graph:n.graph,inheritedConversation:r.conversation,initiatorAuth:t.initiator,limits:r.limits,parent:createParentContext(r,e.replyTo),sandboxSessionId:r.sandbox.sessionId,selfAgent:i.source.type===`runtime`,session:{continuationToken:e.replyTo,sandboxState:r.sandbox.state,sessionId:r.parent.sessionId},source:i.source}),c=createWorkflowRuntime({compiledArtifactsSource:n.compiledArtifactsSource,dynamicSubagentAgentConfig:i.dynamicSubagentAgentConfig,nodeId:a.nodeId});await contextStorage.run(new ContextContainer({localDevRequest:r.localDevRequest}),()=>c.createSession(s));let l=await waitForCommandHookOwner(sessionInboxHookToken(o));return{kind:`local`,name:a.name,nodeId:a.nodeId,sessionId:l.runId}}async function startRemoteSession(e){let{auth:t,bundle:n,context:r,target:i}=e,{action:a}=i,o=resolveRemoteAgentForAction({dynamicRemoteAgent:i.dynamicRemoteAgent,nodeId:a.nodeId,registry:n.subagentRegistry.subagentsByNodeId,remoteAgentName:a.remoteAgentName}),s=resolveWorkflowCallbackBaseUrl(getWorkflowMetadata().url),c=await startRemoteAgentSession({action:a,auth:t.current,callbackBaseUrl:s,capabilities:r.capabilities,initiatorAuth:t.initiator,operationId:`agent-session:${e.key}`,originAudience:r.trace.originAudience,parent:createParentContext(r,e.replyTo),remote:o,session:{continuationToken:e.replyTo}});return{callbackBaseUrl:s,kind:`remote`,forwardPrincipal:o.forwardPrincipal,name:a.remoteAgentName,nodeId:a.nodeId,resolverId:i.dynamicRemoteAgent?.credentialsStepId??a.nodeId,sessionId:c.sessionId,url:o.url}}function createParentContext(e,t){return{continuationToken:t,conversationId:e.trace.conversationId??resolveConversationId(e.parent.rootSessionId),lineage:e.parent,originAudience:e.trace.originAudience,traceContext:e.trace.parentTraceContext}}async function resolveSessionRemote(e,t){let n=await loadAgentSessionBundle(e),r=e.dynamicSelections[t.nodeId];return{...resolveRemoteAgentForAction({dynamicRemoteAgent:r?.kind===`remote`?r.remoteAgent:void 0,nodeId:t.nodeId,registry:n.subagentRegistry.subagentsByNodeId,remoteAgentName:t.name}),url:t.url}}async function loadAgentSessionBundle(e){return await getCompiledRuntimeAgentBundle({compiledArtifactsSource:resolveDurableCompiledArtifactsSource(e.bundle.source),nodeId:e.bundle.nodeId})}export{cancelAgentSessionTurnStep,endAgentSessionsStep,openAgentSessionStep,sendAgentSessionMessageStep};

package/dist/src/execution/agent-sessions/target.d.ts

@@ -0,0 +1,45 @@
+import type { DurableDynamicSubagentSelection } from "#context/keys.js";
+import type { CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
+import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
+import type { DynamicRemoteAgentConfig } from "#runtime/subagents/dynamic-remote-agent-config.js";
+import type { RuntimeAgentDispatchRequest, RuntimeRemoteAgentDispatchRequest, RuntimeSubagentDispatchRequest } from "#shared/action-types.js";
+import type { JsonObject } from "#shared/json.js";
+import type { SubagentInputSource } from "#subagents/tool.js";
+export type DynamicSubagentSelections = Readonly<Record<string, DurableDynamicSubagentSelection>>;
+/** One message to an agent, addressed by its invocation name. */
+export interface AgentActionInput {
+    readonly message: string;
+    readonly outputSchema?: JsonObject;
+    readonly target: string;
+}
+/** Where a new session with an agent starts: in this deployment, or at a remote agent. */
+export type SubagentStartTarget = {
+    readonly kind: "local";
+    readonly action: RuntimeSubagentDispatchRequest;
+    readonly dynamicSubagentAgentConfig?: DynamicSubagentAgentConfig;
+    readonly source: SubagentInputSource;
+} | {
+    readonly kind: "remote";
+    readonly action: RuntimeRemoteAgentDispatchRequest;
+    readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
+};
+/**
+ * Resolves an agent name against the calling agent's registry, its dynamic
+ * selections, and the built-in root copy, as a dispatch request.
+ */
+export declare function resolveAgentAction(input: {
+    readonly bundle: CompiledBundle;
+    readonly callId: string;
+    readonly dynamicSelections: DynamicSubagentSelections;
+    readonly input: AgentActionInput;
+}): RuntimeAgentDispatchRequest;
+/**
+ * Plans a fresh child for a dispatch request. A dynamic agent whose selection
+ * changed and a root copy outside the root session can't start.
+ */
+export declare function resolveAgentStartTarget(input: {
+    readonly action: RuntimeAgentDispatchRequest;
+    readonly bundle: CompiledBundle;
+    readonly dynamicSelections: DynamicSubagentSelections;
+    readonly isRootSession: boolean;
+}): SubagentStartTarget;

package/dist/src/execution/agent-sessions/target.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{AGENT_TOOL_DESCRIPTION,AGENT_TOOL_NAME}from"#tools/framework/agent-contract.js";import{FatalError}from"#compiled/@workflow/core/index.js";import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";const log=createLogger(`execution.agent-target`);function resolveAgentAction(e){let t=findAgentDefinition(e.bundle,e.dynamicSelections,e.input.target);if(t===void 0)throw new FatalError(`Agent target "${e.input.target}" is not available to this agent.`);let n={message:e.input.message};e.input.outputSchema!==void 0&&(n.outputSchema=e.input.outputSchema);let r={callId:e.callId,description:t.description??``,input:n,name:t.name,nodeId:t.nodeId};return t.kind===`remote`?{...r,kind:`remote-agent-call`,remoteAgentName:t.name}:{...r,kind:`subagent-call`,subagentName:t.name}}function findAgentDefinition(e,t,n){let r=e.subagentRegistry.subagentsByName.get(n);if(r!==void 0)return r.definition;let i=Object.values(t).find(e=>e!==null&&e.prepared.name===n);if(i!=null)return i.prepared;if(n===AGENT_TOOL_NAME&&e.nodeId===void 0)return{description:AGENT_TOOL_DESCRIPTION,kind:`subagent`,name:AGENT_TOOL_NAME,nodeId:ROOT_RUNTIME_AGENT_NODE_ID}}function resolveAgentStartTarget(e){let{action:t}=e,n=e.bundle.subagentRegistry.subagentsByNodeId,r=e.bundle.subagentRegistry.dynamicNodeIds?.has(t.nodeId)===!0,i=r?e.dynamicSelections[t.nodeId]??void 0:void 0;if(r&&(i===void 0||t.kind===`subagent-call`&&i.kind!==`subagent`||t.kind===`remote-agent-call`&&i.kind!==`remote`))throw log.warn(`dynamic subagent call blocked after availability changed`,{callId:t.callId,nodeId:t.nodeId,subagentName:t.name}),new FatalError(`Subagent "${t.name}" is not available in the current session context.`);if(isRecursiveAgentAction(t,n)&&!e.isRootSession)throw log.warn(`recursive agent call blocked outside the root session`,{callId:t.callId,nodeId:t.nodeId,subagentName:t.subagentName}),new FatalError(`The built-in "agent" tool is only available to the root session.`);if(t.kind===`remote-agent-call`)return{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{action:t,dynamicSubagentAgentConfig:a,kind:`local`,source:s===void 0?{type:`runtime`}:{description:s,type:`local`}}}function isRecursiveAgentAction(e,t){return e.kind===`subagent-call`&&e.subagentName===AGENT_TOOL_NAME&&!t.has(e.nodeId)}export{resolveAgentAction,resolveAgentStartTarget};

package/dist/src/execution/agent-sessions/usage.d.ts

@@ -0,0 +1,18 @@
+import type { SessionStateMap } from "#harness/types.js";
+import type { TokenUsage } from "#shared/token-usage.js";
+/** What a run's `ctx.agent` sessions have spent, turn by turn. */
+export interface RunUsageTally {
+    /** Adds one ended turn's usage. */
+    record(turnUsage: TokenUsage): void;
+    /** The running total, or `undefined` before any turn ended. */
+    total(): TokenUsage | undefined;
+}
+/** `onRecord` runs after each recorded turn, so the run can send a total no reply will carry. */
+export declare function createRunUsageTally(onRecord?: () => void): RunUsageTally;
+/**
+ * Adds a run's delegated spend to the session's totals: its running `total`,
+ * less the part of it `counted` earlier.
+ */
+export declare function countRunUsage<T extends {
+    readonly state?: SessionStateMap;
+}>(session: T, total: TokenUsage, counted?: TokenUsage): T;

package/dist/src/execution/agent-sessions/usage.js

@@ -0,0 +1 @@
+import{accumulateSessionUsage,getTurnUsageState,setTurnUsageState,toUsage}from"#harness/turn-tag-state.js";function createRunUsageTally(e){let t;return{record(n){t=accumulateSessionUsage({previous:t,usage:n}),e?.()},total(){return t===void 0?void 0:toUsage(t.session)}}}function countRunUsage(e,t,n){return setTurnUsageState(e,accumulateSessionUsage({previous:getTurnUsageState(e.state),usage:usageSince(t,n)}))}function usageSince(e,t){return t===void 0?e:{cacheReadTokens:e.cacheReadTokens-t.cacheReadTokens,cacheWriteTokens:e.cacheWriteTokens-t.cacheWriteTokens,costUsd:e.costUsd===void 0?void 0:e.costUsd-(t.costUsd??0),inputTokens:e.inputTokens-t.inputTokens,outputTokens:e.outputTokens-t.outputTokens}}export{countRunUsage,createRunUsageTally};

package/dist/src/execution/authorization-callback-match.d.ts

@@ -1,9 +1,7 @@
 import type { DeliverPayload } from "#channel/types.js";
-import type { AuthorizationResult, PendingAuthorizationState } from "#harness/authorization.js";
-import type { ConnectionAuthorizationChallenge } from "#connections/errors.js";
+import type { AuthorizationChallenge, AuthorizationResult, PendingAuthorizationState } from "#harness/authorization.js";
 export interface MatchedAuthorizationCallback {
-    readonly authorization: ConnectionAuthorizationChallenge;
-    readonly candidateId?: string;
+    readonly challenge: AuthorizationChallenge;
     readonly result: {
         readonly name: string;
         readonly attemptId: string;

package/dist/src/execution/authorization-callback-match.js

@@ -1 +1 @@
-function matchAuthorizationCallbacks(e,t){let n=[],r=[],i=new Set;for(let a of t){let t=a.authorizationCallback;if(t===void 0){r.push(a);continue}let o=e.challenges.find(e=>e.name===t.connectionName&&typeof t.attemptId==`string`&&e.attemptId===t.attemptId),s=o?.attemptId;o===void 0||s===void 0||o.principal===void 0||i.has(s)||(i.add(s),n.push({authorization:o.challenge,candidateId:o.candidateId,result:{attemptId:s,callback:t.callback,hookUrl:o.hookUrl,instanceId:o.instanceId,name:o.name,principal:o.principal,resume:o.resume}}))}return{matches:n,remainingPayloads:r}}export{matchAuthorizationCallbacks};
+function matchAuthorizationCallbacks(e,t){let n=[],r=[],i=new Set;for(let a of t){let t=a.authorizationCallback;if(t===void 0){r.push(a);continue}let o=e.challenges.find(e=>e.name===t.connectionName&&typeof t.attemptId==`string`&&e.attemptId===t.attemptId),s=o?.attemptId;o===void 0||s===void 0||o.principal===void 0||i.has(s)||(i.add(s),n.push({challenge:o,result:{attemptId:s,callback:t.callback,hookUrl:o.hookUrl,instanceId:o.instanceId,name:o.name,principal:o.principal,resume:o.resume}}))}return{matches:n,remainingPayloads:r}}export{matchAuthorizationCallbacks};

package/dist/src/execution/cancel-descendant-turns-step.d.ts

@@ -1,9 +1,5 @@
 import { type DurableSessionState } from "#execution/durable-session-store.js";
-/**
- * Cancels every running delegated child recorded in the agent handle store
- * and every workflow tool run the turn is waiting on.
- */
+/** Cancels every workflow tool run the turn is waiting on. */
 export declare function cancelDescendantTurnsStep(input: {
-    readonly serializedContext: Record<string, unknown>;
     readonly sessionState: DurableSessionState;
 }): Promise<void>;

package/dist/src/execution/cancel-descendant-turns-step.js

@@ -1 +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{getPendingCoordinationBatch}from"#harness/coordination.js";import{deserializeContext}from"#context/serialize.js";import{readDurableSession}from"#execution/durable-session-store.js";import{cancelRemoteAgentTurn,isRetryableRemoteAgentCancelError,resolveRemoteAgentForAction}from"#subagents/remote-dispatch.js";import{cancelWorkflowToolRun}from"#execution/tools/workflow/cancel.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{getAgentHandleStore}from"#subagents/handles/store.js";import{getDynamicSubagentSelection}from"#context/dynamic-subagent-lifecycle.js";const log=createLogger(`execution.cancel-descendant-turns`);async function cancelDescendantTurnsStep(e){"use step";let t,n;try{let r=readDurableSession(e.sessionState);n=getBlockingWorkflowToolRuns(r.state,getPendingCoordinationBatch(r.state)?.event.turnId??e.sessionState.emissionState.turnId);let i=new Set(n.map(e=>e.address.runId));t=(getAgentHandleStore(r.state)?.handles??[]).filter(e=>e.phase===`running`||e.phase===`claimed`&&i.has(e.ownerId))}catch(t){logError(log,`failed to read pending descendants during cancellation`,t,{sessionId:e.sessionState.sessionId});return}let r,getRemoteContext=()=>r??=deserializeContext(e.serializedContext).then(e=>({ctx:e,registry:e.require(BundleKey).subagentRegistry.subagentsByNodeId}));await Promise.all([...n.map(e=>cancelWorkflowToolRun(e.address,`The turn that called the tool was cancelled.`)),...t.map(e=>e.address.kind===`agent/remote`?cancelRemoteDescendant({handle:e,remoteContext:getRemoteContext()}):cancelLocalDescendant({handle:e}))])}async function cancelLocalDescendant(e){let{handle:t}=e;try{let e=await requestCancellationWithRetry({request:()=>requestWorkflowTurnCancellation({sessionId:t.address.sessionId}),shouldRetryError:()=>!1});e.status!==`accepted`&&log.warn(`descendant cancel was never accepted; the child may run to completion`,{callId:readHandleCallId(t),childSessionId:t.address.sessionId,finalStatus:e.status,subagentName:t.identity.name})}catch(e){logError(log,`failed to cancel local descendant turn`,e,{callId:readHandleCallId(t),childSessionId:t.address.sessionId,subagentName:t.identity.name})}}async function cancelRemoteDescendant(e){let{handle:t}=e;if(t.address.kind!==`agent/remote`)return;let n=t.address.url;try{let{ctx:r,registry:i}=await e.remoteContext,a=getDynamicSubagentSelection(r,t.identity.nodeId),o={...await resolveRemoteAgentForAction({dynamicRemoteAgent:a?.kind===`remote`?a.remoteAgent:void 0,nodeId:t.identity.nodeId,remoteAgentName:t.identity.name,registry:i}),url:n},s=await requestCancellationWithRetry({request:()=>cancelRemoteAgentTurn({remote:o,sessionId:t.address.sessionId}),shouldRetryError:isRetryableRemoteAgentCancelError});s.status!==`accepted`&&log.warn(`remote descendant cancel was never accepted; the child may run to completion`,{callId:readHandleCallId(t),childSessionId:t.address.sessionId,finalStatus:s.status,remoteAgentName:t.identity.name})}catch(e){logError(log,`failed to cancel remote descendant turn`,e,{callId:readHandleCallId(t),childSessionId:t.address.sessionId,remoteAgentName:t.identity.name})}}function readHandleCallId(e){return e.phase===`running`?e.operation.callId:e.callId}async function requestCancellationWithRetry(e){let t=250,n={status:`no_active_turn`};for(let r=1;r<=8;r+=1){try{if(n=await e.request(),n.status===`accepted`||r===8)return n}catch(t){if(!e.shouldRetryError(t)||r===8)throw t}await new Promise(e=>setTimeout(e,t)),t=Math.min(t*2,1500)}return n}export{cancelDescendantTurnsStep};
+import{createLogger,logError}from"#internal/logging.js";import{getPendingCoordinationBatch}from"#harness/coordination.js";import{readDurableSession}from"#execution/durable-session-store.js";import{cancelWorkflowToolRun}from"#execution/tools/workflow/cancel.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";const log=createLogger(`execution.cancel-descendant-turns`);async function cancelDescendantTurnsStep(e){"use step";let t;try{let n=readDurableSession(e.sessionState);t=getBlockingWorkflowToolRuns(n.state,getPendingCoordinationBatch(n.state)?.event.turnId??e.sessionState.emissionState.turnId)}catch(t){logError(log,`failed to read pending descendants during cancellation`,t,{sessionId:e.sessionState.sessionId});return}await Promise.all(t.map(e=>cancelWorkflowToolRun(e.address,{kind:`cancel`,reason:`The turn that called the tool was cancelled.`})))}export{cancelDescendantTurnsStep};

package/dist/src/execution/cancelled-model-call-batch.js

@@ -1 +1 @@
-import{contextStorage}from"#context/container.js";import{TurnDeliveryIdsKey}from"#context/keys.js";import{serializeContext}from"#context/serialize.js";import{createDurableSessionState}from"#execution/durable-session-store.js";import{preserveSerializedSessionDynamicModelSelection}from"#context/serialized-dynamic-model-selection.js";import{preserveCancelledTurnMessage}from"#execution/cancelled-turn-message.js";import{readRetainedBackgroundToolResult}from"#execution/tasks/parent/tool-execution.js";import{preserveSerializedInstrumentationState}from"#instrumentation/state.js";import{preserveSerializedBackgroundTaskObservabilityState}from"#shared/serialized-observability-state.js";import{preserveSerializedAgentTraceState}from"#tracing/agent-trace-context-store.js";async function createCancelledModelCallBatchResult(e){let t=serializeContext(e.ctx),n=readRetainedBackgroundToolResult(e.ctx),r=n?.backgroundTaskSession??e.checkpoint?.result.backgroundTaskSession,i=n?.backgroundTasks??e.checkpoint?.result.backgroundTasks,a=r??e.checkpoint?.result.session??e.initialSession,o=e.checkpoint===void 0?await contextStorage.run(e.ctx,()=>preserveCancelledTurnMessage(a,e.stepInput)):a,s={...e.checkpoint?.serializedContext??e.beforeBatchContext,[TurnDeliveryIdsKey.name]:t[TurnDeliveryIdsKey.name]};return{action:`cancelled`,...r===void 0||i===void 0?{}:{backgroundTaskContext:preserveSerializedBackgroundTaskObservabilityState(e.beforeBatchContext,t,i),backgroundTaskState:createDurableSessionState({session:o}),backgroundTasks:i},serializedContext:preserveSerializedInstrumentationState(preserveSerializedAgentTraceState(preserveSerializedSessionDynamicModelSelection(s,t),t),t),sessionState:createDurableSessionState({session:o})}}export{createCancelledModelCallBatchResult};
+import{contextStorage}from"#context/container.js";import{TurnDeliveryIdsKey}from"#context/keys.js";import{createDurableSessionState}from"#execution/durable-session-store.js";import{preserveSerializedSessionDynamicModelSelection}from"#context/serialized-dynamic-model-selection.js";import{serializeContext}from"#context/serialize.js";import{preserveCancelledTurnMessage}from"#execution/cancelled-turn-message.js";import{preserveSerializedInstrumentationState}from"#instrumentation/state.js";import{preserveSerializedAgentTraceState}from"#tracing/agent-trace-context-store.js";async function createCancelledModelCallBatchResult(e){let t=serializeContext(e.ctx),n=e.checkpoint?.result.session??e.initialSession,r=e.checkpoint===void 0?await contextStorage.run(e.ctx,()=>preserveCancelledTurnMessage(n,e.stepInput)):n,i={...e.checkpoint?.serializedContext??e.beforeBatchContext,[TurnDeliveryIdsKey.name]:t[TurnDeliveryIdsKey.name]};return{action:`cancelled`,serializedContext:preserveSerializedInstrumentationState(preserveSerializedAgentTraceState(preserveSerializedSessionDynamicModelSelection(i,t),t),t),sessionState:createDurableSessionState({session:r})}}export{createCancelledModelCallBatchResult};

package/dist/src/execution/connection-announcement.d.ts

@@ -0,0 +1,7 @@
+import type { ContextContainer } from "#context/container.js";
+/**
+ * Announces the agent's connections for the current step: a baseline listing
+ * the first time, then only what changed. Tool names and signatures stay out
+ * of the listing; `connection_search` returns them.
+ */
+export declare function announceConnections(ctx: ContextContainer): void;