@nylorun/runtime 0.36.1-beta → 0.38.0-beta

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

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { TurnChangesPage } from "../../components.js";
+import { taskIdOf } from "../../a2a/tasks.js";
+import { readAccess, readStoreOf } from "../../../reads/access.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+import { parseQuery } from "./reads.js";
+/** A page's size when the query names none, and the most one holds. */
+export const TURNS_PAGE_DEFAULT = 100;
+export const TURNS_PAGE_MAX = 500;
+const turnsQuery = z
+    .object({
+    changedAfter: z.string().optional().meta({
+        description: "The `cursor` a previous page returned: read the changes after it. Absent: from the first turn.",
+    }),
+    sessionId: z.string().optional().meta({ description: "Only this session's turns." }),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .meta({
+        description: `At most this many turns, up to ${TURNS_PAGE_MAX}; a larger limit gets that many. Default ${TURNS_PAGE_DEFAULT}`,
+    }),
+})
+    .strict();
+/** A turn index row as the API shows it. */
+export function turnSummary(row) {
+    const totals = row.totals;
+    return {
+        turnId: row.turnId,
+        sessionId: row.sessionId,
+        agentId: row.agentId,
+        status: row.status,
+        startedAt: row.startedAt,
+        endedAt: row.endedAt,
+        changedAt: row.changedAt,
+        totals: totals ? { steps: totals.steps, tokens: totals.tokens, costUsd: totals.costUsd } : null,
+        a2a: row.a2aContextId === null
+            ? null
+            : { contextId: row.a2aContextId, taskId: taskIdOf(row.a2aContextId, row.turnId) },
+    };
+}
+export function turnRoutes(api) {
+    tenantRoute(api, { credentials: ["application", "subject", "token"], scopes: ["sessions:own"] }, {
+        method: "get",
+        path: "/v1/turns",
+        tags: ["Sessions"],
+        summary: "Follow turns as they change",
+        description: "The turn index's change feed (Host feature `turns`): each turn's status, times, totals and A2A context and task, in the order the turns changed, a turn again each time it changes. Pass the page's `cursor` as `changedAfter` to read on; it is returned even when no turn changed. With `sessionId`, one session's turns, oldest first. An application key reads the whole Tenant; acting for a person, only theirs.",
+        request: { query: turnsQuery },
+        responses: {
+            200: {
+                description: "The turns that changed after the cursor",
+                content: { "application/json": { schema: TurnChangesPage } },
+            },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const q = parseQuery(turnsQuery, c.req.query());
+        const page = await readStoreOf(c.env.tenant).turnChanges(q.sessionId === undefined ? {} : { sessionId: q.sessionId }, {
+            limit: Math.min(q.limit ?? TURNS_PAGE_DEFAULT, TURNS_PAGE_MAX),
+            ...(q.changedAfter === undefined ? {} : { changedAfter: q.changedAfter }),
+        }, readAccess(scope));
+        return jsonResponse(200, { ...page, turns: page.turns.map(turnSummary) });
+    });
+}

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

@@ -2,7 +2,8 @@
  * 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.
+ * with file parts meets applies. AG-UI refuses a file by URL; A2A's `url` parts are fetched
+ * (`fetchUrlFile`, through `guardedFetch` within `inlineFileBytes`) and then stored the same way.
  *
  * 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
@@ -11,6 +12,7 @@
 import type { MessagePart } from "@nylorun/core/contracts";
 import { type ArtifactAccess } from "../artifacts/service.js";
 import type { TenantContext } from "../tenant/context.js";
+import { type OutboundPolicy } from "../tenant/outbound.js";
 /** A file sent inline: its name, declared media type and base64 bytes. */
 export interface InlineFile {
     readonly name: string;
@@ -30,6 +32,15 @@ export type InboundPart = {
 };
 /** The 400 for a file sent by URL. */
 export declare function refuseUrl(): never;
+/**
+ * Fetches a file sent by URL (A2A `url` parts) under `policy`, within the Tenant's Runtime limit
+ * `inlineFileBytes`, as an inline file: its media type is the part's, else the answer's. A URL
+ * the policy refuses, or that does not answer 2xx, is `400`; a file past the limit `413`.
+ */
+export declare function fetchUrlFile(ctx: TenantContext, url: string, named: {
+    mediaType?: string;
+    filename?: string;
+}, policy: OutboundPolicy): Promise<InlineFile>;
 /** 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;
 /**

package/dist/api/inbound-files.js

@@ -3,6 +3,7 @@ import { extensionFor, normalizeContentType } from "@nylorun/core/contracts";
 import { deleteArtifact, uploadArtifact } from "../artifacts/service.js";
 import { fail } from "../tenant/http.js";
 import { readRuntimeLimits } from "../tenant/runtime-limits.js";
+import { guardedFetch, OutboundFailed, OutboundRefused } from "../tenant/outbound.js";
 const BASE64 = /^[A-Za-z0-9+/_-]*={0,2}$/;
 /** The 400 for a file sent by URL. */
 export function refuseUrl() {
@@ -10,6 +11,49 @@ export function refuseUrl() {
         code: "invalid_request",
     });
 }
+/** How long fetching one file `url` part may take. */
+const URL_FETCH_TIMEOUT_MS = 60_000;
+/**
+ * Fetches a file sent by URL (A2A `url` parts) under `policy`, within the Tenant's Runtime limit
+ * `inlineFileBytes`, as an inline file: its media type is the part's, else the answer's. A URL
+ * the policy refuses, or that does not answer 2xx, is `400`; a file past the limit `413`.
+ */
+export async function fetchUrlFile(ctx, url, named, policy) {
+    const { inlineFileBytes } = await ctx.store.tx((t) => readRuntimeLimits(t));
+    let response;
+    try {
+        response = await guardedFetch(policy, { maxResponseBytes: inlineFileBytes, timeoutMs: URL_FETCH_TIMEOUT_MS })(url);
+    }
+    catch (error) {
+        if (error instanceof OutboundFailed && error.code === "TOO_LARGE")
+            return fail(413, `A file sent by URL may hold at most ${inlineFileBytes} bytes (the Runtime limit inlineFileBytes)`, {
+                code: "limit_exceeded",
+                details: { limitBytes: inlineFileBytes },
+            });
+        const reason = error instanceof OutboundRefused || error instanceof OutboundFailed ? error.message : "it did not answer";
+        return fail(400, `The file at ${new URL(url).host} could not be fetched: ${reason}`, { code: "invalid_request" });
+    }
+    if (!response.ok)
+        return fail(400, `The file at ${new URL(url).host} could not be fetched: it answered ${response.status}`, {
+            code: "invalid_request",
+        });
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const answered = response.headers.get("content-type")?.split(";")[0]?.trim();
+    const segment = new URL(url).pathname.split("/").filter(Boolean).at(-1) ?? "";
+    let last = segment;
+    try {
+        last = decodeURIComponent(segment);
+    }
+    catch {
+        // Not percent-encoding: the segment as it is.
+    }
+    const mediaType = named.mediaType ?? (answered || "application/octet-stream");
+    return {
+        name: named.filename ?? (last !== "" ? last : inlineFileName(mediaType, 0)),
+        mediaType,
+        data: bytes.toString("base64"),
+    };
+}
 /** 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);

package/dist/api/openapi.js

@@ -202,6 +202,7 @@ const RUNTIME_TAGS = [
             "GET /v1/sessions/{sessionId}/calls/tool",
             "GET /v1/sessions/{sessionId}/turns/{turnId}/trace",
             "POST /v1/sessions/{sessionId}/sandbox/{tool}",
+            "GET /v1/turns",
         ],
     },
     {
@@ -218,8 +219,12 @@ const RUNTIME_TAGS = [
     {
         name: "A2A",
         group: "Sessions",
-        description: "The same sessions through Agent2Agent: a context is one session per subject, Agent and `contextId`, and a task is one turn; every caller's session runs on the Agent's disk and vault, so an app that serves several audiences makes an Agent for each. The card is how an A2A client finds the Agent.",
-        operations: ["GET /v1/a2a/agents/{agentId}/card", "POST /v1/a2a/agents/{agentId}"],
+        description: "The same sessions through Agent2Agent (A2A 1.0, JSON-RPC) under the Nylorun profile v2: a context is one session per subject, Agent and `contextId`, and a task is one turn; every caller's session runs on the Agent's disk and vault, so an app that serves several audiences makes an Agent for each. The card is how an A2A client finds the Agent; push notifications carry a task's updates to the caller, and the files a task writes are downloaded from `/v1/a2a/files/…` by the same subject.",
+        operations: [
+            "GET /v1/a2a/agents/{agentId}/card",
+            "POST /v1/a2a/agents/{agentId}",
+            "GET /v1/a2a/files/{artifactId}/versions/{version}",
+        ],
     },
     {
         name: "Artifacts",

package/dist/harness/image-engine.d.ts

@@ -0,0 +1,14 @@
+/**
+ * An engine the workload image carries (ADR-99): the Runtime image's tini, node and bundled engine
+ * under `/opt/nylorun`, run by the sandboxes service with `entrypoint: "builtin"`. Such an engine is
+ * the Runtime version the image was built from, so it says which at `host/join`; the Runtime decides
+ * from it whether the next pod runs it or copies its own in (`sandbox/pods/builtin.ts`).
+ */
+/** Where an image keeps the engine it carries. */
+export declare const BUILTIN_ENGINE_ROOT = "/opt/nylorun";
+/** Sent at `host/join` only by an engine running from `BUILTIN_ENGINE_ROOT`: its Runtime version. */
+export declare const IMAGE_ENGINE_HEADER = "nylorun-image-engine";
+/** A Runtime version, as the header carries it. */
+export declare const ENGINE_VERSION_PATTERN: RegExp;
+/** Whether code at `moduleUrl` runs from an image's engine (the engine passes its own URL). */
+export declare function isBuiltinEngine(moduleUrl: string): boolean;

package/dist/harness/image-engine.js

@@ -0,0 +1,16 @@
+/**
+ * An engine the workload image carries (ADR-99): the Runtime image's tini, node and bundled engine
+ * under `/opt/nylorun`, run by the sandboxes service with `entrypoint: "builtin"`. Such an engine is
+ * the Runtime version the image was built from, so it says which at `host/join`; the Runtime decides
+ * from it whether the next pod runs it or copies its own in (`sandbox/pods/builtin.ts`).
+ */
+/** Where an image keeps the engine it carries. */
+export const BUILTIN_ENGINE_ROOT = "/opt/nylorun";
+/** Sent at `host/join` only by an engine running from `BUILTIN_ENGINE_ROOT`: its Runtime version. */
+export const IMAGE_ENGINE_HEADER = "nylorun-image-engine";
+/** A Runtime version, as the header carries it. */
+export const ENGINE_VERSION_PATTERN = /^[0-9A-Za-z.+-]{1,64}$/;
+/** Whether code at `moduleUrl` runs from an image's engine (the engine passes its own URL). */
+export function isBuiltinEngine(moduleUrl) {
+    return moduleUrl.startsWith(`file://${BUILTIN_ENGINE_ROOT}/`);
+}

package/dist/harness/pod.d.ts

@@ -59,4 +59,6 @@ export declare function podHost(config: PodHostConfig, logger: {
     volumeFile?: string;
     /** Where the engine writes the trust bundle: the public roots and the egress CA (R2c). */
     caBundleFile?: string;
+    /** Whether this engine runs from the workload image (default: from where its code is). */
+    imageEngine?: boolean;
 }): PodHost;

package/dist/harness/pod.js

@@ -16,6 +16,8 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { rootCertificates } from "node:tls";
 import { dirname } from "node:path";
 import { hostTuning } from "../tuning.js";
+import { RUNTIME_VERSION } from "../version.js";
+import { IMAGE_ENGINE_HEADER, isBuiltinEngine } from "./image-engine.js";
 /** The variables CLIs read their trust bundle from: OpenSSL, Node, Python, curl, git, AWS. */
 const TRUST_VARIABLES = [
     "SSL_CERT_FILE",
@@ -29,6 +31,7 @@ class Refused extends Error {
 }
 export function podHost(config, logger, options = {}) {
     const call = options.fetch ?? fetch;
+    const imageEngine = options.imageEngine ?? isBuiltinEngine(import.meta.url);
     let held;
     let setup;
     let seeded = false;
@@ -41,6 +44,8 @@ export function podHost(config, logger, options = {}) {
             headers: {
                 ...(init.body === undefined ? {} : { "content-type": "application/json" }),
                 ...(init.bearer ? { authorization: `Bearer ${init.bearer}` } : {}),
+                // An engine the workload image carries says which Runtime it came from (ADR-99).
+                ...(path === "join" && imageEngine ? { [IMAGE_ENGINE_HEADER]: RUNTIME_VERSION } : {}),
             },
             ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
             signal: AbortSignal.timeout(hostTuning().harness.podJoinTimeoutMs),

package/dist/harness-api/ws-server.js

@@ -31,6 +31,7 @@ import { HOST_TOKEN_TYP } from "../tenant/host-token.js";
 import { HostAuthError } from "../sandbox/join.js";
 import { parseSetupReport } from "../sandbox/setup.js";
 import { hostTuning } from "../tuning.js";
+import { ENGINE_VERSION_PATTERN, IMAGE_ENGINE_HEADER } from "../harness/image-engine.js";
 export { HOST_JOIN_PATH, HOST_RENEW_PATH };
 /** Where a pod's engine reads its setup and reports it (R2d step 2, `sandbox/setup.ts`). */
 export const HOST_SETUP_PATH = `${HARNESS_API_PATH}/host/setup`;
@@ -45,6 +46,11 @@ function refuse(socket, status, text, headers = {}) {
     ];
     socket.end(`${lines.join("\r\n")}\r\n\r\n`);
 }
+/** The Runtime version an engine built into the image reports at join (ADR-99), when well formed. */
+function imageEngineOf(request) {
+    const value = request.headers[IMAGE_ENGINE_HEADER];
+    return typeof value === "string" && ENGINE_VERSION_PATTERN.test(value) ? value : undefined;
+}
 function bearerOf(header) {
     return /^Bearer\s+(\S+)$/i.exec(header?.trim() ?? "")?.[1];
 }
@@ -110,7 +116,7 @@ export async function startHarnessListener(options) {
             return reply(response, 503, { error: { code: "unavailable", message: "Try again" } });
         try {
             const answer = path === HOST_JOIN_PATH
-                ? await authority.join(parseJoin(await readBody(request)))
+                ? await authority.join(parseJoin(await readBody(request)), { imageEngine: imageEngineOf(request) })
                 : await authority.renew(bearerOf(request.headers.authorization) ?? "");
             return reply(response, 200, answer);
         }

package/dist/host/config-for.d.ts

@@ -16,4 +16,6 @@ export declare function configForFactory(options: {
     issuers?: TenantConfig["issuers"];
     /** The URL clients reach the Runtime API at (`NYLORUN_PUBLIC_URL`). */
     publicUrl?: string;
+    /** The A2A server's settings (`StackConfig.a2a`). */
+    a2a?: TenantConfig["a2a"];
 }): (id: string) => TenantConfig;

package/dist/host/config-for.js

@@ -17,6 +17,7 @@ export function configForFactory(options) {
             ...(options.delivery ? { delivery: options.delivery } : {}),
             ...(options.issuers ? { issuers: options.issuers } : {}),
             ...(options.publicUrl ? { publicUrl: options.publicUrl } : {}),
+            ...(options.a2a ? { a2a: options.a2a } : {}),
             logger: {
                 info: (message, fields) => options.logger.info(message, { tenantId: id, ...fields }),
                 warn: (message, fields) => options.logger.warn(message, { tenantId: id, ...fields }),

package/dist/host/main.js

@@ -293,6 +293,7 @@ export async function main() {
         ...(stack.delivery ? { delivery: stack.delivery } : {}),
         ...(issuers ? { issuers } : {}),
         ...(stack.publicUrl ? { publicUrl: stack.publicUrl } : {}),
+        ...(stack.a2a ? { a2a: stack.a2a } : {}),
     });
     // The process's Durable Session Execution: Restate when its endpoints are set, else the
     // in-process memory execution. An invocation that arrives while the Tenant opens waits for it.

package/dist/host/stack-config.d.ts

@@ -264,6 +264,17 @@ export interface StackConfig {
         privateAddresses?: "allow" | "refuse";
         allowHttp?: boolean;
     };
+    /**
+     * The A2A server's push notifications (Runtime config `a2a`): `NYLORUN_A2A_PUSH_SECRET`
+     * (`a2a.push.secret`, `whsec_<base64>`) signs them, and `NYLORUN_A2A_PUSH_ALLOW_HOSTS`
+     * (`a2a.push.allowHosts`, comma-separated `host:port`s) names the private hosts they may reach.
+     */
+    a2a?: {
+        push?: {
+            secret?: string;
+            allowHosts?: string[];
+        };
+    };
     /** Present when the process runs core or loop: who its Tenant is on first start. */
     tenant?: TenantSettings;
     /**
@@ -348,6 +359,11 @@ export declare function normalizeAllowedHost(name: string, entry: string): strin
 export declare function isLoopbackHost(host: string): boolean;
 /** Parse the stack configuration; throws `StackConfigError` naming the variable. */
 export declare function parseStackConfig(env: EnvSnapshot, argv: readonly string[]): StackConfig;
+/**
+ * `host:port` entries, comma-separated; a host may be a name, an IPv4 or a bracketed IPv6 address,
+ * and the port `*` for any port (a test receiver on a port it picks).
+ */
+export declare function parseAllowHosts(value: string): string[];
 /** Endpoint summary for logs: which endpoints are set, never their values. */
 export declare function describeEndpoints(endpoints: StackEndpoints): string[];
 export {};

package/dist/host/stack-config.js

@@ -328,6 +328,7 @@ export function parseStackConfig(env, argv) {
     if (harnessListener && listen?.port === harnessListener.listen.port)
         throw new StackConfigError("NYLORUN_HARNESS_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT");
     const delivery = parseDelivery(env);
+    const a2a = parseA2a(env);
     const tenant = servesApi ? parseTenant(env) : undefined;
     const workloadToken = parseWorkloadToken(env);
     const modelHostIdentity = parseModelHostIdentity(env);
@@ -353,6 +354,7 @@ export function parseStackConfig(env, argv) {
         ...(harnessListener ? { harnessListener } : {}),
         ...(sandboxes ? { sandboxes } : {}),
         ...(delivery ? { delivery } : {}),
+        ...(a2a ? { a2a } : {}),
         ...(tenant ? { tenant } : {}),
         ...(workloadToken ? { workloadToken } : {}),
         ...(modelHostIdentity ? { modelHostIdentity } : {}),
@@ -714,6 +716,34 @@ function parseDelivery(env) {
         ...(http ? { allowHttp: http === "allow" } : {}),
     };
 }
+/** `StackConfig.a2a` from `NYLORUN_A2A_PUSH_*`, or `undefined` when none is set. */
+function parseA2a(env) {
+    const secret = read(env, "NYLORUN_A2A_PUSH_SECRET");
+    if (secret !== undefined) {
+        const key = secret.startsWith("whsec_") ? Buffer.from(secret.slice(6), "base64") : undefined;
+        if (!key || key.length < 24 || !/^[A-Za-z0-9+/]+={0,2}$/.test(secret.slice(6)))
+            throw new StackConfigError("NYLORUN_A2A_PUSH_SECRET must be a Standard Webhooks secret: whsec_ and the base64 of at least 24 bytes");
+    }
+    const hosts = read(env, "NYLORUN_A2A_PUSH_ALLOW_HOSTS");
+    const allowHosts = hosts === undefined ? undefined : parseAllowHosts(hosts);
+    if (secret === undefined && allowHosts === undefined)
+        return undefined;
+    return { push: { ...(secret !== undefined ? { secret } : {}), ...(allowHosts ? { allowHosts } : {}) } };
+}
+/**
+ * `host:port` entries, comma-separated; a host may be a name, an IPv4 or a bracketed IPv6 address,
+ * and the port `*` for any port (a test receiver on a port it picks).
+ */
+export function parseAllowHosts(value) {
+    const entries = value
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry !== "");
+    for (const entry of entries)
+        if (!/^(\[[0-9a-f:.]+\]|[a-z0-9.-]+):(\d{1,5}|\*)$/.test(entry) || Number(entry.slice(entry.lastIndexOf(":") + 1)) > 65535)
+            throw new StackConfigError(`NYLORUN_A2A_PUSH_ALLOW_HOSTS entries must be host:port, not ${entry}`);
+    return entries;
+}
 /** Endpoint summary for logs: which endpoints are set, never their values. */
 export function describeEndpoints(endpoints) {
     return Object.entries(endpoints)

package/dist/management-openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Management API",
-    "version": "0.36.1-beta",
+    "version": "0.38.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,
@@ -22,6 +22,7 @@
         "subject-headers",
         "ag-ui-endpoint",
         "a2a-endpoint",
+        "a2a-profile-v2",
         "sandbox-pods",
         "trusted-issuers",
         "session-reads",
@@ -37,7 +38,9 @@
         "agent-folders",
         "session-model",
         "model-host-identity",
-        "credential-provider"
+        "credential-provider",
+        "turns",
+        "agent-model"
       ]
     },
     "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`."
@@ -928,6 +931,22 @@
                     },
                     "additionalProperties": false
                   },
+                  "engine": {
+                    "type": "object",
+                    "properties": {
+                      "images": {
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 256,
+                          "pattern": "^[a-z0-9]([a-z0-9._:/-]*[a-z0-9])?$"
+                        },
+                        "maxItems": 32
+                      }
+                    },
+                    "additionalProperties": false
+                  },
                   "placement": {
                     "type": "object",
                     "additionalProperties": {
@@ -2318,6 +2337,22 @@
             },
             "additionalProperties": false
           },
+          "engine": {
+            "type": "object",
+            "properties": {
+              "images": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 256,
+                  "pattern": "^[a-z0-9]([a-z0-9._:/-]*[a-z0-9])?$"
+                },
+                "maxItems": 32
+              }
+            },
+            "additionalProperties": false
+          },
           "placement": {
             "type": "object",
             "additionalProperties": {