eve 0.26.2 → 0.27.0

package/dist/src/public/nuxt/vercel-services.d.ts

@@ -0,0 +1,117 @@
+interface VercelRequestPathTransform {
+    readonly args: string;
+    readonly op: "set";
+    readonly type: "request.path";
+}
+interface VercelServiceRouteDestination {
+    readonly service?: string;
+    readonly type?: string;
+}
+interface VercelRouteConfig {
+    readonly destination?: string | VercelServiceRouteDestination;
+    readonly handle?: string;
+    readonly src?: string;
+    readonly transforms?: readonly VercelRequestPathTransform[];
+    readonly [key: string]: unknown;
+}
+interface VercelServiceConfig {
+    readonly framework?: string;
+    readonly routes?: readonly VercelRouteConfig[];
+    readonly [key: string]: unknown;
+}
+/**
+ * The top-level Vercel Build Output route that sends eve transport requests to
+ * the generated eve service.
+ */
+export type EveVercelServiceRoute = {
+    readonly destination: {
+        readonly service: string;
+        readonly type: "service";
+    };
+    readonly src: string;
+};
+/**
+ * A service-scoped route carrying the `request.path` transform that pins the
+ * path the eve runtime observes to the eve transport namespace.
+ */
+export type EveVercelServiceRequestPathRoute = {
+    readonly src: string;
+    readonly transforms: readonly [VercelRequestPathTransform];
+};
+/**
+ * The generated eve service entry written into the Vercel Build Output
+ * `services` record.
+ */
+export type EveVercelGeneratedService = {
+    readonly buildCommand: string;
+    readonly framework: "eve";
+    readonly routes: readonly VercelRouteConfig[];
+    readonly root: string;
+};
+/**
+ * Minimal shape of the Nitro Vercel build-output config the module merges the
+ * generated eve service into.
+ */
+export interface NitroVercelBuildConfig {
+    version?: number;
+    routes?: unknown[];
+    services?: Record<string, VercelServiceConfig>;
+    [key: string]: unknown;
+}
+/**
+ * Result of {@link ensureEveVercelServicesConfig}: `root` when `vercel.json`
+ * already declares stable services (the user owns routing; nothing is
+ * generated), `generated` with the service record to merge into the Nitro
+ * Vercel build config otherwise.
+ */
+export type EnsureEveVercelServicesConfigResult = {
+    readonly mode: "root";
+} | {
+    readonly mode: "generated";
+    readonly services: Record<string, EveVercelGeneratedService>;
+};
+/**
+ * Build the top-level Build Output route that exposes the eve service on the
+ * eve transport namespace (`/eve/v1/*`).
+ */
+export declare function createEveServiceRoute(serviceName?: string): EveVercelServiceRoute;
+/**
+ * Build the eve service's own route that sets `request.path` so the eve
+ * runtime observes the transport path regardless of how the platform routed
+ * the request into the service.
+ */
+export declare function createEveServiceRequestPathRoute(): EveVercelServiceRequestPathRoute;
+/**
+ * Resolve the stable Vercel services configuration for a Nuxt + eve
+ * deployment.
+ *
+ * When `vercel.json` (looked up from the linked Vercel project root, falling
+ * back to the Nuxt root) already declares stable `services`, it must include
+ * an eve service and the module generates nothing. Otherwise this prepares a
+ * generated eve service — creating its isolated build root under
+ * `.eve/vercel-services/eve` so the eve build output cannot collide with the
+ * Nuxt Build Output — and returns the service record plus the public service
+ * route for the caller to merge into the Nitro Vercel build config. A legacy
+ * `experimentalServices` field is ignored with a migration warning: Vercel no
+ * longer routes it.
+ */
+export declare function ensureEveVercelServicesConfig(input: {
+    readonly appRoot: string;
+    readonly eveBuildCommand?: string;
+    readonly nuxtRoot: string;
+}): Promise<EnsureEveVercelServicesConfigResult>;
+/**
+ * Merge the generated eve service and its public route into a Nitro Vercel
+ * build config (`nitro.vercel.config`).
+ *
+ * The service route is inserted before an existing `handle: "filesystem"`
+ * route, or prepended when none exists — Nitro appends its own generated
+ * routes (including the filesystem handle) after this config's routes, so the
+ * eve route always resolves before the Nuxt app's filesystem routing. An eve
+ * service already configured by the user is preserved and only gains the
+ * `request.path` route; everything else passes through untouched.
+ */
+export declare function mergeEveVercelConfig(existing: NitroVercelBuildConfig | undefined, generated: Extract<EnsureEveVercelServicesConfigResult, {
+    mode: "generated";
+}>): NitroVercelBuildConfig;
+export {};

package/dist/src/public/nuxt/vercel-services.js

@@ -0,0 +1 @@
+import{EVE_ROUTE_PREFIX}from"#protocol/routes.js";import{dirname,join,relative}from"node:path";import{mkdir,readFile}from"node:fs/promises";import{EVE_INTERNAL_BUILD_OUTPUT_DIRECTORY_ENV,EVE_INTERNAL_HOST_BUILD_OUTPUT_DIRECTORY_ENV}from"#internal/application/paths.js";import{findClosestLinkedVercelDirectory}from"#shared/vercel-output-directory.js";import{resolveEveBinaryPath}from"#shared/resolve-eve-binary.js";const VERCEL_JSON_FILE_NAME=`vercel.json`,EVE_SERVICE_ROUTE_SRC=`^${EVE_ROUTE_PREFIX}/(.*)$`,EVE_SERVICE_ROUTE_PATH=`${EVE_ROUTE_PREFIX}/$1`;function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function toPosixRelative(e,t){let n=relative(e,t);return n.length===0?`.`:n.replaceAll(`\\`,`/`)}function quoteShellArgument(e){return`'${e.replaceAll(`'`,`'\\''`)}'`}function isNamedServiceConfigArray(e){return Array.isArray(e)}function createServiceConfigRecord(e){if(e===void 0)return{};if(isNamedServiceConfigArray(e)){let t={};for(let n of e)if(typeof n.name==`string`&&n.name.trim().length>0){let{name:e,...r}=n;t[e]=r}return t}return e}function normalizeVercelJsonConfig(e){if(!isRecord(e))throw Error(`${VERCEL_JSON_FILE_NAME} must contain a JSON object.`);let t=e.services;if(t!==void 0&&!isRecord(t)&&!(Array.isArray(t)&&t.every(e=>isRecord(e)&&typeof e.name==`string`&&e.name.trim().length>0)))throw Error(`${VERCEL_JSON_FILE_NAME} services must be a JSON object or named service array.`);return e}async function readVercelJsonConfig(e){try{return normalizeVercelJsonConfig(JSON.parse(await readFile(e,`utf8`)))}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return{};throw e}}function findEveService(e){return Object.values(e).find(e=>e.framework===`eve`)}function assertRootServicesIncludeEve(t){if(findEveService(t)===void 0)throw Error(`${VERCEL_JSON_FILE_NAME} already defines services, so the eve Nuxt module cannot add a generated eve service. Add an eve service (framework "eve") and a rewrite from ${EVE_ROUTE_PREFIX}/(.*) to it in ${VERCEL_JSON_FILE_NAME}, or remove services from ${VERCEL_JSON_FILE_NAME}.`)}function createEveServiceRoute(e=`eve`){return{destination:{service:e,type:`service`},src:EVE_SERVICE_ROUTE_SRC}}function createEveServiceRequestPathRoute(){return{src:EVE_SERVICE_ROUTE_SRC,transforms:[{args:EVE_SERVICE_ROUTE_PATH,op:`set`,type:`request.path`}]}}function isEveServiceRoute(e,t){let n=e.destination;return e.src===EVE_SERVICE_ROUTE_SRC&&isRecord(n)&&n.type===`service`&&n.service===t}function insertEveServiceRoute(e,t){let n=e.filter(e=>!(isRecord(e)&&isEveServiceRoute(e,t))),r=n.findIndex(e=>isRecord(e)&&e.handle===`filesystem`);return r===-1?[createEveServiceRoute(t),...n]:[...n.slice(0,r),createEveServiceRoute(t),...n.slice(r)]}function insertEveServiceRequestPathRoute(e){let t=(e??[]).filter(e=>e.src!==EVE_SERVICE_ROUTE_SRC);return[createEveServiceRequestPathRoute(),...t]}function createGeneratedServiceBuild(e){let t=join(e.nuxtRoot,`.eve/vercel-services`,`eve`),r=join(t,`.vercel`,`output`),i=join(e.nuxtRoot,`.vercel`,`output`),a=toPosixRelative(t,e.appRoot),c=toPosixRelative(e.appRoot,r),l=toPosixRelative(e.appRoot,i),u=e.eveBuildCommand??`node ${quoteShellArgument(toPosixRelative(e.appRoot,resolveEveBinaryPath(e.nuxtRoot)))} build`;return{buildCommand:`cd ${quoteShellArgument(a)} && export ${EVE_INTERNAL_BUILD_OUTPUT_DIRECTORY_ENV}=${quoteShellArgument(c)} && export ${EVE_INTERNAL_HOST_BUILD_OUTPUT_DIRECTORY_ENV}=${quoteShellArgument(l)} && ${u}`,root:toPosixRelative(e.nuxtRoot,t),rootDirectory:t}}async function ensureEveVercelServicesConfig(e){let r=await findClosestLinkedVercelDirectory(e.nuxtRoot),a=await readVercelJsonConfig(join(r===void 0?e.nuxtRoot:dirname(r),VERCEL_JSON_FILE_NAME)),o=createServiceConfigRecord(a.services);if(Object.keys(o).length>0)return assertRootServicesIncludeEve(o),{mode:`root`};a.experimentalServices!==void 0&&console.warn(`[eve] ${VERCEL_JSON_FILE_NAME} defines experimentalServices, which Vercel no longer routes. The eve Nuxt module now generates the stable services config automatically — remove experimentalServices from ${VERCEL_JSON_FILE_NAME}.`);let s=createGeneratedServiceBuild(e);return await mkdir(s.rootDirectory,{recursive:!0}),{mode:`generated`,services:{eve:{buildCommand:s.buildCommand,framework:`eve`,routes:[createEveServiceRequestPathRoute()],root:s.root}}}}function mergeEveVercelConfig(e,t){let n=e?.services??{},r=Object.entries(n).find(([e,t])=>e===`eve`||t.framework===`eve`),i=r?.[0]??`eve`,a=r?{...n,[i]:{...r[1],routes:insertEveServiceRequestPathRoute(r[1].routes)}}:{...n,...t.services};return{version:3,...e,routes:insertEveServiceRoute(e?.routes??[],i),services:a}}export{createEveServiceRequestPathRoute,createEveServiceRoute,ensureEveVercelServicesConfig,mergeEveVercelConfig};

package/dist/src/runtime/framework-tools/todo.js

@@ -1,3 +1,3 @@
-import{z}from"#compiled/zod/index.js";import{loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";const TodoStateKey=new ContextKey(`eve.todo`);function formatTodoSummary(e){return e.items.length===0?void 0:`[Your task list was preserved across context compaction]\n${e.items.map(e=>`- [${e.status===`completed`?`x`:e.status===`cancelled`?`-`:` `}] [${e.priority}] ${e.content}`).join(`
+import{z}from"#compiled/zod/index.js";import{loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";import{TODO_COMPACTION_PRESERVATION_LABEL}from"#harness/compaction-prompt.js";const TodoStateKey=new ContextKey(`eve.todo`);function formatTodoSummary(e){return e.items.length===0?void 0:`${TODO_COMPACTION_PRESERVATION_LABEL}\n${e.items.map(e=>`- [${e.status===`completed`?`x`:e.status===`cancelled`?`-`:` `}] [${e.priority}] ${e.content}`).join(`
 `)}`}function getTodoCompactionMessage(){let e=loadContext().get(TodoStateKey);if(e===void 0||e.items.length===0)return;let n=formatTodoSummary(e);if(n!==void 0)return{content:n,role:`user`}}function formatTodoResult(e){let{items:t}=e,n={cancelled:0,completed:0,in_progress:0,pending:0,total:t.length};for(let e of t)n[e.status]++;return{counts:n,todos:t}}function executeTodoTool(e){let n=loadContext(),{todos:r}=e??{};if(r!==void 0){let e={items:[...r]};return n.set(TodoStateKey,e),formatTodoResult(e)}return formatTodoResult(n.ensure(TodoStateKey,()=>({items:[]})))}const TODO_ITEM_SCHEMA=z.strictObject({content:z.string().describe(`Brief description of the task.`),priority:z.enum([`high`,`medium`,`low`]).describe(`Priority level of the task.`),status:z.enum([`pending`,`in_progress`,`completed`,`cancelled`]).describe(`Current status of the task.`)}),TODO_INPUT_SCHEMA=z.strictObject({todos:z.array(TODO_ITEM_SCHEMA).describe(`The updated todo list. Omit to read the current list without modifying it.`).optional()}),countSchema=z.number().int().min(0),TODO_OUTPUT_SCHEMA=z.strictObject({counts:z.strictObject({cancelled:countSchema,completed:countSchema,in_progress:countSchema,pending:countSchema,total:countSchema}),todos:z.array(TODO_ITEM_SCHEMA)}),TODO_TOOL_DEFINITION={description:[`Use this tool to create and manage a structured task list for the current session.`,`This helps you track progress, organize complex tasks, and demonstrate thoroughness.`,``,`When to use:`,`- Complex multistep tasks requiring 3 or more distinct steps`,`- When the user provides multiple tasks or a numbered list`,`- After receiving new instructions, to capture requirements`,`- After completing a task, to mark it complete and add follow-ups`,``,`When NOT to use:`,`- Single, straightforward tasks that need no tracking`,`- Purely conversational or informational requests`,``,`Usage:`,"- Call with `todos` to replace the entire list (full replacement write)","- Call without `todos` to read the current list",`- Both return the full current list with status counts`,`- Mark tasks in_progress when you start, completed when done`,`- Only have ONE task in_progress at a time`].join(`
 `),execute:async e=>executeTodoTool(e??{}),inputSchema:TODO_INPUT_SCHEMA,logicalPath:`eve:framework/todo`,name:`todo`,outputSchema:TODO_OUTPUT_SCHEMA,sourceId:`eve:todo-tool`,sourceKind:`module`};export{TODO_INPUT_SCHEMA,TODO_OUTPUT_SCHEMA,TODO_TOOL_DEFINITION,TodoStateKey,executeTodoTool,getTodoCompactionMessage};

package/dist/src/runtime/governance/auth/http-basic.js

@@ -1 +1 @@
-import{createHash,timingSafeEqual}from"node:crypto";function authenticateHttpBasicStrategy(e){let t=parseBasicAuthorizationHeader(e.authorization);return t===null||t.username!==e.strategy.username||!timingSafeStringEquals(t.password,e.strategy.password)?{kind:`not-authenticated`}:{kind:`authenticated`,principal:{attributes:Object.freeze({}),authenticator:`http-basic`,claims:Object.freeze({}),principalId:e.strategy.username,principalType:`user`}}}function parseBasicAuthorizationHeader(e){let t=/^Basic\s+(.+)$/i.exec(e);if(t===null)return null;let n=t[1];if(n===void 0)return null;let r;try{r=Buffer.from(n,`base64`).toString(`utf8`)}catch{return null}let i=r.indexOf(`:`);return i===-1?null:{password:r.slice(i+1),username:r.slice(0,i)}}function timingSafeStringEquals(e,n){return timingSafeEqual(hashString(e),hashString(n))}function hashString(t){return createHash(`sha256`).update(t,`utf8`).digest()}export{authenticateHttpBasicStrategy};
+import{createHash,timingSafeEqual}from"node:crypto";function authenticateHttpBasicStrategy(e){let t=parseBasicAuthorizationHeader(e.authorization);return t===null||normalizeCredential(t.username)!==normalizeCredential(e.strategy.username)||!timingSafeStringEquals(normalizeCredential(t.password),normalizeCredential(e.strategy.password))?{kind:`not-authenticated`}:{kind:`authenticated`,principal:{attributes:Object.freeze({}),authenticator:`http-basic`,claims:Object.freeze({}),principalId:e.strategy.username,principalType:`user`}}}function parseBasicAuthorizationHeader(e){let t=/^Basic\s+(.+)$/i.exec(e);if(t===null)return null;let n=t[1];if(n===void 0)return null;let r;try{r=Buffer.from(n,`base64`).toString(`utf8`)}catch{return null}let i=r.indexOf(`:`);return i===-1?null:{password:r.slice(i+1),username:r.slice(0,i)}}function normalizeCredential(e){return e.normalize(`NFC`)}function timingSafeStringEquals(e,n){return timingSafeEqual(hashString(e),hashString(n))}function hashString(t){return createHash(`sha256`).update(t,`utf8`).digest()}export{authenticateHttpBasicStrategy};

package/dist/src/setup/scaffold/create/project.js

@@ -1,4 +1,4 @@
-import{pinnedNodeEngineMajor}from"../../node-engine.js";import{SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS}from"../update/module-files.js";import{pathExists,writeTextFile}from"../files.js";import{resolveVersionToken}from"../version-tokens.js";import{applyPackageManagerWorkspaceConfiguration,isPackageManagerWorkspaceMember,patchWorkspaceRootPackageJson}from"../workspace-root.js";import{WEB_APP_TEMPLATE_FILES}from"./web-template.js";import{basename,join,resolve}from"node:path";import{mkdir,readdir,stat}from"node:fs/promises";const CURRENT_DIRECTORY_PROJECT_NAME=`.`,ALLOWED_CREATE_IN_PLACE_ENTRIES=new Set([`.DS_Store`,`.git`,`.gitkeep`,`.hg`]),DEFAULT_AI_PACKAGE_VERSION=`^7.0.26`,DEFAULT_CONNECT_PACKAGE_VERSION=`0.4.0`,DEFAULT_ZOD_PACKAGE_VERSION=`4.4.3`,DEFAULT_EVE_PACKAGE_CONTRACT={version:`0.26.2`,nodeEngine:`>=24`};function resolveEvePackageContract(e=DEFAULT_EVE_PACKAGE_CONTRACT){return{version:resolveVersionToken(`evePackage.version`,e.version),nodeEngine:resolveVersionToken(`evePackage.nodeEngine`,e.nodeEngine)}}function modelProviderSlug(e){let t=(e.split(`/`)[0]??``).replaceAll(/[^A-Za-z0-9._-]/gu,``);return t.length>0?t:`anthropic`}function byokProviderEnvVar(e){let t=modelProviderSlug(e).toUpperCase().replaceAll(/[^A-Z0-9]/gu,`_`);return`${/^[0-9]/.test(t)?`_`:``}${t}_API_KEY`}function agentTemplateFiles(e){return{"agent/agent.ts":BASE_AGENT_TEMPLATE.replaceAll(`__EVE_INIT_MODEL__`,e),"agent/channels/eve.ts":WEB_APP_TEMPLATE_FILES[`agent/channels/eve.ts`],"agent/instructions.md":AGENT_INSTRUCTIONS_TEMPLATE}}function renderTemplate(e,t){return e.replaceAll(`__EVE_INIT_APP_NAME__`,t.appName).replaceAll(`__EVE_INIT_MODEL__`,t.model).replaceAll(`__EVE_INIT_BYOK_PROVIDER__`,modelProviderSlug(t.model)).replaceAll(`__EVE_INIT_BYOK_ENV_VAR__`,byokProviderEnvVar(t.model)).replaceAll(`__EVE_INIT_PACKAGE_VERSION__`,formatEveDependencySpecifier(t.eveVersion)).replaceAll(`__EVE_INIT_AI_SDK_VERSION__`,t.aiPackageVersion).replaceAll(`__EVE_INIT_CONNECT_VERSION__`,t.connectPackageVersion).replaceAll(`__EVE_INIT_ZOD_VERSION__`,t.zodPackageVersion).replaceAll(`__EVE_INIT_TYPESCRIPT_VERSION__`,t.typescriptPackageVersion).replaceAll(`__EVE_INIT_TYPES_NODE_VERSION__`,t.nodeTypesVersion).replaceAll(`__EVE_INIT_NODE_ENGINE__`,t.nodeEngine)}function formatEveDependencySpecifier(e){return/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/.test(e)?`^${e}`:e}const BASE_AGENT_TEMPLATE=`import { defineAgent } from "eve";
+import{pinnedNodeEngineMajor}from"../../node-engine.js";import{SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS}from"../update/module-files.js";import{pathExists,writeTextFile}from"../files.js";import{resolveVersionToken}from"../version-tokens.js";import{applyPackageManagerWorkspaceConfiguration,isPackageManagerWorkspaceMember,patchWorkspaceRootPackageJson}from"../workspace-root.js";import{WEB_APP_TEMPLATE_FILES}from"./web-template.js";import{basename,join,resolve}from"node:path";import{mkdir,readdir,stat}from"node:fs/promises";const CURRENT_DIRECTORY_PROJECT_NAME=`.`,ALLOWED_CREATE_IN_PLACE_ENTRIES=new Set([`.DS_Store`,`.git`,`.gitkeep`,`.hg`]),DEFAULT_AI_PACKAGE_VERSION=`^7.0.26`,DEFAULT_CONNECT_PACKAGE_VERSION=`0.4.0`,DEFAULT_ZOD_PACKAGE_VERSION=`4.4.3`,DEFAULT_EVE_PACKAGE_CONTRACT={version:`0.27.0`,nodeEngine:`>=24`};function resolveEvePackageContract(e=DEFAULT_EVE_PACKAGE_CONTRACT){return{version:resolveVersionToken(`evePackage.version`,e.version),nodeEngine:resolveVersionToken(`evePackage.nodeEngine`,e.nodeEngine)}}function modelProviderSlug(e){let t=(e.split(`/`)[0]??``).replaceAll(/[^A-Za-z0-9._-]/gu,``);return t.length>0?t:`anthropic`}function byokProviderEnvVar(e){let t=modelProviderSlug(e).toUpperCase().replaceAll(/[^A-Z0-9]/gu,`_`);return`${/^[0-9]/.test(t)?`_`:``}${t}_API_KEY`}function agentTemplateFiles(e){return{"agent/agent.ts":BASE_AGENT_TEMPLATE.replaceAll(`__EVE_INIT_MODEL__`,e),"agent/channels/eve.ts":WEB_APP_TEMPLATE_FILES[`agent/channels/eve.ts`],"agent/instructions.md":AGENT_INSTRUCTIONS_TEMPLATE}}function renderTemplate(e,t){return e.replaceAll(`__EVE_INIT_APP_NAME__`,t.appName).replaceAll(`__EVE_INIT_MODEL__`,t.model).replaceAll(`__EVE_INIT_BYOK_PROVIDER__`,modelProviderSlug(t.model)).replaceAll(`__EVE_INIT_BYOK_ENV_VAR__`,byokProviderEnvVar(t.model)).replaceAll(`__EVE_INIT_PACKAGE_VERSION__`,formatEveDependencySpecifier(t.eveVersion)).replaceAll(`__EVE_INIT_AI_SDK_VERSION__`,t.aiPackageVersion).replaceAll(`__EVE_INIT_CONNECT_VERSION__`,t.connectPackageVersion).replaceAll(`__EVE_INIT_ZOD_VERSION__`,t.zodPackageVersion).replaceAll(`__EVE_INIT_TYPESCRIPT_VERSION__`,t.typescriptPackageVersion).replaceAll(`__EVE_INIT_TYPES_NODE_VERSION__`,t.nodeTypesVersion).replaceAll(`__EVE_INIT_NODE_ENGINE__`,t.nodeEngine)}function formatEveDependencySpecifier(e){return/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/.test(e)?`^${e}`:e}const BASE_AGENT_TEMPLATE=`import { defineAgent } from "eve";
 
 export default defineAgent({
   model: "__EVE_INIT_MODEL__",

package/dist/src/{public/next → shared}/resolve-eve-binary.d.ts

@@ -9,4 +9,4 @@
  * derive the bin path from the package root. Falls back to the conventional
  * app-local path when eve cannot be resolved (e.g. before install).
  */
-export declare function resolveEveBinaryPath(nextRoot: string): string;
+export declare function resolveEveBinaryPath(appRoot: string): string;

package/docs/extensions.md

@@ -1,39 +1,48 @@
 ---
 title: "Extensions"
-description: "Package tools, connections, skills, and hooks as a reusable package and mount it into an agent."
+description: "Publish reusable eve capabilities as an npm package, then install and mount them in an agent."
 ---
 
-An extension packages eve capabilities — tools, connections, skills, instructions, hooks — as a reusable npm or local package. You author it as an agent-shaped directory; a consuming agent mounts it under `agent/extensions/`, and its contributions compose into the agent under a namespace. Nothing is copied — upgrades come through the package manager.
+Extensions package eve tools, connections, skills, instruction fragments, and hooks. A publisher builds and distributes a package; a consumer installs it and mounts it in an agent.
 
-## Authoring
+This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
 
-Start from a scaffold:
+## Publisher: create and publish an extension
+
+### Create the package
+
+Start with the extension scaffold:
 
 ```bash
 npx eve@latest extension init my-crm
 ```
 
-This creates the package, installs dependencies, and initializes Git. You get `extension/extension.ts`, TypeScript config, and a `package.json` ready to publish or mount. Add tools, skills, hooks, and connections under `extension/` yourself.
+The command creates the package, installs dependencies, and initializes Git. It includes `extension/extension.ts`, TypeScript configuration, and the package metadata required to build and publish.
 
-An extension is an agent-shaped directory without `agent.ts` or `sandbox` (those belong to the consuming agent). Every slot works as it does in an agent, with names derived from paths.
+An extension uses the same file conventions as an agent for its contributions:
 
 ```
 @acme/crm/
   package.json
   extension/
-    extension.ts        # the extension declaration — see Configuration
+    extension.ts
     tools/search.ts
     connections/api.ts
     skills/triage/SKILL.md
+    instructions.md
     hooks/audit.ts
-    lib/http.ts         # shared helpers, imported as ../lib/http
+    lib/http.ts
 ```
 
-Name tools and connections for what they do (`search`, not `crm_search`) — the mount supplies the namespace. Shared code goes in `extension/lib/`, imported by relative path — eve compiles the source, so relative imports need no `.js` extension.
+Each listed slot accepts the same authored forms as its agent counterpart. Static and dynamic tools, skills, and instructions all work in an extension: `extension/instructions.ts` is as valid as `extension/instructions.md`, and `extension/tools/` can contain `defineDynamic(...)`.
+
+Names come from paths, so call the tool `search`, not `crm_search`; the consumer's mount adds the `crm__` prefix. Keep shared code in `extension/lib/`.
 
-### Configuration
+Keep agent configuration, sandboxes, schedules, and nested extensions in the consumer's agent.
 
-Declare the extension in `extension/extension.ts` with `defineExtension`; its default export is the mount factory a consumer calls. Pass `config` — any [Standard Schema](https://standardschema.dev) (a Zod object here), like a tool's `inputSchema` — to accept consumer settings:
+### Add configuration and contributions
+
+The publisher's `extension/extension.ts` default-exports a `defineExtension` handle. Give it a [Standard Schema](https://standardschema.dev) when consumers need to provide settings:
 
 ```ts title="extension/extension.ts"
 import { defineExtension } from "eve/extension";
@@ -42,40 +51,41 @@ import { z } from "zod";
 export default defineExtension({
   config: z.object({
     apiKey: z.string(),
-    baseUrl: z.string().default("https://api.acme.example"),
+    baseUrl: z.string().url().default("https://api.acme.example"),
   }),
 });
 ```
 
-Config is optional — `defineExtension()` with no schema. Read it off the handle, imported from the declaration; it's typed from the schema:
+Contributions import that handle to read the validated configuration. Defaults have already been applied:
 
 ```ts title="extension/tools/search.ts"
 import { defineTool } from "eve/tools";
+import { z } from "zod";
 
 import extension from "../extension";
 
 export default defineTool({
   description: "Search the CRM.",
-  inputSchema: {/* ... */},
+  inputSchema: z.object({ query: z.string() }),
   async execute({ query }) {
-    const { apiKey, baseUrl } = extension.config; // validated, defaults applied
+    const { apiKey, baseUrl } = extension.config;
+    return { query, baseUrl, authenticated: apiKey.length > 0 };
   },
 });
 ```
 
-Config is bound once when the consumer mounts the extension and stays constant for the session; per-request values belong in connection auth instead.
+If no configuration is needed, export `defineExtension()` and let consumers re-export it directly. Config schemas must validate synchronously.
 
-### State
+`defineState` is automatically scoped to the publisher's package, so the same state name does not collide with the consumer or another extension.
 
-`defineState` is scoped to the extension's package automatically, so identically-named state never collides with the consuming agent or another extension. Author it exactly as in an agent — `defineState("budget", …)`.
+### Build and publish
 
-## Publishing
-
-Declare separate authoring and distribution roots and run `eve extension build` (wired to `build`/`prepare`):
+The scaffold's `package.json` declares separate source and distribution roots:
 
 ```jsonc title="package.json"
 {
-  "name": "@acme/crm",
+  "name": "my-crm",
+  "version": "0.0.0",
   "type": "module",
   "eve": {
     "extension": {
@@ -84,86 +94,105 @@ Declare separate authoring and distribution roots and run `eve extension build`
     },
   },
   "files": ["dist"],
-  "peerDependencies": { "eve": "*" },
-  "devDependencies": { "eve": "x.y.z", "typescript": "^x" },
-  "dependencies": { "zod": "^3" },
-  "scripts": { "build": "eve extension build", "prepare": "eve extension build" },
-}
-```
-
-Author the source with `moduleResolution: "bundler"` — eve compiles it, so relative imports need no `.js` extension:
-
-```jsonc title="tsconfig.json"
-{
-  "compilerOptions": {
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "types": ["node"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs",
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.mjs",
+    },
+  },
+  "scripts": {
+    "build": "eve extension build",
+    "prepare": "eve extension build",
+    "typecheck": "tsc",
+  },
+  "dependencies": {
+    "zod": "^x",
+  },
+  "devDependencies": {
+    "@types/node": "^x",
+    "eve": "x.y.z",
+    "typescript": "^x",
+  },
+  "peerDependencies": {
+    "eve": "*",
+  },
+  "engines": {
+    "node": ">=24",
   },
-  "include": ["extension/**/*.ts"],
 }
 ```
 
-`eve extension build` transforms every JavaScript or TypeScript module into an agent-shaped `dist/extension` tree, copies skill packages and their assets, emits type declarations, and writes `dist/extension/_manifest.json`. The generated package entrypoints (`dist/index.mjs` and `dist/tools/index.mjs`) re-export those same dist modules, and the build fills the `exports` map so you never hand-list it. The published package therefore needs `dist/`, not the author's original TypeScript. Consumers read only `eve.extension.dist`, so a published package may omit `eve.extension.source`; keep `source` declared wherever `eve extension build` runs.
+The scaffold omits `engines` when it creates a workspace package.
 
-The build uses the package `tsconfig.json` when it emits declarations. Its `include` must cover every JavaScript or TypeScript module in the extension source (and JavaScript modules require `allowJs`); the build fails before publishing if any distributed module would be missing its declaration.
+Build the package with `eve extension build`:
 
-The manifest contains only its format, the diagnostic eve build version, and the versions of extension capabilities this package actually uses. It does not contain compiled tools, schemas, names, or executable definitions; the consuming eve still discovers and normalizes the agent-shaped dist tree.
+```bash
+eve extension build
+```
 
-### Workspace development
+`eve extension build` writes an agent-shaped `dist/extension` tree, copies skill assets, emits declarations, and records compatibility metadata. It also manages the package exports for the mount factory (`@acme/crm`) and tool definitions (`@acme/crm/tools`). Publish `dist/`; consumers do not need the publisher's TypeScript source.
 
-During local development, `eve dev` automatically rebuilds mounted workspace extensions when their source changes.
+The exact `eve` development pin controls the publisher's authoring API and build tooling. The wildcard peer lets the consumer provide the runtime copy of eve. At consumption time, eve checks generated metadata, not the npm peer range. Do not add eve to regular `dependencies`.
 
-### Dependencies
+Put runtime packages such as `zod` or an SDK in `dependencies`. If a dependency cannot be bundled, such as a native addon, tell consumers to add it to `build.externalDependencies` in `agent.ts`.
 
-`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`.
+Consumers can now add the built package to an agent.
 
-`eve extension init` pins `devDependencies.eve` to the exact eve release that created the scaffold:
+## Consumer: install and mount an extension
 
-```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.
+A mount gives the publisher's contributions a namespace. Updating the package updates the mounted extension; nothing is copied into the consumer's agent.
 
-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.
+### Install the package
 
-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`.
+Install the extension in the consumer's agent project:
 
-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.
+```bash
+npm install @acme/crm
+```
 
-## Mounting
+### Mount it
 
-A consuming agent mounts an extension under `agent/extensions/` — a single file, or a directory when it needs [overrides](#overrides). The namespace is the file basename or directory name; contributions compose as `<namespace>__<name>` (`crm__search`, `crm__api`).
+Create a file under `agent/extensions/`. Its filename becomes the mount namespace. Call the publisher's default export when the extension needs configuration:
 
 ```ts title="agent/extensions/crm.ts"
 import crm from "@acme/crm";
 
-export default crm({ apiKey: process.env.CRM_API_KEY });
+export default crm({ apiKey: process.env.CRM_API_KEY! });
 ```
 
-A no-config extension takes no factory call — mount it with a bare re-export:
+Set `CRM_API_KEY` in the consumer's environment, such as `.env.local` for local development.
+
+The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, and `connections/api.ts` becomes `crm__api`.
+
+For a publisher with no configuration, mount its default export directly:
 
 ```ts title="agent/extensions/gizmo.ts"
 export { default } from "@acme/gizmo";
 ```
 
-### Overrides
+The same mount shape works with an npm package, a workspace dependency, or a linked local package.
+
+### Override a contribution
 
-To override a mounted extension's contributions, author the mount as a directory: the declaration in `extension.ts`, override slots alongside it.
+Use a directory mount to replace or remove a publisher contribution. Put the mount declaration in `extension.ts` and add overrides beside it:
 
 ```
 agent/extensions/crm/
-  extension.ts         # export default crm({ apiKey: process.env.CRM_API_KEY })
-  tools/search.ts      # composes as crm__search, shadowing the extension's own
+  extension.ts
+  tools/search.ts
 ```
 
-A file in an override slot composes under the mount namespace and wins on a name collision. Name it for the bare contribution name (`search`, not `crm__search`) — the directory supplies the prefix. To tweak the extension's own definition, import and re-define it:
+```ts title="agent/extensions/crm/extension.ts"
+import crm from "@acme/crm";
+
+export default crm({ apiKey: process.env.CRM_API_KEY! });
+```
+
+A same-named consumer tool, connection, or skill wins. To adjust a publisher tool, import it from the package's `./tools` export and define it again:
 
 ```ts title="agent/extensions/crm/tools/search.ts"
 import { search } from "@acme/crm/tools";
@@ -173,7 +202,7 @@ import { always } from "eve/tools/approval";
 export default defineTool({ ...search, approval: always() });
 ```
 
-Or drop it entirely by opting out of the slot with `disableTool()`:
+To remove a publisher tool, use `disableTool()` in its matching slot:
 
 ```ts title="agent/extensions/crm/tools/search.ts"
 import { disableTool } from "eve/tools";
@@ -181,13 +210,13 @@ import { disableTool } from "eve/tools";
 export default disableTool();
 ```
 
-An override targets one slot, matched by name and kind: a static file replaces the extension's static tool, a dynamic file replaces its dynamic resolver, and `disableTool()` removes whichever the extension put there. Because a dynamic tool wins over a same-named static one at runtime, replace or disable a dynamic tool through its own slot — a static file of the same name won't shadow it.
+Hooks and instruction fragments are additive, so they cannot be replaced. To replace a dynamic tool, use a dynamic definition in the same slot; dynamic tools win over same-named static tools at runtime. `disableTool()` removes either kind.
 
-Overrides only work here — the `<namespace>__` prefix is reserved, so an agent-root contribution named `crm__…` is a build error and an extension can't be shadowed from outside its mount.
+The `crm__` prefix is reserved for this directory mount. A consumer cannot override the extension from `agent/tools/`, `agent/connections/`, or another agent-root slot.
 
-### Typed tool results
+### Use a publisher tool result in a hook
 
-A consuming agent can narrow a mounted extension's tool result in a hook: import the tool from the extension's `./tools` export and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results). It matches the namespaced result (`crm__search`) because identity keys off the tool definition, not its name.
+To retain a publisher tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results):
 
 ```ts title="agent/hooks/narrow-crm.ts"
 import { defineHook } from "eve/hooks";
@@ -198,14 +227,23 @@ export default defineHook({
   events: {
     "action.result"(event) {
       const match = toolResultFrom(event.data.result, search);
-      if (match) console.log(match.output); // typed as search's output
+      if (match) console.log(match.output);
     },
   },
 });
 ```
 
-Matching keys off the tool's description, so keep extension tool descriptions distinct — one shared with another tool makes the identity ambiguous and `toolResultFrom` stops matching.
+`toolResultFrom` recognizes the mounted `crm__search` result from the original definition, not the namespaced string. Publishers should keep tool descriptions distinct so eve can assign each definition an unambiguous identity.
+
+### Compatibility
+
+At build time, eve checks the publisher's generated capability metadata. If the extension needs an unsupported capability contract, upgrade eve or install a compatible extension release.
 
-## Limits
+## What to read next
 
-An extension cannot declare a `sandbox`, agent config, schedules, or limits, and cannot mount other extensions — those are the consuming agent's to own (background scheduling, for instance, runs on the agent's deployment under its limits). An extension's tools run within the consuming agent's per-session limits.
+- [Tools](/docs/tools): static tools, approval, and tool output
+- [Dynamic capabilities](/docs/guides/dynamic-capabilities): dynamic tools, skills, and instructions
+- [Instructions](/docs/instructions): static and TypeScript instructions
+- [Skills](/docs/skills): package procedures and supporting files
+- [Connections](/docs/connections): integrate external services
+- [Hooks](/docs/guides/hooks): observe agent events

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

@@ -41,7 +41,7 @@ export default eveChannel({
 - returns `null` / `undefined`: skip to the next entry
 - **throws**: reject with a specific status
 
-If every entry skips, the request gets a `401`. An empty array `auth: []` rejects everything.
+If every entry skips, the request gets a `401` whose `WWW-Authenticate` header advertises the challenge scheme(s) the configured entries declare — `Basic` for `httpBasic()`, `Bearer` for the token-based helpers (`jwtHmac`, `jwtEcdsa`, `oidc`, `vercelOidc`), both when you mix them, and `Bearer` as a fallback for entries that don't declare a scheme (custom `AuthFn`s, or an empty array). See [`withAuthChallenges`](#custom-verifiers) to declare a scheme on a custom `AuthFn`.
 
 ```ts
 import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
@@ -96,6 +96,8 @@ Any other thrown error follows the normal channel failure path. When building a
 | `jwtEcdsa(...)`  | You verify asymmetric JWTs minted by another system.                      |
 | `oidc(...)`      | You want eve to verify OIDC-issued tokens from an arbitrary issuer.       |
 
+`httpBasic(credentials, { realm })` accepts an optional `realm`, rendered on the `WWW-Authenticate: Basic` challenge (e.g. `Basic realm="agent", charset="UTF-8"`) so browsers label their native login prompt. It defaults to `"eve"`, ensuring every Basic challenge includes the required realm. Usernames and passwords are normalized to Unicode NFC before comparison, matching the advertised UTF-8 credential encoding.
+
 Exercise caution for agents that process non-public, sensitive, regulated, or production data unless you have implemented other access controls.
 
 ### `localDev()`
@@ -131,6 +133,17 @@ vercelOidc({
 
 When none of the shipped helpers fit, write your own `AuthFn` (the array example above) or call the low-level verifiers directly. Each verifier is the pure function sitting behind the matching strategy helper, and returns `{ ok: true, sessionAuth }` or `{ ok: false }`:
 
+A custom `AuthFn` doesn't declare a `WWW-Authenticate` scheme by default, so `routeAuth` falls back to `Bearer` for it. Wrap it with `withAuthChallenges(fn, challenges)` to declare the scheme(s) it actually satisfies, so a mixed `auth` array produces an accurate 401:
+
+```ts
+import { withAuthChallenges, type AuthFn } from "eve/channels/auth";
+
+const apiKeyAuth: AuthFn<Request> = withAuthChallenges(
+  (request) => (isValidApiKey(request) ? apiKeySessionAuth : null),
+  [{ scheme: "Bearer" }],
+);
+```
+
 | Verifier                               | Behind         | Input                            |
 | -------------------------------------- | -------------- | -------------------------------- |
 | `verifyHttpBasic(header, credentials)` | `httpBasic()`  | raw `Authorization` header value |

package/docs/guides/frontend/nuxt.mdx

@@ -74,7 +74,7 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
 ## Dev vs deploy topology
 
 - **Local dev.** `npm run dev` starts the eve dev server next to `nuxt dev` and proxies the eve routes through it. As far as the browser knows, everything is the Nuxt origin.
-- **Vercel.** A single Vercel project carries both the Nuxt app and the eve runtime. The web app stays public; the runtime sits behind it on the same origin. Set `eveBuildCommand` when the agent needs its own build step:
+- **Vercel.** The web app and the eve runtime deploy as a single project. On Vercel builds the module adds Build Output [`services`](https://vercel.com/docs/services) for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Nuxt app itself remains the default app. No `vercel.json` is required. By default the generated service runs the installed eve binary from the agent root, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:
 
   ```ts
   export default defineNuxtConfig({
@@ -92,6 +92,27 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
   EVE_NUXT_PRODUCTION_PORT=5000 npm run build && npm run preview
   ```
 
+## Managing vercel.json yourself
+
+When `vercel.json` declares [`services`](https://vercel.com/docs/services), the module generates nothing and your configuration owns routing. It must include the eve service (`framework: "eve"`) and a rewrite that exposes the eve transport, or the module fails the build:
+
+```json title="vercel.json"
+{
+  "services": {
+    "web": { "root": ".", "framework": "nuxtjs" },
+    "eve": { "root": "agent", "framework": "eve", "buildCommand": "eve build" }
+  },
+  "rewrites": [{ "source": "/eve/v1/(.*)", "destination": { "service": "eve" } }]
+}
+```
+
+### Migrating from experimentalServices
+
+Earlier versions of the module wrote the legacy `experimentalServices` field into `vercel.json`. Vercel no longer routes that model — deployments build both services but every `/eve/v1/*` request returns a platform NOT_FOUND — so the module now ignores the field and warns when it sees one. Migrate either way:
+
+- **Generated (default).** Delete `vercel.json` (or just its `experimentalServices` block) and set the project's Framework Preset back to Nuxt.js. The module generates the eve service and its routing on every Vercel build.
+- **Hand-maintained.** Replace `experimentalServices` with the stable `services` and `rewrites` shown above, and keep the "Services" Framework Preset.
+
 ## What to read next
 
 - [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API

package/docs/meta.json

@@ -9,6 +9,7 @@
     "skills",
     "channels",
     "connections",
+    "extensions",
     "sandbox",
     "subagents",
     "schedules",

package/package.json

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

package/dist/src/public/nuxt/vercel-json.d.ts

@@ -1,17 +0,0 @@
-export interface EnsureVercelJsonResult {
-    readonly servicePrefix: string;
-}
-/**
- * Ensure `vercel.json` declares the Nuxt web service and the eve agent
- * service so a Vercel deployment ships both from one project.
- *
- * Existing services are preserved untouched; an already-configured eve
- * service's `routePrefix` wins over {@link input.servicePrefix}. The file is
- * only rewritten when the resulting config differs from what is on disk.
- */
-export declare function ensureEveVercelJson(input: {
-    readonly appRoot: string;
-    readonly eveBuildCommand: string;
-    readonly nuxtRoot: string;
-    readonly servicePrefix: string;
-}): Promise<EnsureVercelJsonResult>;

package/dist/src/public/nuxt/vercel-json.js

@@ -1 +0,0 @@
-import{join,relative}from"node:path";import{readFile,writeFile}from"node:fs/promises";const VERCEL_JSON_FILE_NAME=`vercel.json`;function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function resolveRelativeEntrypoint(e,n){let r=relative(e,n);return r.length===0?`.`:r.replaceAll(`\\`,`/`)}function normalizeVercelJsonConfig(e){if(!isRecord(e))throw Error(`${VERCEL_JSON_FILE_NAME} must contain a JSON object.`);let t=e.experimentalServices;if(t!==void 0&&!isRecord(t))throw Error(`${VERCEL_JSON_FILE_NAME} experimentalServices must be a JSON object.`);return e}async function readVercelJsonConfig(e){try{return normalizeVercelJsonConfig(JSON.parse(await readFile(e,`utf8`)))}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return{};throw e}}function findServiceByFramework(e,t){return Object.values(e).find(e=>e.framework===t)}async function ensureEveVercelJson(t){let n=join(t.nuxtRoot,VERCEL_JSON_FILE_NAME),i=await readVercelJsonConfig(n),a=resolveRelativeEntrypoint(t.nuxtRoot,t.appRoot),o=i.experimentalServices??{},s=findServiceByFramework(o,`eve`),c=findServiceByFramework(o,`nuxtjs`),l=s?.routePrefix??t.servicePrefix,u={...o};c===void 0&&(u.web={entrypoint:`.`,framework:`nuxtjs`,routePrefix:`/`}),s===void 0&&(u.eve={buildCommand:t.eveBuildCommand,entrypoint:a,framework:`eve`,routePrefix:l});let d={...i,$schema:i.$schema??`https://openapi.vercel.sh/vercel.json`,experimentalServices:u};return JSON.stringify(i)!==JSON.stringify(d)&&await writeFile(n,`${JSON.stringify(d,null,2)}\n`),{servicePrefix:l}}export{ensureEveVercelJson};