eve 0.5.4 → 0.6.0-beta.3

package/dist/src/execution/durable-session-store.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Durable session storage.
+ *
+ * Session-mutating steps return the current snapshot inside
+ * {@link DurableSessionState}; Workflow step results are the atomic
+ * persistence boundary for session program memory. The legacy
+ * `"eve.session"` stream remains as a fallback for old in-flight
+ * sessions that only carry a small state handle.
+ *
+ * The driver workflow run is pinned to the deployment that called
+ * `start()`; child turn workflows run on latest. Both
+ * {@link DurableSessionState} and {@link DurableSessionSnapshot} carry
+ * a `version` so a pinned driver can ferry shapes written by newer
+ * steps. Adding optional fields is forward-compatible (devalue
+ * preserves unknown POJO fields); shape-breaking changes bump
+ * `version` and add a migrator.
+ */
+import type { ModelMessage } from "ai";
+import { type HarnessEmissionState } from "#harness/emission.js";
+import type { HarnessSession, SessionStateMap } from "#harness/types.js";
+import type { SandboxState } from "#sandbox/state.js";
+import type { JsonObject } from "#shared/json.js";
+/** Current wire version for {@link DurableSessionState} and {@link DurableSessionSnapshot}. */
+export declare const DURABLE_SESSION_VERSION = 1;
+/**
+ * Serializable handle to a durable session.
+ *
+ * Carries the current session snapshot plus the small projections the
+ * workflow body needs without taking a step boundary: identity, the
+ * hook continuation token,
+ * `hasProxyInputRequests` (a closed-contract short-circuit that lets
+ * the driver skip a per-delivery proxy-routing step when no
+ * descendant subagent is active), and `emissionState` (so workflow-body
+ * framework steps can stamp protocol events
+ * with `{ turnId, sequence, stepIndex }` without reading the full
+ * durable session). All other control-plane state travels via
+ * {@link import("#execution/next-driver-action.js").NextDriverAction}.
+ * `snapshot` is optional so old stream-backed states can still read
+ * from the legacy `eve.session` fallback.
+ */
+export interface DurableSessionState {
+    readonly version: typeof DURABLE_SESSION_VERSION;
+    readonly sessionId: string;
+    readonly continuationToken: string;
+    readonly hasProxyInputRequests: boolean;
+    readonly emissionState: HarnessEmissionState;
+    readonly snapshot?: DurableSessionSnapshot;
+}
+/**
+ * Durable projection of {@link HarnessSession} embedded in state
+ * snapshots or legacy `eve.session` stream chunks.
+ *
+ * Omits `agent.modelReference`, `agent.tools`,
+ * `agent.compactionModelReference`, and the `compaction` thresholds —
+ * those are rebuilt every turn from `bundle.turnAgent` by
+ * {@link import("#execution/session.js").hydrateDurableSession}.
+ * `agent.system` is the session-start prompt snapshot, pinned at
+ * `createSession`.
+ */
+export interface DurableSession {
+    readonly sessionId: string;
+    /**
+     * Top user-facing session id in the dispatch chain. Optional because
+     * a top-level session is its own root. Persisted so a rehydrated
+     * subagent session still knows its root after a workflow step
+     * boundary.
+     */
+    readonly rootSessionId?: string;
+    readonly continuationToken: string;
+    readonly history: ModelMessage[];
+    readonly outputSchema?: JsonObject;
+    readonly state?: SessionStateMap;
+    readonly sandboxState?: SandboxState;
+    readonly agent: {
+        readonly system: string;
+    };
+    readonly compaction?: {
+        readonly lastKnownInputTokens?: number;
+        readonly lastKnownPromptMessageCount?: number;
+    };
+}
+/** Versioned wrapper around a {@link DurableSession} on the wire. */
+export interface DurableSessionSnapshot {
+    readonly version: typeof DURABLE_SESSION_VERSION;
+    readonly session: DurableSession;
+}
+/** Projects a {@link HarnessSession} into the boundary-safe state value. */
+export declare function projectSessionState(input: {
+    readonly session: HarnessSession;
+}): DurableSessionState;
+/**
+ * Reads the latest durable session snapshot and returns the
+ * {@link DurableSession} inside.
+ *
+ * New states carry the snapshot directly through Workflow step
+ * results. States without `snapshot` fall back to the legacy
+ * `eve.session` stream tail (`startIndex: -1`). The snapshot is
+ * migrated to {@link DURABLE_SESSION_VERSION} before return; unknown
+ * versions throw.
+ *
+ * Devalue handles encode/decode so rich types in the session (URL
+ * `FilePart.data`, Buffer, Date, Map, Set) round-trip structurally.
+ *
+ * MUST be called from inside a `"use step"` body.
+ */
+export declare function readDurableSession(state: DurableSessionState): Promise<DurableSession>;
+/**
+ * Creates the projected {@link DurableSessionState} with the current
+ * snapshot embedded in the Workflow step result.
+ */
+export declare function createDurableSessionState(input: {
+    readonly session: HarnessSession;
+}): DurableSessionState;

package/dist/src/execution/durable-session-store.js

@@ -0,0 +1 @@
+import{projectToDurableSession}from"#execution/session.js";import{getHarnessEmissionState}from"#harness/emission.js";import{hasProxyInputRequests}from"#harness/proxy-input-requests.js";import{migrateDurableSessionSnapshot}from"#execution/durable-session-migrations/snapshot.js";const EVE_SESSION_STREAM_NAMESPACE=`eve.session`,DURABLE_SESSION_VERSION=1,DURABLE_SESSION_READ_TIMEOUT_MS=1e4;function projectSessionState(e){return{continuationToken:e.session.continuationToken,emissionState:getHarnessEmissionState(e.session.state),hasProxyInputRequests:hasProxyInputRequests(e.session.state),sessionId:e.session.sessionId,version:1}}async function readDurableSession(e){if(e.snapshot!==void 0)return migrateDurableSessionSnapshot(e.snapshot).session;let{getRun:t}=await import(`#compiled/@workflow/core/runtime.js`),n=t(e.sessionId).getReadable({namespace:EVE_SESSION_STREAM_NAMESPACE,startIndex:-1}).getReader(),r=`eve durable session tail read failed`,i;try{let t=await Promise.race([n.read().then(e=>({kind:`read`,read:e})),new Promise(e=>{i=setTimeout(()=>e({kind:`timeout`}),DURABLE_SESSION_READ_TIMEOUT_MS)})]);if(t.kind===`timeout`)throw r=`eve durable session tail read timed out after ${DURABLE_SESSION_READ_TIMEOUT_MS}ms`,new DurableSessionReadTimeoutError(e);if(t.read.done||t.read.value===void 0)throw r=`eve durable session tail read returned no snapshot`,Error(`No durable session snapshot found in stream "${EVE_SESSION_STREAM_NAMESPACE}" for run ${e.sessionId}.`);return r=`eve durable session tail read complete`,migrateDurableSessionSnapshot(t.read.value).session}finally{i!==void 0&&clearTimeout(i),await n.cancel(r).catch(()=>{}),n.releaseLock()}}var DurableSessionReadTimeoutError=class extends Error{constructor(e){super(`Timed out reading durable session snapshot from stream "${EVE_SESSION_STREAM_NAMESPACE}" for run ${e.sessionId} after ${DURABLE_SESSION_READ_TIMEOUT_MS}ms.`),this.name=`DurableSessionReadTimeoutError`}};function createDurableSessionState(t){let n={session:projectToDurableSession(t.session),version:1};return{...projectSessionState({session:t.session}),snapshot:n}}export{DURABLE_SESSION_VERSION,createDurableSessionState,projectSessionState,readDurableSession};

package/dist/src/execution/eve-workflow-attributes.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Builders for the framework's reserved `$eve.*` workflow attributes.
+ *
+ * Each builder returns a plain `Record<string, string | number | undefined>`
+ * suitable for `setEveAttributes` from
+ * {@link "#runtime/attributes/emit.js" }. Builders are intentionally
+ * pure data → data transforms: they hold zero dependencies on the
+ * workflow runtime so the workflow body, step bodies, and tests can
+ * all call them identically.
+ *
+ * `$eve.*` is the framework-owned attribute namespace. Authored code
+ * never emits these tags directly — they describe the structural shape
+ * of a session/turn/subagent run so dashboards can stitch a tree of
+ * workflow runs back together without inspecting their bodies.
+ *
+ * Tag inventory (recap):
+ * - `$eve.type`         — `"session" | "turn" | "subagent"`
+ * - `$eve.parent`       — sessionId of the **immediate** parent
+ * - `$eve.root`         — sessionId of the **root** session in the chain
+ * - `$eve.parent_call`  — parent runtime-action tool call id (subagent rows only)
+ * - `$eve.parent_turn`  — parent turn id that dispatched the subagent (subagent rows only)
+ * - `$eve.subagent`     — active compiled graph node id (subagent rows only)
+ * - `$eve.trigger`      — channel adapter kind (session/subagent rows)
+ * - `$eve.title`        — truncated session title from the first user message
+ */
+import type { EveAttributeValue } from "#runtime/attributes/emit.js";
+/**
+ * Active compiled graph node id for the session's agent. Returned by
+ * `createSessionStep` so workflow bodies don't have to load the bundle
+ * themselves. Equal to the framework root sentinel (`"__root__"`) for
+ * the root agent; equal to the subagent's compiled node id for
+ * delegated child runs. Tag emitters use this to populate
+ * `$eve.subagent`.
+ */
+export interface SessionIdentitySummary {
+    readonly nodeId: string;
+}
+/**
+ * Parent session lineage decoded from the serialized run context.
+ */
+export interface SessionParentLineage {
+    readonly callId?: string;
+    readonly rootSessionId?: string;
+    readonly sessionId?: string;
+    readonly turnId?: string;
+}
+/**
+ * Reads the active channel kind from a deserialized context map.
+ * Returns `undefined` when the channel slot is missing or malformed —
+ * tag emission silently drops undefined values.
+ */
+export declare function readChannelKind(serializedContext: Record<string, unknown>): string | undefined;
+/**
+ * Reads parent session lineage from a deserialized context map. Returns
+ * an empty object for top-level runs or malformed delegated contexts.
+ */
+export declare function readParentLineage(serializedContext: Record<string, unknown>): SessionParentLineage;
+/**
+ * Reads the immediate parent session id from a deserialized context map.
+ * Returns `undefined` when the run is a top-level session.
+ */
+export declare function readParentSessionId(serializedContext: Record<string, unknown>): string | undefined;
+/**
+ * Reads the **root** session id from a deserialized context map.
+ *
+ * `eve.parentSession.rootSessionId` is denormalized at every dispatch
+ * site (see {@link "#channel/types.js".SessionParent}) so a subagent
+ * five levels deep can still attribute itself to the top user-facing
+ * session without walking the chain. Returns `undefined` for top-level
+ * runs, which carry no `eve.parentSession`.
+ */
+export declare function readRootSessionId(serializedContext: Record<string, unknown>): string | undefined;
+/**
+ * Maximum visible length (in code points) of a derived `$eve.title`.
+ *
+ * The runtime separately caps every tag value to a byte budget
+ * (`EVE_ATTRIBUTE_VALUE_MAX_BYTES`), but titles render as the first
+ * column of the dashboard's run table, so they get a tighter,
+ * display-oriented cap here. Kept well under the byte budget so the
+ * value never reaches the runtime truncator.
+ */
+export declare const EVE_SESSION_TITLE_MAX_CHARS = 80;
+/**
+ * Derives the `$eve.title` value from the first user message of a
+ * top-level session.
+ *
+ * Returns `undefined` when no plain-text content is available; the
+ * attribute emitter strips undefined values. Multimodal messages
+ * (image/file parts) contribute only their text parts to keep the
+ * title human-readable. Long prompts are truncated to
+ * {@link EVE_SESSION_TITLE_MAX_CHARS} code points with a trailing
+ * ellipsis so the dashboard's title column stays readable.
+ */
+export declare function deriveSessionTitle(message: unknown): string | undefined;
+/**
+ * Builds the `$eve.*` attribute payload for a top-level session run
+ * (`workflowEntry` invoked without an `eve.parentSession`).
+ *
+ * `$eve.root` is intentionally omitted — the session row IS the root,
+ * so its own `workflowRunId` already identifies the chain root.
+ */
+export declare function buildSessionAttributes(input: {
+    readonly inputMessage: unknown;
+    readonly serializedContext: Record<string, unknown>;
+}): Record<string, EveAttributeValue>;
+/**
+ * Builds the `$eve.*` attribute payload for a delegated subagent root
+ * run (`workflowEntry` invoked with an `eve.parentSession`).
+ *
+ * `$eve.root` carries the **root** session id so the dashboard can
+ * group every descendant under one query: `search($eve.root=<root>)`
+ * returns all turns and nested subagents under that user-facing
+ * session in a single round trip.
+ */
+export declare function buildSubagentRootAttributes(input: {
+    readonly identity: SessionIdentitySummary;
+    readonly parentCallId?: string;
+    readonly parentSessionId: string;
+    readonly parentTurnId?: string;
+    readonly rootSessionId: string;
+    readonly serializedContext: Record<string, unknown>;
+}): Record<string, EveAttributeValue>;
+/**
+ * Builds the `$eve.*` attribute payload for one turn workflow run.
+ *
+ * Turns live one level below their session: `$eve.parent` always points
+ * to the parent's sessionId (which is the session-row's
+ * `workflowRunId`), and `$eve.root` denormalizes the chain root (equal
+ * to `$eve.parent` for turns of top-level sessions). Turn ordering is
+ * recovered from each run's `createdAt`, so no explicit sequence tag is
+ * emitted.
+ */
+export declare function buildTurnAttributes(input: {
+    readonly parentSessionId: string;
+    readonly rootSessionId: string;
+}): Record<string, EveAttributeValue>;

package/dist/src/execution/eve-workflow-attributes.js

@@ -0,0 +1 @@
+import{isNonEmptyString}from"#shared/guards.js";function readChannelKind(t){let n=t[`eve.channel`]?.kind;return isNonEmptyString(n)?n:void 0}function readParentLineage(t){let n=t[`eve.parentSession`],r=n?.callId,i=n?.rootSessionId,a=n?.sessionId,o=n?.turn?.id;return{callId:isNonEmptyString(r)?r:void 0,rootSessionId:isNonEmptyString(i)?i:void 0,sessionId:isNonEmptyString(a)?a:void 0,turnId:isNonEmptyString(o)?o:void 0}}function readParentSessionId(e){return readParentLineage(e).sessionId}function readRootSessionId(e){return readParentLineage(e).rootSessionId}const EVE_SESSION_TITLE_MAX_CHARS=80;function deriveSessionTitle(e){let t=collectMessageText(e);if(t===void 0||t.length===0)return;let n=t.replace(/\s+/gu,` `).trim();if(n.length===0)return;let r=Array.from(n);return r.length<=80?n:`${r.slice(0,79).join(``)}…`}function collectMessageText(e){if(typeof e==`string`)return e;if(!Array.isArray(e))return;let t=[];for(let n of e)n&&typeof n==`object`&&n.type===`text`&&typeof n.text==`string`&&t.push(n.text);return t.length>0?t.join(` `):void 0}function buildSessionAttributes(e){return{"$eve.type":`session`,"$eve.trigger":readChannelKind(e.serializedContext),"$eve.title":deriveSessionTitle(e.inputMessage)}}function buildSubagentRootAttributes(e){return{"$eve.type":`subagent`,"$eve.parent":e.parentSessionId,"$eve.parent_call":e.parentCallId,"$eve.parent_turn":e.parentTurnId,"$eve.root":e.rootSessionId,"$eve.subagent":e.identity.nodeId,"$eve.trigger":readChannelKind(e.serializedContext)}}function buildTurnAttributes(e){return{"$eve.type":`turn`,"$eve.parent":e.parentSessionId,"$eve.root":e.rootSessionId}}export{EVE_SESSION_TITLE_MAX_CHARS,buildSessionAttributes,buildSubagentRootAttributes,buildTurnAttributes,deriveSessionTitle,readChannelKind,readParentLineage,readParentSessionId,readRootSessionId};

package/dist/src/execution/next-driver-action.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Closed-contract dispatch surface between session-mutating step
+ * bodies (latest deployment) and the durable driver workflow (pinned
+ * to whichever deployment called `start()`).
+ *
+ * The driver matches on `kind` and follows a fixed playbook per arm.
+ * Adding a new arm is breaking (pinned drivers can't dispatch an
+ * unknown `kind`); adding optional fields inside an existing arm is
+ * forward-compatible because the driver passes the action through by
+ * reference and devalue preserves unknown POJO fields. Do not
+ * destructure-and-rebuild a `NextDriverAction` — full destructuring
+ * strips unknown fields.
+ */
+import type { DurableSessionState } from "#execution/durable-session-store.js";
+/** Discriminated union the driver workflow body dispatches on. */
+export type NextDriverAction = {
+    readonly kind: "done";
+    readonly output: unknown;
+    readonly isError?: boolean;
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+} | {
+    readonly kind: "park";
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+    readonly authorizationNames?: readonly string[];
+} | {
+    readonly kind: "dispatch-runtime-actions";
+    readonly pendingActionKeys: readonly string[];
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+} | {
+    readonly kind: "dispatch-code-mode-runtime-actions";
+    readonly pendingActionKeys: readonly string[];
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+};

package/dist/src/execution/next-driver-action.js

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

package/dist/src/execution/node-step.d.ts

@@ -0,0 +1,52 @@
+import type { Runtime, SessionCapabilities } from "#channel/types.js";
+import type { HandleEventFn, HarnessToolMap, StepFn } from "#harness/types.js";
+import type { RunMode } from "#shared/run-mode.js";
+import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import type { ResolvedRuntimeAgentNode } from "#runtime/graph.js";
+/**
+ * Factory that creates a {@link Runtime} for the given compiled
+ * artifacts source and optional node id. Matches the signature of
+ * `createWorkflowRuntime`, so callers pass the constructor directly —
+ * no wrapper needed.
+ */
+export type CreateRuntime = (config: {
+    readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
+    readonly nodeId?: string;
+}) => Runtime;
+/**
+ * Input for building a harness step for one resolved runtime node.
+ */
+export interface CreateExecutionNodeStepInput {
+    /**
+     * Session-level capabilities propagated from the runtime. The
+     * harness passes this through to `buildToolSet` so `ask_question`
+     * registration and any other capability-gated behavior tracks the
+     * current run.
+     */
+    readonly capabilities?: SessionCapabilities;
+    readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
+    /**
+     * Runtime constructor used by the subagent tool executor to start
+     * delegated child runs on the same workflow runtime as the parent.
+     */
+    readonly createRuntime: CreateRuntime;
+    readonly handleEvent?: HandleEventFn;
+    readonly mode: RunMode;
+    readonly node: ResolvedRuntimeAgentNode;
+}
+/**
+ * Builds a harness step for one resolved runtime node using the execution-owned
+ * tool, sandbox, and subagent wiring.
+ */
+export declare function createExecutionNodeStep(input: CreateExecutionNodeStepInput): StepFn;
+/**
+ * Resolves unified {@link HarnessToolDefinition}s from the node's registries.
+ *
+ * For authored tools: copies all lifecycle fields from the resolved definition.
+ * For subagent tools: surfaces runtime-owned subagent-call metadata and leaves
+ * execution to the runtime layer.
+ * Tools without `execute` (provider-managed) get entries with schema but no execute.
+ */
+export declare function createNodeHarnessTools(input: {
+    readonly node: ResolvedRuntimeAgentNode;
+}): HarnessToolMap;

package/dist/src/execution/node-step.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{jsonSchema}from"ai";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createToolLoopHarness}from"#harness/tool-loop.js";import{resolveCodeModeEnabled}from"#shared/code-mode.js";import{resolveRuntimeModelReference}from"#runtime/agent/resolve-model.js";import{findRegisteredRuntimeTool}from"#runtime/tools/registry.js";import{SUBAGENT_TOOL_INPUT_SCHEMA}from"#runtime/subagents/registry.js";import{createToolCompactionHandler}from"#execution/tool-compaction.js";import{buildUnauthorizedToolContext,createAuthorizedToolExecute}from"#execution/tool-auth.js";const log=createLogger(`execution.node-step`);function createExecutionNodeStep(e){let t=createRuntimeModelResolver(e.compiledArtifactsSource),n=createNodeHarnessTools({node:e.node}),a=createToolCompactionHandler(collectResolvedTools(e.node));return createToolLoopHarness({capabilities:e.capabilities,codeMode:resolveCodeModeEnabled(e.node.agent.config?.experimental?.codeMode),workflow:e.node.agent.workflowEnabled===!0,handleEvent:e.handleEvent,mode:e.mode,onCompaction:a,resolveModel:t,runtimeIdentity:buildRuntimeIdentity(e.node),tools:n})}function buildRuntimeIdentity(e){let t=resolveInstalledPackageInfo(),r={agentId:e.turnAgent.id,agentName:e.agent.config?.name,eveVersion:t.version,modelId:e.turnAgent.model.id},i=process.env.VERCEL_GIT_COMMIT_SHA?.trim(),a=process.env.VERCEL_GIT_COMMIT_REF?.trim(),o=process.env.VERCEL_DEPLOYMENT_CREATED_AT?.trim();return i||a||o?{...r,build:{deployedAt:o||void 0,gitBranch:a||void 0,gitSha:i||void 0}}:r}function createRuntimeModelResolver(e){return t=>resolveRuntimeModelReference(t,{compiledArtifactsSource:e})}function collectResolvedTools(e){return[...e.toolRegistry.toolsByName.values()].map(e=>e.definition)}function createNodeHarnessTools(e){let n=new Map;for(let t of e.node.turnAgent.tools){let r=resolveHarnessToolDefinition({node:e.node,tool:t});r!==null&&n.set(t.name,r)}return n.has(`agent`)||n.set(`agent`,{description:`Launch a new agent to handle a complex, multi-step subtask.`,inputSchema:jsonSchema(SUBAGENT_TOOL_INPUT_SCHEMA),name:`agent`,runtimeAction:{kind:`subagent-call`,nodeId:e.node.nodeId,subagentName:`agent`}}),n}function resolveHarnessToolDefinition(e){if(e.tool.kind===`subagent`)return{description:e.tool.description??``,inputSchema:jsonSchema(e.tool.inputSchema??{}),name:e.tool.name,outputSchema:e.tool.outputSchema===void 0?void 0:jsonSchema(e.tool.outputSchema),runtimeAction:{kind:`subagent-call`,nodeId:e.tool.nodeId,subagentName:e.tool.name}};if(e.tool.kind===`remote`)return{description:e.tool.description??``,inputSchema:jsonSchema(e.tool.inputSchema??{}),name:e.tool.name,outputSchema:e.tool.outputSchema===void 0?void 0:jsonSchema(e.tool.outputSchema),runtimeAction:{kind:`remote-agent-call`,nodeId:e.tool.nodeId,remoteAgentName:e.tool.name,subagentName:e.tool.name}};let n=findRegisteredRuntimeTool(e.node.toolRegistry,e.tool.name);if(n===null)return log.warn(`declared tool is not registered — omitting from toolset`,{toolName:e.tool.name,nodeId:e.node.nodeId}),null;let r=n.definition,i=r.sourceId.startsWith(`eve:`),a=r.execute;return{approvalKey:r.approvalKey,description:r.description,execute:resolveAuthoredExecute({auth:r.auth,isFrameworkTool:i,rawExecute:a,scope:r.name}),inputSchema:r.inputStandardSchema??jsonSchema(r.inputSchema??{}),name:r.name,needsApproval:r.needsApproval,outputSchema:r.outputStandardSchema??maybeJsonSchema(r.outputSchema),toModelOutput:r.toModelOutput}}function resolveAuthoredExecute(e){let{auth:t,isFrameworkTool:n,rawExecute:r,scope:i}=e;if(r===void 0)return;if(n)return r;let a=r;return t===void 0?e=>a(e,buildUnauthorizedToolContext(i)):createAuthorizedToolExecute({auth:t,execute:a,scope:i})}function maybeJsonSchema(e){return e===void 0?void 0:jsonSchema(e)}export{createExecutionNodeStep,createNodeHarnessTools};

package/dist/src/execution/remote-agent-dispatch.d.ts

@@ -0,0 +1,15 @@
+import type { HarnessSession } from "#harness/types.js";
+import type { RuntimeRemoteAgentCallActionRequest } from "#runtime/actions/types.js";
+import type { RuntimeSubagentRegistry } from "#runtime/subagents/registry.js";
+import type { ResolvedRuntimeRemoteAgentNode } from "#runtime/types.js";
+export declare function startRemoteAgentSession(input: {
+    readonly action: RuntimeRemoteAgentCallActionRequest;
+    readonly callbackBaseUrl: string | undefined;
+    readonly remote: ResolvedRuntimeRemoteAgentNode;
+    readonly session: HarnessSession;
+}): Promise<string>;
+export declare function resolveRemoteAgentForAction(input: {
+    readonly nodeId: string;
+    readonly registry: RuntimeSubagentRegistry["subagentsByNodeId"];
+    readonly remoteAgentName: string;
+}): ResolvedRuntimeRemoteAgentNode;

package/dist/src/execution/remote-agent-dispatch.js

@@ -0,0 +1 @@
+import{createEveCallbackRoutePath}from"#protocol/routes.js";import{EVE_SESSION_ID_HEADER}from"#protocol/message.js";import{createWorkflowCallbackUrl}from"#execution/workflow-callback-url.js";import{formatSubagentInvocation}from"#execution/subagent-invocation.js";async function startRemoteAgentSession(n){let r=n.session.continuationToken;if(!r)throw Error(`Cannot dispatch remote agent without a parent continuation token.`);if(!n.callbackBaseUrl)throw Error(`Cannot dispatch remote agent without a callback base URL.`);let i=await resolveRemoteAgentRequestHeaders(n.remote),a=await fetch(createRemoteAgentSessionUrl(n.remote),{body:JSON.stringify({callback:{callId:n.action.callId,subagentName:n.action.remoteAgentName,token:r,url:createWorkflowCallbackUrl(n.callbackBaseUrl,createEveCallbackRoutePath(r))},message:formatRemoteAgentCallInputMessage(n.action),mode:`task`,outputSchema:n.action.input.outputSchema??n.remote.outputSchema}),headers:{"content-type":`application/json`,...i},method:`POST`});if(!a.ok)throw Error(`Remote agent "${n.action.remoteAgentName}" create-session request failed with HTTP ${a.status}.`);let o=a.headers.get(EVE_SESSION_ID_HEADER);if(o!==null&&o.length>0)return o;try{let e=await a.json();if(typeof e.sessionId==`string`&&e.sessionId.length>0)return e.sessionId}catch{}throw Error(`Remote agent "${n.action.remoteAgentName}" create-session response did not include a session id.`)}function resolveRemoteAgentForAction(e){let t=e.registry.get(e.nodeId)?.definition;if(t?.kind!==`remote`)throw Error(`Missing remote agent "${e.remoteAgentName}" in runtime registry.`);return t}function createRemoteAgentSessionUrl(e){return new URL(e.path,`${trimTrailingSlash(e.url)}/`).toString()}async function resolveRemoteAgentRequestHeaders(e){let t={};return e.headers!==void 0&&Object.assign(t,typeof e.headers==`function`?await e.headers():e.headers),e.auth!==void 0&&Object.assign(t,(await e.auth()).headers),t}function formatRemoteAgentCallInputMessage(e){let t=typeof e.input.message==`string`?e.input.message:``;return formatSubagentInvocation({description:e.description,message:t,name:e.remoteAgentName}).message}function trimTrailingSlash(e){return e.endsWith(`/`)?e.slice(0,-1):e}export{resolveRemoteAgentForAction,startRemoteAgentSession};

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

@@ -0,0 +1,10 @@
+import type { RunInput } from "#channel/types.js";
+import { ContextContainer } from "#context/container.js";
+import { type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
+/**
+ * Builds the bootstrap {@link ContextContainer} for one run.
+ */
+export declare function buildRunContext(input: {
+    readonly bundle: CompiledBundle;
+    readonly run: RunInput;
+}): ContextContainer;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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