eve 0.74.0 → 0.75.0

package/dist/src/svelte/index.js

@@ -1,4 +1,4 @@
-import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-mP0M7SrL.js";
+import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-B2Kne9z6.js";
 
 //#region src/client/tool-call-state.ts
 function toolCallState(conversation, callId, options = {}) {

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

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

package/dist/src/tool-stubs/execute.d.ts

@@ -0,0 +1,13 @@
+import type { StubResult } from "#tool-stubs/types.js";
+import type { ToolExecuteOptions } from "#tools/definition.js";
+/** Tool inputs and approvals have already been checked before a stub can replace execution. */
+export declare function executeWithToolStub(tool: string, input: unknown, options: ToolExecuteOptions, execute: () => unknown): unknown;
+/** The connection wrapper checks operation inputs and approvals before requesting a stub. */
+export declare function connectionToolStub(tool: string, input: unknown, callId: string): Promise<StubResult>;
+/** Record errors converting stub responses so eval verification can detect them. */
+export declare function recordToolStubFailure(tool: string, callId: string | undefined, turnId?: string): Promise<void>;
+/** Record stub failures even when the caller recovers with fallback output. */
+export declare function observeToolOutput<T>(tool: string, calls: readonly {
+    readonly callId: string;
+    readonly turnId?: string;
+}[], project: () => T | Promise<T>, recover?: (error: unknown) => T): Promise<T>;

package/dist/src/tool-stubs/execute.js

@@ -0,0 +1 @@
+import{contextStorage}from"#context/container.js";import{SessionKey,ToolStubsKey}from"#context/keys.js";import{ToolStubPlaybackKey}from"#context/providers/tool-stubs-key.js";import{findStubTarget,stubCallId}from"#tool-stubs/target.js";import{isAsyncIterable}from"#shared/async-iterable.js";import{toolStubOutput}from"#tool-stubs/output.js";function executeWithToolStub(e,t,n,r){let i=contextStubCall(e,t,n.toolCallId);return i===void 0?r():executeStubbedTool(i.playback,i.call,n,r)}async function*executeStubbedTool(e,t,n,r){n.abortSignal?.throwIfAborted();let i=await e.call(t);if(i.kind===`error`)throw Error(i.error);if(i.kind===`stub`){yield toolStubOutput(i.outcome);return}let a=await r();isAsyncIterable(a)?yield*a:yield a}async function connectionToolStub(e,t,n){let r=contextStubCall(e,t,n);return r===void 0?{kind:`real`}:await r.playback.call(r.call)}function contextStubCall(e,t,n){let r=contextStorage.getStore();if(r===void 0)return;let i=findStubTarget(r.get(ToolStubsKey),e);if(i===void 0)return;let a=r.require(SessionKey);return{playback:r.require(ToolStubPlaybackKey),call:{tool:i.tool,input:t,callId:stubCallId(a.sessionId,a.turn.id,n)}}}async function recordToolStubFailure(e,t,n){let r=contextStorage.getStore(),i=r?.get(ToolStubsKey);if(i===void 0||t===void 0||e!==`connection_execute`&&findStubTarget(i,e)===void 0)return;let a=r.require(SessionKey);await r.require(ToolStubPlaybackKey).fail(stubCallId(a.sessionId,n??a.turn.id,t),`Stubbed tool "${e}" failed during output processing.`)}async function observeToolOutput(e,t,n,r){try{return await n()}catch(n){try{for(let n of t)await recordToolStubFailure(e,n.callId,n.turnId)}catch(e){throw AggregateError([n,e],`Tool output processing and failure reporting failed.`,{cause:n})}if(r!==void 0)return r(n);throw n}}export{connectionToolStub,executeWithToolStub,observeToolOutput,recordToolStubFailure};

package/dist/src/tool-stubs/output.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from "#shared/json.js";
+import type { ToolStubOutcome } from "#tool-stubs/types.js";
+/** Throws at the tool boundary, after the outcome has been recorded for replay. */
+export declare function toolStubOutput(outcome: ToolStubOutcome): JsonValue;

package/dist/src/tool-stubs/output.js

@@ -0,0 +1 @@
+function toolStubOutput(e){if(e.throw!==void 0){let t=Error(e.throw.message);throw t.name=e.throw.name??`Error`,t}return e.response}export{toolStubOutput};

package/dist/src/tool-stubs/playback.d.ts

@@ -0,0 +1,15 @@
+import type { StubCall, StubResult, ToolStub } from "#tool-stubs/types.js";
+/**
+ * Selects stub outcomes and advances their sequences.
+ * The surrounding workflow orders calls and restores progress on replay.
+ */
+export declare class StubPlayback {
+    private readonly rules;
+    private readonly results;
+    private readonly positions;
+    constructor(rules: readonly ToolStub[]);
+    get matchedRuleCount(): number;
+    call(call: StubCall): StubResult;
+    private record;
+    fail(callId: string, error: string): StubResult;
+}

package/dist/src/tool-stubs/playback.js

@@ -0,0 +1 @@
+import{isObject}from"#shared/guards.js";import{createStubValidator}from"#tool-stubs/schema.js";var StubPlayback=class{rules;results=new Map;positions=new Map;constructor(e){this.rules=e.map(e=>({...e,constraints:Object.entries(e.match??{}).map(([t,n])=>{try{return{property:t,validator:createStubValidator(n)}}catch(n){throw Error(`Could not create validator for matcher "${t}" in tool stub "${e.id}".`,{cause:n})}})}))}get matchedRuleCount(){return this.positions.size}call(e){let t=this.results.get(e.callId);if(t!==void 0)return t;if(this.results.size>=1e4)return{kind:`error`,error:`Tool stub session exceeded 10,000 calls. Start a new eval session.`};let n=this.rules.filter(t=>t.tool===e.tool);if(e.persistent&&n.some(e=>e.constraints.length>0))return this.record(e,{kind:`error`,error:`Persistent tool "${e.tool}" requires an unconditional stub.`});let r=n.find(t=>t.constraints.every(({property:t,validator:n})=>isObject(e.input)&&Object.hasOwn(e.input,t)&&n.validate(e.input[t]).valid));if(r===void 0)return this.record(e,{kind:`real`});let i=r.outcomes??[r.outcome],a=Math.min(this.positions.get(r.id)??0,i.length-1);return this.positions.set(r.id,a+1),this.record(e,{kind:`stub`,ruleId:r.id,position:a,outcome:i[a]})}record(e,t){return this.results.set(e.callId,t),t}fail(e,t){return this.results.get(e)?.kind===`stub`?{kind:`error`,error:t}:{kind:`real`}}};export{StubPlayback};

package/dist/src/tool-stubs/rules.d.ts

@@ -0,0 +1,3 @@
+import type { ToolStub } from "#tool-stubs/types.js";
+/** Validates stubs before creating the session. */
+export declare function parseToolStubs(value: unknown): readonly ToolStub[];

package/dist/src/tool-stubs/rules.js

@@ -0,0 +1 @@
+import{z}from"#compiled/zod/index.js";import{parseJsonValue}from"#shared/json.js";import{createStubValidator,validateStubConstraint}from"#tool-stubs/schema.js";const ruleSchema=z.strictObject({id:z.string().min(1),tool:z.string().min(1),match:z.record(z.string(),z.union([z.boolean(),z.record(z.string(),z.json())])).optional()}),outcomeSchema=z.union([z.strictObject({response:z.json()}),z.strictObject({throw:z.strictObject({message:z.string(),name:z.string().min(1).optional()})})]),toolStubsSchema=z.array(z.union([ruleSchema.extend({outcome:outcomeSchema}),ruleSchema.extend({outcomes:z.tuple([outcomeSchema]).rest(outcomeSchema)})])).max(100);function parseToolStubs(e){boundStubConfiguration(e);let t=toolStubsSchema.parse(parseJsonValue(e)),n=new Set;for(let e of t){if(n.has(e.id))throw Error(`Duplicate tool stub id "${e.id}".`);if(n.add(e.id),[`connection_execute`,`connection_search`].includes(e.tool.split(`/`).at(-1)))throw Error(`Cannot stub connection_execute or connection_search. Stub a specific connection operation, such as linear__list_issues.`);for(let[t,n]of Object.entries(e.match??{})){validateStubConstraint(n,e.id,t);try{createStubValidator(n)}catch(n){throw Error(`Could not create matcher "${t}" in tool stub "${e.id}".`,{cause:n})}}}return t}function boundStubConfiguration(e){let t=[{value:e,depth:0}],n=0,r=0;for(;t.length>0;){let e=t.pop();if(++n>2e4||e.depth>32)throw Error(`Tool stubs exceed the size or nesting limit.`);if(typeof e.value==`string`&&(r+=e.value.length),e.value!==null&&typeof e.value==`object`)for(let[n,i]of Object.entries(e.value)){if(n===`__proto__`)throw Error(`Tool stubs cannot contain prototype keys.`);r+=n.length,t.push({value:i,depth:e.depth+1})}if(r>1e6)throw Error(`Tool stubs exceed the size or nesting limit.`)}}export{parseToolStubs};

package/dist/src/tool-stubs/schema.d.ts

@@ -0,0 +1,4 @@
+import { Validator } from "#compiled/@cfworker/json-schema/index.js";
+import type { JsonObject } from "#shared/json.js";
+export declare function validateStubConstraint(value: unknown, ruleId: string, property: string): void;
+export declare function createStubValidator(value: JsonObject | boolean): Validator;

package/dist/src/tool-stubs/schema.js

@@ -0,0 +1 @@
+import{Validator}from"#compiled/@cfworker/json-schema/index.js";const schema={$ref:`#`},schemaList={type:`array`,minItems:1,items:schema},propertyName={type:`string`,not:{enum:Object.getOwnPropertyNames(Object.prototype)}},schemaMap={type:`object`,propertyNames:propertyName,additionalProperties:schema},strings={type:`array`,uniqueItems:!0,items:propertyName},nonnegativeInteger={type:`integer`,minimum:0},jsonType={enum:[`array`,`boolean`,`integer`,`null`,`number`,`object`,`string`]},constraintSchema=new Validator({anyOf:[{type:`boolean`},{type:`object`,additionalProperties:!1,properties:{type:{anyOf:[jsonType,{type:`array`,minItems:1,uniqueItems:!0,items:jsonType}]},const:{type:[`string`,`number`,`boolean`,`null`]},enum:{type:`array`,minItems:1,uniqueItems:!0,items:{type:[`string`,`number`,`boolean`,`null`]}},title:{type:`string`},description:{type:`string`},default:!0,minimum:{type:`number`},maximum:{type:`number`},exclusiveMinimum:{type:`number`},exclusiveMaximum:{type:`number`},minLength:nonnegativeInteger,maxLength:nonnegativeInteger,pattern:{type:`string`,format:`regex`},minItems:nonnegativeInteger,maxItems:nonnegativeInteger,items:schema,prefixItems:schemaList,contains:schema,minProperties:nonnegativeInteger,maxProperties:nonnegativeInteger,properties:schemaMap,propertyNames:schema,required:strings,additionalProperties:schema,allOf:schemaList,anyOf:schemaList,oneOf:schemaList,not:schema,if:schema,then:schema,else:schema}}]},`2020-12`);function validateStubConstraint(e,t,n){let r=constraintSchema.validate(e);if(!r.valid){let e=r.errors.at(-1),i=e.keyword===`false`?`Unsupported JSON Schema keyword.`:e.error;throw Error(`Invalid matcher "${n}" in tool stub "${t}" at ${e.instanceLocation}: ${i}`)}}function createStubValidator(e){return new Validator(structuredClone(e),`2020-12`)}export{createStubValidator,validateStubConstraint};

package/dist/src/tool-stubs/target.d.ts

@@ -0,0 +1,8 @@
+import type { StubScope } from "#tool-stubs/types.js";
+/** Qualify names for stub matching without changing the names sent to the model. */
+export declare function stubToolPath(scope: StubScope | undefined, tool: string): string;
+export declare function findStubTarget(scope: StubScope | undefined, tool: string): {
+    scope: StubScope;
+    tool: string;
+} | undefined;
+export declare function stubCallId(sessionId: string, turnId: string, callId: string): string;

package/dist/src/tool-stubs/target.js

@@ -0,0 +1 @@
+function stubToolPath(e,t){return e?.agentPath===void 0?t:`${e.agentPath}/${t}`}function findStubTarget(e,t){if(e!==void 0)return t=stubToolPath(e,t),e.rules.some(e=>e.tool===t)?{scope:e,tool:t}:void 0}function stubCallId(e,t,n){return`${e}:${t}:${n}`}export{findStubTarget,stubCallId,stubToolPath};

package/dist/src/tool-stubs/types.d.ts

@@ -0,0 +1,56 @@
+import type { JsonObject, JsonValue } from "#shared/json.js";
+/** Return JSON or immediately throw an error for a matching tool call. */
+export type ToolStubOutcome = {
+    readonly response: JsonValue;
+    readonly throw?: never;
+} | {
+    readonly response?: never;
+    readonly throw: {
+        readonly message: string;
+        /** Defaults to Error. Sets the name, not a custom JavaScript class. */
+        readonly name?: string;
+    };
+};
+/** Stub outcomes selected by tool name and input fields. */
+export type ToolStub = {
+    readonly id: string;
+    /** Use list_tasks for a root tool or researcher/list_tasks for a local subagent's tool. */
+    readonly tool: string;
+    /** Each named input property must exist and satisfy its JSON Schema. */
+    readonly match?: Readonly<Record<string, JsonObject | boolean>>;
+} & ({
+    readonly outcome: ToolStubOutcome;
+    readonly outcomes?: never;
+} | {
+    readonly outcome?: never;
+    readonly outcomes: readonly [ToolStubOutcome, ...ToolStubOutcome[]];
+});
+export interface StubCall {
+    /** Combines the session, turn, and tool call IDs. */
+    readonly callId: string;
+    readonly tool: string;
+    readonly input: unknown;
+    readonly persistent?: boolean;
+}
+export type StubResult = {
+    readonly kind: "real";
+} | {
+    readonly kind: "error";
+    readonly error: string;
+} | {
+    readonly kind: "stub";
+    readonly ruleId: string;
+    readonly position: number;
+    readonly outcome: ToolStubOutcome;
+};
+/** Rules and workflow routing set by the server after it authorizes tool stubs. */
+export interface StubScope {
+    readonly token: string;
+    readonly rules: readonly ToolStub[];
+    readonly rootSessionId?: string;
+    readonly agentPath?: string;
+}
+export declare const STUB_CONTEXT_KEY = "eve.toolStubs";
+export declare const STUB_MATCHES_NAMESPACE = "eve.tool-stubs.matches";
+export declare const STUB_FAILURE_NAMESPACE = "eve.tool-stubs.failure";
+export declare const stubResponseNamespace: (callId: string) => string;

package/dist/src/tool-stubs/types.js

@@ -0,0 +1 @@
+const STUB_CONTEXT_KEY=`eve.toolStubs`,STUB_MATCHES_NAMESPACE=`eve.tool-stubs.matches`,STUB_FAILURE_NAMESPACE=`eve.tool-stubs.failure`,stubResponseNamespace=e=>`eve.tool-stubs.${e}`;export{STUB_CONTEXT_KEY,STUB_FAILURE_NAMESPACE,STUB_MATCHES_NAMESPACE,stubResponseNamespace};

package/dist/src/tool-stubs/validate-targets.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedAgentGraphBundle } from "#runtime/graph.js";
+import type { ToolStub } from "#tool-stubs/types.js";
+export declare class InvalidToolStubTargetError extends Error {
+}
+/** Check compiled tools without running dynamic resolvers or contacting connections. */
+export declare function validateToolStubTargets(rules: readonly ToolStub[], graph: ResolvedAgentGraphBundle): void;

package/dist/src/tool-stubs/validate-targets.js

@@ -0,0 +1 @@
+var InvalidToolStubTargetError=class extends Error{};function validateToolStubTargets(e,t){for(let n of e)if(!hasToolPath(t,n.tool.split(`/`)))throw new InvalidToolStubTargetError(`Tool stub "${n.id}" names an unknown or unsupported tool path "${n.tool}".`)}function hasToolPath(e,t){if(t.some(e=>e.length===0))return!1;let n=e.root;for(let[r,i]of t.entries()){let a=n.turnAgent.tools.find(e=>e.name===i);if(r===t.length-1)return a===void 0?n.agent.dynamicToolResolvers.some(e=>e.slug!==`connection_tools`&&(e.extensionNamespace===void 0||i.startsWith(`${e.extensionNamespace}__`)))||n.subagentRegistry.dynamicResolvers.some(e=>e.name===i)||i.includes(`__`)&&((n.agent.dynamicConnectionResolvers?.length??0)>0||n.agent.connections.some(e=>i.startsWith(`${e.connectionName}__`))):a.behavior?.handling?.kind!==`provider-tool`;if(a===void 0)return n.subagentRegistry.dynamicResolvers.some(e=>e.name===i);let o=a.behavior?.handling;if(o?.kind!==`dispatch`||o.target.kind!==`subagent-call`&&o.target.kind!==`self-agent-call`)return!1;n=e.nodesByNodeId.get(o.target.nodeId)}return!1}export{InvalidToolStubTargetError,validateToolStubTargets};

package/dist/src/tools/provided/ask-question-workflow.js

@@ -1 +1 @@
-async function executeAskQuestionTool(e,t){"use workflow";return toAskQuestionOutput(await t.ask(toAskQuestionRequest(e)))}function toAskQuestionRequest(e){let t=e.options?.map(e=>({description:e.description,id:e.label,label:e.label}));return{allowFreeform:!0,display:t===void 0?`text`:`select`,prompt:e.question,...t!==void 0&&{options:t}}}function toAskQuestionOutput(e){switch(e.status){case`answered`:return{answer:e.optionId??e.text??``,status:`answered`};case`cancelled`:return{interrupted:!0};case`unavailable`:return{status:`unavailable`}}}executeAskQuestionTool.workflowId=`workflow//eve@0.74.0//executeAskQuestionTool`;export{executeAskQuestionTool,toAskQuestionOutput,toAskQuestionRequest};
+async function executeAskQuestionTool(e,t){"use workflow";return toAskQuestionOutput(await t.ask(toAskQuestionRequest(e)))}function toAskQuestionRequest(e){let t=e.options?.map(e=>({description:e.description,id:e.label,label:e.label}));return{allowFreeform:!0,display:t===void 0?`text`:`select`,prompt:e.question,...t!==void 0&&{options:t}}}function toAskQuestionOutput(e){switch(e.status){case`answered`:return{answer:e.optionId??e.text??``,status:`answered`};case`cancelled`:return{interrupted:!0};case`unavailable`:return{status:`unavailable`}}}executeAskQuestionTool.workflowId=`workflow//eve@0.75.0//executeAskQuestionTool`;export{executeAskQuestionTool,toAskQuestionOutput,toAskQuestionRequest};

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

@@ -1 +1 @@
-import{sleep}from"#compiled/@workflow/core/index.js";async function executeSleepTool(e,t){"use workflow";let n=new Promise(e=>t.abortSignal.addEventListener(`abort`,()=>e(`interrupted`),{once:!0})),r=sleep(Math.ceil(e.seconds*1e3)).then(()=>`elapsed`);return await Promise.race([r,n])===`elapsed`?{waitedSeconds:e.seconds}:{interrupted:!0}}executeSleepTool.workflowId=`workflow//eve@0.74.0//executeSleepTool`;export{executeSleepTool};
+import{sleep}from"#compiled/@workflow/core/index.js";async function executeSleepTool(e,t){"use workflow";let n=new Promise(e=>t.abortSignal.addEventListener(`abort`,()=>e(`interrupted`),{once:!0})),r=sleep(Math.ceil(e.seconds*1e3)).then(()=>`elapsed`);return await Promise.race([r,n])===`elapsed`?{waitedSeconds:e.seconds}:{interrupted:!0}}executeSleepTool.workflowId=`workflow//eve@0.75.0//executeSleepTool`;export{executeSleepTool};

package/dist/src/vue/index.js

@@ -1,4 +1,4 @@
-import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DOOXadF0.js";
+import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DK_T88EP.js";
 
 //#region src/client/tool-call-state.ts
 function toolCallState(conversation, callId, options = {}) {

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

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

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

@@ -123,7 +123,7 @@ Note: consider the privacy, confidentiality, and user-experience implications fo
 
 A delegated subagent publishes progress on its own child-session stream. When a subagent tool call or a workflow tool's `ctx.agent` opens a session, the parent emits `agent.started` with the call's `callId` and `turnId`, its `taskId` when the call runs as a task, the child's `sessionId`, and a `streamPath` that a client follows with `session.agent(started).stream()`. A subagent tool call is a [task](#task-events) whose `task.started` has `kind: "agent"`: its `task.started` and `task.settled` carry the call, and `task.settled.data.output` is the child's reply. A call that fails before the child session opens has no `agent.started`. A settled call does not end the child session; later calls with the same `taskId` reach it.
 
-A question or sign-in from inside a running call does not end the turn. This covers a workflow tool's `ctx.ask()`, including the built-in `ask_question` tool, and a delegated subagent's question or sign-in. The stream emits `input.requested` or `authorization.required`, then `turn.waiting` with `on: "input"` and the open turn's `turnId`. After the answer or sign-in, the turn resumes with the next `step.started` for the same `turnId`, and only `turn.completed`, `turn.failed`, or `turn.cancelled` ends it. When you answer a question that belongs to a workflow tool or a subagent, the session you answer on emits `input.resolved` for it as it routes the answer down. While other relayed questions are still pending, it then emits `turn.waiting` with `on: "input"` again. If the workflow tool run that relayed a question or approval ends before anyone answers, that session emits `input.resolved` with `outcome: "cancelled"` for it. This covers the run's own `ctx.ask()` questions and requests from sessions it opened with `ctx.agent`. A cancelled turn does the same for every question or approval the session relays. A sign-in or tool approval the turn raises itself holds it the same way, also with `on: "input"`. A message from the same person steers the turn and cancels the request: a sign-in reports `authorization.completed` with `outcome: "declined"`, and an approval reports `input.resolved` with `outcome: "ignored"`. Messages from other people wait until the turn ends. Cancelling the turn ends both: a held sign-in reports `authorization.completed` with `outcome: "declined"`, and a held approval reports `input.resolved` with `outcome: "cancelled"`.
+A question or sign-in from inside a running call does not end the turn. This covers a workflow tool's `ctx.ask()`, including the built-in `ask_question` tool, and a delegated subagent's question or sign-in. The stream emits `input.requested` or `authorization.required`, then `turn.waiting` with `on: "input"` and the open turn's `turnId`. After the answer or sign-in, the turn resumes with the next `step.started` for the same `turnId`, and only `turn.completed`, `turn.failed`, or `turn.cancelled` ends it. When you answer a question that belongs to a workflow tool or a subagent, the session you answer on emits `input.resolved` for it as it routes the answer down. A subagent's tool approval instead stays open until the subagent resolves it, and the session relays that subagent's `input.resolved`. While other relayed questions are still pending, it then emits `turn.waiting` with `on: "input"` again. If the workflow tool run that relayed a question or approval ends before anyone answers, that session emits `input.resolved` with `outcome: "cancelled"` for it. This covers the run's own `ctx.ask()` questions and requests from sessions it opened with `ctx.agent`. A cancelled turn does the same for every question or approval the session relays. A sign-in or tool approval the turn raises itself holds it the same way, also with `on: "input"`. A message from the same person steers the turn and cancels the request: a sign-in reports `authorization.completed` with `outcome: "declined"`, and an approval reports `input.resolved` with `outcome: "ignored"`. Messages from other people wait until the turn ends. Cancelling the turn ends both: a held sign-in reports `authorization.completed` with `outcome: "declined"`, and a held approval reports `input.resolved` with `outcome: "cancelled"`.
 
 ### Task events
 
@@ -219,7 +219,7 @@ Message sends default to `"steer"`. Before assistant output begins, eve interrup
 
 If the session is waiting on a human-in-the-loop approval, respond with the channel’s Approve or Cancel controls. Text that doesn't match an option doesn't approve the call. From the person the turn serves, it steers the turn and cancels the approval, even when sent with `turnPolicy: "queue"`, since the turn can't end until that person acts; from anyone else, it waits until the turn ends. If they had already approved some calls in the batch, those calls still run. Cancelling the turn withdraws the approval, and a later answer to it approves nothing.
 
-A pending `ctx.ask()` question from a tool, such as `ask_question`, can be answered with plain text. When it is the only pending question, a message that matches an option answers it, and so does any message when the question allows free text. The stream records that message as `message.received`, carrying its delivery id, just before the `input.resolved` it produces. Otherwise eve does not guess which question the text addresses: the message follows the normal `turnPolicy`. A steering message withdraws the questions of the `execute` workflow tool calls the turn waits on, which resolve as `cancelled`; a task's questions stay open. Questions from subagents always need a structured response. Use structured responses to target requests unambiguously.
+A pending prompt, whether a `ctx.ask()` question from a tool such as `ask_question`, a tool approval, or a session-limit prompt, can be answered with plain text, including prompts proxied from a subagent. A message answers the first open prompt, as described in [Several requests at once](/docs/human-in-the-loop#several-requests-at-once): a reply that matches one of its options, such as `approve` or `continue`, answers it as if the sender had pressed that option, and so does any message when the prompt allows free text. Send one message per prompt to answer several. The stream records a message that answers a question as `message.received`, carrying its delivery id, just before the `input.resolved` it produces. A message that doesn't answer the first open prompt follows the normal `turnPolicy`. A steering message withdraws the questions of the `execute` workflow tool calls the turn waits on, which resolve as `cancelled`; a task's questions stay open. Use structured responses to target requests unambiguously.
 
 A structured response matches any currently pending request by ID, not only the newest batch. It becomes stale only after that request was answered, cleared, or cancelled. eve delivers a stale response to the model as a new user message, and the model decides whether the old selection still matters. A stale approval never authorizes the earlier tool call; the model must request the action and approval again if they are still needed.
 

package/docs/evals/meta.json

@@ -1,5 +1,14 @@
 {
   "title": "Evals",
   "defaultOpen": false,
-  "pages": ["overview", "cases", "assertions", "judge", "targets", "reporters", "running"]
+  "pages": [
+    "overview",
+    "cases",
+    "assertions",
+    "tool-stubs",
+    "judge",
+    "targets",
+    "reporters",
+    "running"
+  ]
 }

package/docs/evals/overview.mdx

@@ -7,6 +7,8 @@ An eval is a scored check that runs your agent against real sessions and grades
 
 Evals exercise the same HTTP surface your users hit. The runner boots (or targets) a real agent server, drives sessions through the [TypeScript client](../guides/client/overview) protocol, and grades what comes back, so a passing eval means the agent booted, accepted a request, and produced the result you asserted.
 
+Define [tool stubs](./tool-stubs) in your eval to control tool results, then assert on the agent's tool calls and responses.
+
 ## `defineEval`
 
 eve discovers evals under the app-root `evals/` directory, in `.eval.ts` files. Each file is one eval by default. A file can also default-export an array to fan out over a dataset (see [Cases](./cases)). The file path is the eval's identity, so you don't author an `id` or `name`. Directories group related evals (`evals/weather/brooklyn-forecast.eval.ts` becomes id `weather/brooklyn-forecast`).

package/docs/evals/tool-stubs.mdx

@@ -0,0 +1,257 @@
+---
+title: "Tool Stubs"
+description: "Define tool outcomes and outcome sequences in your evals."
+---
+
+Pass `stubs` when creating an eval session to replace selected tool executions with JSON responses. The same rules work against local and deployed agents, without deploying mock functions or keeping the runner connected to answer tool calls.
+
+Stubs specify what tools return. [Assertions](./assertions) check what the agent does and tells the user. Unused stubs produce a warning without failing the eval.
+
+## Author an eval
+
+```ts title="evals/complete-task.eval.ts"
+import { defineEval } from "eve/evals";
+
+export default defineEval({
+  async test(t) {
+    const session = await t.session({
+      stubs: [
+        {
+          id: "tasks",
+          tool: "list_tasks",
+          outcomes: [
+            {
+              response: {
+                tasks: [
+                  { id: "milk", title: "Buy milk" },
+                  { id: "dog", title: "Walk dog" },
+                  { id: "rent", title: "Pay rent" },
+                ],
+              },
+            },
+            {
+              response: {
+                tasks: [
+                  { id: "dog", title: "Walk dog" },
+                  { id: "rent", title: "Pay rent" },
+                ],
+              },
+            },
+          ],
+        },
+        {
+          id: "complete-milk",
+          tool: "complete_task",
+          match: { task_id: { const: "milk" } },
+          outcome: { response: { success: true } },
+        },
+      ],
+    });
+
+    const first = await session.send("What tasks do I have?");
+    first.expectOk();
+    first.calledTool("list_tasks", { count: 1 });
+    first.messageIncludes("Buy milk");
+
+    const second = await session.send("Complete Buy milk, then list my remaining tasks.");
+    second.expectOk();
+    second.calledTool("complete_task", { input: { task_id: "milk" }, count: 1 });
+    second.toolOrder(["complete_task", "list_tasks"]);
+    second.messageIncludes("Walk dog");
+    second.messageIncludes("Pay rent");
+  },
+});
+```
+
+Use your agent's actual tool names and response shapes. The client accepts the same option on `client.sessions.create({ stubs })` or `client.sessions.create({ message, stubs })`.
+
+These responses describe a sequence, not a simulated task database. The second `list_tasks` call returns two tasks even if `complete_task` was never called. The completion and order assertions check that the agent actually requested the write; testing a real database update requires the real tool.
+
+## Stub fields
+
+| Field      | Meaning                                                                                                                                |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`       | Your session-unique rule identifier. eve uses it to track this rule's response sequence. It is neither a tool name nor a tool-call ID. |
+| `tool`     | The existing tool's name, optionally qualified by its local subagent path.                                                             |
+| `match`    | Optional input-property constraints, expressed as JSON Schema. Omit it or use `{}` to match any valid input.                           |
+| `outcome`  | One outcome repeated on every matching call, such as `{ response: { tasks: [] } }`.                                                    |
+| `outcomes` | A nonempty array of outcomes returned in sequence. Use exactly one of `outcome` or `outcomes`.                                         |
+
+Each outcome contains exactly one of `response` or `throw`. `response` holds the JSON returned by the tool; `throw` describes an error raised immediately instead. The enclosing outcome is not part of the tool's response. Top-level `response` and `responses` are not accepted.
+
+Exposing rule IDs and response positions in traces is a follow-up: [AX-5157](https://linear.app/vercel/issue/AX-5157).
+
+Stubs are plain JSON and can be shared between evals:
+
+```ts title="evals/fixtures/tasks.ts"
+import type { ToolStub } from "eve/evals";
+
+export const taskStubs = [
+  { id: "tasks", tool: "list_tasks", outcome: { response: { tasks: [] } } },
+] satisfies readonly ToolStub[];
+```
+
+Pass the fixture to `t.session({ stubs: taskStubs })`. Each session has its own sequence position. Both `eve/evals` and `eve/client` export `ToolStub` and `ToolStubOutcome`. These types check the JSON contract; they do not infer the response type from your tool definition.
+
+## Match tool arguments
+
+**Rules are evaluated from top to bottom. The first matching stub wins.** Put specific rules before an unconditional fallback:
+
+```ts
+const stubs = [
+  {
+    id: "milk",
+    tool: "complete_task",
+    match: { task_id: { const: "milk" } },
+    outcome: { response: { success: true } },
+  },
+  { id: "other-tasks", tool: "complete_task", outcome: { response: { success: false } } },
+];
+```
+
+A call for milk receives success; other valid calls receive the fallback. Reversing these rules makes the unconditional rule win every time. If no rule matches, eve executes the real tool. A broken stub or failure processing its response fails the eval, even if the agent recovers. An intentional `throw` outcome is a normal tool failure that the eval can assert on. Neither falls back to real execution.
+
+If eve cannot record an output-processing failure, it cancels the workflow serving stubs. The original tool error or fallback is preserved, but verification rejects the eval. Failed or cancelled stub sessions cannot pass verification.
+
+Every property listed in `match` must exist and satisfy its constraint. Extra top-level properties are allowed:
+
+```json
+{
+  "id": "open-tasks",
+  "tool": "search_tasks",
+  "match": {
+    "filter": {
+      "type": "object",
+      "properties": { "status": { "const": "open" } },
+      "required": ["status"]
+    },
+    "query": { "type": "string", "pattern": "\\b(?i:milk)\\b" },
+    "tags": { "type": "array", "contains": { "const": "urgent" } }
+  },
+  "outcome": { "response": { "tasks": ["Buy milk"] } }
+}
+```
+
+Nested properties are optional unless listed in `required`. Matching does not coerce values, apply defaults, or change arguments. The real tool schema validates input before replacement; normal approvals and output processing still apply.
+
+Constraints use a reference-free subset of JSON Schema 2020-12: types, scalar `const` and `enum`, string patterns and bounds, numeric bounds, array items/contains, object properties/required/additionalProperties, and logical/conditional schemas. `pattern` uses JavaScript regular expressions. Schema validation, regex syntax checks, and validator initialization run before session creation.
+
+Unsupported constraints fail setup: `patternProperties`, references, formats, `multipleOf`, `minContains`, `maxContains`, `uniqueItems`, dependencies, and object/array values in `const` or `enum`. Nested `properties` and `required` cannot use inherited property names such as `constructor` or `toString`. Use nested properties or array items to match structured values.
+
+Unknown static tool names, invalid local-agent paths, and paths into remote agents fail session creation. Dynamic names and connection operations are checked where possible; unresolved names are allowed. After the eval, unused rule IDs are reported as warnings. Use tool assertions when a call must happen.
+
+Configuration is limited to 100 rules, 20,000 JSON nodes, nesting depth 32, and approximately one million characters. The `__proto__` property name is reserved.
+
+## Sequences and session scope
+
+`outcome` repeats on every matching call. `outcomes` advances on each new matching call, then repeats its final entry. For example, `outcomes: [{ response: "pending" }, { response: "completed" }]` returns `"pending"` once and `"completed"` thereafter. Only the selected rule advances; exhaustion never selects a later rule.
+
+Two calls within one agent turn consume two entries. Later turns continue the same sequence. Calls awaiting or denied approval do not consume entries. Each session supports up to 10,000 recorded calls.
+
+Choose the rules at session creation; they stay fixed for that session. Local subagents share playback through explicit tool paths, and deployment handoffs preserve it. An independent session starts at the first response.
+
+eve's transparent internal workflow replay reuses the recorded outcome without consuming another entry.
+
+Parallel calls consume responses in arrival order, which can vary. Use separate argument matchers when particular arguments must receive particular responses.
+
+## Permit tool replacement
+
+Tool replacement is denied by default, including in development. With [Vercel OIDC](../guides/auth-and-route-protection#verceloidc), put the permission on the eval runner's verified subject:
+
+```ts title="agent/channels/eve.ts"
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+
+export default eveChannel({
+  auth: [
+    vercelOidc({
+      subjects: [
+        vercelSubject({ teamSlug: "acme", projectName: "app" }),
+        {
+          subject: vercelSubject({ teamSlug: "acme", projectName: "eval-runner" }),
+          allowToolStubs: true,
+        },
+      ],
+    }),
+  ],
+});
+```
+
+Both projects can authenticate; only the eval runner receives replacement permission. `vercelSubject` defaults to production; pass `environment: "*"` to include all environments. The target's server configuration supplies the grant after token verification. Request JSON cannot grant permission, and user principals do not inherit project grants.
+
+Custom authenticators can return the same `allowToolStubs: true` after verifying the caller. See [authentication and route protection](../guides/auth-and-route-protection#tool-replacement-permission) for the grant rules and a local development example.
+
+Permission is checked at session creation before identity projection. Later messages and result reads use normal channel authentication. Anyone your channel admits to an existing session can use its stubs. Your application's session-access policy must provide the required isolation; an isolated eval deployment can use the same agent code.
+
+The stub verification endpoint also requires `allowToolStubs`, checked before reading workflow status.
+
+## Supported tools and subagents
+
+Stubs replace execution of existing ordinary, dynamic, and workflow tools. They retain the real tool's input schema, approvals, and output processing. A stub does not register a new tool or make it visible to the model.
+
+Ordinary tools with configured stub rules can emit an extra `action.partial` containing the final response. This also applies when no rule matches and the real tool returns a non-streaming result. The final `action.result` remains correct, and real streaming still delivers progress. Use `action.result` for final-result assertions. Removing the extra event is tracked in [AX-5164](https://linear.app/vercel/issue/AX-5164).
+
+### Subagents
+
+Stubbing a delegation tool returns its configured result without starting the subagent. Persistent tools implemented with `serve`, including the built-in `agent`, require an unconditional stub: omit `match` or use `{}`. Mixing real and mocked calls to the same persistent tool is unsupported.
+
+To let a local subagent run but replace its tools, use `/` to qualify the delegation path:
+
+```ts
+const stubs = [
+  { id: "root-tasks", tool: "list_tasks", outcome: { response: ["Root task"] } },
+  { id: "research-tasks", tool: "researcher/list_tasks", outcome: { response: ["Research task"] } },
+  { id: "nested-tasks", tool: "researcher/assistant/list_tasks", outcome: { response: [] } },
+];
+```
+
+`researcher` replaces the whole delegation; `researcher/list_tasks` replaces only that subagent's list tool. The built-in `agent` uses `agent/list_tasks`. Model-visible names stay unchanged. A root rule never implicitly matches a subagent's same-named tool.
+
+Repeated subagent sessions at the same path share that rule's sequence. Different paths use different rules. Remote agents do not receive the configuration; replace their whole delegation tool instead.
+
+### Connections and provider tools
+
+Use the qualified operation name, such as `linear__list_issues` or `researcher/linear__list_issues`. Put operation arguments in `match` and its JSON result in `outcome.response`, or in each sequence entry's `response`.
+
+Connection authentication and discovery stay live so eve can validate the operation and its arguments. Stubs do not provide an offline connection. The framework's `connection_search` and `connection_execute` tools cannot themselves be replaced.
+
+Tools executed by the model provider, such as provider-hosted web search, have no eve executor to replace. A search tool implemented in your own agent can be stubbed.
+
+## Inject tool errors
+
+Use `throw` to test how the agent handles a failed tool call. Mix errors and responses to test recovery:
+
+```ts
+const stubs = [
+  {
+    id: "tasks",
+    tool: "list_tasks",
+    outcomes: [
+      { throw: { name: "TimeoutError", message: "Task service timed out" } },
+      { response: { tasks: [] } },
+    ],
+  },
+];
+```
+
+`throw.message` is required. `throw.name` is optional and defaults to `"Error"`. eve creates an ordinary JavaScript `Error` with that name and message; it does not instantiate custom error classes. `TimeoutError` reports a timeout immediately, without delaying the call or testing an actual deadline.
+
+Ordinary tools and connection operations expose the error message to the model, without the error name. Workflow task errors also retain the name. Put any details the model needs to act on in `message`.
+
+Use `outcome: { throw: { message: "Service unavailable" } }` to fail every matching call. A sequence consumes one entry per new call, whether it returns or throws, and repeats its final entry. Workflow replay reuses the same recorded outcome.
+
+An injected exception follows the tool's normal error handling. Ordinary and blocking workflow calls are recorded as failed; background tasks report failure when they settle. The model can report the failure or try again. Assert the failed call explicitly:
+
+```ts
+const turn = await session.send(
+  "List my tasks once. If the service fails, explain the failure and wait for me to retry.",
+);
+turn.expectOk();
+turn.calledTool("list_tasks", { status: "failed", count: 1 });
+```
+
+The eval can pass when the agent handles the failure correctly. `noFailedActions()` still rejects the failed call, so use explicit assertions for expected failures. Stub infrastructure and response-processing failures still fail verification.
+
+This works for ordinary tools, workflow tools, whole-agent replacements, and qualified connection operations. An exception in a persistent workflow tool ends that task; retry with a new call, rather than its failed task ID. Normal approvals apply before an outcome is consumed.
+
+Returning `{ response: { error: "timeout" } }` remains ordinary JSON. Only `throw` raises an exception.

package/docs/extensions.md

@@ -178,7 +178,7 @@ A mount gives the extension's contributions a namespace. Updating the package up
 
 ### Install the package
 
-Install the extension with the package manager already used by the consumer's agent project. Fresh eve projects use pnpm:
+Install the extension with the package manager already used by the consumer's agent project. For example, in a pnpm project:
 
 ```bash
 pnpm add @acme/crm

package/docs/guides/auth-and-route-protection.md

@@ -113,6 +113,8 @@ Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/o
 
 Auth fails closed: routes reject unauthenticated traffic by default, and the OIDC user branch verifies `external_sub` against `VERCEL_PROJECT_ID` and the deployment environment, returning `false` when either is unset. An external-subject token cannot authenticate on a deployment that hasn't pinned its project.
 
+Subject entries can also be objects: `{ subject: vercelSubject({ teamSlug: "acme", projectName: "eval-runner" }), allowToolStubs: true }`. This explicitly permits that verified service/runtime caller to create [stubbed eval sessions](../evals/tool-stubs). Plain subject strings and implicit current-project acceptance grant ordinary access only. Custom authenticators can return the same permission in their authentication result; it is not part of persisted or forwarded session identity.
+
 #### `subjects` patterns and `vercelSubject(...)`
 
 Each `subjects` entry is matched against the token's `sub` claim, which Vercel shapes as `owner:<team>:project:<name>:environment:<env>`. Hand-writing that string is a footgun: a typo silently rejects every caller, and an over-broad `*` wildcard silently lets unrelated ones in. Build the pattern with `vercelSubject(...)` instead. It rejects malformed input at construction time, and defaults `environment` to `"production"` when you omit it, so an unspecified environment cannot silently accept preview or development tokens:
@@ -298,6 +300,29 @@ Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolv
 
 Route auth does not enforce session ownership. If multiple users or tenants can reach the same route, you must implement the per-user, per-tenant, or per-session authorization your application requires.
 
+## Tool replacement permission
+
+Creating a [stubbed eval session](../evals/tool-stubs) requires an explicit `allowToolStubs: true` in the verified route authentication result. The target's server configuration grants permission; request JSON cannot. With `vercelOidc`, put the grant on a `subjects` entry as shown above. Any matching entry with the grant permits replacement; other entries do not revoke it. Implicit current-project acceptance and user principals do not inherit project grants.
+
+Custom authenticators return the same grant after verifying their caller. For example, this alternative channel permits stubs only in local development:
+
+```ts
+import { localDev } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+
+const authenticate = localDev();
+export default eveChannel({
+  auth: async (request) => {
+    const caller = await authenticate(request);
+    return caller ? { ...caller, allowToolStubs: true } : null;
+  },
+});
+```
+
+The channel checks the grant before forwarded-principal handling or `onMessage` projection. It removes the grant before using the identity for forwarding, audience classification, or session persistence. This is an authentication-result permission, not a session attribute.
+
+Later messages, approvals, controls, and result reads use normal channel authentication. There is no additional creator-only rule or replacement-permission recheck. Anyone your channel admits to an existing session can use its configured stubs; apply the same application-specific session-access policy you need for ordinary sessions.
+
 ## Tool and connection auth
 
 Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools should resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token; eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.

package/docs/guides/dynamic-capabilities.md

@@ -221,9 +221,16 @@ same name; namespace one map key to remove the ambiguity.
 
 Dynamic connections support `session.started` and `turn.started`. A turn result
 replaces that file's session result for the turn, including when the turn
-handler returns `null`. A throwing or invalid handler fails the lifecycle
-without rebuilding the registry, so a static connection shadowed by the
-dynamic result cannot reappear as a fallback.
+handler returns `null`. A throwing or invalid handler fails the current turn
+and parks the session, so a later message can retry after the dependency
+recovers. The failed lifecycle does not rebuild the registry, so a static
+connection shadowed by the dynamic result cannot reappear as a fallback.
+
+Recovery needs another message. eve does not keep the input from the failed
+turn or replay it, so the caller must send it again once the dependency is
+back. This applies to the first message of a session too. A scheduled run
+whose resolver fails is not retried; the session stays idle until the next
+scheduled run or message arrives.
 
 eve may run the active session and turn handlers again when a parked turn
 resumes or a durable step retries. This rebuilds live auth, header, approval,