eve 0.82.0 → 0.83.1

package/dist/src/execution/sandbox/development-run.d.ts

@@ -1,7 +1,5 @@
 export declare const EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV = "EVE_DEVELOPMENT_SANDBOX_RUN_ID";
-export declare const EVE_DEVELOPMENT_SANDBOX_METADATA_PATH_TAG = "eve.metadataPath";
 export declare const EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG = "devRunId";
 export declare function createDevelopmentSandboxRunId(): string;
 export declare function getDevelopmentSandboxRunId(): string | undefined;
 export declare function withDevelopmentSandboxTags(tags: Readonly<Record<string, string>> | undefined): Readonly<Record<string, string>> | undefined;
-export declare function withDevelopmentSandboxMetadataPathTag(tags: Readonly<Record<string, string>> | undefined, metadataPath: string): Readonly<Record<string, string>> | undefined;

package/dist/src/execution/sandbox/development-run.js

@@ -1 +1 @@
-import{randomUUID}from"node:crypto";const EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV=`EVE_DEVELOPMENT_SANDBOX_RUN_ID`,EVE_DEVELOPMENT_SANDBOX_METADATA_PATH_TAG=`eve.metadataPath`,EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG=`devRunId`;function createDevelopmentSandboxRunId(){return randomUUID()}function getDevelopmentSandboxRunId(){let e=process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV];return e===void 0||e.trim()===``?void 0:e}function withDevelopmentSandboxTags(e){let t=getDevelopmentSandboxRunId();return t===void 0?e:{...e,[EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG]:t}}function withDevelopmentSandboxMetadataPathTag(e,t){return getDevelopmentSandboxRunId()===void 0?e:{...e,[EVE_DEVELOPMENT_SANDBOX_METADATA_PATH_TAG]:t}}export{EVE_DEVELOPMENT_SANDBOX_METADATA_PATH_TAG,EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV,EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG,createDevelopmentSandboxRunId,getDevelopmentSandboxRunId,withDevelopmentSandboxMetadataPathTag,withDevelopmentSandboxTags};
+import{randomUUID}from"node:crypto";const EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV=`EVE_DEVELOPMENT_SANDBOX_RUN_ID`,EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG=`devRunId`;function createDevelopmentSandboxRunId(){return randomUUID()}function getDevelopmentSandboxRunId(){let e=process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV];return e===void 0||e.trim()===``?void 0:e}function withDevelopmentSandboxTags(e){let t=getDevelopmentSandboxRunId();return t===void 0?e:{...e,[EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG]:t}}export{EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV,EVE_DEVELOPMENT_SANDBOX_RUN_ID_TAG,createDevelopmentSandboxRunId,getDevelopmentSandboxRunId,withDevelopmentSandboxTags};

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

@@ -18,7 +18,3 @@ export declare function buildSandboxDockerfile(input: {
     readonly dockerfile: SandboxDockerfile;
     readonly imageReference: string;
 }): Promise<void>;
-export declare function publishDockerImageForMicrosandbox(input: {
-    readonly cli: DockerCli;
-    readonly imageReference: string;
-}): Promise<string>;

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

@@ -1 +1 @@
-import{createHash,randomUUID}from"node:crypto";import{access,mkdir,rename,rm,writeFile}from"node:fs/promises";import{dirname,join}from"node:path";import{expectDockerSuccess}from"#execution/sandbox/bindings/docker-utils.js";async function materializeSandboxDockerfile(e){let t;try{t=await e.files.read(`Dockerfile`)}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return;throw e}let n=await e.files.list(),r=createHash(`sha256`),i=await Promise.all(n.map(async t=>({content:await e.files.read(t),path:t})));for(let e of i)r.update(e.path).update(`\0`).update(e.content).update(`\0`);let a=r.digest(`hex`),o=join(e.storagePath,`dockerfiles`,a);try{return await access(join(o,`Dockerfile`)),{contentHash:a,contextPath:o,path:join(o,`Dockerfile`)}}catch(e){if(!isFileNotFoundError(e))throw e}let s=`${o}.${randomUUID()}.tmp`;await Promise.all(i.map(async e=>{let t=join(s,e.path);await mkdir(dirname(t),{recursive:!0}),await writeFile(t,e.content)})),n.includes(`Dockerfile`)||(await mkdir(s,{recursive:!0}),await writeFile(join(s,`Dockerfile`),t)),await mkdir(dirname(o),{recursive:!0});try{await rename(s,o)}catch(e){try{await access(join(o,`Dockerfile`))}catch{throw e}}finally{await rm(s,{force:!0,recursive:!0})}return{contentHash:a,contextPath:o,path:join(o,`Dockerfile`)}}function dockerfileImageReference(e){return`eve-sandbox-dockerfile:${createHash(`sha256`).update(`${e.templateKey}:${e.dockerfile.contentHash}`).digest(`hex`).slice(0,24)}`}async function buildSandboxDockerfile(e){expectDockerSuccess(await e.cli.run([`build`,`--file`,e.dockerfile.path,`--tag`,e.imageReference,e.dockerfile.contextPath]),`build sandbox Dockerfile "${e.dockerfile.path}"`)}const LOCAL_REGISTRY_CONTAINER=`eve-sandbox-registry`,LOCAL_REGISTRY_HOST=`127.0.0.1:51921`;async function publishDockerImageForMicrosandbox(e){let t=await e.cli.run([`container`,`inspect`,`--format`,`{{.State.Running}}`,LOCAL_REGISTRY_CONTAINER]);t.exitCode===0?t.stdout.trim()!==`true`&&expectDockerSuccess(await e.cli.run([`start`,LOCAL_REGISTRY_CONTAINER]),`restart the local microsandbox image registry`):expectDockerSuccess(await e.cli.run([`run`,`--detach`,`--name`,LOCAL_REGISTRY_CONTAINER,`--publish`,`${LOCAL_REGISTRY_HOST}:5000`,`registry:2`]),`start the local microsandbox image registry`);let n=`${LOCAL_REGISTRY_HOST}/eve/${e.imageReference.replace(`:`,`-`)}`;return expectDockerSuccess(await e.cli.run([`tag`,e.imageReference,n]),`tag microsandbox image "${n}"`),expectDockerSuccess(await e.cli.run([`push`,n]),`publish microsandbox image "${n}"`),n}function isFileNotFoundError(e){return e instanceof Error&&`code`in e&&e.code===`ENOENT`}export{buildSandboxDockerfile,dockerfileImageReference,materializeSandboxDockerfile,publishDockerImageForMicrosandbox};
+import{createHash,randomUUID}from"node:crypto";import{access,mkdir,rename,rm,writeFile}from"node:fs/promises";import{dirname,join}from"node:path";import{expectDockerSuccess}from"#execution/sandbox/bindings/docker-utils.js";async function materializeSandboxDockerfile(e){let t;try{t=await e.files.read(`Dockerfile`)}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return;throw e}let n=await e.files.list(),r=createHash(`sha256`),i=await Promise.all(n.map(async t=>({content:await e.files.read(t),path:t})));for(let e of i)r.update(e.path).update(`\0`).update(e.content).update(`\0`);let a=r.digest(`hex`),o=join(e.storagePath,`dockerfiles`,a);try{return await access(join(o,`Dockerfile`)),{contentHash:a,contextPath:o,path:join(o,`Dockerfile`)}}catch(e){if(!isFileNotFoundError(e))throw e}let s=`${o}.${randomUUID()}.tmp`;await Promise.all(i.map(async e=>{let t=join(s,e.path);await mkdir(dirname(t),{recursive:!0}),await writeFile(t,e.content)})),n.includes(`Dockerfile`)||(await mkdir(s,{recursive:!0}),await writeFile(join(s,`Dockerfile`),t)),await mkdir(dirname(o),{recursive:!0});try{await rename(s,o)}catch(e){try{await access(join(o,`Dockerfile`))}catch{throw e}}finally{await rm(s,{force:!0,recursive:!0})}return{contentHash:a,contextPath:o,path:join(o,`Dockerfile`)}}function dockerfileImageReference(e){return`eve-sandbox-dockerfile:${createHash(`sha256`).update(`${e.templateKey}:${e.dockerfile.contentHash}`).digest(`hex`).slice(0,24)}`}async function buildSandboxDockerfile(e){expectDockerSuccess(await e.cli.run([`build`,`--file`,e.dockerfile.path,`--tag`,e.imageReference,e.dockerfile.contextPath]),`build sandbox Dockerfile "${e.dockerfile.path}"`)}function isFileNotFoundError(e){return e instanceof Error&&`code`in e&&e.code===`ENOENT`}export{buildSandboxDockerfile,dockerfileImageReference,materializeSandboxDockerfile};

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

@@ -1,28 +1,48 @@
 import { type RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
-import type { RuntimeSandboxRegistry } from "#runtime/sandbox/registry.js";
-import type { SandboxAccess, SandboxSessionEndReason, SandboxState } from "#sandbox/state.js";
-import { type SandboxProviderHandle } from "#shared/sandbox-provider.js";
+import { type RuntimeSandboxRegistry } from "#runtime/sandbox/registry.js";
+import { type SandboxAccess, type SandboxSessionEndReason, type SandboxState } from "#sandbox/state.js";
 interface EnsureSandboxAccessInput {
     readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
     readonly nodeId: string;
-    /** `false` when the sandbox outlives this access: it may not delete it, even after a failed start. */
+    /** `false` when the sandbox outlives this access: it may neither delete nor end it. */
     readonly ownsSandbox?: boolean;
     readonly registry: RuntimeSandboxRegistry;
     readonly sessionId: string;
     readonly state: SandboxState | null;
+    /**
+     * How long the server-shutdown registry, which holds one connection per
+     * session, keeps this access's connection. `"session"`, the default for a
+     * session's own steps, keeps a connection without `close()` after release,
+     * so shutdown still stops the session's sandbox. `"call"` drops it at
+     * release, for a keyed tool call, whose sandbox no session ends. `"none"`
+     * never registers it, for a workflow step that borrows a session's sandbox
+     * outside its turns and must not replace or drop the session's own.
+     */
+    readonly shutdownTracking?: "call" | "none" | "session";
 }
 /** The access `ensureSandboxAccess` builds, with what the opener may do beyond the sandbox API. */
 export interface EnsuredSandboxAccess extends SandboxAccess {
-    /** Permanently releases provider resources when the owning session ends. */
+    /**
+     * Permanently releases what the provider keeps under this access's key
+     * when the owning session ends, even when its last checkpoint recorded no
+     * sandbox. Waits for this access's open still in flight first.
+     */
     end(reason: SandboxSessionEndReason): Promise<void>;
     /**
-     * Lets go of the handle this access opened, if any, without stopping or
-     * deleting the sandbox, and returns it so the caller can free what it
-     * holds in this process. For a sandbox that outlives the access, such as a
-     * tool session's. Waits for an open still in flight, so a caller that
-     * finished early never leaves that handle behind.
+     * Lets go of the connection this access opened, if any, when the step that
+     * opened it ends: closes it without stopping or deleting the sandbox.
+     * Waits for an open still in flight, so a caller that finished early never
+     * leaves that connection behind.
+     */
+    release(): Promise<void>;
+    /**
+     * Resumes the sandbox the session recorded, in the background, so a turn
+     * that needs it waits only for the rest. Never starts one: does nothing
+     * when nothing is recorded, and leaves a gone sandbox for `get()`.
      */
-    detach(): Promise<SandboxProviderHandle | undefined>;
+    resumeRecorded(): void;
+    /** Waits for the work `prepare()` and `resumeRecorded()` queued; never throws. */
+    settle(): Promise<void>;
 }
 export declare function ensureSandboxAccess(input: EnsureSandboxAccessInput): Promise<EnsuredSandboxAccess>;
 export {};

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

@@ -1 +1 @@
-import{getRuntimeCompiledArtifactsSandboxAppRoot}from"#runtime/compiled-artifacts-source.js";import{contextStorage}from"#context/container.js";import{resolveSandboxCacheDirectory}from"#internal/application/paths.js";import{getSandboxEnvironmentRuntime,runWithSandboxConstructorRuntime}from"#shared/sandbox-environment.js";import{buildCallbackContext,withRuntimeSandboxLifecycle}from"#context/build-callback-context.js";import{isEveDevEnvironment}from"#internal/application/dev-environment.js";import{trackActiveSandboxHandle,untrackActiveSandboxHandle}from"#execution/sandbox/active-handles.js";import{isSandboxPreparedArtifact}from"#shared/sandbox-provider.js";import{SandboxTemplateNotProvisionedError}from"#shared/sandbox-template-error.js";import{loadSandboxPreparedArtifact}from"#runtime/sandbox/prepared-artifacts.js";import{ensureDevelopmentSandboxesPrepared}from"#execution/sandbox/development-lazy-prewarm.js";import{createSandboxProviderHost}from"#execution/sandbox/provider-host.js";const pendingSandboxStarts=new Map;async function ensureSandboxAccess(e){let t=e.state?.session?.providerName===void 0?null:e.state.session,n,r,i,a=getRuntimeCompiledArtifactsSandboxAppRoot(e.compiledArtifactsSource)??process.cwd(),o=e.registry.sandbox;if(o===null)return{async captureState(){return{session:t}},async detach(){},async end(){},async get(){return null},async stop(){}};async function open(n,i,s,c){if(r!==void 0)throw Error(`A sandbox definition can open only one sandbox.`);let l=o.inheritance,u=l?.definition??o.definition;if(u.kind!==`independent`)throw Error(`Sandbox "${u.logicalPath}" has no environment.`);if(s!==u.environment)throw Error(`Sandbox "${u.logicalPath}" selected a different environment.`);if(n!==getSandboxEnvironmentRuntime(u.environment))throw Error(`Sandbox "${u.logicalPath}" selected a different provider.`);if(t!==null)throw Error(`Sandbox "${u.logicalPath}" is already initialized.`);let d=l?.nodeId??e.nodeId,f=await loadSandboxPreparedArtifact({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:d,providerName:n.providerName});if(f===void 0)throw new SandboxTemplateNotProvisionedError({providerName:n.providerName,templateKey:d});let p={host:createSandboxProviderHost(a),session:c,storagePath:resolveSandboxCacheDirectory(a)};r=(async()=>{let e=await n.implementation.start(p,i,f);if(!isSandboxPreparedArtifact(e.state))throw Error(`Sandbox provider "${n.providerName}" returned non-serializable session state.`);return t={providerName:n.providerName,state:e.state,stateProtocolVersion:n.stateProtocolVersion},e.handle})().catch(e=>{throw r=void 0,e});let m=await r;return installHandle(n.providerName,m)}function installHandle(e,t){let r=withRuntimeSandboxLifecycle(t.sandbox,e=>t.onSandboxDelete(e),()=>t.onSandboxStop());return n={handle:t,providerName:e,sandbox:r},r}async function resumePersisted(n,i){if(t===null)throw Error(`Sandbox session state is missing.`);let s=getSandboxEnvironmentRuntime(n.environment);if(t.providerName!==s.providerName)throw Error(`Sandbox session state belongs to provider "${t.providerName}", not "${s.providerName}".`);if(t.stateProtocolVersion!==s.stateProtocolVersion)throw Error(`Sandbox session state protocol ${t.stateProtocolVersion} is incompatible with provider "${s.providerName}" protocol ${s.stateProtocolVersion}.`);let c=o.inheritance?.nodeId??e.nodeId,l=await loadSandboxPreparedArtifact({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:c,providerName:s.providerName});if(l===void 0)throw new SandboxTemplateNotProvisionedError({providerName:s.providerName,templateKey:c});let u={host:createSandboxProviderHost(a),session:i,storagePath:resolveSandboxCacheDirectory(a)};r=s.implementation.resume(u,l,t.state).catch(e=>{throw r=void 0,e});let d=await r;return installHandle(s.providerName,d),trackActiveSandboxHandle({handle:d,providerName:s.providerName,sessionId:e.sessionId}),d}async function resolveHandle(){let n=o.inheritance,r=n?.definition??o.definition;if(r.kind!==`independent`)throw Error(`Sandbox "${r.logicalPath}" has no resolved parent.`);isEveDevEnvironment()&&e.compiledArtifactsSource.kind===`disk`&&await ensureDevelopmentSandboxesPrepared({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:n?.nodeId??e.nodeId,providerName:getSandboxEnvironmentRuntime(r.environment).providerName});let i={...contextStorage.getStore()===void 0?{auth:{current:null,initiator:null},id:e.sessionId,turn:{id:`sandbox-initialization`,sequence:0}}:buildCallbackContext().session,id:e.sessionId};if(t!==null)return await resumePersisted(r,i);let a=`${n?.nodeId??e.nodeId}\0${e.sessionId}`,s=pendingSandboxStarts.get(a);for(;s!==void 0;){if(t=await s,t!==null)return await resumePersisted(r,i);s=pendingSandboxStarts.get(a)}let c=startHandle(r,i),l=c.then(()=>t,()=>null);pendingSandboxStarts.set(a,l);try{return await c}finally{pendingSandboxStarts.get(a)===l&&pendingSandboxStarts.delete(a)}}async function startHandle(i,a){if(o.inheritance!==void 0)await open(getSandboxEnvironmentRuntime(i.environment),void 0,i.environment,a);else try{let e=await runWithSandboxConstructorRuntime({open:({environment:e,options:t,provider:n})=>open(n,t,e,a)},async()=>i.selector({session:a}));if(n===void 0||e!==n.sandbox)throw Error(`Sandbox "${i.logicalPath}" must return the sandbox it opens.`)}catch(a){let o=n?.handle;if(n=void 0,r=void 0,t=null,o!==void 0&&e.ownsSandbox!==!1)try{await o.onSandboxDelete()}catch(e){throw AggregateError([a,e],`Sandbox "${i.logicalPath}" initialization and cleanup both failed.`,{cause:a})}throw a}if(n===void 0)throw Error(`Sandbox "${i.logicalPath}" did not open a provider handle.`);return trackActiveSandboxHandle({handle:n.handle,providerName:n.providerName,sessionId:e.sessionId}),n.handle}function requireHandle(){return i===void 0&&(i=resolveHandle().catch(e=>{throw i=void 0,e})),i}let s=o.inheritance?.definition??o.definition;return{environment:s.kind===`independent`?s.environment:void 0,async captureState(){return r!==void 0&&await r,{session:t}},async delete(a){if(e.ownsSandbox===!1)throw Error(`Only the owning session can delete this sandbox.`);let o=await requireHandle(),s=n?.providerName;await o.onSandboxDelete(a),s!==void 0&&untrackActiveSandboxHandle({handle:o,providerName:s,sessionId:e.sessionId}),n=void 0,r=void 0,t=null,i=void 0},async detach(){i!==void 0&&await i.catch(()=>void 0);let t=n;if(t!==void 0)return untrackActiveSandboxHandle({handle:t.handle,providerName:t.providerName,sessionId:e.sessionId}),n=void 0,r=void 0,i=void 0,t.handle},async end(s){if(e.ownsSandbox===!1||t===null)return;let c=o.inheritance,l=c?.definition??o.definition;if(l.kind!==`independent`)throw Error(`Sandbox "${l.logicalPath}" has no environment.`);let u=getSandboxEnvironmentRuntime(l.environment);if(t.providerName!==u.providerName||t.stateProtocolVersion!==u.stateProtocolVersion)throw Error(`Sandbox session state is incompatible with provider "${u.providerName}".`);let d=await loadSandboxPreparedArtifact({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:c?.nodeId??e.nodeId,providerName:u.providerName});if(d===void 0)throw new SandboxTemplateNotProvisionedError({providerName:u.providerName,templateKey:c?.nodeId??e.nodeId});let f=contextStorage.getStore()===void 0?{auth:{current:null,initiator:null},id:e.sessionId,turn:{id:`sandbox-cleanup`,sequence:0}}:buildCallbackContext().session,p={host:createSandboxProviderHost(a),session:{...f,id:e.sessionId},storagePath:resolveSandboxCacheDirectory(a)},m=n;u.implementation.onSessionEnd===void 0?m===void 0?await(await u.implementation.resume(p,d,t.state)).onSandboxDelete():await m.handle.onSandboxDelete():await u.implementation.onSessionEnd(p,d,t.state,{reason:s}),m!==void 0&&untrackActiveSandboxHandle({handle:m.handle,providerName:m.providerName,sessionId:e.sessionId}),n=void 0,r=void 0,t=null,i=void 0},async get(){return await requireHandle(),n?.sandbox??null},async stop(){await(await requireHandle()).onSandboxStop(),n=void 0,r=void 0,i=void 0}}}export{ensureSandboxAccess};
+import{randomUUID}from"node:crypto";import{createLogger}from"#internal/logging.js";import{getRuntimeCompiledArtifactsSandboxAppRoot}from"#runtime/compiled-artifacts-source.js";import{contextStorage}from"#context/container.js";import{resolve}from"node:path";import{resolveSandboxCacheDirectory}from"#internal/application/paths.js";import{getSandboxEnvironmentRuntime,runWithSandboxConstructorRuntime}from"#shared/sandbox-environment.js";import{buildCallbackContext,withRuntimeSandboxLifecycle}from"#context/build-callback-context.js";import{isEveDevEnvironment}from"#internal/application/dev-environment.js";import{trackActiveSandboxConnection,untrackActiveSandboxConnection}from"#execution/sandbox/active-connections.js";import{isToolSessionId}from"#execution/tool-session/id.js";import{ToolSessionSandboxUnsupportedError}from"#shared/sandbox-tool-session-error.js";import{loadSandboxPreparedArtifact}from"#runtime/sandbox/prepared-artifacts.js";import{createConnectionSession}from"#execution/sandbox/session.js";import{ensureDevelopmentSandboxesPrepared}from"#execution/sandbox/development-lazy-prewarm.js";import{owningSandboxDefinition}from"#runtime/sandbox/registry.js";import{getSessionEndWithArtifact,resolvePersistedSandboxSessionState}from"#sandbox/state.js";import{isSandboxPreparedArtifact}from"#shared/sandbox-provider.js";import{SandboxSessionGoneError}from"#shared/sandbox-session-gone-error.js";import{SandboxTemplateNotProvisionedError}from"#shared/sandbox-template-error.js";const pendingSandboxStarts=new Map,log=createLogger(`execution.sandbox`);async function ensureSandboxAccess(e){let t=e.registry.sandbox,n=t===null?void 0:owningSandboxDefinition(t),r=resolvePersistedSandboxSessionState(e.state?.session,n?.kind===`independent`?getSandboxEnvironmentRuntime(n.environment):void 0),i,a,o,s,c=e.shutdownTracking??`session`,l=getRuntimeCompiledArtifactsSandboxAppRoot(e.compiledArtifactsSource)??process.cwd(),captured=()=>({session:r});if(t===null)return{async captureState(){return captured()},async end(){},async get(){return null},async open(){return null},prepare(){},async release(){},resumeRecorded(){},async settle(){},async stop(){}};let u=owningSandboxDefinition(t),d=t.inheritance?.nodeId??e.nodeId;function providerContext(t){let n=contextStorage.getStore()===void 0?{auth:{current:null,initiator:null},id:e.sessionId,turn:{id:t,sequence:0}}:buildCallbackContext().session;return{kind:isToolSessionId(e.sessionId)?`tool-session`:`session`,resolveProjectPath:e=>resolve(l,e),session:{...n,id:e.sessionId},storagePath:resolveSandboxCacheDirectory(l)}}function activeDefinition(){if(u.kind!==`independent`)throw Error(`Sandbox "${u.logicalPath}" uses defineParentSandbox(), but this agent has no parent sandbox to share. Only a declared subagent can share its parent's sandbox. Give this agent its own sandbox with defineSandbox() and an exported environment.`);return u}async function loadArtifact(t){let n=await loadSandboxPreparedArtifact({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:d,providerName:t.providerName});if(n===void 0)throw new SandboxTemplateNotProvisionedError({nodeId:d,providerName:t.providerName});return n}async function open(e,t,n,a){if(o!==void 0)throw Error("A sandbox definition can open only one sandbox. Call `environment.open()` once in the defineSandbox() selector and return that sandbox.");let s=activeDefinition();if(n!==s.environment)throw Error(`Sandbox "${s.logicalPath}" opened an environment other than the one it exports as \`environment\`. Call \`open()\` on the exported environment. A selector cannot open an environment created inside the selector or exported by another sandbox file.`);if(e!==getSandboxEnvironmentRuntime(s.environment))throw Error(`Sandbox "${s.logicalPath}" selected a different provider.`);if(r!==null)throw Error(`Sandbox "${s.logicalPath}" already opened this session's sandbox. Call \`environment.open()\` once in the defineSandbox() selector and return that sandbox.`);let c=await loadArtifact(e);return o=(async()=>{let n=await e.implementation.start(a,t,c);if(!isSandboxPreparedArtifact(n.state))throw Error(`Sandbox provider "${e.providerName}" returned non-serializable session state.`);let i=await openSandbox(e,a,n.connection,n.state);return r={generation:randomUUID(),providerName:e.providerName,state:n.state,stateProtocolVersion:e.stateProtocolVersion},i})().catch(e=>{throw o=void 0,e}),i=await o,i.sandbox}async function resumePersisted(e){if(r===null)throw Error(`Sandbox session state is missing.`);let t=getSandboxEnvironmentRuntime(activeDefinition().environment);if(r.providerName!==t.providerName)throw new SandboxSessionGoneError(`This session's sandbox was created by provider "${r.providerName}", but the agent now selects provider "${t.providerName}". eve cannot move a sandbox between providers, so the session continues in a fresh sandbox without the old sandbox's files.`);if(r.stateProtocolVersion!==t.stateProtocolVersion)throw new SandboxSessionGoneError(`Sandbox session state protocol ${r.stateProtocolVersion} is incompatible with provider "${t.providerName}" protocol ${t.stateProtocolVersion}.`);let n=await loadArtifact(t),a=r.state;return o=t.implementation.resume(e,n,a).then(n=>openSandbox(t,e,n,a)).catch(e=>{throw o=void 0,e}),i=await o,track(i),i}async function resolveOpened(t){let n=activeDefinition(),i=getSandboxEnvironmentRuntime(n.environment),a=providerContext(`sandbox-initialization`);if(a.kind===`tool-session`&&i.implementation.toolSessions!==!0)throw new ToolSessionSandboxUnsupportedError(i.providerName);if(isEveDevEnvironment()&&e.compiledArtifactsSource.kind===`disk`&&await ensureDevelopmentSandboxesPrepared({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:d,providerName:i.providerName}),r===null&&t.resumeOnly)throw Error(`This session has not recorded a sandbox to resume.`);if(r!==null)try{return await resumePersisted(a)}catch(n){if(!SandboxSessionGoneError.is(n)||t.resumeOnly)throw n;log.warn(`session sandbox is gone, starting a fresh one`,{error:n,providerName:r.providerName,sessionId:e.sessionId}),r=null}let o=[l,d,e.sessionId].join(`\0`),s=pendingSandboxStarts.get(o);for(;s!==void 0;){if(r=await s,r!==null)return await resumePersisted(a);s=pendingSandboxStarts.get(o)}let c=startOpened(a),u=c.then(()=>r,()=>null);pendingSandboxStarts.set(o,u);try{return await c}finally{pendingSandboxStarts.get(o)===u&&pendingSandboxStarts.delete(o)}}async function startOpened(e){let t=activeDefinition();try{let n=await runWithSandboxConstructorRuntime({open:({environment:t,options:n,provider:r})=>open(r,n,t,e)},async()=>t.selector({session:e.session}));if(i===void 0||n!==i.sandbox)throw Error(`Sandbox "${t.logicalPath}" must return the sandbox it opens.`)}catch(e){throw await i?.close().catch(()=>void 0),i=void 0,o=void 0,r=null,e}return track(i),i}function requireOpened(e={resumeOnly:!1}){return s===void 0&&(s=resolveOpened(e).catch(e=>{throw s=void 0,e})),s}async function openSession(){try{return(await requireOpened()).sandbox}catch(e){if(!SandboxSessionGoneError.is(e))throw e;return(await requireOpened()).sandbox}}let f=Promise.resolve();function enqueue(t,n={retry:!0}){let report=t=>{log.warn(`background sandbox preparation failed; it runs again when it is needed`,{error:t,sessionId:e.sessionId})};f=f.then(async()=>{try{await t()}catch(e){n.retry?await t().catch(report):report(e)}})}function track(t){c!==`none`&&trackActiveSandboxConnection({connection:t,providerName:t.providerName,sessionId:e.sessionId})}function forgetOpened(){let e=i;return i=void 0,o=void 0,s=void 0,e}function forgetSandbox(t){forgetOpened(),a=void 0,untrackActiveSandboxConnection({providerName:t,sessionId:e.sessionId}),r=null}return{environment:u.kind===`independent`?u.environment:void 0,async captureState(){return o!==void 0&&await o,captured()},async delete(t){if(e.ownsSandbox===!1)throw Error(`Only the owning session can delete this sandbox.`);await f;let n=await requireOpened();await n.delete(t),forgetSandbox(n.providerName)},async end(t){if(e.ownsSandbox===!1)return;await f,s!==void 0&&await s.catch(()=>void 0),await i?.close().catch(t=>{log.warn(`failed to close a sandbox connection at session end`,{error:t,sessionId:e.sessionId})});let n=getSandboxEnvironmentRuntime(activeDefinition().environment),a=r?.providerName===n.providerName&&r.stateProtocolVersion===n.stateProtocolVersion?r.state:null,o=providerContext(`sandbox-cleanup`),c=getSessionEndWithArtifact(n.implementation);c===void 0?await n.implementation.onSessionEnd(o,a,{reason:t}):await c(o,a,{artifact:await loadSandboxPreparedArtifact({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:d,providerName:n.providerName}),reason:t}),forgetSandbox(n.providerName)},async get(){return await f,await openSession()},open:openSession,prepare(e){enqueue(e===void 0?requireOpened:()=>e(openSession))},resumeRecorded(){r!==null&&enqueue(()=>requireOpened({resumeOnly:!0}),{retry:!1})},async settle(){await f},async release(){await f,s!==void 0&&await s.catch(()=>void 0);let t=forgetOpened();a!==void 0&&c!==`session`&&(untrackActiveSandboxConnection({connection:a,providerName:a.providerName,sessionId:e.sessionId}),a=void 0),!(t===void 0||c===`session`&&!t.closable)&&(untrackActiveSandboxConnection({connection:t,providerName:t.providerName,sessionId:e.sessionId}),await t.close())},async stop(){await f;let t=await requireOpened();if(await t.stop(),forgetOpened(),!t.closable){a=t;return}untrackActiveSandboxConnection({connection:t,providerName:t.providerName,sessionId:e.sessionId})}};async function openSandbox(t,n,r,i){let a;try{a=createConnectionSession(r)}catch(t){throw await r.close?.().catch(t=>{log.warn(`failed to close a sandbox connection eve could not use`,{error:t,sessionId:e.sessionId})}),t}let o=shared(()=>r.stop()),s=once(async()=>await r.close?.()),c={closable:r.close!==void 0,close:s,async delete(e){try{await s()}finally{await t.implementation.onSessionEnd(n,i,{abortSignal:e?.abortSignal,reason:`deleted`})}},providerName:t.providerName,sandbox:withRuntimeSandboxLifecycle(a,e=>c.delete(e),()=>c.stop()),async stop(){try{await o()}finally{await s()}}};return c}}function shared(e){let t;return()=>t??=e().finally(()=>{t=void 0})}function once(e){let t;return()=>t??=e().catch(e=>{throw t=void 0,e})}export{ensureSandboxAccess};

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

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

@@ -1,3 +1,3 @@
-import{shellQuote}from"#execution/sandbox/shell-quote.js";import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{normalizeModelPath}from"#execution/tools/file-state.js";import{resolveAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{ripgrepIsAvailable}from"#execution/sandbox/ripgrep-probe.js";async function executeGrepOnSandbox(e,t){let n=t.path??`/workspace`,r=await resolveAbsoluteFilePath(e,n),i=normalizeModelPath(r),a=Math.min(Math.max(1,t.limit??100),1e3),o=t.context!==void 0&&t.context>0?t.context:0,s=await ripgrepIsAvailable(e)?buildRipgrepCommand({contextLines:o,effectiveLimit:a,glob:t.glob,ignoreCase:t.ignoreCase??!1,literal:t.literal??!1,normalizedPath:i,pattern:t.pattern}):buildPosixGrepCommand({contextLines:o,effectiveLimit:a,glob:t.glob,ignoreCase:t.ignoreCase??!1,literal:t.literal??!1,normalizedPath:i,pattern:t.pattern}),c=await e.run({command:s});if(c.exitCode!==0&&c.exitCode!==1||c.exitCode===1&&c.stderr.trim().length>0)throw buildGrepExecutionError(s,c.exitCode,c.stderr);let l=c.stdout;return l.trim().length===0?{content:`No matches found`,matchCount:0,path:i,truncated:!1}:processOutput({effectiveLimit:a,normalizedPath:i,stdout:l})}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`,`--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(`-e ${shellQuote(e.pattern)}`),t.push(shellQuote(e.normalizedPath)),t.join(` `)}function processOutput(e){let t=e.stdout.split(`
+import{shellQuote}from"#execution/sandbox/shell-quote.js";import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{normalizeModelPath}from"#execution/tools/file-state.js";import{resolveAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{ripgrepIsAvailable}from"#execution/sandbox/ripgrep-probe.js";async function executeGrepOnSandbox(e,t){let n=await resolveAbsoluteFilePath(e,t.path??`.`),r=normalizeModelPath(n),i=Math.min(Math.max(1,t.limit??100),1e3),a=t.context!==void 0&&t.context>0?t.context:0,o=await ripgrepIsAvailable(e)?buildRipgrepCommand({contextLines:a,effectiveLimit:i,glob:t.glob,ignoreCase:t.ignoreCase??!1,literal:t.literal??!1,normalizedPath:r,pattern:t.pattern}):buildPosixGrepCommand({contextLines:a,effectiveLimit:i,glob:t.glob,ignoreCase:t.ignoreCase??!1,literal:t.literal??!1,normalizedPath:r,pattern:t.pattern}),s=await e.run({command:o});if(s.exitCode!==0&&s.exitCode!==1||s.exitCode===1&&s.stderr.trim().length>0)throw buildGrepExecutionError(o,s.exitCode,s.stderr);let c=s.stdout;return c.trim().length===0?{content:`No matches found`,matchCount:0,path:r,truncated:!1}:processOutput({effectiveLimit:i,normalizedPath:r,stdout:c})}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`,`--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(`-e ${shellQuote(e.pattern)}`),t.push(shellQuote(e.normalizedPath)),t.join(` `)}function processOutput(e){let t=e.stdout.split(`
 `),n=[],r=0,i=0,a=!1;for(let e=0;e<t.length;e+=1){let o=t[e]??``;if(o.length===0&&e===t.length-1)continue;o!==`--`&&o.length>0&&/^.+:\d+:/.test(o)&&i++;let s=capLineLength(o),c=Buffer.byteLength(s,`utf8`)+1;if(r+c>MAX_OUTPUT_BYTES&&n.length>0){a=!0;break}n.push(s),r+=c}let o=a||i>=e.effectiveLimit,s=n.join(`
 `);if(o){let t=[];i>=e.effectiveLimit&&t.push(`Match limit reached (${e.effectiveLimit}). Use a larger limit or more specific pattern.`),a&&t.push(`Output truncated due to size. Use a more specific path or pattern.`),s+=`\n\n[${t.join(` `)}]`}return{content:s,matchCount:i,path:e.normalizedPath,truncated:o}}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/logging-session.js

@@ -1,2 +1,2 @@
-import{truncateTail}from"#execution/sandbox/truncate-output.js";function createLoggingSandboxSession(e){let{log:t,session:n}=e;return{...n,async run(e){t?.(`preparation run: ${formatCommand(e.command)}`);let r=await n.run(e);if(r.exitCode===1)throw Error(formatPreparationRunFailure(e.command,r));return r},async spawn(e){return t?.(`preparation spawn: ${formatCommand(e.command)}`),await n.spawn(e)},async writeFile(e){return t?.(`preparation write file: ${e.path}`),await n.writeFile(e)},async writeBinaryFile(e){return t?.(`preparation write binary file: ${e.path} (${e.content.byteLength} bytes)`),await n.writeBinaryFile(e)},async writeTextFile(e){return t?.(`preparation write text file: ${e.path} (${e.content.length} chars)`),await n.writeTextFile(e)},async removePath(e){return t?.(`preparation remove path: ${e.path}`),await n.removePath(e)}}}function formatPreparationRunFailure(e,t){return[`Sandbox preparation failed because sandbox.run command exited with code 1:`,e,``,`stdout:`,formatCapturedOutput(`stdout`,t.stdout),``,`stderr:`,formatCapturedOutput(`stderr`,t.stderr)].join(`
+import{truncateTail}from"#execution/sandbox/truncate-output.js";function createLoggingSandboxSession(e){let{log:t,session:n}=e;return{...n,async run(e){t?.(`preparation run: ${formatCommand(e.command)}`);let r=await n.run(e);if(r.exitCode===1)throw Error(formatPreparationRunFailure(e.command,r));return r},async spawn(e){return t?.(`preparation spawn: ${formatCommand(e.command)}`),await n.spawn(e)},async writeFile(e){return t?.(`preparation write file: ${e.path}`),await n.writeFile(e)},async writeBinaryFile(e){return t?.(`preparation write binary file: ${e.path} (${e.content.byteLength} bytes)`),await n.writeBinaryFile(e)},async writeTextFile(e){return t?.(`preparation write text file: ${e.path} (${e.content.length} chars)`),await n.writeTextFile(e)},async writeFiles(e){return t?.(`preparation write files: ${e.files.length} files`),await n.writeFiles(e)},async removePath(e){return t?.(`preparation remove path: ${e.path}`),await n.removePath(e)}}}function formatPreparationRunFailure(e,t){return[`Sandbox preparation failed because sandbox.run command exited with code 1:`,e,``,`stdout:`,formatCapturedOutput(`stdout`,t.stdout),``,`stderr:`,formatCapturedOutput(`stderr`,t.stderr)].join(`
 `)}function formatCapturedOutput(e,t){let n=truncateTail(t);return n.truncated?`[${e} truncated: showing last ${n.outputLines} of ${n.totalLines} lines]\n${n.output}`:n.output}function formatCommand(e){return truncateOneLine(e)}function truncateOneLine(e){let t=e.replaceAll(/\s+/g,` `).trim();return t.length<=240?t:`${t.slice(0,239)}…`}export{createLoggingSandboxSession};

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

@@ -1,4 +1,5 @@
-import { type SandboxPreparedArtifact, type SandboxProviderPrepareContext, type SandboxProviderRuntime } from "#shared/sandbox-provider.js";
+import type { SandboxJson, SandboxPrepareContext, SandboxProviderRuntime } from "#sandbox/provider.js";
+import type { SandboxProviderFiles, SandboxProviderResourceFile } from "#shared/sandbox-provider.js";
 import { type RuntimeCompiledArtifactsSource, type RuntimeDiskCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
 import { type ResolvedAgentGraphBundle } from "#runtime/graph.js";
 import type { SandboxPreparedArtifactEntry } from "#shared/sandbox-prepared-artifacts.js";
@@ -16,9 +17,9 @@ export interface SandboxPreparedArtifactStore {
  * them.
  */
 type SandboxProviderPrepareDispatch = (input: {
-    readonly context: SandboxProviderPrepareContext;
+    readonly context: SandboxPrepareContext;
     readonly provider: SandboxProviderRuntime;
-}) => Promise<SandboxPreparedArtifact>;
+}) => Promise<SandboxJson>;
 /**
  * Loads the compiled runtime graph for one authored app root and
  * prepares every provider sandbox template required by that graph.
@@ -38,4 +39,23 @@ export declare function prewarmAppSandboxes(input: {
     readonly dispatch?: SandboxProviderPrepareDispatch;
     readonly preparedArtifactStore?: SandboxPreparedArtifactStore;
 }): Promise<void>;
+/** The compiled workspace and skill files one sandbox template seeds. */
+export interface SandboxTemplateResources {
+    /** The compiled resource tree's content hash; absent when the agent has none. */
+    readonly key?: string;
+    /** The compiled resource directory on the host, holding `workspace/` and `skills/`. */
+    readonly path?: string;
+    readonly skills?: readonly SandboxProviderResourceFile[];
+    readonly workspace?: readonly SandboxProviderResourceFile[];
+}
+/** The context eve passes to a provider's `prepare()` for one template. */
+export declare function createSandboxPrepareContext(input: {
+    readonly appRoot: string;
+    readonly files: SandboxProviderFiles;
+    readonly log: (message: string) => void;
+    readonly provider: Pick<SandboxProviderRuntime, "prepare" | "providerName">;
+    readonly resources: SandboxTemplateResources;
+    readonly sourceRevision: string;
+    readonly storagePath: string;
+}): SandboxPrepareContext;
 export {};

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

@@ -1 +1,2 @@
-import{getRuntimeCompiledArtifactsSandboxAppRoot}from"#runtime/compiled-artifacts-source.js";import{loadCompiledManifest}from"#runtime/loaders/manifest.js";import{join,relative,resolve}from"node:path";import{resolveRuntimeCompilerArtifactPaths}from"#runtime/loaders/artifact-paths.js";import{toErrorMessage}from"#shared/errors.js";import{resolveSandboxCacheDirectory}from"#internal/application/paths.js";import{getSandboxEnvironmentRuntime}from"#shared/sandbox-environment.js";import{ROOT_RUNTIME_AGENT_NODE_ID,getResolvedRuntimeAgentNode}from"#runtime/graph.js";import{createSandboxProviderResources}from"#shared/sandbox-provider.js";import{writeSandboxPreparedArtifactsManifest}from"#runtime/sandbox/prepared-artifacts.js";import{loadCompiledModuleMapFromAuthoredSource}from"#internal/authored-module-map-loader.js";import{createAuthoredSourceRuntimeCompiledArtifactsSource}from"#internal/application/runtime-compiled-artifacts-source.js";import{resolveRuntimeAgentGraph}from"#runtime/resolve-agent-graph.js";import{createSandboxProviderFiles}from"#execution/sandbox/provider-files.js";import{createDevelopmentSandboxProviderHost}from"#execution/sandbox/provider-host-development.js";import{materializeWorkspaceDirectory}from"#runtime/workspace/seed-files.js";const diskPreparedArtifactStore={async write(e){await writeSandboxPreparedArtifactsManifest(e)}};async function prewarmSandboxes(e){let t=await collectPrewarmTargets(e);if(t.length===0)return;let n=e.preparedArtifactStore??diskPreparedArtifactStore,r=e.dispatch??(async({context:e,provider:t})=>await t.implementation.prepare(e));e.log?.(`eve: initializing ${formatSandboxTemplateCount(t.length)}...`);let i=await Promise.allSettled(t.map(async({context:t,label:n,nodeId:i,provider:a})=>{let logProviderProgress=t=>{shouldLogSandboxPrewarmProgress(t)&&e.log?.(`eve: sandbox template "${n}" (${a.providerName}): ${t}`)};try{return{nodeId:i,provider:a,result:await r({context:{...t,log:e.log===void 0?void 0:logProviderProgress},provider:a})}}catch(t){let r=formatPrewarmFailureForEnvironment({providerName:a.providerName,error:t});throw e.log?.(`eve: failed to initialize sandbox template "${n}" on provider "${a.providerName}": ${toErrorMessage(r)}`),r}})),a=i.find(e=>e.status===`rejected`);if(a?.status===`rejected`)throw a.reason;let o=i.flatMap(e=>e.status===`fulfilled`?[{artifact:e.value.result,nodeId:e.value.nodeId,providerName:e.value.provider.providerName}]:[]);await n.write({compileDirectoryPath:e.compileDirectoryPath,entries:o}),e.log?.(`eve: initialized ${formatSandboxTemplateCount(t.length)}.`)}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:getRuntimeCompiledArtifactsSandboxAppRoot(t)??e.appRoot,compileDirectoryPath:resolveRuntimeCompilerArtifactPaths(t.appRoot).compileDirectoryPath,compiledArtifactsSource:t,dispatch:e.dispatch,graph:n,log:e.log,preparedArtifactStore:e.preparedArtifactStore})}async function collectPrewarmTargets(e){let t=[];return await Promise.all(collectNodeSandboxes(e.graph).map(async({definition:n,nodeId:r,workspaceResourceRoot:i})=>{let a=getResolvedRuntimeAgentNode(e.graph,r).agent,o=join(resolve(e.appRoot,relative(a.metadata.appRoot,a.metadata.agentRoot)),`sandbox`),s=getSandboxEnvironmentRuntime(n.environment),c=await loadResourceRootSeedFiles({compileDirectoryPath:e.compileDirectoryPath,workspaceResourceRoot:i});t.push({context:{files:createSandboxProviderFiles(o),host:createDevelopmentSandboxProviderHost(e.appRoot),resources:createSandboxProviderResources({resourcesKey:i.contentHash,resourcesPath:i.contentHash===void 0?void 0:`${e.compileDirectoryPath}/${i.logicalPath}`,seedFiles:c}),sourceRevision:n.revisionHash,storagePath:resolveSandboxCacheDirectory(e.appRoot)},label:formatLabel(r),nodeId:r,provider:s})})),t.sort((e,t)=>e.label.localeCompare(t.label))}async function loadResourceRootSeedFiles(e){return e.workspaceResourceRoot.contentHash===void 0&&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.definition.kind===`parent`?[]:[{...n,definition:n.definition,nodeId:e}]})}function formatLabel(e){return e===ROOT_RUNTIME_AGENT_NODE_ID?`root`:e}function formatSandboxTemplateCount(e){return`${e} sandbox ${e===1?`template`:`templates`}`}function shouldLogSandboxPrewarmProgress(e){return!e.startsWith(`checking `)&&!e.startsWith(`reusing `)&&e!==`loading microsandbox runtime`&&e!==`microsandbox runtime ready`}function formatPrewarmFailureForEnvironment(e){return!isVercelEnvironment()||!isLocalSandboxProvider(e.providerName)?e.error:Error(`The ${e.providerName} sandbox provider is not available when deploying on Vercel. Vercel build containers cannot run local Docker containers or microsandbox VMs. Use DefaultSandbox.environment() so eve selects Vercel Sandbox on Vercel, or configure VercelSandbox.environment() explicitly. Original ${e.providerName} error: ${toErrorMessage(e.error)}`,{cause:e.error})}function isVercelEnvironment(){return!!process.env.VERCEL?.trim()}function isLocalSandboxProvider(e){return e===`docker`||e===`microsandbox`}export{prewarmAppSandboxes};
+import{getRuntimeCompiledArtifactsSandboxAppRoot}from"#runtime/compiled-artifacts-source.js";import{loadCompiledManifest}from"#runtime/loaders/manifest.js";import{join,relative,resolve}from"node:path";import{resolveRuntimeCompilerArtifactPaths}from"#runtime/loaders/artifact-paths.js";import{toErrorMessage}from"#shared/errors.js";import{resolveSandboxCacheDirectory}from"#internal/application/paths.js";import{getSandboxEnvironmentRuntime}from"#shared/sandbox-environment.js";import{ROOT_RUNTIME_AGENT_NODE_ID,getResolvedRuntimeAgentNode}from"#runtime/graph.js";import{shellQuote}from"#execution/sandbox/shell-quote.js";import{createSandboxProviderIdentity}from"#execution/sandbox/provider-identity.js";import{copyDirectoryAtomically}from"#execution/sandbox/bindings/local-provider-utils.js";import{writeSandboxPreparedArtifactsManifest}from"#runtime/sandbox/prepared-artifacts.js";import{createLoggingSandboxSession}from"#execution/sandbox/logging-session.js";import{createConnectionSession}from"#execution/sandbox/session.js";import{loadCompiledModuleMapFromAuthoredSource}from"#internal/authored-module-map-loader.js";import{createAuthoredSourceRuntimeCompiledArtifactsSource}from"#internal/application/runtime-compiled-artifacts-source.js";import{resolveRuntimeAgentGraph}from"#runtime/resolve-agent-graph.js";import{createSandboxProviderFiles}from"#execution/sandbox/provider-files.js";import{materializeWorkspaceDirectory}from"#runtime/workspace/seed-files.js";import{MODEL_SKILL_ROOT,resolveSandboxModelPath}from"#shared/skill-paths.js";const diskPreparedArtifactStore={async write(e){await writeSandboxPreparedArtifactsManifest(e)}};async function prewarmSandboxes(e){let t=await collectPrewarmTargets(e);if(t.length===0)return;let n=e.preparedArtifactStore??diskPreparedArtifactStore,r=e.dispatch??(async({context:e,provider:t})=>await t.implementation.prepare(e));e.log?.(`eve: initializing ${formatSandboxTemplateCount(t.length)}...`);let i=await Promise.allSettled(t.map(async({label:t,nodeId:n,provider:i,...a})=>{let logProviderProgress=n=>{shouldLogSandboxPrewarmProgress(n)&&e.log?.(`eve: sandbox template "${t}" (${i.providerName}): ${n}`)};try{return{nodeId:n,provider:i,result:await r({context:createSandboxPrepareContext({...a,appRoot:e.appRoot,log:logProviderProgress,provider:i,storagePath:resolveSandboxCacheDirectory(e.appRoot)}),provider:i})}}catch(n){let r=formatPrewarmFailureForEnvironment({providerName:i.providerName,error:n});throw e.log?.(`eve: failed to initialize sandbox template "${t}" on provider "${i.providerName}": ${toErrorMessage(r)}`),r}})),a=i.find(e=>e.status===`rejected`);if(a?.status===`rejected`)throw a.reason;let o=i.flatMap(e=>e.status===`fulfilled`?[{artifact:e.value.result,nodeId:e.value.nodeId,providerName:e.value.provider.providerName}]:[]);await n.write({compileDirectoryPath:e.compileDirectoryPath,entries:o}),e.log?.(`eve: initialized ${formatSandboxTemplateCount(t.length)}.`)}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:getRuntimeCompiledArtifactsSandboxAppRoot(t)??e.appRoot,compileDirectoryPath:resolveRuntimeCompilerArtifactPaths(t.appRoot).compileDirectoryPath,compiledArtifactsSource:t,dispatch:e.dispatch,graph:n,log:e.log,preparedArtifactStore:e.preparedArtifactStore})}async function collectPrewarmTargets(e){let t=[];return await Promise.all(collectNodeSandboxes(e.graph).map(async({definition:n,nodeId:r,workspaceResourceRoot:i})=>{let a=getResolvedRuntimeAgentNode(e.graph,r).agent,o=join(resolve(e.appRoot,relative(a.metadata.appRoot,a.metadata.agentRoot)),`sandbox`),s=getSandboxEnvironmentRuntime(n.environment),c=await loadSandboxProviderResources({compileDirectoryPath:e.compileDirectoryPath,workspaceResourceRoot:i});t.push({files:createSandboxProviderFiles(o),label:formatLabel(r),nodeId:r,provider:s,resources:c,sourceRevision:n.revisionHash})})),t.sort((e,t)=>e.label.localeCompare(t.label))}async function loadSandboxProviderResources(e){let{contentHash:t,logicalPath:n}=e.workspaceResourceRoot;if(t===void 0)return{};let r=`${e.compileDirectoryPath}/${n}`;return{key:t,path:r,...await materializeWorkspaceDirectory(r)}}function createSandboxPrepareContext(e){let{log:t,resources:n,storagePath:r}=e,{prepare:i}=e.provider,a=n.workspace??[],o=n.skills??[],s=n.key===void 0?void 0:n.path;return{files:e.files,isEmpty:a.length===0&&o.length===0&&i===void 0,log:t,async populate(e,n){let r=createConnectionSession(e);if(n?.mountedAt!==void 0&&s!==void 0)t(`copying workspace and skills from mounted resources`),await copyMountedResources(r,shellQuote(n.mountedAt));else if(a.length>0||o.length>0){t(`writing workspace and skills`);let bytes=e=>typeof e.content==`string`?Buffer.from(e.content):e.content;await r.writeFiles({files:[...a.map(e=>({content:bytes(e),path:r.resolvePath(e.relativePath)})),...await Promise.all(o.map(async e=>({content:bytes(e),path:await resolveSandboxModelPath({path:`${MODEL_SKILL_ROOT}/${e.relativePath}`,sandbox:r})})))]})}i!==void 0&&(t(`running sandbox preparation`),await i(createLoggingSandboxSession({log:t,session:r})))},resolveProjectPath:t=>resolve(e.appRoot,t),async resourcesDirectory(){if(n.key===void 0||s===void 0)return;let t=join(r,e.provider.providerName,`resources`,n.key);return await copyDirectoryAtomically(s,t),t},storagePath:r,templateKey(t){assertSandboxIdentity(t,`identity`,new WeakSet);for(let e of[`resources`,`sourceRevision`])if(Object.hasOwn(t,e))throw Error(`ctx.templateKey() reserves "${e}": eve adds the workspace and skill files and the sandbox source revision itself. Rename that identity field.`);let r=n.key;return createSandboxProviderIdentity({...t,resources:{skills:r===void 0?void 0:`${r}:skills`,workspace:r===void 0?void 0:`${r}:workspace`},sourceRevision:e.sourceRevision})}}}async function copyMountedResources(e,t){let n=shellQuote(e.resolvePath(`.`)),r=await e.run({command:[`set -e`,`if [ -d ${t}/workspace ]; then cp -a ${t}/workspace/. ${n}/; fi`,`if [ -d ${t}/skills ]; then`,`  mkdir -p "$HOME/.agents"`,`  rm -rf "$HOME/.agents/skills"`,`  mkdir -p "$HOME/.agents/skills"`,`  cp -a ${t}/skills/. "$HOME/.agents/skills/"`,`fi`].join(`
+`)});if(r.exitCode!==0)throw Error(`Failed to hydrate sandbox resources: ${r.stderr||r.stdout}`)}function assertSandboxIdentity(e,t,n){if(e==null||typeof e==`function`||typeof e==`string`||typeof e==`boolean`||typeof e==`number`&&Number.isFinite(e))return;let r=typeof e==`object`?Object.getPrototypeOf(e):void 0;if(typeof e!=`object`||!(Array.isArray(e)||r===Object.prototype||r===null))throw Error(`ctx.templateKey() accepts only JSON values, plain objects, arrays, and functions, but ${t} is ${describeIdentityValue(e)}. Pass a JSON form, such as a string.`);if(n.has(e))throw Error(`ctx.templateKey() cannot hash a circular value at ${t}.`);n.add(e);for(let[r,i]of Object.entries(e))assertSandboxIdentity(i,Array.isArray(e)?`${t}[${r}]`:`${t}.${r}`,n);n.delete(e)}function describeIdentityValue(e){return typeof e==`object`&&e?`a ${e.constructor?.name??`non-plain object`}`:typeof e==`number`?String(e):`a ${typeof e}`}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.definition.kind===`parent`?[]:[{...n,definition:n.definition,nodeId:e}]})}function formatLabel(e){return e===ROOT_RUNTIME_AGENT_NODE_ID?`root`:e}function formatSandboxTemplateCount(e){return`${e} sandbox ${e===1?`template`:`templates`}`}function shouldLogSandboxPrewarmProgress(e){return!e.startsWith(`checking `)&&!e.startsWith(`reusing `)}function formatPrewarmFailureForEnvironment(e){return!isVercelEnvironment()||!isLocalSandboxProvider(e.providerName)?e.error:Error(`The ${e.providerName} sandbox provider is not available when deploying on Vercel. Vercel build containers cannot run local Docker containers. Use DefaultSandbox.environment() so eve selects Vercel Sandbox on Vercel, or configure VercelSandbox.environment() explicitly. Original ${e.providerName} error: ${toErrorMessage(e.error)}`,{cause:e.error})}function isVercelEnvironment(){return!!process.env.VERCEL?.trim()}function isLocalSandboxProvider(e){return e===`docker`}export{createSandboxPrepareContext,prewarmAppSandboxes};

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

@@ -1,3 +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"#execution/tools/file-state.js";import{resolveAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{detectImageMediaType,hasPdfHeader,readMediaMetadata}from"#internal/attachments/media-metadata.js";import{inlinesSandboxRefAsBytes}from"#internal/attachments/sandbox-refs.js";async function executeReadFileOnSandbox(e,t){let{filePath:n,offset:r,limit:i}=t,a=await resolveAbsoluteFilePath(e,n),o=normalizeModelPath(a),s=await e.readBinaryFile({path:a});if(s===null)throw Error(`File not found: ${n}. Verify the path exists and is accessible in the sandbox.`);if(hasPdfHeader(s))return buildFileReadResult(s,o,`application/pdf`);let c=decodeUtf8(s);if(c===void 0||c.includes(`\0`)){let e=detectImageMediaType(s);if(e!==void 0)return buildFileReadResult(s,o,e);throw Error(`File "${n}" appears to be a binary file. read_file only supports text files, PNG, JPEG, GIF, or WebP images, and PDFs.`)}let l=r??1,u=i??2e3;if(l<1)throw Error(`offset must be >= 1. Received: ${l}.`);let d=c.split(`
+import{loadContext}from"#context/container.js";import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{buildReadFileTargetKey,createReadFileStamp,normalizeModelPath,setReadFileStamp}from"#execution/tools/file-state.js";import{resolveAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{detectImageMediaType,hasPdfHeader,readMediaMetadata}from"#internal/attachments/media-metadata.js";import{inlinesSandboxRefAsBytes}from"#internal/attachments/sandbox-refs.js";async function executeReadFileOnSandbox(e,t){let{filePath:n,offset:r,limit:i}=t,a=await resolveAbsoluteFilePath(e,n),o=normalizeModelPath(a),s=await e.readBinaryFile({path:a});if(s===null)throw Error(`File not found: ${o}. Verify the path exists and is accessible in the sandbox.`);if(hasPdfHeader(s))return buildFileReadResult(s,o,`application/pdf`);let c=decodeUtf8(s);if(c===void 0||c.includes(`\0`)){let e=detectImageMediaType(s);if(e!==void 0)return buildFileReadResult(s,o,e);throw Error(`File "${o}" appears to be a binary file. read_file only supports text files, PNG, JPEG, GIF, or WebP images, and PDFs.`)}let l=r??1,u=i??2e3;if(l<1)throw Error(`offset must be >= 1. Received: ${l}.`);let d=c.split(`
 `),f=d.length>0&&d[d.length-1]===``?d.length-1:d.length;if(f===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.`)}else if(l>f)throw Error(`offset ${l} is past the end of the file (${f} lines).`);let p=createReadFileStamp({content:c,filePath:o}),m=buildReadFileTargetKey(o);if(setReadFileStamp(loadContext(),m,p),f===0)return{content:``,path:o,totalLines:0,truncated:!1};let h=l-1,g=Math.min(h+u,f),_=d.slice(h,g),v=[],y=0,b=!1;for(let e=0;e<_.length;e++){let t=`${l+e}: ${capLineLength(_[e]??``)}`,n=Buffer.byteLength(t,`utf8`)+1;if(y+n>MAX_OUTPUT_BYTES&&v.length>0){b=!0;break}v.push(t),y+=n}let x=v.join(`
 `),S=l+v.length-1;return S<f||b?{content:x,nextOffset:S+1,path:o,totalLines:f,truncated:!0}:{content:x,path:o,totalLines:f,truncated:!1}}function decodeUtf8(e){try{return new TextDecoder(`utf-8`,{fatal:!0}).decode(e)}catch{return}}function buildFileReadResult(e,t,n){let r=readMediaMetadata(e,n),i=n===`application/pdf`;if(!inlinesSandboxRefAsBytes({...r,path:t}))throw Error(i?`PDF "${t}" is ${e.byteLength} bytes; read_file shows PDFs up to 20 MiB. Split it or extract its text in the sandbox first.`:`Image "${t}" is ${describeImage(r)}; read_file shows images up to 3 MiB and 8000 pixels per side. Resize or crop it in the sandbox first.`);let a=r.pages===void 0?``:`, ${r.pages} ${r.pages===1?`page`:`pages`}`;return{content:`${i?`PDF`:`Image`} ${t} (${n}, ${e.byteLength} bytes${a}).`,file:r,path:t,totalLines:0,truncated:!1}}function describeImage(e){let t=`${e.size} bytes`;return e.width===void 0?t:`${e.width}x${e.height} pixels, ${t}`}export{executeReadFileOnSandbox};

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

@@ -1,6 +1,7 @@
 import type { SandboxSession } from "#public/definitions/sandbox.js";
 /**
- * Resolves a model-supplied `$HOME` prefix and validates that the resulting
- * sandbox file path is absolute.
+ * Resolves a model-supplied file path to an absolute sandbox path: a leading
+ * `$HOME` through the sandbox's home, and a relative path from the workspace
+ * root, where `bash` commands start.
  */
 export declare function resolveAbsoluteFilePath(sandbox: SandboxSession, filePath: string): Promise<string>;

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

@@ -1 +1 @@
-import{resolveSandboxModelPath}from"#shared/skill-paths.js";async function resolveAbsoluteFilePath(e,t){let n=await resolveSandboxModelPath({path:t,sandbox:e});if(!n.startsWith(`/`))throw Error(`filePath must be an absolute path. Received: "${t}". Use an absolute path such as /workspace/foo.ts or a path beginning with \$HOME/.`);return n}export{resolveAbsoluteFilePath};
+import{resolveSandboxModelPath}from"#shared/skill-paths.js";async function resolveAbsoluteFilePath(e,t){let n=await resolveSandboxModelPath({path:t,sandbox:e});if(n===`$HOME`||n.startsWith(`$HOME/`))throw Error(`Cannot resolve "${t}": the sandbox has no usable $HOME. Use an absolute path or a path relative to the workspace root.`);return e.resolvePath(n)}export{resolveAbsoluteFilePath};

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

@@ -1 +1 @@
-async function ripgrepIsAvailable(e){try{let t=await e.run({command:`command -v rg >/dev/null 2>&1 || exit 127; rg --line-number --color=never --hidden --glob '!.git/*' --max-count 1 -- '__eve_ripgrep_probe_never_matches__' /workspace`});return(t.exitCode===0||t.exitCode===1)&&t.stderr.trim().length===0}catch{return!1}}export{ripgrepIsAvailable};
+async function ripgrepIsAvailable(e){try{let t=await e.run({command:`command -v rg >/dev/null 2>&1 || exit 127; rg --line-number --color=never --hidden --glob '!.git/*' --max-count 1 -- '__eve_ripgrep_probe_never_matches__' /dev/null`});return(t.exitCode===0||t.exitCode===1)&&t.stderr.trim().length===0}catch{return!1}}export{ripgrepIsAvailable};

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

@@ -1,26 +1,16 @@
-import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
-type NetworkPolicySandboxSession = SandboxSession & {
-    setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
-};
-import type { InternalSandboxSession, SandboxSession } from "#shared/sandbox-session.js";
-export type { InternalSandboxSession };
+import type { SandboxConnection } from "#sandbox/provider.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
 /**
  * Tells agent-aware CLIs (such as `vercel`) that an automated agent runs
- * the command, so they skip interactive prompts. Built-in providers apply it
- * beneath environment-level and per-call env so authors can override it.
+ * the command, so they skip interactive prompts. Providers apply it beneath
+ * environment-level and per-call env so authors can override it.
  */
 export declare const SANDBOX_AGENT_ENV: Readonly<Record<string, string>>;
 /**
- * Builds a public {@link SandboxSession} from provider-specific primitives.
- *
- * Encoding handling, line-range slicing, and the binary/text/stream
- * variants live here so each provider only has to implement byte-oriented
- * read/write primitives. `run` is implemented as a thin wrapper over the
- * provider's `spawn`: collect stdout/stderr to strings, await `wait()`,
- * then return the combined result.
- *
- * Providers without mutable firewall support omit `setNetworkPolicy`; the
- * dedicated Vercel provider wires it to `sandbox.update`.
+ * Builds the {@link SandboxSession} eve hands out from a provider's
+ * connection: every path and working directory resolves from the
+ * connection's workspace root, `run` collects `spawn`, the read and write
+ * variants share the connection's byte primitives, and the connection's
+ * extensions merge on top.
  */
-export declare function buildSandboxSession(primitives: InternalSandboxSession, setNetworkPolicy: (policy: SandboxNetworkPolicy) => Promise<void>): NetworkPolicySandboxSession;
-export declare function buildSandboxSession(primitives: InternalSandboxSession): SandboxSession;
+export declare function createConnectionSession<Extensions extends object>(connection: SandboxConnection<Extensions>): SandboxSession & Extensions;

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

@@ -1,3 +1,3 @@
-import{bufferToStream,streamToBuffer}from"./stream-utils.js";const SANDBOX_AGENT_ENV={AI_AGENT:`eve`};function buildSandboxSession(e,t){async function run(t){let n=await e.spawn(t),[r,i,{exitCode:a}]=await Promise.all([collectStreamToString(n.stdout),collectStreamToString(n.stderr),n.wait()]);return{exitCode:a,stderr:i,stdout:r}}let n={resolvePath(t){return e.resolvePath(t)},run,async spawn(t){return await e.spawn(t)},async readFile(t){return await e.readFile({abortSignal:t.abortSignal,path:e.resolvePath(t.path)})},async readBinaryFile(t){let n=await e.readFile({abortSignal:t.abortSignal,path:e.resolvePath(t.path)});return n===null?null:await streamToBuffer(n)},async readTextFile(t){validateReadTextFileOptions(t);let n=await e.readFile({abortSignal:t.abortSignal,path:e.resolvePath(t.path)});return n===null?null:applyLineRange(decodeBytes(await streamToBuffer(n),t.encoding??`utf-8`),t)},async writeFile(t){await e.writeFile({abortSignal:t.abortSignal,content:t.content,path:e.resolvePath(t.path)})},async writeBinaryFile(t){await e.writeFile({abortSignal:t.abortSignal,content:bufferToStream(t.content),path:e.resolvePath(t.path)})},async writeTextFile(t){let n=encodeString(t.content,t.encoding??`utf-8`);await e.writeFile({abortSignal:t.abortSignal,content:bufferToStream(n),path:e.resolvePath(t.path)})},async removePath(t){await e.removePath({abortSignal:t.abortSignal,force:t.force,path:e.resolvePath(t.path),recursive:t.recursive})}};return t===void 0?n:{...n,setNetworkPolicy:t}}async function collectStreamToString(e){let t=await streamToBuffer(e);return new TextDecoder().decode(t)}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]===`
+import{bufferToStream,streamToBuffer}from"./stream-utils.js";import{posix}from"node:path";import{WORKSPACE_ROOT}from"#runtime/workspace/types.js";const SANDBOX_AGENT_ENV={AI_AGENT:`eve`};function createConnectionSession(e){let t=e.workspaceRoot??WORKSPACE_ROOT;if(!posix.isAbsolute(t))throw Error(`Sandbox connection workspaceRoot must be an absolute path, but received "${t}".`);let resolveSandboxPath=e=>posix.resolve(t,e);async function read(t){return await e.readFile({abortSignal:t.abortSignal,path:resolveSandboxPath(t.path)})}async function readBytes(e){let t=await read(e);return t===null?null:ArrayBuffer.isView(t)?Buffer.from(t):await streamToBuffer(t)}async function write(t,n){await e.writeFiles({abortSignal:t.abortSignal,files:[{content:n,path:resolveSandboxPath(t.path)}]})}async function spawn(t){return await e.spawn({abortSignal:t.abortSignal,command:t.command,env:t.env??{},workingDirectory:resolveSandboxPath(t.workingDirectory??`.`)})}let n={resolvePath:resolveSandboxPath,async run(e){let t=await spawn(e),[n,r,{exitCode:i}]=await Promise.all([collectStreamToString(t.stdout),collectStreamToString(t.stderr),t.wait()]);return{exitCode:i,stderr:r,stdout:n}},spawn,async readFile(e){let t=await read(e);return t===null||!ArrayBuffer.isView(t)?t:bufferToStream(new Uint8Array(t.buffer,t.byteOffset,t.byteLength))},readBinaryFile:e=>readBytes(e),async readTextFile(e){validateReadTextFileOptions(e);let t=await readBytes(e);return t===null?null:applyLineRange(decodeBytes(t,e.encoding??`utf-8`),e)},async writeFile(e){await write(e,await streamToBuffer(e.content))},async writeBinaryFile(e){await write(e,Buffer.from(e.content))},async writeTextFile(e){let t=e.encoding??`utf-8`;await write(e,Buffer.from(e.content,t))},async writeFiles(t){await e.writeFiles({abortSignal:t.abortSignal,files:t.files.map(e=>({content:e.content,path:resolveSandboxPath(e.path)}))})},async removePath(t){await e.removePath({abortSignal:t.abortSignal,force:t.force,path:resolveSandboxPath(t.path),recursive:t.recursive})}},r=e.extensions??{},i=Object.keys(r).filter(e=>Object.hasOwn(n,e)||e===`delete`||e===`stop`);if(i.length>0)throw Error(`Sandbox connection extensions cannot replace the session members eve provides: ${i.join(`, `)}. Rename them.`);return{...r,...n}}async function collectStreamToString(e){let t=await streamToBuffer(e);return new TextDecoder().decode(t)}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{SANDBOX_AGENT_ENV,buildSandboxSession};
+`&&(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)}export{SANDBOX_AGENT_ENV,createConnectionSession};

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

@@ -1 +1 @@
-import{getWorkflowMetadata}from"#compiled/@workflow/core/index.js";import{isWorkflowMessage}from"#execution/session-inbox/inbox.js";import{SessionInboxPayloadError,decodeSessionInboxPayload}from"#execution/session-inbox/protocol.js";import{reportDroppedWirePayloadStep}from"#execution/report-dropped-wire-payload-step.js";async function admitSessionInboxPayload(e,t){if(e.kind===`session-failure`)throw Error(e.error);if(e.kind===`runtime-action-result`)return{kind:`runtime-action-result`,payload:e};if(isWorkflowMessage(e))return{kind:`workflow`,message:e};if(e.kind===`authorization-callback`)return t.queue.enqueueAuthorization(e.payloads),{kind:`consumed`};if(e.kind===`subagent-input-request`||e.kind===`subagent-authorization-event`)return{kind:`consumed`};let n;try{n=decodeSessionInboxPayload(e)}catch(e){if(!(e instanceof SessionInboxPayloadError))throw e;return await reportDroppedWirePayloadStep({detail:e.message,family:`session-inbox`}),{kind:`consumed`}}switch(n.kind){case`deliver`:{let e=t.queue.enqueueDelivery(n);return e===void 0?{kind:`consumed`}:{admission:e,kind:`delivery`}}case`clear`:case`compact`:return t.queue.enqueueControl(n.kind),{kind:`consumed`};case`session-timeout`:return n.ownerRunId===getWorkflowMetadata().workflowRunId&&t.queue.enqueueControl(`expired`),{kind:`consumed`};case`reset`:return t.queue.enqueueControl(`reset`),{kind:`cancel`};case`cancel`:return{kind:`cancel`}}}export{admitSessionInboxPayload};
+import{getWorkflowMetadata}from"#compiled/@workflow/core/index.js";import{isWorkflowMessage}from"#execution/session-inbox/inbox.js";import{SessionInboxPayloadError,decodeSessionInboxPayload}from"#execution/session-inbox/protocol.js";import{reportDroppedWirePayloadStep}from"#execution/report-dropped-wire-payload-step.js";async function admitSessionInboxPayload(e,t){if(e.kind===`session-failure`)throw Error(e.error);if(e.kind===`runtime-action-result`)return{kind:`runtime-action-result`,payload:e};if(isWorkflowMessage(e))return{kind:`workflow`,message:e};if(e.kind===`authorization-callback`)return t.queue.enqueueAuthorization(e.payloads),{kind:`consumed`};if(e.kind===`subagent-input-request`||e.kind===`subagent-authorization-event`)return{kind:`consumed`};let n;try{n=decodeSessionInboxPayload(e)}catch(e){if(!(e instanceof SessionInboxPayloadError))throw e;return await reportDroppedWirePayloadStep({detail:e.message,family:`session-inbox`}),{kind:`consumed`}}switch(n.kind){case`session-prewarm`:return n.expectedOwnerRunId===getWorkflowMetadata().workflowRunId&&t.queue.prepareOnDeployment(n.targetDeploymentId),{kind:`consumed`};case`deliver`:{let e=t.queue.enqueueDelivery(n);return e===void 0?{kind:`consumed`}:{admission:e,kind:`delivery`}}case`clear`:case`compact`:return t.queue.enqueueControl(n.kind),{kind:`consumed`};case`session-timeout`:return n.ownerRunId===getWorkflowMetadata().workflowRunId&&t.queue.enqueueControl(`expired`),{kind:`consumed`};case`reset`:return t.queue.enqueueControl(`reset`),{kind:`cancel`};case`cancel`:return{kind:`cancel`}}}export{admitSessionInboxPayload};

package/dist/src/execution/session/checkpoint-migrations.js

@@ -1 +1 @@
-import{initialSessionProjection}from"#protocol/session-projection.js";import{isObject}from"#shared/guards.js";import{DELIVERY_IDEMPOTENCY_WINDOW,MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH}from"#channel/delivery-idempotency.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{SESSION_CHECKPOINT_VERSION}from"#execution/session/handoff.js";import{LEGACY_HITL_STATE_KEYS,upgradeLegacyHitlState}from"#harness/hitl/requests.js";const MIN_SESSION_CHECKPOINT_VERSION=8,CHECKPOINT_UPGRADES={8:e=>{let{mode:t,...n}=e;return{...n,serializedContext:omitKeys(readRecord(n,`serializedContext`),[`eve.mode`])}},9:(e,t)=>{let n=readRecord(e,`sessionState`),r=readRecord(n,`snapshot`),{taskId:i,...a}=readRecord(r,`session`);return{...e,serializedContext:upgradeLegacyCaller(omitKeys(readRecord(e,`serializedContext`),[`eve.activityObserver`,`eve.activityPendingBlockers`,`eve.activityRootTurnId`,`eve.connectionSearchResults`,`eve.internal.backgroundToolExecution`,`eve.runtime.taskDeliveryPolicy`,`eve.turnTaskDelivery`])),sessionState:{...n,snapshot:{...r,session:{...a,history:readArray(a,`history`).map(renameBackgroundTaskMessage),state:upgradeSessionState(a.state,t)}}}}},10:e=>{let t=readRecord(e,`sessionState`),n=readRecord(t,`snapshot`),{history:r,...i}=readRecord(n,`session`);return t.version!==1&&refuse(`durable session version is not 1`),Array.isArray(r)||refuse(`session history is missing`),{...e,history:r,sessionState:{...t,snapshot:{...n,session:i},version:2}}},11:upgradeIdleLifecycle,12:e=>e,13:e=>e,14:e=>{let t=readRecord(e,`sessionState`),n=readRecord(t,`snapshot`),r=readRecord(n,`session`);if(r.state===void 0)return e;let i=upgradeLegacyHitlState(readRecord(r,`state`));return{...e,sessionState:{...t,snapshot:{...n,session:{...r,state:i}}}}},15:e=>({...e,admittedDeliveryKeys:[]})};function migrateSessionCheckpoint(e){if(!isObject(e))return{kind:`incompatible`,detail:`checkpoint is not an object`};let{version:t}=e;if(typeof t!=`number`||!Number.isSafeInteger(t)||t<8||t>SESSION_CHECKPOINT_VERSION)return{kind:`incompatible`,detail:`checkpoint version ${JSON.stringify(t)} is outside the supported range 8-${SESSION_CHECKPOINT_VERSION}`};let n={childRunIdsToStop:[]},r=e;try{for(let e=t;e<SESSION_CHECKPOINT_VERSION;e++){let t=CHECKPOINT_UPGRADES[e];t===void 0&&refuse(`no upgrade from checkpoint version ${e}`),r={...t(r,n),version:e+1}}}catch(e){if(!(e instanceof CheckpointRefusal))throw e;return{kind:`incompatible`,detail:`checkpoint version ${t}: ${e.message}`}}return isCurrentCheckpoint(r)?{kind:`current`,checkpoint:r,childRunIdsToStop:n.childRunIdsToStop}:{kind:`incompatible`,detail:`checkpoint version ${t} is incomplete`}}function upgradeIdleLifecycle(e){let t=readRecord(e,`sessionState`);t.version!==2&&refuse(`durable session version is not 2`);let n=readRecord(t,`snapshot`),r=readRecord(n,`session`),i=r.state===void 0?{}:readRecord(r,`state`),a=i[`eve.harness.emission`]??t.emissionState;(!isObject(a)||typeof a.sessionStarted!=`boolean`||!Number.isSafeInteger(a.sequence)||a.sequence<0||!Number.isSafeInteger(a.stepIndex)||a.stepIndex<0||a.turnId!==``)&&refuse(`lifecycle position is malformed or a turn is still open`),[LEGACY_HITL_STATE_KEYS.signIns,`eve.runtime.pendingInputBatch`,`eve.runtime.pendingCoordinationBatch`,`eve.runtime.deferredStepInput`,`eve.harness.pendingWorkflowInterrupt`].some(e=>i[e]!==void 0)&&refuse(`session holds pending work`);let o=i[`eve.runtime.pendingInputBatches`];o!==void 0&&(!Array.isArray(o)||o.length>0)&&refuse(`session holds pending input`);let s=i[LEGACY_HITL_STATE_KEYS.relays];(t.hasProxyInputRequests!==!1||s!==void 0&&(!isObject(s)||Object.keys(s).length>0))&&refuse(`session holds relayed input`);try{getBlockingWorkflowToolRuns(i).length>0&&refuse(`session holds workflow runs`)}catch(e){if(e instanceof CheckpointRefusal)throw e;refuse(`workflow tool run registry is incompatible`)}let c=i[LEGACY_HITL_STATE_KEYS.approvals];c!==void 0&&(!isObject(c)||!isObject(c.activeCandidates)||Object.keys(c.activeCandidates).length>0)&&refuse(`session holds approval candidates or malformed approval state`);let l=i[`eve.runtime.hitl.approvedTools`]??[];(!Array.isArray(l)||!l.every(e=>typeof e==`string`))&&refuse(`approval grants are malformed`),(i[`eve.harness.turnState`]!==void 0||i[`eve.harness.sessionProjection`]!==void 0)&&refuse(`v11 checkpoint already contains machine state`);let u={...initialSessionProjection(),nextSequence:a.sequence};a.sessionStarted&&(u.started=!0);let d={...omitKeys(i,[`eve.harness.emission`,`eve.runtime.hitl.approvedTools`,`eve.runtime.pendingInputBatches`]),"eve.harness.sessionProjection":u};l.length>0&&(d[`eve.harness.turnState`]={grants:[...l],suspended:[]});let{emissionState:f,...p}=t;return{...e,sessionState:{...p,snapshot:{...n,session:{...r,state:d}}}}}function isCurrentCheckpoint(e){return isObject(e)&&e.version===SESSION_CHECKPOINT_VERSION&&Array.isArray(e.admittedDeliveryKeys)&&e.admittedDeliveryKeys.length<=DELIVERY_IDEMPOTENCY_WINDOW&&e.admittedDeliveryKeys.every(e=>typeof e==`string`&&e.length>0&&e.length<=MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH)&&Array.isArray(e.history)&&isObject(e.serializedContext)&&isObject(e.sessionState)}var CheckpointRefusal=class extends Error{};function refuse(e){throw new CheckpointRefusal(e)}function readRecord(e,t){let n=e[t];return isObject(n)||refuse(`${t} is not an object`),n}function readArray(e,t){let n=e[t];return Array.isArray(n)||refuse(`${t} is not an array`),n}function omitKeys(e,t){return Object.fromEntries(Object.entries(e).filter(([e])=>!t.includes(e)))}function upgradeLegacyCaller(e){let t=e[`eve.sessionCallback`];if(!isObject(t))return e;let{taskId:n,...r}=t;return{...e,"eve.legacyRemoteAgentCaller":typeof n==`string`&&n.length>0?{taskId:n}:{},"eve.sessionCallback":r}}function renameBackgroundTaskMessage(e){return isObject(e)&&e.role===`user`&&e.kind===`execution.background_task`?{...e,kind:`task.result`}:e}function upgradeSessionState(e,t){return isObject(e)?omitKeys(e,[...dropSettledWorkflowToolRuns(e),...stopIdleSubagents(e,t)]):e}function dropSettledWorkflowToolRuns(e){let t=e[`eve.workflowTool`];if(!isObject(t)||t.version!==3)return[];let n=t.runs;return(!Array.isArray(n)||!n.every(e=>isObject(e)&&e.lifetime===`session`&&isObject(e.task)&&e.task.outcome!==void 0))&&refuse(`workflow tool run registry version 3 holds unsettled runs`),[`eve.workflowTool`]}function stopIdleSubagents(e,t){let n=e[`eve.agent.handles`];if(n===void 0)return[];(!isObject(n)||!Array.isArray(n.handles))&&refuse(`subagent handles are malformed`);for(let e of n.handles){(!isObject(e)||e.phase!==`parked`&&e.phase!==`available`)&&refuse(`a subagent session is still working`);let n=e.address;isObject(n)&&(n.kind===`agent/local`||n.kind===`agent/self`)&&typeof n.sessionId==`string`&&n.sessionId.length>0&&t.childRunIdsToStop.push(n.sessionId)}return[`eve.agent.handles`]}export{MIN_SESSION_CHECKPOINT_VERSION,migrateSessionCheckpoint};
+import{initialSessionProjection}from"#protocol/session-projection.js";import{isObject}from"#shared/guards.js";import{DELIVERY_IDEMPOTENCY_WINDOW,MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH}from"#channel/delivery-idempotency.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{SESSION_CHECKPOINT_VERSION}from"#execution/session/handoff.js";import{LEGACY_HITL_STATE_KEYS,upgradeLegacyHitlState}from"#harness/hitl/requests.js";const MIN_SESSION_CHECKPOINT_VERSION=8,CHECKPOINT_UPGRADES={8:e=>{let{mode:t,...n}=e;return{...n,serializedContext:omitKeys(readRecord(n,`serializedContext`),[`eve.mode`])}},9:(e,t)=>{let n=readRecord(e,`sessionState`),r=readRecord(n,`snapshot`),{taskId:i,...a}=readRecord(r,`session`);return{...e,serializedContext:upgradeLegacyCaller(omitKeys(readRecord(e,`serializedContext`),[`eve.activityObserver`,`eve.activityPendingBlockers`,`eve.activityRootTurnId`,`eve.connectionSearchResults`,`eve.internal.backgroundToolExecution`,`eve.runtime.taskDeliveryPolicy`,`eve.turnTaskDelivery`])),sessionState:{...n,snapshot:{...r,session:{...a,history:readArray(a,`history`).map(renameBackgroundTaskMessage),state:upgradeSessionState(a.state,t)}}}}},10:e=>{let t=readRecord(e,`sessionState`),n=readRecord(t,`snapshot`),{history:r,...i}=readRecord(n,`session`);return t.version!==1&&refuse(`durable session version is not 1`),Array.isArray(r)||refuse(`session history is missing`),{...e,history:r,sessionState:{...t,snapshot:{...n,session:i},version:2}}},11:upgradeIdleLifecycle,12:e=>e,13:e=>e,14:e=>{let t=readRecord(e,`sessionState`),n=readRecord(t,`snapshot`),r=readRecord(n,`session`);if(r.state===void 0)return e;let i=upgradeLegacyHitlState(readRecord(r,`state`));return{...e,sessionState:{...t,snapshot:{...n,session:{...r,state:i}}}}},15:e=>({...e,admittedDeliveryKeys:[]}),16:e=>e};function migrateSessionCheckpoint(e){if(!isObject(e))return{kind:`incompatible`,detail:`checkpoint is not an object`};let{version:t}=e;if(typeof t!=`number`||!Number.isSafeInteger(t)||t<8||t>SESSION_CHECKPOINT_VERSION)return{kind:`incompatible`,detail:`checkpoint version ${JSON.stringify(t)} is outside the supported range 8-${SESSION_CHECKPOINT_VERSION}`};let n={childRunIdsToStop:[]},r=e;try{for(let e=t;e<SESSION_CHECKPOINT_VERSION;e++){let t=CHECKPOINT_UPGRADES[e];t===void 0&&refuse(`no upgrade from checkpoint version ${e}`),r={...t(r,n),version:e+1}}}catch(e){if(!(e instanceof CheckpointRefusal))throw e;return{kind:`incompatible`,detail:`checkpoint version ${t}: ${e.message}`}}return isCurrentCheckpoint(r)?{kind:`current`,checkpoint:r,childRunIdsToStop:n.childRunIdsToStop}:{kind:`incompatible`,detail:`checkpoint version ${t} is incomplete`}}function upgradeIdleLifecycle(e){let t=readRecord(e,`sessionState`);t.version!==2&&refuse(`durable session version is not 2`);let n=readRecord(t,`snapshot`),r=readRecord(n,`session`),i=r.state===void 0?{}:readRecord(r,`state`),a=i[`eve.harness.emission`]??t.emissionState;(!isObject(a)||typeof a.sessionStarted!=`boolean`||!Number.isSafeInteger(a.sequence)||a.sequence<0||!Number.isSafeInteger(a.stepIndex)||a.stepIndex<0||a.turnId!==``)&&refuse(`lifecycle position is malformed or a turn is still open`),[LEGACY_HITL_STATE_KEYS.signIns,`eve.runtime.pendingInputBatch`,`eve.runtime.pendingCoordinationBatch`,`eve.runtime.deferredStepInput`,`eve.harness.pendingWorkflowInterrupt`].some(e=>i[e]!==void 0)&&refuse(`session holds pending work`);let o=i[`eve.runtime.pendingInputBatches`];o!==void 0&&(!Array.isArray(o)||o.length>0)&&refuse(`session holds pending input`);let s=i[LEGACY_HITL_STATE_KEYS.relays];(t.hasProxyInputRequests!==!1||s!==void 0&&(!isObject(s)||Object.keys(s).length>0))&&refuse(`session holds relayed input`);try{getBlockingWorkflowToolRuns(i).length>0&&refuse(`session holds workflow runs`)}catch(e){if(e instanceof CheckpointRefusal)throw e;refuse(`workflow tool run registry is incompatible`)}let c=i[LEGACY_HITL_STATE_KEYS.approvals];c!==void 0&&(!isObject(c)||!isObject(c.activeCandidates)||Object.keys(c.activeCandidates).length>0)&&refuse(`session holds approval candidates or malformed approval state`);let l=i[`eve.runtime.hitl.approvedTools`]??[];(!Array.isArray(l)||!l.every(e=>typeof e==`string`))&&refuse(`approval grants are malformed`),(i[`eve.harness.turnState`]!==void 0||i[`eve.harness.sessionProjection`]!==void 0)&&refuse(`v11 checkpoint already contains machine state`);let u={...initialSessionProjection(),nextSequence:a.sequence};a.sessionStarted&&(u.started=!0);let d={...omitKeys(i,[`eve.harness.emission`,`eve.runtime.hitl.approvedTools`,`eve.runtime.pendingInputBatches`]),"eve.harness.sessionProjection":u};l.length>0&&(d[`eve.harness.turnState`]={grants:[...l],suspended:[]});let{emissionState:f,...p}=t;return{...e,sessionState:{...p,snapshot:{...n,session:{...r,state:d}}}}}function isCurrentCheckpoint(e){return isObject(e)&&e.version===SESSION_CHECKPOINT_VERSION&&Array.isArray(e.admittedDeliveryKeys)&&e.admittedDeliveryKeys.length<=DELIVERY_IDEMPOTENCY_WINDOW&&e.admittedDeliveryKeys.every(e=>typeof e==`string`&&e.length>0&&e.length<=MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH)&&Array.isArray(e.history)&&isObject(e.serializedContext)&&isObject(e.sessionState)}var CheckpointRefusal=class extends Error{};function refuse(e){throw new CheckpointRefusal(e)}function readRecord(e,t){let n=e[t];return isObject(n)||refuse(`${t} is not an object`),n}function readArray(e,t){let n=e[t];return Array.isArray(n)||refuse(`${t} is not an array`),n}function omitKeys(e,t){return Object.fromEntries(Object.entries(e).filter(([e])=>!t.includes(e)))}function upgradeLegacyCaller(e){let t=e[`eve.sessionCallback`];if(!isObject(t))return e;let{taskId:n,...r}=t;return{...e,"eve.legacyRemoteAgentCaller":typeof n==`string`&&n.length>0?{taskId:n}:{},"eve.sessionCallback":r}}function renameBackgroundTaskMessage(e){return isObject(e)&&e.role===`user`&&e.kind===`execution.background_task`?{...e,kind:`task.result`}:e}function upgradeSessionState(e,t){return isObject(e)?omitKeys(e,[...dropSettledWorkflowToolRuns(e),...stopIdleSubagents(e,t)]):e}function dropSettledWorkflowToolRuns(e){let t=e[`eve.workflowTool`];if(!isObject(t)||t.version!==3)return[];let n=t.runs;return(!Array.isArray(n)||!n.every(e=>isObject(e)&&e.lifetime===`session`&&isObject(e.task)&&e.task.outcome!==void 0))&&refuse(`workflow tool run registry version 3 holds unsettled runs`),[`eve.workflowTool`]}function stopIdleSubagents(e,t){let n=e[`eve.agent.handles`];if(n===void 0)return[];(!isObject(n)||!Array.isArray(n.handles))&&refuse(`subagent handles are malformed`);for(let e of n.handles){(!isObject(e)||e.phase!==`parked`&&e.phase!==`available`)&&refuse(`a subagent session is still working`);let n=e.address;isObject(n)&&(n.kind===`agent/local`||n.kind===`agent/self`)&&typeof n.sessionId==`string`&&n.sessionId.length>0&&t.childRunIdsToStop.push(n.sessionId)}return[`eve.agent.handles`]}export{MIN_SESSION_CHECKPOINT_VERSION,migrateSessionCheckpoint};

package/dist/src/execution/session/entry-input.d.ts

@@ -32,17 +32,18 @@ export type SessionHandoffStart = {
     readonly reason?: undefined;
 } | {
     /**
-     * The previous owner compacted the session and moved it to a fresh run on
-     * its own deployment, so no single run's event log grows with the
-     * session.
+     * The previous owner rotated an idle session after compaction or prepared
+     * it on the deployment accepting the next interaction.
      */
-    readonly reason: "compaction";
+    readonly reason: "compaction" | "prewarm";
     /**
      * Only sources older than version 3 send one: the lone delivery that
      * arrived before they could move, processed first. Without one, the
      * successor parks until the next input arrives.
      */
     readonly delivery?: DeliverHookPayload;
+    /** Proactive preparation preserves the current idle deadline. */
+    readonly sessionTimeoutDeadline?: Date;
 };
 /** A successor owner started by a previous owner during a handoff. */
 export type HandoffWorkflowEntryInput = SessionHandoffStart & {

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

@@ -1 +1 @@
-import{attachClientContext,readClientContext}from"#internal/client-context.js";import{SESSION_INBOX_CONTEXT_KEY,sessionCommandHookToken}from"#execution/session-inbox/address.js";import{readSerializedSessionSchedule}from"#context/session-schedule.js";import{createHook,getWorkflowMetadata,getWritable}from"#compiled/@workflow/core/index.js";import{claimHookOwnership,isHookConflictError}from"#execution/hook-ownership.js";import{DEFAULT_SESSION_TIMEOUT_MS}from"#execution/session/timeout.js";import{sessionHookTokens}from"#execution/session/hook-tokens.js";import{createSessionInbox}from"#execution/session-inbox/inbox.js";import{failSession,runPreparedSession}from"#execution/session/program.js";import{createSessionTimeoutControl}from"#execution/session/timeout-control.js";import{prepareSuccessorStep,signalSessionOwnerActivationStep,stopUntrackedChildSessionsStep}from"#execution/session/handoff-steps.js";import{hasDelegatedSessionContext}from"#execution/delegated-session-context.js";import{readChannelRequestId,readRootSessionId}from"#execution/eve-workflow-attributes.js";import{createTurnControl}from"#execution/session/turn-control.js";import{HANDOFF_LEASE_RETENTION,handoffLeaseToken,sendSessionHandover}from"#execution/session/handoff.js";import{resolveInitialTurnCallerStep}from"#subagents/parent-notification.js";import{normalizeSerializableError}from"#execution/workflow-errors.js";import{createSessionStep}from"#execution/create-session-step.js";import{settleContinuationConflictStep}from"#execution/continuation-conflict-step.js";import{migrateSessionCheckpoint}from"#execution/session/checkpoint-migrations.js";import{abandonHandoverIfRunEnds,watchRunEnd}from"#execution/session/run-watch.js";async function workflowEntry(e){"use workflow";let t=e.kind===`initial`?await bootInitialOwner(e,getWorkflowMetadata().workflowRunId):(e.handoffVersion??0)>=3?await bootForcedHandoffOwner(e):await bootReleasedHandoffOwner(e);return t===void 0?{output:``}:{output:(await runPreparedSession(t.session,t.inbox)).output}}function stampSessionIdentity(e,t){return{...e,"eve.sessionId":t,[SESSION_INBOX_CONTEXT_KEY]:{sessionId:t}}}async function prepareInitialOwner(e,t){let[n,r]=await Promise.allSettled([e.claimSessionHook(sessionCommandHookToken(t.sessionId)),t.continuationToken===``?Promise.resolve():e.claimSessionHook(t.continuationToken)]);if(n.status===`rejected`)throw n.reason;if(r.status===`rejected`){if(isHookConflictError(r.reason))return{kind:`alias-conflict`};throw r.reason}let i=createTurnControl(),a=createSessionTimeoutControl({sessionId:t.sessionId,timeoutMs:t.sessionTimeoutMs}),o={kind:`owned`,timeoutControl:a,turnControl:i,async dispose(){i.dispose(),await a?.dispose()}};return a?.start().catch(()=>{}),o}function unwrapSettled(e){if(e.status===`rejected`)throw e.reason;return e.value}async function disposeInitialBoot(e,t){let[n,r]=await Promise.allSettled([t?.dispose(),e.dispose()]);if(n.status===`rejected`)throw n.reason;if(r.status===`rejected`)throw r.reason}async function bootInitialOwner(e,t){let n=stampSessionIdentity(e.serializedContext,t),r=getWritable(),i=createSessionInbox(t),a=e.sessionTimeoutMs??DEFAULT_SESSION_TIMEOUT_MS,o=n[`eve.continuationToken`]||``,s=n[`eve.bundle`],c;try{let l=createSessionStep({agentSessionRuntimeOverrides:n[`eve.agentSessionRuntimeOverrides`],compiledArtifactsSource:s.source,continuationToken:o,dynamicSubagentAgentConfig:n[`eve.dynamicSubagentAgentConfig`],history:e.input.message===void 0?e.input.history:void 0,nodeId:s.nodeId,outputSchema:e.input.outputSchema,rootSessionId:readRootSessionId(n),sessionId:t}),u=prepareInitialOwner(i,{continuationToken:o,sessionId:t,sessionTimeoutMs:a}),d=hasDelegatedSessionContext(n)?resolveInitialTurnCallerStep({serializedContext:n}):Promise.resolve(void 0),[f,p,m]=await Promise.allSettled([l,u,d]);p.status===`fulfilled`&&p.value.kind===`owned`&&(c=p.value);let h=unwrapSettled(f),g=unwrapSettled(p);if(g.kind===`alias-conflict`){e.continuationConflictCommand!==void 0&&await settleContinuationConflictStep({command:e.continuationConflictCommand,continuationToken:o}),await disposeInitialBoot(i,c);return}let _=unwrapSettled(m);return{inbox:i,session:{admittedDeliveryKeys:e.idempotencyKey===void 0?[]:[e.idempotencyKey],anchor:{kind:`self`},caller:_,capabilities:n[`eve.capabilities`],deploymentId:e.ownerDeploymentId,history:h.history,start:e.input.message===void 0?{kind:`first-message`}:{input:createInitialDelivery(e,n),kind:`turn`},initialTurnControl:g.turnControl,retention:e.retention,serializedContext:n,sessionId:t,sessionState:h.state,sessionTimeoutControl:g.timeoutControl,sessionTimeoutMs:a,sessionWritable:r}}}catch(e){return await disposeInitialBoot(i,c),await failSession({error:e,serializedContext:n,sessionId:t,sessionState:void 0,sessionWritable:r})}}async function prepareSuccessor(e,t){let{sessionId:n}=e,r=migrateSessionCheckpoint(e.checkpoint),i=await prepareSuccessorStep({handoffVersion:e.handoffVersion,migration:r,sessionId:n,...t!==void 0&&{source:t}});if(r.kind===`incompatible`||i.kind===`incompatible`){await signalSessionOwnerActivationStep({activation:{kind:`incompatible`,payloads:[],reason:`checkpoint-version`,runId:getWorkflowMetadata().workflowRunId},token:e.activationToken});return}if(i.kind===`source-gone`){await signalFailedActivation(e,Error(`The session's previous owner no longer holds all of its addresses.`),{payloads:[]});return}let{checkpoint:a,childRunIdsToStop:o}=r;return{checkpoint:a,childRunIdsToStop:o,serializedContext:stampSessionIdentity(a.serializedContext,n)}}async function signalFailedActivation(e,t,n){await signalSessionOwnerActivationStep({activation:{error:normalizeSerializableError(t),kind:`failed`,runId:getWorkflowMetadata().workflowRunId,...n},token:e.activationToken})}async function bootForcedHandoffOwner(e){let{attemptKey:t,hookTokens:n,sessionId:r,sourceRunId:i}=e;if(t===void 0||n===void 0||i===void 0){await signalFailedActivation(e,Error(`Session handoff version 3 input is missing attemptKey, hookTokens, or sourceRunId.`),{payloads:[]});return}try{let e=createHook({experimental_minRetention:HANDOFF_LEASE_RETENTION,token:handoffLeaseToken(t)});await claimHookOwnership(e)}catch(t){if(isHookConflictError(t))return;await signalFailedActivation(e,t,{payloads:[]});return}let a;try{a=await prepareSuccessor(e,{hookTokens:n,runId:i})}catch(t){await signalFailedActivation(e,t,{payloads:[]});return}if(a===void 0)return;let o=createSessionInbox(r);try{await o.claimSessionHooks(n,{force:!0,handover:t})}catch(n){let a=o.claimedTokens.length>0;await signalFailedActivation(e,n,{claimedHooks:a,payloads:[]}),a&&await handBack(o,{attemptKey:t,sessionId:r,sourceRunId:i}),await o.dispose();return}return abandonHandoverIfRunEnds(o,{attemptKey:t,sourceRunId:i}),await startSuccessor(e,o,a)}async function handBack(e,t){let n=watchRunEnd(t.sourceRunId),r=new AbortController;try{if(await Promise.race([e.whenTakenOver(r.signal).then(()=>`taken-back`),n.ended.then(()=>`source-ended`)])===`source-ended`)return}finally{n.stop(),r.abort()}await sendSessionHandover({attemptKey:t.attemptKey,payloads:e.drain(),sessionId:t.sessionId})}async function bootReleasedHandoffOwner(e){let t=createSessionInbox(e.sessionId),n;try{if(n=await prepareSuccessor(e),n===void 0)return;await t.claimSessionHooks(sessionHookTokens({serializedContext:n.serializedContext,sessionState:n.checkpoint.sessionState})),await signalSessionOwnerActivationStep({activation:{kind:`active`},token:e.activationToken})}catch(n){await signalFailedActivation(e,n,{payloads:await t.release()});return}return await startSuccessor(e,t,n)}async function startSuccessor(e,t,n){let{sessionId:r}=e,{checkpoint:i,childRunIdsToStop:a,serializedContext:o}=n;return a.length>0&&await stopUntrackedChildSessionsStep({runIds:a,sessionId:r}),{inbox:t,session:{anchor:{kind:`successor`},admittedDeliveryKeys:i.admittedDeliveryKeys,caller:e.delivery?.caller,capabilities:i.capabilities,deploymentId:e.ownerDeploymentId,history:i.history,start:e.delivery===void 0?{kind:`parked`}:{input:e.delivery,kind:`turn`},retention:i.retention,serializedContext:o,sessionId:r,sessionState:i.sessionState,sessionTimeoutControl:createSessionTimeoutControl({sessionId:r,timeoutMs:i.sessionTimeoutMs}),sessionTimeoutMs:i.sessionTimeoutMs,sessionWritable:e.sessionWritable}}}function createInitialDelivery(e,t){if(e.input.message!==void 0)return{idempotencyKey:e.idempotencyKey,schedule:readSerializedSessionSchedule(t),deliveryMetadata:t[`eve.channelDelivery`]===void 0?void 0:[{...t[`eve.channelDelivery`],payloadIndex:0}],kind:`deliver`,payloads:[attachClientContext({message:e.input.message,context:e.input.context,history:e.input.history,outputSchema:e.input.outputSchema,state:e.input.state},readClientContext(e.input))],requestId:readChannelRequestId(t)}}workflowEntry.workflowId=`workflow//eve//workflowEntry`;export{bootInitialOwner,workflowEntry};
+import{attachClientContext,readClientContext}from"#internal/client-context.js";import{SESSION_INBOX_CONTEXT_KEY,sessionCommandHookToken}from"#execution/session-inbox/address.js";import{readSerializedSessionSchedule}from"#context/session-schedule.js";import{createHook,getWorkflowMetadata,getWritable}from"#compiled/@workflow/core/index.js";import{claimHookOwnership,isHookConflictError}from"#execution/hook-ownership.js";import{DEFAULT_SESSION_TIMEOUT_MS}from"#execution/session/timeout.js";import{sessionHookTokens}from"#execution/session/hook-tokens.js";import{createSessionInbox}from"#execution/session-inbox/inbox.js";import{failSession,runPreparedSession}from"#execution/session/program.js";import{createSessionTimeoutControl}from"#execution/session/timeout-control.js";import{prepareSuccessorStep,signalSessionOwnerActivationStep,stopUntrackedChildSessionsStep}from"#execution/session/handoff-steps.js";import{hasDelegatedSessionContext}from"#execution/delegated-session-context.js";import{readChannelRequestId,readRootSessionId}from"#execution/eve-workflow-attributes.js";import{createTurnControl}from"#execution/session/turn-control.js";import{HANDOFF_LEASE_RETENTION,handoffLeaseToken,sendSessionHandover}from"#execution/session/handoff.js";import{resolveInitialTurnCallerStep}from"#subagents/parent-notification.js";import{normalizeSerializableError}from"#execution/workflow-errors.js";import{createSessionStep}from"#execution/create-session-step.js";import{settleContinuationConflictStep}from"#execution/continuation-conflict-step.js";import{migrateSessionCheckpoint}from"#execution/session/checkpoint-migrations.js";import{abandonHandoverIfRunEnds,watchRunEnd}from"#execution/session/run-watch.js";async function workflowEntry(e){"use workflow";let t=e.kind===`initial`?await bootInitialOwner(e,getWorkflowMetadata().workflowRunId):(e.handoffVersion??0)>=3?await bootForcedHandoffOwner(e):await bootReleasedHandoffOwner(e);return t===void 0?{output:``}:{output:(await runPreparedSession(t.session,t.inbox)).output}}function stampSessionIdentity(e,t){return{...e,"eve.sessionId":t,[SESSION_INBOX_CONTEXT_KEY]:{sessionId:t}}}async function prepareInitialOwner(e,t){let n={kind:`owned`,timeoutControl:createSessionTimeoutControl({sessionId:t.sessionId,timeoutMs:t.sessionTimeoutMs}),turnControl:createTurnControl()},r={confirmAfter:t.sessionCreation},[i,a]=await Promise.allSettled([e.claimSessionHook(sessionCommandHookToken(t.sessionId),r),t.continuationToken===``?Promise.resolve():e.claimSessionHook(t.continuationToken,r)]);if(i.status===`rejected`)throw i.reason;if(a.status===`rejected`){if(isHookConflictError(a.reason))return{kind:`alias-conflict`};throw a.reason}return n}function unwrapSettled(e){if(e.status===`rejected`)throw e.reason;return e.value}async function bootInitialOwner(e,t){let n=stampSessionIdentity(e.serializedContext,t),r=getWritable(),i=createSessionInbox(t),a=e.sessionTimeoutMs??DEFAULT_SESSION_TIMEOUT_MS,o=n[`eve.continuationToken`]||``,s=n[`eve.bundle`];try{let c=createSessionStep({agentSessionRuntimeOverrides:n[`eve.agentSessionRuntimeOverrides`],compiledArtifactsSource:s.source,continuationToken:o,dynamicSubagentAgentConfig:n[`eve.dynamicSubagentAgentConfig`],history:e.input.message===void 0?e.input.history:void 0,nodeId:s.nodeId,outputSchema:e.input.outputSchema,rootSessionId:readRootSessionId(n),sessionId:t}),l=prepareInitialOwner(i,{continuationToken:o,sessionCreation:c,sessionId:t,sessionTimeoutMs:a}),u=hasDelegatedSessionContext(n)?resolveInitialTurnCallerStep({serializedContext:n}):Promise.resolve(void 0),[d,f,p]=await Promise.allSettled([c,l,u]),m=unwrapSettled(d),h=unwrapSettled(f);if(h.kind===`alias-conflict`){e.continuationConflictCommand!==void 0&&await settleContinuationConflictStep({command:e.continuationConflictCommand,continuationToken:o}),await i.dispose();return}let g=unwrapSettled(p);return{inbox:i,session:{admittedDeliveryKeys:e.idempotencyKey===void 0?[]:[e.idempotencyKey],anchor:{kind:`self`},caller:g,capabilities:n[`eve.capabilities`],deploymentId:e.ownerDeploymentId,history:m.history,start:e.input.message===void 0?{kind:`first-message`}:{input:createInitialDelivery(e,n),kind:`turn`},initialTurnControl:h.turnControl,retention:e.retention,serializedContext:n,sessionId:t,sessionState:m.state,sessionTimeoutControl:h.timeoutControl,sessionTimeoutMs:a,sessionWritable:r}}}catch(e){return await i.dispose(),await failSession({error:e,serializedContext:n,sessionId:t,sessionState:void 0,sessionWritable:r})}}async function prepareSuccessor(e,t){let{sessionId:n}=e,r=migrateSessionCheckpoint(e.checkpoint),i=await prepareSuccessorStep({handoffVersion:e.handoffVersion,migration:r,sessionId:n,...t!==void 0&&{source:t}});if(r.kind===`incompatible`||i.kind===`incompatible`){await signalSessionOwnerActivationStep({activation:{kind:`incompatible`,payloads:[],reason:`checkpoint-version`,runId:getWorkflowMetadata().workflowRunId},token:e.activationToken});return}if(i.kind===`source-gone`){await signalFailedActivation(e,Error(`The session's previous owner no longer holds all of its addresses.`),{payloads:[]});return}let{checkpoint:a,childRunIdsToStop:o}=r;return{checkpoint:a,childRunIdsToStop:o,serializedContext:stampSessionIdentity(a.serializedContext,n)}}async function signalFailedActivation(e,t,n){await signalSessionOwnerActivationStep({activation:{error:normalizeSerializableError(t),kind:`failed`,runId:getWorkflowMetadata().workflowRunId,...n},token:e.activationToken})}async function bootForcedHandoffOwner(e){let{attemptKey:t,hookTokens:n,sessionId:r,sourceRunId:i}=e;if(t===void 0||n===void 0||i===void 0){await signalFailedActivation(e,Error(`Session handoff version 3 input is missing attemptKey, hookTokens, or sourceRunId.`),{payloads:[]});return}try{let e=createHook({experimental_minRetention:HANDOFF_LEASE_RETENTION,token:handoffLeaseToken(t)});await claimHookOwnership(e)}catch(t){if(isHookConflictError(t))return;await signalFailedActivation(e,t,{payloads:[]});return}let a;try{a=await prepareSuccessor(e,{hookTokens:n,runId:i})}catch(t){await signalFailedActivation(e,t,{payloads:[]});return}if(a===void 0)return;let o=createSessionInbox(r);try{await o.claimSessionHooks(n,{force:!0,handover:t})}catch(n){let a=o.claimedTokens.length>0;await signalFailedActivation(e,n,{claimedHooks:a,payloads:[]}),a&&await handBack(o,{attemptKey:t,sessionId:r,sourceRunId:i}),await o.dispose();return}return abandonHandoverIfRunEnds(o,{attemptKey:t,sourceRunId:i}),await startSuccessor(e,o,a)}async function handBack(e,t){let n=watchRunEnd(t.sourceRunId),r=new AbortController;try{if(await Promise.race([e.whenTakenOver(r.signal).then(()=>`taken-back`),n.ended.then(()=>`source-ended`)])===`source-ended`)return}finally{n.stop(),r.abort()}await sendSessionHandover({attemptKey:t.attemptKey,payloads:e.drain(),sessionId:t.sessionId})}async function bootReleasedHandoffOwner(e){let t=createSessionInbox(e.sessionId),n;try{if(n=await prepareSuccessor(e),n===void 0)return;await t.claimSessionHooks(sessionHookTokens({serializedContext:n.serializedContext,sessionState:n.checkpoint.sessionState})),await signalSessionOwnerActivationStep({activation:{kind:`active`},token:e.activationToken})}catch(n){await signalFailedActivation(e,n,{payloads:await t.release()});return}return await startSuccessor(e,t,n)}async function startSuccessor(e,t,n){let{sessionId:r}=e,{checkpoint:i,childRunIdsToStop:a,serializedContext:o}=n;return a.length>0&&await stopUntrackedChildSessionsStep({runIds:a,sessionId:r}),{inbox:t,session:{anchor:{kind:`successor`},admittedDeliveryKeys:i.admittedDeliveryKeys,caller:e.delivery?.caller,capabilities:i.capabilities,deploymentId:e.ownerDeploymentId,history:i.history,start:e.delivery===void 0?{kind:`parked`}:{input:e.delivery,kind:`turn`},retention:i.retention,serializedContext:o,sessionId:r,sessionState:i.sessionState,sessionTimeoutControl:createSessionTimeoutControl({deadline:e.reason===`prewarm`?e.sessionTimeoutDeadline:void 0,sessionId:r,timeoutMs:i.sessionTimeoutMs}),sessionTimeoutMs:i.sessionTimeoutMs,sessionWritable:e.sessionWritable}}}function createInitialDelivery(e,t){if(e.input.message!==void 0)return{idempotencyKey:e.idempotencyKey,schedule:readSerializedSessionSchedule(t),deliveryMetadata:t[`eve.channelDelivery`]===void 0?void 0:[{...t[`eve.channelDelivery`],payloadIndex:0}],kind:`deliver`,payloads:[attachClientContext({message:e.input.message,context:e.input.context,history:e.input.history,outputSchema:e.input.outputSchema,state:e.input.state},readClientContext(e.input))],requestId:readChannelRequestId(t)}}workflowEntry.workflowId=`workflow//eve//workflowEntry`;export{bootInitialOwner,workflowEntry};

package/dist/src/execution/session/handoff-state.d.ts

@@ -0,0 +1,5 @@
+import type { DurableSessionState } from "#execution/durable-session-store.js";
+/** Parses retained work with this deployment's code before deciding whether it can move. */
+export declare function isSessionStateIdleForHandoff(input: {
+    readonly sessionState: DurableSessionState;
+}): boolean;

package/dist/src/execution/session/handoff-state.js

@@ -0,0 +1 @@
+import{openInputs,openSignIns}from"#protocol/session-projection.js";import{queuedInput,storedProjection}from"#harness/session-machine/view.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{readDurableSession}from"#execution/durable-session-read.js";import{holdsHitlRequests}from"#harness/hitl/view.js";function isSessionStateIdleForHandoff(e){let{state:t}=readDurableSession(e.sessionState),n=getBlockingWorkflowToolRuns(t);if(holdsHitlRequests(t)||[`eve.runtime.pendingInputBatch`,`eve.runtime.pendingCoordinationBatch`,`eve.runtime.deferredStepInput`,`eve.harness.pendingWorkflowInterrupt`].some(e=>t?.[e]!==void 0))return!1;let r=t?.[`eve.runtime.pendingInputBatches`];if(r!==void 0&&(!Array.isArray(r)||r.length>0))return!1;let i=storedProjection(t);return n.length===0&&i.activeTurnId===void 0&&openInputs(i).length===0&&openSignIns(i).length===0&&queuedInput(t)===void 0}export{isSessionStateIdleForHandoff};

package/dist/src/execution/session/handoff-steps.d.ts

@@ -1,12 +1,7 @@
 import type { SessionHandoverPayload } from "#execution/session-inbox/inbox.js";
 import type { SessionCheckpointMigration } from "#execution/session/checkpoint-migrations.js";
-import { type DurableSessionState } from "#execution/durable-session-store.js";
 import { type SessionCheckpoint, type SessionOwnerActivation } from "#execution/session/handoff.js";
 import { type SessionHandoffStart } from "#execution/session/entry-input.js";
-/** Parses retained work with this deployment's code before deciding whether it can move. */
-export declare function isSessionStateIdleForHandoff(input: {
-    readonly sessionState: DurableSessionState;
-}): boolean;
 export type SuccessorStartInput = SessionHandoffStart & {
     readonly activationToken: string;
     /** Original run whose stream stays the public session stream. */
@@ -116,6 +111,7 @@ export declare function reportHandoverPartStuckStep(input: {
  * for the caller to retry until it is delivered.
  */
 export declare function sendSessionHandoverPartStep(input: {
+    readonly bufferedPayloadCount: number;
     readonly part: Omit<SessionHandoverPayload, "kind">;
     readonly sessionId: string;
 }): Promise<"delivered" | "session-ended">;

package/dist/src/execution/session/handoff-steps.js

@@ -1 +1 @@
-import{openInputs,openSignIns}from"#protocol/session-projection.js";import{createLogger,logError}from"#internal/logging.js";import{sessionCommandHookToken,sessionInboxHookToken}from"#execution/session-inbox/address.js";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{walkCauseChain}from"#shared/errors.js";import{getSandboxEnvironmentRuntime}from"#shared/sandbox-environment.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{queuedInput,storedProjection}from"#harness/session-machine/view.js";import{cancelRun,getRun,getWorld,resumeHook}from"#internal/workflow/runtime.js";import{hasRunEnded,startWorkflowOnDeployment,workflowEntryReference}from"#execution/workflow-runtime.js";import{getResolvedRuntimeAgentNode}from"#runtime/graph.js";import{readDurableSession}from"#execution/durable-session-store.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{IncompatibleStateLayoutError,deserializeContext}from"#context/serialize.js";import{holdsHitlRequests}from"#harness/hitl/index.js";import{EntityConflictError,HookNotFoundError,RunExpiredError,WorkflowRunNotFoundError}from"#compiled/@workflow/errors/index.js";import{findSessionHookHolder}from"#execution/session-inbox/owner.js";import{EVE_SESSION_ATTRIBUTE,EVE_VERSION_ATTRIBUTE}from"#execution/eve-workflow-attributes.js";import{SESSION_CHECKPOINT_VERSION}from"#execution/session/handoff.js";import{mapWithConcurrency}from"#shared/map-with-concurrency.js";import{SESSION_HANDOFF_VERSION}from"#execution/session/entry-input.js";const log=createLogger(`execution.handoff`);function isSessionStateIdleForHandoff(e){let{state:t}=readDurableSession(e.sessionState),n=getBlockingWorkflowToolRuns(t);if(holdsHitlRequests(t)||[`eve.runtime.pendingInputBatch`,`eve.runtime.pendingCoordinationBatch`,`eve.runtime.deferredStepInput`,`eve.harness.pendingWorkflowInterrupt`].some(e=>t?.[e]!==void 0))return!1;let r=t?.[`eve.runtime.pendingInputBatches`];if(r!==void 0&&(!Array.isArray(r)||r.length>0))return!1;let i=storedProjection(t);return n.length===0&&i.activeTurnId===void 0&&openInputs(i).length===0&&openSignIns(i).length===0&&queuedInput(t)===void 0}async function startSuccessorStep(e){"use step";let{activationToken:t,anchorRunId:n,checkpoint:r,targetDeploymentId:i,...a}=e,{capabilities:o}=await getWorld();if(o?.hookForceClaim!==!0||o.hookRetention?.active!==!0)return log.warn(`session handoff unavailable: the Workflow world cannot force-claim hooks`,{sessionId:n}),{kind:`unsupported`};if(!isSessionStateIdleForHandoff(r))return{kind:`not-idle`};let s={...a,activationToken:t,checkpoint:r,handoffVersion:SESSION_HANDOFF_VERSION,kind:`handoff`,ownerDeploymentId:i,sessionWritable:getRun(n).getWritable(),sessionId:n};return{kind:`started`,runId:(await startWorkflowOnDeployment(workflowEntryReference,[s],i,r.retention===void 0?void 0:{experimental_retention:r.retention})).runId}}async function hasRunEndedStep(e){"use step";return await hasRunEnded(e.runId)}async function prepareSuccessorStep(e){"use step";let{migration:t}=e,unreadable=t=>(log.warn(`session handoff refused: this deployment cannot read the checkpoint`,{detail:t,readableCheckpointVersion:SESSION_CHECKPOINT_VERSION,sessionId:e.sessionId}),{kind:`incompatible`,reason:`checkpoint-version`});if(t.kind===`incompatible`)return unreadable(t.detail);let{checkpoint:n}=t,r=n.sessionTimeoutMs;if(r!==!1&&(typeof r!=`number`||!Number.isFinite(r)||r<0))throw Error(`Session checkpoint contains an invalid timeout duration.`);let i;try{i=await deserializeContext(n.serializedContext)}catch(e){if(e instanceof IncompatibleStateLayoutError)return unreadable(e.message);throw e}let a=i.require(BundleKey),o=readDurableSession(n.sessionState).sandboxState?.session;if(o!=null&&o.providerName!==void 0){let e=getResolvedRuntimeAgentNode(a.graph,a.nodeId).sandboxRegistry.sandbox.inheritance?.definition??getResolvedRuntimeAgentNode(a.graph,a.nodeId).sandboxRegistry.sandbox.definition;if(e.kind!==`independent`)throw Error(`Session checkpoint sandbox has no resolved provider.`);let t=getSandboxEnvironmentRuntime(e.environment);if(o.providerName!==t.providerName||o.stateProtocolVersion!==t.stateProtocolVersion)throw Error(`Session checkpoint sandbox provider state is incompatible.`)}if(!isSessionStateIdleForHandoff(n))throw Error(`Session checkpoint contains pending work and cannot be handed off.`);return e.source!==void 0&&!await holdsEveryAddress(e.source)?{kind:`source-gone`}:(await recordSessionOwner(e.sessionId),(e.handoffVersion??1)<SESSION_HANDOFF_VERSION&&log.info(`session moved from an owner that releases its addresses first`,{handoffVersion:e.handoffVersion??1,sessionId:e.sessionId}),{kind:`valid`})}async function holdsEveryAddress(e){return(await mapWithConcurrency(e.hookTokens,16,e=>findSessionHookHolder(sessionInboxHookToken(e)))).every(t=>t?.runId===e.runId)}async function stopUntrackedChildSessionsStep(e){"use step";let t=await getWorld();for(let n of e.runIds)if(n!==e.sessionId)try{await cancelRun(t,n,{cancelReason:`Session upgraded`})}catch(t){[...walkCauseChain(t)].some(e=>EntityConflictError.is(e)||RunExpiredError.is(e)||WorkflowRunNotFoundError.is(e))||logError(log,`could not stop a subagent session after handoff`,t,{childRunId:n,sessionId:e.sessionId})}}async function reportSessionHandoffRetainedStep(e){"use step";log.warn(`session handoff failed; the current owner keeps the session`,{...e,checkpointVersion:SESSION_CHECKPOINT_VERSION})}async function recordSessionOwnerStep(e){"use step";await recordSessionOwner(e.sessionId)}async function recordSessionOwner(e){let{setAttributes:t}=await import(`#compiled/@workflow/core/index.js`);await t({[EVE_SESSION_ATTRIBUTE]:e,[EVE_VERSION_ATTRIBUTE]:resolveInstalledPackageInfo().version},{allowReservedAttributes:!0})}async function signalSessionOwnerActivationStep(e){"use step";try{await resumeHook(e.token,e.activation)}catch(e){if(!HookNotFoundError.is(e))throw e}}async function reportSessionTakenOverOutsideAttemptStep(e){"use step";log.error(`session taken over with no handoff attempt open; this run leaves without finalizing`,{sessionId:e.sessionId})}async function reportHandoverPartStuckStep(e){"use step";log.warn(`session handover part keeps failing; the previous owner keeps retrying`,e)}async function sendSessionHandoverPartStep(e){"use step";try{return await resumeHook(sessionInboxHookToken(sessionCommandHookToken(e.sessionId)),{...e.part,kind:`handover`}),`delivered`}catch(e){if(HookNotFoundError.is(e))return`session-ended`;throw e}}async function signalSessionAnchorStep(e){"use step";await resumeHook(e.token,e.result)}export{hasRunEndedStep,isSessionStateIdleForHandoff,prepareSuccessorStep,recordSessionOwnerStep,reportHandoverPartStuckStep,reportSessionHandoffRetainedStep,reportSessionTakenOverOutsideAttemptStep,sendSessionHandoverPartStep,signalSessionAnchorStep,signalSessionOwnerActivationStep,startSuccessorStep,stopUntrackedChildSessionsStep};
+import{createLogger,logError}from"#internal/logging.js";import{sessionCommandHookToken,sessionInboxHookToken}from"#execution/session-inbox/address.js";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{walkCauseChain}from"#shared/errors.js";import{getSandboxEnvironmentRuntime}from"#shared/sandbox-environment.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{cancelRun,getRun,getWorld,resumeHook}from"#internal/workflow/runtime.js";import{hasRunEnded,startWorkflowOnDeployment,workflowEntryReference}from"#execution/workflow-runtime.js";import{getResolvedRuntimeAgentNode}from"#runtime/graph.js";import{IncompatibleStateLayoutError,deserializeContext}from"#context/serialize.js";import{readDurableSession}from"#execution/durable-session-read.js";import{EntityConflictError,HookNotFoundError,RunExpiredError,WorkflowRunNotFoundError}from"#compiled/@workflow/errors/index.js";import{findSessionHookHolder}from"#execution/session-inbox/owner.js";import{EVE_PREWARM_ATTRIBUTE,EVE_SESSION_ATTRIBUTE,EVE_VERSION_ATTRIBUTE}from"#execution/eve-workflow-attributes.js";import{owningSandboxDefinition}from"#runtime/sandbox/registry.js";import{isRetiredSandboxSessionState,resolvePersistedSandboxSessionState}from"#sandbox/state.js";import{SESSION_CHECKPOINT_VERSION}from"#execution/session/handoff.js";import{mapWithConcurrency}from"#shared/map-with-concurrency.js";import{isSessionStateIdleForHandoff}from"#execution/session/handoff-state.js";import{SESSION_HANDOFF_VERSION}from"#execution/session/entry-input.js";import{traceSessionHandover}from"#execution/session/handover-tracing.js";const log=createLogger(`execution.handoff`);async function startSuccessorStep(e){"use step";let{activationToken:t,anchorRunId:n,checkpoint:r,targetDeploymentId:i,...a}=e,{capabilities:o}=await getWorld();if(o?.hookForceClaim!==!0||o.hookRetention?.active!==!0)return log.warn(`session handoff unavailable: the Workflow world cannot force-claim hooks`,{sessionId:n}),{kind:`unsupported`};if(!isSessionStateIdleForHandoff(r))return{kind:`not-idle`};let s={...a,activationToken:t,checkpoint:r,handoffVersion:SESSION_HANDOFF_VERSION,kind:`handoff`,ownerDeploymentId:i,sessionWritable:getRun(n).getWritable(),sessionId:n};return{kind:`started`,runId:(await startWorkflowOnDeployment(workflowEntryReference,[s],i,r.retention===void 0?void 0:{experimental_retention:r.retention})).runId}}async function hasRunEndedStep(e){"use step";return await hasRunEnded(e.runId)}async function prepareSuccessorStep(e){"use step";let{migration:t}=e,unreadable=t=>(log.warn(`session handoff refused: this deployment cannot read the checkpoint`,{detail:t,readableCheckpointVersion:SESSION_CHECKPOINT_VERSION,sessionId:e.sessionId}),{kind:`incompatible`,reason:`checkpoint-version`});if(t.kind===`incompatible`)return unreadable(t.detail);let{checkpoint:n}=t,r=n.sessionTimeoutMs;if(r!==!1&&(typeof r!=`number`||!Number.isFinite(r)||r<0))throw Error(`Session checkpoint contains an invalid timeout duration.`);let i;try{i=await deserializeContext(n.serializedContext)}catch(e){if(e instanceof IncompatibleStateLayoutError)return unreadable(e.message);throw e}let a=i.require(BundleKey),o=readDurableSession(n.sessionState).sandboxState?.session;if(o!=null&&!isRetiredSandboxSessionState(o)){let e=owningSandboxDefinition(getResolvedRuntimeAgentNode(a.graph,a.nodeId).sandboxRegistry.sandbox);if(e.kind!==`independent`)throw Error(`Session checkpoint sandbox has no resolved provider.`);let t=getSandboxEnvironmentRuntime(e.environment),n=resolvePersistedSandboxSessionState(o,t);if(n?.providerName!==t.providerName||n.stateProtocolVersion!==t.stateProtocolVersion)throw Error(`Session checkpoint sandbox provider state is incompatible.`)}if(!isSessionStateIdleForHandoff(n))throw Error(`Session checkpoint contains pending work and cannot be handed off.`);return e.source!==void 0&&!await holdsEveryAddress(e.source)?{kind:`source-gone`}:(await recordSessionOwner(e.sessionId),(e.handoffVersion??1)<SESSION_HANDOFF_VERSION&&log.info(`session moved from an owner that releases its addresses first`,{handoffVersion:e.handoffVersion??1,sessionId:e.sessionId}),{kind:`valid`})}async function holdsEveryAddress(e){return(await mapWithConcurrency(e.hookTokens,16,e=>findSessionHookHolder(sessionInboxHookToken(e)))).every(t=>t?.runId===e.runId)}async function stopUntrackedChildSessionsStep(e){"use step";let t=await getWorld();for(let n of e.runIds)if(n!==e.sessionId)try{await cancelRun(t,n,{cancelReason:`Session upgraded`})}catch(t){[...walkCauseChain(t)].some(e=>EntityConflictError.is(e)||RunExpiredError.is(e)||WorkflowRunNotFoundError.is(e))||logError(log,`could not stop a subagent session after handoff`,t,{childRunId:n,sessionId:e.sessionId})}}async function reportSessionHandoffRetainedStep(e){"use step";log.warn(`session handoff failed; the current owner keeps the session`,{...e,checkpointVersion:SESSION_CHECKPOINT_VERSION})}async function recordSessionOwnerStep(e){"use step";await recordSessionOwner(e.sessionId)}async function recordSessionOwner(e){let{setAttributes:t}=await import(`#compiled/@workflow/core/index.js`);await t({[EVE_SESSION_ATTRIBUTE]:e,[EVE_PREWARM_ATTRIBUTE]:`1`,[EVE_VERSION_ATTRIBUTE]:resolveInstalledPackageInfo().version},{allowReservedAttributes:!0})}async function signalSessionOwnerActivationStep(e){"use step";try{await resumeHook(e.token,e.activation)}catch(e){if(!HookNotFoundError.is(e))throw e}}async function reportSessionTakenOverOutsideAttemptStep(e){"use step";log.error(`session taken over with no handoff attempt open; this run leaves without finalizing`,{sessionId:e.sessionId})}async function reportHandoverPartStuckStep(e){"use step";log.warn(`session handover part keeps failing; the previous owner keeps retrying`,e)}async function sendSessionHandoverPartStep(e){"use step";let t={"eve.handoff.buffered_payload_count":e.bufferedPayloadCount,"eve.handoff.part_index":e.part.index};e.part.index===0&&traceSessionHandover(`forwarding_started`,e.sessionId,e.part.attemptKey,t);try{let n=await resumeHook(sessionInboxHookToken(sessionCommandHookToken(e.sessionId)),{...e.part,kind:`handover`});return traceSessionHandover(e.part.final===!0?`final_submitted`:`part_submitted`,e.sessionId,e.part.attemptKey,{...t,"eve.handoff.destination_run_id":n.runId}),`delivered`}catch(e){if(HookNotFoundError.is(e))return`session-ended`;throw e}}async function signalSessionAnchorStep(e){"use step";await resumeHook(e.token,e.result)}export{hasRunEndedStep,prepareSuccessorStep,recordSessionOwnerStep,reportHandoverPartStuckStep,reportSessionHandoffRetainedStep,reportSessionTakenOverOutsideAttemptStep,sendSessionHandoverPartStep,signalSessionAnchorStep,signalSessionOwnerActivationStep,startSuccessorStep,stopUntrackedChildSessionsStep};