@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/api/http/routes/sandboxes.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { isSandboxId, PutSandboxRequestSchema } from "@nylorun/core/contracts";
+import { DeleteSandboxResponse, ListSandboxEventsResponse, ListSandboxesResponse, PutSandboxRequest, SandboxView, } from "../../components.js";
+import { fail } from "../../../tenant/http.js";
+import { deleteSandbox, getSandbox, listSandboxes, putSandbox, resetSandbox, sandboxEventsOf, stopSandbox, } from "../../../tenant/sandboxes.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+/** Reading a sandbox: any caller that may use sessions, or change sandboxes. */
+const READ = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sessions:own", "sandboxes:write"],
+    browser: true,
+};
+/** Creating or deleting one. */
+const WRITE = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sandboxes:write"],
+    browser: true,
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const sandboxId = z.object({
+    sandboxId: z
+        .string()
+        .meta({ description: "The sandbox id, percent-encoded: `team-a%2Fproj-42` for `team-a/proj-42`" }),
+});
+/** The path's sandbox id, or a 400 naming the rule. */
+function idOf(value) {
+    if (!isSandboxId(value))
+        return fail(400, "A sandbox id is up to 200 characters: /-separated segments of letters, digits, '.', '_' and '-'");
+    return value;
+}
+/** `label=k=v`, repeated: every one must match. */
+function labelsOf(values) {
+    const labels = {};
+    for (const value of values ?? []) {
+        const at = value.indexOf("=");
+        if (at <= 0)
+            fail(400, `label must be key=value, not ${value}`);
+        labels[value.slice(0, at)] = value.slice(at + 1);
+    }
+    return labels;
+}
+export function sandboxRoutes(api) {
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/sandboxes",
+        tags: ["Sandboxes"],
+        summary: "List sandboxes",
+        description: "Every sandbox with all the labels asked for. A subject token sees only the sandboxes its grants reach.",
+        request: {
+            query: z.object({
+                label: z
+                    .union([z.string(), z.array(z.string())])
+                    .optional()
+                    .meta({ description: "`key=value`; repeat it to require several labels" }),
+            }),
+        },
+        responses: { 200: json(ListSandboxesResponse, "The sandboxes") },
+    }, async (c) => jsonResponse(200, await listSandboxes(c.env.tenant, labelsOf(c.req.queries("label")), c.get("scope"))));
+    tenantRoute(api, WRITE, {
+        method: "put",
+        path: "/v1/sandboxes/{sandboxId}",
+        tags: ["Sandboxes"],
+        summary: "Create or find a sandbox",
+        description: "Creates the sandbox within the Tenant's limits, or answers the one with this id, so get-or-create is one call. Its spec is fixed once it exists; labels, when sent, replace its labels. Kind `pod` needs sandbox pods (`nylorun sandbox enable`): it is created at once, and a PUT on an existing pod sandbox starts it again when it was stopped, or revives it with a longer `lifecycle.ttl`.",
+        request: {
+            params: sandboxId,
+            body: { required: true, content: { "application/json": { schema: PutSandboxRequest } } },
+        },
+        responses: {
+            200: json(SandboxView, "The sandbox"),
+            409: {
+                description: "A sandbox with this id has another spec, the Tenant holds as many sandboxes as it allows (`limit_exceeded`), kind pod without sandbox pods (`sandbox_unavailable`), or a lost pod sandbox (`sandbox_lost`)",
+            },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("sandboxId"));
+        const body = PutSandboxRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await putSandbox(c.env.tenant, id, body, c.get("scope")));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/sandboxes/{sandboxId}",
+        tags: ["Sandboxes"],
+        summary: "Get a sandbox",
+        description: "Its spec, labels, state and the sessions attached to it (acting for a person, only theirs).",
+        request: { params: sandboxId },
+        responses: { 200: json(SandboxView, "The sandbox") },
+    }, async (c) => jsonResponse(200, await getSandbox(c.env.tenant, idOf(c.req.param("sandboxId")), c.get("scope"))));
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/sandboxes/{sandboxId}/events",
+        tags: ["Sandboxes"],
+        summary: "Read a sandbox's lifecycle events",
+        description: "`sandbox.created`, `sandbox.attached`, `sandbox.detached` and `sandbox.deleted`, in order, numbered from 0.",
+        request: {
+            params: sandboxId,
+            query: z.object({
+                from: z.string().optional().meta({ description: "The first `seq` to return" }),
+            }),
+        },
+        responses: { 200: json(ListSandboxEventsResponse, "The events") },
+    }, async (c) => {
+        const from = c.req.query("from");
+        if (from !== undefined && !/^\d+$/.test(from))
+            fail(400, "from must be a seq");
+        return jsonResponse(200, await sandboxEventsOf(c.env.tenant, idOf(c.req.param("sandboxId")), c.get("scope"), from === undefined ? undefined : Number(from)));
+    });
+    tenantRoute(api, WRITE, {
+        method: "delete",
+        path: "/v1/sandboxes/{sandboxId}",
+        tags: ["Sandboxes"],
+        summary: "Delete a sandbox",
+        description: "Deletes the sandbox and its files. Sessions attached to it stay attached by id; their next turn is refused until a sandbox with this id exists again.",
+        request: { params: sandboxId },
+        responses: {
+            200: json(DeleteSandboxResponse, "Deleted, or there was none"),
+            409: { description: "A session attached to it has a turn running (`sandbox_busy`)" },
+        },
+    }, async (c) => jsonResponse(200, await deleteSandbox(c.env.tenant, idOf(c.req.param("sandboxId")), c.get("scope"))));
+    for (const [action, summary, description, run] of [
+        [
+            "stop",
+            "Stop a pod sandbox",
+            "Suspends the pod: its volume is kept, and the next turn of a session attached to it (or a PUT) starts it again. Refused during a turn (`sandbox_busy`).",
+            stopSandbox,
+        ],
+        [
+            "reset",
+            "Reset a pod sandbox",
+            "A new pod on a new, empty volume; the old pod and volume are deleted. The way out of `sandbox_lost`. Refused during a turn (`sandbox_busy`).",
+            resetSandbox,
+        ],
+    ])
+        tenantRoute(api, WRITE, {
+            method: "post",
+            path: `/v1/sandboxes/{sandboxId}/${action}`,
+            tags: ["Sandboxes"],
+            summary,
+            description,
+            request: { params: sandboxId },
+            responses: {
+                200: json(SandboxView, "The sandbox"),
+                400: { description: "The sandbox is virtual" },
+                409: { description: "A turn holds it (`sandbox_busy`), or no sandbox pods (`sandbox_unavailable`)" },
+            },
+        }, async (c) => jsonResponse(200, await run(c.env.tenant, idOf(c.req.param("sandboxId")), c.get("scope"))));
+}

package/dist/api/http/routes/sessions.js

@@ -7,6 +7,7 @@ import { sandboxRouteDeps } from "../../../tenant/actions.js";
 import { accessOf, requireApplication } from "../../../tenant/auth.js";
 import { loadSession, sessionOf } from "../../../tenant/context.js";
 import { fail } from "../../../tenant/http.js";
+import { sandboxGrantsOf } from "../../../tenant/sandboxes.js";
 import { readHistory, requestCursor, streamSessionEvents } from "../../../tenant/session-streams.js";
 import { listAgentsPublic, listDefinitions, listSessions, putDefinition, putSession, sessionView, } from "../../../tenant/sessions.js";
 import { readJson } from "../body.js";
@@ -107,7 +108,8 @@ export function sessionRoutes(api) {
         // Agent code may trust `info`: only an app server sets it.
         if (scope.kind === "token" && request.info !== undefined)
             fail(403, "A subject token cannot set session info", { code: "scope_required" });
-        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope));
+        const grants = sandboxGrantsOf(scope);
+        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope), grants === undefined ? {} : { sandboxGrants: grants });
         return jsonResponse(200, await ctx.store.tx((t) => sessionView(t, session)));
     });
     tenantRoute(api, OWN_SESSIONS, {

package/dist/api/http/routes/tenant.js

@@ -10,11 +10,12 @@ import { clearObservers } from "../../../tenant/session-streams.js";
 import { usesFixtureModel } from "../../../tenant/model-setting.js";
 import { resetTenant } from "../../../tenant/reset.js";
 import { clearWork, drain } from "../../../tenant/scheduler.js";
-import { buildTenantStatus, seedTenantConfig } from "../../../tenant/status.js";
+import { buildTenantStatus, harnessStatusOf, seedTenantConfig } from "../../../tenant/status.js";
 import { tenantReset, streamsStatus, } from "../../../tenant/streams.js";
 import { readJson } from "../body.js";
 import { pathSegments, tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
+import { rearmPodTimers } from "../../../tenant/sandboxes.js";
 const settings = (scopes) => ({
     credentials: scopes === "never" ? ["application"] : ["application", "subject"],
     scopes,
@@ -46,7 +47,36 @@ const budgetView = (row) => ({
 /** `GET /v1/tenant/sandbox`: the backend report and the configuration with defaults applied. */
 async function sandboxView(ctx) {
     const config = await ctx.store.tx((t) => readSandboxConfig(t));
-    return { ...(await ctx.sandbox.report()), config: effectiveSandboxConfig(config) };
+    return {
+        ...(await ctx.sandbox.report()),
+        config: effectiveSandboxConfig(config),
+        cluster: await clusterOf(ctx),
+    };
+}
+/** The Tenant's cluster for pod sandboxes (F7.2), from the sandboxes service; null without one. */
+async function clusterOf(ctx) {
+    if (!ctx.pods)
+        return null;
+    try {
+        const [info, ready] = await Promise.all([ctx.pods.client.info(), ctx.pods.client.ready()]);
+        return {
+            namespace: info.namespace,
+            context: info.context,
+            ready,
+            ...(info.controllerVersion ? { controllerVersion: info.controllerVersion } : {}),
+            ...(info.networkPolicy
+                ? {
+                    networkPolicy: {
+                        enforced: info.networkPolicy.enforced === true,
+                        ...(info.networkPolicy.probedAt ? { probedAt: info.networkPolicy.probedAt } : {}),
+                    },
+                }
+                : {}),
+        };
+    }
+    catch {
+        return null;
+    }
 }
 export function tenantRoutes(api) {
     tenantRoute(api, SETTINGS, {
@@ -70,6 +100,7 @@ export function tenantRoutes(api) {
                 (await vault.getHostModel()).configured,
             ...(ctx.stuckInvocations ? { stuckInvocations: ctx.stuckInvocations } : {}),
             streamsStatus: () => streamsStatus(ctx),
+            harness: harnessStatusOf(ctx),
         }));
     });
     tenantRoute(api, settings("never"), {
@@ -91,6 +122,7 @@ export function tenantRoutes(api) {
             store: ctx.store,
             sandbox: ctx.sandbox,
             paths: ctx.config.paths,
+            blobs: ctx.blobs,
             clearSessionState: () => {
                 clearWork(ctx);
                 clearObservers(ctx.sessionStreams);
@@ -147,6 +179,8 @@ export function tenantRoutes(api) {
         if (errors.length > 0)
             fail(400, errors.join(" "));
         await ctx.store.tx((t) => writeSandboxConfig(t, config));
+        // Pods' idle timers follow the new limits.idle (D36).
+        await rearmPodTimers(ctx);
         return jsonResponse(200, await sandboxView(ctx));
     });
     tenantRoute(api, SETTINGS, {

package/dist/artifacts/config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A Tenant's artifact configuration, stored as Tenant setting `artifacts.config`: the largest
+ * file one upload may store and the most bytes every artifact version together may hold.
+ * Unset limits take the defaults (100 MiB and 10 GiB).
+ */
+import { type TenantArtifactsConfig } from "@nylorun/core/contracts";
+export declare const ARTIFACTS_CONFIG_SETTING = "artifacts.config";
+export interface ArtifactLimits {
+    readonly fileBytes: number;
+    readonly totalBytes: number;
+}
+interface SettingsReader {
+    getSetting(key: string): Promise<string | undefined>;
+}
+interface SettingsWriter extends SettingsReader {
+    putSetting(key: string, value: string): Promise<void>;
+}
+/** The limits in force: the Tenant's, with the defaults for what it leaves unset. */
+export declare function effectiveArtifactLimits(config: TenantArtifactsConfig): ArtifactLimits;
+export declare function readArtifactsConfig(t: SettingsReader): Promise<TenantArtifactsConfig>;
+export declare function readArtifactLimits(t: SettingsReader): Promise<ArtifactLimits>;
+export declare function writeArtifactsConfig(t: SettingsWriter, config: TenantArtifactsConfig): Promise<void>;
+export {};

package/dist/artifacts/config.js

@@ -0,0 +1,27 @@
+/**
+ * A Tenant's artifact configuration, stored as Tenant setting `artifacts.config`: the largest
+ * file one upload may store and the most bytes every artifact version together may hold.
+ * Unset limits take the defaults (100 MiB and 10 GiB).
+ */
+import { ARTIFACT_FILE_BYTES_DEFAULT, ARTIFACT_TOTAL_BYTES_DEFAULT, TenantArtifactsConfigSchema, } from "@nylorun/core/contracts";
+export const ARTIFACTS_CONFIG_SETTING = "artifacts.config";
+/** The limits in force: the Tenant's, with the defaults for what it leaves unset. */
+export function effectiveArtifactLimits(config) {
+    return {
+        fileBytes: config.limits?.fileBytes ?? ARTIFACT_FILE_BYTES_DEFAULT,
+        totalBytes: config.limits?.totalBytes ?? ARTIFACT_TOTAL_BYTES_DEFAULT,
+    };
+}
+export async function readArtifactsConfig(t) {
+    const raw = await t.getSetting(ARTIFACTS_CONFIG_SETTING);
+    if (raw === undefined)
+        return {};
+    const parsed = TenantArtifactsConfigSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : {};
+}
+export async function readArtifactLimits(t) {
+    return effectiveArtifactLimits(await readArtifactsConfig(t));
+}
+export async function writeArtifactsConfig(t, config) {
+    await t.putSetting(ARTIFACTS_CONFIG_SETTING, JSON.stringify(TenantArtifactsConfigSchema.parse(config)));
+}

package/dist/artifacts/export.d.ts

@@ -0,0 +1,8 @@
+import { type TenantContext } from "../tenant/context.js";
+/** The directory every sandbox's outputs are exported from. */
+export declare const OUTPUTS_DIR = "/workspace/outputs";
+/**
+ * Exports the outputs of turn `turnId` of session `sessionId`, if it completed and its sandbox
+ * has any. Never throws.
+ */
+export declare function exportOutputs(ctx: TenantContext, sessionId: string, turnId: string | null, signal: AbortSignal): Promise<void>;

package/dist/artifacts/export.js

@@ -0,0 +1,205 @@
+/**
+ * The turn-end export (F8.2): when an agent's turn completes, core reads `/workspace/outputs` of
+ * the session's sandbox through the `WorkspaceReader` seam and keeps it as a version of the
+ * session's folder artifact `outputs` (the first export creates it; later turns add versions,
+ * and a turn whose outputs did not change adds none).
+ *
+ * - **After the turn.** The advance calls `exportOutputs` once `settle` has committed the turn,
+ *   outside its transaction and while it still holds the session's lease, so the next turn
+ *   cannot change the workspace under it. Nothing here fails the turn: a sandbox or store
+ *   failure is logged and recorded as `artifact.export.failed`.
+ * - **Claimed.** The listing and the bytes are what the holder of the workspace supplied: the
+ *   version's source is `export` and its event says `claimed: true`.
+ * - **Bounded.** At most `EXPORT_MAX_FILES` files and `EXPORT_MAX_BYTES` bytes per export, each
+ *   file within the Tenant's per-file limit, and the new bytes within its total; past any of
+ *   them nothing is stored and `artifact.export.skipped` says why.
+ * - **Deduplicated.** Each file is stored content-addressed (`folders.ts`); a file the store
+ *   already holds is not stored again.
+ *
+ * No sandbox, a sandbox never created, or an empty or missing `/workspace/outputs` exports
+ * nothing and records nothing. The package's declared outputs are left for later: the manifest
+ * has no `outputs` field yet.
+ */
+import { posix } from "node:path";
+import { EXPORT_MAX_BYTES, EXPORT_MAX_FILES, OUTPUTS_ARTIFACT_NAME, } from "@nylorun/core/contracts";
+import { SANDBOX_WORKSPACE } from "@nylorun/core/define";
+import { isWorkflowManifest } from "../core/flow-host.js";
+import { sandboxWorkspaceOf } from "../sandbox/share.js";
+import { SandboxFileTooLargeError } from "../sandbox/types.js";
+import { sandboxLookup } from "../tenant/context.js";
+import { readArtifactLimits } from "./config.js";
+import { collectContent, commitFolderVersion, contentEpoch, contentKey, encodeManifest, FolderCommitRefused, sha256Hex, } from "./folders.js";
+import { contentTypeFor } from "./media-types.js";
+/** The directory every sandbox's outputs are exported from. */
+export const OUTPUTS_DIR = `${SANDBOX_WORKSPACE}/outputs`;
+/** Stops the export with `artifact.export.skipped`. */
+class Skip extends Error {
+    reason;
+    limit;
+    path;
+    constructor(reason, message, limit, path) {
+        super(message);
+        this.reason = reason;
+        this.limit = limit;
+        this.path = path;
+    }
+}
+/**
+ * Exports the outputs of turn `turnId` of session `sessionId`, if it completed and its sandbox
+ * has any. Never throws.
+ */
+export async function exportOutputs(ctx, sessionId, turnId, signal) {
+    try {
+        await runExport(ctx, sessionId, turnId, signal);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (signal.aborted) {
+            ctx.config.logger.info("outputs export stopped", { sessionId, message });
+            return;
+        }
+        const skip = error instanceof Skip
+            ? error
+            : error instanceof FolderCommitRefused && error.reason === "tenant_total"
+                ? new Skip("tenant_total", error.message, error.limit)
+                : undefined;
+        if (!skip)
+            ctx.config.logger.warn("outputs export failed", { sessionId, message });
+        try {
+            await ctx.store.tx(async (t) => {
+                if (skip)
+                    await t.event(sessionId, turnId, "artifact.export.skipped", {
+                        name: OUTPUTS_ARTIFACT_NAME,
+                        reason: skip.reason,
+                        message: skip.message,
+                        ...(skip.limit === undefined ? {} : { limit: skip.limit }),
+                        ...(skip.path === undefined ? {} : { path: skip.path }),
+                    });
+                else
+                    await t.event(sessionId, turnId, "artifact.export.failed", {
+                        name: OUTPUTS_ARTIFACT_NAME,
+                        message,
+                    });
+            });
+        }
+        catch {
+            /* the session is gone (reset) or the store closed */
+        }
+    }
+}
+async function runExport(ctx, sessionId, turnId, signal) {
+    const found = await ctx.store.tx(async (t) => {
+        const s = await t.get("sessions", sessionId);
+        // Only a turn that completed, and only an agent's (a flow agent's sandbox is its agents').
+        if (!s || s.status !== "completed" || s.lastTurnId !== turnId || isWorkflowManifest(s.manifest))
+            return undefined;
+        const workspace = sandboxWorkspaceOf(s, await sandboxLookup(t, s.id));
+        const prior = (await t.listArtifacts({ sessionId })).find((row) => row.kind === "folder" && row.name === OUTPUTS_ARTIFACT_NAME);
+        const latest = prior ? await t.artifactVersion(prior.id, prior.latestVersion) : undefined;
+        return {
+            session: {
+                sessionId,
+                turnId,
+                ownerId: workspace.ownerId,
+                ...(workspace.sandboxId === undefined ? {} : { sandboxId: workspace.sandboxId }),
+                manifest: s.manifest,
+            },
+            limits: await readArtifactLimits(t),
+            priorId: prior?.id,
+            latestSha: latest?.sha256,
+            epoch: await contentEpoch(t),
+        };
+    });
+    if (!found)
+        return;
+    const { session, limits } = found;
+    const listing = await ctx.workspaces.list(session, OUTPUTS_DIR, {
+        maxEntries: EXPORT_MAX_FILES,
+        signal,
+    });
+    if (!listing || listing.entries.length === 0)
+        return;
+    if (listing.truncated)
+        throw new Skip("too_many_files", `${OUTPUTS_DIR} holds more than ${EXPORT_MAX_FILES} files`, EXPORT_MAX_FILES);
+    const large = listing.entries.find((entry) => entry.size > limits.fileBytes);
+    if (large)
+        throw tooLargeFile(large.path, large.size, limits.fileBytes);
+    const maxBytes = Math.min(EXPORT_MAX_BYTES, limits.totalBytes);
+    const listed = listing.entries.reduce((sum, entry) => sum + entry.size, 0);
+    if (listed > maxBytes)
+        throw tooLarge(listed, maxBytes);
+    // The files this export stored: removed again if it commits nothing, unless another version
+    // names them by then.
+    const put = [];
+    try {
+        await storeAndCommit(ctx, found, listing.entries, maxBytes, put, signal);
+    }
+    catch (error) {
+        if (put.length > 0)
+            await ctx.store
+                .tx(async (t) => {
+                await t.lockArtifactQuota();
+                await collectContent(ctx.blobs, t, put);
+            })
+                .catch(() => undefined);
+        throw error;
+    }
+}
+async function storeAndCommit(ctx, found, listed, maxBytes, put, signal) {
+    const { session, limits } = found;
+    const { sessionId, turnId } = session;
+    const entries = [];
+    const stored = new Set();
+    let read = 0;
+    for (const entry of listed) {
+        let bytes;
+        try {
+            bytes = await ctx.workspaces.readBytes(session, posix.join(OUTPUTS_DIR, entry.path), {
+                maxBytes: limits.fileBytes,
+                signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof SandboxFileTooLargeError)
+                throw tooLargeFile(entry.path, error.size, limits.fileBytes);
+            throw error;
+        }
+        // Gone since the listing: the folder is what is there now.
+        if (bytes === undefined)
+            continue;
+        read += bytes.length;
+        if (read > maxBytes)
+            throw tooLarge(read, maxBytes);
+        const sha256 = sha256Hex(bytes);
+        const contentType = contentTypeFor(posix.basename(entry.path));
+        if (!stored.has(sha256)) {
+            stored.add(sha256);
+            const key = contentKey(sha256);
+            if (!(await ctx.blobs.head(key))) {
+                put.push(sha256);
+                await ctx.blobs.put(key, bytes, { contentType, signal });
+            }
+        }
+        entries.push({ path: entry.path, size: bytes.length, sha256, contentType });
+    }
+    // Every file vanished, or nothing changed since the last export: no new version.
+    if (entries.length === 0)
+        return;
+    if (found.latestSha !== undefined && sha256Hex(encodeManifest(entries)) === found.latestSha)
+        return;
+    await commitFolderVersion(ctx, {
+        sessionId,
+        turnId,
+        ...(found.priorId === undefined ? {} : { artifactId: found.priorId }),
+        name: OUTPUTS_ARTIFACT_NAME,
+        entries,
+        epoch: found.epoch,
+        totalBytes: limits.totalBytes,
+    });
+}
+function tooLargeFile(path, size, limit) {
+    return new Skip("file_too_large", `${OUTPUTS_DIR}/${path} is ${size} bytes; a file may hold at most ${limit}`, limit, path);
+}
+function tooLarge(bytes, limit) {
+    return new Skip("too_large", `${OUTPUTS_DIR} holds ${bytes} bytes; an export stores at most ${limit}`, limit);
+}

package/dist/artifacts/files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How model-gate reads the files a prompt names (protocol 6): a media part's reference is an
+ * artifact version (`./parts.ts`), resolved here to its bytes from the Object store. The gate
+ * holds the store credential; the loop and the transcript only ever hold the reference.
+ *
+ * It replaces `MediaStore`: images are file artifacts, and their bytes reach the provider only in
+ * the request model-gate builds.
+ */
+import type { JsonValue } from "@nylorun/core/define";
+import type { BlobStore } from "../blob/index.js";
+import type { SessionStore } from "../store/types.js";
+/** A file a prompt names, with its bytes. */
+export interface ResolvedFile {
+    readonly name: string;
+    /** The version's media type, as stored. */
+    readonly mediaType: string;
+    readonly bytes: Uint8Array;
+}
+/** Why a file cannot go to the model: the message is the outcome's, so it names no secret. */
+export declare class FileUnavailableError extends Error {
+    constructor(message: string);
+}
+/** Resolves a media part's reference to the file's bytes, or throws `FileUnavailableError`. */
+export type FileResolver = (reference: JsonValue) => Promise<ResolvedFile>;
+/**
+ * Files from the Tenant's artifacts: `store` for the version's row, `blobs` for its bytes, for
+ * the call of session `sessionId`. An artifact of another session is refused (a Tenant-wide one
+ * is not), and without a session every file is: the check is never skipped.
+ */
+export declare function artifactFiles(options: {
+    readonly store: SessionStore;
+    readonly blobs: BlobStore;
+    /** The session the call is for: the run token's, over HTTP. */
+    readonly sessionId: string | undefined;
+    readonly maxBytes?: number;
+}): FileResolver;

package/dist/artifacts/files.js

@@ -0,0 +1,45 @@
+import { MODEL_FILE_MAX_BYTES } from "./media-types.js";
+import { fileReferenceOf } from "./parts.js";
+/** Why a file cannot go to the model: the message is the outcome's, so it names no secret. */
+export class FileUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FileUnavailableError";
+    }
+}
+/**
+ * Files from the Tenant's artifacts: `store` for the version's row, `blobs` for its bytes, for
+ * the call of session `sessionId`. An artifact of another session is refused (a Tenant-wide one
+ * is not), and without a session every file is: the check is never skipped.
+ */
+export function artifactFiles(options) {
+    const maxBytes = options.maxBytes ?? MODEL_FILE_MAX_BYTES;
+    return async (value) => {
+        const reference = fileReferenceOf(value);
+        if (!reference)
+            throw new FileUnavailableError("Expected an artifact reference.");
+        const sessionId = options.sessionId;
+        if (typeof sessionId !== "string" || sessionId === "")
+            throw new FileUnavailableError("A model call reads files only for its own session.");
+        const found = await options.store.tx(async (t) => {
+            const artifact = await t.artifact(reference.artifactId);
+            if (!artifact)
+                return undefined;
+            const version = await t.artifactVersion(artifact.id, reference.version);
+            return version ? { artifact, version } : undefined;
+        });
+        if (!found ||
+            (found.artifact.sessionId !== null && found.artifact.sessionId !== sessionId))
+            throw new FileUnavailableError(`Artifact ${reference.artifactId} version ${reference.version} is not available.`);
+        const { artifact, version } = found;
+        if (artifact.kind !== "file")
+            throw new FileUnavailableError(`${artifact.name} is a folder; a model reads files only.`);
+        if (version.size > maxBytes)
+            throw new FileUnavailableError(`${artifact.name} is ${version.size} bytes; a model reads files of at most ${maxBytes} bytes.`);
+        const got = await options.blobs.get(version.blobKey);
+        if (!got)
+            throw new FileUnavailableError(`The bytes of ${artifact.name} are missing from the Object store.`);
+        const bytes = new Uint8Array(await new Response(got.body).arrayBuffer());
+        return { name: artifact.name, mediaType: version.contentType, bytes };
+    };
+}

package/dist/artifacts/folders.d.ts

@@ -0,0 +1,60 @@
+import type { ArtifactDiff, FolderEntry, FolderManifest } from "@nylorun/core/contracts";
+import type { BlobStore } from "../blob/index.js";
+import type { ArtifactRow, ArtifactVersionRow, Tx } from "../store/types.js";
+import { type TenantContext } from "../tenant/context.js";
+/** Where a folder file's bytes are: content-addressed by their SHA-256. */
+export declare function contentKey(sha256: string): string;
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Entries in manifest order: by path, comparing UTF-16 code units. */
+export declare function sortEntries(entries: readonly FolderEntry[]): FolderEntry[];
+/** The manifest's bytes, as stored: deterministic for the same entries. */
+export declare function encodeManifest(entries: readonly FolderEntry[]): Uint8Array;
+/** A folder version's manifest, read from the Object store. */
+export declare function readManifest(blobs: BlobStore, version: ArtifactVersionRow): Promise<FolderManifest>;
+/** The entry at `path`, or the 404 of a missing file. */
+export declare function entryAt(manifest: FolderManifest, path: string): FolderEntry;
+/** What changed from `from` (absent: nothing) to `to`. */
+export declare function diffManifests(artifactId: string, from: {
+    version: number;
+    manifest: FolderManifest;
+} | undefined, to: {
+    version: number;
+    manifest: FolderManifest;
+}): ArtifactDiff;
+/** The Tenant's content epoch: moves whenever content-addressed files are deleted. */
+export declare function contentEpoch(t: Tx): Promise<number>;
+/**
+ * Deletes those of `shas` no committed folder version references any more, and moves the content
+ * epoch when it deletes any. Call it in a transaction holding the quota lock, after the rows that
+ * named them are gone: the deletes happen before the transaction commits, under the lock.
+ */
+export declare function collectContent(blobs: BlobStore, t: Tx, shas: readonly string[]): Promise<number>;
+/** The commit could not go ahead: a limit, or content removed while the export ran. */
+export declare class FolderCommitRefused extends Error {
+    readonly reason: "tenant_total" | "content_gone" | "artifact_gone";
+    readonly limit?: number | undefined;
+    constructor(message: string, reason: "tenant_total" | "content_gone" | "artifact_gone", limit?: number | undefined);
+}
+export interface FolderVersionInput {
+    readonly sessionId: string;
+    readonly turnId: string | null;
+    /** A new version of this folder of the session; otherwise a new folder named `name`. */
+    readonly artifactId?: string;
+    readonly name: string;
+    /** Every file, each one's bytes already at `contentKey(sha256)`. */
+    readonly entries: readonly FolderEntry[];
+    /** The content epoch read before the first `head` of those bytes. */
+    readonly epoch: number;
+    /** The Tenant total in force. */
+    readonly totalBytes: number;
+}
+/**
+ * Commits a folder version whose files are already stored: its manifest to the Object store,
+ * then, in one transaction under the session and quota locks, the version row, its content rows
+ * and `artifact.created` or `artifact.version.created` (`claimed: true`, source `export`).
+ * Throws `FolderCommitRefused` when the Tenant total would be passed or a file is gone.
+ */
+export declare function commitFolderVersion(ctx: TenantContext, input: FolderVersionInput): Promise<{
+    artifact: ArtifactRow;
+    version: ArtifactVersionRow;
+}>;