@nylorun/runtime 0.37.0-beta → 0.38.0-beta

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.38.0-beta
+
+### Minor Changes
+
+- 63a6217: An image can carry the Runtime's engine (ADR-99). A pod of an image the Tenant lists in
+  `engine.images` (`PUT /v1/tenant/sandbox`) runs the engine under `/opt/nylorun` with nothing copied
+  in: the sandboxes service's new `entrypoint: "builtin"`, without the `nylo-copy` init container and
+  the `/nylo` volume. Such an engine reports its Runtime version at join (header
+  `nylorun-image-engine`), the Agent's record keeps it beside its pinned image digest, and a pod runs
+  it only while it is the Runtime's own version; otherwise the engine is copied in as for any image.
+  New column `agents.engine_image` (migration 0042).
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [63a6217]
+- Updated dependencies
+  - @nylorun/core@0.33.0-beta
+  - @nylorun/harness@0.30.1-beta
+
 ## 0.37.0-beta
 
 ### Minor Changes

package/dist/api/components.d.ts

@@ -13921,6 +13921,9 @@ export declare const SeedTenantConfigRequest: z.ZodObject<{
             lifecycle: z.ZodOptional<z.ZodObject<{
                 stopGrace: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
+            engine: z.ZodOptional<z.ZodObject<{
+                images: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
             placement: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                 hosts: z.ZodArray<z.ZodEnum<{
                     "harness-container": "harness-container";
@@ -14214,6 +14217,9 @@ export declare const PutTenantEnvironmentsRequest: z.ZodObject<{
     lifecycle: z.ZodOptional<z.ZodObject<{
         stopGrace: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        images: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     placement: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         hosts: z.ZodArray<z.ZodEnum<{
             "harness-container": "harness-container";

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/management-openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Management API",
-    "version": "0.37.0-beta",
+    "version": "0.38.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,
@@ -931,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": {
@@ -2321,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": {

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Runtime API",
-    "version": "0.37.0-beta",
+    "version": "0.38.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,

package/dist/sandbox/join.d.ts

@@ -20,7 +20,13 @@ export declare class HostAuthError extends Error {
 }
 /** The Tenant's side of the exchange, as the Harness API listener calls it. */
 export interface HostAuthority {
-    join(request: HostJoinRequest): Promise<HostJoinAnswer>;
+    /**
+     * `imageEngine`: the Runtime version an engine the workload image carries reported (ADR-99);
+     * absent for an engine copied in.
+     */
+    join(request: HostJoinRequest, from?: {
+        imageEngine?: string;
+    }): Promise<HostJoinAnswer>;
     renew(hostToken: string): Promise<HostJoinAnswer>;
     /** The claims of a current host's token, for a connection; refuses a stale one. */
     verify(hostToken: string): Promise<HostClaims>;

package/dist/sandbox/join.js

@@ -85,7 +85,7 @@ export function hostAuthority(ctx) {
         return verdict.claims;
     };
     return {
-        async join(request) {
+        async join(request, from) {
             const { sandboxId, podUid, joinToken, volumeId } = request;
             if (!isAgentId(sandboxId) ||
                 typeof podUid !== "string" ||
@@ -146,6 +146,10 @@ export function hostAuthority(ctx) {
                     hostEpoch: epoch,
                     podUid,
                     ...(pod.volumeId === undefined && volumeId !== undefined ? { volumeId } : {}),
+                    // The engine the image carries, against the digest this pod runs (ADR-99).
+                    ...(from?.imageEngine === undefined
+                        ? {}
+                        : { engineImage: { version: from.imageEngine, ...(pod.imageDigest ? { digest: pod.imageDigest } : {}) } }),
                     ...(pod.desired === "running" ? { observed: "running", reason: null } : {}),
                 }, now);
                 if (pod.podUid !== podUid) {

package/dist/sandbox/pods/builtin.d.ts

@@ -0,0 +1,18 @@
+export { BUILTIN_ENGINE_ROOT, ENGINE_VERSION_PATTERN, IMAGE_ENGINE_HEADER } from "../../harness/image-engine.js";
+/** The engine an image carries, as the pod's record keeps it: its version, seen on `digest`. */
+export interface EngineImage {
+    readonly version: string;
+    readonly digest?: string;
+}
+/**
+ * Whether a pod of `image` (its pinned digest, or as asked) runs the engine the image carries:
+ * the Tenant lists its repository, and the engine recorded for that digest is this Runtime's
+ * version or not known yet.
+ */
+export declare function runsBuiltinEngine(input: {
+    readonly image: string | undefined;
+    readonly imageDigest: string | undefined;
+    readonly engineImage: EngineImage | undefined;
+    readonly listed: readonly string[] | undefined;
+    readonly runtimeVersion?: string;
+}): boolean;

package/dist/sandbox/pods/builtin.js

@@ -0,0 +1,33 @@
+/**
+ * An engine built into the workload's image (ADR-99): the Runtime image's tini, node and bundled
+ * engine under `/opt/nylorun`, which the sandboxes service runs with `entrypoint: "builtin"` and
+ * nothing copied in.
+ *
+ * The Tenant lists the images that carry one (`engine.images`, by repository). Such an engine is
+ * whichever Runtime version the image was built from, so it reports that version when it joins
+ * (`IMAGE_ENGINE_HEADER`, sent only by an engine running from `/opt/nylorun`), and the pod's
+ * record keeps it beside the digest it ran (`engineImage`). A pod runs the image's engine while
+ * that version is the Runtime's own, or not known yet for the digest it runs (a first start, which
+ * the Harness API version check at `hello` still guards); otherwise the engine is copied in, so a
+ * Runtime upgrade never leaves a pod on an older engine for more than that first turn.
+ */
+import { RUNTIME_VERSION } from "../../version.js";
+import { repositoryOf } from "./lifecycle.js";
+export { BUILTIN_ENGINE_ROOT, ENGINE_VERSION_PATTERN, IMAGE_ENGINE_HEADER } from "../../harness/image-engine.js";
+/**
+ * Whether a pod of `image` (its pinned digest, or as asked) runs the engine the image carries:
+ * the Tenant lists its repository, and the engine recorded for that digest is this Runtime's
+ * version or not known yet.
+ */
+export function runsBuiltinEngine(input) {
+    const image = input.imageDigest ?? input.image;
+    if (!image || !input.listed?.length)
+        return false;
+    const repository = repositoryOf(image);
+    if (!input.listed.some((entry) => repositoryOf(entry) === repository))
+        return false;
+    const known = input.engineImage !== undefined && input.imageDigest !== undefined && input.engineImage.digest === input.imageDigest
+        ? input.engineImage.version
+        : undefined;
+    return known === undefined || known === (input.runtimeVersion ?? RUNTIME_VERSION);
+}

package/dist/sandbox/pods/client.d.ts

@@ -5,11 +5,12 @@ export interface PodSpec {
     /** The workload image; the service defaults it to `python:3.13-slim`. */
     readonly image?: string;
     /**
-     * What the workload runs: `engine` (default), our engine copied from `harnessImage`, or
-     * `image`, the image's own entrypoint, for a custom harness built into it (R4.4).
+     * What the workload runs: `engine` (default), our engine copied from `harnessImage`;
+     * `builtin`, our engine the image carries under `/opt/nylorun` (ADR-99); or `image`, the image's
+     * own entrypoint, for a custom harness built into it (R4.4).
      */
-    readonly entrypoint?: "engine" | "image";
-    /** The Runtime image the engine is copied from; not with `entrypoint: "image"`. */
+    readonly entrypoint?: "engine" | "builtin" | "image";
+    /** The Runtime image the engine is copied from; not with `entrypoint: "builtin"` or `"image"`. */
     readonly harnessImage?: string;
     /** Replaces the engine command (diagnostics). */
     readonly command?: readonly string[];

package/dist/sandbox/pods/spec.js

@@ -8,6 +8,7 @@ import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
 import { idleMsOf, memoryMiBOf } from "../policy.js";
 import { podTuningEnv } from "../../tuning.js";
 import { opIdOf } from "./lifecycle.js";
+import { runsBuiltinEngine } from "./builtin.js";
 /** The pod's grace period to stop when the Tenant sets none (D34). */
 export const DEFAULT_STOP_GRACE_SECONDS = 10;
 /** The volume's size when the sandbox asks for none. */
@@ -40,12 +41,24 @@ export function podSpecOf(input) {
     // Pinned by digest once a pod ran it (Q14).
     const image = pod.imageDigest ?? spec.image;
     const ours = (input.harness ?? DEFAULT_HARNESS) === DEFAULT_HARNESS;
+    // Our engine, built into an image the Tenant lists, while it is this Runtime's (ADR-99).
+    const builtin = ours &&
+        runsBuiltinEngine({
+            image: spec.image,
+            imageDigest: pod.imageDigest,
+            engineImage: pod.engineImage,
+            listed: config.engine?.images,
+        });
     return {
         opId: opIdOf(pod),
         mode: input.mode,
         ...(image ? { image } : {}),
         // A custom harness is its image: the pod runs the image's entrypoint, nothing copied in.
-        ...(ours ? { harnessImage: input.harnessImage } : { entrypoint: "image" }),
+        ...(!ours
+            ? { entrypoint: "image" }
+            : builtin
+                ? { entrypoint: "builtin" }
+                : { harnessImage: input.harnessImage }),
         cpus: spec.resources?.cpus ?? 1,
         memoryMiB: memoryMiBOf(spec),
         storageGiB: storageGiBOf(spec),

package/dist/store/postgres/drizzle/0042_worker_engine_image.sql

@@ -0,0 +1 @@
+ALTER TABLE "nylorun"."agents" ADD COLUMN "engine_image" json;

package/dist/store/postgres/drizzle/meta/_journal.json

@@ -295,6 +295,13 @@
       "when": 1793448353003,
       "tag": "0041_turn_index_backfill",
       "breakpoints": true
+    },
+    {
+      "idx": 42,
+      "version": "7",
+      "when": 1793509192153,
+      "tag": "0042_worker_engine_image",
+      "breakpoints": true
     }
   ]
 }

package/dist/store/postgres/schema.d.ts

@@ -1302,6 +1302,25 @@ export declare const agents: import("drizzle-orm/pg-core").PgTableWithColumns<{
         }, {}, {
             pgColumnBuilderBrand: 'PgCustomColumnBuilderBrand';
         }>;
+        engineImage: import("drizzle-orm/pg-core").PgColumn<{
+            name: "engineImage";
+            tableName: "agents";
+            dataType: "custom";
+            columnType: "PgCustomColumn";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            pgColumnBuilderBrand: 'PgCustomColumnBuilderBrand';
+        }>;
         diskOp: import("drizzle-orm/pg-core").PgColumn<{
             name: "diskOp";
             tableName: "agents";

package/dist/store/postgres/schema.js

@@ -171,6 +171,8 @@ export const agents = nylorun.table("agents", {
     volumeId: text(),
     /** The workload image by digest, from the first ready pod on (Q14): later pods run it. */
     imageDigest: textC(),
+    /** The engine the image carries (ADR-99): `{ version, digest? }`, from a join of its engine. */
+    engineImage: jsonText(),
     /**
      * The disk lease (R2d step 3): `{ kind, version?, startedAt, until }` while a snapshot, a
      * restore or a seed copies the disk; turns are refused until it ends or `until` passes.

package/dist/store/postgres/store.js

@@ -283,6 +283,7 @@ function environmentOf(row) {
                     ...(row.retiring !== null ? { retiring: row.retiring } : {}),
                     ...(row.volumeId !== null ? { volumeId: row.volumeId } : {}),
                     ...(row.imageDigest !== null ? { imageDigest: row.imageDigest } : {}),
+                    ...(row.engineImage ? { engineImage: row.engineImage } : {}),
                 },
             }
             : {}),
@@ -317,6 +318,7 @@ function podColumns(patch) {
         retiring: patch.retiring,
         volumeId: patch.volumeId,
         imageDigest: patch.imageDigest,
+        engineImage: patch.engineImage,
     };
     return Object.fromEntries(Object.entries(columns).filter(([, value]) => value !== undefined));
 }

package/dist/store/types.d.ts

@@ -260,6 +260,15 @@ export interface SandboxPodState {
      * Environment is ready (Q14): every later pod, after a stop, a relaunch or a reset, runs it.
      */
     imageDigest?: string;
+    /**
+     * The engine the workload image carries (ADR-99, `sandbox/pods/builtin.ts`): its Runtime
+     * version, as its engine reported at join, and the digest that pod ran. It counts only while
+     * that digest is `imageDigest`.
+     */
+    engineImage?: {
+        version: string;
+        digest?: string;
+    };
 }
 /** A change to a pod's columns: `null` clears an optional one. */
 export type SandboxPodPatch = {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.37.0-beta";
+export declare const RUNTIME_VERSION = "0.38.0-beta";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in step with package.json by runtime/server/scripts/check-package.mjs, which runs in npm run check.
 // release:prepare also rewrites this when it bumps @nylorun/runtime.
-export const RUNTIME_VERSION = "0.37.0-beta";
+export const RUNTIME_VERSION = "0.38.0-beta";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.37.0-beta",
+  "version": "0.38.0-beta",
   "description": "Nylorun Runtime: the agent execution Host on Postgres, Restate and S2, and model providers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -65,8 +65,8 @@
     "@hono/node-server": "^2.1.5",
     "@hono/zod-openapi": "^1.6.3",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@nylorun/core": "0.32.0-beta",
-    "@nylorun/harness": "0.30.0-beta",
+    "@nylorun/core": "0.33.0-beta",
+    "@nylorun/harness": "0.30.1-beta",
     "@restatedev/restate-sdk": "1.17.3",
     "@restatedev/restate-sdk-clients": "1.17.3",
     "@s2-dev/streamstore": "0.28.0",