@hachej/boring-execution 0.0.0-stage → 0.2.1

package/dist/aws-code-interpreter.js

@@ -0,0 +1,453 @@
+import { posix } from 'node:path';
+import { lstat, readlink, realpath } from 'node:fs/promises';
+import { InvokeCodeInterpreterCommand, StartCodeInterpreterSessionCommand, StopCodeInterpreterSessionCommand } from '@aws-sdk/client-bedrock-agentcore';
+import { ExecutionError, FileError, err, ok } from '@earendil-works/pi-durable/env';
+import { NodeExecutionEnv } from '@earendil-works/pi-durable/env/node';
+import { boundedMessage } from './bounded-error.js';
+import { shellCommand } from './fs-readers.js';
+const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+const MOUNT_PATH = /^\/mnt\/[A-Za-z0-9._-]+$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const within = (path, root) => path === root || path.startsWith(root.endsWith('/') ? root : `${root}/`);
+const errorName = (error) => typeof error === 'object' && error !== null && typeof error.name === 'string' ? error.name : 'Error';
+const errorText = (error) => boundedMessage(error);
+const sleep = (ms, signal) => new Promise(resolve => {
+    if (signal?.aborted)
+        return resolve();
+    const timer = setTimeout(done, ms);
+    function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); }
+    signal?.addEventListener('abort', done, { once: true });
+});
+/**
+ * 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
+ * renewing would not fix it. Matching needs both a listed name and a message pattern.
+ */
+export const SESSION_ENDED_ERRORS = [
+    { name: 'ValidationException', message: /session.*(terminat|expir|not (found|active|running)|no longer|ended|stopped)|(terminat|expir|stopped).*session/i },
+    { name: 'ConflictException', message: /session.*(terminat|expir|stopped|ended)/i },
+];
+const sessionEnded = (error) => {
+    const name = errorName(error);
+    if (name === 'ResourceNotFoundException')
+        return true;
+    const message = typeof error === 'object' && error !== null && typeof error.message === 'string' ? error.message : '';
+    return SESSION_ENDED_ERRORS.some(entry => entry.name === name && entry.message.test(message));
+};
+/** A stream error member of `InvokeCodeInterpreter` (the service reports some failures inside the stream). */
+const STREAM_ERRORS = ['accessDeniedException', 'conflictException', 'internalServerException', 'resourceNotFoundException', 'serviceQuotaExceededException', 'throttlingException', 'validationException'];
+class ServiceError extends Error {
+    constructor(name, message) { super(message); this.name = name; }
+}
+/**
+ * A native Pi `ExecutionEnv` over an AgentCore Code Interpreter session whose sandbox mounts the same folder this host
+ * mounts. Commands run in the session through the task API (`startCommandExecution`, `getTask`, `stopTask`); file
+ * operations run on this host's mount of the folder, so the agent's file tools, the workspace provider and the commands
+ * see the same bytes without copying them through the API. Nothing here creates AWS resources or credentials.
+ */
+export function createCodeInterpreterEnv(options) {
+    const { client, codeInterpreterIdentifier } = options;
+    const mountPath = posix.normalize(options.mount.path), root = posix.resolve(options.mount.root);
+    if (!MOUNT_PATH.test(mountPath) || mountPath === '/mnt/.' || mountPath === '/mnt/..')
+        throw new TypeError('mount.path must be /mnt/<name>, as AgentCore requires');
+    if (!options.id)
+        throw new TypeError('A file namespace id is required');
+    const cwd = posix.resolve(mountPath, options.cwd ?? mountPath);
+    if (!within(cwd, mountPath))
+        throw new TypeError('cwd must be inside mount.path');
+    const umask = options.umask ?? '002';
+    if (!/^[0-7]{3,4}$/.test(umask))
+        throw new TypeError('umask must be octal');
+    const pollMs = options.pollIntervalMs ?? 500;
+    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';
+    const ttlMs = (start?.sessionTimeoutSeconds ?? 900) * 1000;
+    const marginMs = Math.min((options.rotateMarginSeconds ?? 60) * 1000, ttlMs / 2);
+    let sessionId = borrowed, starting, lost = false, stopped = false, startedAt = 0, rotateRetryAt = 0;
+    const forgetLost = () => { lost = false; sessionId = undefined; }; // the next command starts a new session
+    // Every session this env started and has not confirmed stopped (rotation never stops one), and the stops in flight.
+    const owned = new Set(), stopping = new Map();
+    const stopSession = (id, signal) => {
+        let stop = stopping.get(id);
+        if (!stop) {
+            stop = (async () => {
+                try {
+                    await client.send(new StopCodeInterpreterSessionCommand({ codeInterpreterIdentifier, sessionId: id }), signal ? { abortSignal: signal } : {});
+                }
+                catch (error) {
+                    if (errorName(error) !== 'ResourceNotFoundException')
+                        throw error;
+                }
+                owned.delete(id);
+            })().finally(() => { stopping.delete(id); });
+            stopping.set(id, stop);
+        }
+        return stop;
+    };
+    const local = new NodeExecutionEnv({ cwd: root });
+    // ---- Session: borrowed or owned, started lazily, reported lost instead of silently replaced.
+    // The start is never cancelled half way: an abandoned start could leave a session nobody stops.
+    async function session() {
+        if (lost)
+            throw new ServiceError('SessionLost', 'The Code Interpreter session is gone (expired or stopped); files on the mount remain');
+        if (stopped)
+            throw new ServiceError('SessionStopped', 'The Code Interpreter session was stopped by its owner');
+        if (sessionId)
+            return sessionId;
+        if (!start)
+            throw new ServiceError('SessionMissing', 'No Code Interpreter session');
+        return begin();
+    }
+    /** Starts a session: the first one, a replacement after a loss, or a rotation. One start at a time; callers share it. */
+    function begin() {
+        if (!start)
+            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 id = response.sessionId;
+            if (!id)
+                throw new ServiceError('SessionMissing', 'StartCodeInterpreterSession returned no session id');
+            owned.add(id);
+            if (!stopped) {
+                sessionId = id;
+                startedAt = Date.now();
+                lost = false;
+            }
+            return id;
+        })().finally(() => { starting = undefined; });
+    }
+    /**
+     * Before a command (`'auto'` only): a lost session is replaced, and one near its time to live is rotated. The old
+     * session stays current until the new one is up, so a failed Start leaves everything working on the old one and backs
+     * off. Rotation never stops the old session: commands running there finish, and it expires on its own.
+     */
+    async function prepare() {
+        if (!auto || stopped)
+            return;
+        if (lost) {
+            forgetLost();
+            return;
+        }
+        if (!sessionId || (!starting && (Date.now() < rotateRetryAt || Date.now() - startedAt <= ttlMs - marginMs)))
+            return;
+        try {
+            await begin();
+        }
+        catch {
+            rotateRetryAt = Date.now() + Math.max(1000, marginMs / 4);
+        }
+    }
+    /** One tool call; the streamed result, or a ServiceError for an exception (thrown or streamed). */
+    async function invoke(name, args, context, 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 } : {});
+            let result;
+            for await (const event of response.stream ?? []) {
+                if (event.result) {
+                    result = event.result;
+                    continue;
+                }
+                for (const key of STREAM_ERRORS) {
+                    const failure = event[key];
+                    if (failure)
+                        throw new ServiceError(`${key[0].toUpperCase()}${key.slice(1)}`, failure.message ?? key);
+                }
+            }
+            if (!result)
+                throw new ServiceError('EmptyResult', `${name} returned no result`);
+            return result;
+        }
+        catch (error) {
+            if (sessionEnded(error)) {
+                owned.delete(id);
+                if (id === sessionId)
+                    lost = true;
+            }
+            throw error;
+        }
+    }
+    const failure = (error, fallback) => {
+        const name = errorName(error);
+        if (name === 'SessionLost' || name === 'SessionStopped' || name === 'SessionMissing' || name === 'AccessDeniedException' || sessionEnded(error)) {
+            return new ExecutionError('shell_unavailable', boundedMessage(`${name}: ${errorText(error)}`));
+        }
+        if (name === 'AbortError')
+            return new ExecutionError('aborted', 'Command aborted');
+        return new ExecutionError(fallback, boundedMessage(`${name}: ${errorText(error)}`));
+    };
+    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). */
+    const stopTask = async (taskId, id) => { try {
+        await invoke('stopTask', { taskId }, undefined, id);
+    }
+    catch { /* reported as unconfirmed termination */ } };
+    async function exec(command, execOptions, context) {
+        if (context.abortSignal?.aborted)
+            return err(new ExecutionError('aborted', 'Command aborted before dispatch'));
+        const directory = posix.resolve(env.cwd, execOptions?.cwd ?? '.');
+        const variables = Object.entries(execOptions?.env ?? {});
+        const invalid = variables.find(([name]) => !ENV_NAME.test(name));
+        if (invalid)
+            return err(new ExecutionError('spawn_error', boundedMessage(`Invalid environment variable name: ${invalid[0]}`)));
+        const assignments = variables.map(([name, value]) => `${name}=${quote(value)}`).join(' ');
+        // The task API takes one command string: cwd, environment and umask become part of it.
+        const runner = execOptions?.inheritEnv === false ? `env -i ${assignments} bash -c` : `${assignments ? `env ${assignments} ` : ''}bash -c`;
+        const script = `umask ${umask} && cd ${quote(directory)} && ${runner} ${quote(shellCommand(command))}`;
+        return dispatch(script, execOptions, context);
+    }
+    async function dispatch(script, execOptions, context) {
+        let taskId, pinned;
+        try {
+            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'));
+        }
+        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.
+        const deliver = (stream, value) => {
+            if (!value)
+                return;
+            const delta = value.startsWith(seen[stream]) ? value.slice(seen[stream].length) : value;
+            seen[stream] = value.startsWith(seen[stream]) ? value : seen[stream] + value;
+            if (delta)
+                execOptions?.onOutput?.(delta, context, { stream });
+        };
+        for (;;) {
+            if (context.abortSignal?.aborted) {
+                await stopTask(taskId, pinned);
+                return err(new ExecutionError('aborted', 'Command aborted; stopTask was requested, termination is not confirmed'));
+            }
+            if (deadline !== undefined && Date.now() >= deadline) {
+                await stopTask(taskId, pinned);
+                return err(new ExecutionError('timeout', `Command exceeded ${execOptions?.timeout} s; stopTask was requested, termination is not confirmed`));
+            }
+            let status;
+            try {
+                const polled = await invoke('getTask', { taskId }, context, pinned);
+                status = polled.structuredContent;
+                try {
+                    deliver('stdout', status?.stdout);
+                    deliver('stderr', status?.stderr);
+                }
+                catch (error) {
+                    await stopTask(taskId, pinned);
+                    return err(new ExecutionError('callback_error', boundedMessage(`Output callback failed: ${errorText(error)}`)));
+                }
+                if (!status?.taskStatus)
+                    return err(new ExecutionError('unknown', boundedMessage(`getTask returned no task status: ${text(polled)}`)));
+            }
+            catch (error) {
+                if (context.abortSignal?.aborted)
+                    continue;
+                return err(failure(error, 'unknown'));
+            }
+            if (status.taskStatus === 'completed' || (status.taskStatus === 'failed' && typeof status.exitCode === 'number'))
+                return ok({ exitCode: status.exitCode ?? 0 });
+            if (status.taskStatus === 'failed')
+                return err(new ExecutionError('unknown', 'The command failed without an exit code'));
+            if (status.taskStatus === 'canceled')
+                return err(new ExecutionError('aborted', 'The command was canceled in the Code Interpreter'));
+            await sleep(pollMs, context.abortSignal);
+        }
+    }
+    // ---- Files: interpreter paths mapped onto this host's mount of the same folder, confined to it.
+    let realRoot;
+    const namespace = (path) => posix.resolve(env.cwd, path);
+    const toLocal = (path) => {
+        const absolute = namespace(path);
+        return within(absolute, mountPath) ? posix.join(root, absolute.slice(mountPath.length)) : undefined;
+    };
+    const fromLocal = (path, base = root) => within(path, base) ? posix.join(mountPath, path.slice(base.length)) : mountPath;
+    const outside = (path) => new FileError('permission_denied', boundedMessage(`Outside the workspace: ${namespace(path)}`), namespace(path));
+    /** Whether `local` stays in the folder; `follow` also resolves a final symbolic link (dangling ones included). */
+    async function confined(local, follow) {
+        const base = await (realRoot ??= realpath(root));
+        let target = follow ? local : posix.dirname(local);
+        for (let hops = 0; hops < 40; hops++) {
+            let probe = target;
+            for (;;) {
+                try {
+                    await lstat(probe);
+                    break;
+                }
+                catch (error) {
+                    const code = error.code;
+                    if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                        return false;
+                    const up = posix.dirname(probe);
+                    if (up === probe)
+                        return false;
+                    probe = up;
+                }
+            }
+            try {
+                return within(await realpath(probe), base);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    return false;
+                // The probe exists but does not resolve: a dangling symbolic link. Follow it by hand.
+                try {
+                    target = posix.join(posix.resolve(posix.dirname(probe), await readlink(probe)), target.slice(probe.length));
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        return false;
+    }
+    const mapError = (error) => new FileError(error.code, boundedMessage(error.message.split(root).join(mountPath)), error.path !== undefined && within(error.path, root) ? fromLocal(error.path) : error.path, error);
+    const mapInfo = (info) => ({ ...info, path: fromLocal(info.path) });
+    async function guarded(paths, run) {
+        const locals = [];
+        for (const [path, follow] of paths) {
+            const mapped = toLocal(path);
+            if (mapped === undefined)
+                return err(outside(path));
+            try {
+                if (!await confined(mapped, follow))
+                    return err(outside(path));
+            }
+            catch (error) {
+                return err(new FileError('unknown', errorText(error), namespace(path)));
+            }
+            locals.push(mapped);
+        }
+        const result = await run(...locals);
+        return result.ok ? result : err(mapError(result.error));
+    }
+    const notSupported = (what) => err(new FileError('not_supported', `${what} is not available on the shared workspace mount`));
+    const env = {
+        id: options.id,
+        cwd,
+        absolutePath: async (path) => ok(namespace(path)),
+        joinPath: async (parts) => ok(posix.join(...parts)),
+        readTextFile: (path, context) => guarded([[path, true]], file => local.readTextFile(file, context)),
+        readBinaryFile: (path, context) => guarded([[path, true]], file => local.readBinaryFile(file, context)),
+        readTextLines: (path, lines, context) => guarded([[path, true]], file => local.readTextLines(file, lines, context)),
+        openTextLineReader: (path, context) => guarded([[path, true]], file => local.openTextLineReader(file, context)),
+        openBinaryReader: (path, readerOptions, context) => guarded([[path, !readerOptions?.noFollow]], file => local.openBinaryReader(file, readerOptions, context)),
+        openDirReader: (path, context) => guarded([[path, true]], directory => local.openDirReader(directory, context)),
+        // The mount's own watcher, with its paths reported in the workspace's namespace.
+        watch: async (targets, onChange, context) => {
+            const mapped = [];
+            for (const target of targets) {
+                const path = toLocal(target.path);
+                if (path === undefined)
+                    return err(outside(target.path));
+                mapped.push({ ...target, path });
+            }
+            const watcher = await local.watch(mapped, change => onChange('paths' in change ? { paths: change.paths.map(path => fromLocal(path)) } : 'error' in change ? { error: mapError(change.error) } : change), context);
+            return watcher.ok ? watcher : err(mapError(watcher.error));
+        },
+        writeFile: (path, content, context) => guarded([[path, true]], file => local.writeFile(file, content, context)),
+        appendFile: (path, content, context) => guarded([[path, true]], file => local.appendFile(file, content, context)),
+        truncateFile: (path, size, context) => guarded([[path, true]], file => local.truncateFile(file, size, context)),
+        flushFile: (path, context) => guarded([[path, true]], file => local.flushFile(file, context)),
+        renameFile: (source, destination, context) => guarded([[source, false], [destination, false]], (from, to) => local.renameFile(from, to, context)),
+        fileInfo: async (path, context) => { const info = await guarded([[path, false]], file => local.fileInfo(file, context)); return info.ok ? ok(mapInfo(info.value)) : info; },
+        listDir: async (path, context) => { const list = await guarded([[path, true]], directory => local.listDir(directory, context)); return list.ok ? ok(list.value.map(mapInfo)) : list; },
+        canonicalPath: async (path, context) => {
+            const resolved = await guarded([[path, true]], file => local.canonicalPath(file, context));
+            if (!resolved.ok)
+                return resolved;
+            const base = await (realRoot ??= realpath(root));
+            return within(resolved.value, base) ? ok(fromLocal(resolved.value, base)) : err(outside(path));
+        },
+        exists: (path, context) => guarded([[path, false]], file => local.exists(file, context)),
+        createDir: (path, directory, context) => guarded([[path, true]], file => local.createDir(file, directory, context)),
+        remove: (path, removal, context) => guarded([[path, false]], file => local.remove(file, removal, context)),
+        // A temporary file on this host would not be visible to the interpreter, and one in the folder would show in the workspace.
+        createTempDir: async () => notSupported('createTempDir'),
+        createTempFile: async () => notSupported('createTempFile'),
+        // Releasing a consumer's view never ends the session: only the owner's stop() does.
+        cleanup: async () => { },
+        exec,
+    };
+    return {
+        env, owned: start !== undefined,
+        sessionId: () => sessionId,
+        lost: () => lost,
+        renew: () => {
+            if (!start || stopped)
+                return false;
+            if (lost)
+                forgetLost();
+            return true;
+        },
+        stop: async (context) => {
+            if (!start)
+                return;
+            stopped = true;
+            await Promise.allSettled([starting]); // a start in flight still registers its session
+            const results = await Promise.allSettled([...owned].map(id => stopSession(id, context.abortSignal)));
+            const failed = results.find((result) => result.status === 'rejected');
+            if (failed)
+                throw failed.reason;
+        },
+    };
+}
+const USER_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * One EFS file system, one folder per user below the runtime's access point (root `/boring`, mounted at `/mnt/efs`):
+ * `users/<id>` (the interpreter's whole view, through the user's own access point rooted there) and `state/<id>` (the
+ * runtime's SQLite files, which no interpreter can reach). The runtime confines itself to the user's folders; the
+ * interpreter is confined by the access point itself.
+ */
+export function efsUserLayout(options) {
+    const { userId, uid } = options, gid = options.gid ?? 1000;
+    if (typeof userId !== 'string' || !USER_ID.test(userId))
+        throw new TypeError('userId must match [a-z0-9][a-z0-9_-]{0,63}');
+    if (!Number.isInteger(uid) || uid < 1001 || uid > 2_147_483_646)
+        throw new TypeError('uid must be an integer in 1001..2147483646');
+    if (!Number.isInteger(gid) || gid < 1 || gid > 2_147_483_646)
+        throw new TypeError('gid must be a positive integer');
+    const runtimeMount = posix.normalize(options.runtimeMountPath ?? '/mnt/efs'), interpreterMount = posix.normalize(options.interpreterMountPath ?? '/mnt/workspace');
+    if (!MOUNT_PATH.test(interpreterMount) || interpreterMount === '/mnt/.' || interpreterMount === '/mnt/..')
+        throw new TypeError(`The interpreter mount path must be /mnt/<name>: ${interpreterMount}`);
+    // AgentCore Runtime also requires /mnt/<name>; an ECS task or a test may mount the file system elsewhere.
+    if (!posix.isAbsolute(runtimeMount) || runtimeMount === '/')
+        throw new TypeError(`The runtime mount path must be an absolute directory: ${runtimeMount}`);
+    const base = posix.normalize(options.runtimeAccessPointRoot ?? '/boring');
+    if (!posix.isAbsolute(base) || base.split('/').includes('..'))
+        throw new TypeError(`The runtime access point root must be an absolute path: ${base}`);
+    const state = posix.join(runtimeMount, 'state', userId);
+    return {
+        userId,
+        namespaceId: `efs:${posix.join(base, 'users', userId)}`,
+        accessPoint: {
+            rootDirectory: posix.join(base, 'users', userId),
+            posixUser: { uid, gid },
+            // setgid directory: new entries keep the shared group.
+            creationInfo: { ownerUid: uid, ownerGid: gid, permissions: '2770' },
+            tags: [{ key: 'boring:user', value: userId }],
+        },
+        interpreter: { mountPath: interpreterMount, cwd: interpreterMount },
+        runtime: { root: posix.join(runtimeMount, 'users', userId), state, journal: posix.join(state, 'journal.sqlite') },
+        harnessFile: key => {
+            if (!/^[a-z0-9_-]{1,64}$/.test(key))
+                throw new TypeError('A conversation key matches [a-z0-9_-]{1,64}');
+            return posix.join(state, `${key}.pi.sqlite`);
+        },
+        filesystemConfiguration: ({ accessPointArn, fileSystemArn }) => ({ efsConfiguration: { accessPointArn, fileSystemArn, mountPath: interpreterMount } }),
+    };
+}

package/dist/bounded-error.d.ts

@@ -0,0 +1,8 @@
+/** Largest error text, in characters, that the shell, Git and the native environment of a workspace pass on (into a tool result). */
+export declare const MAX_ERROR_CHARS = 2000;
+/**
+ * The one bound on error text leaving a workspace environment (virtual or AWS Code Interpreter): the message only, never a stack (stack frames are dropped even when a backing
+ * put them in its message), at most `MAX_ERROR_CHARS`. The whole error stays on `cause` for the host's own logs.
+ */
+export declare function boundedMessage(error: unknown): string;
+//# sourceMappingURL=bounded-error.d.ts.map

package/dist/bounded-error.js

@@ -0,0 +1,12 @@
+// No imports: shared by the virtual workspace and the AWS Code Interpreter environment without loading either one's dependencies.
+/** Largest error text, in characters, that the shell, Git and the native environment of a workspace pass on (into a tool result). */
+export const MAX_ERROR_CHARS = 2000;
+/**
+ * The one bound on error text leaving a workspace environment (virtual or AWS Code Interpreter): the message only, never a stack (stack frames are dropped even when a backing
+ * put them in its message), at most `MAX_ERROR_CHARS`. The whole error stays on `cause` for the host's own logs.
+ */
+export function boundedMessage(error) {
+    const text = (error instanceof Error ? error.message : String(error)).replace(/\n[ \t]*at [^\n]*/g, '').trim() || 'Unknown error';
+    const note = ` [error truncated at ${MAX_ERROR_CHARS} characters]`;
+    return text.length > MAX_ERROR_CHARS ? `${text.slice(0, MAX_ERROR_CHARS - note.length)}${note}` : text;
+}

package/dist/contracts.d.ts

@@ -0,0 +1,46 @@
+import type { Context } from '@earendil-works/chord';
+import type { FileSystem, Shell, ExecutionEnv } from '@earendil-works/pi-durable/env';
+export interface WorkspaceIdentity {
+    readonly providerId: string;
+    readonly instanceId: string;
+    readonly incarnation: string;
+    readonly viewId: string;
+}
+/** A provider can expose files, shell, or both. Native Shell-only capability
+ * must not force a dummy filesystem. Pi's env factory still requires its
+ * complete ExecutionEnv when used; a shell-only tool closes over Shell.
+ *
+ * Reuse a native environment for compatible, stable cwd/view/scope bindings;
+ * fresh allocation per invocation is not required. Do not mutate one shared
+ * cwd across concurrent incompatible calls. Identity is not permission.
+ */
+export interface WorkspaceLease<Environment extends FileSystem | Shell = FileSystem> {
+    readonly identity: WorkspaceIdentity;
+    readonly environment: Environment;
+    readonly ownership: 'owned' | 'borrowed';
+    /** Release this lease, not other owners. Host supplies a usable cleanup
+     * Context. Idempotent release cannot count twice or destroy another lease.
+     * Native cleanup on a borrowed per-call facade is not provider disposal.
+     */
+    readonly release: (context: Context) => Promise<void>;
+}
+export type CodingWorkspaceLease = WorkspaceLease<ExecutionEnv>;
+export interface WorkspaceRequest<Input> {
+    readonly operationId: string;
+    readonly input: Input;
+}
+export interface WorkspaceProvider<Input, Environment extends FileSystem | Shell = FileSystem> {
+    readonly providerId: string;
+    readonly acquire: (request: WorkspaceRequest<Input>, context: Context) => Promise<WorkspaceLease<Environment>>;
+}
+export type Reattachment<Environment extends FileSystem | Shell> = {
+    readonly kind: 'available';
+    readonly lease: WorkspaceLease<Environment>;
+} | {
+    readonly kind: 'missing' | 'expired' | 'unavailable';
+    readonly reason: string;
+};
+export interface RecoverableWorkspaceProvider<Input, Environment extends FileSystem | Shell = FileSystem> extends WorkspaceProvider<Input, Environment> {
+    readonly reattach: (identity: WorkspaceIdentity, context: Context) => Promise<Reattachment<Environment>>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

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

package/dist/fs-readers.d.ts

@@ -0,0 +1,7 @@
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+type Source = Pick<FileSystem, 'readBinaryFile' | 'fileInfo' | 'listDir'>;
+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;
+export {};
+//# sourceMappingURL=fs-readers.d.ts.map

package/dist/fs-readers.js

@@ -0,0 +1,72 @@
+// Pi 1.0.3 asks every `FileSystem` for positional readers, paged directory readers and watchers. Environments here that hold no open
+// file handles (the in-memory virtual file system) build the readers on whole-file and whole-directory reads they
+// already have: a reader keeps the bytes or entries as they were when opened. They report no changes: `watch` is `not_supported`. The remote file system does not use this: its worker has native positional
+// readers, which `remote-files-positional.ts` forwards without moving the whole file.
+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);
+            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);
+            if (!content.ok)
+                return content;
+            const bytes = content.value, opened = { ...info.value, size: bytes.length };
+            let closed = false;
+            return ok({
+                info: async (inner) => { const failed = guard(closed, path, inner); return failed ? err(failed) : ok({ ...opened }); },
+                read: async (offset, length, inner) => {
+                    const failed = guard(closed, path, inner);
+                    if (failed)
+                        return err(failed);
+                    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 0)
+                        return err(new FileError('invalid', 'Offset and length must be non-negative integers', path));
+                    return ok(bytes.slice(offset, offset + length));
+                },
+                scanLines: async ({ startLine, endLine }, inner) => {
+                    const failed = guard(closed, path, inner);
+                    if (failed)
+                        return err(failed);
+                    if (!Number.isSafeInteger(startLine) || startLine < 0 || (endLine !== undefined && (!Number.isSafeInteger(endLine) || endLine <= startLine))) {
+                        return err(new FileError('invalid', 'Line range must be non-negative integers with endLine > startLine', path));
+                    }
+                    const scanner = new LineScanner(startLine, endLine);
+                    scanner.push(bytes);
+                    return ok(scanner.finish());
+                },
+                close: async () => { closed = true; },
+            });
+        },
+        openDirReader: async (path, context) => {
+            const listed = await source.listDir(path, context);
+            if (!listed.ok)
+                return listed;
+            const entries = listed.value.filter(entry => entry.kind === 'file' || entry.kind === 'directory' || entry.kind === 'symlink');
+            let offset = 0, closed = false;
+            return ok({
+                next: async (maxEntries, inner) => {
+                    const failed = guard(closed, path, inner);
+                    if (failed)
+                        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 });
+                },
+                close: async () => { closed = true; },
+            });
+        },
+        watch: async () => err(new FileError('not_supported', 'This environment does not report file changes')),
+    };
+}
+/** A POSIX shell command that runs exactly `argv`: each word single-quoted. These environments run commands through a shell. */
+export function shellCommand(command) {
+    return typeof command === 'string' ? command : command.map(word => `'${word.replaceAll("'", `'\\''`)}'`).join(' ');
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './native.js';
+export type * from './contracts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

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

package/dist/native.d.ts

@@ -0,0 +1,8 @@
+/** Native types are aliases, never a duplicated/narrowed Boring environment. */
+import type { HarnessOptions } from '@earendil-works/pi-durable';
+export type { FileSystem, Shell, ExecutionEnv, FileInfo, FileError, ExecutionError, Result, TextLineReader, ShellExecOptions, ShellExecResult, ShellSpillOptions, } from '@earendil-works/pi-durable/env';
+export type { Context } from '@earendil-works/chord';
+export type { EnvTarget } from '@earendil-works/pi-durable';
+/** Preserve native target/committed reads/Context, async and undefined results. */
+export type EnvironmentFactory = NonNullable<HarnessOptions['env']>;
+//# sourceMappingURL=native.d.ts.map

package/dist/native.js

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

package/dist/remote-files-handler.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '@earendil-works/chord';
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+import type { WorkspaceIdentity, WorkspaceLease } from './contracts.js';
+import type { RemoteFileSystemCall } from './remote-files-protocol.js';
+export interface RemoteFileSystemAccess {
+    readonly identity: WorkspaceIdentity;
+    readonly filesystemId: string;
+    readonly context: Context;
+    readonly revoked: AbortSignal;
+    readonly bindFileSystem: (cwd: string, context: Context) => Promise<WorkspaceLease<FileSystem>>;
+    readonly authorize: (call: RemoteFileSystemCall, cwd: string) => boolean | Promise<boolean>;
+}
+export interface RemoteFileSystemHandlerOptions {
+    readonly authenticate: (request: Request) => Promise<RemoteFileSystemAccess | null>;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxFrameBytes?: number;
+    readonly onCleanupError?: (error: unknown) => void;
+}
+export declare function createRemoteFileSystemHandler(options: RemoteFileSystemHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=remote-files-handler.d.ts.map