eve 0.51.0 → 0.52.0

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

@@ -7,11 +7,11 @@ import type { TokenResult } from "#shared/connection-types.js";
 import type { ToolAuthOptions, ToolAuthProvider } from "#tools/auth.js";
 import type { InputOption } from "#shared/input.js";
 import type { ToolModelOutput } from "#tools/model-output.js";
-import type { TaskDelegated, TaskExec, TaskReceipt } from "#tools/task.js";
+import type { TaskExec, TaskReceipt } from "#tools/task.js";
 type ApprovalContextInput<TInput> = unknown extends TInput ? Record<string, unknown> : TInput;
 export type { ToolAuthDefinition, ToolAuthOptions, ToolAuthProvider } from "#tools/auth.js";
 export type { ToolModelOutput, ToolModelOutputPart } from "#tools/model-output.js";
-export type { TaskBinding, TaskDelegated, TaskExec, TaskExecutorBinding, TaskReceipt, TaskSendCommand, } from "#tools/task.js";
+export type { TaskExec, TaskExecutorBinding, TaskReceipt } from "#tools/task.js";
 export type ToolExecuteOptions = Omit<ToolExecutionOptions<unknown>, "context">;
 export type ToolExecuteFn<TInput = unknown, TOutput = unknown> = (input: TInput, options: ToolExecuteOptions, task?: TaskExec) => Promise<TOutput> | TOutput | AsyncIterable<TOutput>;
 export type ToolExecution = "background";
@@ -53,7 +53,7 @@ export interface PublicToolDefinitionWithExecuteFn<TInput = unknown, TOutput = u
 }
 /**
  * A question a workflow tool asks the human on the session's channel, sent
- * with `ask` from `eve/workflow`. Channels render it the way they render
+ * with `ctx.ask` from a `defineWorkflowTool` executor. Channels render it the way they render
  * `ask_question` and tool approvals.
  */
 export interface ToolInputRequest {
@@ -82,10 +82,8 @@ export interface ToolInputResponse {
  * Extends {@link SessionContext} with token accessors. Passing a provider
  * resolves that provider inline, which lets one tool use multiple credentials.
  *
- * A tool whose `execute` is a workflow (`"use workflow"`) receives the same
- * context inside its durable body, except that `getSandbox`, `getSkill`,
- * `getToken`, and `requireAuth` are unavailable there and throw when touched —
- * read credentials inside a `"use step"` function instead.
+ * Workflow tools use the separate `WorkflowToolContext` provided by
+ * `defineWorkflowTool`.
  */
 export type ToolContext = SessionContext & {
     /**
@@ -152,14 +150,14 @@ export interface ToolDefinition<TInput = unknown, TOutput = unknown> extends Pub
     toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
 }
 /** A tool whose executor can outlive the model tool-call phase as a durable task. */
-export interface BackgroundToolDefinition<TInput = unknown, TOutput = unknown> extends PublicToolDefinition<TInput, TOutput> {
+export interface BackgroundToolDefinition<TInput = unknown, TOutput = unknown> extends PublicToolDefinition<TInput, TaskReceipt> {
     readonly execution: "background";
-    execute(input: TInput, ctx: ToolContext, task: TaskExec): Promise<TaskDelegated | TOutput> | TaskDelegated | TOutput | AsyncIterable<TOutput>;
+    execute(input: TInput, ctx: ToolContext, task: TaskExec): Promise<TOutput> | TOutput | AsyncIterable<unknown>;
     approval?: Approval<ApprovalContextInput<TInput>>;
-    toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
+    toModelOutput?: (output: TaskReceipt) => ToolModelOutput | Promise<ToolModelOutput>;
 }
 type ToolOutputFromExecuteReturn<TReturn> = TReturn extends Promise<infer TOutput> ? TOutput : TReturn extends AsyncIterable<infer TOutput> ? TOutput : TReturn;
-type BackgroundToolOutputFromExecuteReturn<TReturn> = ToolOutputFromExecuteReturn<TReturn> extends infer TOutput ? TOutput extends TaskDelegated<infer TData> ? TaskReceipt<TData> : TOutput : never;
+type BackgroundToolOutputFromExecuteReturn<TReturn> = TReturn extends AsyncGenerator<unknown, infer TOutput> ? TOutput : TReturn extends AsyncIterable<unknown> ? null : Awaited<TReturn>;
 type ToolDefinitionWithExecuteReturn<TInput, TOutput, TReturn> = ToolDefinition<TInput, TOutput> & {
     execute(input: TInput, ctx: ToolContext): TReturn;
 };
@@ -178,7 +176,7 @@ export declare function defineTool<TSchema extends StandardSchemaV1<unknown, unk
     description: BackgroundToolDefinition<unknown, unknown>["description"];
     execution: "background";
     inputSchema: TSchema;
-    outputSchema?: PublicToolDefinition<unknown, BackgroundToolOutputFromExecuteReturn<TReturn>>["outputSchema"];
+    outputSchema?: PublicToolDefinition<unknown, TaskReceipt>["outputSchema"];
     execute(input: StandardSchemaV1.InferOutput<TSchema>, ctx: ToolContext, task: TaskExec): TReturn;
     approval?: BackgroundToolDefinition<StandardSchemaV1.InferOutput<TSchema>, unknown>["approval"];
     toModelOutput?: BackgroundToolDefinition<unknown, BackgroundToolOutputFromExecuteReturn<TReturn>>["toModelOutput"];
@@ -216,6 +214,12 @@ export declare function defineTool<TReturn>(definition: {
     toModelOutput?: ToolDefinition<unknown, ToolOutputFromExecuteReturn<TReturn>>["toModelOutput"];
 }): ToolDefinitionWithExecuteReturn<Record<string, unknown>, ToolOutputFromExecuteReturn<TReturn>, TReturn>;
 export declare function defineTool<TInput = unknown, TOutput = unknown>(definition: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+export declare function stampToolDefinition<T extends {
+    readonly description: string;
+    readonly execute: (...args: never[]) => unknown;
+    readonly approval?: Approval<never>;
+    readonly toModelOutput?: (...args: never[]) => unknown;
+}>(definition: T, definer: "defineTool" | "defineWorkflowTool"): T;
 /**
  * Marker discriminator written into every {@link DisabledToolSentinel}.
  */

package/dist/src/tools/definition.js

@@ -1 +1 @@
-import{collectDurableDynamicToolCallbacks,stampDurableDynamicToolCallbacks}from"#tools/durable-callbacks.js";import{TOOL_BRAND}from"#tools/dynamic.js";import{stampDefinitionKey}from"#internal/authored-definition/source-identity.js";function defineTool(t){if(t.auth!==void 0)throw Error(`defineTool: The "auth" field is no longer supported. Pass auth providers inline to ctx.getToken(provider) or ctx.requireAuth(provider).`);return Object.assign(t,{[TOOL_BRAND]:!0}),stampDurableDynamicToolCallbacks(t,collectDurableDynamicToolCallbacks({approval:t.approval,execute:t.execute,toModelOutput:t.toModelOutput})),stampDefinitionKey(t,`tool:${t.description}`),t}const DISABLED_TOOL_SENTINEL_KIND=`eve:disabled-tool`;function disableTool(){return{kind:DISABLED_TOOL_SENTINEL_KIND}}function isDisabledToolSentinel(e){return typeof e==`object`&&!!e&&e.kind===DISABLED_TOOL_SENTINEL_KIND}export{defineTool,disableTool,isDisabledToolSentinel};
+import{collectDurableDynamicToolCallbacks,stampDurableDynamicToolCallbacks}from"#tools/durable-callbacks.js";import{TOOL_BRAND}from"#tools/dynamic.js";import{stampDefinitionKey}from"#internal/authored-definition/source-identity.js";function defineTool(e){return stampToolDefinition(e,`defineTool`)}function stampToolDefinition(t,n){if(t.auth!==void 0)throw Error(`${n}: The "auth" field is no longer supported. Pass auth providers inline to ctx.getToken(provider) or ctx.requireAuth(provider).`);return Object.assign(t,{[TOOL_BRAND]:!0}),stampDurableDynamicToolCallbacks(t,collectDurableDynamicToolCallbacks({approval:t.approval,execute:t.execute,toModelOutput:t.toModelOutput})),stampDefinitionKey(t,`tool:${t.description}`),t}const DISABLED_TOOL_SENTINEL_KIND=`eve:disabled-tool`;function disableTool(){return{kind:DISABLED_TOOL_SENTINEL_KIND}}function isDisabledToolSentinel(e){return typeof e==`object`&&!!e&&e.kind===DISABLED_TOOL_SENTINEL_KIND}export{defineTool,disableTool,isDisabledToolSentinel,stampToolDefinition};

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

@@ -1,7 +1,7 @@
 import type { Approval } from "#approval/definition.js";
 import type { DynamicResolveContext, DynamicToolEventName } from "#dynamic/definition.js";
 import type { PublicToolInputSchema, PublicToolOutputSchema, ToolContext } from "#tools/definition.js";
-import type { TaskDelegated, TaskExec } from "#tools/task.js";
+import type { TaskExec } from "#tools/task.js";
 import type { ToolModelOutput } from "#tools/model-output.js";
 /**
  * A single tool entry within a resolved dynamic tool set.
@@ -20,7 +20,7 @@ export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = an
     readonly inputSchema: PublicToolInputSchema<TInput>;
     readonly outputSchema?: PublicToolOutputSchema<TOutput>;
     readonly execution?: "background";
-    execute(input: TInput, ctx: ToolContext, task?: TaskExec): TOutput | TaskDelegated | Promise<TOutput | TaskDelegated>;
+    execute(input: TInput, ctx: ToolContext, task?: TaskExec): TOutput | Promise<TOutput>;
     readonly toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
     /**
      * Optional per-call approval gate, mirroring the authored-tool

package/dist/src/tools/provided/sleep.d.ts

@@ -1,4 +1,4 @@
-import { type ToolDefinition } from "#tools/definition.js";
+import { type BlockingWorkflowToolDefinition } from "#tools/workflow-definition.js";
 import { type SleepToolInput, type SleepToolOutput } from "#execution/tools/sleep.js";
 export type { SleepToolInput, SleepToolOutput };
 /**
@@ -12,7 +12,7 @@ export type { SleepToolInput, SleepToolOutput };
  * export default sleep();
  * ```
  *
- * Calls pause the durable turn workflow rather than holding an application
- * runtime open with an in-process timer.
+ * Each call runs as a durable workflow, so the wait does not hold an
+ * application runtime open.
  */
-export declare function sleep(): ToolDefinition<SleepToolInput, SleepToolOutput>;
+export declare function sleep(): BlockingWorkflowToolDefinition<SleepToolInput, SleepToolOutput>;

package/dist/src/tools/provided/sleep.js

@@ -1 +1 @@
-import{defineTool}from"#tools/definition.js";import{SLEEP_INPUT_SCHEMA,SLEEP_OUTPUT_SCHEMA,SLEEP_TOOL_DESCRIPTION,executeSleepTool}from"#execution/tools/sleep.js";function sleep(){return defineTool({description:SLEEP_TOOL_DESCRIPTION,execute:executeSleepTool,inputSchema:SLEEP_INPUT_SCHEMA,outputSchema:SLEEP_OUTPUT_SCHEMA})}export{sleep};
+import{defineWorkflowTool}from"#tools/workflow-definition.js";import{SLEEP_INPUT_SCHEMA,SLEEP_OUTPUT_SCHEMA,SLEEP_TOOL_DESCRIPTION,executeSleepTool}from"#execution/tools/sleep.js";function sleep(){return defineWorkflowTool({description:SLEEP_TOOL_DESCRIPTION,execute:executeSleepTool,inputSchema:SLEEP_INPUT_SCHEMA,outputSchema:SLEEP_OUTPUT_SCHEMA})}export{sleep};

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

@@ -1,48 +1,25 @@
 import type { BackgroundTask } from "#execution/tasks/parent/delegate.js";
-import type { BackgroundToolCall } from "#harness/background-tools.js";
 import type { HarnessSession } from "#harness/types.js";
 import type { JsonObject, JsonValue } from "#shared/json.js";
-declare const TASK_DELEGATED_KIND = "eve:task-delegated";
-/** Private address an executor uses to report lifecycle changes to its owning task. */
-export interface TaskBinding {
-    readonly taskId: string;
-    readonly token: string;
-    readonly url?: string;
-}
-/**
- * Opaque, task-private address used to control an external executor. `data`
- * means nothing to the task layer beyond deep equality (replay idempotency);
- * only the executor `kind` that wrote it may parse it (e.g. cancel routing).
- */
+declare const TASK_MESSAGE_KIND: "eve:task-message";
+export type TaskMessage = JsonObject & {
+    readonly kind: typeof TASK_MESSAGE_KIND;
+    readonly message: string;
+};
+export declare function createTaskMessage(message: string): TaskMessage;
+export declare function isTaskMessage(value: unknown): value is TaskMessage;
+/** Opaque, framework-private address used to control a task executor. */
 export interface TaskExecutorBinding {
     readonly kind: string;
     readonly data: JsonObject;
 }
-/**
- * What the model sees as this call's tool output when work is delegated: the
- * author-supplied data plus `status: "working"` and the `taskId` it can poll
- * or cancel. It acknowledges delegation — it is not the task's result, which
- * arrives later through task completion.
- */
-export type TaskReceipt<TData extends JsonObject = JsonObject> = TData & {
-    readonly status: "working";
+/** @deprecated Use workflow-backed background tools with yield descriptors. */
+export interface TaskBinding {
     readonly taskId: string;
-};
-/**
- * Sentinel returned by a background tool after an external executor accepts
- * responsibility for the task. Returning it ends `execute`; it does not
- * complete the durable task.
- */
-export interface TaskDelegated<TData extends JsonObject = JsonObject> {
-    readonly kind: typeof TASK_DELEGATED_KIND;
-    readonly executor: TaskExecutorBinding;
-    readonly receipt: TaskReceipt<TData>;
+    readonly token: string;
+    readonly url?: string;
 }
-/**
- * Commands an in-process executor may report to its task via
- * {@link TaskExec.send}. Deliberately narrower than the task run's full
- * command surface — bind, ready, and input routing stay runtime-owned.
- */
+/** @deprecated Use workflow-backed background tools with yield descriptors. */
 export type TaskSendCommand = {
     readonly kind: "update";
     readonly message: string;
@@ -55,53 +32,24 @@ export type TaskSendCommand = {
 } | {
     readonly kind: "cancel";
 };
-/** Task capability passed only to tools declared with `execution: "background"`. */
+/** Fixed acknowledgement returned when a background task is admitted. */
+export interface TaskReceipt {
+    readonly status: "working";
+    readonly taskId: string;
+}
+/** Capability passed only to tools declared with `execution: "background"`. */
 export interface TaskExec {
-    /**
-     * The sibling background calls admitted in the same step. The only view a
-     * tool has of what launched alongside it, for enforcing batch-wide
-     * invariants before delegating.
-     */
-    readonly batch: readonly BackgroundToolCall[];
-    /**
-     * The task-private address for reporting lifecycle changes back to this
-     * task. Hand it to the external executor so completion routes to the task
-     * directly instead of through the (already finished) tool call.
-     */
+    /** Model-facing durable task identity. */
+    readonly taskId: string;
+    /** Returns a descriptor which sends one message to the parent when yielded. */
+    postMessage(message: string): TaskMessage;
+    /** @deprecated Use yields from a workflow-backed background tool. */
     readonly binding: TaskBinding;
-    /**
-     * Snapshot of the harness session at step start, for reading context.
-     * Mutating it changes nothing durable: session writes belong to the
-     * runtime, keyed off the executor binding at step commit.
-     */
-    readonly session: HarnessSession;
-    /**
-     * Delivers progress or a terminal command to this task's inbox from the same
-     * process, for executors that outlive `execute` in-memory (e.g. a callback firing
-     * after delegation). Call it only after `execute` returned `delegated(...)`
-     * — the runtime settles non-delegated returns itself, and a second terminal
-     * command is refused. Not restart-safe: an in-process callback dies with
-     * the process; the persisted executor binding remains the durable
-     * cancellation path. Throws when the task no longer accepts commands
-     * (already terminal).
-     */
+    /** @deprecated Use yields from a workflow-backed background tool. */
     readonly send: (command: TaskSendCommand) => Promise<void>;
-    /** The durable task backing this call; its identity outlives `execute`. */
+    /** @deprecated Use ctx.session. */
+    readonly session: HarnessSession;
+    /** @deprecated Framework-owned task internals are not part of the authoring API. */
     readonly task: BackgroundTask;
-    /**
-     * Builds the `TaskDelegated` sentinel to return from `execute`. Centralizes
-     * receipt stamping so every receipt carries this task's `taskId` and
-     * `status: "working"` — tools cannot mint receipts for tasks they don't own.
-     */
-    delegated<TData extends JsonObject>(input: {
-        readonly executor: TaskExecutorBinding;
-        readonly receipt: TData;
-    }): TaskDelegated<TData>;
 }
-export declare function createTaskDelegated<TData extends JsonObject>(input: {
-    readonly binding: TaskBinding;
-    readonly executor: TaskExecutorBinding;
-    readonly receipt: TData;
-}): TaskDelegated<TData>;
-export declare function isTaskDelegated(value: unknown): value is TaskDelegated;
 export {};

package/dist/src/tools/task.js

@@ -1 +1 @@
-const TASK_DELEGATED_KIND=`eve:task-delegated`;function createTaskDelegated(e){return{executor:e.executor,kind:TASK_DELEGATED_KIND,receipt:{...e.receipt,status:`working`,taskId:e.binding.taskId}}}function isTaskDelegated(e){return typeof e==`object`&&!!e&&`kind`in e&&e.kind===TASK_DELEGATED_KIND}export{createTaskDelegated,isTaskDelegated};
+const TASK_MESSAGE_KIND=`eve:task-message`;function createTaskMessage(e){if(e.trim()===``)throw TypeError(`Task messages must not be empty.`);return{kind:TASK_MESSAGE_KIND,message:e}}function isTaskMessage(e){return typeof e==`object`&&!!e&&Reflect.get(e,`kind`)===TASK_MESSAGE_KIND}export{createTaskMessage,isTaskMessage};

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

@@ -0,0 +1,60 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
+import type { Approval } from "#approval/definition.js";
+import type { JsonObject, JsonValue } from "#shared/json.js";
+import { type PublicToolDefinition, type BackgroundToolDefinition, type ToolContext, type ToolInputRequest, type ToolInputResponse } from "#tools/definition.js";
+import type { TaskExec } from "#tools/task.js";
+import type { ToolModelOutput } from "#tools/model-output.js";
+export interface AgentInput {
+    readonly agentId?: string;
+    readonly key: string;
+    readonly message: string;
+    readonly outputSchema?: JsonObject;
+    readonly target: string;
+}
+/** Context supplied only to a defineWorkflowTool executor, inside its durable run. */
+export type WorkflowToolContext = Pick<ToolContext, "abortSignal" | "callId" | "session" | "toolName"> & {
+    /** Invoke a visible subagent. The key must be unique within this workflow run. */
+    agent(input: AgentInput): Promise<JsonValue>;
+    /** Ask the human on the session's channel; awaiting the answer suspends the run. */
+    ask(request: ToolInputRequest): PromiseLike<ToolInputResponse>;
+};
+declare const WORKFLOW_TOOL_BRAND: unique symbol;
+/** A static tool whose executor runs as a durable workflow. Its executor must start with "use workflow". */
+export interface BlockingWorkflowToolDefinition<TInput = unknown, TOutput = unknown> extends PublicToolDefinition<TInput, TOutput> {
+    readonly [WORKFLOW_TOOL_BRAND]: true;
+    readonly execution?: never;
+    execute(input: TInput, ctx: WorkflowToolContext): Promise<TOutput> | AsyncIterable<TOutput>;
+    approval?: Approval<unknown extends TInput ? Record<string, unknown> : TInput>;
+    toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
+}
+type BackgroundWorkflowToolDefinition<TInput, TOutput> = Omit<BackgroundToolDefinition<TInput, TOutput>, "execute"> & {
+    readonly [WORKFLOW_TOOL_BRAND]: true;
+    execute(input: TInput, ctx: WorkflowToolContext, task: TaskExec): Promise<TOutput> | AsyncIterable<unknown>;
+};
+/** A static tool whose executor runs as a durable workflow. */
+export type WorkflowToolDefinition<TInput = unknown, TOutput = unknown> = BlockingWorkflowToolDefinition<TInput, TOutput> | BackgroundWorkflowToolDefinition<TInput, TOutput>;
+type Unbranded<T> = T extends unknown ? Omit<T, typeof WORKFLOW_TOOL_BRAND> : never;
+type BackgroundReturn<T> = T extends AsyncGenerator<unknown, infer Output> ? Output : T extends AsyncIterable<unknown> ? null : Awaited<T>;
+type BackgroundDefinition<TInput, TReturn> = Omit<BackgroundWorkflowToolDefinition<TInput, BackgroundReturn<TReturn>>, typeof WORKFLOW_TOOL_BRAND | "execute"> & {
+    execute(input: TInput, ctx: WorkflowToolContext, task: TaskExec): TReturn;
+};
+type WorkflowReturn<T> = T extends AsyncIterable<infer Output> ? Output : Awaited<T>;
+type Schema = StandardSchemaV1<unknown, unknown> | StandardJSONSchemaV1<unknown, unknown>;
+type Definition<TInput, TReturn> = Omit<BlockingWorkflowToolDefinition<TInput, WorkflowReturn<TReturn>>, typeof WORKFLOW_TOOL_BRAND | "execute"> & {
+    execute(input: TInput, ctx: WorkflowToolContext): TReturn;
+};
+export declare function defineWorkflowTool<TSchema extends Schema, TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: Omit<BackgroundDefinition<StandardSchemaV1.InferOutput<TSchema>, TReturn>, "inputSchema"> & {
+    inputSchema: TSchema;
+}): BackgroundWorkflowToolDefinition<StandardSchemaV1.InferOutput<TSchema>, BackgroundReturn<TReturn>>;
+export declare function defineWorkflowTool<TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: BackgroundDefinition<Record<string, unknown>, TReturn> & {
+    inputSchema: JsonObject;
+}): BackgroundWorkflowToolDefinition<Record<string, unknown>, BackgroundReturn<TReturn>>;
+export declare function defineWorkflowTool<TSchema extends Schema, TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: Omit<Definition<StandardSchemaV1.InferOutput<TSchema>, TReturn>, "inputSchema"> & {
+    inputSchema: TSchema;
+}): BlockingWorkflowToolDefinition<StandardSchemaV1.InferOutput<TSchema>, WorkflowReturn<TReturn>>;
+export declare function defineWorkflowTool<TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: Definition<Record<string, unknown>, TReturn> & {
+    inputSchema: JsonObject;
+}): BlockingWorkflowToolDefinition<Record<string, unknown>, WorkflowReturn<TReturn>>;
+export declare function defineWorkflowTool<TInput = unknown, TOutput = unknown>(definition: Unbranded<WorkflowToolDefinition<TInput, TOutput>>): WorkflowToolDefinition<TInput, TOutput>;
+export declare function isWorkflowToolDefinition(value: unknown): boolean;
+export {};

package/dist/src/tools/workflow-definition.js

@@ -0,0 +1 @@
+import{stampToolDefinition}from"#tools/definition.js";const WORKFLOW_TOOL_BRAND=Symbol.for(`eve:workflow-tool-brand`);function defineWorkflowTool(t){return stampToolDefinition(t,`defineWorkflowTool`),Object.assign(t,{[WORKFLOW_TOOL_BRAND]:!0})}function isWorkflowToolDefinition(e){return typeof e==`object`&&!!e&&Reflect.get(e,WORKFLOW_TOOL_BRAND)===!0}export{defineWorkflowTool,isWorkflowToolDefinition};

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-B4xN7-fK.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-D7apPojZ.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-B4xN7-fK.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-D7apPojZ.js";
 
 export { useEveAgent };

package/docs/agent-config.md

@@ -147,9 +147,9 @@ See [Default harness](./concepts/default-harness#compaction) for how the loop ap
 
 ## Runtime limits
 
-Use `limits` for framework-owned runtime caps. Session token limits stop the
+Use `limits` for framework-owned runtime caps. Session usage limits stop the
 current durable session from starting another model call after accumulated
-provider-reported input or output token usage reaches the configured limit:
+provider-reported tokens or model token cost reaches a configured limit:
 
 ```ts title="agent/agent.ts"
 export default defineAgent({
@@ -157,6 +157,7 @@ export default defineAgent({
   limits: {
     maxInputTokensPerSession: 200_000,
     maxOutputTokensPerSession: 20_000,
+    maxTokenCostUsdPerSession: 1.5,
     sessionTimeoutMs: 7 * 24 * 60 * 60 * 1_000,
   },
 });
@@ -169,14 +170,13 @@ then emits `session.completed` and releases the continuation; the next
 qualifying channel message starts fresh. Set it to `false` to disable the
 timeout. Expiration does not delete stored session data.
 
-Input and output budgets are checked independently. The model call that crosses
-either limit is allowed to finish because providers only report exact token
-usage after a call completes. Before the next model call, eve pauses the
+Input tokens, output tokens, and model token cost are checked independently.
+The model call that crosses a limit is allowed to finish because exact usage
+arrives after the call completes. Before the next model call, eve pauses the
 session and sends a deterministic continuation prompt with two options:
-**Approve** grants a fresh budget window of the configured size (both input
-and output windows reset together), and **Stop** cancels the in-flight turn
-through the standard cancellation path (`turn.cancelled` → `session.waiting`)
-— a user decision, not an error. The session stays resumable; because it is
+**Approve** grants a fresh window of each configured size, and **Stop**
+cancels the in-flight turn through the standard cancellation path
+(`turn.cancelled` → `session.waiting`) — a user decision, not an error. The session stays resumable; because it is
 still over budget, the next message re-raises the prompt. Declining a
 delegated child's prompt cancels the root turn, which cascades to the whole
 delegation tree — the delegating parent never receives an error result it
@@ -186,23 +186,28 @@ copy. The reply is processed once the budget is granted.
 
 Sessions that cannot reach a human — task-mode runs such as schedules and
 delegated runs without input proxying — skip the prompt and fail the next model
-call with `SESSION_TOKEN_LIMIT_REACHED`. A delegated task with no inherited
-quota also fails instead of raising a continuation prompt that could only
-grant another zero-token window.
+call with `SESSION_TOKEN_LIMIT_REACHED` for token budgets or
+`SESSION_TOKEN_COST_LIMIT_REACHED` for model token cost. A delegated task with
+no inherited quota also fails instead of raising a continuation prompt that
+could only grant another zero-value window.
 
 When `maxInputTokensPerSession` is omitted, root sessions apply a default
 input budget of `40_000_000` provider-reported input tokens.
-`maxOutputTokensPerSession` is unset unless configured. Setting either limit
-to `false` uncaps that axis — the session never stops on it.
+`maxOutputTokensPerSession` and `maxTokenCostUsdPerSession` are unset by
+default. `maxTokenCostUsdPerSession` is a US-dollar limit on model token cost,
+not tool or infrastructure spend. It uses the cost reported with each model
+step; AI Gateway supplies this value, while model steps without reported cost
+do not add to the limit. Set any usage limit to `false` to uncap that axis.
 
 Delegated subagent sessions have no fixed default. Each child receives a
 share of the delegating parent's remaining quota at dispatch time — the
 remainder in the current budget window split evenly across the batch's local
 subagent calls — and a completed child's usage counts against the parent's
-quota, so a delegation tree can never outspend the budget configured at its
-root. Approving a continuation opens a fresh parent window for later child
-grants without erasing lifetime usage. An authored child limit applies only
-when it is tighter than the parent's grant; an uncapped parent delegates
+quota. Token-cost budgets follow the same rules, including splitting the
+remaining US-dollar budget across a batch and adding completed child cost back
+to the parent. Approving a continuation opens a fresh parent window for later
+child grants without erasing lifetime usage. An authored child limit applies
+only when it is tighter than the parent's grant; an uncapped parent delegates
 uncapped children.
 
 ## Workflow world
@@ -250,7 +255,7 @@ installed package must stay external in hosted output, list it in
 | -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                 |
 | `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                        |
-| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; token-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                   |
+| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                   |
 | `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
 | `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for function-like invocations such as a subagent turn, schedule, or remote job. Ordinary interactive turns ignore it unless the client supplies a per-message schema.                  |
 | `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.      |

package/docs/channels/eve.mdx

@@ -91,7 +91,7 @@ Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/
 
 ### Cancel a turn
 
-Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.cancelled` followed by `session.waiting`.
+Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Include `tasks: true` to also cancel every background task owned by the session, including while the session is parked. Cancellation is asynchronous; confirm the turn boundary on the stream as `turn.cancelled` followed by `session.waiting`, and inspect task state in a later turn to confirm task cancellation.
 
 See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for response statuses, HTTP status codes, subagent cancellation, and race behavior.
 

package/docs/channels/mcp.mdx

@@ -67,6 +67,8 @@ The authorization server identified by `issuer` must issue tokens accepted by th
 
 `oauthResource()` does not issue tokens or run an authorization server. It decorates an ordinary inbound `AuthFn` with OAuth protected-resource metadata so `mcpChannel()` can publish discovery and add `resource_metadata` to Bearer challenges. Client registration, consent, token issuance, and authorization-server metadata remain the identity provider's responsibility.
 
+Most hosted MCP clients (Claude, ChatGPT, Grok, and similar) register themselves with the authorization server through Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) the first time a user connects. Choose an issuer that supports it, or pre-register each client with the issuer before the demo. If registration fails, the client stops before it ever reaches eve.
+
 ### Verify the bearer token yourself
 
 Use a custom `AuthFn` when token verification needs application-specific logic:
@@ -144,7 +146,7 @@ export default mcpChannel({
 });
 ```
 
-This allows anyone to invoke the agent. Every caller shares the anonymous principal, so invocation IDs become bearer capabilities until workflow retention expires. Use public access only when anonymous invocation is intentional.
+This allows anyone to invoke the agent. Every caller shares the anonymous principal, so invocation IDs become bearer capabilities until workflow retention expires: anyone holding an ID can read, answer, or cancel that invocation. Use public access only when anonymous invocation is intentional. For a public demo, prefer [Interactive OAuth](#interactive-oauth) so each caller owns their own invocations.
 
 ## HTTP security
 
@@ -171,6 +173,10 @@ MCP clients receive four tools:
 | `agent_update` | `{ invocationId, responses }` | Answer the complete pending human-input batch.              |
 | `agent_cancel` | `{ invocationId }`            | Request cooperative cancellation of non-terminal work.      |
 
+The server also returns `instructions` from `initialize` and `server/discover` that summarize this
+protocol for the connecting model, so a hosted client does not have to infer it from the tool
+schemas alone.
+
 `agent_start` creates one task-mode eve session and returns after durable acceptance without
 waiting for the session continuation hook to become readable. Keep its `invocationId`, then call
 `agent_get` until the invocation reaches a terminal state. While the status is `working`, wait at
@@ -179,15 +185,31 @@ least `pollAfterMs` before polling again.
 The invocation response is discriminated by `status`:
 
 - `working`: work is active; continue polling according to `pollAfterMs`.
-- `input_required`: present `inputRequests`, then send the complete answer batch through `agent_update`. A successful update returns fresh `working` state.
+- `input_required`: present `inputRequests`, then send the complete answer batch through `agent_update`. A successful update returns the current invocation state.
 - `authorization_required`: present the returned sign-in URL, user code, or instructions. The connection callback resumes the invocation automatically; continue polling.
 - `completed`: consume the optional `result`.
 - `failed`: inspect the structured `error`.
 - `cancelled`: cancellation reached a terminal state.
 
+A tool result with `isError: true` means the call itself was rejected. A `failed` status means the call succeeded and the task itself failed. Handle them differently: correct the call in the first case, report the task failure in the second. Rejected calls carry `structuredContent.error` with a stable `code`, a short `message`, and `retryable`:
+
+| `code`          | Meaning                                                                        | `retryable` |
+| --------------- | ------------------------------------------------------------------------------ | ----------- |
+| `invalid_input` | An argument was rejected, for example an oversized or external `outputSchema`. | `false`     |
+| `not_found`     | The invocation does not exist, has expired, or belongs to another caller.      | `false`     |
+| `conflict`      | The invocation is not in the expected state; read it with `agent_get` first.   | `true`      |
+| `internal`      | eve failed; `errorId` correlates with server logs. No details are exposed.     | `false`     |
+
 Cancellation is cooperative, so call `agent_get` after `agent_cancel` until the state becomes terminal.
 
-Optional output schemas are limited to 64 KiB, 32 levels, and 2,048 nodes. External `$ref` values are rejected.
+Requests are bounded: the whole MCP request body is limited to 1 MiB, `message` to 64 KiB, each input-response `text` to 16 KiB (both measured as UTF-8 bytes, not characters), and one `agent_update` to 64 responses. Optional output schemas are limited to 64 KiB, 32 levels, and 2,048 nodes, and external `$ref` values are rejected. Oversized bodies receive a JSON-RPC `413`; oversized fields fail input validation before any work starts.
+
+### Durability guarantees
+
+- Once `agent_start` returns, the work is durable. A dropped HTTP connection, a client restart, or a closed MCP session does not cancel it. Only `agent_cancel` stops work.
+- `agent_start` is not idempotent. If its response is lost, the client has no `invocationId` to check, and a second call starts a second task. Ask the user before starting again rather than retrying blindly.
+- `agent_update` answers one pending batch. Re-sending the same answers after eve has accepted them returns the current invocation state; sending different answers for an already-answered batch is a conflict.
+- `agent_cancel` is cooperative and can race with completion. Poll `agent_get` until the status is terminal (`cancelled`, `completed`, or `failed`), not specifically `cancelled`.
 
 ## Invocation ownership
 

package/docs/concepts/built-in-tools.md

@@ -134,7 +134,7 @@ import { sleep } from "eve/tools/sleep";
 export default sleep();
 ```
 
-The model calls it with `{ seconds }` when it is useful to wait before checking progress or status again. The pause sleeps the durable turn workflow, so it does not hold an application runtime open, and the same turn continues automatically when the duration elapses. If one model response makes concurrent `sleep` calls, eve waits for the longest requested duration.
+The model calls it with `{ seconds }` when it is useful to wait before checking progress or status again. Each call runs as a durable tool workflow, so it does not hold an application runtime open, and the same turn continues automatically when the duration elapses. Concurrent `sleep` calls run in parallel, so the turn continues after the longest requested duration.
 
 ## What to read next
 

package/docs/concepts/execution-model-and-durability.mdx

@@ -60,11 +60,22 @@ Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up fro
 
 There's nothing to configure. eve owns the workflow lifecycle, and sessions are durable by default.
 
-You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of eve's runtime layer; channels, tools, and hooks never touch them. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.
+For ordinary tools, eve manages the workflow around your executor. Use [`defineWorkflowTool`](../tools/workflows) when your own tool body needs durable waits, such as a timer, webhook, or human answer. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.
 
 ## Parked work
 
-Some work has to wait, including a human approving a [tool](../tools) or an interactive OAuth sign-in for a [connection](../connections). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on arrives, even if that's much later. When it does, the conversation picks up exactly where it left off. Background tools and subagents return a task receipt instead, so the turn continues and later task notifications deliver progress or the outcome.
+Some work has to wait, including a human approving a [tool](../tools) or an interactive OAuth sign-in for a [connection](../connections). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on arrives, even if that's much later. When it does, the conversation picks up exactly where it left off.
+
+Background execution is a separate choice about result delivery. A background workflow tool
+returns a task receipt so the parent turn can continue; the tool's workflow may then run or
+suspend independently. A default workflow tool can suspend too, with its original tool call
+still pending. Ordinary background tools run their executor inside the initiating step and do
+not gain durable waits by setting `execution: "background"`.
+
+A generator's `yield` reports progress; an awaited workflow operation provides the durable wait.
+For background tools, ordinary yields are stream-only, while `yield task.postMessage(...)`
+requests a parent-agent turn. See [background execution](../tools#background-execution) and
+[workflow suspension](../tools/workflows#how-suspension-works) for the execution and result rules.
 
 ## Message delivery and steering
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -191,7 +191,15 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/cancel
 # {"ok":true,"sessionId":"<sessionId>","status":"accepted"}
 ```
 
-`"accepted"` means the live session durably queued the request. Confirm an actual cancellation on the stream as `turn.cancelled` followed by `session.waiting`; the session then accepts the next message normally. Background tasks that were already admitted survive initiating-turn cancellation and are stopped with `task_cancel`; background work that has not yet been admitted is rejected with the cancelled step. Each cancelled child reports its own boundary on its child-session stream. A live but already-parked session also returns `"accepted"` and consumes the command as a no-op. `"no_active_turn"` means the session or channel address is unknown or terminal. Both statuses are success, so clients can fire and forget. See the [eve channel](../channels/eve) for the full route contract.
+By default, background tasks that were already admitted survive initiating-turn cancellation. Pass `tasks: true` to cancel every background task owned by the session as well. This works while the session is parked, so you can stop background work without resetting the session:
+
+```bash
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/cancel \
+  -H 'content-type: application/json' \
+  -d '{"tasks":true}'
+```
+
+`"accepted"` means the live session durably queued the request; cancellation completes asynchronously. Confirm turn cancellation on the stream as `turn.cancelled` followed by `session.waiting`. Inspect task state in a later turn to confirm task cancellation. The session then accepts the next message normally. Background work that has not yet been admitted is rejected with the cancelled step. Each cancelled child reports its own boundary on its child-session stream. A live but already-parked session returns `"accepted"`; plain cancellation is a no-op there, while `tasks: true` still cancels indexed tasks. `"no_active_turn"` means the session or channel address is unknown or terminal. Both statuses are success, so clients can fire and forget. See the [eve channel](../channels/eve) for the full route contract.
 
 The HTTP route returns `202` for `"accepted"` and `200` for
 `"no_active_turn"`. Only the accepted result includes `sessionId`.

package/docs/guides/client/messages.mdx

@@ -59,7 +59,7 @@ const { session, response } = await client.sessions.create({
 await response.result();
 ```
 
-`clientContext` is one-turn context for the next model call. Strings become user-role context messages, arrays of strings become multiple context messages, and objects are JSON-serialized into one context message. It isn't persisted to durable session history and doesn't dispatch a turn by itself.
+`clientContext` is ephemeral context for the current turn. Strings become user-role context messages, arrays of strings become multiple context messages, and objects are JSON-serialized into one context message. The context remains available to every model call in the turn, then disappears before the next turn. It isn't persisted to durable session history and doesn't dispatch a turn by itself.
 
 ## Send attachments
 

package/docs/guides/client/streaming.mdx

@@ -237,7 +237,7 @@ stream index after the captured prefix.
 
 ## Abort a request
 
-Pass an `AbortSignal` to cancel the POST or stream. Aborting is local transport cancellation: turns are resumable across disconnects, so detaching never stops the server-side turn — it keeps running and remains attachable by index. To stop the turn itself, POST the session's [cancel route](../../channels/eve#routes) and watch the stream settle with `turn.cancelled` followed by `session.waiting`.
+Pass an `AbortSignal` to cancel the POST or stream. Aborting is local transport cancellation: turns are resumable across disconnects, so detaching never stops server-side work. Use `session.cancel()` to stop the active turn, or `session.cancel({ tasks: true })` to also stop background tasks owned by the session. Cancellation is asynchronous; watch the stream for `turn.cancelled` followed by `session.waiting`, and inspect task state in a later turn to confirm task cancellation.
 
 Arm the timeout before awaiting `send()` so it covers the POST as well as the stream:
 

package/docs/guides/deployment/vercel.mdx

@@ -63,12 +63,14 @@ my-project/
         └── agent/
 ```
 
-An `agents/` directory marks the project as a workspace. eve validates and discovers only direct `agents/<name>/agent/` children. Their directory names become their public identities, exposed at `/<name>/eve/v1/*`. Run an agent-specific command from a child directory or pass `--agent <name>` at the workspace root; interactive commands open a picker when the name is omitted. Run project-level build, link, and deploy commands from the workspace root. The workspace root owns the project package, dependencies, and build scripts.
+In an eve workspace, eve discovers direct `agents/<name>/` children that contain nested or flat agent files and do not have their own `package.json`. Their directory names become their public identities, exposed at `/<name>/eve/v1/*`. A child with its own `package.json` is a separate package rather than a member of the parent eve workspace. Run an agent-specific command from a member directory or pass `--agent <name>` at the workspace root; interactive commands open a picker when the name is omitted. Run project-level build, link, and deploy commands from the workspace root. Workspace members share the root package, dependencies, and build scripts.
 
 Create this layout with `eve init my-project --agents support,research`, or add one agent to an existing workspace with `eve init billing`.
 
 With no authored `vercel.json#services`, `eve build` derives the complete Vercel Services graph on every build. If `vercel.json` declares `services`, that authored graph is authoritative instead; use `vercel build` to build and validate the complete project. This supports heterogeneous projects with frontends, private APIs, bindings, and other non-eve services without generated configuration files.
 
+An authored eve service routed at `/eve/v1` already uses the protocol path; callbacks remain at `/eve/v1/callback/*`. A named mount such as `/support` adds that mount before the protocol path, giving `/support/eve/v1/callback/*`.
+
 Deploy the linked project to production:
 
 ```bash