eve 0.55.0 → 0.56.0

package/docs/tools/workflows.mdx

@@ -99,7 +99,62 @@ workflow and step modules reachable from the agent's runtime modules. Unrelated
 in the host application stay outside the agent bundle. An unresolved workflow import fails
 the build with the missing import in the error.
 
-### Migrate an existing workflow tool
+### Add a runtime-generated workflow tool
+
+Create `agent/tools/workflow.ts` and export the provided `workflow` factory when the model should
+supply the JavaScript program at runtime:
+
+```ts title="agent/tools/workflow.ts"
+import { workflow } from "eve/tools/workflow";
+
+export default workflow({ maxSubagents: 20 });
+```
+
+The model supplies an async function body through the tool's `js` input. Its only host capability is
+`ctx.agent(name, { message, agentId?, outputSchema? })`. For example:
+
+```js
+const [triage, review] = await Promise.all([
+  ctx.agent("ticket-triage", { message: JSON.stringify(tickets) }),
+  ctx.agent("ticket-review", { message: JSON.stringify(tickets) }),
+]);
+return { triage, review };
+```
+
+`maxSubagents` defaults to `100` and must be an integer from `1` through `128`. The generated
+program cannot access the workflow context, session state,
+credentials, imports, or ordinary tools. Agent authorization, questions, approvals, cancellation,
+and `agentId` continuation use the same owner-managed behavior as direct `ctx.agent` calls.
+
+The sandbox resumes after every pending call in the current batch settles. `Promise.all` supports
+fan-out followed by fan-in, but `Promise.race` does not resume after only the first child settles.
+A child failure is thrown at the corresponding `ctx.agent` call, so generated code can catch it.
+The program must return a JSON-serializable value.
+
+### Migrate from `experimental_workflow`
+
+The experimental uppercase `Workflow` framework tool and its exports have been removed. Replace the
+old sentinel:
+
+```diff
+-import { experimental_workflow } from "eve/tools/workflow";
+-
+-export default experimental_workflow({ maxSubagents: 20 });
+```
+
+with the lowercase factory:
+
+```ts
+import { workflow } from "eve/tools/workflow";
+
+export default workflow({ maxSubagents: 20 });
+```
+
+The path gives the authored tool the model-facing name `workflow`. eve does not discover or inject
+an agent catalog. Calls use the same target resolution, availability, and authorization checks as
+`ctx.agent` in any other authored workflow tool.
+
+### Migrate an authored workflow tool
 
 Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workflow"` directive,
 and replace `agent(ctx, input)` and `ask(ctx, request)` with `ctx.agent(target, input)` and

package/package.json

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

package/dist/src/cli/commands/registry-package.d.ts

@@ -1,52 +0,0 @@
-import { type RegistryConfig } from "#compiled/shadcn-registry/index.js";
-import { z } from "#compiled/zod/index.js";
-import { type Prompter } from "#setup/prompter.js";
-import type { RegistrySetupCompletion } from "#setup/registry-setup-protocol.js";
-import type { AddCommandOptions, RegistryCommandLogger } from "./registry.js";
-import { type DeclaredPnpmBuildPolicy } from "./registry-pnpm-build-policy-flow.js";
-import type { RegistrySetupCommand } from "./registry-setup-command.js";
-export declare const RegistryPackageComponentSchema: z.ZodObject<{
-    item: z.ZodString;
-    label: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    default: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-export type RegistryPackageComponent = z.infer<typeof RegistryPackageComponentSchema>;
-interface PackageMetadata {
-    requires?: string;
-    install?: {
-        pnpm?: {
-            buildScripts: readonly DeclaredPnpmBuildPolicy[];
-        };
-    };
-    setup?: RegistrySetupCommand[];
-}
-export interface RegistryPackageDependencies {
-    createPrompter?: () => Prompter;
-    hasInteractiveTerminal?: () => boolean;
-}
-export interface RegistryPackageOperations {
-    itemAddress(item: string): string;
-    metadata(item: unknown): PackageMetadata | undefined;
-    assertCompatibleVersion(requiredVersion: string | undefined): void;
-    runSetups(input: {
-        item: string;
-        setups: RegistrySetupCommand[];
-        prompter: Prompter;
-    }): Promise<RegistrySetupCompletion | false>;
-    setupReminder(item: string): string;
-}
-export declare function runRegistryPackage(input: {
-    logger: RegistryCommandLogger;
-    appRoot: string;
-    item: string;
-    components: readonly RegistryPackageComponent[];
-    config: RegistryConfig;
-    options: AddCommandOptions & {
-        prompter?: Prompter;
-        signal?: AbortSignal;
-    };
-    dependencies: RegistryPackageDependencies;
-    operations: RegistryPackageOperations;
-}): Promise<RegistrySetupCompletion | false>;
-export {};

package/dist/src/cli/commands/registry-package.js

@@ -1 +0,0 @@
-import{hasInteractiveTerminal}from"./preconditions.js";import{headlessSetupContinuation,serializeHeadlessSetupEvent}from"./setup-headless.js";import{prepareDeclaredPnpmBuildPolicy}from"./registry-pnpm-build-policy-flow.js";import{z}from"#compiled/zod/index.js";import{createPrompter}from"#setup/prompter.js";import{headlessAsker,interactiveAsker,withAnswers,withPolicy}from"#setup/ask.js";import{mergeRegistrySetupCompletions}from"#setup/registry-setup-completion.js";import{addRegistryItems,getRegistryItems}from"#compiled/shadcn-registry/index.js";const RegistryPackageComponentSchema=z.object({item:z.string().min(1),label:z.string().min(1),description:z.string().optional(),default:z.boolean().default(!1)});async function selectComponents(e,t,n,r,i,a){if(r.prompter===void 0&&!r.nonInteractive&&(r.yes===!0||!i))return n.filter(e=>e.default);let o={key:`components`,message:`Add ${t}`,required:!0,recommended:n.filter(e=>e.default),options:n.map(e=>({id:e.item,value:e,label:e.label,hint:e.description}))},s=r.nonInteractive?withAnswers(r.answers??{})(r.yes?withPolicy(`assume`)(headlessAsker()):headlessAsker()):interactiveAsker(a());try{return await s.askMany(o)}catch(n){if(!r.nonInteractive||!(n instanceof Error)||n.name!==`InteractionRequired`)throw n;let i=n.question,{setupQuestionToWire:a}=await import(`#setup/setup-question-wire.js`),o=a(i);e.error(serializeHeadlessSetupEvent({version:1,type:`blocked`,status:`input_required`,item:t,installed:!1,completedItems:[],question:o,next:headlessSetupContinuation({item:t,installed:!1,answers:r.answers,question:o})})),process.exitCode=2;return}}async function runRegistryPackage(e){let{logger:t,appRoot:n,item:r,components:i,config:a,options:o,dependencies:s,operations:c}=e,l=s.hasInteractiveTerminal?.()??hasInteractiveTerminal(),u=o.prompter,getPrompter=()=>u??=s.createPrompter?.()??createPrompter(),d=await selectComponents(t,r,i,o,l,getPrompter);if(d===void 0)return!1;let f=d.map(e=>c.itemAddress(e.item)),p=await getRegistryItems(f,{config:a});if(p.length!==d.length)throw Error(`Registry package "${r}" could not resolve all selected components.`);let m=p.map(e=>{let t=c.metadata(e);return c.assertCompatibleVersion(t?.requires),t});if(o.skipInstall!==!0&&!await prepareDeclaredPnpmBuildPolicy({logger:t,appRoot:n,item:r,policies:m.flatMap(e=>e?.install?.pnpm?.buildScripts??[]),options:o}))return!1;o.skipInstall!==!0&&await addRegistryItems(f,{config:a,cwd:n,overwrite:o.overwrite,silent:o.silent});let h={facts:[]};if(o.skipSetup===!0)return h;if(!o.nonInteractive&&o.yes!==!0&&o.prompter===void 0&&!l)return t.log(c.setupReminder(r)),h;for(let e of m){if(e?.setup===void 0)continue;let t=await c.runSetups({item:r,setups:e.setup,prompter:getPrompter()});if(t===!1)return!1;h=mergeRegistrySetupCompletions(h,t)}return h}export{RegistryPackageComponentSchema,runRegistryPackage};

package/dist/src/harness/workflow-continuation-security.d.ts

@@ -1,5 +0,0 @@
-import type { HarnessSession } from "#harness/types.js";
-import type { WorkflowSandboxContinuationSecurity } from "#shared/workflow-sandbox.js";
-export declare function ensureWorkflowContinuationSecurity(session: HarnessSession): HarnessSession;
-export declare function readWorkflowContinuationSecurity(session: HarnessSession): WorkflowSandboxContinuationSecurity | undefined;
-export declare function getWorkflowContinuationSecurity(session: HarnessSession): WorkflowSandboxContinuationSecurity;

package/dist/src/harness/workflow-continuation-security.js

@@ -1 +0,0 @@
-import{randomBytes}from"node:crypto";const WORKFLOW_CONTINUATION_SECURITY_KEY=`eve.harness.workflowContinuationSecurity`;function ensureWorkflowContinuationSecurity(e){return e.state?.[WORKFLOW_CONTINUATION_SECURITY_KEY]===void 0?{...e,state:{...e.state,[WORKFLOW_CONTINUATION_SECURITY_KEY]:{signingKey:randomBytes(32).toString(`base64url`),version:1}}}:(getWorkflowContinuationSecurity(e),e)}function readWorkflowContinuationSecurity(e){let t=e.state?.[WORKFLOW_CONTINUATION_SECURITY_KEY];if(typeof t==`object`&&t&&t.version===1&&typeof t.signingKey==`string`&&/^[A-Za-z0-9_-]{43}$/.test(t.signingKey))return{signingKey:t.signingKey,maxAgeMs:31536e6}}function getWorkflowContinuationSecurity(e){let t=readWorkflowContinuationSecurity(e);if(t===void 0)throw Error(`Workflow continuation security state is missing or invalid.`);return t}export{ensureWorkflowContinuationSecurity,getWorkflowContinuationSecurity,readWorkflowContinuationSecurity};

package/dist/src/harness/workflow-interrupt-state.d.ts

@@ -1,20 +0,0 @@
-import type { ModelMessage } from "ai";
-import type { HarnessSession, SessionStateMap } from "#harness/types.js";
-import type { WorkflowSandboxInterrupt } from "#shared/workflow-sandbox.js";
-export interface PendingWorkflowInterrupt {
-    readonly interrupt: WorkflowSandboxInterrupt;
-    readonly responseMessages: readonly ModelMessage[];
-    readonly usedCalls: number;
-}
-export declare function getPendingWorkflowInterrupt(state: SessionStateMap | undefined): PendingWorkflowInterrupt | undefined;
-export declare function setPendingWorkflowInterrupt(input: {
-    readonly interrupt: WorkflowSandboxInterrupt;
-    readonly responseMessages: readonly ModelMessage[];
-    readonly session: HarnessSession;
-    readonly usedCalls: number;
-}): HarnessSession;
-export declare function setPendingWorkflowUsedCalls(input: {
-    readonly session: HarnessSession;
-    readonly usedCalls: number;
-}): HarnessSession;
-export declare function clearPendingWorkflowInterrupt(session: HarnessSession): HarnessSession;

package/dist/src/harness/workflow-interrupt-state.js

@@ -1 +0,0 @@
-import{WORKFLOW_TASK_INTERRUPT_KIND}from"#harness/workflow-task-state.js";const PENDING_KEY=`eve.harness.pendingWorkflowInterrupt`;function getPendingWorkflowInterrupt(e){let t=e?.[PENDING_KEY];if(isRecord(t)&&isWorkflowInterruptShape(t.interrupt)&&Array.isArray(t.responseMessages)&&!(!Number.isSafeInteger(t.usedCalls)||t.usedCalls<0))return{interrupt:t.interrupt,responseMessages:t.responseMessages,usedCalls:t.usedCalls}}function setPendingWorkflowInterrupt(e){return{...e.session,state:{...e.session.state,[PENDING_KEY]:{interrupt:e.interrupt,responseMessages:e.responseMessages,usedCalls:e.usedCalls}}}}function setPendingWorkflowUsedCalls(e){let t=getPendingWorkflowInterrupt(e.session.state);return t===void 0?e.session:setPendingWorkflowInterrupt({...t,session:e.session,usedCalls:e.usedCalls})}function clearPendingWorkflowInterrupt(e){if(e.state?.[PENDING_KEY]===void 0)return e;let t={...e.state};return delete t[PENDING_KEY],{...e,state:Object.keys(t).length>0?t:void 0}}function isWorkflowInterruptShape(e){return isRecord(e)&&e.type===`code-mode-interrupt`&&typeof e.interruptId==`string`&&typeof e.outerToolCallId==`string`&&isRecord(e.payload)&&e.payload.kind===WORKFLOW_TASK_INTERRUPT_KIND&&isRecord(e.continuation)&&e.continuation.version===2&&typeof e.continuation.outerToolCallId==`string`&&Array.isArray(e.continuation.pendingInterruptions)&&Array.isArray(e.continuation.resolutions)}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{clearPendingWorkflowInterrupt,getPendingWorkflowInterrupt,setPendingWorkflowInterrupt,setPendingWorkflowUsedCalls};

package/dist/src/harness/workflow-lifecycle.d.ts

@@ -1,32 +0,0 @@
-import type { HarnessEmissionState } from "#harness/emission.js";
-import type { HarnessEmitFn, HarnessToolMap } from "#harness/types.js";
-import type { WorkflowSandboxInterrupt } from "#shared/workflow-sandbox.js";
-export declare function createWorkflowLifecycle(input: {
-    readonly emit: EmitWorkflowLifecycleEvent;
-    readonly emissionState: HarnessEmissionState;
-    readonly skipReplayed?: boolean;
-    readonly tools: HarnessToolMap;
-}): {
-    onAfterExecute?: (input: {
-        readonly result: unknown;
-    }) => Promise<void>;
-};
-type EmitWorkflowLifecycleEvent = HarnessEmitFn;
-/** Projects newly parked workflow calls onto eve's existing action stream. */
-export declare function emitWorkflowActionsRequested(input: {
-    readonly emit: EmitWorkflowLifecycleEvent;
-    readonly emissionState: HarnessEmissionState;
-    readonly interrupts: readonly WorkflowSandboxInterrupt[];
-    readonly tools: HarnessToolMap;
-}): Promise<void>;
-/** Projects completed workflow children before replaying their continuation. */
-export declare function emitWorkflowActionResults(input: {
-    readonly emit: EmitWorkflowLifecycleEvent;
-    readonly emissionState: HarnessEmissionState;
-    readonly interrupts: readonly WorkflowSandboxInterrupt[];
-    readonly results: readonly {
-        readonly isError?: boolean;
-        readonly output?: unknown;
-    }[];
-}): Promise<void>;
-export {};

package/dist/src/harness/workflow-lifecycle.js

@@ -1 +0,0 @@
-import{createActionResultEvent,createActionsRequestedEvent}from"#protocol/message.js";import{collectActionPresentation,createPresentedRuntimeActionRequestFromToolCall}from"#harness/action-presentation.js";import{createRuntimeToolResultFromValue}from"#harness/action-result-helpers.js";import{getWorkflowSandboxInterrupt}from"#shared/workflow-sandbox.js";function createWorkflowLifecycle(e){return{async onAfterExecute(t){if(e.skipReplayed)return;let n=await getWorkflowSandboxInterrupt(t.result,{});n!==void 0&&await emitWorkflowActionsRequested({emit:e.emit,emissionState:e.emissionState,interrupts:[n],tools:e.tools})}}}async function emitWorkflowActionsRequested(e){for(let t of e.interrupts){let n={input:t.input,toolCallId:t.toolCallId,toolName:t.toolName,type:`tool-call`},r=createPresentedRuntimeActionRequestFromToolCall({toolCall:n,tools:e.tools});await e.emit(createActionsRequestedEvent({actions:[r.action],presentation:collectActionPresentation([r]),sequence:e.emissionState.sequence,stepIndex:e.emissionState.stepIndex,turnId:e.emissionState.turnId}))}}async function emitWorkflowActionResults(e){for(let[t,n]of e.results.entries()){let r=e.interrupts[t];if(r===void 0)break;await e.emit(createActionResultEvent({result:createRuntimeToolResultFromValue({callId:r.toolCallId,isError:n.isError,output:n.output,toolName:r.toolName}),sequence:e.emissionState.sequence,stepIndex:e.emissionState.stepIndex,turnId:e.emissionState.turnId}))}}export{createWorkflowLifecycle,emitWorkflowActionResults,emitWorkflowActionsRequested};

package/dist/src/harness/workflow-sandbox.d.ts

@@ -1,28 +0,0 @@
-import type { ToolSet } from "ai";
-import type { HarnessToolMap } from "#harness/types.js";
-import { type WorkflowSandboxContinuationSecurity } from "#shared/workflow-sandbox.js";
-interface WorkflowToolSet {
-    readonly hostTools: ToolSet;
-    readonly modelTools: ToolSet;
-}
-/**
- * Adds the dynamic `Workflow` tool while leaving every ordinary model tool
- * untouched. Only workflow-callable delegation tasks enter the sandbox.
- */
-export declare function applyWorkflowTool(input: {
-    readonly continuationSecurity: WorkflowSandboxContinuationSecurity;
-    readonly harnessTools: HarnessToolMap;
-    readonly maxSubagents?: number;
-    readonly tools: ToolSet;
-}): Promise<WorkflowToolSet>;
-/**
- * Keeps code mode's bridge capacity strictly above eve's dispatch budget.
- * The extra request lets the first over-budget call resolve through eve's
- * `WORKFLOW_SUBAGENT_LIMIT_REACHED` result instead of failing the sandbox.
- */
-export declare function resolveWorkflowSandboxBridgeRequestLimit(maxSubagents?: number): number;
-/** Rebuilds the subagent-only host surface used to resume a parked workflow. */
-export declare function buildWorkflowHostTools(input: {
-    readonly tools: HarnessToolMap;
-}): ToolSet;
-export {};

package/dist/src/harness/workflow-sandbox.js

@@ -1,2 +0,0 @@
-import{z}from"#compiled/zod/index.js";import{DEFAULT_WORKFLOW_MAX_SUBAGENTS}from"#harness/workflow-subagent-limit.js";import{WORKFLOW_TASK_INTERRUPT_KIND}from"#harness/workflow-task-state.js";import{WORKFLOW_TOOL_NAME,createWorkflowSandboxTool,readWorkflowSandboxResolution,requestWorkflowSandboxInterrupt}from"#shared/workflow-sandbox.js";import{workflowToolDescription}from"#harness/workflow-tool-description.js";const workflowInputSchema=z.strictObject({js:z.string().describe(`Complete JavaScript orchestration program. Call only the agents listed in the Workflow description and return one JSON-serializable result.`)});async function applyWorkflowTool(e){let t=createWorkflowHostTools(e.harnessTools,Object.keys(e.tools));if(Object.keys(t).length===0)return{hostTools:t,modelTools:e.tools};let n=await createWorkflowSandboxTool({bridgeRequestLimit:resolveWorkflowSandboxBridgeRequestLimit(e.maxSubagents),continuationSecurity:e.continuationSecurity,hostTools:t}),r=typeof n.description==`string`?n.description:``,i=workflowToolDescription(Object.keys(t),{maxSubagents:e.maxSubagents}),a=workflowApiReference(r),o={...e.tools};return o[WORKFLOW_TOOL_NAME]={...n,description:a.length>0?`${i}\n\n${a}`:i,inputSchema:workflowInputSchema},{hostTools:t,modelTools:o}}function resolveWorkflowSandboxBridgeRequestLimit(e){return Math.max(256,(e??DEFAULT_WORKFLOW_MAX_SUBAGENTS)+1)}function workflowApiReference(e){let t=e.indexOf(`Tools:
-`);return t<0?e:`Available agent API:\n${e.slice(t+7)}`}function buildWorkflowHostTools(e){return createWorkflowHostTools(e.tools,e.tools.keys())}function createWorkflowHostTools(e,t){let n={};for(let r of t){let t=e.get(r);t?.workflowId!==void 0&&(n[r]=createWorkflowTaskHostTool(t))}return n}function createWorkflowTaskHostTool(e){return{description:e.description,inputSchema:e.inputSchema,execute:async(t,n)=>{let r=readWorkflowSandboxResolution(n);return r===void 0?requestWorkflowSandboxInterrupt({kind:WORKFLOW_TASK_INTERRUPT_KIND,task:{executeInput:e.executeInput?.(t),nodeId:e.nodeId,resultKind:e.resultKind,workflowId:e.workflowId},toolInput:t,toolName:e.name}):r}}}export{applyWorkflowTool,buildWorkflowHostTools,resolveWorkflowSandboxBridgeRequestLimit};

package/dist/src/harness/workflow-subagent-limit.d.ts

@@ -1,28 +0,0 @@
-import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
-/**
- * Default maximum number of subagent (and remote-agent) calls one `Workflow`
- * tool invocation may dispatch.
- */
-export declare const DEFAULT_WORKFLOW_MAX_SUBAGENTS = 100;
-/**
- * Partition of one workflow interrupt's pending tasks against the invocation's
- * subagent budget. Allowed tasks may dispatch; blocked tasks resolve with an
- * error result instead of starting a child.
- */
-export type WorkflowSubagentDispatchPlan = {
-    readonly allowed: readonly RuntimeWorkflowTaskRequest[];
-    readonly blocked: readonly RuntimeWorkflowTaskRequest[];
-    readonly maxSubagents: number;
-    readonly usedCalls: number;
-};
-/**
- * Splits the pending actions of one workflow interrupt into the prefix that
- * still fits the invocation's `maxSubagents` budget and the remainder that
- * must be blocked. Actions keep request order so results pair with the sandbox
- * program's call order.
- */
-export declare function planWorkflowSubagentDispatch(input: {
-    readonly tasks: readonly RuntimeWorkflowTaskRequest[];
-    readonly maxSubagents?: number;
-    readonly usedCalls: number;
-}): WorkflowSubagentDispatchPlan;

package/dist/src/harness/workflow-subagent-limit.js

@@ -1 +0,0 @@
-const DEFAULT_WORKFLOW_MAX_SUBAGENTS=100;function planWorkflowSubagentDispatch(e){let t=e.maxSubagents??100,n=e.usedCalls,r=Math.max(0,t-n),i=[],a=[];for(let t of e.tasks)t.resultKind===`subagent`?r>0?(i.push(t),r--):a.push(t):i.push(t);return{allowed:i,blocked:a,maxSubagents:t,usedCalls:n}}export{DEFAULT_WORKFLOW_MAX_SUBAGENTS,planWorkflowSubagentDispatch};

package/dist/src/harness/workflow-task-state.d.ts

@@ -1,9 +0,0 @@
-import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
-import { type WorkflowSandboxInterrupt } from "#shared/workflow-sandbox.js";
-export declare const WORKFLOW_TASK_INTERRUPT_KIND = "eve.workflow-task";
-export declare function isWorkflowTaskInterrupt(interrupt: unknown): boolean;
-export declare function buildWorkflowTaskFromInterrupt(interrupt: WorkflowSandboxInterrupt): RuntimeWorkflowTaskRequest;
-/** Returns every pending workflow-task interrupt in deterministic ledger order. */
-export declare function getWorkflowTaskInterrupts(interrupt: WorkflowSandboxInterrupt): WorkflowSandboxInterrupt[];
-export declare function buildWorkflowTasksFromInterrupt(interrupt: WorkflowSandboxInterrupt): RuntimeWorkflowTaskRequest[];
-export declare function getWorkflowTaskCallIds(interrupt: WorkflowSandboxInterrupt): string[];

package/dist/src/harness/workflow-task-state.js

@@ -1 +0,0 @@
-import{getWorkflowSandboxPendingInterrupts}from"#shared/workflow-sandbox.js";const WORKFLOW_TASK_INTERRUPT_KIND=`eve.workflow-task`;function isWorkflowTaskInterrupt(e){return isRecord(e)&&isRecord(e.payload)&&e.payload.kind===`eve.workflow-task`}function buildWorkflowTaskFromInterrupt(e){let t=e.payload,n=t.task,r=t.toolInput,i=t.toolName,a=sanitizeCallId(`${i}_${`interruptId`in e?String(e.interruptId):``}`);if(n===void 0||typeof n.workflowId!=`string`)throw Error(`Workflow delegation interrupts require a workflow task.`);let o={callId:a,executeInput:n.executeInput,input:r,kind:`workflow-task`,resultKind:n.resultKind,toolName:i,workflowId:n.workflowId};return n.nodeId!==void 0&&(o.nodeId=n.nodeId),o}function getWorkflowTaskInterrupts(e){return getWorkflowSandboxPendingInterrupts(e).filter(isWorkflowTaskInterrupt)}function buildWorkflowTasksFromInterrupt(e){return getWorkflowTaskInterrupts(e).map(e=>buildWorkflowTaskFromInterrupt(e))}function getWorkflowTaskCallIds(e){return buildWorkflowTasksFromInterrupt(e).map(e=>e.callId)}function sanitizeCallId(e){return e.replace(/[^a-zA-Z0-9_-]/g,`_`)}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{WORKFLOW_TASK_INTERRUPT_KIND,buildWorkflowTaskFromInterrupt,buildWorkflowTasksFromInterrupt,getWorkflowTaskCallIds,getWorkflowTaskInterrupts,isWorkflowTaskInterrupt};

package/dist/src/harness/workflow-tool-description.d.ts

@@ -1,22 +0,0 @@
-/**
- * Builds the model-facing description for the `Workflow` orchestration tool.
- *
- * Dynamic in the agent's callable agents:
- * - lists every callable agent by name (the built-in `agent` plus one per
- *   declared subagent and remote agent);
- * - the worked example uses only the built-in `agent`, so it is valid for any
- *   agent;
- * - a single simple subagent example is appended *only when* the agent has a
- *   declared subagent or remote agent (i.e. an agent other than `agent`).
- *
- * The sandbox package's generated input signatures are appended after this
- * framing.
- *
- * @param toolNames - Names of the agent functions callable inside the sandbox.
- * @param options - `maxSubagents`: the invocation's subagent-call budget
- *   (defaults to {@link DEFAULT_WORKFLOW_MAX_SUBAGENTS}), surfaced so the
- *   model sizes its fan-out to fit.
- */
-export declare function workflowToolDescription(toolNames: readonly string[], options?: {
-    readonly maxSubagents?: number;
-}): string;

package/dist/src/harness/workflow-tool-description.js

@@ -1,37 +0,0 @@
-import{DEFAULT_WORKFLOW_MAX_SUBAGENTS}from"#harness/workflow-subagent-limit.js";function workflowToolDescription(e,t){let n=t?.maxSubagents??DEFAULT_WORKFLOW_MAX_SUBAGENTS,r=e.length>0?e:[`agent`],i=r.map(e=>`\`${e}\``).join(`, `),a=r.filter(e=>e!==`agent`),o=a.length>0?`\n\nDeclared subagents use the same API — e.g. \`const note = await ${agentAccess(a[0])}({ message: "..." });\`.`:``;return`Use \`Workflow\` when a task needs JavaScript to coordinate multiple child-agent calls as one durable step. It is an orchestration tool, not a general-purpose tool runner.
-
-Use \`Workflow\` for:
-- fan-out or map-reduce over a list, especially when the number of calls comes from runtime data;
-- dependent pipelines where one agent's result becomes another agent's input;
-- conditional branches or follow-up calls chosen from earlier results;
-- deterministic filtering, sorting, or aggregation of several agent results before returning one value.
-
-Do not use \`Workflow\` when:
-- one delegation, or a small fixed set of unrelated delegations, can be called directly;
-- no child-agent call is needed;
-- the task needs files, network, shell, connections, skills, or ordinary tools — none are available inside Workflow;
-- JavaScript would only wrap work the parent agent can express more clearly with direct calls.
-
-Workflow earns its overhead when code materially controls call count, concurrency, ordering, data flow, or aggregation. Put the complete orchestration in one JavaScript program and return the final JSON-serializable value.
-
-One Workflow program may dispatch at most ${String(n)} agent calls in total (sequential and parallel calls alike); calls beyond that budget fail with \`WORKFLOW_SUBAGENT_LIMIT_REACHED\` instead of running. Size fan-outs to fit the budget.
-
-The only callable operations are these agents — no filesystem, network, shell, or other tools: ${i}. Call them only through the \`tools\` object, using the exact member syntax in the API reference below. Each call is async and resolves to the child's result, or a typed object when you pass an \`outputSchema\`. Sequence with \`await\`, run agents concurrently with \`Promise.all([...])\`, and use \`map\`/\`filter\`/\`flatMap\` to build calls and combine results. The program's return value becomes the tool result.
-
-Example — fan out across areas with \`agent\`, then pipe the results into a synthesis step:
-\`\`\`js
-const areas = ["correctness", "security", "performance"];
-const reviews = await Promise.all(
-  areas.map((area) =>
-    tools.agent({
-      message: \`Review the change for \${area}.\`,
-      outputSchema: { type: "object", properties: { findings: { type: "array", items: { type: "string" } } } },
-    }),
-  ),
-);
-const verdict = await tools.agent({
-  message: \`Summarize these findings into a verdict: \${JSON.stringify(reviews)}\`,
-  outputSchema: { type: "object", properties: { verdict: { type: "string" }, blocking: { type: "boolean" } } },
-});
-return verdict;
-\`\`\`${o}`}function agentAccess(e){return/^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(e)?`tools.${e}`:`tools[${JSON.stringify(e)}]`}export{workflowToolDescription};

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

@@ -1,37 +0,0 @@
-declare const EXPERIMENTAL_WORKFLOW_TOOL_KIND = "eve:enable-workflow-tool";
-/** Configuration accepted by {@link experimental_workflow}. */
-export interface ExperimentalWorkflowToolInput {
-    /**
-     * Maximum number of subagent or remote-agent calls one `Workflow` program
-     * may dispatch, counted across sequential and parallel calls alike.
-     *
-     * Calls beyond the limit fail with a `WORKFLOW_SUBAGENT_LIMIT_REACHED`
-     * result instead of starting a child session.
-     *
-     * @default 100
-     */
-    readonly maxSubagents?: number;
-}
-/** Framework `Workflow` tool definition returned by {@link experimental_workflow}. */
-export interface ExperimentalWorkflowToolDefinition extends ExperimentalWorkflowToolInput {
-    readonly kind: typeof EXPERIMENTAL_WORKFLOW_TOOL_KIND;
-}
-/**
- * Enables and configures the experimental framework `Workflow` tool, an
- * isolated JavaScript sandbox whose only callable operations are this agent's
- * subagents and remote agents. Export the result from
- * `agent/tools/workflow.ts`:
- *
- * ```ts
- * import { experimental_workflow } from "eve/tools";
- *
- * export default experimental_workflow({ maxSubagents: 25 });
- * ```
- *
- * Only the root session sees the tool. The resulting model-facing tool is
- * still called `Workflow`.
- */
-export declare function experimental_workflow(input?: ExperimentalWorkflowToolInput): ExperimentalWorkflowToolDefinition;
-/** Type guard for a definition returned by {@link experimental_workflow}. */
-export declare function isExperimentalWorkflowToolDefinition(value: unknown): value is ExperimentalWorkflowToolDefinition;
-export {};

package/dist/src/tools/workflow.js

@@ -1 +0,0 @@
-const EXPERIMENTAL_WORKFLOW_TOOL_KIND=`eve:enable-workflow-tool`;function experimental_workflow(e={}){let t={kind:EXPERIMENTAL_WORKFLOW_TOOL_KIND};return e.maxSubagents!==void 0&&(t.maxSubagents=e.maxSubagents),t}function isExperimentalWorkflowToolDefinition(e){return typeof e==`object`&&!!e&&e.kind===EXPERIMENTAL_WORKFLOW_TOOL_KIND}export{experimental_workflow,isExperimentalWorkflowToolDefinition};

package/docs/guides/instrumentation-providers.md

@@ -1,249 +0,0 @@
----
-title: "Instrumentation Providers"
-description: "Configure the experimental instrumentation provider layout, control captured inputs and outputs, and redact OpenTelemetry spans before export."
----
-
-Instrumentation providers split observability into files under `agent/instrumentation/`. Each file can handle eve lifecycle events or add an OpenTelemetry destination without owning the rest of the telemetry pipeline.
-
-**This API is experimental and may change without a deprecation period.** Enable it explicitly in `agent.ts`:
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-sonnet-5",
-  experimental: {
-    instrumentationProviders: true,
-  },
-});
-```
-
-The provider directory replaces `agent/instrumentation.ts`; the two layouts cannot be used together. See [Observability](./instrumentation) for the default `instrumentation.ts` API.
-
-## Add a provider
-
-The filename identifies the provider slot. Each file must default-export `defineInstrumentation(...)`, an OpenTelemetry integration, or `disableInstrumentation()`.
-
-```text
-agent/instrumentation/
-  audit.ts       lifecycle event provider
-  braintrust.ts  OpenTelemetry destination
-  otel.ts        process-wide OpenTelemetry settings
-```
-
-This provider records action timing and identity without receiving tool arguments or results:
-
-```ts title="agent/instrumentation/audit.ts"
-import { defineInstrumentation } from "eve/instrumentation";
-
-export default defineInstrumentation({
-  events: {
-    "action.started": (event, ctx) => {
-      ctx.state.set({ name: event.name, startedAt: Date.now() });
-    },
-    "action.completed": (event, ctx) => {
-      const started = ctx.state.get() as { name: string; startedAt: number } | undefined;
-      if (started === undefined) return;
-
-      console.log({
-        action: started.name,
-        durationMs: Date.now() - started.startedAt,
-        outcome: event.outcome,
-      });
-    },
-  },
-});
-```
-
-`ctx.state` is JSON storage scoped to this provider and operation. It survives durable suspension and is released after the terminal event.
-
-## Control inputs and outputs
-
-Each provider has an independent `tracePolicy`. It decides whether the provider receives events and whether those events include input or output content.
-
-```ts title="agent/instrumentation/audit.ts"
-import { defineInstrumentation } from "eve/instrumentation";
-
-export default defineInstrumentation({
-  tracePolicy: ({ audience, environment }) => ({
-    emit: true,
-    recordInputs: audience === "public" || environment === "development",
-    recordOutputs: audience === "public" || environment === "development",
-  }),
-  events: {
-    "model.call.started": (event) => {
-      console.log("input", event.input);
-    },
-    "model.call.completed": (event) => {
-      console.log("output", event.content);
-    },
-  },
-});
-```
-
-The policy receives `agentName`, `channel`, `audience`, `mode`, `environment`, and `principalType`. `audience` is `"public"`, `"private"`, or `"unknown"`. `environment` is `"development"`, `"preview"`, or `"production"`.
-
-`principalType` is the principal used for classification. Normal channels report their route or session principal; forwarded eve sessions report the calling deployment's principal. Sessions that predate the durable conversation key report their session initiator.
-
-The default policy emits metadata for every audience and includes inputs and outputs for `public` conversations and for any audience in a development environment. Preview behaves like production: an `unknown` conversation records metadata only. Return an explicit decision to change that behavior:
-
-| Decision                                      | Result                                                       |
-| --------------------------------------------- | ------------------------------------------------------------ |
-| `false` or `{ emit: false }`                  | Do not invoke this provider for the trace.                   |
-| `true`                                        | Emit the trace with the default audience-aware content rule. |
-| `{ emit: true, recordInputs, recordOutputs }` | Emit the trace with the selected content directions.         |
-
-Inputs include model prompts, tool arguments, channel input, and user responses. Outputs include model responses, tool results, requests for user input, provider metadata, and error details. Content fields are optional on event types because the active policy may remove them.
-
-A provider's policy does not change another provider or the OpenTelemetry pipeline. A policy that throws fails closed for that provider.
-
-## Redact fields in a custom provider
-
-Lifecycle events are immutable snapshots. Copy the fields you need into a destination-specific payload and redact that copy before sending it:
-
-```ts title="agent/instrumentation/audit.ts"
-import { defineInstrumentation } from "eve/instrumentation";
-
-export default defineInstrumentation({
-  tracePolicy: () => ({
-    emit: true,
-    recordInputs: true,
-    recordOutputs: false,
-  }),
-  events: {
-    "action.started": async (event) => {
-      await sendAuditRecord({
-        id: event.idempotencyKey,
-        input: redactApiKey(event.input),
-        kind: event.kind,
-        name: event.name,
-      });
-    },
-  },
-});
-
-function redactApiKey(value: unknown): unknown {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
-
-  const record = value as Record<string, unknown>;
-  return "apiKey" in record ? { ...record, apiKey: "[redacted]" } : record;
-}
-
-async function sendAuditRecord(record: unknown): Promise<void> {
-  // Send the sanitized record to your provider.
-  void record;
-}
-```
-
-Prefer `recordInputs: false` or `recordOutputs: false` when the destination does not need an entire content direction. Use field-level redaction only when the destination needs part of that content.
-
-## Add an OpenTelemetry destination
-
-OpenTelemetry configuration has two parts:
-
-- `otel()` declares process-wide settings such as the resource, sampler, propagators, and trace capture policy. Declare it at most once.
-- `otelIntegration()` adds one destination. Declare one file per exporter or processor chain.
-
-Most agents only need a destination:
-
-```ts title="agent/instrumentation/braintrust.ts"
-import { BraintrustExporter } from "@braintrust/otel";
-import { otelIntegration } from "eve/instrumentation/otel";
-
-export default otelIntegration({
-  traceExporter: new BraintrustExporter({ filterAISpans: true }),
-});
-```
-
-Custom destinations receive the schema v4 agent trace contract. Follow [Query exported traces](./instrumentation#query-exported-traces) to find activations and sessions across traces.
-
-Add `agent/instrumentation/otel.ts` when you need process-wide settings or want to control which content eve writes to OpenTelemetry spans:
-
-```ts title="agent/instrumentation/otel.ts"
-import { otel } from "eve/instrumentation/otel";
-
-export default otel({
-  resource: { "deployment.environment": process.env.VERCEL_ENV ?? "development" },
-  tracePolicy: ({ audience, environment }) => ({
-    emit: true,
-    recordInputs: audience === "public" || environment === "development",
-    recordOutputs: audience === "public" || environment === "development",
-  }),
-});
-```
-
-The OpenTelemetry `tracePolicy` is a capture ceiling shared by its destinations. A destination cannot restore content excluded by this policy. It does not affect lifecycle event providers created with `defineInstrumentation()`.
-
-## Redact managed OpenTelemetry destinations
-
-`localTraces()` and `agentRuns()` accept an `exportPolicy`. Use the built-in redactors to remove known input or output attributes before that destination's processors receive a span:
-
-```ts title="agent/instrumentation/agent-runs.ts"
-import {
-  agentRuns,
-  composeSpanExportPolicies,
-  redactSpanInputs,
-  redactSpanOutputs,
-} from "eve/instrumentation/otel";
-
-export default agentRuns({
-  exportPolicy: composeSpanExportPolicies(
-    redactSpanInputs(({ audience }) => audience !== "public"),
-    redactSpanOutputs(({ audience }) => audience !== "public"),
-    {
-      attribute: ({ key }) =>
-        key === "user.email" ? { action: "replace", value: "[redacted]" } : { action: "keep" },
-    },
-  ),
-});
-```
-
-`redactSpanInputs()` removes known prompts, instructions, documents, and tool arguments. `redactSpanOutputs()` removes known responses, reasoning, tool results, exception details, event attributes, and status messages. Their optional predicate receives the span name, IDs, attributes, and channel audience.
-
-An export policy can also remove spans or attributes:
-
-```ts
-{
-  span: ({ name }) => name !== "internal.cache.refresh",
-  attribute: ({ key }) =>
-    key === "customer.id" ? { action: "drop" } : { action: "keep" },
-}
-```
-
-Policies run in declaration order. A later policy sees the filtered span produced by earlier policies. Redaction and filtering apply only to that destination and do not mutate spans shared with other destinations.
-
-`recordInputs` and `recordOutputs` remain accepted by `localTraces()` and `agentRuns()` for compatibility, but are deprecated. Use `redactSpanInputs()` and `redactSpanOutputs()` in `exportPolicy` instead.
-
-`otelIntegration()` does not accept `exportPolicy`. Use the process-wide `otel({ tracePolicy })` to limit capture for all custom OpenTelemetry destinations, or supply a destination-specific `SpanProcessor` that filters before its exporter.
-
-## Built-in slots
-
-The provider layout adds two environment-specific defaults:
-
-- `local` records local traces during `eve dev`.
-- `agent-runs` exports to Vercel Agent Runs in preview and production deployments.
-
-Omitting these files preserves the defaults. Reconfigure a slot by exporting `localTraces()` or `agentRuns()` from the matching file. Disable one explicitly:
-
-```ts title="agent/instrumentation/local.ts"
-import { disableInstrumentation } from "eve/instrumentation";
-
-export default disableInstrumentation();
-```
-
-## Lifecycle events
-
-Providers can handle session, channel delivery, turn, model attempt, model call, action, input request, and tool call events. Start and terminal events share an `idempotencyKey`, which can serve as a destination row ID.
-
-An ordinary tool emits both `action.*` and `tool.call.*` events. Use `action.*` for eve's durable dispatch lifecycle, including tools, skills, subagents, and remote agents. Use `tool.call.*` only when you need the AI SDK's in-process tool execution boundary.
-
-Handlers for different providers run concurrently and are failure-isolated. Do not depend on provider execution order. Use `flush` to drain buffered records and `shutdown` to release resources.
-
-The [agent trace contract](./instrumentation#agent-trace-contract) defines span
-names, identities, and usage counters shared by the exporters and local viewers.
-
-## What to read next
-
-- [Observability](./instrumentation): the default `instrumentation.ts` API and trace hierarchy
-- [Local development](./dev-tui): inspect local traces in the TUI
-- [Hooks](./hooks): react to runtime events outside the instrumentation provider API