@hachej/boring-execution 0.2.0 → 0.2.2

package/README.md

@@ -90,9 +90,9 @@ Run `node examples/remote-files.mjs` after building to write and stream a fictio
 
 - **Commands** run through `startCommandExecution`, then `getTask` every `pollIntervalMs` (500 ms by default) until a terminal status. The cwd, environment (`env`, or `env -i` for `inheritEnv: false`) and `umask` (default `002`) are prefixed to the command, which runs under `bash -c`. `onOutput` receives the new part of stdout, then of stderr, after each poll; spill thresholds are accepted and nothing is spilled. `timeout` (seconds) and an aborted context call `stopTask` and return `timeout`/`aborted`, termination unconfirmed. A `failed` status with an exit code is a normal result.
 - **Files** run on this host's mount through Pi's `NodeExecutionEnv`: no bytes cross the API. A path outside `mount.path`, or one whose resolution (symbolic links included, dangling ones followed by hand) leaves `mount.root`, returns `FileError('permission_denied')`; operations that do not follow a final link (`fileInfo`, `exists`, `remove`, `renameFile`) check its directory. Paths in results and errors are session paths. `createTempDir`/`createTempFile` return `not_supported` (a temporary file here would be invisible to the session). The check and the use are separate steps: a link changed in between by a concurrent command is not caught.
-- **Session**: `{ sessionId }` borrows a running session, which `stop()` never ends; `{ start: { name?, sessionTimeoutSeconds?, filesystemConfigurations? } }` starts one on the first command and `stop()` ends it once. `env.cleanup()` never stops a session. When the service reports the session gone (`ResourceNotFoundException`), the running and every later command return `shell_unavailable` and `lost()` is true; files stay. `renew: 'auto'` (default for started sessions; borrowed ones are always manual) starts a new session on the NEXT command after a loss: the failing command still returns `shell_unavailable` and is never replayed, since it may have had side effects. Before a command, a session older than `sessionTimeoutSeconds - rotateMarginSeconds` (default 60 s, at most half the time to live) is replaced for NEW commands. Rotation never stops the old session: a command stays on the session it started in (an `unknown` outcome after a transport failure stays unknown; nothing kills or replays it) and the old session lingers until its own `sessionTimeoutSeconds`, so hosts that care about idle sessions set a shorter timeout. Starts are single-flight (commands arriving during a rotation share the one new session); a failed Start leaves commands on the current session and backs off. `stop()` stops the current session and every session this env started and has not confirmed stopped, and waits for them; a failed stop stays tracked, rejects, and is retried by the next `stop()`. `renew: 'manual'` keeps the earlier behaviour: only `renew()` (started sessions only) lets the next command start a new session. Loss is `ResourceNotFoundException` plus the names and message patterns in the exported `SESSION_ENDED_ERRORS` (for example a `ValidationException` about a terminated session): those extra shapes are UNVERIFIED against real AgentCore (open question), and `AccessDeniedException` is never loss. Service and file errors map to `ExecutionError`/`FileError` with messages bounded by the same `boundedMessage` (no stack frames, at most `MAX_ERROR_CHARS`).
+- **Session**: `{ sessionId }` borrows a running session, which `stop()` never ends; `{ start: { name?, sessionTimeoutSeconds?, filesystemConfigurations? } }` starts one on the first command and `stop()` ends it once. `env.cleanup()` never stops a session. When the service reports the session gone (`ResourceNotFoundException`), the running and every later command return `shell_unavailable` and `lost()` is true; files stay. `renew: 'auto'` (default for started sessions; borrowed ones are always manual) starts a new session on the NEXT command after a loss: the failing command still returns `shell_unavailable` and is never replayed, since it may have had side effects. Before a command, a session older than `sessionTimeoutSeconds - rotateMarginSeconds` (default 60 s, at most half the time to live) is replaced for NEW commands. Rotation never stops the old session: a command stays on the session it started in (an `unknown` outcome after a transport failure stays unknown; nothing kills or replays it) and the old session lingers until its own `sessionTimeoutSeconds`, so hosts that care about idle sessions set a shorter timeout. Starts are single-flight (commands arriving during a rotation share the one new session); a failed Start leaves commands on the current session and backs off. `stop()` stops the current session and every session this env started and has not confirmed stopped, and waits for them; a failed stop stays tracked, rejects, and is retried by the next `stop()`. `renew: 'manual'` keeps the earlier behaviour: only `renew()` (started sessions only) lets the next command start a new session. Loss is `ResourceNotFoundException` plus the names and message patterns in the exported `SESSION_ENDED_ERRORS` (for example a `ValidationException` about a terminated session): those extra shapes are verified against the real service (owner, 2026-10-12; see [HOST-RECIPE-AWS.md](../../docs/architecture/HOST-RECIPE-AWS.md)), and `AccessDeniedException` is never loss. Service and file errors map to `ExecutionError`/`FileError` with messages bounded by the same `boundedMessage` (no stack frames, at most `MAX_ERROR_CHARS`).
 
 `efsUserLayout({ userId, uid, gid?, runtimeMountPath?, runtimeAccessPointRoot?, interpreterMountPath? })` is pure: for a user id (`[a-z0-9][a-z0-9_-]{0,63}`, never a path) and a host-allocated uid it returns the access point to create (root `/boring/users/<id>`, POSIX user `uid:1000`, setgid `2770`, a `boring:user` tag), the session mount (`/mnt/workspace`), this host's folder (`/mnt/efs/users/<id>`), the state directory outside it (`/mnt/efs/state/<id>`, with `journal.sqlite` and `harnessFile(key)`), the namespace id and the `filesystemConfigurations` entry.
 
-`test/packages/execution.test.mjs` drives the real SDK client against `examples/aws/fake-code-interpreter.mjs` (the wire format, without AWS): shared files, output, exit codes, cwd and environment, timeout and abort through `stopTask`, a lost session (auto renewal mid-turn and under concurrent commands, rotation before the time to live without stopping the old session, a stop that fails once and is retried, manual mode, borrowed sessions), borrowed versus owned stop, and two users who never see each other's folders (`..`, absolute paths, links and dangling links made by a command). Nothing has run against the real service; see the open questions in HOST-RECIPE-AWS.md.
+`test/packages/execution.test.mjs` drives the real SDK client against `examples/aws/fake-code-interpreter.mjs` (the wire format, without AWS): shared files, output, exit codes, cwd and environment, timeout and abort through `stopTask`, a lost session (auto renewal mid-turn and under concurrent commands, rotation before the time to live without stopping the old session, a stop that fails once and is retried, manual mode, borrowed sessions), borrowed versus owned stop, and two users who never see each other's folders (`..`, absolute paths, links and dangling links made by a command). The full deployment journey has not run against AWS (the session-ended error shapes are verified against the real service, owner 2026-10-12); see the open questions in HOST-RECIPE-AWS.md.
 

package/dist/aws-code-interpreter.d.ts

@@ -38,6 +38,8 @@ export interface CodeInterpreterEnvOptions {
     readonly umask?: string;
     /** Delay between `getTask` polls while a command runs (default 500 ms). */
     readonly pollIntervalMs?: number;
+    /** Deadline for the whole answer to one start or stop call (default 30 s); the SDK sets no timeout of its own. */
+    readonly serviceDeadlineMs?: number;
     /**
      * What happens after a started session is lost or nearly expired. `'auto'` (default for `{ start }`): the failing
      * command still returns `shell_unavailable` (it is never replayed: it may have had side effects) and the NEXT command
@@ -70,8 +72,7 @@ export interface CodeInterpreterEnv {
 }
 /**
  * Error names and messages, besides `ResourceNotFoundException`, taken to mean "the session ended".
- * UNVERIFIED against the real AgentCore service (open question in HOST-RECIPE-AWS.md): they are the likely shapes of an
- * expired or terminated session. `AccessDeniedException` is deliberately NOT here: it is a permissions problem and
+ * These shapes are verified against the real AgentCore service (owner, 2026-10-12). `AccessDeniedException` is deliberately NOT here: it is a permissions problem and
  * renewing would not fix it. Matching needs both a listed name and a message pattern.
  */
 export declare const SESSION_ENDED_ERRORS: readonly {

package/dist/aws-code-interpreter.js

@@ -20,8 +20,7 @@ const sleep = (ms, signal) => new Promise(resolve => {
 });
 /**
  * Error names and messages, besides `ResourceNotFoundException`, taken to mean "the session ended".
- * UNVERIFIED against the real AgentCore service (open question in HOST-RECIPE-AWS.md): they are the likely shapes of an
- * expired or terminated session. `AccessDeniedException` is deliberately NOT here: it is a permissions problem and
+ * These shapes are verified against the real AgentCore service (owner, 2026-10-12). `AccessDeniedException` is deliberately NOT here: it is a permissions problem and
  * renewing would not fix it. Matching needs both a listed name and a message pattern.
  */
 export const SESSION_ENDED_ERRORS = [
@@ -60,6 +59,9 @@ export function createCodeInterpreterEnv(options) {
     if (!/^[0-7]{3,4}$/.test(umask))
         throw new TypeError('umask must be octal');
     const pollMs = options.pollIntervalMs ?? 500;
+    const serviceDeadlineMs = options.serviceDeadlineMs ?? 30_000;
+    /** The one deadline for every service call that could otherwise wait forever (the SDK sets no timeout): start, begin, polls and stop. */
+    const serviceDeadline = () => AbortSignal.timeout(serviceDeadlineMs);
     const borrowed = 'sessionId' in options.session ? options.session.sessionId : undefined;
     const start = 'start' in options.session ? options.session.start : undefined;
     const auto = start !== undefined && (options.renew ?? 'auto') === 'auto';
@@ -106,12 +108,21 @@ export function createCodeInterpreterEnv(options) {
             throw new ServiceError('SessionMissing', 'No Code Interpreter session');
         const { name, sessionTimeoutSeconds, filesystemConfigurations } = start;
         return starting ??= (async () => {
-            const response = await client.send(new StartCodeInterpreterSessionCommand({
-                codeInterpreterIdentifier,
-                ...(name === undefined ? {} : { name }),
-                ...(sessionTimeoutSeconds === undefined ? {} : { sessionTimeoutSeconds }),
-                ...(filesystemConfigurations === undefined ? {} : { filesystemConfigurations: [...filesystemConfigurations] }),
-            }));
+            const deadline = serviceDeadline();
+            let response;
+            try {
+                response = await client.send(new StartCodeInterpreterSessionCommand({
+                    codeInterpreterIdentifier,
+                    ...(name === undefined ? {} : { name }),
+                    ...(sessionTimeoutSeconds === undefined ? {} : { sessionTimeoutSeconds }),
+                    ...(filesystemConfigurations === undefined ? {} : { filesystemConfigurations: [...filesystemConfigurations] }),
+                }), { abortSignal: deadline });
+            }
+            catch (error) {
+                if (deadline.aborted)
+                    throw new ServiceError('StartTimeout', `The Code Interpreter did not answer the session start within ${serviceDeadlineMs / 1000} s: whether a session started is unknown`);
+                throw error;
+            }
             const id = response.sessionId;
             if (!id)
                 throw new ServiceError('SessionMissing', 'StartCodeInterpreterSession returned no session id');
@@ -146,10 +157,10 @@ export function createCodeInterpreterEnv(options) {
         }
     }
     /** One tool call; the streamed result, or a ServiceError for an exception (thrown or streamed). */
-    async function invoke(name, args, context, pinned) {
+    async function invoke(name, args, signal, pinned) {
         const id = pinned ?? await session();
         try {
-            const response = await client.send(new InvokeCodeInterpreterCommand({ codeInterpreterIdentifier, sessionId: id, name, arguments: args }), context?.abortSignal ? { abortSignal: context.abortSignal } : {});
+            const response = await client.send(new InvokeCodeInterpreterCommand({ codeInterpreterIdentifier, sessionId: id, name, arguments: args }), signal ? { abortSignal: signal } : {});
             let result;
             for await (const event of response.stream ?? []) {
                 if (event.result) {
@@ -187,8 +198,9 @@ export function createCodeInterpreterEnv(options) {
     const text = (result) => (result.content ?? []).map(block => block.text ?? '').join('');
     const TERMINAL = new Set(['completed', 'failed', 'canceled']);
     /** Asks the service to stop the task; the outcome is never assumed (the command's result says it is not confirmed). */
+    // Bounded like the start call: the SDK has no request timeout, so a stop answer that never comes must not hang the command.
     const stopTask = async (taskId, id) => { try {
-        await invoke('stopTask', { taskId }, undefined, id);
+        await invoke('stopTask', { taskId }, serviceDeadline(), id);
     }
     catch { /* reported as unconfirmed termination */ } };
     async function exec(command, execOptions, context) {
@@ -211,14 +223,30 @@ export function createCodeInterpreterEnv(options) {
             await prepare();
             // Every call of this command goes to the session it started in, even if a later command rotates.
             pinned = await session();
-            const started = await invoke('startCommandExecution', { command: script }, context, pinned);
-            taskId = started.structuredContent?.taskId;
-            if (!taskId)
-                return err(new ExecutionError('spawn_error', boundedMessage(`Code Interpreter did not start the command: ${text(started) || 'no task id'}`)));
         }
         catch (error) {
             return err(failure(error, 'spawn_error'));
         }
+        // A caller that cancelled while the session was being acquired gets no command: nothing is dispatched.
+        if (context.abortSignal?.aborted)
+            return err(new ExecutionError('aborted', 'Command aborted before dispatch'));
+        // The start call is not aborted by the caller: a task it started must always come back with its id, so the polling loop
+        // below can stop it. It has its own deadline instead, covering the whole response, because the SDK sets none. Nothing is
+        // replayed when it expires: the task may or may not exist, and only a stop with its id could end it.
+        const startDeadline = serviceDeadline();
+        let started;
+        try {
+            started = await invoke('startCommandExecution', { command: script }, startDeadline, pinned);
+        }
+        catch (error) {
+            if (startDeadline.aborted) {
+                return err(new ExecutionError('unknown', boundedMessage(`The Code Interpreter did not answer the start call within ${serviceDeadlineMs / 1000} s: whether the command started is unknown and it was not retried`)));
+            }
+            return err(failure(error, 'spawn_error'));
+        }
+        taskId = started.structuredContent?.taskId;
+        if (!taskId)
+            return err(new ExecutionError('spawn_error', boundedMessage(`Code Interpreter did not start the command: ${text(started) || 'no task id'}`)));
         const deadline = execOptions?.timeout && execOptions.timeout > 0 ? Date.now() + execOptions.timeout * 1000 : undefined;
         const seen = { stdout: '', stderr: '' };
         // getTask reports the output so far; a value that does not extend what was seen is treated as new output.
@@ -240,8 +268,9 @@ export function createCodeInterpreterEnv(options) {
                 return err(new ExecutionError('timeout', `Command exceeded ${execOptions?.timeout} s; stopTask was requested, termination is not confirmed`));
             }
             let status;
+            const pollDeadline = serviceDeadline();
             try {
-                const polled = await invoke('getTask', { taskId }, context, pinned);
+                const polled = await invoke('getTask', { taskId }, context.abortSignal ? AbortSignal.any([context.abortSignal, pollDeadline]) : pollDeadline, pinned);
                 status = polled.structuredContent;
                 try {
                     deliver('stdout', status?.stdout);
@@ -257,6 +286,9 @@ export function createCodeInterpreterEnv(options) {
             catch (error) {
                 if (context.abortSignal?.aborted)
                     continue;
+                // A poll that never answers is a transient poll failure: the state is unknown, and nothing is stopped or replayed.
+                if (pollDeadline.aborted)
+                    return err(new ExecutionError('unknown', boundedMessage(`The Code Interpreter did not answer a status poll within ${serviceDeadlineMs / 1000} s: the command's state is unknown`)));
                 return err(failure(error, 'unknown'));
             }
             if (status.taskStatus === 'completed' || (status.taskStatus === 'failed' && typeof status.exitCode === 'number'))

package/dist/fs-readers.d.ts

@@ -1,5 +1,5 @@
 import type { FileSystem } from '@earendil-works/pi-durable/env';
-type Source = Pick<FileSystem, 'readBinaryFile' | 'fileInfo' | 'listDir'>;
+type Source = Pick<FileSystem, 'readBinaryFile' | 'fileInfo' | 'listDir' | 'canonicalPath'>;
 export declare function snapshotReaders(source: Source): Pick<FileSystem, 'openBinaryReader' | 'openDirReader' | 'watch'>;
 /** A POSIX shell command that runs exactly `argv`: each word single-quoted. These environments run commands through a shell. */
 export declare function shellCommand(command: string | readonly string[]): string;

package/dist/fs-readers.js

@@ -6,15 +6,26 @@ import { FileError, LineScanner, ok, err } from '@earendil-works/pi-durable/env'
 export function snapshotReaders(source) {
     const guard = (closed, path, context) => context.abortSignal?.aborted ? new FileError('aborted', 'Operation aborted', path) : closed ? new FileError('invalid', 'Reader is closed', path) : undefined;
     return {
-        openBinaryReader: async (path, _options, context) => {
-            const info = await source.fileInfo(path, context);
+        openBinaryReader: async (path, options, context) => {
+            // `fileInfo` describes the final path itself. A symbolic link is followed unless the caller refuses it (`noFollow`).
+            const link = await source.fileInfo(path, context);
+            if (!link.ok)
+                return link;
+            let resolved = path;
+            if (link.value.kind === 'symlink' && !options?.noFollow) {
+                const canonical = await source.canonicalPath(path, context);
+                if (!canonical.ok)
+                    return canonical;
+                resolved = canonical.value;
+            }
+            const info = resolved === path ? link : await source.fileInfo(resolved, context);
             if (!info.ok)
                 return info;
             if (info.value.kind === 'directory')
                 return err(new FileError('is_directory', 'EISDIR: illegal operation on a directory', path));
             if (info.value.kind !== 'file')
                 return err(new FileError('invalid', 'Not a regular file', path));
-            const content = await source.readBinaryFile(path, context);
+            const content = await source.readBinaryFile(resolved, context);
             if (!content.ok)
                 return content;
             const bytes = content.value, opened = { ...info.value, size: bytes.length };
@@ -44,10 +55,15 @@ export function snapshotReaders(source) {
             });
         },
         openDirReader: async (path, context) => {
-            const listed = await source.listDir(path, context);
+            // Resolve the directory once: a later change of the environment's cwd must not move this reader to another directory.
+            const directory = await source.canonicalPath(path, context);
+            if (!directory.ok)
+                return directory;
+            const listed = await source.listDir(directory.value, context);
             if (!listed.ok)
                 return listed;
-            const entries = listed.value.filter(entry => entry.kind === 'file' || entry.kind === 'directory' || entry.kind === 'symlink');
+            const prefix = directory.value === '/' ? '' : directory.value;
+            const pending = listed.value.filter(entry => entry.kind === 'file' || entry.kind === 'directory' || entry.kind === 'symlink').map(entry => `${prefix}/${entry.name}`);
             let offset = 0, closed = false;
             return ok({
                 next: async (maxEntries, inner) => {
@@ -56,9 +72,16 @@ export function snapshotReaders(source) {
                         return err(failed);
                     if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
                         return err(new FileError('invalid', 'maxEntries must be a positive integer', path));
-                    const page = entries.slice(offset, offset + maxEntries);
-                    offset += page.length;
-                    return ok({ entries: page, done: offset >= entries.length });
+                    // Stat only the entries this page consumes; an entry removed since the open is skipped, as Pi's readers allow.
+                    const page = [];
+                    while (page.length < maxEntries && offset < pending.length) {
+                        const info = await source.fileInfo(pending[offset++], inner);
+                        if (info.ok)
+                            page.push(info.value);
+                        else if (info.error.code !== 'not_found')
+                            return err(info.error);
+                    }
+                    return ok({ entries: page, done: offset >= pending.length });
                 },
                 close: async () => { closed = true; },
             });

package/dist/virtual.js

@@ -135,7 +135,7 @@ function nativeEnvironment(fs, id, cwd, closed, release, createBash) {
         return path;
     }
     // Readers and the watcher over the memory file system's whole-file reads (see fs-readers.ts).
-    const readers = snapshotReaders({ readBinaryFile: (path, context) => environment.readBinaryFile(path, context), fileInfo: (path, context) => environment.fileInfo(path, context), listDir: (path, context) => environment.listDir(path, context) });
+    const readers = snapshotReaders({ readBinaryFile: (path, context) => environment.readBinaryFile(path, context), fileInfo: (path, context) => environment.fileInfo(path, context), listDir: (path, context) => environment.listDir(path, context), canonicalPath: (path, context) => environment.canonicalPath(path, context) });
     const environment = {
         id, cwd: posix.normalize(cwd), ...readers,
         absolutePath: (path, context) => run(path, context, path => path),
@@ -242,6 +242,9 @@ function nativeEnvironment(fs, id, cwd, closed, release, createBash) {
                 catch (cause) {
                     return err(new ExecutionError('spawn_error', `Working directory does not exist: ${cwd}\nCannot execute bash commands.`, cause instanceof Error ? cause : undefined));
                 }
+                // An argv with no program is a spawn error; nothing runs.
+                if (typeof command !== 'string' && command.length === 0)
+                    return err(new ExecutionError('spawn_error', 'Empty argv: there is no program to run'));
                 const result = await createBash({ cwd, ...(options?.timeout === undefined ? {} : { executionLimits: { maxExecutionTimeMs: options.timeout * 1000 } }) }).exec(shellCommand(command), {
                     ...(options?.env === undefined ? {} : { env: options.env }), replaceEnv: options?.inheritEnv === false,
                     signal: AbortSignal.any(signals),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-execution",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -52,13 +52,13 @@
     }
   },
   "peerDependencies": {
-    "@earendil-works/pi-durable": "1.1.0",
-    "@earendil-works/chord": "1.1.0",
-    "just-bash": "3.6.0",
-    "isomorphic-git": "1.42.6",
-    "@hachej/boring-files": "0.2.0",
-    "zod": "4.6.5",
-    "@aws-sdk/client-bedrock-agentcore": "3.1146.0"
+    "@earendil-works/pi-durable": "^1.1.0",
+    "@earendil-works/chord": "^1.1.0",
+    "just-bash": "^3.6.0",
+    "isomorphic-git": "^1.42.6",
+    "@hachej/boring-files": "^0.2.2",
+    "zod": "^4.6.5",
+    "@aws-sdk/client-bedrock-agentcore": "^3.1146.0"
   },
   "engines": {
     "node": ">=22.19.0"