@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/artifacts/workspace.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The `WorkspaceReader` seam (F8.2): how core reads a session's sandbox workspace at turn end, to
+ * export its outputs as a folder artifact. Two calls, a listing and one file's bytes, both the
+ * claim of whoever holds the workspace: the Runtime stores what it is given without observing it.
+ *
+ * One implementation, `sandboxWorkspaceReader`, over the workspace capability (F6.2,
+ * `harness-api/workspace.ts`): the in-process `SandboxManager`, or the harness that serves the
+ * Tenant's workspaces (`workspace.read`). F6.2 reimplements it over the Harness API's `workspace.read`, and F7.2's pod
+ * sandboxes are read through the same seam, so the export never knows which kind of sandbox it
+ * reads.
+ */
+import { type AgentManifest } from "@nylorun/core/define";
+import { type SandboxManager } from "../sandbox/manager.js";
+/** What the reader needs of a workspace: a `SandboxManager`, or the workspace capability. */
+export type WorkspaceFiles = Pick<SandboxManager, "listFiles" | "readBytes">;
+/** Whose workspace to read: the session whose turn ended, resolved to the workspace it uses. */
+export interface WorkspaceSession {
+    /** The session whose turn ended. */
+    readonly sessionId: string;
+    /** The turn that ended. */
+    readonly turnId: string | null;
+    /** The session that owns the workspace (one hop through `sandboxOwnerId`). */
+    readonly ownerId: string;
+    /** The sandbox resource the workspace belongs to, when the owner is attached to one. */
+    readonly sandboxId?: string;
+    /** The session's pinned manifest: its sandbox capability carries the sandbox's spec. */
+    readonly manifest: AgentManifest;
+}
+/** One regular file under the listed directory. */
+export interface WorkspaceEntry {
+    /** Relative to the directory listed, `/`-separated, never `.` or `..` segments. */
+    readonly path: string;
+    readonly size: number;
+}
+export interface WorkspaceListing {
+    /** The files in path order, symbolic links left out. */
+    readonly entries: readonly WorkspaceEntry[];
+    /** More than `maxEntries` files: `entries` holds `maxEntries + 1` of them. */
+    readonly truncated: boolean;
+}
+export interface WorkspaceReader {
+    /**
+     * The regular files under `dir` (absolute, e.g. `/workspace/outputs`), recursively. Undefined
+     * when the session has no sandbox, its sandbox was never created, or `dir` is not a directory.
+     */
+    list(session: WorkspaceSession, dir: string, options: {
+        readonly maxEntries: number;
+        readonly signal: AbortSignal;
+    }): Promise<WorkspaceListing | undefined>;
+    /**
+     * One file's bytes (absolute path), or undefined when it is gone. A file larger than
+     * `maxBytes` throws `SandboxFileTooLargeError`; a sandbox that fails throws.
+     */
+    readBytes(session: WorkspaceSession, path: string, options: {
+        readonly maxBytes: number;
+        readonly signal: AbortSignal;
+    }): Promise<Uint8Array | undefined>;
+}
+/** The reader over the workspaces, in each sandbox's queue of tool calls. */
+export declare function sandboxWorkspaceReader(sandbox: WorkspaceFiles): WorkspaceReader;

package/dist/artifacts/workspace.js

@@ -0,0 +1,57 @@
+/**
+ * The `WorkspaceReader` seam (F8.2): how core reads a session's sandbox workspace at turn end, to
+ * export its outputs as a folder artifact. Two calls, a listing and one file's bytes, both the
+ * claim of whoever holds the workspace: the Runtime stores what it is given without observing it.
+ *
+ * One implementation, `sandboxWorkspaceReader`, over the workspace capability (F6.2,
+ * `harness-api/workspace.ts`): the in-process `SandboxManager`, or the harness that serves the
+ * Tenant's workspaces (`workspace.read`). F6.2 reimplements it over the Harness API's `workspace.read`, and F7.2's pod
+ * sandboxes are read through the same seam, so the export never knows which kind of sandbox it
+ * reads.
+ */
+import { SANDBOX_CAPABILITY_ID, } from "@nylorun/core/define";
+import { sandboxCapabilityOf } from "../sandbox/manager.js";
+import { SandboxFileTooLargeError } from "../sandbox/types.js";
+/** The reader over the workspaces, in each sandbox's queue of tool calls. */
+export function sandboxWorkspaceReader(sandbox) {
+    const target = (session) => {
+        const capability = sandboxCapabilityOf(session.manifest, SANDBOX_CAPABILITY_ID, "read");
+        if (!capability)
+            return undefined;
+        return {
+            capability,
+            ref: {
+                id: session.ownerId,
+                activeTurnId: session.turnId,
+                manifest: session.manifest,
+                ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+            },
+        };
+    };
+    return {
+        async list(session, dir, options) {
+            const found = target(session);
+            if (!found)
+                return undefined;
+            const listed = await sandbox.listFiles(found.ref, found.capability, dir, options.maxEntries, options.signal);
+            if (listed.kind === "missing")
+                return undefined;
+            if (listed.kind === "failed")
+                throw new Error(listed.message);
+            return listed.listing;
+        },
+        async readBytes(session, path, options) {
+            const found = target(session);
+            if (!found)
+                return undefined;
+            const read = await sandbox.readBytes(found.ref, found.capability, path, options.maxBytes, options.signal);
+            if (read.kind === "read")
+                return read.bytes;
+            if (read.kind === "missing")
+                return undefined;
+            if (read.code === "artifact.too_large")
+                throw new SandboxFileTooLargeError(path, options.maxBytes + 1, options.maxBytes);
+            throw new Error(read.message);
+        },
+    };
+}

package/dist/artifacts/zip.d.ts

@@ -0,0 +1,10 @@
+export interface ZipEntry {
+    /** The path in the archive, `/`-separated. */
+    readonly name: string;
+    /** The file's bytes, opened only when the writer reaches it. */
+    readonly open: () => Promise<AsyncIterable<Uint8Array>>;
+}
+/** Why a folder cannot be zipped without ZIP64, or undefined when it can. */
+export declare function zipTooLarge(files: number, bytes: number): string | undefined;
+/** The archive's bytes, as the writer produces them. */
+export declare function zipStream(entries: readonly ZipEntry[], modified?: Date): AsyncGenerator<Uint8Array>;

package/dist/artifacts/zip.js

@@ -0,0 +1,126 @@
+/**
+ * A streaming zip writer (PKWARE APPNOTE 6.3), enough for a folder artifact's download: each
+ * file deflated as it streams, its CRC-32 and sizes in a data descriptor after it (general
+ * purpose bit 3) and again in the central directory, names in UTF-8 (bit 11). Nothing is
+ * buffered beyond one chunk. No ZIP64: a folder this serves stays under 4 GiB and 65,535 files
+ * (the export's limits), and `zipTooLarge` says when one would not.
+ */
+import { constants, crc32, createDeflateRaw } from "node:zlib";
+const LOCAL = 0x04034b50;
+const DESCRIPTOR = 0x08074b50;
+const CENTRAL = 0x02014b50;
+const END = 0x06054b50;
+const FLAGS = 0x0808; // bit 3: sizes in a data descriptor; bit 11: UTF-8 names
+const DEFLATE = 8;
+const VERSION = 20;
+/** Made by Unix (3), so the external attributes below are a Unix mode. */
+const MADE_BY_UNIX = (3 << 8) | VERSION;
+/** A regular file, `rw-r--r--`, in the high 16 bits. */
+const REGULAR_FILE = (0o100644 << 16) >>> 0;
+const MAX_32 = 0xffffffff;
+/** Why a folder cannot be zipped without ZIP64, or undefined when it can. */
+export function zipTooLarge(files, bytes) {
+    if (files > 0xffff)
+        return `A zip holds at most 65535 files; this folder has ${files}`;
+    // Deflate adds at most 5 bytes per 16 KiB block; keep well clear of 4 GiB.
+    if (bytes > 3.5 * 1024 * 1024 * 1024)
+        return `A zip holds at most 3.5 GiB; this folder has ${bytes} bytes`;
+    return undefined;
+}
+/** MS-DOS date and time, as zip headers store them (local time is not known: UTC). */
+function dosDateTime(date) {
+    const year = Math.max(1980, date.getUTCFullYear());
+    return {
+        time: (date.getUTCHours() << 11) | (date.getUTCMinutes() << 5) | (date.getUTCSeconds() >> 1),
+        date: ((year - 1980) << 9) | ((date.getUTCMonth() + 1) << 5) | date.getUTCDate(),
+    };
+}
+/** The archive's bytes, as the writer produces them. */
+export async function* zipStream(entries, modified = new Date()) {
+    const stamp = dosDateTime(modified);
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name, "utf8");
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(LOCAL, 0);
+        local.writeUInt16LE(VERSION, 4);
+        local.writeUInt16LE(FLAGS, 6);
+        local.writeUInt16LE(DEFLATE, 8);
+        local.writeUInt16LE(stamp.time, 10);
+        local.writeUInt16LE(stamp.date, 12);
+        // CRC and sizes (14–25) are zero: they follow in the data descriptor.
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        const headerAt = offset;
+        yield local;
+        yield name;
+        offset += local.length + name.length;
+        let crc = 0;
+        let size = 0;
+        let compressed = 0;
+        const deflate = createDeflateRaw({ level: constants.Z_DEFAULT_COMPRESSION });
+        const source = await entry.open();
+        const feed = (async () => {
+            try {
+                for await (const chunk of source) {
+                    // The reader went away (a cancelled download): stop reading the file.
+                    if (deflate.destroyed)
+                        break;
+                    crc = crc32(chunk, crc);
+                    size += chunk.length;
+                    if (!deflate.write(chunk))
+                        await new Promise((resolve) => {
+                            deflate.once("drain", resolve);
+                            deflate.once("close", resolve);
+                        });
+                }
+                if (!deflate.destroyed)
+                    deflate.end();
+            }
+            catch (error) {
+                deflate.destroy(error);
+            }
+        })();
+        for await (const chunk of deflate) {
+            compressed += chunk.length;
+            yield chunk;
+        }
+        await feed;
+        offset += compressed;
+        if (offset > MAX_32 || size > MAX_32)
+            throw new Error("The folder is too large to zip without ZIP64");
+        const descriptor = Buffer.alloc(16);
+        descriptor.writeUInt32LE(DESCRIPTOR, 0);
+        descriptor.writeUInt32LE(crc >>> 0, 4);
+        descriptor.writeUInt32LE(compressed, 8);
+        descriptor.writeUInt32LE(size, 12);
+        yield descriptor;
+        offset += descriptor.length;
+        const record = Buffer.alloc(46);
+        record.writeUInt32LE(CENTRAL, 0);
+        record.writeUInt16LE(MADE_BY_UNIX, 4);
+        record.writeUInt16LE(VERSION, 6);
+        record.writeUInt16LE(FLAGS, 8);
+        record.writeUInt16LE(DEFLATE, 10);
+        record.writeUInt16LE(stamp.time, 12);
+        record.writeUInt16LE(stamp.date, 14);
+        record.writeUInt32LE(crc >>> 0, 16);
+        record.writeUInt32LE(compressed, 20);
+        record.writeUInt32LE(size, 24);
+        record.writeUInt16LE(name.length, 28);
+        // Extra, comment, disk and internal attributes (30–37) stay zero.
+        record.writeUInt32LE(REGULAR_FILE, 38);
+        record.writeUInt32LE(headerAt, 42);
+        central.push(record, name);
+    }
+    const directory = Buffer.concat(central);
+    yield directory;
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(END, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    yield end;
+}

package/dist/blob/fs.d.ts

@@ -0,0 +1,13 @@
+import { type BlobStore } from "./types.js";
+export interface FsBlobStoreOptions {
+    /** Absolute directory the store owns; created on the first write. */
+    root: string;
+}
+/**
+ * The `fs` adapter: objects as files under `root`, for embedding (`startEphemeralRuntime`, a
+ * Host without an Object store) and tests. `objects/<key>` holds the bytes, `meta/<key>.json`
+ * the content type; a write goes to `tmp/` first and is renamed into place, so a reader sees
+ * the old object or the new one, never part of one. A key cannot also be the directory of
+ * another key (`a` and `a/b`); the Runtime's keys never are.
+ */
+export declare function createFsBlobStore(options: FsBlobStoreOptions): BlobStore;

package/dist/blob/fs.js

@@ -0,0 +1,194 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, rm, stat, unlink } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { Readable } from "node:stream";
+import { BlobRangeError, BlobTooLargeError, DEFAULT_CONTENT_TYPE, assertBlobKey, assertBlobPrefix, assertMaxBytes, assertRange, chunksOf, } from "./types.js";
+function isMissing(error) {
+    const code = error?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * The `fs` adapter: objects as files under `root`, for embedding (`startEphemeralRuntime`, a
+ * Host without an Object store) and tests. `objects/<key>` holds the bytes, `meta/<key>.json`
+ * the content type; a write goes to `tmp/` first and is renamed into place, so a reader sees
+ * the old object or the new one, never part of one. A key cannot also be the directory of
+ * another key (`a` and `a/b`); the Runtime's keys never are.
+ */
+export function createFsBlobStore(options) {
+    const objects = join(options.root, "objects");
+    const metadata = join(options.root, "meta");
+    const tmp = join(options.root, "tmp");
+    const objectPath = (key) => join(objects, ...key.split("/"));
+    const metaPath = (key) => `${join(metadata, ...key.split("/"))}.json`;
+    async function readMeta(key) {
+        try {
+            const parsed = JSON.parse(await readFile(metaPath(key), "utf8"));
+            return { contentType: parsed.contentType ?? DEFAULT_CONTENT_TYPE };
+        }
+        catch {
+            return { contentType: DEFAULT_CONTENT_TYPE };
+        }
+    }
+    async function head(key) {
+        assertBlobKey(key);
+        let stats;
+        try {
+            stats = await stat(objectPath(key));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return undefined;
+            throw error;
+        }
+        if (!stats.isFile())
+            return undefined;
+        const meta = await readMeta(key);
+        return { key, size: stats.size, contentType: meta.contentType, lastModified: stats.mtime };
+    }
+    return {
+        kind: "fs",
+        async put(key, body, put = {}) {
+            assertBlobKey(key);
+            assertMaxBytes(put.maxBytes);
+            put.signal?.throwIfAborted();
+            await mkdir(tmp, { recursive: true });
+            const id = randomUUID();
+            const dataTmp = join(tmp, id);
+            const metaTmp = join(tmp, `${id}.json`);
+            const hash = createHash("sha256");
+            let size = 0;
+            const file = await open(dataTmp, "wx", 0o600);
+            try {
+                try {
+                    for await (const chunk of chunksOf(body)) {
+                        put.signal?.throwIfAborted();
+                        size += chunk.byteLength;
+                        if (put.maxBytes !== undefined && size > put.maxBytes)
+                            throw new BlobTooLargeError(put.maxBytes);
+                        hash.update(chunk);
+                        await file.write(chunk);
+                    }
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                const stored = { contentType: put.contentType ?? DEFAULT_CONTENT_TYPE };
+                await writeTmp(metaTmp, JSON.stringify(stored));
+                await mkdir(dirname(objectPath(key)), { recursive: true });
+                await mkdir(dirname(metaPath(key)), { recursive: true });
+                await rename(metaTmp, metaPath(key));
+                await rename(dataTmp, objectPath(key));
+            }
+            catch (error) {
+                await rm(dataTmp, { force: true });
+                await rm(metaTmp, { force: true });
+                throw error;
+            }
+            return { key, size, sha256: hash.digest("hex") };
+        },
+        async get(key, get = {}) {
+            assertBlobKey(key);
+            if (get.range)
+                assertRange(get.range);
+            get.signal?.throwIfAborted();
+            let file;
+            try {
+                file = await open(objectPath(key), "r");
+            }
+            catch (error) {
+                if (isMissing(error) || error?.code === "EISDIR")
+                    return undefined;
+                throw error;
+            }
+            try {
+                const stats = await file.stat();
+                if (!stats.isFile()) {
+                    await file.close();
+                    return undefined;
+                }
+                const meta = await readMeta(key);
+                const base = {
+                    key,
+                    size: stats.size,
+                    contentType: meta.contentType,
+                    lastModified: stats.mtime,
+                };
+                if (!get.range) {
+                    const stream = file.createReadStream({ autoClose: true });
+                    return { ...base, body: Readable.toWeb(stream) };
+                }
+                if (get.range.start >= stats.size)
+                    throw new BlobRangeError(get.range, stats.size);
+                const end = Math.min(get.range.end ?? stats.size - 1, stats.size - 1);
+                const stream = file.createReadStream({ start: get.range.start, end, autoClose: true });
+                return {
+                    ...base,
+                    body: Readable.toWeb(stream),
+                    range: { start: get.range.start, end },
+                };
+            }
+            catch (error) {
+                await file.close().catch(() => undefined);
+                throw error;
+            }
+        },
+        head,
+        async delete(key) {
+            assertBlobKey(key);
+            for (const path of [objectPath(key), metaPath(key)])
+                try {
+                    await unlink(path);
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (!isMissing(error) && code !== "EISDIR" && code !== "EPERM")
+                        throw error;
+                }
+        },
+        async *list(prefix) {
+            assertBlobPrefix(prefix);
+            // Walk the deepest directory the prefix names, then filter and sort: `a-b` sorts before
+            // `a/c`, so directory order is not key order.
+            const slash = prefix.lastIndexOf("/");
+            const start = slash < 0 ? objects : join(objects, ...prefix.slice(0, slash).split("/"));
+            const found = [];
+            const walk = async (directory) => {
+                let entries;
+                try {
+                    entries = await readdir(directory, { withFileTypes: true });
+                }
+                catch (error) {
+                    if (isMissing(error))
+                        return;
+                    throw error;
+                }
+                for (const entry of entries) {
+                    const path = join(directory, entry.name);
+                    if (entry.isDirectory())
+                        await walk(path);
+                    else if (entry.isFile()) {
+                        const key = relative(objects, path).split(sep).join("/");
+                        if (!key.startsWith(prefix))
+                            continue;
+                        const stats = await stat(path).catch(() => undefined);
+                        if (stats)
+                            found.push({ key, size: stats.size, lastModified: stats.mtime });
+                    }
+                }
+            };
+            await walk(start);
+            found.sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+            yield* found;
+        },
+    };
+}
+async function writeTmp(path, text) {
+    const file = await open(path, "wx", 0o600);
+    try {
+        await file.writeFile(text, "utf8");
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/blob/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `BlobStore` seam (`./types.ts`) and its adapters. A Host with an Object store
+ * (`StackConfig.objectStore`, from `NYLORUN_OBJECT_STORE_*`) passes an `s3` store to its Tenant
+ * (`TenantOpenHooks.blobs`); without one the Tenant keeps blobs on disk (`fs`, under
+ * `TenantPaths.blobs`). Tenant code reaches it as `TenantContext.blobs`.
+ */
+export * from "./types.js";
+export { createFsBlobStore, type FsBlobStoreOptions } from "./fs.js";
+export { createS3BlobStore, type S3BlobStore, type S3BlobStoreOptions } from "./s3.js";

package/dist/blob/index.js

@@ -0,0 +1,9 @@
+/**
+ * The `BlobStore` seam (`./types.ts`) and its adapters. A Host with an Object store
+ * (`StackConfig.objectStore`, from `NYLORUN_OBJECT_STORE_*`) passes an `s3` store to its Tenant
+ * (`TenantOpenHooks.blobs`); without one the Tenant keeps blobs on disk (`fs`, under
+ * `TenantPaths.blobs`). Tenant code reaches it as `TenantContext.blobs`.
+ */
+export * from "./types.js";
+export { createFsBlobStore } from "./fs.js";
+export { createS3BlobStore } from "./s3.js";

package/dist/blob/s3.d.ts

@@ -0,0 +1,42 @@
+import { type BlobStore } from "./types.js";
+export interface S3BlobStoreOptions {
+    /** The S3 endpoint, e.g. `http://rustfs:9000` or `https://s3.eu-west-1.amazonaws.com`. */
+    endpoint: string;
+    bucket: string;
+    /** The signing region. Default `us-east-1`, which RustFS accepts. */
+    region?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /**
+     * Path-style URLs (`<endpoint>/<bucket>/<key>`), which RustFS and most S3 servers expect.
+     * `false` uses virtual-hosted URLs (`<bucket>.<endpoint host>/<key>`). Default `true`.
+     */
+    forcePathStyle?: boolean;
+    /**
+     * A body longer than this is uploaded in parts of about this size (multipart upload); a
+     * shorter one in one request. At least 5 MiB, the S3 minimum. Default 8 MiB.
+     */
+    partSize?: number;
+    /** Attempts for a request that fails with a network error, 429 or 5xx. Default 3. */
+    attempts?: number;
+    /** Replaces the global `fetch` (tests). */
+    fetch?: typeof fetch;
+}
+/** The `s3` adapter, plus the one bucket operation the Runtime needs at boot. */
+export interface S3BlobStore extends BlobStore {
+    readonly kind: "s3";
+    /** Create the bucket unless it exists. The local stack's runtime calls it at boot. */
+    ensureBucket(): Promise<void>;
+}
+/**
+ * The `s3` adapter over the plain S3 API: PutObject, multipart upload, GetObject with Range,
+ * HeadObject, DeleteObject and ListObjectsV2, signed with SigV4 by aws4fetch (MIT, no
+ * dependencies, built on `fetch` and web streams). It uses no server's admin, KMS or lifecycle
+ * API (D35), so RustFS, S3, R2 or any S3 server sits behind it.
+ *
+ * Uploads stream: the body is counted and hashed as it arrives and sent in parts of
+ * `partSize`, so memory stays at about one part whatever the size, and a body that passes
+ * `maxBytes` aborts its multipart upload. Each request carries the SHA-256 of its payload,
+ * which the server checks. Downloads hand back the response's stream.
+ */
+export declare function createS3BlobStore(options: S3BlobStoreOptions): S3BlobStore;