eve 0.5.4 → 0.6.0-beta.1

package/dist/src/execution/runtime-context.js

@@ -0,0 +1 @@
+import{AuthKey,CapabilitiesKey,ChannelInstrumentationKey,ContinuationTokenKey,InitiatorAuthKey,ModeKey,ParentSessionKey,SessionCallbackKey}from"#context/keys.js";import{ContextContainer}from"#context/container.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{setChannelContext}from"#execution/channel-context.js";function buildRunContext(t){let{bundle:n,run:r}=t,i=new ContextContainer,a=r.auth;if(i.set(BundleKey,n),setChannelContext(i,r.adapter,{channelName:r.channelName}),r.channelMetadata!==void 0){let e=i.get(ChannelInstrumentationKey);i.set(ChannelInstrumentationKey,{kind:e?.kind??r.channelMetadata.kind,metadata:r.channelMetadata.metadata})}return i.set(ContinuationTokenKey,r.continuationToken??``),i.set(ModeKey,r.mode),i.set(AuthKey,a),i.set(InitiatorAuthKey,r.initiatorAuth??a),r.capabilities!==void 0&&i.set(CapabilitiesKey,r.capabilities),r.callback!==void 0&&i.set(SessionCallbackKey,r.callback),r.parent!==void 0&&i.set(ParentSessionKey,r.parent),i}export{buildRunContext};

package/dist/src/execution/runtime-errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown by a {@link Runtime}'s `deliver` when no in-flight session
+ * matches the continuation token. Callers using the resume-or-start
+ * pattern (e.g. {@link createSendFn}) treat this as the signal to start
+ * a fresh session.
+ */
+export declare class RuntimeNoActiveSessionError extends Error {
+    readonly code: "NO_ACTIVE_SESSION";
+    readonly continuationToken: string;
+    constructor(continuationToken: string);
+}
+/** Type guard for {@link RuntimeNoActiveSessionError}. */
+export declare function isRuntimeNoActiveSessionError(error: unknown): error is RuntimeNoActiveSessionError;

package/dist/src/execution/runtime-errors.js

@@ -0,0 +1 @@
+var RuntimeNoActiveSessionError=class extends Error{code=`NO_ACTIVE_SESSION`;continuationToken;constructor(e){super(`No active session for continuationToken "${e}".`),this.name=`RuntimeNoActiveSessionError`,this.continuationToken=e}};function isRuntimeNoActiveSessionError(e){return e instanceof RuntimeNoActiveSessionError}export{RuntimeNoActiveSessionError,isRuntimeNoActiveSessionError};

package/dist/src/execution/sandbox/bash-tool.d.ts

@@ -0,0 +1,30 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/**
+ * Typed input accepted by {@link executeBeveOnSandbox}.
+ */
+export interface BeveInput {
+    readonly command: string;
+}
+/**
+ * Structured result returned from {@link executeBeveOnSandbox}.
+ */
+export interface BeveResult {
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+    /** True when stdout or stderr was shortened to fit within output limits. */
+    readonly truncated: boolean;
+}
+/**
+ * Executes one shell command inside the agent's sandbox via `SandboxKey`
+ * on the active runtime context.
+ *
+ * Both stdout and stderr are tail-truncated to keep the end of the output
+ * (where errors and final results typically appear) within the shared
+ * {@link MAX_OUTPUT_LINES} / {@link MAX_OUTPUT_BYTES} limits.
+ *
+ * Used by the framework `bash` tool and by author tools constructed via
+ * `defineBeveTool`. Centralizing the executor here keeps the error
+ * messages and result shape identical across all bash-style tools.
+ */
+export declare function executeBeveOnSandbox(sandbox: SandboxSession, args: BeveInput): Promise<BeveResult>;

package/dist/src/execution/sandbox/bash-tool.js

@@ -0,0 +1 @@
+import{truncateTail}from"#execution/sandbox/truncate-output.js";async function executeBeveOnSandbox(e,t){let n=await e.run({command:t.command}),r=truncateTail(n.stdout),i=truncateTail(n.stderr),a=r.truncated||i.truncated,o=r.output;r.truncated&&(o=`[stdout truncated: showing last ${r.outputLines} of ${r.totalLines} lines]\n`+o);let s=i.output;return i.truncated&&(s=`[stderr truncated: showing last ${i.outputLines} of ${i.totalLines} lines]\n`+s),{exitCode:n.exitCode,stderr:s,stdout:o,truncated:a}}export{executeBeveOnSandbox};

package/dist/src/execution/sandbox/bindings/local.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+/**
+ * Construction input for {@link createLocalSandboxBackend}. Internal —
+ * the public surface is the `localBackend()` factory under
+ * `eve/sandbox`.
+ */
+export interface CreateLocalSandboxBackendInput {
+    readonly createOptions?: LocalSandboxCreateOptions;
+}
+/**
+ * Creates the local just-bash-backed sandbox backend.
+ *
+ * The cache directory is derived from the runtime context's `appRoot`
+ * on every `create` call so the backend stays stateless and matches
+ * the framework's per-call dispatch contract.
+ *
+ * Accepts `createOptions` for parity with other backends; the local
+ * backend currently has no consumer-controllable create options so the
+ * value is reserved for future widening of {@link LocalSandboxCreateOptions}.
+ */
+export declare function createLocalSandboxBackend(_input?: CreateLocalSandboxBackendInput): SandboxBackend;

package/dist/src/execution/sandbox/bindings/local.js

@@ -0,0 +1 @@
+import{dirname,join}from"node:path";import{access,mkdir,readFile,writeFile}from"node:fs/promises";import{resolveSandboxCacheDirectory}from"#internal/application/paths.js";import{shellQuote}from"#execution/sandbox/shell-quote.js";import{SandboxTemplateNotProvisionedError}from"#public/definitions/sandbox-backend.js";import{WORKSPACE_ROOT}from"#runtime/workspace/types.js";import{buildSandboxSession}from"#execution/sandbox/session.js";import{bufferToStream,streamToBuffer}from"#execution/sandbox/stream-utils.js";function createLocalSandboxBackend(e={}){return{name:`local`,async prewarm(e){let t=resolveTemplateSnapshotPath(resolveSandboxCacheDirectory(e.runtimeContext.appRoot),e.templateKey);if(await doesPathExist(t))return{reused:!0};let n=await createBeveSandbox({sessionKey:e.templateKey,snapshotPath:t}),r=buildSandboxSession(createLocalInternalSandboxSession(n),localSetNetworkPolicyUnsupported);try{e.bootstrap!==void 0&&await e.bootstrap({use:async()=>r});for(let t of e.seedFiles)typeof t.content==`string`?await r.writeTextFile({content:t.content,path:t.path}):await r.writeBinaryFile({content:t.content,path:t.path});if(await n.captureSnapshot()===null)throw Error(`Failed to capture local sandbox template state for "${e.templateKey}".`)}finally{await n.dispose()}return{reused:!1}},async create(e){let t=resolveSandboxCacheDirectory(e.runtimeContext.appRoot),n=getLocalSnapshotPath(e.existingMetadata)??resolveSessionSnapshotPath(t,e.sessionKey);if(e.templateKey!==null&&!await doesPathExist(n)){let r=await readLocalSnapshot(resolveTemplateSnapshotPath(t,e.templateKey));if(r===null)throw new SandboxTemplateNotProvisionedError({backendName:`local`,templateKey:e.templateKey});await writeLocalSnapshot(n,r)}return createHandle(await createBeveSandbox({sessionKey:e.sessionKey,snapshotPath:n}))}}}async function createBeveSandbox(t){let{InMemoryFs:n,Sandbox:r}=await import(`#compiled/just-bash/index.js`),i=await readLocalSnapshot(t.snapshotPath),a=new n(createInitialFiles(i));await ensureLocalSandboxDirectories(a),await restoreLocalSandboxDirectories(a,i?.entries??[]);let o=await r.create({cwd:WORKSPACE_ROOT,env:i?.env,fs:a,network:{dangerouslyAllowFullInternetAccess:!0}});return{async captureSnapshot(){let e=await captureLocalSnapshot({filesystem:a,sandbox:o});return await writeLocalSnapshot(t.snapshotPath,e),{snapshotPath:t.snapshotPath}},async dispose(){await o.stop()},async readFileBytes(e){let t;try{t=await a.readFileBuffer(e)}catch{return null}return Buffer.from(t)},async removePath(e){await a.rm(e.path,{force:e.force,recursive:e.recursive})},sessionKey:t.sessionKey,snapshotPath:t.snapshotPath,async spawn(e){if(e.abortSignal?.aborted)throw new DOMException(`The operation was aborted.`,`AbortError`);let t=e.workingDirectory===void 0?e.command:`( cd ${shellQuote(e.workingDirectory)} && ${e.command} )`;return adaptJustBeveCommandToSandboxProcess(await o.runCommand({args:[t],cmd:`eval`,detached:!0,env:e.env,signal:e.abortSignal}))},async writeFiles(t){for(let n of t){let t=dirname(n.path);await a.mkdir(t,{recursive:!0}),await a.writeFile(n.path,n.content)}}}}function adaptJustBeveCommandToSandboxProcess(e){let t=new TextEncoder,n,r,i=!1,a,o=new ReadableStream({start(e){n=e}}),s=new ReadableStream({start(e){r=e}});return(async()=>{try{for await(let i of e.logs()){let e=t.encode(i.data);i.type===`stdout`?n?.enqueue(e):r?.enqueue(e)}}catch(e){a=e,n?.error(e),r?.error(e)}finally{i=!0,a===void 0&&(n?.close(),r?.close())}})(),{stdout:o,stderr:s,async wait(){let t=await e.wait();for(;!i;)await new Promise(e=>setTimeout(e,0));if(a!==void 0)throw a;return{exitCode:t.exitCode}},async kill(){await e.kill()}}}async function localSetNetworkPolicyUnsupported(){throw Error(`setNetworkPolicy() is not supported on the local sandbox backend. just-bash applies its network policy only at sandbox creation (no run-time update) and does not run git or other binaries. Use the Vercel backend for credential brokering and egress control.`)}function createHandle(e){let t=buildSandboxSession(createLocalInternalSandboxSession(e),localSetNetworkPolicyUnsupported);return{session:t,useSessionFn:async()=>t,async captureState(){return{backendName:`local`,metadata:await e.captureSnapshot()??{},sessionKey:e.sessionKey}},async dispose(){await e.dispose()}}}function createLocalInternalSandboxSession(e){return{id:e.sessionKey,resolvePath:resolveLocalPath,async spawn(t){return await e.spawn(t)},async readFile(t){let n=await e.readFileBytes(t.path);return n===null?null:bufferToStream(n)},async removePath(t){await e.removePath(t)},async writeFile(t){let n=await streamToBuffer(t.content);await e.writeFiles([{content:n,path:t.path}])}}}function resolveLocalPath(e){return e.startsWith(`/`)?e:`${WORKSPACE_ROOT}/${e}`}function resolveTemplateSnapshotPath(e,n){return join(e,`local`,`templates`,`${n}.json`)}function resolveSessionSnapshotPath(e,n){return join(e,`local`,`sessions`,`${n}.json`)}function createInitialFiles(e){let t={};for(let n of e?.entries??[])n.kind===`file`&&(t[n.path]=Buffer.from(n.contentBase64,`base64`));return t}async function ensureLocalSandboxDirectories(e){await e.mkdir(WORKSPACE_ROOT,{recursive:!0})}async function restoreLocalSandboxDirectories(e,t){let n=t.filter(e=>e.kind===`directory`).map(e=>e.path).sort((e,t)=>e.localeCompare(t));for(let t of n)t!==WORKSPACE_ROOT&&await e.mkdir(t,{recursive:!0})}async function captureLocalSnapshot(e){let t=[],n=e.filesystem.getAllPaths().sort((e,t)=>e.localeCompare(t));for(let r of n){let n=await e.filesystem.stat(r);if(n.isSymbolicLink)continue;if(n.isDirectory){t.push({kind:`directory`,path:r});continue}if(!n.isFile)continue;let i=await e.filesystem.readFileBuffer(r);t.push({contentBase64:Buffer.from(i).toString(`base64`),kind:`file`,path:r})}return{entries:t,env:{...e.sandbox.bashEnvInstance.getEnv()},version:1}}async function readLocalSnapshot(e){if(!await doesPathExist(e))return null;let t=JSON.parse(await readFile(e,`utf8`));return t.version===1?t:null}async function writeLocalSnapshot(t,n){await mkdir(dirname(t),{recursive:!0}),await writeFile(t,`${JSON.stringify(n,null,2)}\n`)}async function doesPathExist(e){try{return await access(e),!0}catch{return!1}}function getLocalSnapshotPath(e){let t=e?.snapshotPath;return typeof t==`string`?t:void 0}export{createLocalSandboxBackend};

package/dist/src/execution/sandbox/bindings/vercel.d.ts

@@ -0,0 +1,28 @@
+import type * as VercelSandboxSdk from "#compiled/@vercel/sandbox/index.js";
+import type { Sandbox as SdkSandbox } from "#compiled/@vercel/sandbox/index.js";
+import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
+type VercelSandboxModule = typeof VercelSandboxSdk;
+/**
+ * User-controllable subset of `Sandbox.create` parameters.
+ */
+export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "onResume" | "persistent" | "signal">;
+/**
+ * Construction input for {@link createVercelSandboxBackend}. Internal —
+ * the public surface is the `vercelBackend()` factory under
+ * `eve/sandbox`.
+ */
+export interface CreateVercelSandboxBackendInput {
+    readonly createOptions?: VercelSandboxCreateOptions;
+    readonly loadSandboxModule?: () => Promise<VercelSandboxModule>;
+}
+/**
+ * Creates the Vercel-backed sandbox backend.
+ *
+ * Any author-supplied `createOptions` are forwarded to the Vercel SDK
+ * `Sandbox.create(...)` for every fresh sandbox the framework creates
+ * (template at prewarm time, session at first-time session-create). On
+ * resume (`Sandbox.get`) no create happens, so they are not re-applied.
+ */
+export declare function createVercelSandboxBackend(input?: CreateVercelSandboxBackendInput): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;
+export {};

package/dist/src/execution/sandbox/bindings/vercel.js

@@ -0,0 +1 @@
+import{SandboxTemplateNotProvisionedError}from"#public/definitions/sandbox-backend.js";import{WORKSPACE_ROOT}from"#runtime/workspace/types.js";import{buildSandboxSession}from"#execution/sandbox/session.js";import{streamToBuffer}from"#execution/sandbox/stream-utils.js";function createVercelSandboxBackend(e={}){let t=e.loadSandboxModule??(async()=>await import(`#compiled/@vercel/sandbox/index.js`)),n={timeout:DEFAULT_SANDBOX_TIMEOUT_MS,...e.createOptions},r=new Map;return{name:`vercel`,async create(e){let i=resolveVercelSandboxTags(n.tags,e.tags),a=e.templateKey===null?null:await readTemplateForCreate({loadSandboxModule:t,prewarmedTemplates:r,templateKey:e.templateKey}),o;try{o=await ensureSession({createOptions:n,existingMetadata:e.existingMetadata,sandboxModule:await t(),sessionKey:e.sessionKey,snapshotId:a?.snapshotId,tags:i})}catch(t){throw Error(`Failed to create sandbox session "${e.sessionKey}": ${errorMessage(t)}`,{cause:t})}return a===null&&o.created&&await ensureSandboxWorkingDirectory(o.sandbox,n),createHandle(o.sandbox,e.sessionKey)},async prewarm(e){let i;try{i=await ensureTemplate({bootstrap:e.bootstrap,createOptions:n,loadSandboxModule:t,seedFiles:e.seedFiles,templateKey:e.templateKey})}catch(t){throw Error(`Failed to prewarm Vercel sandbox template "${e.templateKey}": ${errorMessage(t)}. Run \`vercel login\` and \`vercel link\` so the SDK can authenticate, or set VERCEL_TOKEN.`,{cause:t})}return r.set(e.templateKey,i.template),{reused:i.reused}}}}async function readTemplate(t){let n=t.prewarmedTemplates.get(t.templateKey);if(n!==void 0)return n;let r=await getNamedSandbox(await t.loadSandboxModule(),t.templateKey);if(r===null||typeof r.currentSnapshotId!=`string`)throw new SandboxTemplateNotProvisionedError({backendName:`vercel`,templateKey:t.templateKey});return{sandboxName:r.name,snapshotId:r.currentSnapshotId,templateKey:t.templateKey}}async function readTemplateForCreate(t){try{return await readTemplate(t)}catch(n){throw SandboxTemplateNotProvisionedError.is(n)?n:Error(`Failed to read sandbox template "${t.templateKey}": ${errorMessage(n)}`,{cause:n})}}async function ensureTemplate(e){let t=await e.loadSandboxModule(),r=await getNamedSandbox(t,e.templateKey),i=resolveVercelSandboxTags(e.createOptions.tags,e.tags);if(r===null){let n={...e.createOptions,name:e.templateKey,persistent:!1};i!==void 0&&(n.tags=i),r=await t.Sandbox.create(n)}else await ensureVercelSandboxTags(r,i);let a=extractAuthorSnapshotId(e.createOptions);if(typeof r.currentSnapshotId==`string`&&r.currentSnapshotId.length>0&&r.currentSnapshotId!==a)return{reused:!0,template:{sandboxName:r.name,snapshotId:r.currentSnapshotId,templateKey:e.templateKey}};await ensureSandboxWorkingDirectory(r,e.createOptions);let o=buildSandboxSession(createVercelInternalSandboxSession(r,e.templateKey),createVercelNetworkPolicySetter(r));e.bootstrap!==void 0&&await e.bootstrap({use:async e=>(e!==void 0&&await r.update(e),o)});for(let t of e.seedFiles)typeof t.content==`string`?await o.writeTextFile({content:t.content,path:t.path}):await o.writeBinaryFile({content:t.content,path:t.path});let s=await r.snapshot();return{reused:!1,template:{sandboxName:r.name,snapshotId:s.snapshotId,templateKey:e.templateKey}}}async function ensureSession(e){let t=getVercelSandboxName(e.existingMetadata)??e.sessionKey,n=await getNamedSandbox(e.sandboxModule,t);if(n!==null)return await ensureVercelSandboxTags(n,e.tags),{created:!1,sandbox:n};let r=createSessionCreateParams(e,t);return e.tags!==void 0&&(r.tags=e.tags),{created:!0,sandbox:await e.sandboxModule.Sandbox.create(r)}}function createSessionCreateParams(e,t){if(e.snapshotId===void 0)return{...e.createOptions,name:t,persistent:!0};let{runtime:n,source:r,...i}=e.createOptions;return{...i,name:t,persistent:!0,source:{snapshotId:e.snapshotId,type:`snapshot`}}}function createHandle(e,t){return{session:buildSandboxSession(createVercelInternalSandboxSession(e,t),createVercelNetworkPolicySetter(e)),useSessionFn:async r=>(r!==void 0&&await e.update(r),buildSandboxSession(createVercelInternalSandboxSession(e,t),createVercelNetworkPolicySetter(e))),async captureState(){return{backendName:`vercel`,metadata:{sandboxName:e.name},sessionKey:t}},async dispose(){}}}function createVercelNetworkPolicySetter(e){return async t=>{await e.update({networkPolicy:t})}}function createVercelInternalSandboxSession(e,n){return{id:n,resolvePath:resolveVercelSandboxPath,async spawn(n){return adaptVercelCommandToSandboxProcess(await e.runCommand({args:[`-lc`,n.command],cmd:`bash`,cwd:n.workingDirectory??WORKSPACE_ROOT,detached:!0,env:n.env,signal:n.abortSignal}))},async readFile(t){return await e.readFile({path:t.path})??null},async writeFile(t){let n=await streamToBuffer(t.content);await e.writeFiles([{content:n,path:t.path}])},async removePath(t){await e.fs.rm(t.path,{force:t.force,recursive:t.recursive,signal:t.abortSignal})}}}function adaptVercelCommandToSandboxProcess(e){let t=new TextEncoder,n,r,i=!1,a,o=new ReadableStream({start(e){n=e}}),s=new ReadableStream({start(e){r=e}});return(async()=>{try{for await(let i of e.logs()){let e=t.encode(i.data);i.stream===`stdout`?n?.enqueue(e):r?.enqueue(e)}}catch(e){a=e,n?.error(e),r?.error(e)}finally{i=!0,a===void 0&&(n?.close(),r?.close())}})(),{stdout:o,stderr:s,async wait(){let t=await e.wait();for(;!i;)await new Promise(e=>setTimeout(e,0));if(a!==void 0)throw a;return{exitCode:t.exitCode}},async kill(){await e.kill()}}}function resolveVercelSandboxPath(e){return e.startsWith(`/`)?e:`${WORKSPACE_ROOT}/${e}`}async function ensureSandboxWorkingDirectory(e,n){await runSandboxBootstrapStep(e,{failureMessage:`Failed to initialize Vercel sandbox workspace.`,script:`mkdir -p ${WORKSPACE_ROOT} && chown ${SANDBOX_USER}:${SANDBOX_USER} ${WORKSPACE_ROOT}`}),n.networkPolicy!==`deny-all`&&await runSandboxBootstrapStep(e,{failureMessage:`Failed to install ripgrep in Vercel sandbox.`,script:`command -v rg >/dev/null 2>&1 || { dnf install -y spal-release && dnf install -y ripgrep; }`})}async function runSandboxBootstrapStep(e,t){let n=await e.runCommand({args:[`-lc`,t.script],cmd:`bash`,sudo:!0});if(n.exitCode!==0){let e=await n.stderr();throw Error(`${t.failureMessage} ${e}`.trim())}}const SANDBOX_USER=`vercel-sandbox`;async function getNamedSandbox(e,t){try{return await e.Sandbox.get({name:t})}catch(e){if(isSandboxMissingError(e))return null;throw Error(`Failed to look up Vercel sandbox "${t}": ${errorMessage(e)}`,{cause:e})}}function isSandboxMissingError(e){return e instanceof Error?(e.response?.status??e.cause?.response?.status)===404:!1}function extractAuthorSnapshotId(e){let t=e.source;if(t?.type===`snapshot`&&typeof t.snapshotId==`string`)return t.snapshotId}function getVercelSandboxName(e){let t=e?.sandboxName;return typeof t==`string`?t:void 0}function resolveVercelSandboxTags(e,t){let n={};if(e!==void 0)for(let[t,r]of Object.entries(e))n[t]=r;if(t!==void 0)for(let[e,r]of Object.entries(t))n[e]=r;let r=Object.keys(n).length;if(r!==0){if(r>VERCEL_SANDBOX_TAG_LIMIT)throw Error(`Vercel Sandbox supports at most ${VERCEL_SANDBOX_TAG_LIMIT} tags. Eve reserves "agent", "channel", and "sessionId"; remove or consolidate custom tags passed to vercelBackend().`);return n}}async function ensureVercelSandboxTags(e,t){t===void 0||areVercelSandboxTagsEqual(e.tags,t)||await e.update({tags:t})}function areVercelSandboxTagsEqual(e,t){let n=e??{},r=Object.entries(n),i=Object.entries(t);return r.length===i.length?i.every(([e,t])=>n[e]===t):!1}function errorMessage(e){return e instanceof Error?e.message:String(e)}const DEFAULT_SANDBOX_TIMEOUT_MS=1800*1e3,VERCEL_SANDBOX_TAG_LIMIT=5;export{createVercelSandboxBackend};

package/dist/src/execution/sandbox/ensure.d.ts

@@ -0,0 +1,27 @@
+import type { SandboxBackendTags } from "#public/definitions/sandbox-backend.js";
+import { type RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import type { RuntimeSandboxRegistry } from "#runtime/sandbox/registry.js";
+import type { SandboxAccess, SandboxState } from "#sandbox/state.js";
+/**
+ * Input for creating or reattaching the live sandbox for one step execution.
+ */
+export interface EnsureSandboxAccessInput {
+    readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
+    readonly nodeId: string;
+    readonly registry: RuntimeSandboxRegistry;
+    readonly sessionId: string;
+    readonly runOnSession?: (callback: () => Promise<void>) => Promise<void>;
+    readonly state: SandboxState | null;
+    readonly tags?: SandboxBackendTags;
+}
+/**
+ * Creates or reattaches the live sandbox from the compiled agent bundle's
+ * registry and persisted session state, returning a {@link SandboxAccess}
+ * suitable for the runtime context.
+ *
+ * Every agent has exactly one sandbox. The sandbox carries its own
+ * `SandboxBackend` value (resolved from the authored module or
+ * substituted with `defaultBackend()` when omitted), and the runtime
+ * simply calls `backend.create(...)`.
+ */
+export declare function ensureSandboxAccess(input: EnsureSandboxAccessInput): Promise<SandboxAccess>;

package/dist/src/execution/sandbox/ensure.js

@@ -0,0 +1 @@
+import{buildCallbackContext}from"#context/build-callback-context.js";import{getRuntimeCompiledArtifactsAppRoot}from"#runtime/compiled-artifacts-source.js";import{createRuntimeSandboxKeys}from"#runtime/sandbox/keys.js";import{createRuntimeSandboxTemplatePlan}from"#runtime/sandbox/template-plan.js";async function ensureSandboxAccess(n){let r=n.state?.initialized??!1,i=n.state?.session??null,a=getRuntimeCompiledArtifactsAppRoot(n.compiledArtifactsSource)??process.cwd(),o=n.registry.sandbox,s;function getHandle(){return s===void 0&&(s=createHandle().catch(e=>{throw s=void 0,e})),s}async function createHandle(){if(o===null)return null;let t=o.definition,s=t.backend,c=createRuntimeSandboxTemplatePlan({definition:t,workspaceResourceRoot:o.workspaceResourceRoot}),l=await createRuntimeSandboxKeys({backendName:s.name,compiledArtifactsSource:n.compiledArtifactsSource,nodeId:n.nodeId,sessionId:n.sessionId,sourceId:t.sourceId,templatePlan:c}),u=await s.create({existingMetadata:i?.backendName===s.name&&i.sessionKey===l.sessionKey?i.metadata:void 0,runtimeContext:{appRoot:a},sessionKey:l.sessionKey,tags:n.tags,templateKey:l.templateKey});return r||=(await runOnSession(async()=>{await t.onSession?.({ctx:buildCallbackContext(),use:u.useSessionFn})}),!0),u}async function runOnSession(e){if(n.runOnSession!==void 0){await n.runOnSession(e);return}await e()}return{async captureState(){if(s!==void 0){let e=await s;e!==null&&(i=await e.captureState())}return{initialized:r,session:i}},async dispose(){s!==void 0&&await(await s)?.dispose()},async get(){return(await getHandle())?.session??null}}}export{ensureSandboxAccess};

package/dist/src/execution/sandbox/glob-tool.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/**
+ * Typed input accepted by {@link executeGlobOnSandbox}.
+ */
+export interface GlobInput {
+    readonly limit?: number;
+    readonly path?: string;
+    readonly pattern: string;
+}
+/**
+ * Structured result returned from {@link executeGlobOnSandbox}.
+ */
+export interface GlobResult {
+    readonly content: string;
+    readonly count: number;
+    readonly path: string;
+    readonly truncated: boolean;
+}
+/**
+ * Searches for files matching a glob pattern inside the sandbox.
+ */
+export declare function executeGlobOnSandbox(sandbox: SandboxSession, args: GlobInput): Promise<GlobResult>;

package/dist/src/execution/sandbox/glob-tool.js

@@ -0,0 +1,3 @@
+import{MAX_OUTPUT_BYTES}from"#execution/sandbox/truncate-output.js";import{shellQuote}from"#execution/sandbox/shell-quote.js";import{normalizeModelPath}from"#runtime/framework-tools/file-state.js";import{validateAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{ripgrepIsAvailable}from"#execution/sandbox/ripgrep-probe.js";async function executeGlobOnSandbox(t,a){let o=a.path??`/workspace`;validateAbsoluteFilePath(o);let s=normalizeModelPath(o),c=Math.min(Math.max(1,a.limit??100),1e3),l=await ripgrepIsAvailable(t)?buildRipgrepCommand({normalizedPath:s,pattern:a.pattern}):buildPosixFindCommand({normalizedPath:s,pattern:a.pattern}),u=await t.run({command:l});if(u.exitCode!==0&&u.exitCode!==1)throw buildGlobExecutionError(l,u.exitCode,u.stderr);let d=u.stdout.split(`
+`).filter(e=>e.length>0),f=d.length>c,p=f?d.slice(0,c):d,m=[],h=0,g=!1;for(let t of p){let r=normalizeModelPath(t),i=Buffer.byteLength(r,`utf8`)+1;if(h+i>MAX_OUTPUT_BYTES&&m.length>0){g=!0;break}m.push(r),h+=i}if(m.length===0)return{content:`No files found`,count:0,path:s,truncated:!1};let _=f||g,v=[...m];return _&&(v.push(``),v.push(`(Results truncated: showing first ${m.length} results out of more. Use a more specific path or pattern to narrow results.)`)),{content:v.join(`
+`),count:m.length,path:s,truncated:_}}function buildRipgrepCommand(e){return[`rg --files --hidden`,`--glob '!.git/*'`,`--glob ${shellQuote(e.pattern)}`,`-- ${shellQuote(e.normalizedPath)}`].join(` `)}function buildPosixFindCommand(e){let n=translateGlobToFindPattern(e.pattern),r=n.includes(`/`)?`-path ${shellQuote(`*/${n}`)}`:`-name ${shellQuote(n)}`;return[`find ${shellQuote(e.normalizedPath)}`,`-type f`,`-not -path '*/.git/*'`,r].join(` `)}function translateGlobToFindPattern(e){let t=e.replaceAll(`**`,`*`);for(;t.startsWith(`*/`);)t=t.slice(2);return t}function buildGlobExecutionError(e,t,n){let r=n.trim(),i=r.length>0?r:`no stderr output`;return Error(`glob failed (exit ${t}): ${i}\nCommand: ${e}`)}export{executeGlobOnSandbox};

package/dist/src/execution/sandbox/grep-tool.d.ts

@@ -0,0 +1,26 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/**
+ * Typed input accepted by {@link executeGrepOnSandbox}.
+ */
+export interface GrepInput {
+    readonly context?: number;
+    readonly glob?: string;
+    readonly ignoreCase?: boolean;
+    readonly limit?: number;
+    readonly literal?: boolean;
+    readonly path?: string;
+    readonly pattern: string;
+}
+/**
+ * Structured result returned from {@link executeGrepOnSandbox}.
+ */
+export interface GrepResult {
+    readonly content: string;
+    readonly matchCount: number;
+    readonly path: string;
+    readonly truncated: boolean;
+}
+/**
+ * Searches file contents for a pattern inside the sandbox.
+ */
+export declare function executeGrepOnSandbox(sandbox: SandboxSession, args: GrepInput): Promise<GrepResult>;

package/dist/src/execution/sandbox/grep-tool.js

@@ -0,0 +1,3 @@
+import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{shellQuote}from"#execution/sandbox/shell-quote.js";import{normalizeModelPath}from"#runtime/framework-tools/file-state.js";import{validateAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{ripgrepIsAvailable}from"#execution/sandbox/ripgrep-probe.js";async function executeGrepOnSandbox(e,t){let n=t.path??`/workspace`;validateAbsoluteFilePath(n);let o=normalizeModelPath(n),s=Math.min(Math.max(1,t.limit??100),1e3),c=t.context!==void 0&&t.context>0?t.context:0,l=await ripgrepIsAvailable(e)?buildRipgrepCommand({contextLines:c,effectiveLimit:s,glob:t.glob,ignoreCase:t.ignoreCase??!1,literal:t.literal??!1,normalizedPath:o,pattern:t.pattern}):buildPosixGrepCommand({contextLines:c,effectiveLimit:s,glob:t.glob,ignoreCase:t.ignoreCase??!1,literal:t.literal??!1,normalizedPath:o,pattern:t.pattern}),u=await e.run({command:l});if(u.exitCode!==0&&u.exitCode!==1)throw buildGrepExecutionError(l,u.exitCode,u.stderr);let d=u.stdout;return d.trim().length===0?{content:`No matches found`,matchCount:0,path:o,truncated:!1}:processOutput({effectiveLimit:s,normalizedPath:o,stdout:d})}function buildRipgrepCommand(e){let t=[`rg`,`--line-number`,`--color=never`,`--hidden`,`--glob '!.git/*'`];return e.ignoreCase&&t.push(`--ignore-case`),e.literal&&t.push(`--fixed-strings`),e.glob!==void 0&&t.push(`--glob ${shellQuote(e.glob)}`),e.contextLines>0&&t.push(`--context ${e.contextLines}`),t.push(`--max-count ${e.effectiveLimit}`),t.push(`--`),t.push(shellQuote(e.pattern)),t.push(shellQuote(e.normalizedPath)),t.join(` `)}function buildPosixGrepCommand(e){let t=[`grep`,`-r`,`-n`,`--color=never`,`--exclude-dir=.git`];return e.ignoreCase&&t.push(`-i`),e.literal?t.push(`-F`):t.push(`-E`),e.glob!==void 0&&t.push(`--include=${shellQuote(e.glob)}`),e.contextLines>0&&t.push(`-C ${e.contextLines}`),t.push(`-m ${e.effectiveLimit}`),t.push(`--`),t.push(shellQuote(e.pattern)),t.push(shellQuote(e.normalizedPath)),t.join(` `)}function processOutput(n){let r=n.stdout.split(`
+`),i=[],a=0,o=0,s=!1;for(let n of r){if(n.length===0&&r.indexOf(n)===r.length-1)continue;n!==`--`&&n.length>0&&/^.+:\d+:/.test(n)&&o++;let c=capLineLength(n),l=Buffer.byteLength(c,`utf8`)+1;if(a+l>MAX_OUTPUT_BYTES&&i.length>0){s=!0;break}i.push(c),a+=l}let c=s||o>=n.effectiveLimit,l=i.join(`
+`);if(c){let e=[];o>=n.effectiveLimit&&e.push(`Match limit reached (${n.effectiveLimit}). Use a larger limit or more specific pattern.`),s&&e.push(`Output truncated due to size. Use a more specific path or pattern.`),l+=`\n\n[${e.join(` `)}]`}return{content:l,matchCount:o,path:n.normalizedPath,truncated:c}}function buildGrepExecutionError(e,t,n){let r=n.trim(),i=r.length>0?r:`no stderr output`;return Error(`grep failed (exit ${t}): ${i}\nCommand: ${e}`)}export{executeGrepOnSandbox};

package/dist/src/execution/sandbox/lazy-backend.d.ts

@@ -0,0 +1,15 @@
+import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+/**
+ * Wraps a backend-producing function in a `SandboxBackend` proxy that
+ * invokes the function exactly once, on first access to any of `.name`,
+ * `.create`, or `.prewarm`. Subsequent accesses return the same cached
+ * underlying backend.
+ *
+ * Used by `defaultBackend()` for env-conditional selection, and by the
+ * authored-definition normalizer when an author passes a callback to
+ * `SandboxDefinition.backend` (e.g. `backend: () => vercelBackend({...})`)
+ * so the factory runs at first use rather than at module load — while
+ * still preserving backend-internal state (such as the Vercel backend's
+ * prewarmed-templates map) across every framework call.
+ */
+export declare function lazyBackend<BO, SO>(factory: () => SandboxBackend<BO, SO>): SandboxBackend<BO, SO>;

package/dist/src/execution/sandbox/lazy-backend.js

@@ -0,0 +1 @@
+function lazyBackend(e){let t;function resolve(){return t===void 0&&(t=e()),t}return{get name(){return resolve().name},create(e){return resolve().create(e)},prewarm(e){return resolve().prewarm(e)}}}export{lazyBackend};

package/dist/src/execution/sandbox/prewarm.d.ts

@@ -0,0 +1,57 @@
+import type { SandboxBackend, SandboxBackendPrewarmInput, SandboxBackendPrewarmResult } from "#public/definitions/sandbox-backend.js";
+import { type RuntimeCompiledArtifactsSource, type RuntimeDiskCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { type ResolvedAgentGraphBundle } from "#runtime/graph.js";
+/**
+ * Optional dispatch override that intercepts every `backend.prewarm`
+ * call. Production code never supplies this; the orchestrator dispatches
+ * directly to the backend. Tests inject a recorder to verify which
+ * templates the orchestrator emits and what bootstrap calls flow through
+ * them.
+ */
+export type SandboxBackendPrewarmDispatch = (input: {
+    readonly backend: SandboxBackend;
+    readonly input: SandboxBackendPrewarmInput;
+}) => Promise<SandboxBackendPrewarmResult>;
+interface PrewarmSandboxesInput {
+    readonly appRoot: string;
+    readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
+    readonly graph: ResolvedAgentGraphBundle;
+    readonly log?: (message: string) => void;
+    readonly dispatch?: SandboxBackendPrewarmDispatch;
+}
+/**
+ * Prewarms every backend sandbox template required by one compiled
+ * runtime graph.
+ *
+ * Iterates every registered sandbox and invokes `backend.prewarm(...)`
+ * for each backend template.
+ */
+export declare function prewarmSandboxes(input: PrewarmSandboxesInput): Promise<void>;
+/**
+ * Loads the compiled runtime graph for one authored app root and
+ * prewarms every backend's sandbox templates required by that graph.
+ *
+ * Hydrates the module map directly from authored source so callers
+ * don't need a pre-existing `module-map.mjs` import in Node's cache.
+ * Shared entrypoint for `eve dev` startup, the dev watcher, and the
+ * Vercel build hook.
+ */
+export declare function prewarmAppSandboxes(input: {
+    readonly appRoot: string;
+    readonly compiledArtifactsSource?: RuntimeCompiledArtifactsSource;
+    readonly loadAgentGraph?: (input: Readonly<{
+        compiledArtifactsSource: RuntimeDiskCompiledArtifactsSource;
+    }>) => Promise<ResolvedAgentGraphBundle>;
+    readonly log?: (message: string) => void;
+    readonly dispatch?: SandboxBackendPrewarmDispatch;
+}): Promise<void>;
+/**
+ * Loads one built app's bundled compiled artifacts and prewarms the sandbox
+ * templates that its production Nitro runtime will request.
+ */
+export declare function prewarmBuiltAppSandboxes(input: {
+    readonly appRoot: string;
+    readonly log?: (message: string) => void;
+    readonly dispatch?: SandboxBackendPrewarmDispatch;
+}): Promise<void>;
+export {};

package/dist/src/execution/sandbox/prewarm.js

@@ -0,0 +1 @@
+import{toErrorMessage}from"#shared/errors.js";import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{createBundledRuntimeCompiledArtifactsSource}from"#runtime/compiled-artifacts-source.js";import{createRuntimeSandboxTemplateKey}from"#runtime/sandbox/keys.js";import{createRuntimeSandboxTemplatePlan}from"#runtime/sandbox/template-plan.js";import{loadCompiledModuleMapFromAuthoredSource}from"#internal/authored-module-map-loader.js";import{createAuthoredSourceRuntimeCompiledArtifactsSource}from"#internal/application/runtime-compiled-artifacts-source.js";import{loadCompileMetadata}from"#runtime/loaders/compile-metadata.js";import{withBundledCompiledArtifacts}from"#runtime/loaders/bundled-artifacts.js";import{loadCompiledManifest}from"#runtime/loaders/manifest.js";import{resolveRuntimeCompilerArtifactPaths}from"#runtime/loaders/artifact-paths.js";import{resolveRuntimeAgentGraph}from"#runtime/resolve-agent-graph.js";import{materializeWorkspaceDirectory}from"#runtime/workspace/seed-files.js";async function prewarmSandboxes(t){let n=await collectPrewarmTargets(t);if(n.length===0)return;t.log?.(`Eve: initializing ${n.length} sandbox ${pluralize(n.length,`template`)}...`);let r=t.dispatch??(async({backend:e,input:t})=>await e.prewarm(t)),i=0;await Promise.all(n.map(async({backend:n,label:a,input:o})=>{t.log?.(`Eve: initializing sandbox template "${a}"...`);let s;try{s=await r({backend:n,input:o})}catch(r){throw t.log?.(`Eve: failed to initialize sandbox template "${a}" on backend "${n.name}": ${toErrorMessage(r)}`),r}s.reused?(i+=1,t.log?.(`Eve: reused cached sandbox template "${a}".`)):t.log?.(`Eve: built sandbox template "${a}".`)})),t.log?.(`Eve: initialized ${n.length} sandbox ${pluralize(n.length,`template`)} (${i} reused, ${n.length-i} built).`)}async function prewarmAppSandboxes(e){let t=e.compiledArtifactsSource??createAuthoredSourceRuntimeCompiledArtifactsSource(e.appRoot);if(t.kind!==`disk`)throw Error(`prewarmAppSandboxes requires disk-backed compiled artifacts.`);let n=await(e.loadAgentGraph??loadGraphFromArtifacts)({compiledArtifactsSource:t});await prewarmSandboxes({appRoot:t.appRoot,compiledArtifactsSource:t,dispatch:e.dispatch,graph:n,log:e.log})}async function prewarmBuiltAppSandboxes(e){let t=createAuthoredSourceRuntimeCompiledArtifactsSource(e.appRoot),[r,i,u]=await Promise.all([loadCompileMetadata({compiledArtifactsSource:t}),loadCompiledManifest({compiledArtifactsSource:t}),loadCompiledModuleMapFromAuthoredSource({compiledArtifactsSource:t})]);await withBundledCompiledArtifacts({manifest:i,metadata:r??void 0,moduleMap:u,sessionId:`built-app-prewarm`},async()=>{let t=createBundledRuntimeCompiledArtifactsSource(),r=await resolveRuntimeAgentGraph({manifest:i,moduleMap:u});await prewarmSandboxes({appRoot:e.appRoot,compiledArtifactsSource:t,dispatch:e.dispatch,graph:r,log:e.log})})}async function collectPrewarmTargets(e){let t=resolveRuntimeCompilerArtifactPaths(e.appRoot).compileDirectoryPath,n={appRoot:e.appRoot},a=[];return await Promise.all(collectNodeSandboxes(e.graph).map(async({definition:o,nodeId:s,workspaceResourceRoot:c})=>{let l=createRuntimeSandboxTemplatePlan({definition:o,workspaceResourceRoot:c}),u=await createRuntimeSandboxTemplateKey({backendName:o.backend.name,compiledArtifactsSource:e.compiledArtifactsSource,nodeId:s,sourceId:o.sourceId,templatePlan:l});u!==null&&a.push({backend:o.backend,label:formatLabel(s),input:{bootstrap:o.bootstrap,seedFiles:await loadResourceRootSeedFiles({compileDirectoryPath:t,workspaceResourceRoot:c}),runtimeContext:n,templateKey:u}})})),a.sort((e,t)=>e.label.localeCompare(t.label))}async function loadResourceRootSeedFiles(e){return e.workspaceResourceRoot.rootEntries.length===0?[]:(await materializeWorkspaceDirectory(`${e.compileDirectoryPath}/${e.workspaceResourceRoot.logicalPath}`)).map(e=>({content:e.content,path:e.path}))}async function loadGraphFromArtifacts(e){let[t,n]=await Promise.all([loadCompiledManifest({compiledArtifactsSource:e.compiledArtifactsSource}),loadCompiledModuleMapFromAuthoredSource({compiledArtifactsSource:e.compiledArtifactsSource})]);return await resolveRuntimeAgentGraph({manifest:t,moduleMap:n})}function collectNodeSandboxes(e){return[...e.nodesByNodeId.entries()].flatMap(([e,t])=>{let n=t.sandboxRegistry.sandbox;return n===null?[]:[{...n,nodeId:e}]})}function pluralize(e,t){return e===1?t:`${t}s`}function formatLabel(e){return e===ROOT_RUNTIME_AGENT_NODE_ID?`root`:e}export{prewarmAppSandboxes,prewarmBuiltAppSandboxes,prewarmSandboxes};

package/dist/src/execution/sandbox/read-file-tool.d.ts

@@ -0,0 +1,28 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/**
+ * Typed input accepted by {@link executeReadFileOnSandbox}.
+ */
+export interface ReadFileInput {
+    readonly filePath: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/**
+ * Structured result returned from {@link executeReadFileOnSandbox}.
+ */
+export interface ReadFileResult {
+    readonly content: string;
+    readonly nextOffset?: number;
+    readonly path: string;
+    readonly totalLines: number;
+    readonly truncated: boolean;
+}
+/**
+ * Reads one text file from the sandbox, applies output shaping
+ * (offset, limit, line numbering, truncation), and persists a full-file
+ * stamp into durable read-file state for stale-write detection.
+ *
+ * Used by the framework `read_file` tool and by author tools constructed
+ * via `defineReadFileTool`.
+ */
+export declare function executeReadFileOnSandbox(sandbox: SandboxSession, args: ReadFileInput): Promise<ReadFileResult>;

package/dist/src/execution/sandbox/read-file-tool.js

@@ -0,0 +1,3 @@
+import{loadContext}from"#context/container.js";import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{buildReadFileTargetKey,createReadFileStamp,normalizeModelPath,setReadFileStamp}from"#runtime/framework-tools/file-state.js";import{validateAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";async function executeReadFileOnSandbox(r,i){let{filePath:a,offset:o,limit:s}=i;validateAbsoluteFilePath(a);let c=normalizeModelPath(a),l=o??1,u=s??2e3;if(l<1)throw Error(`offset must be >= 1. Received: ${l}.`);let d=await r.readTextFile({path:a});if(d===null)throw Error(`File not found: ${a}. Verify the path exists and is accessible in the sandbox.`);if(d.includes(`\0`))throw Error(`File "${a}" contains NUL bytes and appears to be a binary file. read_file only supports text files.`);let f=d.split(`
+`),p=f.length>0&&f[f.length-1]===``?f.length-1:f.length;if(p===0){if(l>1)throw Error(`offset ${l} is past the end of the file (0 lines). Use the default offset to read an empty file.`);return{content:``,path:c,totalLines:0,truncated:!1}}if(l>p)throw Error(`offset ${l} is past the end of the file (${p} lines).`);let m=createReadFileStamp({content:d,filePath:c}),h=buildReadFileTargetKey(c);setReadFileStamp(loadContext(),h,m);let g=l-1,_=Math.min(g+u,p),v=f.slice(g,_),y=[],b=0,x=!1;for(let e=0;e<v.length;e++){let t=`${l+e}: ${capLineLength(v[e]??``)}`,n=Buffer.byteLength(t,`utf8`)+1;if(b+n>MAX_OUTPUT_BYTES&&y.length>0){x=!0;break}y.push(t),b+=n}let S=y.join(`
+`),C=l+y.length-1;return C<p||x?{content:S,nextOffset:C+1,path:c,totalLines:p,truncated:!0}:{content:S,path:c,totalLines:p,truncated:!1}}export{executeReadFileOnSandbox};

package/dist/src/execution/sandbox/require-sandbox.d.ts

@@ -0,0 +1,15 @@
+import type { SandboxSession } from "#public/definitions/sandbox.js";
+/**
+ * Resolves the active sandbox session from the runtime context.
+ *
+ * Shared preamble for every sandbox-backed tool executor (`bash`,
+ * `read_file`, `write_file`, `glob`, `grep`). Centralizes the context
+ * lookup, null checks, and error messages so each executor does not
+ * duplicate them.
+ */
+export declare function requireSandboxSession(): Promise<SandboxSession>;
+/**
+ * Validates that a model-supplied file path is absolute. Throws a
+ * descriptive error when the path does not start with `/`.
+ */
+export declare function validateAbsoluteFilePath(filePath: string): void;

package/dist/src/execution/sandbox/require-sandbox.js

@@ -0,0 +1 @@
+import{SandboxKey}from"#context/keys.js";import{loadContext}from"#context/container.js";async function requireSandboxSession(){let t=loadContext().get(SandboxKey);if(t===void 0)throw Error(`This tool requires sandbox access on the runtime context. Ensure the step is running inside a managed runtime context with sandbox support.`);let n=await t.get();if(n===null)throw Error(`The sandbox is not available in the current runtime context.`);return n}function validateAbsoluteFilePath(e){if(!e.startsWith(`/`))throw Error(`filePath must be an absolute path. Received: "${e}". Use an absolute path such as /workspace/foo.ts.`)}export{requireSandboxSession,validateAbsoluteFilePath};

package/dist/src/execution/sandbox/ripgrep-probe.d.ts

@@ -0,0 +1,9 @@
+import type { SandboxSession } from "#public/definitions/sandbox.js";
+/**
+ * Returns `true` when `rg` is on PATH in the given sandbox session,
+ * `false` otherwise. Result is cached per session.
+ *
+ * Framework `grep` and `glob` tools call this to decide whether to use
+ * ripgrep or the POSIX `grep`/`find` fallback.
+ */
+export declare function ripgrepIsAvailable(session: SandboxSession): Promise<boolean>;

package/dist/src/execution/sandbox/ripgrep-probe.js

@@ -0,0 +1 @@
+const probes=new Map;async function ripgrepIsAvailable(t){let n=probes.get(t.id);if(n!==void 0)return n;let r=runProbe(t);probes.set(t.id,r);try{return await r}catch{return probes.delete(t.id),!1}}async function runProbe(e){return(await e.run({command:`command -v rg >/dev/null 2>&1`})).exitCode===0}export{ripgrepIsAvailable};

package/dist/src/execution/sandbox/session.d.ts

@@ -0,0 +1,17 @@
+import type { InternalSandboxSession, SandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+export type { InternalSandboxSession };
+/**
+ * Builds a public {@link SandboxSession} from backend-specific primitives.
+ *
+ * Encoding handling, line-range slicing, and the binary/text/stream
+ * variants live here so each backend only has to implement byte-oriented
+ * read/write primitives. `run` is implemented as a thin wrapper over the
+ * backend's `spawn`: collect stdout/stderr to strings, await `wait()`,
+ * then return the combined result.
+ *
+ * `setNetworkPolicy` applies a firewall policy to the live sandbox. It
+ * defaults to a no-op so backends without a firewall (and test doubles)
+ * need not supply one; the Vercel backend wires it to `sandbox.update`.
+ */
+export declare function buildSandboxSession(primitives: InternalSandboxSession, setNetworkPolicy?: (policy: SandboxNetworkPolicy) => Promise<void>): SandboxSession;

package/dist/src/execution/sandbox/session.js

@@ -0,0 +1,3 @@
+import{bufferToStream,streamToBuffer}from"./stream-utils.js";function buildSandboxSession(n,r=async()=>{}){async function run(e){let t=await n.spawn(e),[r,i,{exitCode:a}]=await Promise.all([collectStreamToString(t.stdout),collectStreamToString(t.stderr),t.wait()]);return{exitCode:a,stderr:i,stdout:r}}return{id:n.id,resolvePath(e){return n.resolvePath(e)},run,async spawn(e){return await n.spawn(e)},async readFile(e){return await n.readFile({abortSignal:e.abortSignal,path:n.resolvePath(e.path)})},async readBinaryFile(e){let r=await n.readFile({abortSignal:e.abortSignal,path:n.resolvePath(e.path)});return r===null?null:await streamToBuffer(r)},async readTextFile(e){validateReadTextFileOptions(e);let r=await n.readFile({abortSignal:e.abortSignal,path:n.resolvePath(e.path)});return r===null?null:applyLineRange(decodeBytes(await streamToBuffer(r),e.encoding??`utf-8`),e)},async writeFile(e){await n.writeFile({abortSignal:e.abortSignal,content:e.content,path:n.resolvePath(e.path)})},async writeBinaryFile(t){await n.writeFile({abortSignal:t.abortSignal,content:bufferToStream(t.content),path:n.resolvePath(t.path)})},async writeTextFile(t){let r=encodeString(t.content,t.encoding??`utf-8`);await n.writeFile({abortSignal:t.abortSignal,content:bufferToStream(r),path:n.resolvePath(t.path)})},async removePath(e){await n.removePath({abortSignal:e.abortSignal,force:e.force,path:n.resolvePath(e.path),recursive:e.recursive})},setNetworkPolicy:r}}async function collectStreamToString(e){let n=await streamToBuffer(e);return new TextDecoder().decode(n)}function validateReadTextFileOptions(e){let{startLine:t,endLine:n}=e;if(t!==void 0&&(!Number.isInteger(t)||t<1))throw Error(`startLine must be a positive integer (1-based).`);if(n!==void 0&&(!Number.isInteger(n)||n<1))throw Error(`endLine must be a positive integer (1-based).`);if(t!==void 0&&n!==void 0&&t>n)throw Error(`startLine must not be greater than endLine.`)}function splitLinesPreservingEndings(e){let t=[],n=0;for(let r=0;r<e.length;r++)e[r]===`\r`?r+1<e.length&&e[r+1]===`
+`?(t.push(e.slice(n,r+2)),n=r+2,r++):(t.push(e.slice(n,r+1)),n=r+1):e[r]===`
+`&&(t.push(e.slice(n,r+1)),n=r+1);return n<e.length&&t.push(e.slice(n)),t}function applyLineRange(e,t){if(t.startLine===void 0&&t.endLine===void 0)return e;let n=splitLinesPreservingEndings(e),r=n.length,i=t.startLine??1,a=Math.min(t.endLine??r,r);return i>r?``:n.slice(i-1,a).join(``)}function decodeBytes(e,t){return t===`utf-8`||t===`utf8`?new TextDecoder(`utf-8`,{fatal:!0}).decode(e):Buffer.from(e.buffer,e.byteOffset,e.byteLength).toString(t)}function encodeString(e,t){return t===`utf-8`||t===`utf8`?new TextEncoder().encode(e):Buffer.from(e,t)}export{buildSandboxSession};

package/dist/src/execution/sandbox/shell-quote.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wraps a value in POSIX single-quotes, escaping any embedded single-quotes.
+ *
+ * Used by the `glob` and `grep` execution cores to safely embed model-supplied
+ * patterns, paths, and globs into shell commands run via `sandbox.run`.
+ *
+ * The quoting strategy is the standard POSIX approach: wrap the value in
+ * single-quotes and replace each embedded `'` with `'\''` (end the
+ * single-quoted string, insert an escaped single-quote, re-open
+ * single-quoting).
+ */
+export declare function shellQuote(value: string): string;

package/dist/src/execution/sandbox/shell-quote.js

@@ -0,0 +1 @@
+function shellQuote(e){return`'${e.replace(/'/g,`'\\''`)}'`}export{shellQuote};

package/dist/src/execution/sandbox/stream-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Collects all chunks of a `ReadableStream<Uint8Array>` into a single
+ * Buffer.
+ */
+export declare function streamToBuffer(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
+/**
+ * Wraps a byte buffer as a single-chunk `ReadableStream<Uint8Array>`.
+ */
+export declare function bufferToStream(buf: Uint8Array): ReadableStream<Uint8Array>;

package/dist/src/execution/sandbox/stream-utils.js

@@ -0,0 +1 @@
+async function streamToBuffer(e){let t=[];for await(let n of e)t.push(n);return Buffer.concat(t)}function bufferToStream(e){return new ReadableStream({start(t){t.enqueue(e),t.close()}})}export{bufferToStream,streamToBuffer};

package/dist/src/execution/sandbox/truncate-output.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared output truncation utilities for framework tool executors.
+ *
+ * Every framework tool that can return unbounded text output (bash,
+ * grep, glob, read_file, web_fetch) uses these helpers to enforce
+ * consistent size limits inside its executor before the result enters
+ * conversation history. Authored tools are expected to do the same —
+ * bounding at the source keeps the contract simple: whatever `execute`
+ * returns is what the model sees.
+ */
+/**
+ * Maximum number of lines kept after truncation.
+ */
+export declare const MAX_OUTPUT_LINES = 2000;
+/**
+ * Maximum byte size of the truncated output.
+ */
+export declare const MAX_OUTPUT_BYTES: number;
+/**
+ * Maximum length of a single line before it is truncated.
+ */
+export declare const MAX_LINE_LENGTH = 2000;
+/**
+ * Suffix appended to lines exceeding {@link MAX_LINE_LENGTH}.
+ */
+export declare const LINE_TRUNCATION_SUFFIX = " [truncated]";
+/**
+ * Result of a {@link truncateTail} or {@link truncateHead} call.
+ */
+export interface TruncationResult {
+    /** The truncated output text. */
+    readonly output: string;
+    /** True when the output was shortened. */
+    readonly truncated: boolean;
+    /** Total number of lines in the original input. */
+    readonly totalLines: number;
+    /** Number of lines included in the truncated output. */
+    readonly outputLines: number;
+}
+/**
+ * Keeps the **first** lines of `text` that fit within the line and byte
+ * budgets. This is the default shape of tool-result truncation — most
+ * tool output (file contents, grep results, web fetches) is more
+ * informative at the beginning.
+ *
+ * Each included line is individually capped at {@link MAX_LINE_LENGTH}
+ * characters. Iteration starts from the beginning and stops when either
+ * the line count reaches {@link MAX_OUTPUT_LINES} or cumulative byte
+ * size would exceed {@link MAX_OUTPUT_BYTES}.
+ */
+export declare function truncateHead(text: string): TruncationResult;
+/**
+ * Keeps the **last** lines of `text` that fit within the line and byte
+ * budgets. Useful for bash output where errors and results appear at
+ * the end.
+ *
+ * Each included line is individually capped at {@link MAX_LINE_LENGTH}
+ * characters. Iteration starts from the end and stops when either the
+ * line count reaches {@link MAX_OUTPUT_LINES} or cumulative byte size
+ * would exceed {@link MAX_OUTPUT_BYTES}.
+ */
+export declare function truncateTail(text: string): TruncationResult;
+/**
+ * Caps a single line at {@link MAX_LINE_LENGTH} characters, appending
+ * {@link LINE_TRUNCATION_SUFFIX} when truncated.
+ *
+ * Exported for tools that build their own output line-by-line (e.g.
+ * `read_file` prepends line numbers, `grep` counts matches) so they
+ * share the same per-line cap as {@link truncateHead} / {@link truncateTail}
+ * without re-implementing the slice+suffix pattern.
+ */
+export declare function capLineLength(line: string): string;

package/dist/src/execution/sandbox/truncate-output.js

@@ -0,0 +1,3 @@
+const MAX_OUTPUT_LINES=2e3,MAX_OUTPUT_BYTES=50*1024,MAX_LINE_LENGTH=2e3,LINE_TRUNCATION_SUFFIX=` [truncated]`;function truncateHead(e){return truncateByDirection(e,`head`)}function truncateTail(e){return truncateByDirection(e,`tail`)}function truncateByDirection(e,t){let n=e.split(`
+`),r=countLogicalLines(n),i=t===`head`,a=[],o=0,s=i?0:n.length-1,c=i?1:-1;for(let e=s;e>=0&&e<n.length&&a.length<2e3;e+=c){let t=capLineLength(n[e]??``),r=Buffer.byteLength(t,`utf8`)+1;if(o+r>51200&&a.length>0)break;a.push(t),o+=r}return i||a.reverse(),{output:a.join(`
+`),outputLines:a.length,totalLines:r,truncated:a.length<r}}function capLineLength(e){return e.length<=2e3?e:e.slice(0,MAX_LINE_LENGTH)+LINE_TRUNCATION_SUFFIX}function countLogicalLines(e){return e.length>0&&e[e.length-1]===``?e.length-1:e.length}export{LINE_TRUNCATION_SUFFIX,MAX_LINE_LENGTH,MAX_OUTPUT_BYTES,MAX_OUTPUT_LINES,capLineLength,truncateHead,truncateTail};

package/dist/src/execution/sandbox/write-file-tool.d.ts

@@ -0,0 +1,23 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/**
+ * Typed input accepted by {@link executeWriteFileOnSandbox}.
+ */
+export interface WriteFileInput {
+    readonly content: string;
+    readonly filePath: string;
+}
+/**
+ * Structured result returned from {@link executeWriteFileOnSandbox}.
+ */
+export interface WriteFileResult {
+    readonly existed: boolean;
+    readonly path: string;
+}
+/**
+ * Writes one text file to the sandbox with read-before-write
+ * enforcement and stale-read detection for existing files.
+ *
+ * Used by the framework `write_file` tool and by author tools
+ * constructed via `defineWriteFileTool`.
+ */
+export declare function executeWriteFileOnSandbox(sandbox: SandboxSession, args: WriteFileInput): Promise<WriteFileResult>;

package/dist/src/execution/sandbox/write-file-tool.js

@@ -0,0 +1 @@
+import{loadContext}from"#context/container.js";import{ReadFileStateKey,buildReadFileTargetKey,createReadFileStamp,normalizeModelPath,setReadFileStamp}from"#runtime/framework-tools/file-state.js";import{validateAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";async function executeWriteFileOnSandbox(e,t){let{filePath:n,content:r}=t;validateAbsoluteFilePath(n);let i=loadContext(),a=normalizeModelPath(n),o=buildReadFileTargetKey(a),s=await e.readTextFile({path:n});if(s===null)return await e.writeTextFile({content:r,path:n}),setReadFileStamp(i,o,createReadFileStamp({content:r,filePath:a})),{existed:!1,path:a};let c=i.ensure(ReadFileStateKey,()=>({byTarget:{}})).byTarget[o];if(c===void 0)throw Error(`You must read file ${n} before overwriting it. Use the read_file tool first.`);let l=createReadFileStamp({content:s,filePath:a});if(l.contentHash!==c.contentHash||l.byteLength!==c.byteLength)throw Error(`File ${n} has been modified since it was last read. Please read the file again before modifying it.`);return await e.writeTextFile({content:r,path:n}),setReadFileStamp(i,o,createReadFileStamp({content:r,filePath:a})),{existed:!0,path:a}}export{executeWriteFileOnSandbox};

package/dist/src/execution/session-callback-step.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sends the configured session terminal callback.
+ *
+ * Absence is a no-op. Once callback metadata is present, delivery is part of
+ * the remote delegation result path, so failures are logged and rethrown
+ * instead of being reported as a successful terminal step. Throwing is
+ * intentional: this function runs as a durable Workflow step, so rejection
+ * hands retry/failure policy back to the Workflow orchestrator rather than
+ * letting Eve falsely mark the callback delivery as complete.
+ */
+export declare function fireSessionCallbackStep(input: {
+    readonly error?: unknown;
+    readonly output?: unknown;
+    readonly serializedContext: Record<string, unknown>;
+    readonly status: "completed" | "failed";
+}): Promise<void>;

package/dist/src/execution/session-callback-step.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{SessionCallbackKey}from"#context/keys.js";import{toErrorMessage}from"#shared/errors.js";import{parseSessionCallback}from"#channel/session-callback.js";const log=createLogger(`execution.session-callback`);async function fireSessionCallbackStep(e){"use step";let n=e.serializedContext[`eve.sessionId`]??``,i=e.serializedContext[SessionCallbackKey.name];if(i!==void 0)try{let t=parseSerializedSessionCallback(i),r=e.status===`completed`?{callId:t.callId,kind:`session.completed`,output:e.output??``,sessionId:n,subagentName:t.subagentName}:{callId:t.callId,error:{code:`SESSION_FAILED`,message:toErrorMessage(e.error)},kind:`session.failed`,sessionId:n,subagentName:t.subagentName},a=await fetch(t.url,{body:JSON.stringify(r),headers:{"content-type":`application/json`},method:`POST`,redirect:`error`,signal:AbortSignal.timeout(3e4)});if(!a.ok)throw Error(`Session callback failed with HTTP ${a.status}.`)}catch(e){throw log.error(`failed to post session callback`,{error:e,sessionId:n}),e}}function parseSerializedSessionCallback(e){let t=parseSessionCallback(e);if(!t.ok)throw Error(`Serialized session callback is invalid.`,{cause:t.cause});return t.callback}export{fireSessionCallbackStep};