@nylorun/runtime 0.30.0-beta → 0.31.0-beta

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

@@ -2569,6 +2569,25 @@ export declare const agentManifests: import("drizzle-orm/pg-core").PgTableWithCo
         }, {}, {
             pgColumnBuilderBrand: 'PgCustomColumnBuilderBrand';
         }>;
+        source: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source";
+            tableName: "agent_manifests";
+            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';
+        }>;
     };
     dialect: 'pg';
 }>;

package/dist/store/postgres/schema.js

@@ -326,6 +326,12 @@ export const agentManifests = nylorun.table("agent_manifests", {
     /** `{ actor }`: the subject the save acted for, else `application`. */
     savedBy: jsonText().notNull(),
     createdAt: textC().notNull(),
+    /**
+     * The agent folder the version was compiled from (track T6): `{ compiler, files, bytes,
+     * entries }`, each entry `{ path, size, sha256 }` of a definition file. Null for a version
+     * saved as JSON.
+     */
+    source: jsonText(),
 }, (t) => [primaryKey({ name: "agent_manifests_pkey", columns: [t.name, t.version] })]);
 /**
  * A vault (D56): the host model's (`id = 'host'`), or one Environment's, created and deleted with

package/dist/store/postgres/store.js

@@ -295,6 +295,7 @@ function agentManifestOf(row) {
         hash: row.hash,
         savedBy: row.savedBy,
         createdAt: row.createdAt,
+        ...(row.source === null || row.source === undefined ? {} : { source: row.source }),
     };
 }
 /** A pod patch as column values: ISO times become dates, `null` clears. */

package/dist/store/types.d.ts

@@ -204,6 +204,20 @@ export interface AgentManifestRow {
         actor: string;
     };
     createdAt: string;
+    /** The agent folder the version was compiled from (track T6); none for a version saved as JSON. */
+    source?: AgentManifestSourceRecord;
+}
+/** An agent folder as a version keeps it: its compiler, size and files, each a definition file. */
+export interface AgentManifestSourceRecord {
+    compiler: string;
+    files: number;
+    bytes: number;
+    /** Sorted by path; `sha256` is lowercase hex, the file `sha256:<hex>` in the definition file store. */
+    entries: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
 }
 /** A disk lease (R2d step 3): what holds the disk, since when, and until when unless renewed. */
 export interface DiskOperation {

package/dist/tenant/agent-manifests.d.ts

@@ -1,28 +1,4 @@
-/**
- * Agent manifests (protocol 16, track T2): `/v1/agent-manifests/{name}`, named and versioned
- * documents with what runs inside an agent's loop (`harness`) and what the Runtime provides
- * around it (`runtime`). They replace agent definitions (`PUT /v1/agents/:id` before protocol
- * 16) and environment manifests.
- *
- * - **Versions.** A save whose manifest hashes the same as the latest answers it unchanged; any
- *   other writes the next version. A version is never changed or deleted alone.
- * - **Tracking Agents move.** Saving a version moves every Agent that tracks the manifest to it
- *   (track T3, `moveAgent`), in the save's transaction: at once, at its pod's next start, or once
- *   its required secrets are set. A pinned Agent stays, and so does one the version cannot move
- *   (a fixed field) or whose start failed on it. The plan counts both.
- * - **Both sections at once.** The Runtime sees both sections, so it checks them against each
- *   other (`sectionGaps`): every gap is named in one `422 manifest_inconsistent`, which is what
- *   `requires` checked when a session opened before protocol 16. Each section's own checks run
- *   too: the harness's (no code tools, no approvals, HTTP tool timeouts, the skill files) and the
- *   runtime's (the Tenant's limits, its files).
- * - **Plan and drift.** `?dryRun=true` answers what a save would do and saves nothing: the
- *   changes from the latest by section, every reason the Runtime would refuse it, warnings, the
- *   Agents it moves and how many stay on older versions. `If-Match: <version>` refuses
- *   (`412 manifest_changed`) a save whose latest version moved since the client read it; `0` asks
- *   for a manifest that does not exist yet.
- * - **Every client is equal** (Q12): a version records who saved it (`savedBy`).
- */
-import { type AgentManifestChange, type AgentManifestPlan, type AgentManifestV8, type AgentManifestVersions, type AgentManifestView, type PutAgentManifestRequest, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
+import { type AgentManifestChange, type AgentManifestPlan, type AgentManifestSource, type AgentManifestV8, type AgentManifestVersions, type AgentManifestView, type PutAgentFolderRequest, type PutAgentManifestRequest, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
 import { type RecipeRequest } from "../sandbox/resolve.js";
 import type { AuthScope, TenantContext } from "./context.js";
 /** What a manifest's runtime section asks of an Agent's recipe, with the harness its loop names. */
@@ -54,6 +30,23 @@ export declare function saveAgentManifest(ctx: TenantContext, name: string, body
     dryRun?: false;
     ifMatch?: number;
 }): Promise<SaveAgentManifestResponse>;
+/**
+ * `PUT /v1/agent-manifests/{name}` with an agent folder by hash (track T6): reads the files the
+ * compiler needs from the definition file store, compiles the folder (`422 folder_invalid` when
+ * it does not), then saves or plans the manifest as a JSON save does, keeping the folder as the
+ * version's source.
+ */
+export declare function saveAgentFolder(ctx: TenantContext, name: string, body: PutAgentFolderRequest, scope: AuthScope, options?: {
+    dryRun?: boolean;
+    ifMatch?: number;
+}): Promise<AgentManifestPlan | SaveAgentManifestResponse>;
+/** `GET /v1/agent-manifests/{name}/versions/{v}/source`: the folder a version was compiled from. */
+export declare function getAgentManifestSource(ctx: TenantContext, name: string, version: number): Promise<AgentManifestSource>;
+/** `GET .../versions/{v}/source/files/{path}`: one file of a version's source, streamed. */
+export declare function readAgentManifestSourceFile(ctx: TenantContext, name: string, version: number, path: string): Promise<{
+    body: ReadableStream<Uint8Array>;
+    size: number;
+}>;
 /** `GET /v1/agent-manifests/{name}` (the latest) and `.../versions/{n}`. */
 export declare function getAgentManifest(ctx: TenantContext, name: string, version?: number): Promise<AgentManifestView>;
 /** `GET /v1/agent-manifests`: each manifest's latest version. */

package/dist/tenant/agent-manifests.js

@@ -21,7 +21,15 @@
  *   (`412 manifest_changed`) a save whose latest version moved since the client read it; `0` asks
  *   for a manifest that does not exist yet.
  * - **Every client is equal** (Q12): a version records who saved it (`savedBy`).
+ * - **Agent folders** (track T6, D79): the same route takes a folder by hash
+ *   (`application/vnd.nylorun.folder+json`). The Runtime reads the files the compiler needs from
+ *   the definition file store, compiles them with `@nylorun/core/folder` (a folder that does not
+ *   compile is `422 folder_invalid`, every diagnostic in `details.diagnostics`), and saves the
+ *   manifest as above, with the folder kept as the version's source (`source`, its files recorded
+ *   as the version's definition files). A folder whose manifest is unchanged saves no new
+ *   version, so its source is not saved either.
  */
+import { compileAgentFolder, folderTextPaths, AGENT_FOLDER_LIMITS, } from "@nylorun/core/folder";
 import { definitionFilesOf, } from "@nylorun/core/contracts";
 import { hashManifest } from "@nylorun/core/compatibility";
 import { approvalRefusal, codeToolRefusal, harnessIdOf, loopManifestOf, runtimeOf, sectionGaps, } from "@nylorun/core/define";
@@ -35,7 +43,7 @@ import { readRuntimeLimits } from "./runtime-limits.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
 import { actorOf, fileErrors } from "./agents.js";
 import { moveAgent, planMove } from "./agent-versions.js";
-import { definitionFileIssues } from "./definition-files.js";
+import { definitionFileIssues, openDefinitionFile, readDefinitionFile } from "./definition-files.js";
 import { fail } from "./http.js";
 /** What a manifest's runtime section asks of an Agent's recipe, with the harness its loop names. */
 export function manifestRecipeRequest(manifest) {
@@ -73,6 +81,9 @@ function viewOf(row, counts) {
         savedBy: row.savedBy,
         createdAt: row.createdAt,
         agents: counts.get(row.version) ?? 0,
+        ...(row.source === undefined
+            ? {}
+            : { source: { compiler: row.source.compiler, files: row.source.files, bytes: row.source.bytes } }),
     };
 }
 /** Each field that differs between `before` and `after`, by path; arrays compare whole. */
@@ -237,6 +248,9 @@ export async function saveAgentManifest(ctx, name, body, scope, options = {}) {
     const { requestId: _, ...manifest } = body;
     if (manifest.name !== name)
         fail(400, `The manifest is named ${manifest.name}, and the path names ${name}: they must match.`);
+    return saveManifest(ctx, name, manifest, scope, options);
+}
+async function saveManifest(ctx, name, manifest, scope, options, folder) {
     const hash = agentManifestHash(manifest);
     const gaps = sectionGaps(manifest);
     return ctx.store.tx(async (t) => {
@@ -248,12 +262,33 @@ export async function saveAgentManifest(ctx, name, body, scope, options = {}) {
                 : `Agent manifest ${name} is at version ${latest.version}, not ${options.ifMatch}: someone saved it since you read it. Read it again, or save without If-Match to replace it.`, { code: "manifest_changed", details: { latest: latest?.version ?? 0 } });
         const unchanged = latest?.hash === hash;
         const to = unchanged ? latest.version : (latest?.version ?? 0) + 1;
+        // A folder whose manifest is unchanged keeps the latest version, and with it that version's source.
+        const notes = folder === undefined
+            ? undefined
+            : unchanged && canonical(latest?.source?.entries ?? null) !== canonical(folder.source.entries)
+                ? [
+                    ...folder.diagnostics,
+                    {
+                        severity: "note",
+                        code: "source_not_saved",
+                        message: "Source files changed that are not part of the agent; the manifest is unchanged, so no version is saved",
+                    },
+                ]
+                : folder.diagnostics;
         const counts = await t.agentsOfManifest(name);
         const checked = await errorsOf(t, manifest);
         // The version as it would be saved, for the plan of the Agents it moves.
         const row = unchanged
             ? latest
-            : { name, version: to, body: manifest, hash, savedBy: { actor: actorOf(scope) }, createdAt: new Date().toISOString() };
+            : {
+                name,
+                version: to,
+                body: manifest,
+                hash,
+                savedBy: { actor: actorOf(scope) },
+                createdAt: new Date().toISOString(),
+                ...(folder === undefined ? {} : { source: folder.source }),
+            };
         if (options.dryRun) {
             const errors = [...gaps, ...checked.errors];
             // A save with errors moves nothing; one that changes nothing moves no Agent either.
@@ -268,6 +303,7 @@ export async function saveAgentManifest(ctx, name, body, scope, options = {}) {
                 errors,
                 behind: moves?.behind ?? (await agentsBehind(t, name, to)).length,
                 moves: { now: moves?.now ?? 0, nextStart: moves?.nextStart ?? 0, secrets: moves?.secrets ?? 0 },
+                ...(folder === undefined ? {} : { manifest, diagnostics: [...notes], compiler: folder.compiler }),
             };
         }
         if (gaps.length > 0)
@@ -287,8 +323,9 @@ export async function saveAgentManifest(ctx, name, body, scope, options = {}) {
             });
         if (checked.errors.length > 0)
             fail(400, checked.errors.join(" "));
+        const folderNotes = notes === undefined ? {} : { diagnostics: [...notes] };
         if (unchanged)
-            return { manifest: viewOf(latest, counts), unchanged: true, warnings: warningsOf(ctx, manifest, to, undefined) };
+            return { manifest: viewOf(latest, counts), unchanged: true, warnings: warningsOf(ctx, manifest, to, undefined), ...folderNotes };
         await t.insertAgentManifest(row);
         // Its files by hash, skills' and runtime files' alike, for the sweep that deletes unused ones.
         const shas = new Set(definitionFilesOf(loopManifestOf(manifest)));
@@ -296,13 +333,108 @@ export async function saveAgentManifest(ctx, name, body, scope, options = {}) {
             if ("files" in file)
                 for (const sha of Object.values(file.files))
                     shas.add(sha);
+        // A folder's every file too: the version keeps its source.
+        for (const entry of folder?.source.entries ?? [])
+            shas.add(`sha256:${entry.sha256}`);
         if (shas.size > 0)
             await t.insertDefinitionFileUses(manifestFileOwner(name), hash, [...shas]);
         // Every Agent that tracks the manifest moves to the new version (track T3).
         const moves = await moveTracking(t, row, true);
-        return { manifest: viewOf(row, await t.agentsOfManifest(name)), unchanged: false, warnings: warningsOf(ctx, manifest, to, moves) };
+        return {
+            manifest: viewOf(row, await t.agentsOfManifest(name)),
+            unchanged: false,
+            warnings: warningsOf(ctx, manifest, to, moves),
+            ...folderNotes,
+        };
+    });
+}
+/**
+ * `PUT /v1/agent-manifests/{name}` with an agent folder by hash (track T6): reads the files the
+ * compiler needs from the definition file store, compiles the folder (`422 folder_invalid` when
+ * it does not), then saves or plans the manifest as a JSON save does, keeping the folder as the
+ * version's source.
+ */
+export async function saveAgentFolder(ctx, name, body, scope, options = {}) {
+    const entries = [...body.entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    if (entries.length > AGENT_FOLDER_LIMITS.files)
+        fail(413, `An agent folder holds at most ${AGENT_FOLDER_LIMITS.files} files; this one holds ${entries.length}`, {
+            code: "limit_exceeded",
+            details: { limit: AGENT_FOLDER_LIMITS.files },
+        });
+    // Every file must be held: the version keeps them all as its source.
+    const shas = [...new Set(entries.map((entry) => `sha256:${entry.sha256}`))].sort();
+    const held = await ctx.store.tx((t) => t.heldDefinitionFiles(shas));
+    const missing = entries.filter((entry) => !held.has(`sha256:${entry.sha256}`));
+    if (missing.length > 0)
+        fail(400, `The folder names ${missing.length} file(s) the Runtime does not hold; upload each with PUT /v1/files/sha256:<hex> first: ${missing
+            .slice(0, 20)
+            .map((entry) => entry.path)
+            .join(", ")}`, { code: "definition_files_missing", details: { missing: missing.map((entry) => `sha256:${entry.sha256}`) } });
+    for (const entry of entries)
+        if (held.get(`sha256:${entry.sha256}`) !== entry.size)
+            fail(400, `${entry.path} is listed with ${entry.size} bytes, and the Runtime holds ${held.get(`sha256:${entry.sha256}`)} for its hash`);
+    // The files the compiler reads, each at most the text file limit (it reports a larger one).
+    const files = new Map();
+    for (const path of folderTextPaths(entries)) {
+        const entry = entries.find((item) => item.path === path);
+        if (entry.size > AGENT_FOLDER_LIMITS.textFileBytes)
+            continue;
+        const bytes = await readDefinitionFile(ctx.blobs, `sha256:${entry.sha256}`);
+        if (bytes)
+            files.set(path, bytes);
+    }
+    const compiled = compileAgentFolder({ entries, files, name });
+    if (!compiled.manifest) {
+        const errors = compiled.diagnostics.filter((item) => item.severity === "error");
+        fail(422, `Agent folder ${name} does not compile: ${errors.length} error(s), the first: ${located(errors[0])}`, {
+            code: "folder_invalid",
+            details: { diagnostics: compiled.diagnostics },
+        });
+    }
+    const source = {
+        compiler: compiled.compiler,
+        files: entries.length,
+        bytes: entries.reduce((sum, entry) => sum + entry.size, 0),
+        entries: entries.map((entry) => ({ path: entry.path, size: entry.size, sha256: entry.sha256 })),
+    };
+    return saveManifest(ctx, name, compiled.manifest, scope, options, {
+        source,
+        diagnostics: compiled.diagnostics,
+        compiler: compiled.compiler,
     });
 }
+/** A diagnostic as a person reads it: `file:line:column message`. */
+function located(diagnostic) {
+    if (!diagnostic)
+        return "unknown";
+    const where = diagnostic.file
+        ? `${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}${diagnostic.column ? `:${diagnostic.column}` : ""}` : ""} `
+        : "";
+    return `${where}${diagnostic.message}`;
+}
+/** The source of version `version` of manifest `name`, or a `404` for one saved as JSON. */
+async function sourceOf(ctx, name, version) {
+    const row = (await ctx.store.tx((t) => t.agentManifest(name, version))) ?? notFound(name, version);
+    if (!row.source)
+        fail(404, `Version ${version} of agent manifest ${name} was saved as JSON: it has no source.`, { code: "not_found" });
+    return row.source;
+}
+/** `GET /v1/agent-manifests/{name}/versions/{v}/source`: the folder a version was compiled from. */
+export async function getAgentManifestSource(ctx, name, version) {
+    const source = await sourceOf(ctx, name, version);
+    return { name, version, ...source };
+}
+/** `GET .../versions/{v}/source/files/{path}`: one file of a version's source, streamed. */
+export async function readAgentManifestSourceFile(ctx, name, version, path) {
+    const source = await sourceOf(ctx, name, version);
+    const entry = source.entries.find((item) => item.path === path);
+    if (!entry)
+        fail(404, `Version ${version} of agent manifest ${name} has no file ${path}.`, { code: "not_found" });
+    const body = await openDefinitionFile(ctx.blobs, `sha256:${entry.sha256}`);
+    if (!body)
+        fail(404, `The Runtime no longer holds ${path} of version ${version} of agent manifest ${name}.`, { code: "not_found" });
+    return { body: body, size: entry.size };
+}
 /** `GET /v1/agent-manifests/{name}` (the latest) and `.../versions/{n}`. */
 export async function getAgentManifest(ctx, name, version) {
     return ctx.store.tx(async (t) => {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.30.0-beta";
+export declare const RUNTIME_VERSION = "0.31.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.30.0-beta";
+export const RUNTIME_VERSION = "0.31.0-beta";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.30.0-beta",
+  "version": "0.31.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.26.0-beta",
-    "@nylorun/harness": "0.29.2-beta",
+    "@nylorun/core": "0.27.0-beta",
+    "@nylorun/harness": "0.29.3-beta",
     "@restatedev/restate-sdk": "1.17.3",
     "@restatedev/restate-sdk-clients": "1.17.3",
     "@s2-dev/streamstore": "0.28.0",