@sigrun/sigrun 0.1.6 → 0.2.0

package/dist/sandbox/protocol.js

@@ -0,0 +1,167 @@
+/** The newline-delimited JSON wire shared by the worker and its client. */
+import { ExecutionError, FileError, } from "@earendil-works/pi-durable/env";
+/** Encode binary without ambiguity; undefined void results become null. */
+export function encodeValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (value instanceof Uint8Array) {
+        return { $bytes: Buffer.from(value).toString("base64") };
+    }
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("non-finite number on sandbox wire");
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(encodeValue);
+    if (typeof value === "object") {
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (item !== undefined)
+                result[key] = encodeValue(item);
+        }
+        return result;
+    }
+    throw new TypeError(`unsupported sandbox wire value: ${typeof value}`);
+}
+/** Decode binary; handle sentinels remain plain objects for the client to own. */
+export function decodeValue(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(decodeValue);
+    if ("$bytes" in value) {
+        if (Object.keys(value).length !== 1 || typeof value.$bytes !== "string") {
+            throw new TypeError("invalid $bytes value on sandbox wire");
+        }
+        return new Uint8Array(Buffer.from(value.$bytes, "base64"));
+    }
+    if ("$handle" in value) {
+        if (Object.keys(value).length !== 1 ||
+            typeof value.$handle !== "number" ||
+            !Number.isSafeInteger(value.$handle) ||
+            value.$handle <= 0) {
+            throw new TypeError("invalid $handle value on sandbox wire");
+        }
+        return value;
+    }
+    const result = {};
+    for (const [key, item] of Object.entries(value))
+        result[key] = decodeValue(item);
+    return result;
+}
+export function encodeMessage(message) {
+    return `${JSON.stringify(encodeValue(message))}\n`;
+}
+export function decodeMessage(line) {
+    const value = JSON.parse(line);
+    if (typeof value !== "object" || value === null || !("id" in value)) {
+        throw new TypeError("invalid sandbox message");
+    }
+    const id = value.id;
+    if (typeof id !== "number" || !Number.isSafeInteger(id)) {
+        throw new TypeError("invalid sandbox message id");
+    }
+    if ("event" in value) {
+        if (value.event === "output") {
+            // SAFETY: the id was checked above; stream and text are checked below.
+            const event = value;
+            if ((event.stream !== "stdout" && event.stream !== "stderr") ||
+                typeof event.text !== "string") {
+                throw new TypeError("invalid sandbox output event");
+            }
+            return event;
+        }
+        if (value.event === "command" && "pid" in value && typeof value.pid === "number" &&
+            "phase" in value && (value.phase === "start" || value.phase === "end")) {
+            // SAFETY: id, numeric pid and the two command phases were checked.
+            return value;
+        }
+        if (value.event === "watch" && "change" in value) {
+            // SAFETY: id, event and change presence were checked above.
+            return value;
+        }
+        throw new TypeError("invalid sandbox event");
+    }
+    if (!("ok" in value) || typeof value.ok !== "boolean") {
+        throw new TypeError("invalid sandbox reply");
+    }
+    if (value.ok) {
+        if (!("value" in value))
+            throw new TypeError("sandbox reply has no value");
+        // SAFETY: id, ok and value presence were checked above.
+        return value;
+    }
+    if (!("error" in value))
+        throw new TypeError("sandbox failure has no error");
+    const error = value.error;
+    if ((error.kind !== "file" && error.kind !== "exec") ||
+        typeof error.code !== "string" ||
+        typeof error.message !== "string" ||
+        (error.path !== undefined && typeof error.path !== "string")) {
+        throw new TypeError("invalid sandbox error");
+    }
+    // SAFETY: id, ok=false and every required error field were checked above.
+    return value;
+}
+export function wireError(error, fallbackKind = "file") {
+    if (error instanceof FileError) {
+        return {
+            kind: "file",
+            code: error.code,
+            message: error.message,
+            ...(error.path === undefined ? {} : { path: error.path }),
+        };
+    }
+    if (error instanceof ExecutionError) {
+        return { kind: "exec", code: error.code, message: error.message };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { kind: fallbackKind, code: fallbackKind === "exec" ? "unknown" : "invalid", message };
+}
+export function errorReply(id, error, fallbackKind = "file") {
+    return { id, ok: false, error: wireError(error, fallbackKind) };
+}
+export function decodeError(error) {
+    return error.kind === "file"
+        ? new FileError(error.code, error.message, error.path)
+        : new ExecutionError(error.code, error.message);
+}
+export function decodeWatchChange(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("invalid watcher change");
+    }
+    if ("error" in value) {
+        const candidate = value.error;
+        if (typeof candidate !== "object" ||
+            candidate === null ||
+            Array.isArray(candidate) ||
+            candidate instanceof Uint8Array ||
+            "$handle" in candidate) {
+            throw new TypeError("invalid watcher error");
+        }
+        const kind = candidate.kind;
+        const code = candidate.code;
+        const message = candidate.message;
+        const path = candidate.path;
+        if (kind !== "file" ||
+            typeof code !== "string" ||
+            typeof message !== "string" ||
+            (path !== undefined && typeof path !== "string")) {
+            throw new TypeError("invalid watcher error");
+        }
+        return {
+            error: new FileError(code, message, path),
+        };
+    }
+    if ("overflow" in value && value.overflow === true)
+        return { overflow: true };
+    if ("paths" in value &&
+        Array.isArray(value.paths) &&
+        value.paths.every((path) => typeof path === "string")) {
+        return { paths: value.paths };
+    }
+    throw new TypeError("invalid watcher change");
+}

package/dist/sandbox/sandboxed-env.js

@@ -0,0 +1,245 @@
+/** Forward one ExecutionEnv over a user's worker, including live handles. */
+import { isAbsolute, resolve } from "node:path";
+import { FileError, } from "@earendil-works/pi-durable/env";
+import { decodeError, decodeValue, decodeWatchChange, } from "./protocol.js";
+function wireArgs(values) {
+    // The protocol encoder is intentionally shared with the worker; casting
+    // here is safe because the return value is checked as it is encoded.
+    return values.map((value) => {
+        if (value === undefined)
+            return null;
+        if (value instanceof Uint8Array)
+            return { $bytes: Buffer.from(value).toString("base64") };
+        if (Array.isArray(value))
+            return wireArgs(value);
+        if (typeof value === "object" && value !== null) {
+            const result = {};
+            for (const [key, item] of Object.entries(value)) {
+                if (item !== undefined && typeof item !== "function")
+                    result[key] = wireArgs([item])[0];
+            }
+            return result;
+        }
+        return value;
+    });
+}
+function decoded(value) {
+    return restoreResult(decodeValue(value));
+}
+function restoreResult(value) {
+    if (Array.isArray(value))
+        return value.map(restoreResult);
+    if (typeof value !== "object" || value === null || value instanceof Uint8Array || "$handle" in value)
+        return value;
+    if ("ok" in value && value.ok === false && "error" in value) {
+        const candidate = value.error;
+        if (typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && !(candidate instanceof Uint8Array) && !("$handle" in candidate)) {
+            const kind = candidate.kind;
+            const code = candidate.code;
+            const message = candidate.message;
+            const path = candidate.path;
+            if ((kind === "file" || kind === "exec") && typeof code === "string" && typeof message === "string") {
+                const wire = { kind, code, message, ...(typeof path === "string" ? { path } : {}) };
+                // SAFETY: pi-durable errors are class instances at the API boundary;
+                // DecodedValue deliberately describes JSON-only structural data.
+                return { ok: false, error: decodeError(wire) };
+            }
+        }
+    }
+    const result = {};
+    for (const [key, item] of Object.entries(value))
+        result[key] = restoreResult(item);
+    return result;
+}
+function handleId(value) {
+    if (typeof value !== "object" || value === null || !("$handle" in value)) {
+        throw new Error("sandbox worker did not return a handle");
+    }
+    const id = value.$handle;
+    if (typeof id !== "number")
+        throw new Error("sandbox worker returned an invalid handle");
+    return id;
+}
+class BaseRemoteHandle {
+    client;
+    id;
+    closed = false;
+    constructor(client, id) {
+        this.client = client;
+        this.id = id;
+    }
+    async close(context) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            if (this.client.hasHandle(this.id)) {
+                await this.client.call("handle.close", [this.id], undefined, context);
+            }
+        }
+        finally {
+            this.client.releaseHandle(this.id);
+        }
+    }
+    async call(method, args, context) {
+        if (this.closed)
+            throw new FileError("invalid", "sandbox handle is closed");
+        const value = await this.client.call(`handle.${method}`, [this.id, ...args], undefined, context);
+        return decoded(value);
+    }
+}
+class RemoteTextLineReader extends BaseRemoteHandle {
+    readLine(context) {
+        return this.call("readLine", [], context);
+    }
+}
+class RemoteBinaryReader extends BaseRemoteHandle {
+    info(context) {
+        return this.call("info", [], context);
+    }
+    read(offset, length, context) {
+        return this.call("read", [offset, length], context);
+    }
+    scanLines(options, context) {
+        return this.call("scanLines", [options], context);
+    }
+}
+class RemoteDirReader extends BaseRemoteHandle {
+    next(maxEntries, context) {
+        return this.call("next", [maxEntries], context);
+    }
+}
+class RemoteWatcher extends BaseRemoteHandle {
+    mode;
+    constructor(client, id, mode) {
+        super(client, id);
+        this.mode = mode;
+    }
+}
+/** Every required FileSystem and Shell member is explicitly forwarded. */
+export class SandboxedExecutionEnv {
+    client;
+    id;
+    currentCwd;
+    listFilesForwarder;
+    constructor(client, cwd) {
+        this.client = client;
+        this.id = `sandbox:${client.user}`;
+        this.currentCwd = cwd;
+    }
+    get cwd() {
+        return this.currentCwd;
+    }
+    set cwd(value) {
+        this.currentCwd = isAbsolute(value) ? value : resolve(this.currentCwd, value);
+    }
+    get listFiles() {
+        return this.listFilesForwarder;
+    }
+    async call(op, args, context, onEvent) {
+        // Result is the ExecutionEnv error channel; only transport failures
+        // reject. Never turn an ordinary ENOENT into an RPC exception.
+        const value = await this.client.call("result", wireArgs([op, args, this.currentCwd]), onEvent, context);
+        // A capability reply is consumed by the client at worker start. Install
+        // the optional member only after the worker has actually advertised it.
+        const capabilities = await this.client.capabilities();
+        if (capabilities.listFiles)
+            this.listFilesForwarder ??= this.forwardListFiles.bind(this);
+        return decoded(value);
+    }
+    forwardListFiles(path, options, context) {
+        return this.call("listFiles", [path, options], context);
+    }
+    absolutePath(path, context) {
+        return this.call("absolutePath", [path], context);
+    }
+    joinPath(parts, context) {
+        return this.call("joinPath", [parts], context);
+    }
+    readTextFile(path, context) {
+        return this.call("readTextFile", [path], context);
+    }
+    async openTextLineReader(path, context) {
+        const result = await this.call("openTextLineReader", [path], context);
+        return result.ok ? { ok: true, value: new RemoteTextLineReader(this.client, handleId(result.value)) } : result;
+    }
+    readTextLines(path, options, context) {
+        return this.call("readTextLines", [path, options], context);
+    }
+    readBinaryFile(path, context) {
+        return this.call("readBinaryFile", [path], context);
+    }
+    async openBinaryReader(path, options, context) {
+        const result = await this.call("openBinaryReader", [path, options], context);
+        return result.ok ? { ok: true, value: new RemoteBinaryReader(this.client, handleId(result.value)) } : result;
+    }
+    writeFile(path, content, context) {
+        return this.call("writeFile", [path, content], context);
+    }
+    appendFile(path, content, context) {
+        return this.call("appendFile", [path, content], context);
+    }
+    truncateFile(path, size, context) {
+        return this.call("truncateFile", [path, size], context);
+    }
+    flushFile(path, context) {
+        return this.call("flushFile", [path], context);
+    }
+    renameFile(sourcePath, destinationPath, context) {
+        return this.call("renameFile", [sourcePath, destinationPath], context);
+    }
+    fileInfo(path, context) {
+        return this.call("fileInfo", [path], context);
+    }
+    listDir(path, context) {
+        return this.call("listDir", [path], context);
+    }
+    async openDirReader(path, context) {
+        const result = await this.call("openDirReader", [path], context);
+        return result.ok ? { ok: true, value: new RemoteDirReader(this.client, handleId(result.value)) } : result;
+    }
+    async watch(targets, onChange, context) {
+        const result = await this.call("watch", [targets], context, (event) => {
+            if (event.event === "watch")
+                onChange(decodeWatchChange(decodeValue(event.change)));
+        });
+        return result.ok
+            ? { ok: true, value: new RemoteWatcher(this.client, handleId(result.value.handle), result.value.mode) }
+            : result;
+    }
+    canonicalPath(path, context) {
+        return this.call("canonicalPath", [path], context);
+    }
+    exists(path, context) {
+        return this.call("exists", [path], context);
+    }
+    createDir(path, options, context) {
+        return this.call("createDir", [path, options], context);
+    }
+    remove(path, options, context) {
+        return this.call("remove", [path, options], context);
+    }
+    createTempDir(prefix, context) {
+        return this.call("createTempDir", [prefix], context);
+    }
+    createTempFile(options, context) {
+        return this.call("createTempFile", [options], context);
+    }
+    async cleanup(_context) {
+        // NO-OP: this worker is shared by all of the user's conversations;
+        // cleanup here would kill another conversation's live commands.
+    }
+    exec(command, options, context) {
+        const wireOptions = { ...(options ?? {}) };
+        delete wireOptions.onOutput;
+        return this.call("exec", [command, wireOptions], context, (event) => {
+            if (event.event !== "output")
+                return;
+            const info = {
+                stream: event.stream,
+                ...(event.skipped === undefined ? {} : { skipped: event.skipped }),
+            };
+            options?.onOutput?.(event.text, context, info);
+        });
+    }
+}

package/dist/sandbox/unavailable-env.js

@@ -0,0 +1,49 @@
+/** An ExecutionEnv that can never touch a filesystem or start a process. */
+import { ExecutionError, FileError, } from "@earendil-works/pi-durable/env";
+export class UnavailableExecutionEnv {
+    id = "unavailable";
+    cwd = ".";
+    message;
+    constructor(reason) {
+        this.message = `isolation_unavailable: ${reason}`;
+    }
+    file() {
+        return Promise.resolve({ ok: false, error: new FileError("permission_denied", this.message) });
+    }
+    shell() {
+        return Promise.resolve({ ok: false, error: new ExecutionError("spawn_error", this.message) });
+    }
+    absolutePath() { return this.file(); }
+    joinPath() { return this.file(); }
+    readTextFile() { return this.file(); }
+    openTextLineReader() { return this.file(); }
+    readTextLines() { return this.file(); }
+    readBinaryFile() { return this.file(); }
+    openBinaryReader() { return this.file(); }
+    writeFile() { return this.file(); }
+    appendFile() { return this.file(); }
+    truncateFile() { return this.file(); }
+    flushFile() { return this.file(); }
+    renameFile() { return this.file(); }
+    fileInfo() { return this.file(); }
+    listDir() { return this.file(); }
+    listFiles(_path, _options, _context) {
+        return this.file();
+    }
+    openDirReader() { return this.file(); }
+    watch(_targets, _onChange, _context) {
+        return this.file();
+    }
+    canonicalPath() { return this.file(); }
+    exists() { return this.file(); }
+    createDir() { return this.file(); }
+    remove() { return this.file(); }
+    createTempDir() { return this.file(); }
+    createTempFile() { return this.file(); }
+    cleanup() {
+        return Promise.reject(new FileError("permission_denied", this.message));
+    }
+    exec(_command, _options, _context) {
+        return this.shell();
+    }
+}