@nylorun/runtime 0.24.0-beta → 0.25.0-beta

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

@@ -1,14 +1,15 @@
 import { z } from "zod";
-import { ModelUsageQuerySchema, PutModelBudgetsRequestSchema, PutToolPolicyRequestSchema, PutHostModelRequestSchema, PutTenantEnvironmentsRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
-import { HostModelCatalog, HostModelView, ListProvidersResponse, ModelBudgets, ModelUsageTotals, PutModelBudgetsRequest, PutToolPolicyRequest, ToolPolicy, PutHostModelRequest, PutTenantEnvironmentsRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
+import { ModelUsageQuerySchema, PutModelBudgetsRequestSchema, PutToolPolicyRequestSchema, PutModelInputsRequestSchema, PutHostModelRequestSchema, PutTenantEnvironmentsRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
+import { HostModelCatalog, HostModelView, ListProvidersResponse, ModelBudgets, ModelInputsView, ModelUsageTotals, PutModelBudgetsRequest, PutToolPolicyRequest, PutModelInputsRequest, ToolPolicy, PutHostModelRequest, PutTenantEnvironmentsRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
 import { periodStart } from "../../../gates/meter.js";
 import { readToolPolicy, TOOL_POLICY_SETTING } from "../../../gates/policy.js";
-import { hostModelCatalog } from "../../../model/catalog.js";
+import { addableInputs, capabilitiesOf, inputsError } from "../../../model/capabilities.js";
+import { catalogModel, hostModelCatalog } from "../../../model/catalog.js";
 import { sandboxConfigErrors } from "../../../sandbox/resolve.js";
 import { effectiveSandboxConfig, readSandboxConfig, writeSandboxConfig, } from "../../../sandbox/tenant-config.js";
 import { fail } from "../../../tenant/http.js";
 import { clearObservers } from "../../../tenant/session-streams.js";
-import { usesFixtureModel } from "../../../tenant/model-setting.js";
+import { readAddedInputs, usesFixtureModel, writeAddedInputs } from "../../../tenant/model-setting.js";
 import { resetTenant } from "../../../tenant/reset.js";
 import { clearWork, drain } from "../../../tenant/scheduler.js";
 import { buildTenantStatus, harnessStatusOf, seedTenantConfig } from "../../../tenant/status.js";
@@ -150,10 +151,37 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/models",
         tags: ["Tenant"],
         summary: "List model providers and models",
-        responses: { 200: json(HostModelCatalog, "Provider and model names") },
+        description: "Each model says what it reads (`inputs`: its catalog's inputs and those the operator added) and what may be added (`addableInputs`).",
+        responses: { 200: json(HostModelCatalog, "Provider and model names, and their inputs") },
     }, async (c) => {
-        c.env.tenant;
-        return jsonResponse(200, hostModelCatalog());
+        const added = await c.env.tenant.store.tx((t) => readAddedInputs(t));
+        return jsonResponse(200, hostModelCatalog(added));
+    });
+    tenantRoute(api, MANAGEMENT, {
+        method: "put",
+        path: "/v1/tenant/models/inputs",
+        tags: ["Tenant"],
+        summary: "Set what a catalog model reads",
+        description: "Replaces the inputs the operator added to one catalog model (Tenant setting `model.inputs`): only those in its `addableInputs`, which its provider API carries. Its catalog's own inputs always stay; an empty list removes the additions. A message naming a file the Tenant's model does not read is refused with `422 attachment_unsupported`. A custom endpoint sets `settings.inputs` on `PUT /v1/tenant/model` instead.",
+        request: { body: body(PutModelInputsRequest) },
+        responses: { 200: json(ModelInputsView, "What the model reads now") },
+    }, async (c) => {
+        const { provider, model, inputs } = PutModelInputsRequestSchema.parse(await readJson(c.req.raw));
+        if (provider === "custom")
+            fail(400, "A custom endpoint's inputs are its settings: set settings.inputs on PUT /v1/tenant/model.");
+        const found = catalogModel(provider, model);
+        if (!found)
+            fail(400, `Unknown model ${provider}/${model}.`);
+        const refused = inputsError(found, inputs);
+        if (refused)
+            fail(400, refused);
+        const added = inputs.filter((input) => addableInputs(found).includes(input));
+        await c.env.tenant.store.tx((t) => writeAddedInputs(t, `${provider}/${model}`, added));
+        return jsonResponse(200, {
+            provider,
+            model,
+            inputs: capabilitiesOf(found, added).inputs,
+        });
     });
     tenantRoute(api, MANAGEMENT, {
         method: "get",

package/dist/api/inbound-files.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Files that arrive inside a message (multimodal messages, M7): the AG-UI and A2A endpoints take
+ * a file's bytes inline (base64), store them as an artifact of the message's session, and send
+ * the message as `parts` through the session's normal command path, so every check a message
+ * with file parts meets applies. A file by URL is refused: the Runtime fetches nothing.
+ *
+ * A retried message (the same idempotency key) reuses the files the first one stored rather than
+ * storing them again, so it replays the first turn instead of conflicting with it. A message the
+ * Runtime refuses takes the files it stored with it (`discardFiles`).
+ */
+import type { MessagePart } from "@nylorun/core/contracts";
+import { type ArtifactAccess } from "../artifacts/service.js";
+import type { TenantContext } from "../tenant/context.js";
+/** The largest file a message may carry inline, decoded. */
+export declare const INLINE_FILE_MAX_BYTES: number;
+/**
+ * The request body of an endpoint that takes inline files: one file at the cap, base64-encoded
+ * (a third larger), and the rest of the request.
+ */
+export declare const INLINE_BODY_MAX_BYTES: number;
+/** A file sent inline: its name, declared media type and base64 bytes. */
+export interface InlineFile {
+    readonly name: string;
+    readonly mediaType: string;
+    /** The bytes, base64 (standard or URL-safe alphabet). */
+    readonly data: string;
+}
+/** One part of an inbound message: text, a file sent inline, or an artifact the Runtime holds. */
+export type InboundPart = {
+    readonly type: "text";
+    readonly text: string;
+} | ({
+    readonly type: "inline";
+} & InlineFile) | {
+    readonly type: "artifact";
+    readonly artifactId: string;
+};
+/** The 400 for a file sent by URL. */
+export declare function refuseUrl(): never;
+/** A name for a file its client did not name: its place in the message and its type's extension. */
+export declare function inlineFileName(mediaType: string, index: number): string;
+/**
+ * Stores `file` as a new artifact of `sessionId`, within the inline cap and the Tenant's
+ * artifact limits: `400` for bad base64 or a bad media type, `413 limit_exceeded` past a limit.
+ */
+export declare function storeInlineFile(ctx: TenantContext, sessionId: string, file: InlineFile, access: ArtifactAccess): Promise<{
+    artifactId: string;
+    version: number;
+}>;
+/**
+ * The parts of the message the session already took under `idempotencyKey`, when it took one
+ * with parts: a retry sends the same files again.
+ */
+export declare function priorParts(ctx: TenantContext, sessionId: string, idempotencyKey: string): Promise<readonly MessagePart[] | undefined>;
+/**
+ * A message's parts, its inline files stored as artifacts of `sessionId` (or, on a retry, the
+ * first message's files in their place, by position). `stored` lists the artifacts this call
+ * created, for `discardFiles` when the message is refused.
+ */
+export declare function messageParts(ctx: TenantContext, sessionId: string, idempotencyKey: string, inbound: readonly InboundPart[], access: ArtifactAccess): Promise<{
+    parts: MessagePart[];
+    stored: string[];
+}>;
+/** Deletes the artifacts a refused message stored; one already gone is no error. */
+export declare function discardFiles(ctx: TenantContext, artifactIds: readonly string[], access: ArtifactAccess): Promise<void>;

package/dist/api/inbound-files.js

@@ -0,0 +1,115 @@
+import { MAX_MESSAGE_PARTS } from "@nylorun/core/contracts";
+import { commandKey } from "../core/flow-host.js";
+import { extensionFor, normalizeContentType } from "../artifacts/media-types.js";
+import { deleteArtifact, uploadArtifact } from "../artifacts/service.js";
+import { fail } from "../tenant/http.js";
+/** The largest file a message may carry inline, decoded. */
+export const INLINE_FILE_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * The request body of an endpoint that takes inline files: one file at the cap, base64-encoded
+ * (a third larger), and the rest of the request.
+ */
+export const INLINE_BODY_MAX_BYTES = 28 * 1024 * 1024;
+const BASE64 = /^[A-Za-z0-9+/_-]*={0,2}$/;
+/** The 400 for a file sent by URL. */
+export function refuseUrl() {
+    return fail(400, "File URLs are not fetched yet; send the bytes inline", {
+        code: "invalid_request",
+    });
+}
+/** A name for a file its client did not name: its place in the message and its type's extension. */
+export function inlineFileName(mediaType, index) {
+    const extension = extensionFor(mediaType);
+    return `file-${index + 1}${extension ? `.${extension}` : ""}`;
+}
+/**
+ * Stores `file` as a new artifact of `sessionId`, within the inline cap and the Tenant's
+ * artifact limits: `400` for bad base64 or a bad media type, `413 limit_exceeded` past a limit.
+ */
+export async function storeInlineFile(ctx, sessionId, file, access) {
+    const data = file.data.replace(/\s+/gu, "");
+    if (!BASE64.test(data) || data.length % 4 === 1)
+        fail(400, `File "${file.name}" is not valid base64`, { code: "invalid_request" });
+    // Three bytes per four characters, before decoding a byte.
+    if (Math.floor((data.length * 3) / 4) > INLINE_FILE_MAX_BYTES + 2)
+        fail(413, `A file sent inline may hold at most ${INLINE_FILE_MAX_BYTES} bytes`, {
+            code: "limit_exceeded",
+            details: { limitBytes: INLINE_FILE_MAX_BYTES },
+        });
+    // Node's base64 decoder reads both alphabets.
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.byteLength > INLINE_FILE_MAX_BYTES)
+        fail(413, `A file sent inline may hold at most ${INLINE_FILE_MAX_BYTES} bytes`, {
+            code: "limit_exceeded",
+            details: { limitBytes: INLINE_FILE_MAX_BYTES },
+        });
+    if (bytes.byteLength === 0)
+        fail(400, `File "${file.name}" is empty`, { code: "invalid_request" });
+    const contentType = normalizeContentType(file.mediaType) ??
+        fail(400, `File "${file.name}" has no valid media type`, { code: "invalid_request" });
+    const { artifact, version } = await uploadArtifact(ctx, {
+        name: file.name,
+        contentType,
+        sessionId,
+        declaredBytes: bytes.byteLength,
+        source: "upload",
+    }, new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength), access);
+    return { artifactId: artifact.artifactId, version: version.version };
+}
+/**
+ * The parts of the message the session already took under `idempotencyKey`, when it took one
+ * with parts: a retry sends the same files again.
+ */
+export async function priorParts(ctx, sessionId, idempotencyKey) {
+    const prior = await ctx.store.tx((t) => t.get("commands", commandKey(sessionId, idempotencyKey)));
+    return prior?.command.type === "message" && Array.isArray(prior.command.parts)
+        ? prior.command.parts
+        : undefined;
+}
+/**
+ * A message's parts, its inline files stored as artifacts of `sessionId` (or, on a retry, the
+ * first message's files in their place, by position). `stored` lists the artifacts this call
+ * created, for `discardFiles` when the message is refused.
+ */
+export async function messageParts(ctx, sessionId, idempotencyKey, inbound, access) {
+    const parts = inbound.filter((part) => part.type !== "text" || part.text !== "");
+    if (parts.length > MAX_MESSAGE_PARTS)
+        fail(400, `A message may carry at most ${MAX_MESSAGE_PARTS} parts`, { code: "invalid_request" });
+    const prior = parts.some((part) => part.type === "inline")
+        ? (await priorParts(ctx, sessionId, idempotencyKey))?.filter((part) => part.type === "file")
+        : undefined;
+    const out = [];
+    const stored = [];
+    let files = 0;
+    try {
+        for (const part of parts) {
+            if (part.type === "text") {
+                out.push({ type: "text", text: part.text });
+                continue;
+            }
+            const index = files++;
+            if (part.type === "artifact") {
+                out.push({ type: "file", artifactId: part.artifactId });
+                continue;
+            }
+            const again = prior?.[index];
+            if (again) {
+                out.push(again);
+                continue;
+            }
+            const file = await storeInlineFile(ctx, sessionId, part, access);
+            stored.push(file.artifactId);
+            out.push({ type: "file", artifactId: file.artifactId, version: file.version });
+        }
+    }
+    catch (error) {
+        await discardFiles(ctx, stored, access);
+        throw error;
+    }
+    return { parts: out, stored };
+}
+/** Deletes the artifacts a refused message stored; one already gone is no error. */
+export async function discardFiles(ctx, artifactIds, access) {
+    for (const id of artifactIds)
+        await deleteArtifact(ctx, id, access).catch(() => undefined);
+}

package/dist/api/openapi.js

@@ -160,7 +160,7 @@ const RUNTIME_TAGS = [
     {
         name: "Environments",
         group: "Environments",
-        description: "Where sessions run: one sandbox (a virtual workspace, a pod with its own volume, or none) with a recipe that can change, and one vault of secrets for its shell, MCP servers and HTTP tools. Create, find or change one, watch its lifecycle, stop, reset or delete it, and write its secrets. In `@nylorun/agents`.",
+        description: "Where sessions run: one sandbox (a virtual workspace, a pod with its own volume, or none) made from an environment manifest or inline fields and never changed after that, and one vault of secrets for its shell, MCP servers and HTTP tools. Create or find one, watch its lifecycle, stop, reset or delete it, and write its secrets. In `@nylorun/agents`.",
         operations: [
             "PUT /v1/environments/{environmentId}",
             "GET /v1/environments",
@@ -175,10 +175,24 @@ const RUNTIME_TAGS = [
             "DELETE /v1/environments/{environmentId}/secrets/{name}",
             "POST /v1/environments/{environmentId}/snapshot",
             "POST /v1/environments/{environmentId}/restore",
+            "POST /v1/environments/{environmentId}/fork",
             "GET /v1/environments/{environmentId}/versions",
             "DELETE /v1/environments/{environmentId}/versions/{version}",
         ],
     },
+    {
+        name: "Environment manifests",
+        group: "Environments",
+        description: "Named, versioned definitions of a kind of Environment, saved like agents (protocol 14). Save one with a plan first (`?dryRun=true`) and `If-Match`; an Environment is made from one version and keeps it, so a save changes no Environment. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/environment-manifests/{name}",
+            "GET /v1/environment-manifests",
+            "GET /v1/environment-manifests/{name}",
+            "GET /v1/environment-manifests/{name}/versions",
+            "GET /v1/environment-manifests/{name}/versions/{version}",
+            "DELETE /v1/environment-manifests/{name}",
+        ],
+    },
     {
         name: "Artifacts",
         group: "Artifacts",
@@ -231,9 +245,10 @@ const MANAGEMENT_TAGS = [
     },
     {
         name: "Models",
-        description: "Model providers, their credentials, the model the Tenant uses, what it spent, every model call for export, and the budgets that cap it. `admin.models`.",
+        description: "Model providers, their credentials, the model the Tenant uses, what each model reads, what it spent, every model call for export, and the budgets that cap it. `admin.models`.",
         operations: [
             "GET /v1/tenant/models",
+            "PUT /v1/tenant/models/inputs",
             "GET /v1/tenant/providers",
             "GET /v1/tenant/model",
             "PUT /v1/tenant/model",
@@ -377,7 +392,7 @@ function documents() {
         }),
         management: document(all, MANAGEMENT_TAGS, {
             title: "Nylorun Management API",
-            description: "For operators: the Tenant's models, vaults, signing keys, settings and application keys, at `/v1/tenant/*` on the Tenant's URL, through `@nylorun/admin`. Every operation takes a management key, acting as itself: never for a subject and never from a browser. Management keys are issued only on the Tenant's machine (`nylorun key put <id> --management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`.",
+            description: "For operators: the Tenant's models, vaults, signing keys, settings and application keys, at `/v1/tenant/*` on the Tenant's URL, through `@nylorun/admin`. Every operation takes a management key, acting as itself: never for a subject and never from a browser. Management keys are issued only on the Tenant's machine (`nylorun tenant keys put <id> --management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`.",
         }),
     };
     return built;

package/dist/artifacts/disk.js

@@ -13,8 +13,9 @@
  *   version back: directories, files (large ones in appended ranges), then links.
  * - **Restore** puts a version back: on a virtual Environment at once; on a pod as a reset whose
  *   new volume is seeded before any turn (`disk_seed`, run once the new pod's engine connects).
- *   **Fork** (`from` on a create) and the **recovery of a lost volume** (from the latest version)
- *   are seeds too.
+ *   **Fork** (`from` on a create, and `POST .../fork`) and the **recovery of a lost volume** (from
+ *   the latest version) are seeds too. A fork onto other setup (Q17) keeps its seed, `written`,
+ *   until the engine has run that setup on the written disk; turns wait for both.
  *
  * Nothing here runs inside a transaction but the lease and the commit. No event type is new:
  * a restore or recovery is `environment.reset` with `reason` and `from`.
@@ -23,7 +24,6 @@ import { createHash, randomUUID } from "node:crypto";
 import { newArtifactId } from "@nylorun/core/compatibility";
 import { FOLDER_CONTENT_TYPE, FOLDER_MANIFEST_FORMAT_V2, } from "@nylorun/core/contracts";
 import { sandboxSpecOf } from "../sandbox/resolve.js";
-import { capabilityForSandbox } from "../sandbox/share.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
 import { assertReaches, diskHeld, liveEnvironment, newVolume, SEED_LEASE_MS, wakePod, } from "../tenant/environments.js";
 import { fail } from "../tenant/http.js";
@@ -51,15 +51,17 @@ async function diskTarget(ctx, environment) {
         ref: {
             id: `disk:${environment.id}`,
             activeTurnId: null,
-            manifest: { id: "disk", capabilities: [] },
+            manifest: { manifestSchemaVersion: 7, id: "disk" },
             environmentId: environment.id,
+            // Not through a host a restore or a lost volume retired: its connection outlives the commit.
+            ...(environment.pod === undefined ? {} : { hostEpoch: environment.pod.hostEpoch }),
         },
-        capability: capabilityForSandbox(spec),
+        spec,
     };
 }
 /** One disk operation through the workspace, or a `409 environment_unavailable`. */
 async function diskOp(ctx, target, op) {
-    const answer = await ctx.sandbox.disk(target.ref, target.capability, op, new AbortController().signal);
+    const answer = await ctx.sandbox.disk(target.ref, target.spec, op, new AbortController().signal);
     if ("code" in answer)
         return fail(409, `The disk could not be reached: ${answer.message}`, { code: "environment_unavailable" });
     return answer;
@@ -111,10 +113,13 @@ function heartbeat(ctx, id, ms = LEASE_MS) {
                 const environment = await t.environment(id, { lock: true });
                 if (!environment)
                     return;
-                const clearSeed = options.seed !== undefined &&
-                    environment.diskSeed?.artifactId === options.seed.artifactId &&
-                    environment.diskSeed.version === options.seed.version;
-                await t.updateEnvironment(id, { diskOp: null, ...(clearSeed ? { diskSeed: null } : {}) }, new Date().toISOString());
+                const seed = environment.diskSeed;
+                const written = options.seed !== undefined &&
+                    seed?.artifactId === options.seed.artifactId &&
+                    seed.version === options.seed.version;
+                // A seed with setup stays, written, until the engine reports the setup done (Q17).
+                const next = !written ? {} : seed.setup ? { diskSeed: { ...seed, written: true } } : { diskSeed: null };
+                await t.updateEnvironment(id, { diskOp: null, ...next }, new Date().toISOString());
             });
         },
     };
@@ -437,11 +442,12 @@ export async function runPendingSeed(ctx, id) {
     try {
         const environment = await ctx.store.tx((t) => liveEnvironment(t, id));
         const seed = environment?.diskSeed;
-        if (!environment || !seed)
+        if (!environment || !seed || seed.written)
             return;
         if (environment.kind === "pod") {
             const deadline = Date.now() + ENGINE_WAIT_MS;
-            while (!ctx.harness.hosting(id)) {
+            // The engine on the new volume: the old one's connection may still be open.
+            while (!ctx.harness.hosting(id, environment.pod?.hostEpoch)) {
                 if (Date.now() > deadline)
                     return;
                 await new Promise((resolve) => setTimeout(resolve, 250));
@@ -471,9 +477,9 @@ export async function runPendingSeed(ctx, id) {
 }
 /** Starts the pending seeds whose engine is connected and whose lease lapsed (Tenant sweep). */
 export async function sweepPendingSeeds(ctx) {
-    const pending = (await ctx.store.tx((t) => t.listEnvironments())).filter((environment) => environment.diskSeed !== undefined && environment.pod?.desired !== "deleted");
+    const pending = (await ctx.store.tx((t) => t.listEnvironments())).filter((environment) => environment.diskSeed !== undefined && !environment.diskSeed.written && environment.pod?.desired !== "deleted");
     for (const environment of pending)
-        if (environment.kind !== "pod" || ctx.harness.hosting(environment.id))
+        if (environment.kind !== "pod" || ctx.harness.hosting(environment.id, environment.pod?.hostEpoch))
             void runPendingSeed(ctx, environment.id);
 }
 /**

package/dist/artifacts/media-types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Media types of file artifacts: what an upload may declare, what a name's extension implies,
+ * and which model input a file is (`modelInputOf`, protocol 12): text, an image, a PDF, an Office
+ * document, audio or video. A model reads a file only when its inputs include that one.
+ */
+import type { ModelInput } from "@nylorun/core/contracts";
 /** Images the model reads as images. */
 export declare const MODEL_IMAGE_TYPES: readonly string[];
 /** The largest image or text file a model call carries inline. */
@@ -13,3 +19,12 @@ export declare function isModelImage(contentType: string): boolean;
 export declare function isText(contentType: string): boolean;
 /** The usual extension of a media type, for a name the Runtime gives a file; undefined if none. */
 export declare function extensionFor(contentType: string): string | undefined;
+/** The model input a file of `contentType` is, or undefined for a type no model reads. */
+export declare function modelInputOf(contentType: string): ModelInput | undefined;
+/** An input, in a sentence: "PDFs", "Office documents"; "files of this type" for none. */
+export declare function inputLabel(input: ModelInput | undefined): string;
+/**
+ * Why a model that reads `inputs` cannot read a file of `contentType`, or undefined when it can.
+ * An image must also be PNG, JPEG, GIF or WebP.
+ */
+export declare function unreadableReason(contentType: string, inputs: readonly ModelInput[]): string | undefined;

package/dist/artifacts/media-types.js

@@ -1,7 +1,3 @@
-/**
- * Media types of file artifacts: what an upload may declare, what a name's extension implies,
- * and how the model reads a file (an image as an image, text as text, anything else refused).
- */
 import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
 const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/;
 const BY_EXTENSION = {
@@ -12,6 +8,12 @@ const BY_EXTENSION = {
     webp: "image/webp",
     svg: "image/svg+xml",
     pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
     txt: "text/plain",
     md: "text/markdown",
     csv: "text/csv",
@@ -83,3 +85,53 @@ export function extensionFor(contentType) {
     const type = essence(contentType);
     return Object.keys(BY_EXTENSION).find((extension) => BY_EXTENSION[extension] === type);
 }
+/** Word, Excel and PowerPoint documents, old and Open XML. */
+function isOffice(type) {
+    return (type === "application/msword" ||
+        type === "application/vnd.ms-excel" ||
+        type === "application/vnd.ms-powerpoint" ||
+        type.startsWith("application/vnd.openxmlformats-officedocument."));
+}
+/** The model input a file of `contentType` is, or undefined for a type no model reads. */
+export function modelInputOf(contentType) {
+    const type = essence(contentType);
+    if (isText(type))
+        return "text";
+    if (type.startsWith("image/"))
+        return "image";
+    if (type === "application/pdf")
+        return "pdf";
+    if (isOffice(type))
+        return "office";
+    if (type.startsWith("audio/"))
+        return "audio";
+    if (type.startsWith("video/"))
+        return "video";
+    return undefined;
+}
+const LABELS = {
+    text: "text files",
+    image: "images",
+    pdf: "PDFs",
+    office: "Office documents",
+    audio: "audio",
+    video: "video",
+};
+/** An input, in a sentence: "PDFs", "Office documents"; "files of this type" for none. */
+export function inputLabel(input) {
+    return input === undefined ? "files of this type" : LABELS[input];
+}
+/**
+ * Why a model that reads `inputs` cannot read a file of `contentType`, or undefined when it can.
+ * An image must also be PNG, JPEG, GIF or WebP.
+ */
+export function unreadableReason(contentType, inputs) {
+    const input = modelInputOf(contentType);
+    if (input === undefined)
+        return `no model reads ${essence(contentType)} files`;
+    if (!inputs.includes(input))
+        return `this model does not read ${LABELS[input]}`;
+    if (input === "image" && !isModelImage(contentType))
+        return "the model reads PNG, JPEG, GIF and WebP images only";
+    return undefined;
+}

package/dist/artifacts/parts.d.ts

@@ -5,7 +5,7 @@
  * The engine gets an opaque media part whose `reference` is `{ artifactId, version }`: model-gate
  * resolves it to bytes (`./files.ts`), and the transcript and the record never hold them.
  */
-import type { MessagePart } from "@nylorun/core/contracts";
+import type { MessagePart, ModelInput } from "@nylorun/core/contracts";
 import type { JsonObject, JsonValue } from "@nylorun/core/define";
 import type { Tx } from "../store/types.js";
 import { type ArtifactAccess } from "./service.js";
@@ -24,11 +24,20 @@ export interface FileReference {
     readonly version: number;
 }
 export declare function fileReferenceOf(value: JsonValue | undefined): FileReference | undefined;
+/** A file part the Tenant's model does not read (protocol 12, `attachment_unsupported`). */
+export interface RefusedPart {
+    readonly artifactId: string;
+    readonly name: string;
+    readonly mediaType: string;
+    readonly reason: string;
+}
 /**
  * The parts with each file pinned to a version: for the engine (`engine`) and for a workflow's
- * JSON input (`pinned`). Reads in the caller's transaction.
+ * JSON input (`pinned`). Reads in the caller's transaction. With `inputs`, what the Tenant's model
+ * reads, each file of a type it does not read is in `refused` (its type only: no size is checked).
  */
-export declare function resolveMessageParts(t: Tx, parts: readonly MessagePart[], sessionId: string, access: ArtifactAccess): Promise<{
+export declare function resolveMessageParts(t: Tx, parts: readonly MessagePart[], sessionId: string, access: ArtifactAccess, inputs?: readonly ModelInput[]): Promise<{
     engine: EnginePart[];
     pinned: MessagePart[];
+    refused: RefusedPart[];
 }>;

package/dist/artifacts/parts.js

@@ -1,4 +1,5 @@
 import { fail } from "../tenant/http.js";
+import { unreadableReason } from "./media-types.js";
 import { readableArtifact, versionOf } from "./service.js";
 export function fileReferenceOf(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -10,11 +11,13 @@ export function fileReferenceOf(value) {
 }
 /**
  * The parts with each file pinned to a version: for the engine (`engine`) and for a workflow's
- * JSON input (`pinned`). Reads in the caller's transaction.
+ * JSON input (`pinned`). Reads in the caller's transaction. With `inputs`, what the Tenant's model
+ * reads, each file of a type it does not read is in `refused` (its type only: no size is checked).
  */
-export async function resolveMessageParts(t, parts, sessionId, access) {
+export async function resolveMessageParts(t, parts, sessionId, access, inputs) {
     const engine = [];
     const pinned = [];
+    const refused = [];
     for (const part of parts) {
         if (part.type === "text") {
             engine.push({ type: "text", text: part.text });
@@ -27,12 +30,20 @@ export async function resolveMessageParts(t, parts, sessionId, access) {
         if (artifact.kind !== "file")
             fail(400, `Artifact ${artifact.id} is a folder; a file part names a file artifact`);
         const version = await versionOf(t, artifact, part.version);
+        const reason = inputs && unreadableReason(version.contentType, inputs);
+        if (reason)
+            refused.push({ artifactId: artifact.id, name: artifact.name, mediaType: version.contentType, reason });
         engine.push({
             type: "media",
             mediaType: version.contentType,
-            reference: { artifactId: artifact.id, version: version.version, name: artifact.name },
+            reference: {
+                artifactId: artifact.id,
+                version: version.version,
+                name: artifact.name,
+                size: version.size,
+            },
         });
         pinned.push({ type: "file", artifactId: artifact.id, version: version.version });
     }
-    return { engine, pinned };
+    return { engine, pinned, refused };
 }

package/dist/artifacts/workspace.d.ts

@@ -3,15 +3,15 @@
  * 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,
+ * One implementation, `sandboxWorkspaceReader`, over the workspace feature (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 { 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. */
+/** What the reader needs of a workspace: a `SandboxManager`, or the workspace feature. */
 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 {
@@ -23,7 +23,7 @@ export interface WorkspaceSession {
     readonly ownerId: string;
     /** The sandbox resource the workspace belongs to, when the owner is attached to one. */
     readonly environmentId?: string;
-    /** The session's pinned manifest: its sandbox capability carries the sandbox's spec. */
+    /** The session's pinned manifest: its `runtime` block carries the sandbox's spec. */
     readonly manifest: AgentManifest;
 }
 /** One regular file under the listed directory. */

package/dist/artifacts/workspace.js

@@ -1,25 +1,13 @@
-/**
- * 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 { sandboxToolSpec } 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)
+        const spec = sandboxToolSpec(session.manifest, "read");
+        if (!spec)
             return undefined;
         return {
-            capability,
+            spec,
             ref: {
                 id: session.ownerId,
                 activeTurnId: session.turnId,
@@ -33,7 +21,7 @@ export function sandboxWorkspaceReader(sandbox) {
             const found = target(session);
             if (!found)
                 return undefined;
-            const listed = await sandbox.listFiles(found.ref, found.capability, dir, options.maxEntries, options.signal);
+            const listed = await sandbox.listFiles(found.ref, found.spec, dir, options.maxEntries, options.signal);
             if (listed.kind === "missing")
                 return undefined;
             if (listed.kind === "failed")
@@ -44,7 +32,7 @@ export function sandboxWorkspaceReader(sandbox) {
             const found = target(session);
             if (!found)
                 return undefined;
-            const read = await sandbox.readBytes(found.ref, found.capability, path, options.maxBytes, options.signal);
+            const read = await sandbox.readBytes(found.ref, found.spec, path, options.maxBytes, options.signal);
             if (read.kind === "read")
                 return read.bytes;
             if (read.kind === "missing")

package/dist/core/flow-host.d.ts

@@ -16,7 +16,7 @@ export declare function deriveAgentEffectSessionId(workflowSessionId: string, pa
     readonly context?: Record<string, unknown>;
 }): string;
 export declare function isWorkflowManifest(manifest: unknown): manifest is WorkflowManifest;
-/** Flow tool-node effect: `tool` with path/key and no agent capabilityId. */
+/** Flow tool-node effect: `tool` with path/key and no tool name (an agent's tool call names one). */
 export declare function isFlowToolEffect(request: HostEffect): boolean;
 export declare function isFlowEffect(request: HostEffect): boolean;
 /**