eve 0.5.4 → 0.6.0-beta.3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,81 @@
+import type { DurableSession } from "#execution/durable-session-store.js";
+import type { HarnessSession } from "#harness/types.js";
+import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";
+/**
+ * Creates the durable compaction configuration used by one harness session.
+ */
+export declare function createCompactionConfig(input?: {
+    readonly contextWindowTokens?: number;
+    readonly lastKnownInputTokens?: number;
+    readonly lastKnownPromptMessageCount?: number;
+    readonly thresholdPercent?: number;
+}): {
+    recentWindowSize: number;
+    threshold: number;
+} | {
+    recentWindowSize: number;
+    threshold: number;
+    lastKnownInputTokens: number;
+    lastKnownPromptMessageCount: number | undefined;
+};
+export interface CreateSessionInput {
+    readonly continuationToken: string;
+    readonly compactionOverrides?: {
+        readonly thresholdPercent?: number;
+    };
+    /**
+     * Optional root session id passed in by the runtime when this
+     * session is a delegated subagent child. `undefined` for top-level
+     * sessions — `sessionId` is the root for those.
+     */
+    readonly rootSessionId?: string;
+    readonly sessionId: string;
+    readonly turnAgent: RuntimeTurnAgent;
+    readonly outputSchema?: HarnessSession["outputSchema"];
+}
+/**
+ * Creates a fresh {@link HarnessSession}. The only site that derives
+ * `session.agent.system` from a `turnAgent` — every subsequent turn
+ * preserves the prompt via {@link refreshSessionFromTurnAgent}.
+ */
+export declare function createSession(input: CreateSessionInput): HarnessSession;
+/**
+ * Refreshes a session with the latest `turnAgent` — replaces model/tool
+ * metadata and recalculates compaction thresholds; preserves history and
+ * state. Production callers keep the session-start `agent.system` prompt,
+ * while dev HMR callers can opt into refreshing it from authored source.
+ */
+export declare function refreshSessionFromTurnAgent(input: {
+    readonly session: HarnessSession;
+    readonly turnAgent: RuntimeTurnAgent;
+    readonly refreshSystemPrompt?: boolean;
+    readonly compactionOverrides?: {
+        readonly thresholdPercent?: number;
+    };
+}): HarnessSession;
+/**
+ * Mints a continuation token for a delegated subagent session.
+ * Deterministic when `suffix` is provided so retries address the same
+ * child hook.
+ */
+export declare function mintSubagentContinuationToken(suffix?: string): string;
+/**
+ * Projects a {@link HarnessSession} to {@link DurableSession}.
+ *
+ * Drops fields rebuilt every turn from `bundle.turnAgent`; keeps
+ * `agent.system` and `compaction.lastKnown*` so compaction stays
+ * informed after rehydration.
+ */
+export declare function projectToDurableSession(session: HarnessSession): DurableSession;
+/**
+ * Rehydrates a {@link HarnessSession} from a {@link DurableSession}
+ * plus the current `turnAgent`, rebuilding the runtime-only agent and
+ * compaction fields the durable shape omits.
+ */
+export declare function hydrateDurableSession(input: {
+    readonly durable: DurableSession;
+    readonly turnAgent: RuntimeTurnAgent;
+    readonly compactionOverrides?: {
+        readonly thresholdPercent?: number;
+    };
+}): HarnessSession;

package/dist/src/execution/session.js

@@ -0,0 +1,5 @@
+function createCompactionConfig(e={}){let t=e.thresholdPercent??.9,n={recentWindowSize:10,threshold:e.contextWindowTokens===void 0?1e5:Math.max(1,Math.floor(e.contextWindowTokens*t))};return e.lastKnownInputTokens===void 0?n:{...n,lastKnownInputTokens:e.lastKnownInputTokens,lastKnownPromptMessageCount:e.lastKnownPromptMessageCount}}function createSession(e){let{turnAgent:t}=e,n=createSessionToolDefinitions(t),r={agent:{compactionModelReference:t.compactionModel,modelReference:t.model,system:t.instructions.join(`
+
+`),tools:n},compaction:createCompactionConfig({contextWindowTokens:t.model.contextWindowTokens,thresholdPercent:e.compactionOverrides?.thresholdPercent}),continuationToken:e.continuationToken,history:[],sessionId:e.sessionId};return e.rootSessionId!==void 0&&(r.rootSessionId=e.rootSessionId),e.outputSchema!==void 0&&(r.outputSchema=e.outputSchema),r}function refreshSessionFromTurnAgent(e){return{...e.session,agent:{compactionModelReference:e.turnAgent.compactionModel,modelReference:e.turnAgent.model,system:e.refreshSystemPrompt===!0?e.turnAgent.instructions.join(`
+
+`):e.session.agent.system,tools:createSessionToolDefinitions(e.turnAgent)},compaction:createCompactionConfig({contextWindowTokens:e.turnAgent.model.contextWindowTokens,lastKnownInputTokens:e.session.compaction.lastKnownInputTokens,lastKnownPromptMessageCount:e.session.compaction.lastKnownPromptMessageCount,thresholdPercent:e.compactionOverrides?.thresholdPercent})}}function mintSubagentContinuationToken(e){return`subagent:${e??crypto.randomUUID()}`}function projectToDurableSession(e){let t={agent:{system:e.agent.system},continuationToken:e.continuationToken,history:e.history,sessionId:e.sessionId};return(e.compaction.lastKnownInputTokens!==void 0||e.compaction.lastKnownPromptMessageCount!==void 0)&&(t.compaction={lastKnownInputTokens:e.compaction.lastKnownInputTokens,lastKnownPromptMessageCount:e.compaction.lastKnownPromptMessageCount}),e.rootSessionId!==void 0&&(t.rootSessionId=e.rootSessionId),e.outputSchema!==void 0&&(t.outputSchema=e.outputSchema),e.sandboxState!==void 0&&(t.sandboxState=e.sandboxState),e.state!==void 0&&(t.state=e.state),t}function hydrateDurableSession(e){let{durable:t,turnAgent:n}=e,r=createSessionToolDefinitions(n),i={agent:{compactionModelReference:n.compactionModel,modelReference:n.model,system:t.agent.system,tools:r},compaction:createCompactionConfig({contextWindowTokens:n.model.contextWindowTokens,lastKnownInputTokens:t.compaction?.lastKnownInputTokens,lastKnownPromptMessageCount:t.compaction?.lastKnownPromptMessageCount,thresholdPercent:e.compactionOverrides?.thresholdPercent}),continuationToken:t.continuationToken,history:t.history,sessionId:t.sessionId};return t.rootSessionId!==void 0&&(i.rootSessionId=t.rootSessionId),t.outputSchema!==void 0&&(i.outputSchema=t.outputSchema),t.sandboxState!==void 0&&(i.sandboxState=t.sandboxState),t.state!==void 0&&(i.state=t.state),i}function createSessionToolDefinitions(e){return e.tools.map(e=>({description:e.description??``,inputSchema:e.inputSchema,name:e.name,outputSchema:e.outputSchema}))}export{createCompactionConfig,createSession,hydrateDurableSession,mintSubagentContinuationToken,projectToDurableSession,refreshSessionFromTurnAgent};

package/dist/src/execution/skills/instructions.d.ts

@@ -0,0 +1,19 @@
+interface AvailableSkillDescription {
+    readonly description: string;
+    readonly name: string;
+}
+/**
+ * Formats the "Available skills" system prompt section.
+ *
+ * All skills are always listed regardless of activation state. Active skill
+ * instructions are never injected into the system prompt — the model already
+ * has them from the `load_skill` tool result. This keeps the system
+ * prompt identical across the entire session, preserving prompt caching.
+ *
+ * Authored skills call this at graph resolution time so the section is
+ * part of the turn agent's static instructions. Dynamic skills
+ * (`defineDynamic` in `agent/skills/`) reuse the same formatter for
+ * durable context announcements.
+ */
+export declare function formatAvailableSkillsSection(skills: readonly AvailableSkillDescription[]): string | null;
+export {};

package/dist/src/execution/skills/instructions.js

@@ -0,0 +1,2 @@
+import{WORKSPACE_ROOT}from"#runtime/workspace/types.js";function formatAvailableSkillsSection(e){return e.length===0?null:[`Available skills`,`Listed skills are available in this run. Do not claim a listed skill is inaccessible unless activation or workspace inspection actually fails.`,`If the user names a skill or the request clearly matches one of the descriptions below, call load_skill before proceeding.`,`If multiple skills match, activate the minimal set that covers the task. After activation, follow the returned instructions instead of improvising around them.`,`If activation fails, say so briefly and continue with the best fallback. Packaged sibling files under a skill path can be inspected with bash or read_file when needed.`,...e.map(e=>formatAvailableSkillLine(e))].join(`
+`)}function formatAvailableSkillLine(t){return`- ${t.name}: ${t.description} (path: ${WORKSPACE_ROOT}/skills/${t.name}/SKILL.md)`}export{formatAvailableSkillsSection};

package/dist/src/execution/skills/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A reference to one file inside a sandbox-backed skill directory.
+ */
+export interface SkillFile {
+    /** Reads the file content as bytes. */
+    bytes(): Promise<Uint8Array>;
+    /** Reads the file content as UTF-8 text. */
+    text(): Promise<string>;
+}
+/**
+ * Handle to one authored skill, returned by `ctx.getSkill()`.
+ *
+ * Exposes skill metadata and reads files from a skill package.
+ */
+export interface SkillHandle {
+    /** The skill identifier passed to `ctx.getSkill()`, used as the skill directory segment under the sandbox skills root. */
+    readonly name: string;
+    /**
+     * Returns a file accessor for a path relative to the skill root.
+     */
+    file(relativePath: string): SkillFile;
+}

package/dist/src/execution/skills/types.js

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

package/dist/src/execution/subagent-adapter.d.ts

@@ -0,0 +1,43 @@
+import type { ChannelAdapter } from "#channel/adapter.js";
+/**
+ * Durable adapter kind used for delegated subagent child runs.
+ *
+ * Framework-owned — authored channel code never constructs a subagent
+ * adapter directly. Emitted by `buildSubagentRunInput`
+ * (`execution/subagent-tool.ts`) when a parent dispatches a child
+ * subagent.
+ */
+export declare const SUBAGENT_ADAPTER_KIND = "subagent";
+/**
+ * Durable state carried on a subagent adapter instance.
+ *
+ * Populated by `buildSubagentRunInput` at dispatch time so the child
+ * run retains the parent lineage metadata required to resume its parent
+ * when the child finishes and to forward HITL requests up the chain.
+ *
+ * The parent's turn identifier is not duplicated here — it lives on
+ * `RunInput.parent.turn.id` which is the single source of truth for the
+ * child's parent-turn lineage.
+ */
+export interface SubagentAdapterState extends Record<string, unknown> {
+    readonly callId: string;
+    readonly parentContinuationToken: string;
+    readonly parentSessionId: string;
+    readonly subagentName: string;
+}
+/**
+ * Narrow runtime guard for {@link SubagentAdapterState}.
+ *
+ * Framework adapters live through a JSON round-trip at every workflow
+ * step boundary, so consumers that want to treat the adapter state as
+ * a structured record must validate the shape explicitly.
+ */
+export declare function isSubagentAdapterState(value: unknown): value is SubagentAdapterState;
+/**
+ * Framework adapter that bridges a child subagent session to its
+ * parent.
+ *
+ * It proxies child `input.requested` events upward so the parent channel
+ * can render HITL prompts and route responses back down to the child.
+ */
+export declare const SUBAGENT_ADAPTER: ChannelAdapter;

package/dist/src/execution/subagent-adapter.js

@@ -0,0 +1 @@
+import{createErrorId,createLogger}from"#internal/logging.js";import{ContinuationTokenKey,SessionIdKey}from"#context/keys.js";import{resumeHook}from"#compiled/@workflow/core/runtime.js";const log=createLogger(`execution.subagent-adapter`),SUBAGENT_ADAPTER_KIND=`subagent`;function isSubagentAdapterState(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.callId==`string`&&t.callId.length>0&&typeof t.parentContinuationToken==`string`&&t.parentContinuationToken.length>0&&typeof t.parentSessionId==`string`&&typeof t.subagentName==`string`&&t.subagentName.length>0}const SUBAGENT_ADAPTER={kind:SUBAGENT_ADAPTER_KIND,async"input.requested"(e,t){let i=t.state;isSubagentAdapterState(i)&&await forwardSubagentInputRequestStep({hookPayload:{callId:i.callId,childContinuationToken:t.ctx.require(ContinuationTokenKey),childSessionId:t.ctx.require(SessionIdKey),event:{requests:e.requests,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},kind:`subagent-input-request`,subagentName:i.subagentName},parentContinuationToken:i.parentContinuationToken})}};async function forwardSubagentInputRequestStep(t){"use step";try{await resumeHook(t.parentContinuationToken,t.hookPayload)}catch(n){let r=createErrorId();throw log.warn(`failed to forward proxied HITL batch to parent`,{callId:t.hookPayload.callId,childContinuationToken:t.hookPayload.childContinuationToken,childSessionId:t.hookPayload.childSessionId,errorId:r,parentContinuationToken:t.parentContinuationToken,subagentName:t.hookPayload.subagentName,error:n}),n}}export{SUBAGENT_ADAPTER,SUBAGENT_ADAPTER_KIND,isSubagentAdapterState};

package/dist/src/execution/subagent-hitl-proxy.d.ts

@@ -0,0 +1,37 @@
+import type { DeliverPayload, SubagentInputRequestHookPayload } from "#channel/types.js";
+import type { HarnessEmitFn, HarnessSession, SessionStateMap } from "#harness/types.js";
+import type { RunMode } from "#shared/run-mode.js";
+import type { InputResponse } from "#runtime/input/types.js";
+/**
+ * Runs the parent-side work for a `subagent-input-request`. Conversation
+ * mode emits a waiting boundary on the parent stream; the returned proxy
+ * entries route the eventual response back down to the child.
+ */
+export declare function emitProxiedInputRequest(input: {
+    readonly emit: HarnessEmitFn;
+    readonly hookPayload: SubagentInputRequestHookPayload;
+    readonly mode: RunMode;
+    readonly session: HarnessSession;
+}): Promise<{
+    readonly entries: readonly (readonly [requestId: string, childContinuationToken: string])[];
+    readonly session: HarnessSession;
+}>;
+/**
+ * Outcome of splitting one deliver payload by the session's proxy map.
+ * `forSelf` is the parent-local remainder (or `undefined` when fully
+ * routed); `forChildren` carries one entry per descendant token.
+ */
+export interface RoutedDeliverPayload {
+    readonly forChildren: readonly {
+        readonly childContinuationToken: string;
+        readonly payload: {
+            readonly inputResponses: readonly InputResponse[];
+        };
+    }[];
+    readonly forSelf: DeliverPayload | undefined;
+}
+/** Splits a deliver payload into parent-local and proxied-child buckets. */
+export declare function routeDeliverPayload(input: {
+    readonly payload: DeliverPayload;
+    readonly state: SessionStateMap | undefined;
+}): RoutedDeliverPayload;

package/dist/src/execution/subagent-hitl-proxy.js

@@ -0,0 +1 @@
+import{createInputRequestedEvent}from"#protocol/message.js";import{emitTurnEpilogue,getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";import{getProxyInputRequests,toProxyInputRequestEntries}from"#harness/proxy-input-requests.js";async function emitProxiedInputRequest(i){await i.emit(createInputRequestedEvent({requests:i.hookPayload.event.requests,sequence:i.hookPayload.event.sequence,stepIndex:i.hookPayload.event.stepIndex,turnId:i.hookPayload.event.turnId}));let o=i.session;if(i.mode===`conversation`){let e=getHarnessEmissionState(i.session.state),a=await emitTurnEpilogue(i.emit,e,i.mode);o=setHarnessEmissionState(i.session,a)}return{entries:toProxyInputRequestEntries(i.hookPayload),session:o}}function routeDeliverPayload(e){let t=getProxyInputRequests(e.state),n=e.payload.inputResponses??[],r=new Map,a=[];for(let e of n){let n=t.get(e.requestId);if(n===void 0){a.push(e);continue}let i=r.get(n);i===void 0?r.set(n,[e]):i.push(e)}let o=[...r.entries()].map(([e,t])=>({childContinuationToken:e,payload:{inputResponses:t}})),s={};for(let[t,n]of Object.entries(e.payload))t===`inputResponses`||n===void 0||(s[t]=n);return a.length>0&&(s.inputResponses=a),{forChildren:o,forSelf:Object.keys(s).length>0?s:void 0}}export{emitProxiedInputRequest,routeDeliverPayload};