eve 0.47.0 → 0.47.2

package/dist/src/internal/nitro/host/start-development-server.js

@@ -1,2 +1,2 @@
-import{randomBytes}from"node:crypto";import{EVE_DEV_RUNTIME_ARTIFACTS_REBUILD_ROUTE_PATH,EVE_DEV_RUNTIME_ARTIFACTS_RESUME_ROUTE_PATH,EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH,EVE_DEV_RUNTIME_ARTIFACTS_SUSPEND_ROUTE_PATH}from"#protocol/routes.js";import{isLoopbackServerUrl}from"#shared/network-address.js";import{loadDevelopmentEnvironmentFiles}from"#cli/dev/environment.js";import{resolveDiscoveryProject}from"#discover/project.js";import{eveDevArguments}from"#setup/primitives/index.js";import{detectPackageManager}from"#setup/package-manager.js";import{EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV,createDevelopmentSandboxRunId}from"#execution/sandbox/development-run.js";import{pruneLocalSandboxTemplatesInBackground,stopDevelopmentSandboxResources}from"#execution/sandbox/bindings/local.js";import{EVE_DEV_ENV_FLAG}from"#internal/application/optional-package-install.js";import{toErrorMessage}from"#shared/errors.js";import{startDevelopmentSandboxPrewarmInBackground}from"#execution/sandbox/development-prewarm.js";import{devBootPhase}from"#internal/dev-boot-progress.js";import{readDevelopmentRuntimeArtifactsRevision}from"#services/dev-client/runtime-artifacts.js";import{createDevelopmentApplicationNitro}from"#internal/nitro/host/create-application-nitro.js";import{prepareDevelopmentApplicationHost}from"#internal/nitro/host/prepare-application-host.js";import{createDevelopmentNitroArtifactsConfig}from"#internal/nitro/host/artifacts-config.js";import{buildDevelopmentHostCandidate}from"#internal/nitro/host/dev-host-candidate.js";import{removeDevelopmentHostWorkspace}from"#internal/nitro/host/dev-host-workspace.js";import{DrainedNitroDevServer}from"#internal/nitro/host/drained-nitro-dev-server.js";import{activateDevelopmentGeneration,discardDevelopmentGeneration}from"#internal/nitro/development-generation.js";import{resolveNitroCompiledArtifactsSource}from"#internal/nitro/routes/runtime-artifacts.js";import{DEFAULT_DEVELOPMENT_SERVER_HOST,normalizeDevelopmentServerClientUrl}from"#internal/nitro/host/dev-server-url.js";import{createDevelopmentAuthoredRebuildCoordinator}from"#internal/nitro/host/dev-authored-rebuild-coordinator.js";import{DevelopmentServerState}from"#internal/nitro/host/dev-server-state.js";import{handleDevRuntimeArtifactsRequest}from"#internal/nitro/routes/dev-runtime-artifacts.js";import{DEFAULT_DEVELOPMENT_SERVER_PORT,MAX_DEVELOPMENT_SERVER_PORT_ATTEMPTS}from"#internal/nitro/host/ports.js";import{createDevelopmentWorkflowWorld,installWorkflowLocalQueueEnvironment,installWorkflowTransportEnvironment}from"#internal/nitro/host/dev-workflow-world-setup.js";const MAX_ALLOWED_DEVELOPMENT_SERVER_PORT=65535,PORT_ENV=`PORT`;async function isActiveDevelopmentServerForApp(e){try{let t=await new DevelopmentServerState(await resolveDiscoveryProject(e.appRoot)).read();return t===void 0||!isLoopbackServerUrl(t)||!await isDevelopmentServerReady(t)?!1:new URL(t).origin===new URL(normalizeDevelopmentServerClientUrl(e.serverUrl)).origin}catch{return!1}}async function isDevelopmentServerReady(e){return await readDevelopmentRuntimeArtifactsRevision({serverUrl:e,timeoutMs:1e3})!==void 0}function isAddressInUseError(e){return e instanceof Error&&`code`in e&&e.code===`EADDRINUSE`}function resolveDevelopmentServerPort(e){let t=typeof e==`string`?Number(e):e??DEFAULT_DEVELOPMENT_SERVER_PORT;if(!Number.isInteger(t)||t<0||t>MAX_ALLOWED_DEVELOPMENT_SERVER_PORT)throw Error(`Invalid development server port "${String(e)}". Expected an integer between 0 and ${MAX_ALLOWED_DEVELOPMENT_SERVER_PORT}.`);return t}function readEnvironmentPort(){let e=process.env[PORT_ENV];if(e===void 0||e.trim()===``)return;let t=Number(e);if(!Number.isInteger(t)||t<0||t>MAX_ALLOWED_DEVELOPMENT_SERVER_PORT)throw Error(`Invalid ${PORT_ENV} environment variable "${e}". Expected an integer between 0 and ${MAX_ALLOWED_DEVELOPMENT_SERVER_PORT}.`);return t}async function detectDevelopmentCommandPackageManager(e){try{return(await detectPackageManager(e)).kind}catch{return`pnpm`}}async function formatDevelopmentServerConnectCommand(e,t){let n=await detectDevelopmentCommandPackageManager(e);return[n,...eveDevArguments(n),t].join(` `)}async function createDevelopmentServerAlreadyRunningError(e,t){let n=await formatDevelopmentServerConnectCommand(e,t);return Error([`A dev server is already running for this eve agent.`,`To connect to the existing instance, run: ${n}`].join(`
+import{randomBytes}from"node:crypto";import{EVE_DEV_RUNTIME_ARTIFACTS_REBUILD_ROUTE_PATH,EVE_DEV_RUNTIME_ARTIFACTS_RESUME_ROUTE_PATH,EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH,EVE_DEV_RUNTIME_ARTIFACTS_SUSPEND_ROUTE_PATH}from"#protocol/routes.js";import{isLoopbackServerUrl}from"#shared/network-address.js";import{loadDevelopmentEnvironmentFiles}from"#cli/dev/environment.js";import{resolveDiscoveryProject}from"#discover/project.js";import{eveDevArguments}from"#setup/primitives/index.js";import{detectPackageManager}from"#setup/package-manager.js";import{EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV,createDevelopmentSandboxRunId}from"#execution/sandbox/development-run.js";import{pruneLocalSandboxTemplatesInBackground,stopDevelopmentSandboxResources}from"#execution/sandbox/bindings/local.js";import{EVE_DEV_ENV_FLAG}from"#internal/application/optional-package-install.js";import{devBootPhase}from"#internal/dev-boot-progress.js";import{readDevelopmentRuntimeArtifactsRevision}from"#services/dev-client/runtime-artifacts.js";import{toErrorMessage}from"#shared/errors.js";import{startDevelopmentSandboxPrewarmInBackground}from"#execution/sandbox/development-prewarm.js";import{createDevelopmentApplicationNitro}from"#internal/nitro/host/create-application-nitro.js";import{prepareDevelopmentApplicationHost}from"#internal/nitro/host/prepare-application-host.js";import{createDevelopmentNitroArtifactsConfig}from"#internal/nitro/host/artifacts-config.js";import{buildDevelopmentHostCandidate}from"#internal/nitro/host/dev-host-candidate.js";import{removeDevelopmentHostWorkspace}from"#internal/nitro/host/dev-host-workspace.js";import{DrainedNitroDevServer}from"#internal/nitro/host/drained-nitro-dev-server.js";import{activateDevelopmentGeneration,discardDevelopmentGeneration}from"#internal/nitro/development-generation.js";import{resolveNitroCompiledArtifactsSource}from"#internal/nitro/routes/runtime-artifacts.js";import{DEFAULT_DEVELOPMENT_SERVER_HOST,normalizeDevelopmentServerClientUrl}from"#internal/nitro/host/dev-server-url.js";import{createDevelopmentAuthoredRebuildCoordinator}from"#internal/nitro/host/dev-authored-rebuild-coordinator.js";import{DevelopmentServerState}from"#internal/nitro/host/dev-server-state.js";import{handleDevRuntimeArtifactsRequest}from"#internal/nitro/routes/dev-runtime-artifacts.js";import{DEFAULT_DEVELOPMENT_SERVER_PORT,MAX_DEVELOPMENT_SERVER_PORT_ATTEMPTS}from"#internal/nitro/host/ports.js";import{createDevelopmentWorkflowWorld,installWorkflowLocalQueueEnvironment,installWorkflowTransportEnvironment}from"#internal/nitro/host/dev-workflow-world-setup.js";const MAX_ALLOWED_DEVELOPMENT_SERVER_PORT=65535,PORT_ENV=`PORT`;async function isActiveDevelopmentServerForApp(e){try{let t=await new DevelopmentServerState(await resolveDiscoveryProject(e.appRoot)).read();return t===void 0||!isLoopbackServerUrl(t)||!await isDevelopmentServerReady(t)?!1:new URL(t).origin===new URL(normalizeDevelopmentServerClientUrl(e.serverUrl)).origin}catch{return!1}}async function isDevelopmentServerReady(e){return await readDevelopmentRuntimeArtifactsRevision({serverUrl:e,timeoutMs:1e3})!==void 0}function isAddressInUseError(e){return e instanceof Error&&`code`in e&&e.code===`EADDRINUSE`}function resolveDevelopmentServerPort(e){let t=typeof e==`string`?Number(e):e??DEFAULT_DEVELOPMENT_SERVER_PORT;if(!Number.isInteger(t)||t<0||t>MAX_ALLOWED_DEVELOPMENT_SERVER_PORT)throw Error(`Invalid development server port "${String(e)}". Expected an integer between 0 and ${MAX_ALLOWED_DEVELOPMENT_SERVER_PORT}.`);return t}function readEnvironmentPort(){let e=process.env[PORT_ENV];if(e===void 0||e.trim()===``)return;let t=Number(e);if(!Number.isInteger(t)||t<0||t>MAX_ALLOWED_DEVELOPMENT_SERVER_PORT)throw Error(`Invalid ${PORT_ENV} environment variable "${e}". Expected an integer between 0 and ${MAX_ALLOWED_DEVELOPMENT_SERVER_PORT}.`);return t}async function detectDevelopmentCommandPackageManager(e){try{return(await detectPackageManager(e)).kind}catch{return`pnpm`}}async function formatDevelopmentServerConnectCommand(e,t){let n=await detectDevelopmentCommandPackageManager(e);return[n,...eveDevArguments(n),t].join(` `)}async function createDevelopmentServerAlreadyRunningError(e,t){let n=await formatDevelopmentServerConnectCommand(e,t);return Error([`A dev server is already running for this eve agent.`,`To connect to the existing instance, run: ${n}`].join(`
 `))}function resolveDevelopmentServerPorts(e){let t=resolveDevelopmentServerPort(e.port);if(t===0||!e.retryOnAddressInUse)return[t];let n=[];for(let e=0;e<MAX_DEVELOPMENT_SERVER_PORT_ATTEMPTS;e+=1){let r=t+e;if(r>65535)break;n.push(r)}return n}function addDevelopmentControlHandler(e){e.devServer.setControlHandler(async a=>{let o=await e.workflowWorld?.handleRequest(a);if(o!==void 0)return o;let s=new URL(a.url);if(s.pathname===EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH&&a.method===`GET`)return handleDevRuntimeArtifactsRequest({appRoot:e.appRoot});let c=s.pathname===EVE_DEV_RUNTIME_ARTIFACTS_SUSPEND_ROUTE_PATH&&a.method===`POST`,l=s.pathname===EVE_DEV_RUNTIME_ARTIFACTS_RESUME_ROUTE_PATH&&a.method===`POST`,u=s.pathname===EVE_DEV_RUNTIME_ARTIFACTS_REBUILD_ROUTE_PATH&&(a.method===`GET`||a.method===`POST`);if(!c&&!l&&!u)return;let d=e.getWatcher();return d===void 0?Response.json({error:`The development server is still starting.`},{status:503}):c?(await d.suspend(),Response.json({suspended:!0})):l?(await d.resume({silent:s.searchParams.get(`silent`)===`1`}),handleDevRuntimeArtifactsRequest({appRoot:e.appRoot})):(s.searchParams.get(`force`)===`1`?await d.rebuild():await d.flush(),handleDevRuntimeArtifactsRequest({appRoot:e.appRoot}))})}async function closeDevelopmentServerResources(e){let t=[],attempt=async e=>{try{return await e(),!0}catch(e){return t.push(e),!1}},n=e.authoredSourceWatcher;n!==void 0&&await attempt(()=>n.close());let r=e.workflowWorld;r!==void 0&&await attempt(()=>r.close());let i=e.devServer,a=i===void 0||await attempt(()=>i.close()),o=e.nitro;return o!==void 0&&await attempt(()=>o.close()),await attempt(()=>stopDevelopmentSandboxResources({appRoot:e.appRoot,devRunId:e.developmentSandboxRunId,log:e=>console.warn(`[eve:dev] ${e}`)})),{errors:t,listenerClosed:a}}function createDevelopmentServerCleanupError(e){if(e.length!==0){if(e.length===1){let t=e[0];return t instanceof Error?t:Error(`Failed to close the development server: ${toErrorMessage(t)}`,{cause:t})}return AggregateError(e,`Multiple development-server resources failed to close.`)}}function createDevelopmentServerStartupCleanupError(e,t){return AggregateError([e,...t],`${toErrorMessage(e)} Cleanup also failed.`,{cause:e})}async function listenForDevelopmentServer(e){let t=resolveDevelopmentServerPorts({port:e.port,retryOnAddressInUse:e.retryOnAddressInUse}),n;for(let r of t){let t=e.devServer.listen({hostname:e.host,port:r});try{return await t.ready(),t}catch(r){if(n=r,await t.close().catch(()=>{}),!isAddressInUseError(r)||!e.retryOnAddressInUse)throw r}}throw Error(`Failed to start Nitro dev server after ${t.length} attempts. Tried ports ${t.join(`, `)}.`,{cause:n})}async function startNitroDevelopmentServer(t,n){process.env[EVE_DEV_ENV_FLAG]??=`1`;let r=await resolveDiscoveryProject(t);loadDevelopmentEnvironmentFiles(r.appRoot);let i=readEnvironmentPort(),c=n.port??i,l=n.host!==void 0||n.port!==void 0||i!==void 0,f=new DevelopmentServerState(r),m=await f.read();if(m!==void 0&&isLoopbackServerUrl(m)&&await isDevelopmentServerReady(m)){if(n.existing===`attach-if-unconfigured`&&!l)return{handle:{kind:`existing`,appRoot:r.appRoot,url:m},close:void 0};throw await createDevelopmentServerAlreadyRunningError(r.appRoot,m)}let h=process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV],v=createDevelopmentSandboxRunId();process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV]=v;let y,b,x,S,C,w,T,E=!1,D=!1;try{let t=await devBootPhase(`compiling agent`,()=>prepareDevelopmentApplicationHost(r.appRoot),n.onBootProgress);T=t;let i=resolveNitroCompiledArtifactsSource(createDevelopmentNitroArtifactsConfig({appRoot:t.appRoot,configuredWorld:t.compileResult.manifest.config.experimental?.workflow?.world}));pruneLocalSandboxTemplatesInBackground(t.appRoot);let a=await devBootPhase(`creating dev server`,()=>createDevelopmentApplicationNitro(t),n.onBootProgress);y=a,b=new DrainedNitroDevServer(a.logger);let o=b,s=randomBytes(32).toString(`base64url`);o.setClientAddressSecret(s),S=installWorkflowTransportEnvironment(r.appRoot,s),C=createDevelopmentWorkflowWorld({appRoot:r.appRoot,preparedHost:t,transportSecret:s}),addDevelopmentControlHandler({appRoot:r.appRoot,devServer:o,getWatcher:()=>w,workflowWorld:C});let l=n.host??a.options.devServer.hostname??DEFAULT_DEVELOPMENT_SERVER_HOST,u=c===void 0,d=await devBootPhase(`binding port`,()=>listenForDevelopmentServer({devServer:o,host:l,port:c,retryOnAddressInUse:u}),n.onBootProgress);if(!d.url)throw Error(`Nitro dev server did not expose a URL.`);let p=normalizeDevelopmentServerClientUrl(d.url);x=installWorkflowLocalQueueEnvironment(p),await devBootPhase(`building dev bundle`,async()=>{let e=await buildDevelopmentHostCandidate({host:t,nitro:a});y=void 0;let n=t.workspace;D=!0,await o.replaceWorker({dispose:async()=>await removeDevelopmentHostWorkspace(n),entry:e.entry,workerData:e.workerData}),await activateDevelopmentGeneration({appRoot:t.appRoot,generation:t.generation}),E=!0},n.onBootProgress),await C?.start(),startDevelopmentSandboxPrewarmInBackground({appRoot:t.appRoot,compiledArtifactsSource:i});let m=await createDevelopmentAuthoredRebuildCoordinator({devServer:o,initialHost:t});w=await devBootPhase(`starting file watcher`,async()=>{let{startAuthoredSourceWatcher:e}=await import(`#internal/nitro/host/dev-authored-source-watcher.js`);return e({coordinator:m,preparedHost:t})},n.onBootProgress),await f.write(p);let g=x;if(g===void 0)throw Error(`Workflow local queue environment was not initialized.`);let _=w,O=b,k=C,A=S,j;return{handle:{kind:`started`,appRoot:r.appRoot,url:p},close:()=>(j??=(async()=>{let e=await closeDevelopmentServerResources({appRoot:r.appRoot,authoredSourceWatcher:_,devServer:O,developmentSandboxRunId:v,nitro:void 0,workflowWorld:k});e.listenerClosed&&await f.remove().catch(()=>{});try{let t=createDevelopmentServerCleanupError(e.errors);if(t!==void 0)throw t}finally{g(),A?.(),restoreDevelopmentSandboxRunId(h)}})(),j)}}catch(e){let t=await closeDevelopmentServerResources({appRoot:r.appRoot,authoredSourceWatcher:w,devServer:b,developmentSandboxRunId:v,nitro:y,workflowWorld:C}),n=[...t.errors];throw T!==void 0&&!E&&await discardDevelopmentGeneration(T.generation).catch(e=>{n.push(e)}),T!==void 0&&!D&&await removeDevelopmentHostWorkspace(T.workspace).catch(e=>{n.push(e)}),x?.(),S?.(),t.listenerClosed&&await f.remove().catch(()=>{}),restoreDevelopmentSandboxRunId(h),n.length>0?createDevelopmentServerStartupCleanupError(e,n):e}}function createDevelopmentServer(e,t={}){let n,r;return{start(){if(n!==void 0)throw Error(`DevelopmentServer.start() was already called.`);return n=startNitroDevelopmentServer(e,t).then(({handle:e,close:t})=>(r=t,e)),n},async close(){n!==void 0&&(await n.catch(()=>void 0),await r?.())}}}function restoreDevelopmentSandboxRunId(e){if(e===void 0){delete process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV];return}process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV]=e}export{createDevelopmentServer,isActiveDevelopmentServerForApp,normalizeDevelopmentServerClientUrl};

package/dist/src/services/dev-client.js

@@ -1 +1 @@
-import{isLocalDevelopmentServerUrl}from"#services/dev-client/local-host.js";import{readDevelopmentRuntimeArtifactsRevision,rebuildDevelopmentRuntimeArtifacts}from"#services/dev-client/runtime-artifacts.js";var LocalDevelopmentRuntimeArtifactRefresher=class{#e;#t;#n;constructor(t){this.#e=isLocalDevelopmentServerUrl(t.serverUrl),this.#t=t.serverUrl}clear(){this.#n=void 0}async refresh(e){shouldRefreshRuntimeArtifactsForTurn(e)&&await this.#r({...e,rebuild:!0})}async refreshIdle(e){await this.#r({...e,rebuild:!1})}async refreshAfterSourceChange(e){await this.#r({...e,force:!0,rebuild:!0})}async#r(e){if(!this.#e)return;let n=(e.rebuild?await rebuildDevelopmentRuntimeArtifacts({force:e.force,serverUrl:this.#t}):void 0)??await readDevelopmentRuntimeArtifactsRevision({serverUrl:this.#t});if(n===void 0)return;let r=this.#n;r!==void 0&&r!==n&&await e.onRuntimeArtifactsChanged?.({previousRevision:r,revision:n}),this.#n=n}};function shouldRefreshRuntimeArtifactsForTurn(e){return e.message!==void 0&&(e.inputResponses?.length??0)===0}function createDevelopmentRuntimeArtifactRefresher(e){return new LocalDevelopmentRuntimeArtifactRefresher(e)}export{createDevelopmentRuntimeArtifactRefresher};
+import{readDevelopmentRuntimeArtifactsRevision,rebuildDevelopmentRuntimeArtifacts}from"#services/dev-client/runtime-artifacts.js";import{isLocalDevelopmentServerUrl}from"#services/dev-client/local-host.js";var LocalDevelopmentRuntimeArtifactRefresher=class{#e;#t;#n;constructor(e){this.#e=isLocalDevelopmentServerUrl(e.serverUrl),this.#t=e.serverUrl}clear(){this.#n=void 0}async refresh(e){shouldRefreshRuntimeArtifactsForTurn(e)&&await this.#r({...e,rebuild:!0})}async refreshIdle(e){await this.#r({...e,rebuild:!1})}async refreshAfterSourceChange(e){await this.#r({...e,force:!0,rebuild:!0})}async#r(t){if(!this.#e)return;let n=(t.rebuild?await rebuildDevelopmentRuntimeArtifacts({force:t.force,serverUrl:this.#t}):void 0)??await readDevelopmentRuntimeArtifactsRevision({serverUrl:this.#t});if(n===void 0)return;let r=this.#n;r!==void 0&&r!==n&&await t.onRuntimeArtifactsChanged?.({previousRevision:r,revision:n}),this.#n=n}};function shouldRefreshRuntimeArtifactsForTurn(e){return e.message!==void 0&&(e.inputResponses?.length??0)===0}function createDevelopmentRuntimeArtifactRefresher(e){return new LocalDevelopmentRuntimeArtifactRefresher(e)}export{createDevelopmentRuntimeArtifactRefresher};

package/dist/src/setup/boxes/select-model.js

@@ -1 +1 @@
-import{select}from"../ask.js";import{z}from"#compiled/zod/index.js";import{DEFAULT_AGENT_MODEL_ID}from"#shared/default-agent-model.js";import{AI_GATEWAY_MODELS_URL,vercelGatewayFetch}from"#internal/gateway.js";const gatewayCatalogModelSchema=z.object({id:z.string(),name:z.string(),type:z.string(),owned_by:z.string(),released:z.number().finite().optional().catch(void 0),tags:z.array(z.string()).optional().catch(void 0),pricing:z.object({service_tiers:z.record(z.string(),z.unknown()).optional().catch(void 0)}).optional().catch(void 0)}),gatewayCatalogSchema=z.object({data:z.array(z.unknown())}).transform(({data:e})=>e.flatMap(e=>{let t=gatewayCatalogModelSchema.safeParse(e);return t.success?[t.data]:[]}));function modelOption(e,t,n,r=!0){return{id:e,label:t,value:e,hint:n,featured:r||void 0}}const FEATURED_MODEL_IDS=[DEFAULT_AGENT_MODEL_ID,`anthropic/claude-opus-4.8`,`openai/gpt-5.5`],FALLBACK_MODELS=[modelOption(DEFAULT_AGENT_MODEL_ID,`GLM 5.2`,`Z.AI`),modelOption(`anthropic/claude-opus-4.8`,`Claude Opus 4.8`,`Anthropic`),modelOption(`openai/gpt-5.5`,`GPT-5.5`,`OpenAI`),modelOption(`google/gemini-3.5`,`Gemini 3.5`,`Google`,!1)],PROVIDER_BRANDS={openai:`OpenAI`,zai:`Z.AI`,xai:`xAI`,deepseek:`DeepSeek`,moonshotai:`Moonshot AI`};function providerLabel(e){return e.length===0?``:PROVIDER_BRANDS[e]??e.charAt(0).toUpperCase()+e.slice(1)}async function fetchGatewayCatalog(e){let t=new AbortController,n=setTimeout(()=>t.abort(),5e3);try{let n=await vercelGatewayFetch(AI_GATEWAY_MODELS_URL,{signal:e===void 0?t.signal:AbortSignal.any([e,t.signal])});if(!n.ok)throw Error(`AI Gateway model catalog request failed (${n.status}).`);return parseGatewayCatalog(await n.json())}finally{clearTimeout(n)}}function parseGatewayCatalog(e){let t=gatewayCatalogSchema.safeParse(e);if(!t.success)throw Error(`AI Gateway returned an invalid model catalog.`);return t.data}function featuredPriority(e){let t=FEATURED_MODEL_IDS.indexOf(e);return t===-1?FEATURED_MODEL_IDS.length:t}function modelOptionsFromCatalog(e){if(e===void 0)return FALLBACK_MODELS;let t=e.filter(e=>e.type===`language`&&(e.id===DEFAULT_AGENT_MODEL_ID||(e.tags??[]).includes(`web-search`))).map(e=>{let t=e.id.split(`/`)[0]??``;return{value:e.id,label:e.name,hint:providerLabel(t),provider:t,released:e.released}}).sort((e,t)=>{let n=featuredPriority(e.value)-featuredPriority(t.value);if(n!==0)return n;let r=(t.released??-1/0)-(e.released??-1/0);if(r!==0)return r;let i=e.label.localeCompare(t.label);return i===0?e.value.localeCompare(t.value):i});return t.length===0?FALLBACK_MODELS:t.map(({value:e,label:t,hint:n})=>({id:e,label:t,value:e,hint:n,featured:FEATURED_MODEL_IDS.includes(e)||void 0}))}async function buildModelOptions(e,t){try{return modelOptionsFromCatalog(await e(t))}catch{return t?.throwIfAborted(),FALLBACK_MODELS}}function selectModel(t){let r=t.deps??{fetchModels:fetchGatewayCatalog};return{id:`select-model`,async gather({signal:i}){let a=t.presetModel;if(a!==void 0&&a.length>0)return a;let o=await buildModelOptions(r.fetchModels,i),s=t.defaultModel!==void 0&&o.some(e=>e.value===t.defaultModel)?t.defaultModel:o.some(e=>e.value===DEFAULT_AGENT_MODEL_ID)?DEFAULT_AGENT_MODEL_ID:o[0]?.value;return t.asker.ask(select({key:`model`,message:`Which model should your agent use?`,options:o,recommended:s,required:!0,search:!0,placeholder:`type to search`}))},async perform({input:e}){return e},apply(e,t){return{...e,modelId:t}}}}export{fetchGatewayCatalog,modelOptionsFromCatalog,parseGatewayCatalog,selectModel};
+import{select}from"../ask.js";import{z}from"#compiled/zod/index.js";import{DEFAULT_AGENT_MODEL_ID}from"#shared/default-agent-model.js";import{AI_GATEWAY_MODELS_URL,vercelGatewayFetch}from"#internal/gateway.js";const gatewayCatalogModelSchema=z.object({id:z.string(),name:z.string(),type:z.string(),owned_by:z.string(),released:z.number().finite().optional().catch(void 0),tags:z.array(z.string()).optional().catch(void 0),pricing:z.object({service_tiers:z.record(z.string(),z.unknown()).optional().catch(void 0)}).optional().catch(void 0)}),gatewayCatalogSchema=z.object({data:z.array(z.unknown())}).transform(({data:e})=>e.flatMap(e=>{let t=gatewayCatalogModelSchema.safeParse(e);return t.success?[t.data]:[]}));function modelOption(e,t,n,r=!0){return{id:e,label:t,value:e,hint:n,featured:r||void 0}}const FEATURED_MODEL_IDS=[DEFAULT_AGENT_MODEL_ID,`anthropic/claude-opus-4.8`,`openai/gpt-5.5`],FALLBACK_MODELS=[modelOption(DEFAULT_AGENT_MODEL_ID,`GPT-5.6 Luna Fast`,`OpenAI`),modelOption(`anthropic/claude-opus-4.8`,`Claude Opus 4.8`,`Anthropic`),modelOption(`openai/gpt-5.5`,`GPT-5.5`,`OpenAI`),modelOption(`google/gemini-3.5`,`Gemini 3.5`,`Google`,!1)],PROVIDER_BRANDS={openai:`OpenAI`,zai:`Z.AI`,xai:`xAI`,deepseek:`DeepSeek`,moonshotai:`Moonshot AI`};function providerLabel(e){return e.length===0?``:PROVIDER_BRANDS[e]??e.charAt(0).toUpperCase()+e.slice(1)}async function fetchGatewayCatalog(e){let t=new AbortController,n=setTimeout(()=>t.abort(),5e3);try{let n=await vercelGatewayFetch(AI_GATEWAY_MODELS_URL,{signal:e===void 0?t.signal:AbortSignal.any([e,t.signal])});if(!n.ok)throw Error(`AI Gateway model catalog request failed (${n.status}).`);return parseGatewayCatalog(await n.json())}finally{clearTimeout(n)}}function parseGatewayCatalog(e){let t=gatewayCatalogSchema.safeParse(e);if(!t.success)throw Error(`AI Gateway returned an invalid model catalog.`);return t.data}function featuredPriority(e){let t=FEATURED_MODEL_IDS.indexOf(e);return t===-1?FEATURED_MODEL_IDS.length:t}function modelOptionsFromCatalog(e){if(e===void 0)return FALLBACK_MODELS;let t=e.filter(e=>e.type===`language`&&(e.id===DEFAULT_AGENT_MODEL_ID||(e.tags??[]).includes(`web-search`))).map(e=>{let t=e.id.split(`/`)[0]??``;return{value:e.id,label:e.name,hint:providerLabel(t),provider:t,released:e.released}}).sort((e,t)=>{let n=featuredPriority(e.value)-featuredPriority(t.value);if(n!==0)return n;let r=(t.released??-1/0)-(e.released??-1/0);if(r!==0)return r;let i=e.label.localeCompare(t.label);return i===0?e.value.localeCompare(t.value):i});return t.length===0?FALLBACK_MODELS:t.map(({value:e,label:t,hint:n})=>({id:e,label:t,value:e,hint:n,featured:FEATURED_MODEL_IDS.includes(e)||void 0}))}async function buildModelOptions(e,t){try{return modelOptionsFromCatalog(await e(t))}catch{return t?.throwIfAborted(),FALLBACK_MODELS}}function selectModel(t){let r=t.deps??{fetchModels:fetchGatewayCatalog};return{id:`select-model`,async gather({signal:i}){let a=t.presetModel;if(a!==void 0&&a.length>0)return a;let o=await buildModelOptions(r.fetchModels,i),s=t.defaultModel!==void 0&&o.some(e=>e.value===t.defaultModel)?t.defaultModel:o.some(e=>e.value===DEFAULT_AGENT_MODEL_ID)?DEFAULT_AGENT_MODEL_ID:o[0]?.value;return t.asker.ask(select({key:`model`,message:`Which model should your agent use?`,options:o,recommended:s,required:!0,search:!0,placeholder:`type to search`}))},async perform({input:e}){return e},apply(e,t){return{...e,modelId:t}}}}export{fetchGatewayCatalog,modelOptionsFromCatalog,parseGatewayCatalog,selectModel};

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

@@ -1,4 +1,4 @@
-import{pinnedNodeEngineMajor}from"../../node-engine.js";import{parseChatGptModelSelection}from"../../../shared/chatgpt-model.js";import{SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS}from"../update/module-files.js";import{pathExists,writeTextFile}from"../files.js";import{blockingCreateInPlaceEntries}from"../create-in-place.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{mkdir,readdir,stat}from"node:fs/promises";import{basename,join,resolve}from"node:path";const CURRENT_DIRECTORY_PROJECT_NAME=`.`,DEFAULT_AI_PACKAGE_VERSION=`^7.0.58`,DEFAULT_CONNECT_PACKAGE_VERSION=`1.0.0`,DEFAULT_ZOD_PACKAGE_VERSION=`4.4.3`,DEFAULT_EVE_PACKAGE_CONTRACT={version:`0.47.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,t){return{"agent/agent.ts":renderAgentTemplate(e,t),"agent/channels/eve.ts":WEB_APP_TEMPLATE_FILES[`agent/channels/eve.ts`],"agent/instructions.md":AGENT_INSTRUCTIONS_TEMPLATE}}function renderAgentTemplate(e,n){let r=parseChatGptModelSelection(e);return r===void 0?BASE_AGENT_TEMPLATE.replaceAll(`__EVE_INIT_MODEL__`,e).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n)):`import { defineAgent } from "eve";\nimport { chatgpt } from "eve/models/openai";\n\nexport default defineAgent({\n  model: chatgpt(${JSON.stringify(r)}),\n${reasoningTemplateLine(n)}});\n`}function reasoningTemplateLine(e){return e===void 0||e===`provider-default`?``:`  reasoning: "${e}",\n`}function renderTemplate(e,n){return e===BASE_AGENT_TEMPLATE&&parseChatGptModelSelection(n.model)!==void 0?renderAgentTemplate(n.model,n.reasoning):e.replaceAll(`__EVE_INIT_APP_NAME__`,n.appName).replaceAll(`__EVE_INIT_MODEL__`,n.model).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n.reasoning)).replaceAll(`__EVE_INIT_BYOK_PROVIDER__`,modelProviderSlug(n.model)).replaceAll(`__EVE_INIT_BYOK_ENV_VAR__`,byokProviderEnvVar(n.model)).replaceAll(`__EVE_INIT_PACKAGE_VERSION__`,formatEveDependencySpecifier(n.eveVersion)).replaceAll(`__EVE_INIT_AI_SDK_VERSION__`,n.aiPackageVersion).replaceAll(`__EVE_INIT_CONNECT_VERSION__`,n.connectPackageVersion).replaceAll(`__EVE_INIT_ZOD_VERSION__`,n.zodPackageVersion).replaceAll(`__EVE_INIT_TYPESCRIPT_VERSION__`,n.typescriptPackageVersion).replaceAll(`__EVE_INIT_TYPES_NODE_VERSION__`,n.nodeTypesVersion).replaceAll(`__EVE_INIT_NODE_ENGINE__`,n.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{parseChatGptModelSelection}from"../../../shared/chatgpt-model.js";import{SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS}from"../update/module-files.js";import{pathExists,writeTextFile}from"../files.js";import{blockingCreateInPlaceEntries}from"../create-in-place.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{mkdir,readdir,stat}from"node:fs/promises";import{basename,join,resolve}from"node:path";const CURRENT_DIRECTORY_PROJECT_NAME=`.`,DEFAULT_AI_PACKAGE_VERSION=`^7.0.58`,DEFAULT_CONNECT_PACKAGE_VERSION=`1.0.0`,DEFAULT_ZOD_PACKAGE_VERSION=`4.4.3`,DEFAULT_EVE_PACKAGE_CONTRACT={version:`0.47.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,t){return{"agent/agent.ts":renderAgentTemplate(e,t),"agent/channels/eve.ts":WEB_APP_TEMPLATE_FILES[`agent/channels/eve.ts`],"agent/instructions.md":AGENT_INSTRUCTIONS_TEMPLATE}}function renderAgentTemplate(e,n){let r=parseChatGptModelSelection(e);return r===void 0?BASE_AGENT_TEMPLATE.replaceAll(`__EVE_INIT_MODEL__`,e).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n)):`import { defineAgent } from "eve";\nimport { chatgpt } from "eve/models/openai";\n\nexport default defineAgent({\n  model: chatgpt(${JSON.stringify(r)}),\n${reasoningTemplateLine(n)}});\n`}function reasoningTemplateLine(e){return e===void 0||e===`provider-default`?``:`  reasoning: "${e}",\n`}function renderTemplate(e,n){return e===BASE_AGENT_TEMPLATE&&parseChatGptModelSelection(n.model)!==void 0?renderAgentTemplate(n.model,n.reasoning):e.replaceAll(`__EVE_INIT_APP_NAME__`,n.appName).replaceAll(`__EVE_INIT_MODEL__`,n.model).replaceAll(`__EVE_INIT_REASONING__`,reasoningTemplateLine(n.reasoning)).replaceAll(`__EVE_INIT_BYOK_PROVIDER__`,modelProviderSlug(n.model)).replaceAll(`__EVE_INIT_BYOK_ENV_VAR__`,byokProviderEnvVar(n.model)).replaceAll(`__EVE_INIT_PACKAGE_VERSION__`,formatEveDependencySpecifier(n.eveVersion)).replaceAll(`__EVE_INIT_AI_SDK_VERSION__`,n.aiPackageVersion).replaceAll(`__EVE_INIT_CONNECT_VERSION__`,n.connectPackageVersion).replaceAll(`__EVE_INIT_ZOD_VERSION__`,n.zodPackageVersion).replaceAll(`__EVE_INIT_TYPESCRIPT_VERSION__`,n.typescriptPackageVersion).replaceAll(`__EVE_INIT_TYPES_NODE_VERSION__`,n.nodeTypesVersion).replaceAll(`__EVE_INIT_NODE_ENGINE__`,n.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/shared/default-agent-model.d.ts

@@ -2,4 +2,4 @@
  * Model used when an agent does not declare one, baked in by `eve init`, and
  * pre-selected in the setup model picker.
  */
-export declare const DEFAULT_AGENT_MODEL_ID = "zai/glm-5.2";
+export declare const DEFAULT_AGENT_MODEL_ID = "openai/gpt-5.6-luna-fast";

package/dist/src/shared/default-agent-model.js

@@ -1 +1 @@
-const DEFAULT_AGENT_MODEL_ID=`zai/glm-5.2`;export{DEFAULT_AGENT_MODEL_ID};
+const DEFAULT_AGENT_MODEL_ID=`openai/gpt-5.6-luna-fast`;export{DEFAULT_AGENT_MODEL_ID};

package/docs/agent-config.md

@@ -21,9 +21,7 @@ For a static AI Gateway model ID, you can make the same source change from the
 project root with `eve set --model anthropic/claude-opus-4.8` or from the local
 dev TUI with `/model anthropic/claude-opus-4.8`.
 
-The root `agent.ts` can be omitted when no runtime config is needed. eve then selects its default `agent.ts` source at the same slot, configured with `zai/glm-5.2`; authoring the file replaces that source. GLM 5.2 does not support image input; choose a
-vision-capable model or [route image inputs to Gemini
-Flash](./guides/dynamic-capabilities#route-image-inputs-to-a-vision-model).
+The root `agent.ts` can be omitted when no runtime config is needed. eve then selects its default `agent.ts` source at the same slot, configured with `openai/gpt-5.6-luna-fast`; authoring the file replaces that source.
 When `agent.ts` is present, `model` is required.
 
 A config that selects a static Gateway model is compile-only. A config that contains a dynamic model or a direct-provider `LanguageModel` remains a runtime entry because eve must resolve that authored value while the agent runs. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).

package/docs/concepts/state.md

@@ -72,15 +72,17 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
 `defineState` holds conversation-scoped working memory that lives and dies with
 the session, including counters, the current plan, and what the user has told
 you this conversation. It is the agent's short-term memory, persisted durably
-for the life of the session. For context that must outlive a session, connect a
-first-class [memory provider](../memory) to your own application store. Use a
-general [connection](../connections) instead when the data should be queried
-only through explicit model tool calls rather than recalled automatically.
+for the life of the session. For context that must outlive a session, configure
+a first-class [memory provider](../memory). Use the built-in file provider, a
+third-party provider, or a custom provider for application-specific storage and
+retrieval. Use a general [connection](../connections) instead when the data
+should be queried only through explicit model tool calls rather than recalled
+automatically.
 
 ## What to read next
 
 - Read state inside dynamic resolvers → [Dynamic capabilities](../guides/dynamic-capabilities)
 - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
 - The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
-- Tenant-scoped long-term memory in your own store → [Multi-tenant memory](../patterns/multi-tenant-memory)
+- Tenant-scoped long-term memory with any provider → [Multi-tenant memory](../patterns/multi-tenant-memory)
 - First-class recall, capture, and provider tools → [Memory](../memory)

package/docs/memory.md

@@ -1,24 +1,47 @@
 ---
 title: "Memory"
-description: "Recall and capture scoped, cross-session context with built-in or custom eve memory providers."
+description: "Connect scoped, cross-session context to built-in, third-party, or custom memory providers."
 ---
 
-Memory connects an agent to application-owned storage that can outlive one
-session. A provider recalls relevant context before a turn, can capture the
-settled conversation afterward, and can expose tools that operate on the same
-locked scope.
+Memory is a provider-backed capability for context that outlives one session.
+Each memory slot binds a provider to an eve-managed scope and visibility
+policy. The provider decides how to retrieve relevant context, whether to
+capture conversation history, and which model-facing operations to offer.
 
-eve owns the lifecycle and model-facing history. A provider owns storage,
-retrieval, retention, and deletion. Use the built-in bounded file provider for
-model-maintained facts, or implement a provider for application-specific
-retrieval and capture.
+Breaking down the boundary between eve and the provider:
+
+| eve owns                                                         | The provider owns                                       |
+| ---------------------------------------------------------------- | ------------------------------------------------------- |
+| Path-derived slots and qualified provider-tool names             | Storage and indexing                                    |
+| Namespace and trusted scope resolution                           | Retrieval, ranking, and formatting                      |
+| Lifecycle timing, recalled-message attribution, and supersession | Capture and extraction                                  |
+| Recall visibility in model context                               | Retention, deletion, and model-facing memory operations |
+
+This lets a bounded text file, a hosted semantic-memory service, or an
+application-specific store participate in the same agent lifecycle without
+sharing a storage model.
+
+## Choose a provider
+
+Every memory slot needs a provider. Choose one based on how the agent should
+recall and maintain memory:
+
+| Provider        | Status         | Use it for                                                                |
+| --------------- | -------------- | ------------------------------------------------------------------------- |
+| `fileMemory()`  | Built into eve | A bounded, model-maintained list of durable facts and preferences         |
+| Supermemory     | Coming soon    | The first third-party implementation of the eve provider contract         |
+| Custom provider | Supported      | Application-specific retrieval, capture, retention, or model-facing tools |
+
+Supermemory is building the first third-party provider for eve. It is not
+available yet; until it is released, use `fileMemory()` or implement the
+provider contract described below.
 
 ## Use file memory
 
-`fileMemory()` keeps one indexed document for each resolved scope and gives the
-model `save_memory` and `remove_memory` tools. It recalls the document before
-each turn and after compaction, but does not automatically extract facts from
-the conversation.
+`fileMemory()` keeps one indexed document for each resolved scope. The document
+lives in the selected backend, not in the agent's sandbox filesystem. The
+provider recalls it before each turn and after compaction, and gives the model
+`save_memory` and `remove_memory` tools.
 
 ```ts title="agent/memory/profile.ts"
 import { defineMemory } from "eve/memory";
@@ -32,18 +55,20 @@ export default defineMemory({
 });
 ```
 
-The `profile` slot exposes `profile__save_memory` and
-`profile__remove_memory`. Saved entries are normalized, assigned permanent
-numeric indexes, and recalled as one stable keyed message. Removing an entry
-replaces the previous recalled document at the next boundary, including when
-the final entry is removed, so stale content does not remain in model context.
+The filename creates the `profile` slot, so the provider tools are exposed as
+`profile__save_memory` and `profile__remove_memory`. The slot description is
+prepended to both tool descriptions to tell the model what belongs in this
+slot.
+
+File memory does not automatically extract facts from a conversation. The
+model decides when to call its save and remove tools. Entries receive permanent
+numeric indexes, and the provider recalls the document as one stable keyed
+message so updated or empty documents replace stale context.
 
 The provider rejects rather than truncates or evicts data. `maxCharacters`
 defaults to 4,000 characters and caps the exact recalled message, including
-its heading, removal guidance, indexes, separators, and saved text.
-`save_memory` rejects an entry when the resulting message would exceed that
-limit. Each normalized entry can contain up to 2,048 UTF-8 bytes, and the
-stored document can contain up to 65,536 bytes:
+its heading and removal guidance. Each normalized entry can contain up to
+2,048 UTF-8 bytes, and the stored document can contain up to 65,536 bytes:
 
 ```ts
 provider: fileMemory({ maxCharacters: 8_000 });
@@ -71,102 +96,68 @@ provider: fileMemory({ backend: inMemory() });
 ```
 
 `inMemory()` loses its contents when its backend instance or process is
-replaced. For another durable store, implement `MemoryDocumentBackend` from
-`eve/memory/file`. Its `write()` method conditionally replaces the complete
+replaced. For another durable document store, implement `MemoryDocumentBackend`
+from `eve/memory/file`. Its `write()` method conditionally replaces the complete
 document and must throw `MemoryDocumentConflictError` when `expectedVersion`
-is stale. Use `vercelBlob()` from `eve/memory/file/vercel` when you want to
-configure Vercel Blob credentials or an object prefix explicitly.
+is stale. Use `vercelBlob()` from `eve/memory/file/vercel` to configure Vercel
+Blob credentials or an object prefix explicitly.
+
+A file backend changes where `fileMemory()` stores its document. It does not
+change file memory's recall behavior or tools. Implement a memory provider
+instead when you need semantic retrieval, automatic capture, or different
+model-facing operations.
 
 ## Add a memory slot
 
 Create `agent/memory.ts` for one slot named `memory`, or use
-`agent/memory/<slot>.ts` for named slots. These forms are mutually exclusive.
-
-```ts title="agent/memory/profile.ts"
-import { defineMemory, type MemoryOperationContext } from "eve/memory";
-import { byPrincipal } from "eve/memory/scope";
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-import { profileStore } from "../lib/profile-store";
-
-async function recallProfile(ctx: MemoryOperationContext) {
-  const profile = await profileStore.get(ctx.memory.scope.key);
-  if (profile === null) return null;
-
-  return {
-    messages: [{ id: "profile", content: JSON.stringify(profile) }],
-  };
-}
-
-export default defineMemory({
-  description: "Manage durable facts and preferences for the current caller.",
-  scope: byPrincipal,
-  provider: {
-    recall: {
-      "turn.started": recallProfile,
-      "compaction.completed": recallProfile,
-    },
-
-    capture: {
-      async "turn.completed"(ctx) {
-        await profileStore.observe(ctx.memory.scope.key, ctx.messages, {
-          operationId: ctx.operationId,
-        });
-      },
-    },
-
-    async tools(ctx) {
-      return {
-        save: defineTool({
-          description: "Save one durable profile fact.",
-          inputSchema: z.object({ key: z.string(), value: z.string() }),
-          async execute(input) {
-            await profileStore.put(ctx.memory.scope.key, input);
-            return { saved: true };
-          },
-        }),
-      };
-    },
-  },
-});
+`agent/memory/<slot>.ts` for multiple named slots. The flat file and directory
+forms are mutually exclusive:
+
+```text
+agent/
+  memory/
+    profile.ts
+    workspace.ts
 ```
 
-The filename is the slot name. The provider tool above is exposed as
-`profile__save`; the slot description is prepended to the tool description.
-Provider tools are ordinary `defineTool()` values, so schemas, approvals, and
-`toModelOutput` work normally. Their callbacks remain replayable after a
-process restart or deployment.
-
-Use `defineMemoryProvider()` when several slots share one provider or when you
-want its contract checked separately:
+Each slot independently binds a provider, description, scope, namespace, and
+visibility policy. The same provider can back several slots without merging
+their recalled context or tools. The default namespace includes the slot name,
+so `profile` and `workspace` remain separate even if both resolve the same
+scope.
 
-```ts
-import { defineMemoryProvider, type MemoryOperationContext } from "eve/memory";
+For example, `profile.ts` can use `fileMemory()` with `byPrincipal`, while
+`workspace.ts` uses another `fileMemory()` instance with a trusted workspace
+scope:
 
-async function recall(ctx: MemoryOperationContext) {
-  return await recallFromStore(ctx.memory.scope.key, ctx.messages);
-}
+```ts title="agent/memory/workspace.ts"
+import { defineMemory } from "eve/memory";
+import { fileMemory } from "eve/memory/file";
 
-export const provider = defineMemoryProvider({
-  recall: {
-    "turn.started": recall,
-    "compaction.completed": recall,
+export default defineMemory({
+  description: "Remember shared conventions for the authenticated workspace.",
+  provider: fileMemory(),
+  scope(ctx) {
+    const workspaceId = ctx.session.auth.current?.attributes.workspaceId;
+    return typeof workspaceId === "string" ? workspaceId : null;
   },
 });
 ```
 
 ## Choose a scope
 
-`scope` decides who or what shares memory. Set it to a string or `null`, or use
-a resolver that returns a string, a tuple of strings, or `null`. Resolve tenant
-and caller identity from trusted authentication or channel metadata, never from
-model input:
+`scope` decides who or what shares a slot's memory. Set it to a string or
+`null`, or use a resolver that returns a string, a tuple of strings, or `null`.
+Resolve tenant and caller identity from trusted authentication or channel
+metadata, never from model input:
 
 ```ts title="agent/memory/account.ts"
 import { defineMemory } from "eve/memory";
+import { fileMemory } from "eve/memory/file";
 
 export default defineMemory({
-  scope: (ctx) => {
+  provider: fileMemory(),
+  scope(ctx) {
     const caller = ctx.session.auth.current;
     const tenantId = caller?.attributes.tenantId;
 
@@ -176,7 +167,6 @@ export default defineMemory({
 
     return [tenantId, caller.principalId];
   },
-  provider,
 });
 ```
 
@@ -188,37 +178,66 @@ that returned `null`, without logging the resolved value.
 `byPrincipal` uses `auth.current`. It disables memory for anonymous and runtime
 principals and returns the shared `local-dev` scope during local development.
 Use a custom resolver when the boundary also needs a tenant, channel, or
-conversation identifier.
+conversation identifier. See [Multi-tenant memory](./patterns/multi-tenant-memory)
+for a complete scoped setup.
 
-eve validates the namespace and scope, then gives the provider:
+eve validates and locks the namespace and scope before calling the provider.
+Every provider operation receives:
 
 - `memory.scope.key`: a versioned, opaque digest for storage lookup;
 - `memory.scope.namespace`: the resolved namespace;
 - `memory.scope.value`: the resolved string or tuple;
 - `memory.slot`: the path-derived slot name.
 
-Use `memory.scope.key` as the provider partition key. It preserves tuple
-boundaries and does not persist raw scope components in eve's durable
-attribution.
+Providers must use `memory.scope.key` as the partition key for every read and
+write. The key preserves tuple boundaries and keeps raw scope components out of
+eve's durable attribution.
+
+## Choose visibility
+
+`visibility` controls which previously recalled records eve includes in model
+context after a slot's scope changes. It does not change the scope passed to
+the provider.
+
+| Value               | Behavior after a scope change                                      |
+| ------------------- | ------------------------------------------------------------------ |
+| `"scope"` (default) | Hide recalled records from the slot's earlier scope                |
+| `"session"`         | Keep earlier recalled records visible within the current namespace |
+
+Use `"session"` only when every scope that can appear in the session belongs
+to one trusted audience:
+
+```ts
+export default defineMemory({
+  provider: fileMemory(),
+  scope: byPrincipal,
+  visibility: "session",
+});
+```
+
+Namespace remains an isolation boundary in both modes. Applications that need
+hard isolation between participants must use separate sessions; visibility
+cannot undo information already included in an assistant response.
 
 ## Choose a namespace
 
 The namespace separates an application's memory domains before scope is
-applied. Omit `namespace` for `defaultNamespace`, which includes the graph
+applied. Omit `namespace` to use `defaultNamespace`, which includes the graph
 node and slot plus a deployment-aware identity:
 
-- production and other Vercel environments use the project and environment;
-- Preview also uses the branch or deployment identity;
-- local development uses a digest of the application root, never the raw path.
+- Production and other Vercel environments use the project and environment.
+- Preview also uses the branch or deployment identity.
+- Local development uses a digest of the application root, never the raw path.
 
-Redeployments keep the same production namespace. Preview branches do not
-share memory accidentally. Set a string or resolver for an explicit domain:
+Redeployments keep the same production namespace, while unrelated Preview
+branches do not share memory accidentally. Set a string or resolver when you
+need an explicit application domain:
 
 ```ts
 export default defineMemory({
   namespace: "acme-support-v1",
+  provider: fileMemory(),
   scope: byPrincipal,
-  provider,
 });
 ```
 
@@ -226,13 +245,84 @@ A custom namespace is complete; eve adds no hidden suffix. Returning `null`
 disables the slot. Scope resolves first, so a disabled scope never invokes the
 namespace resolver.
 
+## Build a custom provider
+
+Build a provider when the available providers do not match your storage or
+retrieval model. Most application authors do not need this layer: a provider
+package should expose a `MemoryProvider` or a configured provider factory that
+you pass to `defineMemory()`.
+
+A provider can implement three surfaces:
+
+| Surface   | Responsibility                                                           |
+| --------- | ------------------------------------------------------------------------ |
+| `recall`  | Return relevant messages at turn start and, optionally, after compaction |
+| `capture` | Observe settled history after a turn or before compaction                |
+| `tools`   | Return model-facing operations bound to the same locked scope            |
+
+Each helper
+deliberately throws until you connect it to a database or memory-service SDK:
+
+```ts title="agent/lib/semantic-memory-provider.ts"
+import {
+  defineMemoryProvider,
+  type MemoryOperationContext,
+  type MemoryRecallResult,
+  type MemoryToolsContext,
+  type MemoryToolSet,
+} from "eve/memory";
+
+async function recallFromYourService(_ctx: MemoryOperationContext): Promise<MemoryRecallResult> {
+  throw new Error("Replace with retrieval from your memory service.");
+}
+
+async function captureWithYourService(_ctx: MemoryOperationContext): Promise<void> {
+  throw new Error("Replace with capture into your memory service.");
+}
+
+async function createToolsForYourService(_ctx: MemoryToolsContext): Promise<MemoryToolSet | null> {
+  throw new Error("Replace with tools backed by your memory service.");
+}
+
+export const semanticMemoryProvider = defineMemoryProvider({
+  recall: {
+    "turn.started": recallFromYourService,
+    "compaction.completed": recallFromYourService,
+  },
+  capture: {
+    "turn.completed": captureWithYourService,
+    "compaction.requested": captureWithYourService,
+  },
+  tools: createToolsForYourService,
+});
+```
+
+Omit any optional handler that the provider does not need. For example,
+`fileMemory()` implements recall and tools but no automatic capture. After
+replacing the stubs, bind the provider to a slot like any other provider:
+
+```ts title="agent/memory/profile.ts"
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { semanticMemoryProvider } from "../lib/semantic-memory-provider";
+
+export default defineMemory({
+  provider: semanticMemoryProvider,
+  scope: byPrincipal,
+});
+```
+
+Provider tools are ordinary `defineTool()` values, so schemas, approvals, and
+`toModelOutput` work normally. eve qualifies each returned key with the slot
+name and keeps its callback replayable after a process restart or deployment.
+
 ## Recall behavior
 
-Register recall handlers under their lifecycle keys. `"turn.started"` is
-required and runs before the model. `"compaction.completed"` is optional and
-runs after a compaction checkpoint. A recall handler returns `{ messages }`,
-`null`, or `undefined`. Each recalled item becomes an untrusted user-role
-message; provider content is never promoted to system instructions.
+`recall["turn.started"]` is required and runs before the model.
+`recall["compaction.completed"]` is optional and runs after a compaction
+checkpoint. A recall handler returns `{ messages }`, `null`, or `undefined`.
+Each recalled item becomes an untrusted user-role message; provider content is
+never promoted to system instructions.
 
 ```ts
 return {
@@ -250,13 +340,8 @@ identical. Omitting an earlier item from a later result does not delete it.
 
 All active slots lock their scopes before any recall runs. They see the same
 pre-recall history, and eve commits their validated results atomically. Each
-call receives a stable `operationId`; use it as an idempotency key for writes
-performed by capture handlers.
-
-The default `visibility: "scope"` hides a slot's prior recalled records when
-its scope changes. Set `visibility: "session"` only when those records are
-safe to retain for the rest of the session across scope changes. Namespace
-and slot boundaries still apply.
+call receives a stable `operationId`; providers can use it as an idempotency
+key for writes performed by capture handlers.
 
 ## Lifecycle and compaction
 
@@ -293,7 +378,7 @@ provider's external store. A later turn can recall that data again.
 - A completed-turn capture failure is diagnosed after the response and does
   not rewrite the completed turn.
 
-Keep provider operations idempotent, enforce backend size and retention
+Provider operations should be idempotent, enforce their own size and retention
 policies, and treat recalled content as user-controlled data.
 
 ## Limits and overrides
@@ -311,8 +396,8 @@ with the consuming agent or subagent.
 
 ## What to read next
 
-- [Multi-tenant memory](./patterns/multi-tenant-memory): define a tenant and
-  caller scope for an application store.
+- [Multi-tenant memory](./patterns/multi-tenant-memory): isolate any provider by
+  authenticated tenant and caller.
 - [State](./concepts/state): keep durable working data inside one session.
 - [Default harness](./concepts/default-harness): understand compaction and
   context controls.