@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/adapters/sandbox/local.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxBackend } from "../../sandbox/types.js";
+import type { ExecRequest, ExecResult, SandboxBackend } from "../../sandbox/types.js";
 export interface LocalBackendOptions {
     /** Default `/workspace`. */
     readonly workspace?: string;
@@ -6,5 +6,13 @@ export interface LocalBackendOptions {
     readonly proxyEnv?: () => Readonly<Record<string, string>>;
     /** The base environment of commands (the engine's allowlisted one); `NYLORUN_*` is dropped. */
     readonly env: Readonly<Record<string, string | undefined>>;
+    /** The engine's `/harness` on the same volume, a disk root of its versions (R2d step 3). */
+    readonly harnessRoot?: string;
 }
+/**
+ * How the pod runs a command: `/bin/sh -c` in its own process group, with the base environment,
+ * the request's variables and the proxy of the moment. The sandbox tools and the disk's setup
+ * (`harness/setup.ts`) both run commands this way.
+ */
+export declare function localExec(options: LocalBackendOptions): (request: ExecRequest, signal: AbortSignal) => Promise<ExecResult>;
 export declare function localBackend(options: LocalBackendOptions): SandboxBackend;

package/dist/adapters/sandbox/local.js

@@ -49,10 +49,14 @@ function collector() {
         },
     };
 }
-export function localBackend(options) {
-    const workspace = options.workspace ?? SANDBOX_WORKSPACE;
-    const env = baseEnv(options.env, workspace);
-    const exec = (request, signal) => new Promise((resolve, reject) => {
+/**
+ * How the pod runs a command: `/bin/sh -c` in its own process group, with the base environment,
+ * the request's variables and the proxy of the moment. The sandbox tools and the disk's setup
+ * (`harness/setup.ts`) both run commands this way.
+ */
+export function localExec(options) {
+    const env = baseEnv(options.env, options.workspace ?? SANDBOX_WORKSPACE);
+    return (request, signal) => new Promise((resolve, reject) => {
         if (signal.aborted)
             return reject(signal.reason ?? new Error("Turn cancelled"));
         const child = spawn("/bin/sh", ["-c", request.command], {
@@ -102,10 +106,18 @@ export function localBackend(options) {
             });
         });
     });
+}
+export function localBackend(options) {
+    const workspace = options.workspace ?? SANDBOX_WORKSPACE;
+    const exec = localExec(options);
     const missing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR";
     const handle = {
         workspace,
         exec,
+        diskRoots: {
+            workspace,
+            ...(options.harnessRoot === undefined ? {} : { harness: options.harnessRoot }),
+        },
         async readFile(path) {
             try {
                 return await readFile(path, "utf8");

package/dist/adapters/sandbox/virtual.js

@@ -1,5 +1,6 @@
 /**
- * Virtual backend: an emulated bash with a virtual filesystem, running in the Runtime process.
+ * Virtual backend: an emulated bash with a virtual filesystem, running in the harness's process
+ * (the harness container, or the Runtime process with NYLORUN_HARNESS=in-process).
  * `/workspace` is backed by a host directory so files survive stop and Runtime restarts.
  * It is not a VM boundary; it exists so the first run and CI work on any machine.
  */
@@ -67,6 +68,8 @@ export function virtualBackend(options) {
                 ...(network ? { network } : {}),
             });
             return {
+                // A virtual workspace's disk is its host directory: `/workspace` only.
+                diskRoots: { workspace: root },
                 async exec(request, signal) {
                     const controller = new AbortController();
                     let timedOut = false;

package/dist/api/a2a/card.d.ts

@@ -12,4 +12,14 @@ export interface CardDefinition {
     };
     readonly implementationVersion: string;
 }
-export declare function agentCard(agentId: string, definition: CardDefinition): Record<string, unknown>;
+import type { ModelInput } from "@nylorun/core/contracts";
+/**
+ * The input modes for a model that reads `inputs`: text and JSON, then the media types of the
+ * files it reads. No inputs known (no model in the vault): text and JSON.
+ */
+export declare function inputModesFor(inputs: readonly ModelInput[] | undefined): string[];
+/**
+ * `inputModes`: the media types the agent takes, when its model reads files; default text and
+ * JSON. The output modes stay text and JSON.
+ */
+export declare function agentCard(agentId: string, definition: CardDefinition, inputModes?: readonly string[]): Record<string, unknown>;

package/dist/api/a2a/card.js

@@ -4,8 +4,32 @@
  * `supportedInterfaces` is empty: whoever publishes the card (the gateway in v1) adds its own
  * URL, provider and security schemes.
  */
+import { MODEL_IMAGE_TYPES } from "../../artifacts/media-types.js";
 const MODES = ["text/plain", "application/json"];
-export function agentCard(agentId, definition) {
+/** The media types a card advertises for each file input a model reads. */
+const INPUT_MODES = {
+    image: MODEL_IMAGE_TYPES,
+    pdf: ["application/pdf"],
+    office: [
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ],
+    audio: ["audio/*"],
+    video: ["video/*"],
+};
+/**
+ * The input modes for a model that reads `inputs`: text and JSON, then the media types of the
+ * files it reads. No inputs known (no model in the vault): text and JSON.
+ */
+export function inputModesFor(inputs) {
+    return [...MODES, ...(inputs ?? []).flatMap((input) => (input === "text" ? [] : INPUT_MODES[input]))];
+}
+/**
+ * `inputModes`: the media types the agent takes, when its model reads files; default text and
+ * JSON. The output modes stay text and JSON.
+ */
+export function agentCard(agentId, definition, inputModes = MODES) {
     const { manifest } = definition;
     const name = typeof manifest.name === "string" && manifest.name !== "" ? manifest.name : agentId;
     const description = typeof manifest.description === "string" && manifest.description !== ""
@@ -17,7 +41,7 @@ export function agentCard(agentId, definition) {
         supportedInterfaces: [],
         version: definition.implementationVersion,
         capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
-        defaultInputModes: MODES,
+        defaultInputModes: [...inputModes],
         defaultOutputModes: MODES,
         skills: [{ id: agentId, name, description, tags: [] }],
     };

package/dist/api/a2a/endpoint.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { readText } from "../http/body.js";
-import { tenantRoute } from "../http/define.js";
+import { INLINE_BODY_MAX_BYTES } from "../inbound-files.js";
+import { TraceHeaders, tenantRoute } from "../http/define.js";
+import { traceContextOf } from "../../traces/ids.js";
 import { jsonResponse } from "../http/respond.js";
 import { a2aCall, a2aCard } from "./routes.js";
 const A2A_SPECIFICATION = {
@@ -55,7 +57,7 @@ export function a2aRoutes(api) {
         path: "/v1/a2a/agents/{agentId}",
         tags: TAGS,
         summary: "Call an agent over A2A",
-        description: "A2A 1.0 JSON-RPC, for a subject: `SendMessage` (blocking up to 5 minutes, or `returnImmediately`), `GetTask` and `CancelTask`. A context is one session per subject, agent and `contextId`; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors.",
+        description: "A2A 1.0 JSON-RPC, for a subject: `SendMessage` (blocking up to 5 minutes, or `returnImmediately`), `GetTask` and `CancelTask`. A message is text, one data part, or text and `raw` files (at most 20 MiB each, stored as artifacts of the context's session); a file `url` is `ContentTypeNotSupportedError`. A context is one session per subject, agent and `contextId`; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors.",
         externalDocs: A2A_SPECIFICATION,
         request: {
             params: agentId,
@@ -63,6 +65,7 @@ export function a2aRoutes(api) {
                 "A2A-Version": z.string().optional().meta({ description: "Or the `A2A-Version` header: `1.0`" }),
             }),
             body: { required: true, content: { "application/json": { schema: JsonRpcRequest } } },
+            headers: TraceHeaders,
         },
         responses: {
             200: {
@@ -73,9 +76,12 @@ export function a2aRoutes(api) {
     }, async (c) => {
         const scope = c.get("scope");
         const version = c.env.incoming.headers["a2a-version"];
+        const trace = traceContextOf(c.req.raw.headers);
         return jsonResponse(200, await a2aCall(c.env.tenant, scope, c.req.param("agentId"), {
-            body: () => readText(c.req.raw),
+            // A message may carry files inline.
+            body: () => readText(c.req.raw, INLINE_BODY_MAX_BYTES),
             version: typeof version === "string" ? version : (c.req.query("A2A-Version") ?? null),
+            ...(trace ? { trace } : {}),
         }, c.env.outgoing));
     });
 }

package/dist/api/a2a/protocol.d.ts

@@ -1,7 +1,7 @@
 /**
  * A2A 1.0 over JSON-RPC: the wire types the Runtime answers with, the envelope, the error
  * codes and the parameter checks (Host feature `a2a-endpoint`). Only what v1 serves is typed:
- * text and data parts, tasks, the card. Field names are the spec's ProtoJSON (camelCase,
+ * text, data and file parts, tasks, the card. Field names are the spec's ProtoJSON (camelCase,
  * enum values such as `TASK_STATE_WORKING`). No Tenant state is read here.
  */
 /** The A2A version this endpoint speaks (`A2A-Version`, Major.Minor). */
@@ -16,6 +16,16 @@ export type Part = {
     data: unknown;
     mediaType?: string;
     metadata?: Record<string, unknown>;
+} | {
+    raw: string;
+    mediaType?: string;
+    filename?: string;
+    metadata?: Record<string, unknown>;
+} | {
+    url: string;
+    mediaType?: string;
+    filename?: string;
+    metadata?: Record<string, unknown>;
 };
 export interface Message {
     messageId: string;
@@ -120,11 +130,24 @@ export declare function parseEnvelope(text: string): {
 };
 /** `A2A-Version` as Major.Minor; empty means 0.3 (spec §3.6.2). */
 export declare function checkVersion(value: string | null | undefined): void;
-/** A client's message reduced to what the Runtime runs: text, or one JSON value. */
+/** A file sent inline (`raw`, base64): stored as an artifact of the context's session. */
+export interface RawFile {
+    readonly raw: string;
+    readonly mediaType?: string;
+    readonly filename?: string;
+}
+/**
+ * A client's message reduced to what the Runtime runs: text, one JSON value, or text and files
+ * sent inline.
+ */
 export type MessageInput = {
     content: string;
 } | {
     data: unknown;
+} | {
+    files: readonly ({
+        text: string;
+    } | RawFile)[];
 };
 export interface SendParams {
     messageId: string;

package/dist/api/a2a/protocol.js

@@ -1,7 +1,7 @@
 /**
  * A2A 1.0 over JSON-RPC: the wire types the Runtime answers with, the envelope, the error
  * codes and the parameter checks (Host feature `a2a-endpoint`). Only what v1 serves is typed:
- * text and data parts, tasks, the card. Field names are the spec's ProtoJSON (camelCase,
+ * text, data and file parts, tasks, the card. Field names are the spec's ProtoJSON (camelCase,
  * enum values such as `TASK_STATE_WORKING`). No Tenant state is read here.
  */
 /** The A2A version this endpoint speaks (`A2A-Version`, Major.Minor). */
@@ -136,7 +136,12 @@ function partKind(part, field) {
         return a2aFail("invalidParams", `${field} must contain exactly one of text, raw, url, data`, {}, field);
     if (kinds[0] === "text" && typeof part.text !== "string")
         return a2aFail("invalidParams", `${field}.text must be a string`, {}, `${field}.text`);
-    return kinds[0] === "raw" || kinds[0] === "url" ? "file" : kinds[0];
+    if (kinds[0] === "raw" && typeof part.raw !== "string")
+        return a2aFail("invalidParams", `${field}.raw must be base64 bytes`, {}, `${field}.raw`);
+    for (const key of ["mediaType", "filename"])
+        if (part[key] !== undefined && typeof part[key] !== "string")
+            return a2aFail("invalidParams", `${field}.${key} must be a string`, {}, `${field}.${key}`);
+    return kinds[0] === "raw" ? "raw" : kinds[0] === "url" ? "url" : kinds[0];
 }
 /** `SendMessage` params (spec §3.2.1), checked in the order a client can fix them. */
 export function parseSendParams(params) {
@@ -166,8 +171,20 @@ export function parseSendParams(params) {
         input = { content: parts.map((part) => part.text).join("\n") };
     else if (kinds.length === 1 && kinds[0] === "data")
         input = { data: parts[0].data };
+    else if (kinds.includes("url"))
+        return a2aFail("contentTypeNotSupported", "File URLs are not fetched yet; send the bytes inline as raw", { accepted: "raw" });
+    else if (kinds.includes("data"))
+        return a2aFail("contentTypeNotSupported", "This agent accepts text and file parts, or a single data part", { accepted: "text/plain,application/json" });
     else
-        return a2aFail("contentTypeNotSupported", "This agent accepts text parts, or a single data part; files are not supported", { accepted: "text/plain,application/json" });
+        input = {
+            files: parts.map((part, index) => kinds[index] === "text"
+                ? { text: part.text }
+                : {
+                    raw: part.raw,
+                    ...(part.mediaType !== undefined ? { mediaType: part.mediaType } : {}),
+                    ...(part.filename !== undefined ? { filename: part.filename } : {}),
+                }),
+        };
     if ("content" in input && input.content.trim() === "")
         a2aFail("invalidParams", "The message has no text", {}, "message.parts");
     return {

package/dist/api/a2a/routes.d.ts

@@ -1,11 +1,15 @@
 import type { ServerResponse } from "node:http";
 import { type AuthScope, type TenantContext } from "../../tenant/context.js";
+import type { TraceContext } from "../../traces/ids.js";
 /**
  * How long a blocking `SendMessage` waits for the task to end or ask for input. After it, the
  * task is returned `WORKING` and keeps running; the caller polls `GetTask`.
  */
 export declare const A2A_BLOCKING_WAIT_MS: number;
-/** `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. */
+/**
+ * `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. Its
+ * input modes name the files the Tenant's model reads.
+ */
 export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: string): Promise<unknown>;
 /**
  * `POST /v1/a2a/agents/:agent`: one A2A JSON-RPC call, for a subject. JSON-RPC answers (errors
@@ -16,4 +20,5 @@ export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: s
 export declare function a2aCall(ctx: TenantContext, scope: AuthScope, agentId: string, input: {
     body: () => Promise<string>;
     version: string | null;
+    trace?: TraceContext;
 }, response: ServerResponse): Promise<unknown>;

package/dist/api/a2a/routes.js

@@ -9,13 +9,20 @@
  * caller's scope (limits and owner checks apply), sessions derived from the caller's own
  * subject, history from Durable Streams. A task id from the client only selects a context and
  * a turn within the caller's own sessions, so another subject's task is `TaskNotFoundError`.
+ *
+ * A message's `raw` file parts are stored as artifacts of the context's session once it is open,
+ * and the message goes in as `parts` (`../inbound-files.ts`): a file the model does not read is
+ * `ContentTypeNotSupportedError`, and the files of a refused message are deleted.
  */
 import { randomUUID } from "node:crypto";
 import { SessionCommandSchema, } from "@nylorun/core/contracts";
 import { commandKey } from "../../core/flow-host.js";
-import { agentCard } from "./card.js";
+import { contentTypeFor } from "../../artifacts/media-types.js";
+import { discardFiles, inlineFileName, messageParts, } from "../inbound-files.js";
+import { agentCard, inputModesFor } from "./card.js";
 import { A2aError, a2aFail, checkVersion, jsonRpcError, jsonRpcResult, parseEnvelope, parseSendParams, parseTaskParams, } from "./protocol.js";
 import { SETTLED_EVENTS, buildTask, contextSessionId, newContextId, parseTaskId, pendingInteraction, taskIdOf, } from "./tasks.js";
+import { currentModelInputs } from "../../model/catalog.js";
 import { accessOf } from "../../tenant/auth.js";
 import { command } from "../../tenant/commands.js";
 import { loadSession, } from "../../tenant/context.js";
@@ -27,9 +34,14 @@ import { putSession } from "../../tenant/sessions.js";
  * task is returned `WORKING` and keeps running; the caller polls `GetTask`.
  */
 export const A2A_BLOCKING_WAIT_MS = 5 * 60_000;
-/** `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. */
+/**
+ * `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. Its
+ * input modes name the files the Tenant's model reads.
+ */
 export async function a2aCard(ctx, scope, agentId) {
-    return agentCard(agentId, await definitionFor(ctx, agentId, accessOf(scope)));
+    const definition = await definitionFor(ctx, agentId, accessOf(scope));
+    // The files a caller may send: those the Tenant's model reads now.
+    return agentCard(agentId, definition, inputModesFor(await currentModelInputs(ctx)));
 }
 /**
  * `POST /v1/a2a/agents/:agent`: one A2A JSON-RPC call, for a subject. JSON-RPC answers (errors
@@ -50,7 +62,7 @@ export async function a2aCall(ctx, scope, agentId, input, response) {
     // A blocking call stops waiting when the caller hangs up; the task keeps running.
     const hangup = new AbortController();
     response.on("close", () => hangup.abort());
-    const caller = { ctx, scope, access, agentId };
+    const caller = { ctx, scope, access, agentId, ...(input.trace ? { trace: input.trace } : {}) };
     const { id } = envelope.request;
     try {
         checkVersion(input.version);
@@ -60,7 +72,7 @@ export async function a2aCall(ctx, scope, agentId, input, response) {
         if (error instanceof A2aError)
             return jsonRpcError(id, error);
         // Limits, scopes and unavailable streams stay HTTP answers, as on every Tenant route.
-        if (error instanceof HttpError && [403, 429, 503].includes(error.status))
+        if (error instanceof HttpError && [403, 413, 429, 503].includes(error.status))
             throw error;
         ctx.config.logger.warn("a2a request failed", {
             agentId,
@@ -137,11 +149,18 @@ async function run(caller, sessionId, input,
 /** The error for a `409` conflict: the session is busy or no longer waiting. */
 conflict) {
     try {
-        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope));
+        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope, caller.trace ? { trace: caller.trace } : {}));
         return { turnId: accepted.turnId, cursor: accepted.cursor };
     }
     catch (error) {
-        if (!(error instanceof HttpError) || error.status !== 409)
+        if (!(error instanceof HttpError))
+            throw error;
+        // A file the agent's model does not read (`attachment_unsupported`).
+        if (error.status === 422)
+            return a2aFail("contentTypeNotSupported", error.message, {
+                reason: error.rejection.code ?? "request_rejected",
+            });
+        if (error.status !== 409)
             throw error;
         if (error.message.startsWith("Idempotency key"))
             return a2aFail("invalidParams", "message.messageId was already used for a different message", {}, "message.messageId");
@@ -162,13 +181,17 @@ async function openContext(caller, sessionId) {
 async function sendMessage(caller, params, signal) {
     const send = parseSendParams(params);
     const idempotencyKey = `a2a:${send.messageId}`;
-    const value = "content" in send.input ? send.input.content : send.input.data;
     let contextId;
     let sessionId;
     let accepted;
     if (send.taskId !== undefined) {
         // A reply on an existing task: only a question it is waiting on can take it.
         const ids = parseTaskId(send.taskId) ?? taskNotFound(send.taskId);
+        const value = "content" in send.input
+            ? send.input.content
+            : "data" in send.input
+                ? send.input.data
+                : a2aFail("contentTypeNotSupported", "A reply takes text or one data part; send files in a new message", { accepted: "text/plain,application/json" });
         if (send.contextId !== undefined && send.contextId !== ids.contextId)
             a2aFail("invalidParams", "message.contextId does not match the task's context", {}, "message.contextId");
         contextId = ids.contextId;
@@ -198,17 +221,21 @@ async function sendMessage(caller, params, signal) {
         sessionId = contextSessionId(caller.access.owner, caller.agentId, contextId);
         await openContext(caller, sessionId);
         const context = contextId;
+        const { body, stored } = await messageBody(caller, sessionId, idempotencyKey, send.input);
         accepted = await run(caller, sessionId, {
             type: "message",
             requestId: randomUUID(),
             idempotencyKey,
-            ...send.input,
+            ...body,
         }, async () => {
             const active = (await contextSession(caller, sessionId))?.activeTurnId;
             const taskId = active ? taskIdOf(context, active) : undefined;
             return taskId
                 ? new A2aError("unsupportedOperation", `The context has a task in progress (${taskId}); reply to it or cancel it`, { taskId })
                 : new A2aError("unsupportedOperation", "The context has unresolved work; start a new context");
+        }).catch(async (error) => {
+            await discardFiles(caller.ctx, stored, caller.access);
+            throw error;
         });
     }
     if (!send.returnImmediately)
@@ -216,6 +243,37 @@ async function sendMessage(caller, params, signal) {
     const { task } = await ownedTask(caller, taskIdOf(contextId, accepted.turnId), send.historyLength);
     return { task };
 }
+/**
+ * A new message's body: its text, its JSON value, or parts with its `raw` files stored as
+ * artifacts of the session (`stored`: the ones this call created). A file the Runtime cannot
+ * store is `InvalidParamsError`; one past a limit stays an HTTP `413`.
+ */
+async function messageBody(caller, sessionId, idempotencyKey, input) {
+    if (!("files" in input))
+        return { body: input, stored: [] };
+    let files = 0;
+    const inbound = input.files.map((part) => {
+        if ("text" in part)
+            return { type: "text", text: part.text };
+        const index = files++;
+        const mediaType = part.mediaType ?? (part.filename !== undefined ? contentTypeFor(part.filename) : "application/octet-stream");
+        return {
+            type: "inline",
+            name: part.filename ?? inlineFileName(mediaType, index),
+            mediaType,
+            data: part.raw,
+        };
+    });
+    try {
+        const { parts, stored } = await messageParts(caller.ctx, sessionId, idempotencyKey, inbound, caller.access);
+        return { body: { parts }, stored };
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 400)
+            return a2aFail("invalidParams", error.message, {}, "message.parts");
+        throw error;
+    }
+}
 /** The interaction a reply answers: the task must be active and paused on a question. */
 async function replyTarget(caller, session, sessionId, turnId, taskId) {
     if (session.activeTurnId !== turnId) {

package/dist/api/a2a/tasks.js

@@ -97,7 +97,8 @@ export function historyOf(events, contextId, taskId) {
                 add(clientMessageId(event), "ROLE_USER", [valuePart(payload.value)]);
                 break;
             case "message.assistant":
-                // Agents used as tools speak inside the turn; only the agent's own words are history.
+                // Agents used as tools speak inside the turn; only the agent's own words are history. A
+                // step that said nothing (`text: ""`, R7.1) is none.
                 if (!payload.agent && typeof payload.text === "string" && payload.text.trim() !== "")
                     add(event.eventId, "ROLE_AGENT", [{ text: payload.text }]);
                 break;

package/dist/api/ag-ui/endpoint.js

@@ -2,7 +2,9 @@ import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
 import { z } from "zod";
 import { EventSchemas, MessageSchema, RunAgentInputSchema } from "@ag-ui/core/schemas";
 import { readJson } from "../http/body.js";
-import { tenantRoute } from "../http/define.js";
+import { INLINE_BODY_MAX_BYTES } from "../inbound-files.js";
+import { TraceHeaders, tenantRoute } from "../http/define.js";
+import { traceContextOf } from "../../traces/ids.js";
 import { jsonResponse } from "../http/respond.js";
 import { agUiCaller, cancelRun, reattachRun, startRun, threadMessages } from "./routes.js";
 import { sessionIdFor } from "./session-id.js";
@@ -49,18 +51,21 @@ export function agUiRoutes(api) {
         path: "/v1/ag-ui/agents/{agentId}",
         tags: TAGS,
         summary: "Run an agent",
-        description: "For a person, named by a trusted issuer's token or by `Nylorun-Subject`. The thread is one session per person, agent and thread, created on its first run with `forwardedProps.nylorun.session`. The trailing user message starts a turn (its id is the idempotency key); `resume` answers interrupts. A busy session is a `RUN_ERROR` in the stream.",
+        description: "For a person, named by a trusted issuer's token or by `Nylorun-Subject`. The thread is one session per person, agent and thread, created on its first run with `forwardedProps.nylorun.session`. The trailing user message starts a turn (its id is the idempotency key); its media parts are files: bytes sent inline (`data`, at most 20 MiB each) are stored as artifacts of the session, a `file` source with provider `nylorun` names an artifact, and a URL is refused. `resume` answers interrupts. A busy session, or a file the model does not read, is a `RUN_ERROR` in the stream.",
         request: {
             params: agentId,
             body: {
                 required: true,
                 content: { "application/json": { schema: ref("AgUiRunAgentInput") } },
             },
+            headers: TraceHeaders,
         },
         responses: { 200: events("The run's events, from RUN_STARTED to its end") },
     }, async (c) => {
         const { scope, subject, access } = callerOf(c);
-        await startRun(c.env.tenant, scope, c.req.param("agentId"), { subject, access }, await readJson(c.req.raw), c.env.outgoing);
+        await startRun(c.env.tenant, scope, c.req.param("agentId"), { subject, access }, 
+        // A message may carry files inline.
+        await readJson(c.req.raw, INLINE_BODY_MAX_BYTES), c.env.outgoing, traceContextOf(c.req.raw.headers));
         return RESPONSE_ALREADY_SENT;
     });
     tenantRoute(api, FOR_A_PERSON, {

package/dist/api/ag-ui/history.d.ts

@@ -1,7 +1,12 @@
 /**
  * An AG-UI transcript rebuilt from a session's log, with the ids a live run gave each
- * message (see `translate.ts`), usable as `HttpAgent`'s `initialMessages`.
+ * message (see `translate.ts`), usable as `HttpAgent`'s `initialMessages`. A user message with
+ * files has array content: its text parts, and each file as a media part whose source is the
+ * artifact (`{ type: "file", provider: "nylorun", value: <artifact id> }`), typed by the media
+ * type its `artifact.created` event recorded.
  */
 import type { Message } from "@ag-ui/core";
 import { type LiveEvent } from "@nylorun/core/contracts";
+/** The `provider` of a file source that names one of the Tenant's artifacts. */
+export declare const NYLORUN_FILE_PROVIDER = "nylorun";
 export declare function messagesFromEvents(items: readonly LiveEvent[]): Message[];

package/dist/api/ag-ui/history.js

@@ -1,10 +1,44 @@
-import { parseTranscriptEvent } from "@nylorun/core/contracts";
+import { isEmptyAssistantMessage, parseTranscriptEvent, } from "@nylorun/core/contracts";
 import { outputText, toolResultOf } from "./translate.js";
+/** The `provider` of a file source that names one of the Tenant's artifacts. */
+export const NYLORUN_FILE_PROVIDER = "nylorun";
+/** A file part as an AG-UI media part, its kind from its media type when the log has it. */
+function filePart(artifactId, mediaType) {
+    const top = mediaType?.split("/")[0];
+    const type = top === "image" || top === "audio" || top === "video" ? top : "document";
+    return {
+        type,
+        source: {
+            type: "file",
+            value: artifactId,
+            provider: NYLORUN_FILE_PROVIDER,
+            ...(mediaType ? { mimeType: mediaType } : {}),
+        },
+    };
+}
+/** A message's parts (protocol 6): its text, or text and media parts when it has files. */
+function partsContent(parts, mediaTypes) {
+    if (!parts.some((part) => part.type === "file"))
+        return parts.flatMap((part) => (typeof part.text === "string" ? [part.text] : [])).join("\n");
+    return parts.flatMap((part) => part.type === "file" && typeof part.artifactId === "string"
+        ? [filePart(part.artifactId, mediaTypes.get(part.artifactId))]
+        : typeof part.text === "string"
+            ? [{ type: "text", text: part.text }]
+            : []);
+}
 export function messagesFromEvents(items) {
     const messages = [];
     const results = new Set();
+    // Each artifact's media type, from its events, for the files a message names.
+    const mediaTypes = new Map();
     let sawAssistant = false;
     for (const raw of items) {
+        if (raw.type === "artifact.created" || raw.type === "artifact.version.created") {
+            const p = (raw.payload ?? {});
+            if (typeof p.artifactId === "string" && typeof p.contentType === "string")
+                mediaTypes.set(p.artifactId, p.contentType);
+            continue;
+        }
         if (raw.type === "command.message") {
             const p = (raw.payload ?? {});
             messages.push({
@@ -14,8 +48,7 @@ export function messagesFromEvents(items) {
                 content: typeof p.content === "string"
                     ? p.content
                     : Array.isArray(p.parts)
-                        ? // A message with parts (protocol 6): its text; files are artifacts, not text.
-                            p.parts.flatMap((part) => (typeof part.text === "string" ? [part.text] : [])).join("\n")
+                        ? partsContent(p.parts, mediaTypes)
                         : JSON.stringify(p.data),
             });
             sawAssistant = false;
@@ -37,6 +70,9 @@ export function messagesFromEvents(items) {
             });
             continue;
         }
+        // A step that said nothing is in the log for its timing (R7.1), never a message.
+        if (event.type === "message.assistant" && isEmptyAssistantMessage(event.payload))
+            continue;
         if (event.type === "message.assistant" && !event.payload.agent) {
             const p = event.payload;
             sawAssistant = true;

package/dist/api/ag-ui/routes.d.ts

@@ -1,6 +1,7 @@
 import type { ServerResponse } from "node:http";
 import { type Message } from "@ag-ui/core";
 import { type AuthScope, type SessionAccess, type TenantContext } from "../../tenant/context.js";
+import type { TraceContext } from "../../traces/ids.js";
 /**
  * Who an AG-UI request acts for, once its agent is known: a person (an issuer token's subject,
  * or `Nylorun-Subject`), who may use the agent; else 400, or the 404 of a missing agent.
@@ -13,7 +14,9 @@ export declare function agUiCaller(scope: AuthScope, agentId: string): {
 export declare function startRun(ctx: TenantContext, scope: AuthScope, agentId: string, caller: {
     subject: string;
     access: SessionAccess | undefined;
-}, body: unknown, response: ServerResponse): Promise<void>;
+}, body: unknown, response: ServerResponse, 
+/** The request's trace context (R7.4): the turn the run starts joins the caller's trace. */
+trace?: TraceContext): Promise<void>;
 /** `GET …/threads/:thread/messages`: the thread's messages; none before its first run. */
 export declare function threadMessages(ctx: TenantContext, id: string, access: SessionAccess | undefined): Promise<Message[]>;
 /**