eve 0.5.4 → 0.6.0-beta.3

package/dist/src/public/instrumentation/index.d.ts

@@ -0,0 +1,144 @@
+import type { ExactDefinition } from "#public/definitions/exact.js";
+/**
+ * Instrumentation authoring helpers for `agent/instrumentation.ts`.
+ */
+import type { ModelMessage, SystemModelMessage } from "ai";
+import type { SessionAuthContext, SessionParent } from "#channel/types.js";
+import type { InstrumentationChannel } from "#public/channels/index.js";
+import type { JsonObject } from "#shared/json.js";
+export { isChannel, type ChannelMetadataMap, type ChannelReferenceMap, type InstrumentationChannel, type InstrumentationChannelForChannel, type InstrumentationChannelForKind, type InstrumentationChannelKind, type InstrumentationChannelMetadata, } from "#public/channels/index.js";
+/**
+ * Context passed to the {@link InstrumentationDefinition.setup} callback.
+ */
+export interface InstrumentationSetupContext {
+    /**
+     * The agent name declared by `defineAgent`. Use as the `serviceName` for
+     * `registerOTel` instead of a hard-coded string.
+     */
+    readonly agentName: string;
+}
+/**
+ * User-authored runtime context values attached to AI SDK telemetry spans.
+ *
+ * Keys beginning with `eve.` are reserved for framework-owned context
+ * and are ignored when returned from authored instrumentation.
+ */
+export type InstrumentationRuntimeContext = JsonObject;
+/**
+ * Session lineage and auth snapshot exposed to instrumentation callbacks.
+ *
+ * `auth.current` is the caller principal for this turn (null when the
+ * request carried no credentials). `auth.initiator` is the principal that
+ * started the root session, falling back to `auth.current` for root
+ * sessions. `parent` is present only for delegated subagent sessions.
+ */
+export interface InstrumentationSession {
+    readonly auth: {
+        readonly current: SessionAuthContext | null;
+        readonly initiator: SessionAuthContext | null;
+    };
+    readonly id: string;
+    readonly parent?: SessionParent;
+}
+/**
+ * Identifies the turn in progress when an instrumentation event fires.
+ * `id` is the turn identifier; `sequence` is its zero-based position
+ * within the session.
+ */
+export interface InstrumentationTurn {
+    readonly id: string;
+    readonly sequence: number;
+}
+/**
+ * The step (model-call attempt) in progress for an instrumentation event.
+ * `index` is the zero-based step index within the current turn.
+ */
+export interface InstrumentationStep {
+    readonly index: number;
+}
+/**
+ * Final model input assembled for one model-call attempt, snapshotted for
+ * instrumentation. `instructions` is the resolved system prompt (a single
+ * string, an array of system messages, or undefined when there is none).
+ * `messages` is the non-system conversation passed to the model.
+ */
+export interface InstrumentationModelInput {
+    readonly instructions: string | readonly SystemModelMessage[] | undefined;
+    readonly messages: readonly ModelMessage[];
+}
+/**
+ * Input passed to `events["step.started"]`. Eve runs the callback after
+ * building the final model input for this attempt and before constructing
+ * the AI SDK model call.
+ */
+export interface InstrumentationStepStartedEventInput {
+    readonly channel: InstrumentationChannel;
+    readonly modelInput: InstrumentationModelInput;
+    readonly session: InstrumentationSession;
+    readonly step: InstrumentationStep;
+    readonly turn: InstrumentationTurn;
+}
+/**
+ * Result of a `step.started` callback. Eve merges `runtimeContext` into the
+ * AI SDK telemetry span; child spans inherit the values. Keys beginning with
+ * `eve.` and non-JSON-serializable values are dropped. Return `undefined` to
+ * contribute no context.
+ */
+export interface InstrumentationStepStartedEventResult {
+    /**
+     * Additional runtime context merged into AI SDK telemetry spans.
+     */
+    readonly runtimeContext: InstrumentationRuntimeContext;
+}
+/**
+ * Event hooks accepted by {@link defineInstrumentation}.
+ */
+export interface InstrumentationEvents {
+    /**
+     * Resolve per-attempt runtime context before the model call. The AI SDK
+     * child spans inherit the returned values.
+     */
+    readonly "step.started"?: (input: InstrumentationStepStartedEventInput) => InstrumentationStepStartedEventResult | undefined;
+}
+/**
+ * Authored instrumentation settings accepted by `defineInstrumentation`.
+ *
+ * The presence of a `defineInstrumentation` export implicitly enables
+ * telemetry. There is no separate `isEnabled` toggle.
+ */
+export interface InstrumentationDefinition {
+    /**
+     * Override the function identifier attached to telemetry spans
+     * (`ai.telemetry.functionId`). Defaults to the agent name; omitted when
+     * neither is set.
+     */
+    readonly functionId?: string;
+    /**
+     * Instrumentation event hooks.
+     */
+    readonly events?: InstrumentationEvents;
+    /**
+     * Whether to record full model inputs in telemetry spans. Defaults to
+     * `true` when `instrumentation.ts` is present. Set `false` for sensitive
+     * inputs or to reduce span payload size.
+     */
+    readonly recordInputs?: boolean;
+    /**
+     * Whether to record full model outputs in telemetry spans. Defaults to
+     * `true` when `instrumentation.ts` is present.
+     */
+    readonly recordOutputs?: boolean;
+    /**
+     * Setup callback invoked at server startup with the resolved agent name.
+     * Use it to call `registerOTel` or other OTel provider setup;
+     * `context.agentName` comes from `defineAgent`.
+     */
+    readonly setup?: (context: InstrumentationSetupContext) => void;
+}
+/**
+ * Export the result as the default export of `agent/instrumentation.ts`. Eve
+ * reads these settings at server startup and applies them to every AI SDK
+ * model call. The `setup` callback runs later with the resolved agent name,
+ * not during `defineInstrumentation` itself.
+ */
+export declare function defineInstrumentation<T extends InstrumentationDefinition>(definition: ExactDefinition<T, InstrumentationDefinition>): T;

package/dist/src/public/instrumentation/index.js

@@ -0,0 +1 @@
+import{isChannel}from"#public/channels/index.js";function defineInstrumentation(e){return e}export{defineInstrumentation,isChannel};

package/dist/src/public/next/index.d.ts

@@ -0,0 +1,86 @@
+import type { NextConfig } from "next";
+/**
+ * Default private route namespace for hosting Eve as a separate experimental
+ * Vercel service behind the Next.js app. {@link WithEveOptions.servicePrefix}
+ * defaults to this value.
+ */
+export declare const EVE_NEXT_SERVICE_PREFIX = "/_eve_internal/eve";
+type ArrayElement<T> = T extends readonly (infer TElement)[] ? TElement : never;
+type NextRewrites = Awaited<ReturnType<NonNullable<NextConfig["rewrites"]>>>;
+/**
+ * Next.js rewrite rule that {@link withEve} emits.
+ */
+export type EveNextRewriteRule = ArrayElement<NextRewrites>;
+/**
+ * Resolved return type of a Next.js `rewrites` function: an array of rules, or
+ * the sectioned `{ beforeFiles, afterFiles, fallback }` object.
+ */
+export type EveNextRewrites = NextRewrites;
+/**
+ * Sectioned Next.js rewrite rules.
+ */
+export type EveNextRewriteSections = Extract<NextRewrites, {
+    readonly afterFiles?: EveNextRewriteRule[];
+    readonly beforeFiles?: EveNextRewriteRule[];
+    readonly fallback?: EveNextRewriteRule[];
+}>;
+/**
+ * Alias of Next.js's `NextConfig`, the config object form {@link withEve}
+ * accepts (the other being {@link EveNextConfigFunction}).
+ */
+export type EveNextConfig = NextConfig;
+/**
+ * Structural shape of a Next.js config function: receives the build `phase` and
+ * a `context` containing `defaultConfig`, and returns a config (or a promise of
+ * one). This is the form {@link withEve} returns.
+ */
+export type EveNextConfigFunction<TConfig extends EveNextConfig = EveNextConfig> = (phase: string, context: {
+    readonly defaultConfig: TConfig;
+}) => TConfig | Promise<TConfig>;
+/**
+ * Next.js config input that {@link withEve} accepts.
+ */
+export type EveNextConfigInput<TConfig extends EveNextConfig = EveNextConfig> = EveNextConfigFunction<TConfig> | TConfig;
+/**
+ * Options for {@link withEve}.
+ */
+export interface WithEveOptions {
+    /**
+     * Path to the Eve application root, relative to `process.cwd()` unless
+     * absolute. Defaults to the Next.js app root.
+     */
+    readonly eveRoot?: string;
+    /**
+     * Build command for the generated Eve Vercel service. Defaults to `eve build`.
+     * Use this when the Eve service needs project-specific prework before the
+     * framework build, without changing the Next.js service build command.
+     */
+    readonly eveBuildCommand?: string;
+    /**
+     * Set to `false` to skip creating or updating Vercel Build Output config.
+     * When unset, `withEve` ensures `.vercel/output/config.json` contains
+     * `experimentalServices` for the Next.js app and Eve app.
+     */
+    readonly configureVercelOutput?: boolean;
+    /**
+     * Private Vercel service prefix for the Eve deployment. Defaults to
+     * {@link EVE_NEXT_SERVICE_PREFIX} (`/_eve_internal/eve`). `withEve` normalizes
+     * the prefix (adds a leading slash, strips trailing slashes) and rejects a
+     * prefix that resolves to the root route. The prefix must match the Eve
+     * service's mount in Vercel Build Output config.
+     */
+    readonly servicePrefix?: string;
+}
+/**
+ * Wraps a Next.js config so same-origin Eve endpoints proxy to a separate Eve
+ * service.
+ *
+ * In development, starts `eve dev --no-repl --port 0` for the Eve app and
+ * rewrites Eve protocol endpoints to that local URL. In Vercel production,
+ * rewrites to the private Eve service prefix from `.vercel/output/config.json`.
+ * Outside Vercel production, serves an existing `.output/server/index.mjs` build
+ * on a stable local port when present; otherwise set `EVE_NEXT_PRODUCTION_ORIGIN`
+ * to the origin serving the Eve service namespace.
+ */
+export declare function withEve<TConfig extends EveNextConfig>(configOrFunction: EveNextConfigInput<TConfig>, options?: WithEveOptions): EveNextConfigFunction<TConfig>;
+export {};

package/dist/src/public/next/index.js

@@ -0,0 +1 @@
+import{resolveEveDestinationPrefix}from"./server.js";import{ensureEveVercelOutputConfig}from"./vercel-output-config.js";import{EVE_ROUTE_PREFIX}from"#protocol/routes.js";import{isAbsolute,resolve}from"node:path";const EVE_NEXT_SERVICE_PREFIX=`/_eve_internal/eve`,EVE_NEXT_PRODUCTION_PORT_ENV=`EVE_NEXT_PRODUCTION_PORT`,EVE_PROXY_REWRITE_SOURCES=[`${EVE_ROUTE_PREFIX}/:path+`];function resolveApplicationRoot(e){return e===void 0||e.length===0?process.cwd():isAbsolute(e)?e:resolve(process.cwd(),e)}function normalizeRoutePrefix(e){let t=(e.startsWith(`/`)?e:`/${e}`).replace(/\/+$/,``);if(t.length===0)throw Error(`Eve Next.js service prefix cannot resolve to the root route.`);return t}function joinRoutePrefix(e,t){return`${e.replace(/\/+$/,``)}/${t.replace(/^\/+/,``)}`}function normalizeOrigin(e){return new URL(e.trim()).origin}function readLocalProductionPort(){let e=process.env[EVE_NEXT_PRODUCTION_PORT_ENV];if(e===void 0||e.trim().length===0)return 4274;let t=Number.parseInt(e,10);if(String(t)!==e.trim()||t<1||t>65535)throw Error(`${EVE_NEXT_PRODUCTION_PORT_ENV} must be an integer between 1 and 65535.`);return t}function resolveProductionDestination(e){if(process.env.VERCEL)return{destinationPrefix:e};let t=process.env.EVE_NEXT_PRODUCTION_ORIGIN;if(t!==void 0&&t.trim().length>0)return{destinationPrefix:joinRoutePrefix(normalizeOrigin(t),e)};let n=`http://127.0.0.1:${String(readLocalProductionPort())}`;return{destinationPrefix:n,localServerOrigin:n}}function createEveRewriteRules(e){return EVE_PROXY_REWRITE_SOURCES.map(t=>({destination:joinRoutePrefix(e,t),source:t}))}async function resolveExistingRewrites(e){return await e?.()}function mergeRewriteRules(e,t){return e===void 0?{beforeFiles:t}:isRewriteSections(e)?{...e,beforeFiles:[...t,...e.beforeFiles??[]]}:{afterFiles:e,beforeFiles:t}}function isRewriteSections(e){return!Array.isArray(e)}async function resolveNextConfig(e,t,n){return typeof e==`function`?await e(t,n):e}function withEve(n,r={}){let i=process.cwd(),a=resolveApplicationRoot(r.eveRoot),o=normalizeRoutePrefix(r.servicePrefix??`/_eve_internal/eve`),s=r.configureVercelOutput!==!1;return async function(c,l){let u=await resolveNextConfig(n,c,l),d=u.rewrites,f=resolveProductionDestination((s?await ensureEveVercelOutputConfig({appRoot:a,eveBuildCommand:r.eveBuildCommand??`eve build`,nextRoot:i,servicePrefix:o}):{servicePrefix:o}).servicePrefix);return{...u,async rewrites(){let[t,n]=await Promise.all([resolveExistingRewrites(d),resolveEveDestinationPrefix({appRoot:a,phase:c,productionDestinationPrefix:f.destinationPrefix,productionServerOrigin:f.localServerOrigin})]);return mergeRewriteRules(t,createEveRewriteRules(n))}}}}export{EVE_NEXT_SERVICE_PREFIX,withEve};

package/dist/src/public/next/server.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveEveDestinationPrefix(input: {
+    readonly appRoot: string;
+    readonly phase: string;
+    readonly productionDestinationPrefix: string;
+    readonly productionServerOrigin?: string;
+}): Promise<string>;

package/dist/src/public/next/server.js

@@ -0,0 +1 @@
+import{EVE_ROUTE_PREFIX}from"#protocol/routes.js";import{join}from"node:path";import{mkdir,open,readFile,rm,stat,writeFile}from"node:fs/promises";import{spawn}from"node:child_process";import{existsSync}from"node:fs";import{resolvePackageRoot}from"#internal/application/package.js";const EVE_BASE_URL_ENV=`EVE_BASE_URL`,DEFAULT_SERVER_READY_TIMEOUT_MS=3e4,DEV_SERVER_REGISTRY_TIMEOUT_MS=3e4,SERVER_URL_CANDIDATE_PATTERN=/https?:\/\/[^\s"'<>]+/g,globalStateSymbol=Symbol.for(`eve.next.state`);function getGlobalState(){let e=globalThis;return e[globalStateSymbol]??={servers:new Map},e[globalStateSymbol]}function joinRoutePrefix(e,t){return`${e.replace(/\/+$/,``)}/${t.replace(/^\/+/,``)}`}function normalizeOrigin(e){return new URL(e).origin}function readEveBaseUrlEnvironment(){let e=process.env[EVE_BASE_URL_ENV];if(!(e===void 0||e.trim().length===0))return normalizeOrigin(e)}function isNodeErrorWithCode(e,t){return e instanceof Error&&`code`in e&&e.code===t}function delay(e){return new Promise(t=>setTimeout(t,e))}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function resolveEveCacheDirectory(e){return join(e,`.eve`)}function resolveEveDevServerRegistryPath(e){return join(resolveEveCacheDirectory(e),`next-dev-server.json`)}function resolveEveDevServerLockPath(e){return join(resolveEveCacheDirectory(e),`next-dev-server.lock`)}function normalizeDevServerRegistry(e){if(isRecord(e)&&!(typeof e.appRoot!=`string`||typeof e.origin!=`string`||typeof e.updatedAt!=`string`)&&!(e.pid!==null&&typeof e.pid!=`number`))try{return{appRoot:e.appRoot,origin:normalizeOrigin(e.origin),pid:e.pid,updatedAt:e.updatedAt}}catch{return}}async function isEveServerHealthy(t){let n=new AbortController,r=setTimeout(()=>{n.abort()},1e3);try{return(await fetch(joinRoutePrefix(t,`${EVE_ROUTE_PREFIX}/health`),{signal:n.signal})).ok}catch{return!1}finally{clearTimeout(r)}}async function readUsableEveDevServerRegistry(e){try{let t=normalizeDevServerRegistry(JSON.parse(await readFile(resolveEveDevServerRegistryPath(e),`utf8`)));return t===void 0||t.appRoot!==e||!await isEveServerHealthy(t.origin)?void 0:(process.env[EVE_BASE_URL_ENV]=t.origin,t.origin)}catch(e){if(isNodeErrorWithCode(e,`ENOENT`))return;throw e}}async function writeEveDevServerRegistry(e,t){await mkdir(resolveEveCacheDirectory(e),{recursive:!0}),await writeFile(resolveEveDevServerRegistryPath(e),`${JSON.stringify({appRoot:e,origin:t.origin,pid:t.process?.pid??null,updatedAt:new Date().toISOString()},null,2)}\n`)}async function removeStaleEveDevServerLock(e){try{let t=await stat(e);Date.now()-t.mtimeMs>3e4&&await rm(e,{force:!0})}catch(e){if(!isNodeErrorWithCode(e,`ENOENT`))throw e}}async function acquireEveDevServerLock(e){let t=resolveEveCacheDirectory(e),i=resolveEveDevServerLockPath(e),a=Date.now()+DEV_SERVER_REGISTRY_TIMEOUT_MS;for(await mkdir(t,{recursive:!0});;)try{let e=await open(i,`wx`);return await e.writeFile(`${String(process.pid)}\n`),await e.close(),async()=>{await rm(i,{force:!0})}}catch(t){if(!isNodeErrorWithCode(t,`EEXIST`))throw t;if(await readUsableEveDevServerRegistry(e)!==void 0)return async()=>{};if(await removeStaleEveDevServerLock(i),Date.now()>a)throw Error(`Timed out after ${DEV_SERVER_REGISTRY_TIMEOUT_MS}ms waiting for another Next.js process to start Eve.`);await delay(100)}}function createEveBinaryPath(){return join(resolvePackageRoot(),`bin`,`eve.js`)}function isLoopbackHostname(e){return e===`localhost`||e===`::1`||e===`[::1]`||/^127(?:\.\d{1,3}){3}$/.test(e)}function parseLocalServerOrigin(e){let t=URL.parse(e);if(!(t===null||t.protocol!==`http:`&&t.protocol!==`https:`||!isLoopbackHostname(t.hostname)||t.port.length===0))return t.origin}function findLocalServerOrigin(e){for(let t of e.matchAll(SERVER_URL_CANDIDATE_PATTERN)){let e=t[0],n=parseLocalServerOrigin(e);if(n!==void 0)return n}}function startServerProcess(e){return new Promise((t,n)=>{let r=spawn(e.command,e.args,{cwd:e.cwd,env:{...process.env,...e.env},stdio:[`ignore`,`pipe`,`pipe`]}),i=setTimeout(()=>{r.kill(),n(Error(`Timed out after ${e.timeoutMs??DEFAULT_SERVER_READY_TIMEOUT_MS}ms waiting for Eve to print its server URL.`))},e.timeoutMs??DEFAULT_SERVER_READY_TIMEOUT_MS),cleanup=()=>{clearTimeout(i),r.off(`error`,handleError),r.off(`exit`,handleEarlyExit)},handleError=e=>{cleanup(),n(e)},handleEarlyExit=(e,t)=>{cleanup(),n(Error(`Eve server process exited before printing its server URL (code ${String(e)}, signal ${String(t)}).`))},handleOutput=e=>{let n=findLocalServerOrigin(e.toString(`utf8`));n!==void 0&&(cleanup(),t({origin:n,process:r}))};r.once(`error`,handleError),r.once(`exit`,handleEarlyExit),r.stdout.on(`data`,e=>{process.stdout.write(e),handleOutput(e)}),r.stderr.on(`data`,e=>{process.stderr.write(e),handleOutput(e)})})}function installProcessShutdown(e){let t=e.process;if(t===void 0)return e;let close=()=>{t.killed||t.kill()};return process.once(`beforeExit`,close),process.once(`exit`,close),e}function startEveDevServer(e){return startServerProcess({args:[createEveBinaryPath(),`dev`,`--no-repl`,`--port`,`0`],command:process.execPath,cwd:e}).then(e=>(process.env[EVE_BASE_URL_ENV]=e.origin,installProcessShutdown(e)))}function startEveProductionServer(e){let n=new URL(e.origin),r=n.port,i=join(e.appRoot,`.output`,`server`,`index.mjs`);if(existsSync(i))return startServerProcess({args:[i],command:process.execPath,cwd:e.appRoot,env:{HOST:n.hostname,NITRO_HOST:n.hostname,NITRO_PORT:r,PORT:r}}).then(installProcessShutdown)}async function resolveSharedEveDevServer(e){let t=await readUsableEveDevServerRegistry(e);if(t!==void 0)return{origin:t};let n=await acquireEveDevServerLock(e);try{let t=await readUsableEveDevServerRegistry(e);if(t!==void 0)return{origin:t};let n=await startEveDevServer(e);return await writeEveDevServerRegistry(e,n),n}finally{await n()}}async function resolveEveDestinationPrefix(e){let t=getGlobalState();if(process.env.NODE_ENV===`production`){if(e.phase===`phase-production-build`)return e.productionDestinationPrefix;let n=`production:${e.appRoot}`,r=t.servers.get(n);return r===void 0&&(r=process.env.VERCEL||e.productionServerOrigin===void 0?void 0:startEveProductionServer({appRoot:e.appRoot,origin:e.productionServerOrigin}),r!==void 0&&(r=r.catch(e=>{throw t.servers.delete(n),e}),t.servers.set(n,r))),r===void 0?e.productionDestinationPrefix:(await r).origin}let n=readEveBaseUrlEnvironment();if(n!==void 0)return n;if(process.env.NODE_ENV!==`development`)return e.productionDestinationPrefix;let r=`dev:${e.appRoot}`,i=t.servers.get(r);return i===void 0&&(i=resolveSharedEveDevServer(e.appRoot).catch(e=>{throw t.servers.delete(r),e}),t.servers.set(r,i)),(await i).origin}export{resolveEveDestinationPrefix};

package/dist/src/public/next/vercel-output-config.d.ts

@@ -0,0 +1,9 @@
+export interface EnsureVercelOutputConfigResult {
+    readonly servicePrefix: string;
+}
+export declare function ensureEveVercelOutputConfig(input: {
+    readonly appRoot: string;
+    readonly eveBuildCommand: string;
+    readonly nextRoot: string;
+    readonly servicePrefix: string;
+}): Promise<EnsureVercelOutputConfigResult>;

package/dist/src/public/next/vercel-output-config.js

@@ -0,0 +1 @@
+import{dirname,join,relative}from"node:path";import{mkdir,readFile,writeFile}from"node:fs/promises";import{findClosestLinkedVercelDirectory,findClosestVercelOutputDirectory}from"#shared/vercel-output-directory.js";const VERCEL_JSON_FILE_NAME=`vercel.json`,VERCEL_OUTPUT_CONFIG_FILE_NAME=`.vercel/output/config.json`;function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function hasServices(e){return e!==void 0&&Object.keys(e).length>0}function resolveRelativeEntrypoint(e,t){let r=relative(e,t);return r.length===0?`.`:r.replaceAll(`\\`,`/`)}async function resolveVercelOutputConfigLocation(n){let r=await findClosestLinkedVercelDirectory(n),i=r===void 0?n:dirname(r),a=await findClosestVercelOutputDirectory(n);return a===void 0?r===void 0?{outputConfigPath:join(n,VERCEL_OUTPUT_CONFIG_FILE_NAME),projectRoot:i}:{outputConfigPath:join(r,`output`,`config.json`),projectRoot:i}:{outputConfigPath:join(a,`config.json`),projectRoot:i}}function normalizeVercelServicesConfig(e,t){if(!isRecord(e))throw Error(`${t} must contain a JSON object.`);let n=e.experimentalServices;if(n!==void 0&&!isRecord(n))throw Error(`${t} experimentalServices must be a JSON object.`);return e}async function readVercelServicesConfig(e,t){try{return normalizeVercelServicesConfig(JSON.parse(await readFile(e,`utf8`)),t)}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)}function resolveServicePrefix(e){if(e!==void 0){if(typeof e.routePrefix==`string`&&e.routePrefix.trim().length>0)return e.routePrefix.trim();if(typeof e.mount==`string`&&e.mount.trim().length>0)return e.mount.trim();if(isRecord(e.mount)&&typeof e.mount.path==`string`&&e.mount.path.trim().length>0)return e.mount.path.trim()}}function resolveConfiguredServicePrefix(e){return resolveServicePrefix(findServiceByFramework(e.services,`eve`))??e.servicePrefix}function assertRootServicesAreComplete(e){let t=findServiceByFramework(e.services,`eve`),n=findServiceByFramework(e.services,`nextjs`);if(t!==void 0&&n!==void 0)return resolveServicePrefix(t)??e.servicePrefix;throw Error(`${VERCEL_JSON_FILE_NAME} already defines experimentalServices, so withEve cannot add generated services through ${VERCEL_OUTPUT_CONFIG_FILE_NAME}. Add both the Next.js and Eve services to ${VERCEL_JSON_FILE_NAME}, or remove experimentalServices from ${VERCEL_JSON_FILE_NAME}.`)}async function ensureEveVercelOutputConfig(n){let{outputConfigPath:i,projectRoot:o}=await resolveVercelOutputConfigLocation(n.nextRoot),s=(await readVercelServicesConfig(join(o,VERCEL_JSON_FILE_NAME),VERCEL_JSON_FILE_NAME)).experimentalServices;if(hasServices(s))return{servicePrefix:assertRootServicesAreComplete({services:s,servicePrefix:n.servicePrefix})};let c=await readVercelServicesConfig(i,VERCEL_OUTPUT_CONFIG_FILE_NAME),l=resolveRelativeEntrypoint(n.nextRoot,n.appRoot),u=c.experimentalServices??{},d=findServiceByFramework(u,`eve`),f=findServiceByFramework(u,`nextjs`),p=resolveConfiguredServicePrefix({services:u,servicePrefix:n.servicePrefix}),m={...u};f===void 0&&(m.web={entrypoint:`.`,framework:`nextjs`,mount:`/`,type:`web`}),d===void 0&&(m.eve={buildCommand:n.eveBuildCommand,entrypoint:l,framework:`eve`,mount:p,type:`web`});let h={...c,version:3,experimentalServices:m};return JSON.stringify(c)!==JSON.stringify(h)&&(await mkdir(dirname(i),{recursive:!0}),await writeFile(i,`${JSON.stringify(h,null,2)}\n`)),{servicePrefix:p}}export{ensureEveVercelOutputConfig};

package/dist/src/public/nuxt/dev-server.d.ts

@@ -0,0 +1,24 @@
+import { type ChildProcess } from "node:child_process";
+export declare const EVE_BASE_URL_ENV = "EVE_BASE_URL";
+export interface EveProcessHandle {
+    readonly origin: string;
+    readonly process?: ChildProcess;
+}
+export interface EveDevServerRegistry {
+    readonly appRoot: string;
+    readonly origin: string;
+    readonly pid: number | null;
+    readonly updatedAt: string;
+}
+/**
+ * Parse and validate a persisted dev-server registry record. Returns
+ * `undefined` for anything that is not a well-formed registry so callers fall
+ * back to spawning a fresh server.
+ */
+export declare function normalizeDevServerRegistry(value: unknown): EveDevServerRegistry | undefined;
+/**
+ * Resolve a shared Eve dev server for {@link appRoot}, reusing a healthy
+ * registered server when one exists and otherwise spawning a new one behind a
+ * cross-process lock so concurrent Nuxt processes don't each boot Eve.
+ */
+export declare function resolveSharedEveDevServer(appRoot: string): Promise<EveProcessHandle>;

package/dist/src/public/nuxt/dev-server.js

@@ -0,0 +1 @@
+import{joinRoutePrefix,normalizeOrigin}from"./routing.js";import{EVE_ROUTE_PREFIX}from"#protocol/routes.js";import{join}from"node:path";import{mkdir,open,readFile,rm,stat,writeFile}from"node:fs/promises";import{spawn}from"node:child_process";import{resolvePackageRoot}from"#internal/application/package.js";const EVE_BASE_URL_ENV=`EVE_BASE_URL`,DEFAULT_SERVER_READY_TIMEOUT_MS=3e4,DEV_SERVER_REGISTRY_TIMEOUT_MS=3e4,LOCAL_SERVER_URL_PATTERN=/https?:\/\/(?:\[[^\]\s]+\]|[^\s/:[\]]+)(?::\d+)?/;function isNodeErrorWithCode(e,t){return e instanceof Error&&`code`in e&&e.code===t}function delay(e){return new Promise(t=>setTimeout(t,e))}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function resolveEveCacheDirectory(e){return join(e,`.eve`)}function resolveEveDevServerRegistryPath(e){return join(resolveEveCacheDirectory(e),`nuxt-dev-server.json`)}function resolveEveDevServerLockPath(e){return join(resolveEveCacheDirectory(e),`nuxt-dev-server.lock`)}function normalizeDevServerRegistry(e){if(isRecord(e)&&!(typeof e.appRoot!=`string`||typeof e.origin!=`string`||typeof e.updatedAt!=`string`)&&!(e.pid!==null&&typeof e.pid!=`number`))try{return{appRoot:e.appRoot,origin:normalizeOrigin(e.origin),pid:e.pid,updatedAt:e.updatedAt}}catch{return}}async function isEveServerHealthy(t){let r=new AbortController,i=setTimeout(()=>r.abort(),1e3);try{return(await fetch(joinRoutePrefix(t,`${EVE_ROUTE_PREFIX}/health`),{signal:r.signal})).ok}catch{return!1}finally{clearTimeout(i)}}async function readUsableEveDevServerRegistry(e){try{let t=normalizeDevServerRegistry(JSON.parse(await readFile(resolveEveDevServerRegistryPath(e),`utf8`)));return t===void 0||t.appRoot!==e||!await isEveServerHealthy(t.origin)?void 0:t.origin}catch(e){if(isNodeErrorWithCode(e,`ENOENT`))return;throw e}}async function writeEveDevServerRegistry(e,t){await mkdir(resolveEveCacheDirectory(e),{recursive:!0}),await writeFile(resolveEveDevServerRegistryPath(e),`${JSON.stringify({appRoot:e,origin:t.origin,pid:t.process?.pid??null,updatedAt:new Date().toISOString()},null,2)}\n`)}async function removeStaleEveDevServerLock(e){try{let t=await stat(e);Date.now()-t.mtimeMs>3e4&&await rm(e,{force:!0})}catch(e){if(!isNodeErrorWithCode(e,`ENOENT`))throw e}}async function acquireEveDevServerLock(e){let t=resolveEveCacheDirectory(e),n=resolveEveDevServerLockPath(e),r=Date.now()+DEV_SERVER_REGISTRY_TIMEOUT_MS;for(await mkdir(t,{recursive:!0});;)try{let e=await open(n,`wx`);return await e.writeFile(`${String(process.pid)}\n`),await e.close(),async()=>{await rm(n,{force:!0})}}catch(t){if(!isNodeErrorWithCode(t,`EEXIST`))throw t;if(await readUsableEveDevServerRegistry(e)!==void 0)return async()=>{};if(await removeStaleEveDevServerLock(n),Date.now()>r)throw Error(`Timed out after ${DEV_SERVER_REGISTRY_TIMEOUT_MS}ms waiting for another Nuxt process to start Eve.`);await delay(100)}}function createEveBinaryPath(){return join(resolvePackageRoot(),`bin`,`eve.js`)}function startServerProcess(e){return new Promise((n,r)=>{let i=spawn(e.command,e.args,{cwd:e.cwd,env:{...process.env,...e.env},stdio:[`ignore`,`pipe`,`pipe`]}),a=setTimeout(()=>{i.kill(),r(Error(`Timed out after ${DEFAULT_SERVER_READY_TIMEOUT_MS}ms waiting for Eve to print its server URL.`))},DEFAULT_SERVER_READY_TIMEOUT_MS),cleanup=()=>{clearTimeout(a),i.off(`error`,handleError),i.off(`exit`,handleEarlyExit)},handleError=e=>{cleanup(),r(e)},handleEarlyExit=(e,t)=>{cleanup(),r(Error(`Eve server process exited before printing its server URL (code ${String(e)}, signal ${String(t)}).`))},o=!1,handleOutput=e=>{if(o)return;let r=LOCAL_SERVER_URL_PATTERN.exec(e.toString(`utf8`));r!==null&&(o=!0,cleanup(),n({origin:normalizeOrigin(r[0]),process:i}))};i.once(`error`,handleError),i.once(`exit`,handleEarlyExit),i.stdout.on(`data`,e=>{process.stdout.write(e),handleOutput(e)}),i.stderr.on(`data`,e=>{process.stderr.write(e),handleOutput(e)})})}function installProcessShutdown(e){let t=e.process;if(t===void 0)return e;let close=()=>{process.off(`beforeExit`,close),process.off(`exit`,close),t.killed||t.kill()};return process.once(`beforeExit`,close),process.once(`exit`,close),e}function startEveDevServer(e){return startServerProcess({args:[createEveBinaryPath(),`dev`,`--no-repl`,`--port`,`0`],command:process.execPath,cwd:e}).then(e=>(process.env[EVE_BASE_URL_ENV]=e.origin,installProcessShutdown(e)))}async function resolveSharedEveDevServer(e){let t=await readUsableEveDevServerRegistry(e);if(t!==void 0)return process.env[EVE_BASE_URL_ENV]=t,{origin:t};let n=await acquireEveDevServerLock(e);try{let t=await readUsableEveDevServerRegistry(e);if(t!==void 0)return process.env[EVE_BASE_URL_ENV]=t,{origin:t};let n=await startEveDevServer(e);return await writeEveDevServerRegistry(e,n),n}finally{await n()}}export{EVE_BASE_URL_ENV,normalizeDevServerRegistry,resolveSharedEveDevServer};

package/dist/src/public/nuxt/index.d.ts

@@ -0,0 +1 @@
+export { default, EVE_NUXT_SERVICE_PREFIX, type EveNuxtModuleOptions } from "./module.js";

package/dist/src/public/nuxt/index.js

@@ -0,0 +1 @@
+import{EVE_NUXT_SERVICE_PREFIX}from"./routing.js";import module_default from"./module.js";export{EVE_NUXT_SERVICE_PREFIX,module_default as default};

package/dist/src/public/nuxt/module.d.ts

@@ -0,0 +1,43 @@
+import { EVE_NUXT_SERVICE_PREFIX } from "./routing.js";
+export { EVE_NUXT_SERVICE_PREFIX };
+/**
+ * Options for the Eve Nuxt module.
+ */
+export interface EveNuxtModuleOptions {
+    /**
+     * Path to the Eve application root, resolved relative to the Nuxt project
+     * root unless absolute. Defaults to the Nuxt project root. The dev server is
+     * spawned here and written as the Eve service entrypoint in `vercel.json`
+     * (relative to the Nuxt root).
+     */
+    eveRoot?: string;
+    /**
+     * Build command for the generated Eve Vercel service. Defaults to `"eve build"`.
+     */
+    eveBuildCommand?: string;
+    /**
+     * Set to `false` to skip creating or updating `vercel.json`. By default the
+     * module ensures `vercel.json` contains `experimentalServices` for the Nuxt
+     * app and Eve app.
+     */
+    configureVercelJson?: boolean;
+    /**
+     * Private Vercel service prefix Eve transport is proxied to. Defaults to
+     * {@link EVE_NUXT_SERVICE_PREFIX}. When `configureVercelJson` is enabled, it
+     * is written as the Eve service `routePrefix`, but an existing `routePrefix`
+     * in `vercel.json` takes precedence. Normalized to a leading-slash,
+     * no-trailing-slash route; cannot resolve to `/`.
+     */
+    servicePrefix?: string;
+}
+/**
+ * Nuxt module that wires an Eve agent into a Nuxt app. Register under `modules`
+ * (configured via the `eve` config key). It auto-imports the `useEveAgent()`
+ * composable, routes Eve transport requests (`/eve/v1/**`) to the Eve service
+ * (a shared dev server spawned on demand in dev, a Vercel sibling service or a
+ * configured origin/port in production), and unless `configureVercelJson` is
+ * `false`, ensures `vercel.json` declares both the Nuxt and Eve services.
+ * Requires Nuxt >= 4.0.0. Configure via {@link EveNuxtModuleOptions}.
+ */
+declare const _default: import("nuxt/schema").NuxtModule<EveNuxtModuleOptions, EveNuxtModuleOptions, false>;
+export default _default;

package/dist/src/public/nuxt/module.js

@@ -0,0 +1 @@
+import{EVE_NUXT_SERVICE_PREFIX,createEveVercelRewriteRoute,joinRoutePrefix,normalizeOrigin,normalizeRoutePrefix,resolveProductionTarget}from"./routing.js";import{EVE_BASE_URL_ENV,resolveSharedEveDevServer}from"./dev-server.js";import{ensureEveVercelJson}from"./vercel-json.js";import{EVE_ROUTE_PREFIX}from"#protocol/routes.js";import{isAbsolute,resolve}from"node:path";import{addImports,defineNuxtModule,extendRouteRules}from"@nuxt/kit";function resolveApplicationRoot(e,t){return t===void 0||t.length===0?e:isAbsolute(t)?t:resolve(e,t)}async function resolveEveProxyTarget(e){if(!e.dev)return resolveProductionTarget(e.servicePrefix);let t=process.env[EVE_BASE_URL_ENV]?.trim();if(t&&t.length>0)return joinRoutePrefix(normalizeOrigin(t),EVE_ROUTE_PREFIX);let i=await resolveSharedEveDevServer(e.appRoot);return i.process!==void 0&&e.onDevServerSpawned?.(i.process),joinRoutePrefix(i.origin,EVE_ROUTE_PREFIX)}var module_default=defineNuxtModule({meta:{name:`eve`,configKey:`eve`,compatibility:{nuxt:`>=4.0.0`}},defaults:{},async setup(e,n){let r=n.options.rootDir,a=resolveApplicationRoot(r,e.eveRoot),o=normalizeRoutePrefix(e.servicePrefix??`/_eve_internal/eve`),s=e.configureVercelJson!==!1;if(addImports({name:`useEveAgent`,from:`eve/vue`}),!n.options.dev&&process.env.VERCEL){let e=createEveVercelRewriteRoute(o),r=n.options.nitro,i=r.vercel?.config;r.vercel={...r.vercel,config:{version:3,...i,routes:[e,...i?.routes??[]]}}}else n.hook(`modules:done`,async()=>{let e=await resolveEveProxyTarget({appRoot:a,dev:n.options.dev,servicePrefix:o,onDevServerSpawned:e=>{n.hook(`close`,()=>{e.killed||e.kill()})}});extendRouteRules(`${EVE_ROUTE_PREFIX}/**`,{proxy:`${e}/**`})});s&&await ensureEveVercelJson({appRoot:a,eveBuildCommand:e.eveBuildCommand??`eve build`,nuxtRoot:r,servicePrefix:o})}});export{EVE_NUXT_SERVICE_PREFIX,module_default as default};

package/dist/src/public/nuxt/routing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Private route namespace used when a Vercel deployment hosts Eve as a
+ * separate experimental service behind the Nuxt app.
+ */
+export declare const EVE_NUXT_SERVICE_PREFIX = "/_eve_internal/eve";
+/**
+ * Normalize a user-supplied service prefix into a leading-slash, no-trailing-
+ * slash route. Throws when the prefix resolves to the root route, which would
+ * collide with the Nuxt web service.
+ */
+export declare function normalizeRoutePrefix(prefix: string): string;
+/**
+ * Join a route prefix and a path with exactly one separating slash.
+ */
+export declare function joinRoutePrefix(prefix: string, path: string): string;
+/**
+ * Reduce an origin string to its canonical `protocol://host[:port]` form.
+ */
+export declare function normalizeOrigin(origin: string): string;
+/**
+ * Resolve the local production port the module proxies to when an Eve service
+ * runs alongside a non-Vercel Nuxt deployment. Defaults to
+ * {@link DEFAULT_EVE_NUXT_PRODUCTION_PORT}.
+ */
+export declare function readLocalProductionPort(): number;
+/**
+ * An edge-level Vercel rewrite expressed in Build Output API v3 form.
+ */
+export interface EveVercelRewriteRoute {
+    readonly src: string;
+    readonly dest: string;
+    /**
+     * Re-run route matching against the rewritten `dest`. Required so the
+     * rewritten Eve service path is routed to the sibling Eve service instead of
+     * being resolved inside the host service's own filesystem (which 404s).
+     */
+    readonly check: true;
+}
+/**
+ * Build the edge-level Vercel rewrite that forwards Eve transport requests
+ * (`/eve/v1/**`) to the Eve service prefix (`/_eve_internal/eve/eve/v1/**`).
+ *
+ * Mirrors the Next.js integration's `beforeFiles` rewrite. A Nitro runtime
+ * `proxy` route rule cannot reach a sibling Vercel service — the proxied
+ * request loops back into the Nuxt function and 404s — so production routing
+ * must happen at the edge via the build output config instead.
+ */
+export declare function createEveVercelRewriteRoute(servicePrefix: string): EveVercelRewriteRoute;
+/**
+ * Resolve the proxy destination for Eve routes in production.
+ *
+ * On Vercel the destination is the private service prefix. Off Vercel it is an
+ * explicit origin override (`EVE_NUXT_PRODUCTION_ORIGIN`) or a local port.
+ */
+export declare function resolveProductionTarget(servicePrefix: string): string;

package/dist/src/public/nuxt/routing.js

@@ -0,0 +1 @@
+import{EVE_ROUTE_PREFIX}from"#protocol/routes.js";const EVE_NUXT_SERVICE_PREFIX=`/_eve_internal/eve`,EVE_NUXT_PRODUCTION_PORT_ENV=`EVE_NUXT_PRODUCTION_PORT`;function normalizeRoutePrefix(e){let t=(e.startsWith(`/`)?e:`/${e}`).replace(/\/+$/,``);if(t.length===0)throw Error(`Eve Nuxt service prefix cannot resolve to the root route.`);return t}function joinRoutePrefix(e,t){return`${e.replace(/\/+$/,``)}/${t.replace(/^\/+/,``)}`}function normalizeOrigin(e){return new URL(e.trim()).origin}function readLocalProductionPort(){let e=process.env[EVE_NUXT_PRODUCTION_PORT_ENV];if(e===void 0||e.trim().length===0)return 4274;let t=Number.parseInt(e,10);if(String(t)!==e.trim()||t<1||t>65535)throw Error(`${EVE_NUXT_PRODUCTION_PORT_ENV} must be an integer between 1 and 65535.`);return t}function createEveVercelRewriteRoute(t){let n=joinRoutePrefix(t,EVE_ROUTE_PREFIX);return{src:`^${EVE_ROUTE_PREFIX}/(.*)$`,dest:`${n}/$1`,check:!0}}function resolveProductionTarget(t){if(process.env.VERCEL)return joinRoutePrefix(t,EVE_ROUTE_PREFIX);let n=process.env.EVE_NUXT_PRODUCTION_ORIGIN;return n!==void 0&&n.trim().length>0?joinRoutePrefix(normalizeOrigin(n),EVE_ROUTE_PREFIX):joinRoutePrefix(`http://127.0.0.1:${String(readLocalProductionPort())}`,EVE_ROUTE_PREFIX)}export{EVE_NUXT_SERVICE_PREFIX,createEveVercelRewriteRoute,joinRoutePrefix,normalizeOrigin,normalizeRoutePrefix,readLocalProductionPort,resolveProductionTarget};

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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1 @@
+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};

package/dist/src/public/sandbox/backends/default.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+import type { VercelSandboxCreateOptions } from "#public/sandbox/vercel-sandbox.js";
+/**
+ * Input to {@link defaultBackend}: a separate options bag per inner
+ * backend. The framework picks one bag at runtime based on `process.env.VERCEL`
+ * and passes it to the chosen factory; the other is ignored.
+ */
+export interface DefaultBackendOptions {
+    readonly local?: LocalSandboxCreateOptions;
+    readonly vercel?: VercelSandboxCreateOptions;
+}
+/**
+ * Constructs an env-aware sandbox backend that delegates to
+ * {@link vercelBackend} on hosted Vercel (where `process.env.VERCEL`
+ * is truthy) and to {@link localBackend} everywhere else.
+ *
+ * Optionally accepts a keyed options bag (`{ local, vercel }`) so each
+ * inner backend receives its own typed create options without forcing
+ * authors to pin to one backend up front.
+ */
+export declare function defaultBackend(opts?: DefaultBackendOptions): SandboxBackend;

package/dist/src/public/sandbox/backends/default.js

@@ -0,0 +1 @@
+import{lazyBackend}from"#execution/sandbox/lazy-backend.js";import{localBackend}from"#public/sandbox/backends/local.js";import{vercelBackend}from"#public/sandbox/backends/vercel.js";function defaultBackend(e){return lazyBackend(()=>process.env.VERCEL?vercelBackend(e?.vercel):localBackend(e?.local))}export{defaultBackend};

package/dist/src/public/sandbox/backends/local.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+/**
+ * Constructs the built-in local sandbox backend.
+ *
+ * The local backend runs the workspace under `just-bash` against an
+ * in-memory filesystem and persists snapshots into `.eve/sandbox-cache/`
+ * under the application root. It is the default backend on developer
+ * machines (`pnpm eve dev`).
+ *
+ * Accepts an `opts` parameter for parity with other backends, but
+ * `LocalSandboxCreateOptions` is empty today: `just-bash` exposes no
+ * configuration to surface. To add options, widen
+ * `LocalSandboxCreateOptions` and route them into the binding without
+ * changing this signature.
+ */
+export declare function localBackend(opts?: LocalSandboxCreateOptions): SandboxBackend;

package/dist/src/public/sandbox/backends/local.js

@@ -0,0 +1 @@
+import{createLocalSandboxBackend}from"#execution/sandbox/bindings/local.js";function localBackend(e){return createLocalSandboxBackend({createOptions:e})}export{localBackend};

package/dist/src/public/sandbox/backends/vercel.d.ts

@@ -0,0 +1,24 @@
+import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
+/**
+ * Constructs the built-in Vercel sandbox backend.
+ *
+ * The optional `opts` parameter is forwarded to the Vercel SDK's
+ * `Sandbox.create(...)` for every fresh sandbox the framework creates
+ * (template at prewarm, session at first-time create). On resume
+ * (`Sandbox.get`), no create happens, so opts are not re-applied.
+ *
+ * `opts.source`, if supplied, is used only on the template create:
+ * the author's snapshot, git revision, or tarball becomes the base
+ * layer of the template. Bootstrap, seed files, and framework setup
+ * still run on top, and every session derives from the resulting
+ * Eve-owned snapshot. `source` is stripped from session creates so the
+ * framework's snapshot always wins.
+ *
+ * `bootstrap({ use })` applies its options to the template via
+ * `sandbox.update(...)`; those settings persist into the snapshot.
+ * `onSession({ use })` applies its options to the live session via the
+ * SDK's `update` under the hood, overriding any overlapping field
+ * from `opts`.
+ */
+export declare function vercelBackend(opts?: VercelSandboxCreateOptions): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;

package/dist/src/public/sandbox/backends/vercel.js

@@ -0,0 +1 @@
+import{createVercelSandboxBackend}from"#execution/sandbox/bindings/vercel.js";function vercelBackend(e){return createVercelSandboxBackend({createOptions:e})}export{vercelBackend};

package/dist/src/public/sandbox/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sandbox authoring helpers for `agent/sandbox.ts` (or
+ * `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
+ */
+export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandResult, type SandboxDefinition, type SandboxProcess, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRevalidationKeyFn, type SandboxRunOptions, type SandboxSession, type SandboxSpawnOptions, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
+export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
+export type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
+export { defaultBackend } from "#public/sandbox/backends/default.js";
+export { localBackend } from "#public/sandbox/backends/local.js";
+export { vercelBackend } from "#public/sandbox/backends/vercel.js";
+export type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+export type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";

package/dist/src/public/sandbox/index.js

@@ -0,0 +1 @@
+import{SandboxTemplateNotProvisionedError}from"#public/definitions/sandbox-backend.js";import{localBackend}from"#public/sandbox/backends/local.js";import{vercelBackend}from"#public/sandbox/backends/vercel.js";import{defineSandbox}from"#public/definitions/sandbox.js";import{defaultBackend}from"#public/sandbox/backends/default.js";export{SandboxTemplateNotProvisionedError,defaultBackend,defineSandbox,localBackend,vercelBackend};

package/dist/src/public/sandbox/local-sandbox.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Options accepted by `localBackend(opts)`. Reserved for future
+ * widening: today the local backend exposes no consumer-controllable
+ * create options, so this is an empty object. The parameter exists on
+ * the factory so adding real fields here later is purely additive.
+ */
+export type LocalSandboxCreateOptions = Record<string, never>;

package/dist/src/public/sandbox/local-sandbox.js

@@ -0,0 +1 @@
+export{};

package/dist/src/public/sandbox/vercel-sandbox.d.ts

@@ -0,0 +1,42 @@
+import type { Sandbox as SdkSandbox, SandboxUpdateParams } from "#compiled/@vercel/sandbox/index.js";
+/**
+ * Options accepted by `vercelBackend(opts)`. Forwarded directly to the
+ * Vercel SDK's `Sandbox.create(...)` for every fresh sandbox the
+ * framework creates (template at prewarm time, session at first-time
+ * session-create). Skipped on resume (`Sandbox.get`) since no create
+ * happens there.
+ *
+ * Framework-injected fields (`name`, `onResume`, `persistent`, `signal`)
+ * are excluded: the framework owns those and overrides any
+ * author-supplied values.
+ *
+ * `source` is honored only on the template create at prewarm time, so
+ * an author-supplied snapshot, git revision, or tarball becomes the
+ * base layer for the template. Bootstrap, seed files, and framework
+ * setup (workspace dir, ripgrep) all run on top, and the resulting
+ * framework-owned snapshot is what every later session derives from,
+ * so `source` is stripped from the session-create path. Eve does not
+ * detect external snapshot changes; to pick up a rebuilt external
+ * snapshot, force a template rebuild (e.g. by changing the sandbox
+ * definition so its template key changes).
+ */
+export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "onResume" | "persistent" | "signal">;
+/**
+ * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
+ * Aliases the Vercel SDK's `SandboxUpdateParams` because bootstrap
+ * applies its options to the template via `sandbox.update(...)` after
+ * `Sandbox.create()` and before the snapshot is captured. The Vercel
+ * SDK persists `update`-d settings on the sandbox so they survive into
+ * the snapshot, which becomes the seed for every later session.
+ *
+ * Today this is the same shape as
+ * {@link VercelSandboxSessionUseOptions}; both are exposed as separate
+ * named aliases so future divergence is non-breaking.
+ */
+export type VercelSandboxBootstrapUseOptions = SandboxUpdateParams;
+/**
+ * Options accepted by the Vercel backend's `onSession({ use })` hook.
+ * Aliases the Vercel SDK's `SandboxUpdateParams`; passed values are
+ * applied to the live session via the SDK's `update`.
+ */
+export type VercelSandboxSessionUseOptions = SandboxUpdateParams;

package/dist/src/public/sandbox/vercel-sandbox.js

@@ -0,0 +1 @@
+export{};

package/dist/src/public/schedules/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Schedule authoring helpers for `agent/schedules/*` files.
+ */
+export { defineSchedule, type ScheduleDefinition, type ScheduleHandlerArgs, type ScheduleRunHandler, type TypedReceiveTarget, } from "#public/definitions/schedule.js";

package/dist/src/public/schedules/index.js

@@ -0,0 +1 @@
+import{defineSchedule}from"#public/definitions/schedule.js";export{defineSchedule};