eve 0.25.2 → 0.26.0

package/dist/src/source-change/agent-config-string-path.d.ts

@@ -0,0 +1,18 @@
+export { checkAgentConfigSource } from "./agent-config-ast.js";
+export type AgentConfigStringPathPatch = {
+    readonly kind: "set";
+    readonly value: string;
+} | {
+    readonly kind: "remove";
+    readonly removable?: (value: string) => boolean;
+};
+export type AgentConfigStringPathEdit = {
+    readonly kind: "applied";
+    readonly nextSource: string;
+} | {
+    readonly kind: "bail";
+    readonly reason: string;
+    readonly line: number;
+};
+/** Safely applies one literal string leaf below `defineAgent({ ... })`. */
+export declare function applyAgentConfigStringPath(sourceText: string, path: readonly [string, ...string[]], patch: AgentConfigStringPathPatch): Promise<AgentConfigStringPathEdit>;

package/dist/src/source-change/agent-config-string-path.js

@@ -0,0 +1,2 @@
+import{checkAgentConfigSource,escapeForQuote,isAstNode,keyMatches,lineAt,parseAgentObject,unwrapExpression}from"./agent-config-ast.js";async function applyAgentConfigStringPath(e,n,r){let o=await parseAgentObject(e);if(o.kind===`bail`)return o;let s=[o.object],c=[],l=o.object;for(let[t,a]of n.slice(0,-1).entries()){let o=findProperty(l,a);if(o.kind===`bail`)return{...o,line:lineAt(e,l.start)};if(o.property===void 0){if(r.kind===`remove`)return{kind:`applied`,nextSource:e};let i=nestedObjectSource(n.slice(t+1),r.value);return{kind:`applied`,nextSource:insertProperty(e,l,a,i)}}let u=propertyObjectValue(o.property);if(u===void 0)return{kind:`bail`,reason:`\`${a}\` is not an object literal that eve can edit safely`,line:lineAt(e,o.property.start)};c.push(o.property),s.push(u),l=u}let u=n.at(-1),d=findProperty(l,u);if(d.kind===`bail`)return{...d,line:lineAt(e,l.start)};if(d.property===void 0)return r.kind===`remove`?{kind:`applied`,nextSource:e}:{kind:`applied`,nextSource:insertProperty(e,l,u,JSON.stringify(r.value))};let f=propertyStringValue(d.property);if(f===void 0)return{kind:`bail`,reason:`\`${n.join(`.`)}\` is not a string literal that eve can edit safely`,line:lineAt(e,d.property.start)};if(r.kind===`set`){if(f.value===r.value)return{kind:`applied`,nextSource:e};let n=f.raw?.[0]===`'`?`'`:`"`,i=`${n}${escapeForQuote(r.value,n)}${n}`;return{kind:`applied`,nextSource:e.slice(0,f.start)+i+e.slice(f.end)}}if(r.removable!==void 0&&!r.removable(f.value))return{kind:`bail`,reason:`\`${n.join(`.`)}\` has the custom value ${JSON.stringify(f.value)}`,line:lineAt(e,d.property.start)};let p=d.property,m=l;for(let e=s.length-1;e>0&&m.properties.length===1;--e)p=c[e-1],m=s[e-1];return{kind:`applied`,nextSource:removeProperty(e,m,p)}}function findProperty(e,t){if(e.properties.some(e=>e.type===`SpreadElement`||e.computed===!0))return{kind:`bail`,reason:`\`${t}\` may be supplied by a spread or computed property`};let n=e.properties.filter(e=>e.type===`Property`&&!e.computed&&keyMatches(e.key,t));if(n.length>1)return{kind:`bail`,reason:`\`${t}\` is defined more than once`};let i=n[0];return i!==void 0&&i.start!==void 0&&i.end!==void 0?{kind:`ok`,property:i}:{kind:`ok`}}function propertyObjectValue(e){let t=e.value;if(!isAstNode(t))return;let r=unwrapExpression(t);return r.type===`ObjectExpression`&&r.start!==void 0&&r.end!==void 0&&r.properties!==void 0?r:void 0}function propertyStringValue(e){let t=e.value;if(!isAstNode(t))return;let r=unwrapExpression(t);if(r.type!==`Literal`||typeof r.value!=`string`||r.start===void 0||r.end===void 0)return;let i={start:r.start,end:r.end,value:r.value};return r.raw===void 0?i:{...i,raw:r.raw}}function nestedObjectSource(e,t){let n=JSON.stringify(t);for(let t of[...e].reverse())n=`{ ${t}: ${n} }`;return n}function insertProperty(e,t,n,r){let i=t.end-1,a=t.properties.at(-1);if(a===void 0||a.end===void 0)return e.slice(0,i)+` ${n}: ${r} `+e.slice(i);let o=e.lastIndexOf(`
+`,i-1)+1;if(o>t.start){let t=`${e.slice(o,i)}  `,s=e.slice(a.end,o),c=e;s.includes(`,`)||(c=c.slice(0,a.end)+`,`+c.slice(a.end));let l=o+ +!s.includes(`,`);return c.slice(0,l)+`${t}${n}: ${r},\n`+c.slice(l)}let s=e.slice(a.end,i).includes(`,`)?` `:`, `;return e.slice(0,i)+`${s}${n}: ${r}`+e.slice(i)}function removeProperty(e,t,n){let r=t.properties.indexOf(n),i=r>0?t.properties[r-1]:void 0,a=r>=0?t.properties[r+1]:void 0;return a?.start===void 0?i?.end===void 0?e.slice(0,t.start+1)+e.slice(t.end-1):e.slice(0,i.end)+e.slice(n.end):e.slice(0,n.start)+e.slice(a.start)}export{applyAgentConfigStringPath,checkAgentConfigSource};

package/dist/src/source-change/apply-agent-model-settings.d.ts

@@ -0,0 +1,26 @@
+import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
+export type FieldPatch<T> = {
+    readonly kind: "keep";
+} | {
+    readonly kind: "set";
+    readonly value: T;
+} | {
+    readonly kind: "remove";
+};
+export interface AgentModelSettingsPatch {
+    readonly model: FieldPatch<string>;
+    readonly reasoning: FieldPatch<AgentReasoningDefinition>;
+    readonly gatewayServiceTier: FieldPatch<"priority">;
+}
+export type AgentModelSetting = "model" | "reasoning" | "fast-mode";
+export type AgentModelSettingsEdit = {
+    readonly kind: "applied";
+    readonly changed: readonly AgentModelSetting[];
+    readonly nextSource: string;
+} | {
+    readonly kind: "bail";
+    readonly reason: string;
+    readonly line: number;
+};
+/** Applies every model-setting change in memory; callers own the atomic write. */
+export declare function applyAgentModelSettingsToSource(sourceText: string, patch: AgentModelSettingsPatch): Promise<AgentModelSettingsEdit>;

package/dist/src/source-change/apply-agent-model-settings.js

@@ -0,0 +1 @@
+import{applyAgentConfigStringPath}from"./agent-config-string-path.js";import{applyModelNameToSource}from"./apply-model-name.js";async function applyAgentModelSettingsToSource(n,r){let i=n,a=[];if(r.model.kind===`remove`)return{kind:`bail`,reason:"the required `model` property cannot be removed",line:1};if(r.model.kind===`set`){let e=await applyModelNameToSource(i,r.model.value);if(e.kind===`bail`)return e;e.nextSource!==i&&a.push(`model`),i=e.nextSource}if(r.reasoning.kind!==`keep`){let t=await applyAgentConfigStringPath(i,[`reasoning`],r.reasoning.kind===`set`?{kind:`set`,value:r.reasoning.value}:{kind:`remove`});if(t.kind===`bail`)return t;t.nextSource!==i&&a.push(`reasoning`),i=t.nextSource}if(r.gatewayServiceTier.kind!==`keep`){let t=await applyAgentConfigStringPath(i,[`modelOptions`,`providerOptions`,`gateway`,`serviceTier`],r.gatewayServiceTier.kind===`set`?{kind:`set`,value:r.gatewayServiceTier.value}:{kind:`remove`,removable:e=>e===`priority`});if(t.kind===`bail`)return t;t.nextSource!==i&&a.push(`fast-mode`),i=t.nextSource}return{kind:`applied`,changed:a,nextSource:i}}export{applyAgentModelSettingsToSource};

package/dist/src/source-change/apply-model-name.js

@@ -1,2 +1 @@
-import{parseWithNitroRolldownAst}from"#internal/bundler/nitro-rolldown.js";const AGENT_FACTORY=`defineAgent`;async function applyModelNameToSource(e,n){let r=await parseAgentSource(e);if(`kind`in r)return r;if((r.errors?.length??0)>0){let t=r.errors?.[0];return{kind:`bail`,reason:`agent.ts does not parse: ${t?.message??`unknown parse error`}`,line:parseErrorLine(e,t)}}let i=findDefineAgentObject(r.program??r,AGENT_FACTORY);if(i===void 0)return{kind:`bail`,reason:`no \`export default ${AGENT_FACTORY}({ ... })\` call found`,line:1};let a=findStringLiteralProperty(i,`model`);if(a===void 0)return{kind:`bail`,reason:"`model` is absent or is not a string literal (e.g. an env reference, a template, an inlined SDK model, or a defineDynamic() dynamic model)",line:lineAt(e,i.start??0)};let o=a.value;if(o===n)return{kind:`applied`,from:o,to:n,nextSource:e};let s=a.raw?.[0]===`'`?`'`:`"`,c=`${s}${escapeForQuote(n,s)}${s}`;return{kind:`applied`,from:o,to:n,nextSource:e.slice(0,a.start)+c+e.slice(a.end)}}async function parseAgentSource(t){try{return await parseWithNitroRolldownAst(`agent.ts`,t)}catch(e){let n=e;return{kind:`bail`,reason:`agent.ts does not parse: ${n.message??`unknown parse error`}`,line:parseErrorLine(t,n)}}}function unwrapExpression(e){let t=e;for(;t.type===`ParenthesizedExpression`||t.type===`TSAsExpression`||t.type===`TSSatisfiesExpression`;){if(t.expression===void 0||t.expression===null)return t;t=t.expression}return t}function findDefineAgentObject(e,t){for(let n of e.body??[]){if(n.type!==`ExportDefaultDeclaration`)continue;let e=n.declaration;if(e==null||e.type!==`CallExpression`&&e.type!==`ParenthesizedExpression`&&e.type!==`TSAsExpression`&&e.type!==`TSSatisfiesExpression`)continue;let r=unwrapExpression(e);if(r.type!==`CallExpression`||!isFactoryCallee(r.callee,t))continue;let i=r.arguments?.[0];if(i===void 0||i.type===`SpreadElement`)continue;let a=unwrapExpression(i);if(a.type===`ObjectExpression`)return a}}function isFactoryCallee(e,t){return e?.type===`Identifier`&&e.name===t}function findStringLiteralProperty(e,t){for(let n of e.properties){if(n.type!==`Property`||n.computed||!keyMatches(n.key,t))continue;let e=n.value;if(!isAstNode(e))continue;let r=unwrapExpression(e);return r.type===`Literal`&&typeof r.value==`string`&&r.start!==void 0&&r.end!==void 0?r:void 0}}function keyMatches(e,t){return e===void 0?!1:e.type===`Identifier`?e.name===t:e.type===`Literal`?typeof e.value==`string`&&e.value===t:!1}function isAstNode(e){return typeof e==`object`&&!!e&&typeof e.type==`string`}function parseErrorLine(e,t){return typeof t?.loc?.line==`number`?t.loc.line:lineAt(e,t?.labels?.[0]?.start??t?.start??0)}function escapeForQuote(e,t){return e.replaceAll(`\\`,`\\\\`).replaceAll(t,`\\${t}`)}function lineAt(e,t){let n=1;for(let r=0;r<t&&r<e.length;r+=1)e[r]===`
-`&&(n+=1);return n}export{applyModelNameToSource};
+import{escapeForQuote,isAstNode,keyMatches,lineAt,parseAgentObject,unwrapExpression}from"./agent-config-ast.js";async function applyModelNameToSource(t,n){let a=await parseAgentObject(t);if(a.kind===`bail`)return a;let o=a.object,s=findStringLiteralProperty(o,`model`);if(s===void 0)return{kind:`bail`,reason:"`model` is absent or is not a string literal (e.g. an env reference, a template, an inlined SDK model, or a defineDynamic() dynamic model)",line:lineAt(t,o.start)};let c=s.value;if(c===n)return{kind:`applied`,from:c,to:n,nextSource:t};let l=s.raw?.[0]===`'`?`'`:`"`,u=`${l}${escapeForQuote(n,l)}${l}`;return{kind:`applied`,from:c,to:n,nextSource:t.slice(0,s.start)+u+t.slice(s.end)}}function findStringLiteralProperty(e,r){for(let i of e.properties){if(i.type!==`Property`||i.computed||!keyMatches(i.key,r))continue;let e=i.value;if(!isAstNode(e))continue;let o=unwrapExpression(e);return o.type===`Literal`&&typeof o.value==`string`&&o.start!==void 0&&o.end!==void 0?o:void 0}}export{applyModelNameToSource};

package/dist/src/source-change/static-source-change.d.ts

@@ -1,4 +1,5 @@
 import type { AgentSourceManifest } from "#discover/manifest.js";
+import { type AgentModelSetting, type AgentModelSettingsPatch } from "#source-change/apply-agent-model-settings.js";
 /**
  * Outcome of a static source change, returned to upstream callers (CLI, web
  * setup UI) so they can render success or route the bail to a guided fix.
@@ -15,6 +16,17 @@ export type ApplyResult = {
         readonly line: number;
     };
 };
+export type ApplyModelSettingsResult = {
+    readonly kind: "applied";
+    readonly changed: readonly AgentModelSetting[];
+} | {
+    readonly kind: "bail";
+    readonly reason: string;
+    readonly at: {
+        readonly logicalPath: string;
+        readonly line: number;
+    };
+};
 /**
  * Central, flat API for applying targeted edits to an agent's authored source.
  *
@@ -29,6 +41,8 @@ export interface StaticSourceChange {
      * the caller can offer a manual fix.
      */
     updateModelName(modelName: string): Promise<ApplyResult>;
+    /** Applies the `/model` draft in one source transform and one atomic rename. */
+    updateModelSettings(patch: AgentModelSettingsPatch): Promise<ApplyModelSettingsResult>;
 }
 /**
  * Creates the {@link StaticSourceChange} surface bound to one discovered agent.

package/dist/src/source-change/static-source-change.js

@@ -1 +1 @@
-import{join}from"node:path";import{readFile,rename,writeFile}from"node:fs/promises";import{applyModelNameToSource}from"#source-change/apply-model-name.js";function createStaticSourceChange(e){return{updateModelName:t=>updateAgentModelName(e,t)}}async function updateAgentModelName(n,r){let i=n.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let a=join(n.agentRoot,i.logicalPath),o=await readFile(a,`utf8`),s=await applyModelNameToSource(o,r);if(s.kind===`bail`)return{kind:`bail`,reason:s.reason,at:{logicalPath:i.logicalPath,line:s.line}};if(s.nextSource!==o){let e=`${a}.${process.pid}.eve-tmp`;await writeFile(e,s.nextSource,`utf8`),await rename(e,a)}return{kind:`applied`,from:s.from,to:s.to}}export{createStaticSourceChange};
+import{join}from"node:path";import{readFile,rename,writeFile}from"node:fs/promises";import{checkAgentConfigSource}from"#source-change/agent-config-string-path.js";import{applyAgentModelSettingsToSource}from"#source-change/apply-agent-model-settings.js";import{applyModelNameToSource}from"#source-change/apply-model-name.js";function createStaticSourceChange(e){return{updateModelName:t=>updateAgentModelName(e,t),updateModelSettings:t=>updateAgentModelSettings(e,t)}}async function updateAgentModelSettings(n,r){let i=n.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let o=join(n.agentRoot,i.logicalPath),s=await readFile(o,`utf8`),c=await applyAgentModelSettingsToSource(s,r);if(c.kind===`bail`)return{kind:`bail`,reason:c.reason,at:{logicalPath:i.logicalPath,line:c.line}};let l=await editedSourceBail(s,c.nextSource,i.logicalPath);return l===void 0?(await writeSourceIfChanged(o,s,c.nextSource),{kind:`applied`,changed:c.changed}):l}async function updateAgentModelName(n,r){let i=n.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let a=join(n.agentRoot,i.logicalPath),s=await readFile(a,`utf8`),c=await applyModelNameToSource(s,r);if(c.kind===`bail`)return{kind:`bail`,reason:c.reason,at:{logicalPath:i.logicalPath,line:c.line}};let l=await editedSourceBail(s,c.nextSource,i.logicalPath);return l===void 0?(await writeSourceIfChanged(a,s,c.nextSource),{kind:`applied`,from:c.from,to:c.to}):l}async function writeSourceIfChanged(e,t,i){if(i===t)return;let a=`${e}.${process.pid}.eve-tmp`;await writeFile(a,i,`utf8`),await rename(a,e)}async function editedSourceBail(e,t,n){if(t===e)return;let r=await checkAgentConfigSource(t);if(r!==void 0)return{kind:`bail`,reason:`the edit produced source eve refuses to write (${r})`,at:{logicalPath:n,line:1}}}export{createStaticSourceChange};

package/dist/src/svelte/index.js

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

package/dist/src/svelte/use-eve-agent.d.ts

@@ -80,12 +80,6 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
     readonly initialEvents?: readonly HandleMessageStreamEvent[];
     /** Seed session identity and stream cursor for resuming a prior conversation. */
     readonly initialSession?: SessionState;
-    /**
-     * Maximum number of stream reconnection attempts per turn.
-     *
-     * @default 3
-     */
-    readonly maxReconnectAttempts?: number;
     /**
      * Project submitted user messages before eve confirms them with a
      * `message.received` stream event. Optimistic events are reducer-facing

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

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

package/dist/src/vue/index.js

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

package/dist/src/vue/use-eve-agent.d.ts

@@ -79,8 +79,6 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
     readonly initialEvents?: readonly HandleMessageStreamEvent[];
     /** Prior session cursor to resume from on mount. */
     readonly initialSession?: SessionState;
-    /** Maximum SSE reconnection attempts per turn. @default 3 */
-    readonly maxReconnectAttempts?: number;
     /**
      * Project submitted user messages before eve confirms them with a
      * `message.received` stream event.

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

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

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

@@ -36,7 +36,7 @@ export default defineAgent({
 });
 ```
 
-The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. Custom worlds must implement the runtime protocol expected by eve's vendored `@workflow/*` packages (currently the `5.0.0-beta` line); the Workflow SDK rejects incompatible protocol versions during initialization. See the [deployment guide](../guides/deployment#8-deploy-without-vercel) for the install command, plus [agent.ts](../agent-config#workflow-world) and [Workflow Worlds](https://workflow-sdk.dev/worlds).
+The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. Custom worlds must implement the runtime protocol expected by eve's vendored `@workflow/*` packages (currently the `5.0.0-beta` line); the Workflow SDK rejects incompatible protocol versions during initialization. See [Self-host eve](../guides/deployment/self-hosting#persist-workflow-state), [agent.ts](../agent-config#workflow-world), and [Workflow Worlds](https://workflow-sdk.dev/worlds).
 
 ## Resuming after a crash
 

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

@@ -110,7 +110,7 @@ Custom channel routes request the same cancellation without knowing the session
 
 ## Reconnect and rewind
 
-The stream is durable. Every event is recorded before a step completes, so the whole stream is replayable. A nonnegative `startIndex` is an absolute event count: use it to pick up where you dropped off or pass `0` to rewind to the start.
+The stream is durable. Every event is recorded before a step completes, so consumers can reconnect from their cursor when an HTTP connection ends. A nonnegative `startIndex` is an absolute event count: use it to pick up where you dropped off or pass `0` to rewind to the start.
 
 ```bash
 curl "http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream?startIndex=<count>"

package/docs/extensions.md

@@ -85,7 +85,7 @@ Declare separate authoring and distribution roots and run `eve extension build`
   },
   "files": ["dist"],
   "peerDependencies": { "eve": "*" },
-  "devDependencies": { "eve": "^x", "typescript": "^x" },
+  "devDependencies": { "eve": "x.y.z", "typescript": "^x" },
   "dependencies": { "zod": "^3" },
   "scripts": { "build": "eve extension build", "prepare": "eve extension build" },
 }
@@ -120,6 +120,19 @@ During local development, `eve dev` automatically rebuilds mounted workspace ext
 
 `eve` is a required wildcard **peer** dependency: one eve lives in the consuming app and the extension's `eve/*` imports resolve to it. The extension's concrete eve version belongs in `devDependencies` for authoring types and build tooling. npm peer semver does not decide extension compatibility; eve validates the generated per-capability requirements. Do not mark the eve peer optional and do not add eve to regular `dependencies`.
 
+`eve extension init` pins `devDependencies.eve` to the exact eve release that created the scaffold:
+
+```jsonc title="package.json"
+{
+  "peerDependencies": { "eve": "*" },
+  "devDependencies": { "eve": "0.25.0" },
+}
+```
+
+The exact pin makes builds reproducible. Keep it until the extension intentionally upgrades its eve authoring API. `eve extension build` records the capability contracts required by the build, and each consuming eve validates those requirements before it runs the extension.
+
+If the extension must support an older eve release, replace the development pin with that exact version, then typecheck and build with it. Test the same dist against both the oldest and latest supported consumers; rebuilding with each consumer would produce and test different artifacts.
+
 Everything else the extension imports at execution time (SDKs, `zod`, …) goes in `dependencies`; each extension resolves its own versions. Build-only and test-only packages go in `devDependencies`.
 
 Those deps resolve from `node_modules` under `eve dev`/`eve eval` and are bundled into the deployable by the consuming agent's `eve build`. A dependency that can't be bundled (a native addon) must be listed in the **consuming agent's** `build.externalDependencies` — an extension can't declare build config, so note it in your README.

package/docs/getting-started.mdx

@@ -130,7 +130,7 @@ Other commands the eve binary provides (prefix each with `npx`, or add a matchin
 
 In the dev TUI, type a message and watch it happen in order. First the `get_weather` call, then its result, then the reply.
 
-The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment).
+The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment/overview).
 
 ## Send a message
 

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

@@ -373,4 +373,4 @@ Inline providers derive a stable tool-qualified auth key from Vercel Connect met
 
 - [Security model](../concepts/security-model): trust boundaries and the pre-production checklist
 - [Connections](../connections): connection auth shapes (`connect()` vs static token)
-- [Deployment](./deployment): where route-auth secrets live in production
+- [Deployment](./deployment/overview): where route-auth secrets live in production

package/docs/guides/client/overview.mdx

@@ -9,7 +9,7 @@ For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire
 
 ## Create a client
 
-A `Client` binds one host, auth policy, header policy, and stream reconnection budget:
+A `Client` binds one host, auth policy, and header policy:
 
 ```ts
 import { Client } from "eve/client";

package/docs/guides/client/streaming.mdx

@@ -103,16 +103,7 @@ If you support refresh while an authorization prompt is pending, keep the sessio
 
 ## Reconnection
 
-The client reconnects after transient stream disconnects. It resumes from the number of events already consumed in the current session:
-
-```ts
-const client = new Client({
-  host: "https://agent.example.com",
-  maxReconnectAttempts: 5,
-});
-```
-
-`maxReconnectAttempts` is per turn. The default is `3`.
+HTTP connections can end before a run does. The client reconnects from the number of events already consumed, so long turns continue without replaying events. It stops at a turn boundary, when aborted, or when the stream can no longer make progress.
 
 ## Open a stream manually
 

package/docs/guides/deployment/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Deployment",
+  "pages": ["overview", "vercel", "self-hosting"]
+}

package/docs/guides/deployment/overview.md

@@ -0,0 +1,61 @@
+---
+title: "Overview"
+description: "Choose a deployment strategy and prepare an eve agent for production."
+---
+
+Deploy eve to Vercel or run it as a Node service on your own infrastructure. Your deployment strategy determines the build output, workflow storage, sandbox backend, and routing. The agent’s filesystem-based configuration remains portable across these strategies.
+
+## Choose a deployment strategy
+
+Choose where the eve runtime will run:
+
+| Strategy                       | Build output           | Workflows                      | Sandbox                         | Choose it when                                        |
+| ------------------------------ | ---------------------- | ------------------------------ | ------------------------------- | ----------------------------------------------------- |
+| [Vercel](./vercel)             | `.vercel/output`       | Vercel Workflow                | Vercel Sandbox                  | You want Vercel to operate the runtime services       |
+| [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker, microsandbox, or custom | You operate your own Node or container infrastructure |
+
+eve is frontend agnostic and can be deployed within Next.js, Nuxt, or SvelteKit applications. See [Frontend integrations](../frontend/overview) for more details.
+
+## Prepare for production
+
+Every production deployment must satisfy the same runtime requirements:
+
+1. Run `eve build` to compile the agent and create host output.
+2. Provide a model credential and any secrets required by tools, connections, and route authentication.
+3. Replace `placeholderAuth()` with a production route policy before accepting browser traffic.
+4. Select workflow and sandbox implementations that match the host.
+5. Verify the health route and complete a real agent turn.
+
+`eve build` always writes compiler artifacts under `.eve/`. A Vercel build also writes `.vercel/output`. A build for another host writes the standard Nitro server under `.output/`.
+
+## Configure credentials
+
+Keep credentials in your deployment environment or secret manager. Don’t include them in source or compiled artifacts.
+
+Your model configuration determines the required credential. A string model ID uses the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) and requires Vercel project OpenID Connect (OIDC) or `AI_GATEWAY_API_KEY`. A provider-authored model uses that provider’s package and API key. See [Agent configuration](../../agent-config#set-the-model) for both forms.
+
+Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Auth and route protection](../auth-and-route-protection) for the available policies and secret requirements.
+
+## Verify the deployment
+
+Check the public health route first:
+
+```bash
+curl https://your_agent.example.com/eve/v1/health
+```
+
+Then connect the development terminal user interface (TUI) to the deployment and send a real message:
+
+```bash
+eve dev https://your_agent.example.com
+```
+
+Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if a Vercel deployment uses Deployment Protection.
+
+## Continue with a platform guide
+
+Follow the guide for your deployment platform or application topology:
+
+- [Deploy to Vercel](./vercel): use Vercel Build Output, Workflow, Sandbox, Cron, and observability
+- [Self-host eve](./self-hosting): run the Nitro Node server with infrastructure you manage
+- [Frontend integrations](../frontend/overview): mount eve alongside Next.js, Nuxt, or SvelteKit

package/docs/guides/deployment/self-hosting.md

@@ -0,0 +1,88 @@
+---
+title: "Self-host eve"
+description: "Run an eve agent as a Node service with your own workflow storage, sandbox backend, and routing."
+---
+
+Self-host eve when you operate a Node service, container platform, or reverse proxy. You run eve’s Nitro server and choose the infrastructure that stores workflows and executes sandbox sessions.
+
+## Build and start the Node service
+
+Build the agent, then start the generated server:
+
+```bash
+eve build
+PORT=3000 eve start --host 0.0.0.0
+```
+
+The build writes the Nitro server under `.output/`. `eve start` serves that output and accepts either `PORT` or the `--port` flag.
+
+Run this process under the same process manager or container platform you use for other Node web services. Configure Transport Layer Security (TLS), scaling, restarts, and log collection in that platform.
+
+## Configure model access and route auth
+
+Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway from a non-Vercel host. To call a provider directly, install its [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models). Then pass its model object in `agent.ts` and set its API key. See [Agent configuration](../../agent-config#set-the-model) for examples.
+
+Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Auth and route protection](../auth-and-route-protection).
+
+## Persist workflow state
+
+The default local Workflow world stores run state under `.eve/.workflow-data`. Mount that directory on persistent storage so runs survive process and container replacement.
+
+You can instead select an installed Workflow world package in the root `agent.ts`:
+
+```typescript
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  experimental: {
+    workflow: {
+      world: "@acme/eve-workflow-world",
+    },
+  },
+});
+```
+
+The package must export a default factory or `createWorld()` function. Read credentials and host options from runtime environment variables. Install a world built against the same `@workflow/*` line as your eve release. The current line is `5.0.0-beta`, and the runtime rejects incompatible protocol versions.
+
+See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
+
+## Select a sandbox backend
+
+`defaultBackend()` selects a local sandbox backend in availability order. You can instead select Docker, microsandbox, or a custom `SandboxBackend` adapter for your container, virtual machine, or isolation service.
+
+Don’t select `vercel()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for backend configuration and selection order.
+
+## Configure proxy routes
+
+Forward both runtime route prefixes through your reverse proxy or ingress:
+
+- `/eve/` serves health, sessions, streams, channels, tools, and subagents
+- `/.well-known/workflow/` receives workflow callbacks
+
+A proxy restricted to `/eve/` lets a session start, but the run stalls when its callback can’t reach eve. Preserve both prefixes without rewriting their paths.
+
+## Run schedules
+
+The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
+
+## Verify the service
+
+Check the health route after your proxy and authentication configuration are active:
+
+```bash
+curl https://your_agent.example.com/eve/v1/health
+```
+
+Then connect the development TUI and complete a real turn:
+
+```bash
+eve dev https://your_agent.example.com
+```
+
+## Continue configuring production
+
+Use these guides to secure and observe the deployed agent:
+
+- [Auth and route protection](../auth-and-route-protection): configure the host’s route policy
+- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Sandbox](../../sandbox): select and secure a sandbox backend

package/docs/guides/deployment/vercel.mdx

@@ -0,0 +1,90 @@
+---
+title: "Deploy to Vercel"
+description: "Deploy an eve agent with Vercel Workflow, Sandbox, Cron, and project credentials."
+---
+
+Deploy eve to Vercel when you want the framework’s managed build and runtime integrations. Vercel runs the web service, workflows, sandboxes, schedules, and deployment observability.
+
+## Prepare the Vercel project
+
+Link the agent directory to a Vercel project:
+
+```bash
+eve link
+```
+
+The command links an existing project or creates one, then pulls its environment variables. In continuous integration (CI) environments, use the non-interactive Vercel command instead:
+
+```bash
+vercel link --project your_project_name --yes --non-interactive
+```
+
+## Configure credentials and auth
+
+A string model ID routes requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). The deployment authenticates through project OpenID Connect (OIDC), so you don’t need a provider API key for that path.
+
+Add credentials for direct model providers, tools, and connections to the Vercel project environment. Add any signing keys or passwords required by your [route authentication policy](../auth-and-route-protection). Replace `placeholderAuth()` before a browser sends a production request.
+
+## Select the sandbox backend
+
+Leave the sandbox `backend` unset to use `defaultBackend()`. On Vercel, it selects Vercel Sandbox. You can also select the backend explicitly:
+
+```typescript
+import { defineSandbox } from "eve/sandbox";
+import { vercel } from "eve/sandbox/vercel";
+
+export default defineSandbox({
+  backend: vercel(),
+});
+```
+
+See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle hooks.
+
+<Callout type="info" title="Sandbox prewarming">
+  During a Vercel build, eve automatically creates or reuses a sandbox template when your sandbox
+  has `bootstrap()` or seed files. The build needs permission to create Vercel Sandbox templates,
+  and a prewarm failure stops the deployment. See the [sandbox lifecycle](../../sandbox#lifecycle)
+  for template and session setup.
+</Callout>
+
+## Deploy the agent
+
+Deploy the linked project to production:
+
+```bash
+eve deploy
+```
+
+`eve deploy` installs dependencies, runs `vercel deploy --prod`, and pulls the project environment after deployment. You can also push to a Git-connected Vercel project. Hosted Vercel builds set `VERCEL`, so `eve build` writes the deployment bundle under `.vercel/output`.
+
+Vercel uses the generated output to configure these services:
+
+- **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
+- **Vercel Workflow**: persists and resumes durable runs
+- **Vercel Cron**: invokes authored schedules
+- **Vercel Sandbox**: runs sandbox sessions selected by `defaultBackend()`
+
+## Verify the deployment
+
+Check the health route and connect the development TUI:
+
+```bash
+curl https://your_agent.vercel.app/eve/v1/health
+eve dev https://your_agent.vercel.app
+```
+
+Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before connecting if the deployment uses Deployment Protection.
+
+## Inspect agent runs
+
+Vercel detects eve and can add an **Agent Runs** tab under the project’s **Observability** view. Use it to browse sessions and inspect each conversation trace.
+
+The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel representative if the tab doesn’t appear. For third-party tracing backends, configure [OpenTelemetry instrumentation](../instrumentation).
+
+## Continue configuring production
+
+Use these guides to secure and observe the deployed agent:
+
+- [Auth and route protection](../auth-and-route-protection): configure who can call the deployed agent
+- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Sandbox](../../sandbox): configure resources, isolation, and network access

package/docs/guides/dev-tui.md

@@ -24,7 +24,7 @@ The conversation streams straight into your terminal's normal scrollback, so you
 
 Each turn renders without boxes. A colored gutter glyph marks who is speaking, tool calls collapse to a one-line summary (`✓ get_weather  city="SF" → 73°F`), and a subagent's work is indented beneath its `◆` header. When input is ready, the prompt stays bare until you type. A green circle-dot pulses while the agent is waiting to answer and disappears when reasoning or answer content begins.
 
-A persistent line beneath the prompt or status shows the model, the session's token flow (`↑ 394.4K ↓ 4.3K`), the linked Vercel project, and a yellow `/deploy pending` marker once a channel added this session still needs `/deploy`. The Vercel segment stays hidden until the directory is linked. Local sessions lead with a gray `:port` badge. Remote sessions lead with a padded `↗ project (environment)` badge, or the host when Vercel cannot resolve the deployment. The badge is gray while checking or unavailable, yellow while authentication is required or failed, and blue when connected. Other status segments use `·` separators. Remote status lines omit AI Gateway endpoint state.
+A persistent line beneath the prompt or status shows the model — with its authored reasoning level and a `↯` marker when the Gateway priority tier is on (`xai/grok-4.5@xhigh ↯`) — the linked Vercel project, and a yellow `/deploy pending` marker once a channel added this session still needs `/deploy`. The Vercel segment stays hidden until the directory is linked. Local sessions lead with a gray `:port` badge. Remote sessions lead with a padded `↗ project (environment)` badge, or the host when Vercel cannot resolve the deployment. The badge is gray while checking or unavailable, yellow while authentication is required or failed, and blue when connected. Status segments separate with plain whitespace. Remote status lines omit AI Gateway endpoint state.
 
 Errors render compactly with docs links highlighted. A code bug escaping your agent's own code shows its stack trace dim beneath the error headline. Dev-server rebuilds condense into one status row that updates in place (`tui/setup-panel.ts changed · rebuilding…`, then `· rebuilt`); only the latest rebuild shows, and paths shrink to their last two components.
 
@@ -49,9 +49,9 @@ Each command echoes as an invocation line, asks through a bordered panel that ta
 
 ### Configure the model and provider
 
-Bare `/model` opens the configure menu. When no provider is configured, it opens the provider picker directly and Esc returns to the configure menu. "Change model" runs the same searchable model picker setup uses (the Vercel AI Gateway catalog, pre-selected on the model the runtime is serving). A model change is written into your agent's authored source, and the command reports success only after eve confirms the new id. A completed model or provider change closes the menu and returns its result to the transcript; Done or Esc closes it without a change. `/model <provider/model-id>` applies one directly, skipping the menu.
+Bare `/model` opens the configure menu; its Change model row summarizes the draft (`xai/grok-4.5@high ↯`). When no provider is configured, it opens the provider picker directly and Esc returns to the configure menu. "Change model" opens a value menu — **Model**, **Reasoning effort** (a `●─◉─○` track beside the drafted level), **Service tier** (`fast ↯` or `normal`), and **Done**. Reasoning and tier adjust in place: `←`/`→` (Tab acts as `→`) move the highlighted row's value as a ring — past the top wraps to the bottom and vice versa — sliding the reasoning track over the model's supported effort levels or flipping the tier. An unset reasoning draft shows an empty track; the first `→` enters the ring at the lowest level, `←` at the highest. Picking a model snaps a drafted level the new model cannot serve to its closest supported one, clearing it when the model has no adjustable reasoning. Enter on the Model row opens the searchable Vercel AI Gateway catalog as `▏`-railed model ids, pre-selected on the model the runtime is serving; Esc backs out without changing it. A model with no adjustable reasoning says so on a disabled row, and a model the catalog prices no priority tier for shows no tier row at all. The menu's Done hands the draft to the configure menu, whose own Done commits everything through one atomic edit of your agent's authored source, reporting success only after eve confirms the new id. A completed model or provider change closes the menu and returns its result to the transcript; Done without changes or Esc closes it without one, and Esc notes any discarded draft. `/model <provider/model-id>` applies one directly, skipping the menu.
 
-The provider row opens one menu: AI Gateway via a project, AI Gateway via `AI_GATEWAY_API_KEY`, or **Other providers**. The key option becomes a masked input when highlighted. Enter validates it without replacing the menu. A rejected key shows a red `⨯ Invalid key` beside the masked value; retrying or editing clears that result. With a non-empty key, the first Esc or Ctrl-C clears the input and the second cancels the menu. An accepted key is saved to `.env.local`. The project option asks for a Vercel team, opens that team's recent projects, and lets you search all projects for older matches. Vercel links the selected project, eve verifies its project ID, then pulls its environment into `.env.local`. The **Other providers** option shows direct-provider wiring instructions and leaves the existing setup untouched. The dev server reloads env files and refreshes the status bar automatically, with no restart needed.
+The provider row opens one menu: AI Gateway via a project, AI Gateway via `AI_GATEWAY_API_KEY`, or **Other providers**. The currently-active provider renders checked with its status beneath it ("Linked to **my-project** in team **my-team**", or "`AI_GATEWAY_API_KEY` set in `.env.local`"), and the cursor opens on it with a `↵ change` badge. The key option becomes a masked input on an `⎿` rail when highlighted, with a `↵ validate` badge after it. Enter validates it without replacing the menu — a `▪ validating` badge while it checks, a red `⨯ API key is not valid` badge on rejection; retrying or editing clears that result. With a non-empty key, the first Esc or Ctrl-C clears the input and the second dismisses the menu. An accepted key is saved to `.env.local` and reported as one `AI_GATEWAY_API_KEY set.` line. The project option asks for a Vercel team, opens that team's recent projects with the project named after your agent suggested first (searching the team for it when it is not among the recents), and lets you search all projects for older matches. Vercel links the selected project, eve verifies its project ID, then pulls its environment into `.env.local`. The **Other providers** option shows direct-provider wiring instructions and leaves the existing setup untouched. The dev server reloads env files and refreshes the status bar automatically, with no restart needed.
 
 The provider row demands attention (a bold yellow "Configure model access" with a yellow "Not configured" hint that dims when unselected and uses the terminal foreground when selected) until a link or gateway credential is detected, then names the connection afterward (for example "AI Gateway (Linked to my-project in my-team)"). Setup menus mark the cursor row with a padded, filled-arrow inverse label that inherits the row's accent: blue normally and yellow for warning rows. In stacked menus, the selected row's description appears directly beneath that option. The completed command's outcome stays in the transcript after the panel closes. When a turn fails because AI Gateway authentication is missing or stale, the error points you at `/model` directly.
 
@@ -100,6 +100,10 @@ By default, `eve dev` shows `stderr` and keeps stdout and sandbox lines buffered
 - `--logs <all|stderr|sandbox|none>` sets the starting mode at launch (default `stderr`).
 - `Ctrl+L` at the idle prompt cycles `none → all → stderr → sandbox → none`.
 
+Every captured line, tool failure, workflow error, and eve framework log record also lands in a private per-process diagnostic log under `.eve/logs/`, regardless of the display mode. The file is JSON Lines: each line is one JSON record with `at` and `source` fields (framework log records add `level`, `namespace`, `message`, and `fields`), so it parses with any JSONL tool — `jq -c 'select(.source=="tool")'` — even when a payload spans many stack-trace lines. Long stderr output collapses in the transcript to a one-line summary pointing at the file (the raw text stays available in the `all` mode). Read the logs with `eve logs` — see the [CLI reference](../reference/cli#eve-logs).
+
+Each log has a same-named `.dump` sibling — one JSON document with environment diagnostics (eve, Node.js, and Vercel CLI versions, the Vercel CLI path, and the size of the local session store) plus running session stats: prompts, token usage, tool calls by name, and subagent dispatches. `eve logs --dump` prints the dump and the log together as one parseable report to attach when filing an issue.
+
 ## Display flags
 
 Density flags control how much of each section renders. They accept `full`, `collapsed`, `auto-collapsed`, or `hidden`.
@@ -146,7 +150,7 @@ In a remote session, `/vc:login` first resolves the deployment's Vercel project
 
 The project-scoped token represents the resolved project's Development environment. Vercel already allows a project's Development environment to call its own Preview deployments by default. For a Production or custom-environment target, `/vc:login` shows the exact Development-to-target rule before changing that project's Trusted Sources. Eve preserves existing entries. When it creates an explicit rule, it also carries Vercel's default self-access rows forward because saved rules replace those defaults. See Vercel's [Trusted Sources guide](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources), [error reference](https://vercel.com/docs/errors/trusted_sources_environment_mismatch), and [OIDC token anatomy](https://vercel.com/docs/oidc/reference#oidc-token-anatomy).
 
-`VERCEL_AUTOMATION_BYPASS_SECRET` remains available for a Protection Bypass for Automation token. See [Deployment](./deployment) for the smoke-test flow.
+`VERCEL_AUTOMATION_BYPASS_SECRET` remains available for a Protection Bypass for Automation token. See [Deploy to Vercel](./deployment/vercel#verify-the-deployment) for the smoke-test flow.
 
 ## What to read next
 

package/docs/guides/dynamic-capabilities.md

@@ -25,6 +25,8 @@ their `defineDynamic` export is a build error.
 
 Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. The wrapper stamps them so their `execute` functions survive workflow step boundaries.
 
+Dynamic tool executors receive the same `ToolContext` as static authored tools, including inline provider auth through `ctx.getToken(provider)` and `ctx.requireAuth(provider)`.
+
 The example below builds one tool per warehouse table. A map return names each tool by its bare key, so the model sees `orders`, `users`, and so on.
 
 ```ts title="agent/tools/query.ts"

package/docs/guides/frontend/nextjs.mdx

@@ -124,4 +124,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
 
 - [Frontend overview](./overview): the `useEveAgent` API
 - [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)

package/docs/guides/frontend/nuxt.mdx

@@ -96,4 +96,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
 
 - [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API
 - [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)

package/docs/guides/frontend/overview.mdx

@@ -193,10 +193,7 @@ const agent = useEveAgent({
 });
 ```
 
-Two more options tune turn behavior:
-
-- `optimistic` (default `true`): projects submitted user messages into `data` before eve confirms them with a `message.received` event. These are reducer-facing projection events only. `events` stays the authoritative eve stream.
-- `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.
+The `optimistic` option (default `true`) projects submitted user messages into `data` before eve confirms them with a `message.received` event. These are reducer-facing projection events only. `events` stays the authoritative eve stream.
 
 ## Custom reducer
 
@@ -256,7 +253,7 @@ const agent = useEveAgent({
 
 Store the full `session` object (`sessionId`, `continuationToken`, `streamIndex`), not a single field. The session cursor lets eve continue the durable conversation; the event log lets your UI render historical messages without replaying the whole stream. A database-backed chat app should usually persist stream events as they arrive with `onEvent` and then save a final snapshot in `onFinish`.
 
-For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `maxReconnectAttempts`, and `optimistic` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
+For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, and `optimistic` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
 
 If the user can refresh or navigate immediately after pressing send, create your app-level chat row and store the pending user message before calling `send()`. After the request starts, persist the session state as soon as it contains a `sessionId`, then reconnect an interrupted in-flight turn with `session.stream({ startIndex: savedEvents.length })` from the lower-level client.