eve 0.50.0 → 0.51.0

package/docs/reference/cli.md

@@ -3,7 +3,7 @@ title: "CLI"
 description: "Reference for every eve CLI command: init, set, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
 ---
 
-Relevant `eve` commands can run from the application root or any directory beneath it. Running `eve` with no command runs `eve init` when the current directory is not an eve project, or `eve dev` when it is.
+Relevant `eve` commands can run from the application root or any directory beneath it. In an `agents/` workspace, agent-specific commands accept `--agent <name>` and otherwise open a picker when more than one agent exists. Non-interactive runs must pass `--agent`. Running `eve` with no command runs `eve init` when the current directory is not an eve project, or `eve dev` when it is.
 
 ## Commands
 
@@ -37,7 +37,7 @@ When `eve build` fails on discovery errors, it prints the full diagnostics repor
 ## `eve init`
 
 ```bash
-eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
+eve init [target] [--agents <name,...>] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
 ```
 
 Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git.
@@ -48,6 +48,8 @@ Creates a new agent app or adds an agent to an existing app. Always installs dep
 | `eve init` or `eve init .` in an empty directory                           | Creates an agent project in the current directory                                                                                                                        |
 | `eve init` or `eve init .` in a non-empty directory without `package.json` | Asks whether to scaffold in the current directory or a named subdirectory. Using the current directory preserves unrelated files but overwrites files at generated paths |
 | `eve init .` in an existing project                                        | Adds `agent/` plus missing `eve`, `ai`, and `zod` dependencies. Requires `package.json` and no existing `agent/` files                                                   |
+| `eve init my-project --agents foreman,researcher`                          | Creates a workspace with `agents/foreman/agent/` and `agents/researcher/agent/`                                                                                          |
+| `eve init billing` from an `agents/` workspace                             | Adds only `agents/billing/agent/`; the workspace keeps its existing package, dependencies, and TypeScript configuration                                                  |
 
 Coding-agent launches and non-interactive terminals cannot answer the location prompt and fail before writing. Pass a new directory name, such as `eve init my-agent`, in those environments.
 
@@ -55,6 +57,7 @@ After scaffolding, a human terminal usually continues into `eve dev`. If a codin
 
 | Flag                   | Type   | Default                    | Description                                                                                                              |
 | ---------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--agents <names>`     | list   | unset                      | Create an `agents/` workspace with one or more comma-separated agent names.                                              |
 | `--model <model>`      | string | `openai/gpt-5.6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
 | `--reasoning <effort>` | enum   | provider default           | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
 | `--channel-web-nextjs` | flag   | off                        | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |

package/docs/sandbox.mdx

@@ -158,6 +158,8 @@ With `backend` omitted, eve uses `defaultBackend()`, which resolves on first use
 
 By default, Docker and microsandbox pull `ghcr.io/vercel/eve` while Vercel Sandbox pulls `vcr.vercel.com/vercel/eve/base`. Each image tag matches the installed eve version. Set `EVE_SANDBOX_IMAGE_TAG` to replace the version-derived tag for these default images. An explicit `image` passed to `docker()` or `microsandbox()` still takes precedence.
 
+On every backend, authored commands run as the non-root `vercel-sandbox` user through a non-interactive `bash -lc` login shell. `/workspace` and `$HOME` are writable, `$HOME/.local/bin` is on `PATH` for user-scoped executables, and system paths such as `/usr/local` stay root-owned. Use passwordless `sudo` when setup genuinely needs system-wide changes; `sudo` resets the environment, so pass through variables like `NPM_CONFIG_PREFIX` explicitly if a privileged step depends on them.
+
 `defaultBackend()` also accepts a keyed bag so each inner backend gets its own typed create options:
 
 ```ts

package/docs/subagents/index.mdx

@@ -17,7 +17,7 @@ The root session receives `agent` by default. The model calls it to delegate a t
 }
 ```
 
-The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. To run independent tasks in parallel, emit multiple `agent` calls in one response; eve runs the batch concurrently and returns every result before the root continues. Give parallel children non-overlapping write scopes.
+The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` always runs in the background and needs no configuration: each call returns `{ status: "working", taskId, agentId }`, then task notifications wake the parent with updates or the final result. Give parallel children non-overlapping write scopes.
 
 `agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
 
@@ -46,7 +46,9 @@ export default defineAgent({
 });
 ```
 
-`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out.
+`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out. Every declared local or remote subagent runs as a durable background task: the call returns `{ status: "working", taskId, agentId }` immediately, then task notifications wake the parent with updates, completion, failure, or cancellation. Human input requests surface separately on the parent session.
+
+A child running as a background task receives the framework `task_update` tool. It uses `task_update` to report progress to its parent. `task_cancel` is available to sessions that own background tasks, including a child that starts nested background work.
 
 A mounted extension can also contribute declared subagents from `extension/subagents/`. The mount namespace prefixes the subagent visible to the consuming agent node: mounting an extension as `crm` exposes its `reviewer` subagent as `crm__reviewer`. The contributed subagent keeps its own isolated tools, connections, skills, hooks, instructions, sandbox, and nested subagents, and its modules can read configuration from the extension handle. See [Extensions](./extensions#add-a-subagent) for the authoring and override behavior.
 
@@ -54,7 +56,7 @@ A mounted extension can also contribute declared subagents from `extension/subag
 
 To expose a declared subagent only for certain sessions or turns, export
 `defineDynamic` from that subagent's `agent.ts`. Return a `defineAgent`
-configuration to expose the subagent, or nil to omit it from the parent's tools.
+configuration to expose the subagent, or `null` to omit it from the parent's tools.
 
 ```ts title="agent/subagents/researcher/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
@@ -73,9 +75,9 @@ export default defineDynamic({
 ```
 
 Resolvers run at `session.started` or `turn.started`; `step.started` is not
-supported for subagents. A nil result (`null` or `undefined`) removes the
+supported for subagents. A nullish result (`null` or `undefined`) removes the
 subagent's description and tool definition from the model-visible surface.
-The subagent's filesystem manifest is always compiled; a non-nil result injects
+The subagent's filesystem manifest is always compiled; a non-nullish result injects
 the returned agent configuration when the child runs.
 
 Packaging controls must be available before the resolver runs. Put them on
@@ -151,7 +153,7 @@ eve lowers every subagent visible to the current agent (the root built-in copy,
 
 Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
 
-`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Workflow tool](./concepts/built-in-tools#workflow-tool).
+Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. Background subagents run through the model tool loop and are not available inside a model-authored `Workflow` program.
 
 A directly declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. A subagent supplied by a mounted extension includes the mount namespace, such as `crm__reviewer`. The model, approvals, logs, and evals reference the resulting name. Its input schema is:
 
@@ -169,7 +171,7 @@ Do not rely on subagent delegation by itself as an approval boundary. Put sensit
 
 Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events `subagent.called` and `subagent.completed`, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
 
-Cancelling a parent turn also requests cancellation of every active child it started, recursively through nested and remote subagents. Each affected session emits its own `turn.cancelled` → `session.waiting` boundary; the cancelled parent does not synthesize tool results or emit `subagent.completed`. A child that already completed or parked has no active turn and is a benign no-op.
+A background task that was already admitted survives cancellation of the turn that started it; background work that has not yet been admitted is rejected with the cancelled step. Use `task_cancel` to stop an admitted task. Parent-session finalization cancels remaining live tasks.
 
 Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call so completed earlier steps, tool results, and sandbox work remain available to the child. Other recoverable task errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed task result instead of stacking both retry budgets; terminal errors fail immediately.
 
@@ -188,4 +190,3 @@ Split out a subagent when the task needs a different prompt or specialist role,
 ## What to read next
 
 - [Remote agents](./guides/remote-agents): call another eve deployment as a subagent.
-- [Workflow tool](./concepts/built-in-tools#workflow-tool): have the model orchestrate its subagents programmatically (fan-out, map-reduce).

package/docs/tools/overview.mdx

@@ -56,15 +56,16 @@ history or `toModelOutput`; only the final yield does. Treat snapshots as
 last-write-wins by tool call id, not append-only progress. The durable runtime
 can retry a step and replay overlapping snapshots.
 
-### Experimental background execution
+### Background execution
 
 `defineTool({ execution: "background" })` receives a third `task` argument. Returning a normal
 value completes the durable task with that value. Returning `task.delegated({ executor, receipt })`
-returns a `working` receipt immediately while an external executor continues the task.
-The root agent must enable `experimental.tasks`; eve rejects background tools at build time otherwise.
+returns a `working` receipt immediately while an external executor continues the task. Background
+tools are a normal execution mode and need no root-agent flag.
 
-This contract currently supports framework-owned task executors, including local and remote
-subagents when `experimental.tasks` is enabled. After delegating, an in-process executor reports
+Built-in, declared local, and remote subagents use this background task lifecycle automatically.
+After delegating, an
+in-process executor reports
 progress with `task.send({ kind: "update", message })` and the terminal result with
 `task.send({ kind: "complete", data })` (or `fail` / `cancel`). `send` is not restart-safe — an
 in-memory callback dies with the process — so the cross-process executor wire remains
@@ -78,12 +79,12 @@ Later task-triggered parent turns receive fresh state for the same cohort. The m
 to keep related intermediate results silent while any task remains pending. Once every related
 task is terminal, the state includes their outputs so the model can combine the useful results.
 
-### Durable tools
+### Workflows as tools
 
-A tool whose `execute` starts with `"use workflow"` runs as a durable Workflow run instead of
-inside the model step. It can wait for a person, a webhook, or a timer for as long as it takes, with
-nothing running in between, and its return value still settles the tool call. See
-[Durable tools](/docs/tools/workflows).
+Put `"use workflow"` at the start of a tool's `execute` function to run each call as a durable
+Workflow run. The tool can wait for a person, webhook, or timer without holding compute, then return
+its result to the model. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and
+examples.
 
 ### The `ctx` parameter
 

package/docs/tools/workflows.mdx

@@ -1,26 +1,33 @@
 ---
-title: "Durable Tools"
-description: "Write a tool as a workflow so it can wait for a person, a webhook, or a timer for as long as it takes, with nothing running in between."
+title: "Workflows as Tools"
+description: "Define durable workflow tools that wait for people, webhooks, or timers without holding compute."
 url: /tools/workflows
 ---
 
-A tool's `execute` may be a workflow. eve starts one durable run per tool call and, by default,
-waits for it: the run's return value is the tool result, however long it takes. While the run waits
-on a person, a webhook, or a sleep, the turn is parked and nothing is running. Mark the same tool
-`execution: "background"` and the model gets a receipt instead; eve wakes the agent with the return
-value when the run ends.
+A workflow tool is an authored tool whose `execute` function starts with `"use workflow"`. Each
+call starts a durable Workflow run. Use one when a tool must wait for a person, webhook, or timer,
+delegate work to subagents, or coordinate retryable steps over a long period.
 
-Inside the tool, everything is the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`,
-`"use step"`, `createHook`, `createWebhook`, `sleep`, retries, replay. eve adds `ask` from
-`eve/workflow` — a question the human on the session's channel answers — and treats each `yield` as
-a durable progress report.
+By default, the model's tool call waits for the run's return value. While the run is suspended, the
+turn is parked and holds no compute. Set `execution: "background"` when the conversation should
+continue; the model receives a task receipt, and eve wakes the agent with the result when the run
+ends.
 
-## Write one
+Workflow tools use the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`, `"use step"`,
+`createHook`, `createWebhook`, `sleep`, retries, and replay. eve adds `ask` from `eve/workflow` for
+questions answered through the session's channel and `agent` for durable subagent delegation. Each
+`yield` becomes a durable progress report.
+
+A workflow tool runs code you wrote and appears to the model under its path-derived tool name, such
+as `deploy`.
+
+## Define a workflow tool
 
 ```ts title="agent/tools/deploy.ts"
 import { defineTool } from "eve/tools";
 import { ask } from "eve/workflow";
 import { z } from "zod";
+import { computePlan, runDeploy, type DeployPlan } from "../lib/deploy";
 
 export default defineTool({
   description: "Deploy a service to production. Pauses for a human to approve the plan.",
@@ -85,8 +92,8 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
 | cancel                   | cancelling the turn cancels the run | `task_cancel`, or the session ending        |
 
 Wait when the model needs the answer to continue. Go background when the wait may outlive the
-conversation or the user should keep talking in the meantime. Background tools require
-`experimental.tasks` on the root agent, like every background tool.
+conversation or the user should keep talking in the meantime. Background tools need no root-agent
+flag.
 
 ## Ask a human: `ask`
 
@@ -123,6 +130,25 @@ if (answer === undefined) return { deployed: false, reason: "timed out" };
 Compare the [`approval`](/docs/human-in-the-loop) policy, which gates the call before `execute` runs
 and can only show the model's input. Both compose: `approval` before the run, `ask` inside it.
 
+## Delegate work: `agent`
+
+Workflow tools can call a visible subagent and wait for its result:
+
+```ts
+import { agent } from "eve/workflow";
+
+const result = await agent(ctx, {
+  key: "security-review",
+  target: "reviewer",
+  message: "Review the deployment plan for security risks.",
+});
+```
+
+`key` is required, non-empty, and unique within the workflow run. It makes the invocation identity
+stable across replay, so use a fixed key for each logical call site. Parallel calls must use distinct
+keys. `target` is the model-visible subagent name; pass `agentId` to continue an existing child and
+`outputSchema` to require structured output.
+
 ## Report progress: `yield`
 
 A workflow body may be an async generator. Each `yield` is a durable progress snapshot; the return
@@ -167,7 +193,7 @@ as cancelled whether or not it did. A body parked on a hook or a `sleep` does no
 it is abandoned when the grace period ends. Steps that received the signal are how you clean up
 first.
 
-## Flows
+## Workflow tool examples
 
 ### Approve with a deadline and an escalation
 
@@ -195,8 +221,11 @@ and returning withdraws the request.
 
 ### Wait for an external system to call back
 
-```ts
+```ts title="agent/tools/render_video.ts"
+import { defineTool } from "eve/tools";
 import { createWebhook, FatalError } from "workflow";
+import { z } from "zod";
+import { submitRender } from "../lib/render";
 
 export default defineTool({
   description: "Render a video. Returns the URL once the render farm finishes.",
@@ -220,8 +249,11 @@ system posts to it when it is done. Nothing runs in between.
 
 ### Ask now, act when answered
 
-```ts
+```ts title="agent/tools/refund_order.ts"
+import { defineTool } from "eve/tools";
 import { ask } from "eve/workflow";
+import { z } from "zod";
+import { issueRefund } from "../lib/refunds";
 
 export default defineTool({
   description: "Request approval to refund an order, then issue the refund once approved.",
@@ -250,8 +282,10 @@ on the channel. When it is answered, the refund runs and the agent is woken with
 
 ### Remind me later
 
-```ts
+```ts title="agent/tools/remind.ts"
+import { defineTool } from "eve/tools";
 import { sleep } from "workflow";
+import { z } from "zod";
 
 export default defineTool({
   description: "Remind the user about something after a delay.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [

package/dist/src/execution/agent-continuation-bundle.js

@@ -1 +0,0 @@
-import{resolveRemoteAgentForAction}from"#execution/remote-agent-dispatch.js";function createAgentContinuationBundle(e){let{action:t,dynamicRemoteAgent:n}=e;if(t.kind!==`remote-agent-call`||n===void 0)return e.bundle;let r=e.bundle.subagentRegistry.subagentsByNodeId,i=Object.assign(new Map(r),{get:e=>e===t.nodeId?{definition:resolveRemoteAgentForAction({dynamicRemoteAgent:n,nodeId:e,registry:r,remoteAgentName:t.remoteAgentName})}:r.get(e)});return{...e.bundle,subagentRegistry:{...e.bundle.subagentRegistry,subagentsByNodeId:i}}}export{createAgentContinuationBundle};

package/dist/src/execution/agent-handle-dispatch.d.ts

@@ -1,79 +0,0 @@
-/**
- * Continuation dispatch for stored agent handles.
- *
- * Owns the `agentId` leg of the runtime-action dispatch step: resolving a
- * model-supplied agentId against the session's handle store via
- * `prepareAgentContinuation`, delivering the follow-up message to the
- * address the running handle records, and resolving delivery failures as
- * dead (handle deleted) or retryable (handle restored to `parked`).
- */
-import type { ActivityObserverConfig, SessionAuthContext } from "#channel/types.js";
-import { type AgentAddress } from "#harness/handles/store.js";
-import type { RuntimeActionRequest, RuntimeRemoteAgentCallActionRequest, RuntimeSubagentCallActionRequest, RuntimeSubagentDispatchFailure } from "#shared/action-types.js";
-import type { CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
-import type { hydrateDurableSession } from "#execution/session.js";
-/** Runtime action kinds that may address an agent handle via `agentId`. */
-export type RuntimeAgentHandleAction = RuntimeRemoteAgentCallActionRequest | RuntimeSubagentCallActionRequest;
-/** Narrows an action to the kinds that may carry an `agentId` continuation. */
-export declare function isAgentHandleAction(action: RuntimeActionRequest): action is RuntimeAgentHandleAction;
-/** Hydrated parent session snapshot threaded through dispatch. */
-export type RuntimeSession = ReturnType<typeof hydrateDurableSession>;
-/**
- * Outcome of dispatching one planned runtime action: an adopted child ready
- * for the `subagent.called` emission tail, or a per-action error result.
- * Either way the (possibly updated) session snapshot rides along.
- *
- * `address` is the same confirmed {@link AgentAddress} recorded on the
- * child's running handle; consumers project it into wire shapes (e.g. the
- * flat `childSessionId` / `remote` fields of `subagent.called`) at the
- * emission site instead of this type re-encoding them.
- */
-export type DispatchOutcome = {
-    readonly address: AgentAddress;
-    readonly callId: string;
-    readonly kind: "called";
-    readonly name: string;
-    readonly session: RuntimeSession;
-    readonly toolName: string;
-} | {
-    readonly deliveryAmbiguous?: boolean;
-    readonly kind: "error";
-    readonly result: RuntimeSubagentDispatchFailure;
-    readonly session: RuntimeSession;
-};
-/**
- * Delivers one `agentId` continuation to the child the handle names.
- *
- * Planning converts initially unknown ids into fresh starts, so an id that
- * matches no handle here disappeared mid-batch and reports
- * `AGENT_UNREACHABLE`. Name mismatches and busy handles report
- * `AGENT_MISMATCH` / `AGENT_BUSY` without touching the store. Delivery
- * failures report `AGENT_UNREACHABLE`: permanent ones resolve the handle as
- * dead, transient ones restore it to `parked` so the model can retry the
- * same agentId.
- */
-export declare function dispatchToAgentHandle(input: {
-    readonly action: RuntimeAgentHandleAction;
-    readonly activityObserver?: ActivityObserverConfig;
-    readonly agentId: string;
-    readonly auth: SessionAuthContext | null;
-    readonly bundle: CompiledBundle;
-    readonly currentSession: RuntimeSession;
-    readonly parentToken: string;
-    readonly parentTurnId: string;
-}): Promise<DispatchOutcome>;
-/** Delivers a tasks-mode continuation without creating a second lifecycle claim. */
-export declare function dispatchToTaskAgentAddress(input: {
-    readonly action: RuntimeAgentHandleAction;
-    readonly activityObserver?: ActivityObserverConfig;
-    readonly agentId: string;
-    readonly auth: SessionAuthContext | null;
-    readonly bundle: CompiledBundle;
-    readonly currentSession: RuntimeSession;
-    readonly parentToken: string;
-}): Promise<DispatchOutcome>;
-export declare function createAgentErrorResult(input: {
-    readonly action: RuntimeAgentHandleAction;
-    readonly code: string;
-    readonly message: string;
-}): RuntimeSubagentDispatchFailure;

package/dist/src/execution/agent-handle-dispatch.js

@@ -1 +0,0 @@
-import{createEveCallbackRoutePath}from"#protocol/routes.js";import{createLogger,logError}from"#internal/logging.js";import{createWorkflowRuntime}from"#execution/workflow-runtime.js";import{deriveAgentOperationId}from"#harness/handles/operation-id.js";import{continueRemoteAgentSession,isAmbiguousRemoteAgentContinueError,isRetryableRemoteAgentContinueError,resolveRemoteAgentForAction}from"#execution/remote-agent-dispatch.js";import{AGENT_BUSY,AGENT_MISMATCH,AGENT_UNREACHABLE}from"#harness/agent-handle-errors.js";import{getAgentHandleStore}from"#harness/handles/store.js";import{prepareAgentContinuation,rejectAgentEffect,removeTaskAgentAddress}from"#harness/handles/transitions.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{normalizeRequestedOutputSchema}from"#execution/subagent-invocation.js";import{createWorkflowCallbackUrl}from"#execution/workflow-callback-url.js";import{err,ok}from"#shared/result.js";import{readTaskIdFromInboxToken}from"#tasks/task-inbox-token.js";const log=createLogger(`execution.agent-handle-dispatch`);function isAgentHandleAction(e){return e.kind===`subagent-call`||e.kind===`remote-agent-call`}async function dispatchToAgentHandle(e){let{action:t,agentId:r,bundle:a}=e,o=t.kind===`remote-agent-call`?t.remoteAgentName:t.subagentName,s={callId:t.callId,id:deriveAgentOperationId({callId:t.callId,parentSessionId:e.currentSession.sessionId,parentTurnId:e.parentTurnId}),kind:`continue`,parentTurnId:e.parentTurnId,previousStatus:``},c=prepareAgentContinuation(e.currentSession,{agentId:r,invokedName:o,operation:s});switch(c.kind){case`unknown`:return{kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_UNREACHABLE,message:`Agent with id "${r}" is no longer reachable.`}),session:e.currentSession};case`mismatch`:return{kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_MISMATCH,message:`Agent "${r}" from the <agents> list does not belong to "${o}".`}),session:e.currentSession};case`busy`:return{kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_BUSY,message:`Agent "${r}" is still working on its previous request. Wait for its result before continuing it.`}),session:e.currentSession};case`ready`:break}let{handle:f}=c,p=await deliverToAgentAddress({action:t,activityObserver:e.activityObserver,address:f.address,auth:e.auth,bundle:a,identity:f.identity,parentToken:e.parentToken});if(!p.ok){let{cause:e,permanent:i}=p.error;return logError(log,`agent delivery failed`,e,{agentId:r,callId:t.callId,nodeId:f.identity.nodeId,permanent:i,subagentName:f.identity.name}),{deliveryAmbiguous:p.error.deliveryAmbiguous,kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_UNREACHABLE,message:i?`Agent "${f.identity.name}" with id "${r}" is no longer reachable.`:`Agent "${f.identity.name}" with id "${r}" is temporarily unreachable. Try again.`}),session:rejectAgentEffect(c.session,{disposition:i?`dead`:`retryable`,operationId:s.id})}}return{address:f.address,callId:t.callId,kind:`called`,name:t.name,session:c.session,toolName:f.identity.name}}async function dispatchToTaskAgentAddress(e){let{action:t,agentId:r}=e,i=t.kind===`remote-agent-call`?t.remoteAgentName:t.subagentName,a=(getAgentHandleStore(e.currentSession.state)?.handles??[]).find(e=>e.phase===`addressed`&&e.identity.id===r);if(a===void 0)return{kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_UNREACHABLE,message:`Agent with id "${r}" is no longer reachable.`}),session:e.currentSession};if(a.identity.name!==i)return{kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_MISMATCH,message:`Agent "${r}" from the <agents> list does not belong to "${i}".`}),session:e.currentSession};let o=await deliverToAgentAddress({action:t,activityObserver:e.activityObserver,address:a.address,auth:e.auth,bundle:e.bundle,identity:a.identity,parentToken:e.parentToken});if(!o.ok){let{cause:i,permanent:s}=o.error;return logError(log,`task agent delivery failed`,i,{agentId:r,callId:t.callId,nodeId:a.identity.nodeId,permanent:s,subagentName:a.identity.name}),{deliveryAmbiguous:o.error.deliveryAmbiguous,kind:`error`,result:createAgentErrorResult({action:t,code:AGENT_UNREACHABLE,message:s?`Agent "${a.identity.name}" with id "${r}" is no longer reachable.`:`Agent "${a.identity.name}" with id "${r}" is temporarily unreachable. Try again.`}),session:s?removeTaskAgentAddress(e.currentSession,r):e.currentSession}}return{address:a.address,callId:t.callId,kind:`called`,name:t.name,session:e.currentSession,toolName:a.identity.name}}async function deliverToAgentAddress(t){let{action:n,address:i,bundle:l,identity:u}=t;if(i.kind===`agent/remote`){let r;try{r=resolveRemoteAgentForAction({nodeId:u.nodeId,remoteAgentName:u.name,registry:l.subagentRegistry.subagentsByNodeId})}catch(e){return err({cause:e,deliveryAmbiguous:!1,permanent:!0})}try{await continueRemoteAgentSession({activityObserver:t.activityObserver,auth:t.auth,callback:{callId:n.callId,subagentName:u.name,taskId:readTaskIdFromInboxToken(t.parentToken),token:t.parentToken,url:createWorkflowCallbackUrl(i.callbackBaseUrl,createEveCallbackRoutePath(t.parentToken))},message:readSubagentMessage(n),outputSchema:normalizeRequestedOutputSchema(n.input.outputSchema),remote:{...r,url:i.url},sessionId:i.sessionId})}catch(e){return err({cause:e,deliveryAmbiguous:isAmbiguousRemoteAgentContinueError(e),permanent:!isRetryableRemoteAgentContinueError(e)})}return ok(void 0)}let d=createWorkflowRuntime({compiledArtifactsSource:l.compiledArtifactsSource,nodeId:u.nodeId});try{if((await d.dispatchSession({command:{auth:t.auth,caller:{activityObserver:t.activityObserver,callId:n.callId,replyTo:{kind:`hook`,token:t.parentToken},subagentName:u.name,taskId:readTaskIdFromInboxToken(t.parentToken)},kind:`send`,payload:{message:readSubagentMessage(n),outputSchema:normalizeRequestedOutputSchema(n.input.outputSchema)}},sessionId:i.sessionId})).status===`session_not_active`)return err({cause:Error(`Agent session "${i.sessionId}" is no longer active.`),deliveryAmbiguous:!1,permanent:!0})}catch(e){let t=isRuntimeNoActiveSessionError(e);return err({cause:e,deliveryAmbiguous:!t,permanent:t})}return ok(void 0)}function createAgentErrorResult(e){return{callId:e.action.callId,isError:!0,kind:`subagent-result`,origin:`dispatch`,output:{code:e.code,message:e.message},subagentName:e.action.kind===`remote-agent-call`?e.action.remoteAgentName:e.action.subagentName}}function readSubagentMessage(e){return typeof e.input.message==`string`?e.input.message:``}export{createAgentErrorResult,dispatchToAgentHandle,dispatchToTaskAgentAddress,isAgentHandleAction};

package/dist/src/execution/delegated-parent-notification.js

@@ -1 +0,0 @@
-import{createLogger}from"#internal/logging.js";import{ActivityObserverKey,SessionCallbackKey}from"#context/keys.js";import{toErrorMessage}from"#shared/errors.js";import{parseJsonValue}from"#shared/json.js";import{ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{parseSessionCallback}from"#channel/session-callback.js";import{resumeHook}from"#internal/workflow/runtime.js";import{SUBAGENT_EXECUTION_FAILED}from"#harness/agent-handle-errors.js";import{readTaskIdFromInboxToken}from"#tasks/task-inbox-token.js";import{deserializeContext}from"#context/serialize.js";import{HookNotFoundError}from"#compiled/@workflow/errors/index.js";import{SUBAGENT_ADAPTER_KIND,isSubagentAdapterState}from"#execution/subagent-adapter-state.js";import{postSessionCallbackRequest}from"#execution/session-callback-request.js";const log=createLogger(`execution.delegated-parent-notification`);async function notifyDelegatedParentStep(e){"use step";if(e.result===void 0)return;let t=(await deserializeContext(e.serializedContext)).get(ChannelKey);if(t?.kind!==SUBAGENT_ADAPTER_KIND)return;let n=String(t.state?.parentContinuationToken??``);n!==``&&await resumeHook(n,{kind:`runtime-action-result`,results:[e.usage===void 0?e.result:{...e.result,outcome:{...e.result.outcome,usageDelta:e.usage},usage:e.usage}]})}const ZERO_TOKEN_USAGE={cacheReadTokens:0,cacheWriteTokens:0,inputTokens:0,outputTokens:0};async function notifyTurnCallerStep(e){"use step";if(e.caller===void 0)return;let t=createSettledTurnResult({caller:e.caller,lifecycle:e.lifecycle,sessionId:e.sessionId,settled:e.settled});if(e.caller.replyTo.kind===`callback`){await postSettledTurnCallback({result:t,sessionId:e.sessionId,url:e.caller.replyTo.url});return}await resumeSettledTurnHook(e.caller.replyTo.token,t)}async function notifyCancelledTaskCallerStep(e){"use step";if(e.caller?.taskId===void 0)return;let t=e.usage??ZERO_TOKEN_USAGE,n={callId:e.caller.callId,kind:`subagent-result`,origin:`child`,outcome:{kind:`parked`,result:{kind:`cancelled`},usageDelta:t},output:``,subagentName:e.caller.subagentName},r=e.usage===void 0?n:{...n,usage:e.usage};if(e.caller.replyTo.kind===`callback`){await postSettledTurnCallback({result:r,sessionId:e.sessionId,url:e.caller.replyTo.url});return}await resumeSettledTurnHook(e.caller.replyTo.token,r)}async function notifyTaskTurnStartedStep(e){"use step";let t=e.caller?.taskId;if(e.caller===void 0||t===void 0)return;let n={childSessionId:e.childSessionId,childTurnId:e.childTurnId,kind:`turn-started`,taskId:t};if(e.caller.replyTo.kind===`hook`){await resumeHook(e.caller.replyTo.token,n);return}let r=await postSessionCallbackRequest({body:{callId:e.caller.callId,kind:`turn.started`,sessionId:e.childSessionId,subagentName:e.caller.subagentName,taskId:t,turnId:e.childTurnId},url:e.caller.replyTo.url});if(!r.ok)throw Error(`Task turn-start callback failed with HTTP ${r.status}.`)}function createSettledTurnResult(e){let t=e.settled.usage??ZERO_TOKEN_USAGE;if(e.settled.isError===!0){let n={code:SUBAGENT_EXECUTION_FAILED,message:toErrorMessage(e.settled.output)};return{callId:e.caller.callId,isError:!0,kind:`subagent-result`,origin:`child`,outcome:{kind:e.lifecycle,result:{error:n,kind:`failed`},usageDelta:t},output:n,subagentName:e.caller.subagentName}}let n=parseJsonValue(e.settled.output),a={callId:e.caller.callId,kind:`subagent-result`,origin:`child`,outcome:{kind:e.lifecycle,result:{kind:`succeeded`,output:n},usageDelta:t},output:n,subagentName:e.caller.subagentName};return e.settled.usage===void 0?a:{...a,usage:e.settled.usage}}async function resolveInitialTurnCallerStep(e){"use step";let t=e.serializedContext[SessionCallbackKey.name];if(t!==void 0){let e=parseSessionCallback(t);if(!e.ok)throw Error(`Serialized session callback is invalid.`,{cause:e.cause});return{callId:e.callback.callId,replyTo:{kind:`callback`,token:e.callback.token,url:e.callback.url},subagentName:e.callback.subagentName,taskId:e.callback.taskId??readTaskIdFromInboxToken(e.callback.token)}}let r=(await deserializeContext(e.serializedContext)).get(ChannelKey);if(!(r?.kind!==SUBAGENT_ADAPTER_KIND||!isSubagentAdapterState(r.state)))return{callId:r.state.callId,replyTo:{kind:`hook`,token:r.state.parentContinuationToken},subagentName:r.state.subagentName,taskId:readTaskIdFromInboxToken(r.state.parentContinuationToken)}}async function bindTurnCallerContextStep(e){"use step";let r=e.caller;if(r===void 0)return e.serializedContext;let i=r.activityObserver===void 0?e.serializedContext:{...e.serializedContext,[ActivityObserverKey.name]:r.activityObserver};if(r.replyTo.kind===`callback`){let e={callId:r.callId,subagentName:r.subagentName,token:r.replyTo.token,url:r.replyTo.url};return{...i,[SessionCallbackKey.name]:r.taskId===void 0?e:{...e,taskId:r.taskId}}}let o=i[ChannelKey.name];if(typeof o!=`object`||!o||Reflect.get(o,`kind`)!==SUBAGENT_ADAPTER_KIND||!isSubagentAdapterState(Reflect.get(o,`state`)))throw Error(`Delegated local turn is missing its subagent adapter binding.`);let s=Reflect.get(o,`state`);return{...i,[ChannelKey.name]:{...o,state:{...s,callId:r.callId,parentContinuationToken:r.replyTo.token,subagentName:r.subagentName}}}}async function postSettledTurnCallback(e){let{sessionId:t}=e;if(e.result.isError===!0){await postCallbackPayload({payload:{callId:e.result.callId,error:e.result.output,kind:`turn.failed`,outcome:e.result.outcome,sessionId:t,subagentName:e.result.subagentName},url:e.url});return}await postCallbackPayload({payload:{callId:e.result.callId,kind:`turn.completed`,outcome:e.result.outcome,output:e.result.output,sessionId:t,subagentName:e.result.subagentName},url:e.url})}async function postCallbackPayload(e){let t=await postSessionCallbackRequest({body:e.payload,url:e.url});if(!t.ok)throw Error(`Turn callback failed with HTTP ${t.status}.`)}async function resumeSettledTurnHook(e,t){try{await resumeHook(e,{kind:`runtime-action-result`,results:[t]})}catch(n){if(!HookNotFoundError.is(n))throw n;log.warn(`turn caller hook no longer exists`,{callId:t.callId,callerToken:e})}}export{bindTurnCallerContextStep,notifyCancelledTaskCallerStep,notifyDelegatedParentStep,notifyTaskTurnStartedStep,notifyTurnCallerStep,resolveInitialTurnCallerStep};

package/dist/src/execution/delegated-parent-result.js

@@ -1 +0,0 @@
-import{toErrorMessage}from"#shared/errors.js";import{CHANNEL_CONTEXT_KEY_NAME}from"#context/key-names.js";import{SUBAGENT_EXECUTION_FAILED}from"#harness/agent-handle-errors.js";import{SUBAGENT_ADAPTER_KIND}from"#execution/subagent-adapter-state.js";const ZERO_TOKEN_USAGE={cacheReadTokens:0,cacheWriteTokens:0,inputTokens:0,outputTokens:0};function createDelegatedSubagentSuccessResult(e,n){let i=e[CHANNEL_CONTEXT_KEY_NAME];if(i?.kind===SUBAGENT_ADAPTER_KIND)return{callId:String(i.state?.callId??``),kind:`subagent-result`,origin:`child`,outcome:{kind:`terminal`,result:{kind:`succeeded`,output:n},usageDelta:ZERO_TOKEN_USAGE},output:n,subagentName:String(i.state?.subagentName??``)}}function createDelegatedSubagentErrorResult(t,r){let i=createDelegatedSubagentSuccessResult(t,``);if(i===void 0)return;let a={code:SUBAGENT_EXECUTION_FAILED,message:toErrorMessage(r)};return{...i,isError:!0,outcome:{kind:`terminal`,result:{error:a,kind:`failed`},usageDelta:ZERO_TOKEN_USAGE},output:a}}export{createDelegatedSubagentErrorResult,createDelegatedSubagentSuccessResult};

package/dist/src/execution/delegation-tool.d.ts

@@ -1,10 +0,0 @@
-import type { HarnessToolDefinition } from "#harness/execute-tool.js";
-import type { PreparedRuntimeDelegationTool } from "#runtime/sessions/turn.js";
-import { type ToolSchemaSource } from "#tools/schema.js";
-type HarnessDelegationTool = Pick<PreparedRuntimeDelegationTool, "behavior" | "description" | "name"> & {
-    readonly inputSchema?: ToolSchemaSource | null;
-    readonly outputSchema?: ToolSchemaSource | null;
-};
-export declare function createHarnessDelegationToolDefinition(tool: HarnessDelegationTool): HarnessToolDefinition;
-export declare function createBackgroundSubagentHarnessDefinition(tool: HarnessDelegationTool): HarnessToolDefinition;
-export {};

package/dist/src/execution/delegation-tool.js

@@ -1 +0,0 @@
-import{UNSPECIFIED_INPUT_SCHEMA,toInputSchema,toOutputSchema}from"#tools/schema.js";import{createToolExecuteWithAuth}from"#execution/tool-auth.js";import{defineSubagent}from"#execution/tools/subagent/local.js";import{defineRemoteSubagent}from"#execution/tools/subagent/remote.js";function createHarnessDelegationToolDefinition(t){return{behavior:t.behavior,description:t.description??``,inputSchema:toInputSchema(t.inputSchema)??UNSPECIFIED_INPUT_SCHEMA,name:t.name,outputSchema:toOutputSchema(t.outputSchema)??void 0}}function createBackgroundSubagentHarnessDefinition(n){let r=n.behavior?.handling;if(r?.kind!==`dispatch`)throw Error(`Background subagent tool "${n.name}" has no prepared dispatch target.`);if(r.target.kind===`task-cancel`||r.target.kind===`task-update`||r.target.kind===`workflow-tool-call`)throw Error(`Background subagent tool "${n.name}" cannot dispatch ${r.target.kind}.`);let i=createBackgroundSubagentDefinition({description:n.description??``,name:n.name,target:r.target}),a=createToolExecuteWithAuth({execute:i.execute,execution:i.execution,scope:n.name});return{behavior:n.behavior,description:i.description,execute:a,execution:i.execution,inputSchema:toInputSchema(i.inputSchema)??UNSPECIFIED_INPUT_SCHEMA,name:n.name,outputSchema:toOutputSchema(i.outputSchema)??void 0}}function createBackgroundSubagentDefinition(e){switch(e.target.kind){case`remote-agent-call`:return defineRemoteSubagent({description:e.description,name:e.name,target:e.target});case`self-agent-call`:case`subagent-call`:return defineSubagent({description:e.description,name:e.name,target:e.target})}}export{createBackgroundSubagentHarnessDefinition,createHarnessDelegationToolDefinition};

package/dist/src/execution/dispatch-runtime-actions-shared.d.ts

@@ -1,165 +0,0 @@
-/**
- * Machinery shared by the two runtime-action dispatch steps:
- * `dispatchRuntimeActionsStep` (plain mode) and `dispatchTaskStep`
- * (task mode). Both run the same preflight → plan → dispatch → emit
- * skeleton over one pending batch and differ only in the per-entry
- * delegation lifecycle, so planning and the replay-safe
- * `subagent.called` emission tail live here.
- */
-import type { ActivityObserverConfig, SessionParent } from "#channel/types.js";
-import { type ChannelAdapter, type ChannelAdapterContext } from "#channel/adapter.js";
-import { type LocalDevRequestProvenance } from "#context/keys.js";
-import { type AlsContext } from "#context/container.js";
-import { type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
-import { type DispatchOutcome, type RuntimeAgentHandleAction, type RuntimeSession } from "#execution/agent-handle-dispatch.js";
-import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
-import type { ActivityWorkIdentityV1 } from "#protocol/activity.js";
-import type { RuntimeActionResult, RuntimeRemoteAgentCallActionRequest, RuntimeSubagentCallActionRequest, RuntimeSubagentDispatchFailure } from "#shared/action-types.js";
-import type { PendingAgentDispatchAction, PendingTaskControlAction, PendingWorkflowToolAction } from "#shared/dispatch-action.js";
-import { type DurableSessionState } from "#execution/durable-session-store.js";
-import { buildSubagentRunInput, type SubagentInputSource } from "#execution/subagent-tool.js";
-import { getDynamicSubagentSelection } from "#context/dynamic-subagent-lifecycle.js";
-type DynamicSubagentAgentConfig = NonNullable<Extract<ReturnType<typeof getDynamicSubagentSelection>, {
-    readonly kind: "subagent";
-}>["agentConfig"]>;
-type DynamicRemoteAgentConfig = NonNullable<Extract<ReturnType<typeof getDynamicSubagentSelection>, {
-    readonly kind: "remote";
-}>["remoteAgent"]>;
-export type DispatchPlanEntry = {
-    readonly kind: "resume";
-    readonly action: RuntimeAgentHandleAction;
-    readonly agentId: string;
-    readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
-} | {
-    readonly kind: "reject";
-    readonly result: RuntimeSubagentDispatchFailure;
-} | {
-    readonly kind: "start";
-    readonly target: DispatchStartTarget;
-} | {
-    readonly kind: "task-control";
-    readonly action: PendingTaskControlAction;
-} | {
-    readonly kind: "workflow-tool";
-    readonly action: PendingWorkflowToolAction;
-};
-export type DispatchStartTarget = {
-    readonly kind: "local";
-    readonly action: RuntimeSubagentCallActionRequest;
-    readonly dynamicSubagentAgentConfig?: DynamicSubagentAgentConfig;
-    readonly selfAgent: boolean;
-    readonly source: SubagentInputSource;
-} | {
-    readonly kind: "remote";
-    readonly action: RuntimeRemoteAgentCallActionRequest;
-    readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
-};
-/** Input contract shared by both dispatch steps so the turn workflow can select either. */
-export interface RuntimeActionDispatchInput {
-    readonly callbackBaseUrl?: string;
-    /** Internal hook that receives child completion and HITL payloads. */
-    readonly parentContinuationToken?: string;
-    readonly parentWritable: WritableStream<Uint8Array>;
-    readonly serializedContext: Record<string, unknown>;
-    readonly sessionState: DurableSessionState;
-}
-/**
- * Result contract shared by both dispatch steps. `pendingTasks` is
- * always empty in plain mode; keeping it on both keeps the turn
- * workflow's acknowledgement call site uniform.
- */
-export interface RuntimeActionDispatchResult {
-    readonly results: readonly RuntimeActionResult[];
-    readonly sessionState: DurableSessionState;
-    readonly pendingTasks: readonly {
-        readonly taskInboxToken: string;
-        readonly taskId: string;
-        readonly taskRunId: string;
-    }[];
-}
-/** Everything preflight produces before either step's dispatch loop runs. */
-export interface PreparedRuntimeActionDispatch {
-    readonly adapter: ChannelAdapter;
-    readonly adapterCtx: ChannelAdapterContext;
-    readonly auth: Parameters<typeof buildSubagentRunInput>[0]["auth"];
-    readonly batch: NonNullable<ReturnType<typeof getPendingRuntimeActionBatch>>;
-    readonly bundle: CompiledBundle;
-    readonly capabilities: Parameters<typeof buildSubagentRunInput>[0]["capabilities"];
-    readonly channelMetadata: Parameters<typeof buildSubagentRunInput>[0]["channelMetadata"];
-    /**
-     * Number of freshly started local subagents in the plan. The parent's
-     * remaining token quota is split across these, the children that
-     * actually receive an enforced cap: continuations already run under
-     * their own budget, and remote agents run on their own deployment
-     * under their own limits, so neither dilutes the local shares.
-     */
-    readonly fanoutSize: number;
-    readonly initiatorAuth: Parameters<typeof buildSubagentRunInput>[0]["initiatorAuth"];
-    readonly localDevRequest?: LocalDevRequestProvenance;
-    /** Lineage of the session running this dispatch, when it is itself a delegated child. */
-    readonly parentSession: SessionParent | undefined;
-    readonly parentTraceContext: Parameters<typeof buildSubagentRunInput>[0]["parentTraceContext"];
-    readonly activityObserver?: ActivityObserverConfig & {
-        readonly workIdentity: ActivityWorkIdentityV1;
-    };
-    readonly sandboxSessionId: string;
-    readonly serializedContext: Record<string, unknown>;
-    readonly plan: readonly DispatchPlanEntry[];
-    readonly session: RuntimeSession;
-}
-interface PreparedPendingRuntimeActionDispatch extends PreparedRuntimeActionDispatch {
-    /** Returns the durable baseline corresponding to `session`. */
-    readonly getBaselineSessionState: () => DurableSessionState;
-}
-/**
- * Runs every dispatch precondition that may throw — durable reads, context
- * deserialization, handle-store validation, and batch planning — before
- * the caller acquires the parent stream writer, so a preflight failure
- * never leaks the writer lock. Returns undefined when no actions are
- * pending.
- */
-export declare function prepareRuntimeActionDispatch(input: {
-    readonly serializedContext: Record<string, unknown>;
-    readonly sessionState: DurableSessionState;
-    /**
-     * Classify task-control calls as
-     * task-control plan entries. Only task mode plans them; in plain mode
-     * those calls fail as unsupported batch actions.
-     */
-    readonly taskControls: boolean;
-}): Promise<PreparedPendingRuntimeActionDispatch | undefined>;
-export declare function prepareAgentActionDispatch(input: {
-    readonly action: PendingAgentDispatchAction;
-    readonly ctx: AlsContext;
-    readonly event: {
-        readonly sequence: number;
-        readonly stepIndex: number;
-        readonly turnId: string;
-    };
-    readonly localFanoutSize: number;
-    readonly serializedContext: Record<string, unknown>;
-    readonly sessionState: DurableSessionState;
-}): Promise<PreparedRuntimeActionDispatch>;
-/**
- * Emits the parent `subagent.called` control-plane event for one adopted
- * child. Emission is observability, not control flow: a failure is logged
- * and swallowed, because a throw escaping the dispatch loop would durably
- * replay the step and re-dispatch children that already started.
- */
-export declare function emitSubagentCalled(input: {
-    readonly adapter: ChannelAdapter;
-    readonly adapterCtx: ChannelAdapterContext;
-    readonly batchEvent: {
-        readonly sequence: number;
-        readonly turnId: string;
-    };
-    readonly entry: Extract<DispatchPlanEntry, {
-        readonly kind: "resume" | "start";
-    }>;
-    readonly outcome: Extract<DispatchOutcome, {
-        readonly kind: "called";
-    }>;
-    readonly sessionId: string;
-    readonly writer: WritableStreamDefaultWriter<Uint8Array>;
-}): Promise<void>;
-export {};

package/dist/src/execution/dispatch-runtime-actions-shared.js

@@ -1 +0,0 @@
-import{createLogger,logError}from"#internal/logging.js";import{callAdapterEventHandler}from"#channel/adapter.js";import{ContextContainer}from"#context/container.js";import{ActivityObserverKey,AuthKey,CapabilitiesKey,ChannelInstrumentationKey,InitiatorAuthKey,ParentSessionKey,SandboxKey}from"#context/keys.js";import{createSubagentCalledEvent,encodeMessageStreamEvent,stampMessageStreamEvent}from"#protocol/message.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{workflowEntryReference}from"#execution/workflow-runtime.js";import{deriveRootTurnActivityWorkId}from"#execution/activity-work-id.js";import{getAgentHandleStore}from"#harness/handles/store.js";import{deserializeContext}from"#context/serialize.js";import{createDurableSessionState,readDurableSession}from"#execution/durable-session-store.js";import{getDynamicSubagentSelection}from"#context/dynamic-subagent-lifecycle.js";import{hydrateDurableSession}from"#execution/session.js";import{resolveEffectiveAgentRuntime}from"#execution/effective-agent-config.js";import{buildAdapterContext}from"#channel/adapter-context.js";import{withContextScope}from"#context/run-step.js";import"#execution/agent-handle-dispatch.js";import{assertUniqueRuntimeActionCallIds,getPendingRuntimeActionBatch,setPendingRuntimeActionBatch}from"#harness/runtime-actions.js";import{activeTurnId}from"#harness/active-turn-id.js";import{createRecursiveAgentRootOnlyResult,createUnavailableDynamicSubagentResult,getSubagentName}from"#execution/dispatch-action-failures.js";import"#execution/subagent-tool.js";import{readSessionTraceContext}from"#tracing/agent-trace-context-store.js";import{isSubagentDelegationAction,resolveSubagentDepth}from"#harness/subagent-depth.js";import{isTaskControlAction}from"#execution/tasks/parent/dispatch.js";import{isWorkflowToolAction}from"#execution/tool-run/dispatch.js";import{resolvePreparedAgentAction}from"#execution/prepared-agent-action.js";const log=createLogger(`execution.dispatch-runtime-actions`);async function prepareRuntimeActionDispatch(e){let t=await readDurableSession(e.sessionState),n=getPendingRuntimeActionBatch(t.state);if(n===void 0||n.actions.length===0)return;let r=n.event.turnId||activeTurnId(e.sessionState.emissionState),i=n.event.turnId!==r,a=i?{...n,event:{...n.event,turnId:r}}:n,o=await prepareActionDispatch({batch:a,ctx:await deserializeContext(e.serializedContext),durableSession:t,serializedContext:e.serializedContext,taskControls:e.taskControls});if(!i)return{...o,getBaselineSessionState:()=>e.sessionState};let s=setPendingRuntimeActionBatch({...a,session:o.session});return{...o,getBaselineSessionState:()=>createDurableSessionState({session:s}),session:s}}async function prepareAgentActionDispatch(e){let t=await readDurableSession(e.sessionState);return await prepareActionDispatch({batch:{actions:[e.action],event:e.event,responseMessages:[]},ctx:copyDurableContext(e.ctx),durableSession:t,fanoutSize:e.localFanoutSize,serializedContext:e.serializedContext,taskControls:!1})}function copyDurableContext(e){let t=new ContextContainer;for(let[n,r]of e.entries())t.set(n,r);return t}async function prepareActionDispatch(e){let{batch:t,durableSession:n}=e;assertUniqueRuntimeActionCallIds(t.actions);let r=e.ctx,c=r.require(BundleKey),l=resolveEffectiveAgentRuntime(c,r),u=hydrateDurableSession({compactionOverrides:{thresholdPercent:l.thresholdPercent},durable:n,turnAgent:l.turnAgent}),d=r.require(ChannelKey);getAgentHandleStore(n.state);let f=planDispatch({actions:t.actions,bundle:c,ctx:r,session:u,taskControls:e.taskControls}),p=resolveActiveSandboxSessionId(d.state,u.sessionId);if(planSharesSandbox({bundle:c,plan:f}))try{u=(await withContextScope(r,u,async e=>(await r.require(SandboxKey).get(),{result:void 0,session:e}))).session}finally{r.clearVirtualContext()}return{adapter:d,adapterCtx:buildAdapterContext(d,r),auth:r.get(AuthKey)??null,batch:t,bundle:c,capabilities:r.get(CapabilitiesKey),channelMetadata:r.get(ChannelInstrumentationKey),fanoutSize:e.fanoutSize??f.filter(e=>e.kind===`start`&&e.target.kind===`local`).length,initiatorAuth:r.get(InitiatorAuthKey)??null,localDevRequest:r.localDevRequest,parentSession:r.get(ParentSessionKey),parentTraceContext:readSessionTraceContext(e.serializedContext,u.sessionId),plan:f,activityObserver:resolvePreparedActivity(r.get(ActivityObserverKey),u,t.event.turnId),sandboxSessionId:p,serializedContext:e.serializedContext,session:u}}function resolvePreparedActivity(e,t,n){if(e!==void 0)return{sink:e.sink,workIdentity:e.workIdentity??{id:deriveRootTurnActivityWorkId({sessionId:t.sessionId,turnId:n}),kind:`root-turn`,rootSessionId:t.rootSessionId??t.sessionId,rootTurnId:n,sessionId:t.sessionId,turnId:n}}}function planSharesSandbox(e){let t=e.bundle.graph;return e.plan.some(e=>e.kind!==`start`||e.target.kind!==`local`?!1:e.target.selfAgent||t?.nodesByNodeId.get(e.target.action.nodeId)?.sandboxRegistry.sandbox.definition.inheritsParent===!0)}function resolveActiveSandboxSessionId(e,t){if(typeof e!=`object`||!e)return t;let n=e.sandboxSessionId;return typeof n==`string`&&n.length>0?n:t}async function emitSubagentCalled(e){let{entry:r,outcome:i}=e;try{let t=r.kind===`resume`?r.action:r.target.action,a=r.kind===`resume`?r.dynamicRemoteAgent:r.target.kind===`remote`?r.target.dynamicRemoteAgent:void 0,o=await callAdapterEventHandler(e.adapter,createSubagentCalledEvent({callId:i.callId,childSessionId:i.address.sessionId,name:i.name,remote:i.address.kind===`agent/remote`?{resolverId:a===void 0?t.nodeId:a.credentialsStepId,url:i.address.url}:void 0,sequence:e.batchEvent.sequence,sessionId:e.sessionId,toolName:i.toolName,turnId:e.batchEvent.turnId,workflowId:workflowEntryReference.workflowId}),e.adapterCtx);await e.writer.write(encodeMessageStreamEvent(stampMessageStreamEvent(o)))}catch(e){logError(log,`subagent.called emission failed`,e,{callId:i.callId,childSessionId:i.address.sessionId,toolName:i.toolName})}}function planDispatch(e){let t=getAgentHandleStore(e.session.state)?.handles??[];return e.actions.map(n=>{if(e.taskControls&&isTaskControlAction(n))return{action:n,kind:`task-control`};if(isWorkflowToolAction(n))return{action:n,kind:`workflow-tool`};if(!isSubagentDelegationAction(n))throw Error(`Unsupported prepared dispatch target "${n.target.kind}" in workflow runtime.`);let r=resolvePreparedAgentAction(n),i=n.input.agentId,a=typeof i==`string`&&i.trim()!==``?i:void 0;if(a!==void 0){if(t.some(e=>e.identity.id===a)){let t=e.bundle.subagentRegistry.dynamicNodeIds?.has(r.action.nodeId)===!0?getDynamicSubagentSelection(e.ctx,r.action.nodeId):void 0;return{action:r.action,agentId:a,dynamicRemoteAgent:r.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:a,callId:n.callId})}return classifyFreshStart({action:r.action,bundle:e.bundle,ctx:e.ctx,selfAgent:r.selfAgent,session:e.session})})}function classifyFreshStart(e){let{action:t}=e,n=e.bundle.subagentRegistry.subagentsByNodeId,r=resolveSubagentDepth(e.session),i=e.session.rootSessionId!==void 0||r.currentDepth>0,a=(t.kind===`subagent-call`||t.kind===`remote-agent-call`)&&e.bundle.subagentRegistry.dynamicNodeIds?.has(t.nodeId)===!0,o=a?getDynamicSubagentSelection(e.ctx,t.nodeId):void 0;if(a&&(o===void 0||t.kind===`subagent-call`&&o.kind!==`subagent`||t.kind===`remote-agent-call`&&o.kind!==`remote`)){let e=getSubagentName(t);return log.warn(`dynamic subagent call blocked after availability changed`,{callId:t.callId,nodeId:t.nodeId,subagentName:e}),{kind:`reject`,result:createUnavailableDynamicSubagentResult(t)}}if(e.selfAgent&&t.kind!==`subagent-call`)throw Error(`A self-agent dispatch target must resolve to a local subagent action.`);if(e.selfAgent&&i&&t.kind===`subagent-call`)return log.warn(`recursive agent call blocked outside the root session`,{callId:t.callId,currentDepth:r.currentDepth,nodeId:t.nodeId,subagentName:t.subagentName}),{kind:`reject`,result:createRecursiveAgentRootOnlyResult(t)};switch(t.kind){case`subagent-call`:{let r=o?.kind===`subagent`?o.agentConfig:void 0,i=n.get(t.nodeId),a=r?.description??(i?.definition.kind===`subagent`?i.definition.description:void 0),s=a===void 0?{outputSchema:e.bundle.turnAgent.outputSchema,type:`runtime`}:{description:a,outputSchema:r?.outputSchema??e.bundle.graph?.nodesByNodeId.get(t.nodeId)?.turnAgent?.outputSchema,type:`local`};return{kind:`start`,target:{action:t,dynamicSubagentAgentConfig:r,kind:`local`,selfAgent:e.selfAgent,source:s}}}case`remote-agent-call`:return{kind:`start`,target:{action:t,dynamicRemoteAgent:o?.kind===`remote`?o.remoteAgent:void 0,kind:`remote`}};default:return t}}export{emitSubagentCalled,prepareAgentActionDispatch,prepareRuntimeActionDispatch};