@nylorun/runtime 0.15.2-beta → 0.16.0-beta

package/dist/host/stack-config.js

@@ -13,7 +13,15 @@
  * listener (`NYLORUN_GATES_LISTEN_*`), and only one that runs loop parses
  * where to reach the gate (`NYLORUN_GATES_URL`). Both read
  * `NYLORUN_GATES_TOKEN`. In a container, loop requires the gate: the loop
- * process must never hold a model credential.
+ * process must never hold a model credential. `egress` (egress-gate, F7.2) joins gates and keys
+ * in the gateway and parses its listener (`NYLORUN_EGRESS_LISTEN_*`, default `0.0.0.0:4200`).
+ *
+ * `harness` (F6.2) runs alone: it holds the harness credential and nothing else. It connects to
+ * core's Harness API listener (`NYLORUN_HARNESS_URL`, `NYLORUN_HARNESS_TOKEN`), calls models and
+ * remote MCP servers through the gates service (`NYLORUN_GATES_URL`, with run tokens only), and
+ * keeps its workspaces under `NYLORUN_HARNESS_ROOT`. It refuses to start with a database, the
+ * gates' or keys' credential, or Restate settings. A process running core starts the Harness API
+ * listener when `NYLORUN_HARNESS=remote` (`NYLORUN_HARNESS_LISTEN_*`, `NYLORUN_HARNESS_TOKEN`).
  *
  * Two listen modes:
  * - **local** (no `NYLORUN_LISTEN_*` / `NYLORUN_ALLOWED_HOSTS`): the Host binds
@@ -24,21 +32,31 @@
  *   probes from inside the container.
  *
  * The Postgres, Restate and S2 endpoints are parsed and validated here;
- * `infra/*` builds the clients from them. So is who the Host's Tenant is when its database
+ * `infra/*` builds the clients from them. So is the Object store (`NYLORUN_OBJECT_STORE_*`),
+ * which every service may read; `host/main.ts` builds the `BlobStore` from it. So is who the Host's Tenant is when its database
  * holds none yet (`NYLORUN_TENANT_ID`, `NYLORUN_TENANT_NAME`, `NYLORUN_DERIVED_PRINCIPALS`).
  */
 import { DERIVED_PRINCIPAL_ID_PATTERN, isTenantId } from "@nylorun/core/compatibility";
-export const RUNTIME_SERVICES = ["core", "loop", "gates", "keys"];
+import { blockedAddresses } from "../sandbox/pods/network-gate.js";
+export const RUNTIME_SERVICES = ["core", "loop", "gates", "keys", "egress", "harness"];
 /**
  * Services that may share a process (D12): they hold the same secrets and parse the same
- * trust class of input. keys joins gates (F4.2); egress joins them in a later release.
+ * trust class of input. keys joins gates (F4.2), and egress joins them (F7.2). The harness
+ * (F6.2) runs agent code's neighbours and holds only its own credential: it shares with nothing.
  */
 const SERVICE_GROUPS = [
     ["core", "loop"],
-    ["gates", "keys"],
+    ["gates", "keys", "egress"],
+    ["harness"],
 ];
 /** Where the gates service listens by default. */
 export const DEFAULT_GATES_LISTEN_PORT = 4100;
+/** Where egress-gate listens by default. */
+export const DEFAULT_EGRESS_LISTEN_PORT = 4200;
+/** Where core's Harness API listener listens by default. */
+export const DEFAULT_HARNESS_LISTEN_PORT = 4200;
+/** Where a harness process answers `/health` (loopback only). */
+export const DEFAULT_HARNESS_HEALTH_PORT = 4300;
 /** What a process runs without `--service`: core and loop, as `--role all` did. */
 export const DEFAULT_SERVICES = new Set([
     "core",
@@ -46,8 +64,6 @@ export const DEFAULT_SERVICES = new Set([
 ]);
 /** Services of the blueprint this release doesn't have yet. */
 const LATER_SERVICES = [
-    "egress",
-    "harness",
     "sandboxd",
 ];
 const ROLE_SERVICES = {
@@ -74,7 +90,7 @@ function read(env, name) {
     const trimmed = value.trim();
     return trimmed === "" ? undefined : trimmed;
 }
-const USAGE = "Usage: main.js [--service core,loop|gates]";
+const USAGE = "Usage: main.js [--service core,loop|gates,keys,egress|harness]";
 /** Parses `--service a,b` (or the deprecated `--role`); throws `StackConfigError`. */
 export function parseServices(argv) {
     let service;
@@ -248,11 +264,14 @@ function parseIdentityKeys(env) {
 /** Parse the stack configuration; throws `StackConfigError` naming the variable. */
 export function parseStackConfig(env, argv) {
     const { services, deprecatedRole } = parseServices(argv);
+    if (services.has("harness"))
+        return { services, harness: parseHarnessService(env), endpoints: {} };
     // The image sets NYLORUN_LISTEN_*: only the API's processes read them.
     const servesApi = services.has("core") || services.has("loop");
     const listen = servesApi ? parseListen(env) : undefined;
     const operator = servesApi ? parseAdminListen(env) : undefined;
     const gates = services.has("gates") || services.has("keys") ? parseGates(env) : undefined;
+    const egress = services.has("egress") ? parseEgress(env) : undefined;
     // The gates service's clients: the loop's model and tool calls, and core's endpoint pings.
     const modelGate = servesApi ? parseModelGate(env) : undefined;
     // The keys service is the gateway's unless NYLORUN_KEYS_URL names another listener.
@@ -302,12 +321,23 @@ export function parseStackConfig(env, argv) {
     const rawBrowser = read(env, "NYLORUN_BROWSER_ACCESS");
     if (rawBrowser !== undefined && rawBrowser !== "on" && rawBrowser !== "off")
         throw new StackConfigError(`NYLORUN_BROWSER_ACCESS must be on or off, not ${rawBrowser}`);
+    const harnessMode = servesApi ? parseHarnessMode(env) : undefined;
+    const sandboxes = servesApi ? parseSandboxes(env) : undefined;
+    // Pods connect to the Harness API listener even when the Tenant runs its own harness.
+    const harnessListener = harnessMode === "remote" || sandboxes
+        ? parseHarnessListener(env, harnessMode === "remote")
+        : undefined;
+    if (harnessListener &&
+        [listen?.port, operator?.port].includes(harnessListener.listen.port))
+        throw new StackConfigError("NYLORUN_HARNESS_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT and NYLORUN_ADMIN_LISTEN_PORT");
     const delivery = parseDelivery(env);
     const tenant = servesApi ? parseTenant(env) : undefined;
+    const objectStore = parseObjectStore(env);
     return {
         services,
         ...(deprecatedRole ? { deprecatedRole } : {}),
         ...(gates ? { gates } : {}),
+        ...(egress ? { egress } : {}),
         ...(modelGate ? { modelGate } : {}),
         ...(keys ? { keys } : {}),
         ...(rawPacking ? { packing: rawPacking } : {}),
@@ -315,11 +345,37 @@ export function parseStackConfig(env, argv) {
         endpoints,
         ...(publicUrl ? { publicUrl } : {}),
         ...(rawBrowser === undefined ? {} : { browserAccess: rawBrowser === "on" }),
+        ...(harnessMode ? { harnessMode } : {}),
+        ...(harnessListener ? { harnessListener } : {}),
+        ...(sandboxes ? { sandboxes } : {}),
         ...(operator ? { operator } : {}),
         ...(delivery ? { delivery } : {}),
         ...(tenant ? { tenant } : {}),
+        ...(objectStore ? { objectStore } : {}),
     };
 }
+/** S3 bucket names: 3 to 63 lowercase letters, digits, dots and hyphens. */
+const BUCKET = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+/** `StackConfig.objectStore` from `NYLORUN_OBJECT_STORE_*`, or `undefined` without an endpoint. */
+function parseObjectStore(env) {
+    const endpoint = parseUrl(env, "NYLORUN_OBJECT_STORE_ENDPOINT", ["http:", "https:"]);
+    const accessKeyId = read(env, "NYLORUN_OBJECT_STORE_ACCESS_KEY");
+    const secretAccessKey = read(env, "NYLORUN_OBJECT_STORE_SECRET_KEY");
+    if (endpoint === undefined) {
+        if (accessKeyId !== undefined || secretAccessKey !== undefined)
+            throw new StackConfigError("NYLORUN_OBJECT_STORE_ACCESS_KEY or _SECRET_KEY is set without NYLORUN_OBJECT_STORE_ENDPOINT: set the S3 endpoint, e.g. http://rustfs:9000");
+        return undefined;
+    }
+    if (accessKeyId === undefined || secretAccessKey === undefined)
+        throw new StackConfigError("NYLORUN_OBJECT_STORE_ACCESS_KEY and NYLORUN_OBJECT_STORE_SECRET_KEY are required with NYLORUN_OBJECT_STORE_ENDPOINT (`nylorun start` sets them)");
+    const bucket = read(env, "NYLORUN_OBJECT_STORE_BUCKET") ?? "nylorun";
+    if (!BUCKET.test(bucket))
+        throw new StackConfigError(`NYLORUN_OBJECT_STORE_BUCKET must be an S3 bucket name (3 to 63 of a-z 0-9 . -), not ${bucket}`);
+    const region = read(env, "NYLORUN_OBJECT_STORE_REGION") ?? "us-east-1";
+    if (!/^[a-z0-9-]+$/.test(region))
+        throw new StackConfigError(`NYLORUN_OBJECT_STORE_REGION is not a region: ${region}`);
+    return { endpoint: endpoint.replace(/\/+$/, ""), bucket, region, accessKeyId, secretAccessKey };
+}
 function parseTenant(env) {
     const id = read(env, "NYLORUN_TENANT_ID");
     if (id !== undefined && !isTenantId(id))
@@ -336,6 +392,132 @@ function parseTenant(env) {
     };
 }
 const GATES_TOKEN = /^[0-9a-f]{64,}$/i;
+/** `NYLORUN_HARNESS`: `in-process` (the default when unset) or `remote`. */
+function parseHarnessMode(env) {
+    const raw = read(env, "NYLORUN_HARNESS");
+    if (raw === undefined)
+        return undefined;
+    if (raw !== "in-process" && raw !== "remote")
+        throw new StackConfigError(`NYLORUN_HARNESS must be in-process or remote, not ${raw}`);
+    return raw;
+}
+function parseHarnessToken(env, why) {
+    const token = read(env, "NYLORUN_HARNESS_TOKEN");
+    if (token === undefined)
+        throw new StackConfigError(`NYLORUN_HARNESS_TOKEN is required ${why} (\`nylorun start\` sets it)`);
+    if (!GATES_TOKEN.test(token))
+        throw new StackConfigError("NYLORUN_HARNESS_TOKEN must be at least 32 bytes as hex");
+    return token;
+}
+/** `StackConfig.sandboxes` from `NYLORUN_SANDBOXES_*`, or undefined without a URL. */
+function parseSandboxes(env) {
+    const url = parseUrl(env, "NYLORUN_SANDBOXES_URL", ["http:", "https:"]);
+    if (url === undefined)
+        return undefined;
+    const token = read(env, "NYLORUN_SANDBOXES_TOKEN");
+    if (token === undefined || token.length < 32)
+        throw new StackConfigError("NYLORUN_SANDBOXES_TOKEN (at least 32 characters) is required with NYLORUN_SANDBOXES_URL (`nylorun sandbox enable` sets both)");
+    const harnessImage = read(env, "NYLORUN_SANDBOX_HARNESS_IMAGE");
+    if (harnessImage === undefined || /\s/.test(harnessImage))
+        throw new StackConfigError("NYLORUN_SANDBOX_HARNESS_IMAGE is required with NYLORUN_SANDBOXES_URL: the Runtime image sandbox pods copy the engine from (`nylorun start` sets it)");
+    return { url: url.replace(/\/+$/, ""), token, harnessImage };
+}
+/**
+ * `StackConfig.harnessListener` from `NYLORUN_HARNESS_LISTEN_*` and `NYLORUN_HARNESS_TOKEN`
+ * (required with `NYLORUN_HARNESS=remote`; optional when only sandbox pods connect).
+ */
+function parseHarnessListener(env, tokenRequired = true) {
+    const host = read(env, "NYLORUN_HARNESS_LISTEN_HOST") ?? DEFAULT_CONTAINER_LISTEN_HOST;
+    if (/\s|\//.test(host))
+        throw new StackConfigError(`NYLORUN_HARNESS_LISTEN_HOST is not an address: ${host}`);
+    const rawPort = read(env, "NYLORUN_HARNESS_LISTEN_PORT");
+    const port = rawPort === undefined
+        ? DEFAULT_HARNESS_LISTEN_PORT
+        : parsePort("NYLORUN_HARNESS_LISTEN_PORT", rawPort);
+    const rawAllowed = read(env, "NYLORUN_HARNESS_ALLOWED_HOSTS");
+    const explicit = rawAllowed === undefined
+        ? []
+        : rawAllowed
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== "")
+            .map((entry) => normalizeAllowedHost("NYLORUN_HARNESS_ALLOWED_HOSTS", entry));
+    if (explicit.length === 0 && !isLoopbackAddress(host))
+        throw new StackConfigError(`NYLORUN_HARNESS_ALLOWED_HOSTS is required when NYLORUN_HARNESS_LISTEN_HOST is ${host}: list the Host headers harnesses send, e.g. runtime:${port}`);
+    const token = tokenRequired || read(env, "NYLORUN_HARNESS_TOKEN") !== undefined
+        ? parseHarnessToken(env, "with NYLORUN_HARNESS=remote: the credential harnesses present")
+        : undefined;
+    return {
+        listen: { host, port, allowedHosts: [...new Set([...explicit, ...loopbackForms(port)])] },
+        ...(token ? { token } : {}),
+    };
+}
+/** What a harness process must not hold: it runs next to agent code. */
+const HARNESS_REFUSED = ["NYLORUN_DATABASE_URL", "NYLORUN_GATES_TOKEN", "NYLORUN_KEYS_URL"];
+/** `StackConfig.harness` from `NYLORUN_HARNESS_*` and `NYLORUN_GATES_URL`. */
+function parseHarnessService(env) {
+    const held = [
+        ...HARNESS_REFUSED.filter((name) => read(env, name) !== undefined),
+        ...Object.keys(env)
+            .filter((name) => name.startsWith("NYLORUN_RESTATE_") && read(env, name) !== undefined)
+            .sort(),
+    ];
+    if (held.length > 0)
+        throw new StackConfigError(`--service harness refuses to start with ${held.join(", ")} set: a harness reaches no database, no gate or keys credential and no Restate`);
+    const pod = read(env, "NYLORUN_SANDBOX_KIND") === "pod";
+    const url = parseUrl(env, "NYLORUN_HARNESS_URL", pod ? ["http:", "https:", "ws:", "wss:"] : ["ws:", "wss:"]);
+    if (url === undefined)
+        throw new StackConfigError("NYLORUN_HARNESS_URL is required for --service harness: core's Harness API, e.g. ws://runtime:4200/nylorun/harness/v1");
+    const gatesUrl = parseUrl(env, "NYLORUN_GATES_URL", ["http:", "https:"]);
+    if (gatesUrl === undefined)
+        throw new StackConfigError("NYLORUN_GATES_URL is required for --service harness: its model and MCP calls go through the gates service, e.g. http://gateway:4100");
+    const root = read(env, "NYLORUN_HARNESS_ROOT") ?? "/harness";
+    if (!root.startsWith("/"))
+        throw new StackConfigError(`NYLORUN_HARNESS_ROOT must be an absolute path, not ${root}`);
+    const rawHealth = read(env, "NYLORUN_HARNESS_HEALTH_PORT");
+    const podHost = pod ? parsePodHost(env, url) : undefined;
+    return {
+        url: podHost ? podHost.wsUrl : url,
+        ...(podHost
+            ? { pod: podHost.config }
+            : { token: parseHarnessToken(env, "for --service harness: the credential core's Harness API accepts") }),
+        gatesUrl: gatesUrl.replace(/\/+$/, ""),
+        root,
+        healthPort: rawHealth === undefined
+            ? DEFAULT_HARNESS_HEALTH_PORT
+            : parsePort("NYLORUN_HARNESS_HEALTH_PORT", rawHealth),
+    };
+}
+/**
+ * The engine in a pod sandbox: the pod's identity and its join file, from the variables the
+ * sandboxes service renders into the pod. `NYLORUN_HARNESS_URL` is the listener's address on the
+ * Docker host (`http://<host>:<port>`); the WebSocket URL adds the Harness API path.
+ */
+function parsePodHost(env, url) {
+    const need = (name) => {
+        const value = read(env, name);
+        if (value === undefined)
+            throw new StackConfigError(`${name} is required for the engine in a sandbox pod (NYLORUN_SANDBOX_KIND=pod)`);
+        return value;
+    };
+    if (read(env, "NYLORUN_HARNESS_TOKEN") !== undefined)
+        throw new StackConfigError("A sandbox pod's engine holds no NYLORUN_HARNESS_TOKEN: it joins with its join token");
+    const base = new URL(url);
+    const secure = base.protocol === "https:" || base.protocol === "wss:";
+    const origin = `${secure ? "https" : "http"}://${base.host}`;
+    const egress = read(env, "NYLORUN_EGRESS_PROXY");
+    return {
+        wsUrl: `${secure ? "wss" : "ws"}://${base.host}/nylorun/harness/v1`,
+        config: {
+            sandboxId: need("NYLORUN_SANDBOX_ID"),
+            podUid: need("NYLORUN_POD_UID"),
+            joinFile: need("NYLORUN_SANDBOX_JOIN_FILE"),
+            httpUrl: origin,
+            ...(egress ? { egressProxy: egress.replace(/\/+$/, "") } : {}),
+            blocked: blockedAddresses(env),
+        },
+    };
+}
 /** `StackConfig.gates` from `NYLORUN_GATES_*`. */
 function parseGates(env) {
     const host = read(env, "NYLORUN_GATES_LISTEN_HOST") ?? DEFAULT_CONTAINER_LISTEN_HOST;
@@ -365,6 +547,15 @@ function parseGates(env) {
         token,
     };
 }
+/** `StackConfig.egress` from `NYLORUN_EGRESS_LISTEN_*`. CONNECT has no Host header to check. */
+function parseEgress(env) {
+    const host = read(env, "NYLORUN_EGRESS_LISTEN_HOST") ?? DEFAULT_CONTAINER_LISTEN_HOST;
+    if (/\s|\//.test(host))
+        throw new StackConfigError(`NYLORUN_EGRESS_LISTEN_HOST is not an address: ${host}`);
+    const rawPort = read(env, "NYLORUN_EGRESS_LISTEN_PORT");
+    const port = rawPort === undefined ? DEFAULT_EGRESS_LISTEN_PORT : parsePort("NYLORUN_EGRESS_LISTEN_PORT", rawPort);
+    return { listen: { host, port } };
+}
 /** `StackConfig.modelGate` from `NYLORUN_GATES_URL` and `NYLORUN_GATES_TOKEN`. */
 function parseModelGate(env) {
     const url = parseUrl(env, "NYLORUN_GATES_URL", ["http:", "https:"]);

package/dist/mcp/snapshot.d.ts

@@ -1,5 +1,6 @@
 import type { JsonObject } from "@nylorun/core/define";
-import type { AgentManifest } from "@nylorun/core/define";
+import { type AgentManifest } from "@nylorun/core/define";
+import type { DurableSessionTool, HostEffect } from "@nylorun/harness/run";
 export interface McpToolRecord {
     /** The agent used as a tool that declares the server; absent for the session's root agent. */
     readonly agentId?: string;
@@ -27,3 +28,9 @@ export interface McpDiagnostic {
 }
 export declare function modelToolName(serverName: string, serverToolName: string): string;
 export declare function declaredToolNames(manifest: AgentManifest): Set<string>;
+/** The tools of a snapshot, as the engine advertises them. */
+export declare function sessionToolsOf(snapshot: McpSnapshot | undefined): readonly DurableSessionTool[] | undefined;
+/** The snapshot's record of an MCP tool call, or undefined when the call is not an MCP tool. */
+export declare function mcpToolOf(snapshot: McpSnapshot | undefined, request: Pick<HostEffect, "agent" | "capabilityId" | "toolName">): McpToolRecord | undefined;
+/** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
+export declare function manifestFor(manifest: AgentManifest, agent: HostEffect["agent"]): AgentManifest | undefined;

package/dist/mcp/snapshot.js

@@ -1,3 +1,4 @@
+import { delegateManifest } from "@nylorun/core/define";
 export function modelToolName(serverName, serverToolName) {
     return `${serverName}__${serverToolName}`;
 }
@@ -8,3 +9,30 @@ export function declaredToolNames(manifest) {
             names.add(tool.name);
     return names;
 }
+/** The tools of a snapshot, as the engine advertises them. */
+export function sessionToolsOf(snapshot) {
+    if (!snapshot?.mcpTools.length)
+        return undefined;
+    return snapshot.mcpTools.map((tool) => ({
+        ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
+        capabilityId: tool.capabilityId,
+        name: tool.name,
+        ...(tool.description === undefined
+            ? {}
+            : { description: tool.description }),
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined
+            ? {}
+            : { outputSchema: tool.outputSchema }),
+    }));
+}
+/** The snapshot's record of an MCP tool call, or undefined when the call is not an MCP tool. */
+export function mcpToolOf(snapshot, request) {
+    return snapshot?.mcpTools.find((tool) => tool.agentId === request.agent?.id &&
+        tool.capabilityId === request.capabilityId &&
+        tool.name === request.toolName);
+}
+/** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
+export function manifestFor(manifest, agent) {
+    return agent ? delegateManifest(manifest, agent.id) : manifest;
+}

package/dist/media.d.ts

@@ -1,29 +1,10 @@
+/**
+ * Image checks for code that handles image bytes itself (an image tool in an Action endpoint):
+ * the supported types, the size cap and a signature check. Storing images is the job of file
+ * artifacts (`artifacts/`, protocol 6), which replaced `MediaStore`.
+ */
 export declare const IMAGE_MEDIA_TYPES: readonly string[];
 export declare const MAX_IMAGE_BYTES: number;
-export interface MediaAsset {
-    readonly id: string;
-    readonly mediaType: string;
-    readonly bytes: number;
-    readonly kind: "input" | "generated";
-}
-/** Opaque reference retained by Harness and resolved by the configured media adapter. */
-export interface MediaReference {
-    readonly agentId: string;
-    readonly assetId: string;
-}
 export declare function decodeImageBase64(mediaType: string, base64: string): Uint8Array;
 /** Verify the asserted media type and lightweight file signature for a supported image. */
 export declare function validateImageBytes(mediaType: string, bytes: Uint8Array): void;
-export interface RuntimeMedia {
-    saveInput(agentId: string, sessionId: string, mediaType: string, base64: string): Promise<MediaAsset>;
-    saveGenerated(agentId: string, sessionId: string, mediaType: string, bytes: Uint8Array): Promise<MediaAsset>;
-    dataUrl(reference: MediaReference, sessionId: string): Promise<{
-        readonly asset: MediaAsset;
-        readonly url: string;
-    } | undefined>;
-    latestInput(agentId: string, sessionId: string): Promise<MediaAsset | undefined>;
-    read(agentId: string, sessionId: string, assetId: string): Promise<{
-        asset: MediaAsset;
-        bytes: Uint8Array;
-    } | undefined>;
-}

package/dist/media.js

@@ -1,3 +1,8 @@
+/**
+ * Image checks for code that handles image bytes itself (an image tool in an Action endpoint):
+ * the supported types, the size cap and a signature check. Storing images is the job of file
+ * artifacts (`artifacts/`, protocol 6), which replaced `MediaStore`.
+ */
 export const IMAGE_MEDIA_TYPES = Object.freeze([
     "image/jpeg",
     "image/png",

package/dist/model/pi-model.d.ts

@@ -1,6 +1,6 @@
 import { type Credential } from "@earendil-works/pi-ai";
 import type { RuntimeModelAdapter } from "../contracts.js";
-import type { RuntimeMedia } from "../adapters/media.js";
+import { type FileResolver } from "../artifacts/files.js";
 import type { HostModelSecret } from "../vault/service.js";
 export interface ModelPreview {
     readonly invocationId: string;
@@ -20,7 +20,11 @@ export interface ModelCallSettings {
 export interface PiModelOptions {
     readonly root?: string;
     readonly onPreview?: (preview: ModelPreview) => void;
-    readonly media?: Pick<RuntimeMedia, "dataUrl">;
+    /**
+     * Resolves the files a prompt names (media parts whose reference is an artifact version) to
+     * their bytes. Model-gate passes one over the Tenant's artifacts (`artifactFiles`).
+     */
+    readonly files?: FileResolver;
     readonly readHostModel?: () => HostModelSecret | undefined | Promise<HostModelSecret | undefined>;
     readonly writeHostCredential?: (credential: Credential) => void | Promise<void>;
     readonly settings?: ModelCallSettings;

package/dist/model/pi-model.js

@@ -1,4 +1,6 @@
 import { parseJsonWithRepair, retryAssistantCall, } from "@earendil-works/pi-ai";
+import { FileUnavailableError, } from "../artifacts/files.js";
+import { essence, isModelImage, isText } from "../artifacts/media-types.js";
 import { scrub } from "../redact.js";
 import { classifyAssistantError, failure } from "./classify.js";
 import { modelsFor } from "./models.js";
@@ -227,28 +229,43 @@ async function buildContext(call, selected, options) {
             if (part.type === "text")
                 result.push({ type: "text", text: part.text });
             else if (part.type === "media") {
-                if (!selected.input.includes("image"))
-                    throw new InvalidRequest("The configured model does not accept images.");
-                const ref = part.reference;
-                if (!ref ||
-                    typeof ref !== "object" ||
-                    Array.isArray(ref) ||
-                    !("agentId" in ref) ||
-                    !("assetId" in ref) ||
-                    typeof ref.agentId !== "string" ||
-                    typeof ref.assetId !== "string")
-                    throw new InvalidRequest("Expected a local media reference.");
-                const asset = await options.media?.dataUrl({ agentId: ref.agentId, assetId: ref.assetId }, "sessionId" in ref && typeof ref.sessionId === "string"
-                    ? ref.sessionId
-                    : call.executionId);
-                if (!asset)
-                    throw new InvalidRequest("Media is unavailable; pass the shared media adapter to piModel({ media }).");
-                const comma = asset.url.indexOf(",");
-                result.push({
-                    type: "image",
-                    data: asset.url.slice(comma + 1),
-                    mimeType: asset.asset.mediaType,
-                });
+                // A file the message named by artifact (protocol 6): its bytes go only into the
+                // provider request built here, never into the transcript or the journal.
+                if (!options.files)
+                    throw new InvalidRequest("Files are unavailable; pass a file resolver to piModel({ files }).");
+                let file;
+                try {
+                    file = await options.files(part.reference);
+                }
+                catch (error) {
+                    if (error instanceof FileUnavailableError)
+                        throw new InvalidRequest(error.message);
+                    throw error;
+                }
+                if (isModelImage(file.mediaType)) {
+                    if (!selected.input.includes("image"))
+                        throw new InvalidRequest("The configured model does not accept images.");
+                    result.push({
+                        type: "image",
+                        data: Buffer.from(file.bytes).toString("base64"),
+                        mimeType: essence(file.mediaType),
+                    });
+                }
+                else if (isText(file.mediaType)) {
+                    let text;
+                    try {
+                        text = new TextDecoder("utf-8", { fatal: true }).decode(file.bytes);
+                    }
+                    catch {
+                        throw new InvalidRequest(`${file.name} is not UTF-8 text.`);
+                    }
+                    result.push({
+                        type: "text",
+                        text: `<file name=${JSON.stringify(file.name)} type=${JSON.stringify(essence(file.mediaType))}>\n${text}\n</file>`,
+                    });
+                }
+                else
+                    throw new InvalidRequest(`The model reads images and text files; ${file.name} is ${essence(file.mediaType)}.`);
             }
         }
         return result;

package/dist/node/index.d.ts

@@ -1,5 +1,5 @@
-export { localMedia, MediaStore } from "../adapters/media.js";
 export { jsonlObserver } from "../adapters/observe.js";
 export { piModel, type PiModelOptions } from "../model/pi-model.js";
+export { FileUnavailableError, type FileResolver, type ResolvedFile, } from "../artifacts/files.js";
 export { projectAsset } from "../assets.js";
 export { probeSandboxBackends, type SandboxSelectionReport, } from "../sandbox/select.js";

package/dist/node/index.js

@@ -1,5 +1,5 @@
-export { localMedia, MediaStore } from "../adapters/media.js";
 export { jsonlObserver } from "../adapters/observe.js";
 export { piModel } from "../model/pi-model.js";
+export { FileUnavailableError, } from "../artifacts/files.js";
 export { projectAsset } from "../assets.js";
 export { probeSandboxBackends, } from "../sandbox/select.js";