nylorun 0.24.0-beta → 0.25.0-beta

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # nylorun
 
+## 0.25.0-beta
+
+### Minor Changes
+
+- 67ed2ea: `nylorun check --explain` prints each engine feature the agent and its subagents get, on or off,
+  with what declares it and the tools and text blocks it adds (`explain` in `--json`). `nylorun
+migrate folder <dir> --to 2` makes an agent folder `agent-folder/2` in place, writing the
+  `engine:` declarations that keep what it gets today, after checking that no agent's system text
+  or tool list changes (ADR-100).
+- 67ed2ea: Secret routing: the agent folder names, the installation routes (Host feature `secret-routing`, no
+  protocol change). A `bearer` or `headers` secret slot (`runtime.json`, `runtime.secrets`) takes the
+  gateway's `toolPrefix`, with or without `via`, and a slot's value write
+  (`PUT /v1/agents/{id}/secrets/{name}` with `{ value }` or `{ headers }`) takes `via`, with the same
+  URL rules as a slot's. At each request the secret's `via` wins, else the slot's in the version the
+  Agent runs, else none (the slot's `url`); the slot's `toolPrefix` wins over the secret's and
+  applies only with a `via`; the slot's `url` still picks the credential, for MCP servers and HTTP
+  tools alike, and an HTTP tool whose URL has `{field}` parameters still fails behind a `via`. A
+  write whose `toolPrefix` differs from its slot's is accepted, with a warning in the log. A `via` a
+  write copied from its slot follows the slot when the Agent moves, and a fork keeps a secret's own
+  `via`. Secret views show the `via` and `toolPrefix` in force, never a value.
+  `client.agents.secrets.put` takes `{ value | headers, via?, toolPrefix? }` (`AgentSecretRouting`),
+  and `nylorun agents secrets put` takes `--via` and `--tool-prefix`, and a slot's JSON without a
+  `type`. The JSON Schemas that gained the slot's `toolPrefix` are published as
+  `agent-manifest/v8.2`, `runtime-manifest/v1.1` and `agent-folder/v1/runtime.1`, which `nylorun init`
+  maps; the old `$schema` URLs are still read.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin agents to the tested release.
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies [67ed2ea]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.34.0-beta
+  - @nylorun/agents@0.32.0-beta
+  - @nylorun/admin@0.19.10-beta
+
+## 0.24.1-beta
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin agents to the tested release.
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [63a6217]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.33.0-beta
+  - @nylorun/agents@0.31.1-beta
+  - @nylorun/admin@0.19.9-beta
+
 ## 0.24.0-beta
 
 ### Minor Changes

package/README.md

@@ -54,11 +54,12 @@ nylorun doctor sandbox [--tenant <name>] [--json]   # the sandbox backend the Te
 # apply, agent-manifests, agents, sessions, artifacts: the Runtime API (an application key, or NYLORUN_TOKEN)
 # every one takes --tenant <name>, and --as <subject> [--scope <scope>]... to act for a person
 nylorun init <path> [--description <text>] [--example]   # write <path>/AGENT.md, a new agent folder named after the last segment
-nylorun check [<dir>...] [--fix] [--json]  # compile each agent folder offline: every problem by file, line and column; --fix makes the fixable ones' edits
+nylorun check [<dir>...] [--fix] [--explain] [--json]  # compile each agent folder offline: every problem by file, line and column; --fix makes the fixable ones' edits; --explain prints each engine feature on, and what it adds
 nylorun apply [<dir>...] [--dry-run] [--if-match <n>] [--agent [<id>]] [--watch [--save]]   # plan, then save each folder (AGENT.md or agent.manifest.json), its files uploaded
 nylorun chat <agent> [--session <id>] [--message <text>]   # send each line (or --message), print each reply
 nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]   # the three files from a v7 manifest; reads no Runtime
 nylorun migrate folder <dir> [--out <dir>]   # the agent folder of a three-file folder; reads no Runtime
+nylorun migrate folder <dir> --to 2   # make an agent folder agent-folder/2, declaring what it gets today
 nylorun export --folder <name>[@<n>] [--out <dir>]   # the agent folder of a saved manifest (JSON or TypeScript)
 nylorun pull <name>[@<n>] [--out <dir>]   # the folder a version was saved from, byte for byte
 nylorun agent-manifests list [--json]       # name, latest version, runtime kind, harness, Agents
@@ -288,7 +289,11 @@ secret of that Agent's vault, a `bearer` token or a `headers` map, with `via` an
 an identity header when an MCP gateway holds each person's sign-in. Write it with
 `nylorun agents secrets put <id> <name>` (a slot's value on standard input) or
 `nylorun agents secrets put <id> <name> <secret.json|->` (the secret's JSON
-comes from a file or standard input, never the command line),
+comes from a file or standard input, never the command line; for a slot, only
+`{ "value": … }` or `{ "headers": { … } }`), with `--via <url>` and
+`--tool-prefix <prefix>` for this installation's routing of a `bearer` or
+`headers` secret (Host feature `secret-routing`: the write's `via` wins over the
+slot's, the slot's tool prefix over the write's),
 `client.agents.secrets.put(id, name, secret)` of `@nylorun/agents` (the
 Runtime API, an application key) or in Studio.
 The whole flow, with gateway recipes, is in
@@ -564,6 +569,40 @@ from `mcp.json`) and saves it, uploading its files by hash; the Runtime keeps th
 folder as the version's source. `--dry-run` also prints the compiled manifest. A
 change only to a file outside the agent, such as a README, is `unchanged`.
 
+**What the engine adds (`agent-folder/2`, ADR-100).** An `agent-folder/1` folder (no `format`,
+the default) gets every engine feature by default: with a computer in `runtime.json`, the six
+sandbox tools, `save_artifact` and the outputs folder; always `read_artifact`; and its MCP tools
+deferred behind `tool_search` past a share of the context window. A folder with
+`format: agent-folder/2` gets only what it declares. Memory, skills, `loop` and
+`runtime.selfWake` declare their parts as before; `engine:` declares the rest:
+
+<!-- doc-test: folder declared AGENT.md -->
+```markdown
+---
+name: declared
+description: Answers from the docs it is given.
+format: agent-folder/2
+memory:
+  index: false
+engine:
+  artifacts: { read: true }
+  toolSearch: false
+---
+Answer from the documents in the conversation.
+```
+
+`engine.sandbox` lists any of `bash`, `read`, `write`, `edit`, `grep` and `glob`;
+`artifacts.save`, `outputs` and `sandbox` need a computer; and `engine.instructions.<block>`
+replaces a text block's wording with a Markdown file under `engine/` (the blocks are `skills`,
+`sandbox`, `skill_folder`, `artifacts_save`, `outputs`, `artifacts_read`, `wake`, `memory`,
+`plan`, `connection` and `tool_search`; memory's rule that outside text is data stays). A
+subagent declares its own `engine:`, a subset of its parent's. The compiled manifest lists the
+blocks the agent gets, with their versions and hashes (`harness.engine.blocks`).
+`nylorun check --explain` prints each feature on, and the tools and blocks it adds;
+`previewTurn(manifest)` in `@nylorun/agents` returns the exact system text and tool list.
+`nylorun migrate folder <dir> --to 2` writes the declarations that keep what an `agent-folder/1`
+folder gets, so nothing changes until you remove a line.
+
 The loop from an empty folder to an answer:
 
 ```

package/dist/cli.js

@@ -17,9 +17,11 @@ Agent manifests:
                                       write <path>/AGENT.md, a new agent folder named after the
                                       path's last segment; --example adds a tool, mcp.json and a
                                       trigger
-  check [<dir>...] [--fix] [--json]   compile each agent folder offline and print every problem
+  check [<dir>...] [--fix] [--explain] [--json]
+                                      compile each agent folder offline and print every problem
                                       by file, line and column (reads no Runtime); --fix makes
-                                      the edits the fixable ones name
+                                      the edits the fixable ones name; --explain prints each
+                                      engine feature on, and the tools and text it adds
   apply [<dir>...] [--dry-run] [--if-match <n>] [--agent [<id>]] [--watch [--save]]
                                       save the agent manifest each folder describes (its AGENT.md,
                                       or its agent.manifest.json), with its files (Runtime API);
@@ -32,6 +34,8 @@ Agent manifests:
                                       and an environment manifest v1 (reads no Runtime)
   migrate folder <dir> [--out <dir>]  write the agent folder of a three-file folder
                                       (agent.manifest.json; reads no Runtime)
+  migrate folder <dir> --to 2         make an agent folder agent-folder/2, declaring every
+                                      engine feature it gets today, so nothing it gets changes
   export --folder <name>[@<version>] [--out <dir>]
                                       write the agent folder of a saved manifest (Runtime API)
   pull <name>[@<version>] [--out <dir>]

package/dist/client/agents.js

@@ -45,8 +45,12 @@ NYLORUN_TOKEN).
   secrets put <id> <name>             the value of a slot its manifest declares, piped in
                                       on standard input
   secrets put <id> <name> <secret.json|->
-                                      create or replace a secret: {"type": "bearer", ...}, read
-                                      from a file or standard input
+                                      create or replace a secret: {"type": "bearer", ...}, or a
+                                      slot's {"headers": {...}} or {"value": ...}, read from a file
+                                      or standard input
+      [--via <url>] [--tool-prefix <prefix>]
+                                      a bearer or headers secret's routing: where its requests
+                                      go (over the slot's via) and the gateway's tool prefix
   secrets rm <id> <name>
   triggers list <id>                  its triggers: status, next and last run, as JSON
   triggers pause|resume <id> <trigger>
@@ -313,23 +317,28 @@ async function secrets(deps, args) {
         return 0;
     }
     if (verb === "put") {
-        const usage = "nylorun agents secrets put <id> <name> [<secret.json|->]";
-        const flags = parseFlags(rest, {}, usage);
+        const usage = "nylorun agents secrets put <id> <name> [<secret.json|->] [--via <url>] [--tool-prefix <prefix>]";
+        const flags = parseFlags(rest, { values: ["--via", "--tool-prefix"] }, usage);
         if (flags.rest.length < 2 || flags.rest.length > 3)
             throw usageError(`Usage: ${usage}`);
         const [id, name, path] = flags.rest;
+        // This installation's routing of a bearer or headers secret (`secret-routing`).
+        const via = flags.values.get("--via");
+        const toolPrefix = flags.values.get("--tool-prefix");
+        const routing = { ...(via === undefined ? {} : { via }), ...(toolPrefix === undefined ? {} : { toolPrefix }) };
         if (path === undefined) {
             // A slot its manifest declares (D64): the value only, piped in; the binding is the slot's.
             const value = await readSecret(deps, `value of ${name}`, `printf %s "$TOKEN" | nylorun agents secrets put ${id} ${name}`);
             const { client } = await runtimeClient(deps, flags);
-            printJson(deps, await runtimeCall(() => client.agents.secrets.put(id, name, { value })));
+            printJson(deps, await runtimeCall(() => client.agents.secrets.put(id, name, { value, ...routing })));
             return 0;
         }
         const secret = await readJson(path, "The secret");
-        if (typeof secret.type !== "string")
-            throw usageError('The secret needs a "type".');
+        // Without a type, a slot's value: { "value": … } or { "headers": { … } }, with via and toolPrefix.
+        if (typeof secret.type !== "string" && secret.value === undefined && secret.headers === undefined)
+            throw usageError('The secret needs a "type", or is a slot\'s "value" or "headers".');
         const { client } = await runtimeClient(deps, flags);
-        printJson(deps, await runtimeCall(() => client.agents.secrets.put(id, name, secret)));
+        printJson(deps, await runtimeCall(() => client.agents.secrets.put(id, name, { ...secret, ...routing })));
         return 0;
     }
     if (verb === "rm" || verb === "delete") {

package/dist/client/folder.d.ts

@@ -1,13 +1,16 @@
 import { type PackedFolder } from "@nylorun/agents";
 import { type AgentFolderDiagnostic } from "@nylorun/core/folder";
+import { type ExplainedAgent } from "@nylorun/core/engine";
 import { type StackDeps } from "../stack/commands.js";
 export { initCommand, initUsage } from "./init.js";
-export declare const checkUsage = "nylorun check [<dir>...] [--fix] [--json]\n\nCompiles each agent folder (default .) offline, with the compiler the Runtime runs, and prints\nevery problem by file, line and column. A folder holds AGENT.md; a folder without one checks each\nsubfolder that has one. Exits 1 when a folder does not compile. Reads no Runtime.\n\nA problem one edit fixes says (fixable with --fix): an unknown key with one did-you-mean, CRLF\nline ends, and secrets in a SKILL.md, which go in AGENT.md's skills block.\n\n  --fix                               make those edits in the folder's files, print each, then\n                                      check again; nothing is written without it, and a file\n                                      that changed since it was checked is left as it is\n  --json                              print { \"folders\": [{ path, ok, manifest?, diagnostics }] }\n                                      for CI: whether each folder compiles, the manifest it\n                                      compiles to, and every diagnostic, each fixable one with\n                                      its fix; with --fix, also what was fixed and what was not";
+export declare const checkUsage = "nylorun check [<dir>...] [--fix] [--explain] [--json]\n\nCompiles each agent folder (default .) offline, with the compiler the Runtime runs, and prints\nevery problem by file, line and column. A folder holds AGENT.md; a folder without one checks each\nsubfolder that has one. Exits 1 when a folder does not compile. Reads no Runtime.\n\nA problem one edit fixes says (fixable with --fix): an unknown key with one did-you-mean, CRLF\nline ends, and secrets in a SKILL.md, which go in AGENT.md's skills block.\n\n  --fix                               make those edits in the folder's files, print each, then\n                                      check again; nothing is written without it, and a file\n                                      that changed since it was checked is left as it is\n  --explain                           print each engine feature the agent and its subagents get\n                                      (agent-folder/2 declares them; agent-folder/1 gets them all\n                                      by default), with the tools and text blocks each adds\n  --json                              print { \"folders\": [{ path, ok, manifest?, diagnostics }] }\n                                      for CI: whether each folder compiles, the manifest it\n                                      compiles to, and every diagnostic, each fixable one with\n                                      its fix; with --fix, also what was fixed and what was not;\n                                      with --explain, the features as explain";
 /** The agent folders under `dir`: `dir` when it holds an `AGENT.md`, else each subfolder that does. */
 export declare function agentFolders(dir: string): Promise<string[]>;
 /** Packs the folder, or a `CliError` naming why it cannot be. */
 export declare function packed(folder: string): Promise<PackedFolder>;
 /** A folder's diagnostics as lines, each path relative to `cwd`; `fixable` marks those with a fix. */
 export declare function diagnosticLines(folder: string, cwd: string, diagnostics: readonly AgentFolderDiagnostic[], fixable?: boolean): string[];
+/** `check --explain`'s lines for one folder: each agent, then each feature, on or off. */
+export declare function explainLines(agents: readonly ExplainedAgent[]): string[];
 /** `nylorun check [dir…] [--fix] [--json]` */
 export declare function checkCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/folder.js

@@ -10,11 +10,12 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join, relative, resolve } from "node:path";
 import { AGENT_FOLDER_FILE, FolderError, checkFolder, diagnosticLine, isAgentFolder, packFolder, } from "@nylorun/agents";
 import { applyFolderFixes } from "@nylorun/core/folder";
+import { explainEngine } from "@nylorun/core/engine";
 import { CliError } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { usageError } from "./runtime.js";
 export { initCommand, initUsage } from "./init.js";
-export const checkUsage = `nylorun check [<dir>...] [--fix] [--json]
+export const checkUsage = `nylorun check [<dir>...] [--fix] [--explain] [--json]
 
 Compiles each agent folder (default .) offline, with the compiler the Runtime runs, and prints
 every problem by file, line and column. A folder holds AGENT.md; a folder without one checks each
@@ -26,10 +27,14 @@ line ends, and secrets in a SKILL.md, which go in AGENT.md's skills block.
   --fix                               make those edits in the folder's files, print each, then
                                       check again; nothing is written without it, and a file
                                       that changed since it was checked is left as it is
+  --explain                           print each engine feature the agent and its subagents get
+                                      (agent-folder/2 declares them; agent-folder/1 gets them all
+                                      by default), with the tools and text blocks each adds
   --json                              print { "folders": [{ path, ok, manifest?, diagnostics }] }
                                       for CI: whether each folder compiles, the manifest it
                                       compiles to, and every diagnostic, each fixable one with
-                                      its fix; with --fix, also what was fixed and what was not`;
+                                      its fix; with --fix, also what was fixed and what was not;
+                                      with --explain, the features as explain`;
 /** The agent folders under `dir`: `dir` when it holds an `AGENT.md`, else each subfolder that does. */
 export async function agentFolders(dir) {
     const root = resolve(dir);
@@ -107,11 +112,28 @@ async function fixFolder(pack, diagnostics, cwd) {
         await writeFile(target, after);
     return { fixed: result.changes, unfixed };
 }
+/** `check --explain`'s lines for one folder: each agent, then each feature, on or off. */
+export function explainLines(agents) {
+    const lines = [];
+    for (const agent of agents) {
+        lines.push(`  ${agent.agent}: ${agent.declared ? "declares its engine features (agent-folder/2)" : "every engine feature by default (agent-folder/1)"}`);
+        for (const item of agent.features) {
+            const adds = [
+                ...(item.tools.length > 0 ? [`tools ${item.tools.join(", ")}`] : []),
+                ...(item.blocks.length > 0 ? [`text ${item.blocks.join(", ")}`] : []),
+                ...(item.note === undefined ? [] : [item.note]),
+            ];
+            lines.push(`    ${item.on ? "on " : "off"} ${item.feature} (${item.declaredBy})${item.on && adds.length > 0 ? `: ${adds.join("; ")}` : item.note && item.feature === "toolSearch" ? `: ${item.note}` : ""}`);
+        }
+    }
+    return lines;
+}
 /** `nylorun check [dir…] [--fix] [--json]` */
 export async function checkCommand(deps, args) {
-    const flags = parseStackFlags(args, { booleans: ["--json", "--fix"] }, checkUsage);
+    const flags = parseStackFlags(args, { booleans: ["--json", "--fix", "--explain"] }, checkUsage);
     const json = flags.booleans.has("--json");
     const fix = flags.booleans.has("--fix");
+    const explain = flags.booleans.has("--explain");
     const cwd = deps.cwd ?? process.cwd();
     const folders = [];
     for (const dir of flags.rest.length > 0 ? flags.rest : ["."]) {
@@ -146,6 +168,7 @@ export async function checkCommand(deps, args) {
                 ...(compiled.manifest ? { manifest: compiled.manifest } : {}),
                 diagnostics: compiled.diagnostics,
                 ...(pack.skipped.length > 0 ? { skipped: pack.skipped } : {}),
+                ...(explain && compiled.manifest ? { explain: explainEngine(compiled.manifest) } : {}),
                 ...(fix ? { fixed: fixed.fixed, unfixed: fixed.unfixed } : {}),
             });
             continue;
@@ -164,8 +187,12 @@ export async function checkCommand(deps, args) {
                 deps.err(line);
         const label = relative(cwd, folder) || basename(folder);
         const files = `${pack.entries.length} ${pack.entries.length === 1 ? "file" : "files"}`;
-        if (compiled.manifest)
+        if (compiled.manifest) {
             deps.out(`${label}: ok, agent manifest ${compiled.manifest.name} (${files}, ${compiled.compiler})`);
+            if (explain)
+                for (const line of explainLines(explainEngine(compiled.manifest)))
+                    deps.out(line);
+        }
         else {
             const errors = compiled.diagnostics.filter((item) => item.severity === "error").length;
             deps.err(`${label}: ${errors} ${errors === 1 ? "error" : "errors"}`);

package/dist/client/init.js

@@ -49,7 +49,7 @@ export function schemaMappings(root, folder) {
     // Folders under a parent (agents/) share one pattern; a folder at the root is named alone.
     const base = parent === "" ? relative(root, folder).split(sep).join("/") : `${parent}/**`;
     return [
-        { fileMatch: [`${base}/runtime.json`], url: `${SCHEMA_BASE}/runtime.json` },
+        { fileMatch: [`${base}/runtime.json`], url: `${SCHEMA_BASE}/runtime.1.json` },
         { fileMatch: [`${base}/tools/*.json`], url: `${SCHEMA_BASE}/tool.json` },
         { fileMatch: [`${base}/flow.json`], url: `${SCHEMA_BASE}/flow.json` },
         { fileMatch: [`${base}/mcp.json`, `!${base}/plugins/**`], url: `${SCHEMA_BASE}/mcp.json` },

package/dist/client/migrate-format.d.ts

@@ -0,0 +1,12 @@
+import type { StackDeps } from "../stack/commands.js";
+export declare const migrateFormatUsage = "nylorun migrate folder <dir> --to 2\n\nMakes the agent folder <dir> agent-folder/2, in place: it adds format: agent-folder/2 to its\nAGENT.md, and to it and each subagent's AGENT.md the engine: block that declares every engine\nfeature the folder gets today by default (the sandbox tools, save_artifact and the outputs folder\nwhen runtime.json has a computer, read_artifact, tool search). Nothing the model reads or may\ncall changes, which it checks before it writes; then remove the lines the agent does not need.\nReads no Runtime.";
+/** The `engine:` block that keeps what an agent-folder/1 agent gets, as YAML lines. */
+export declare function engineLines(computer: boolean): string[];
+/**
+ * `text`, an `AGENT.md`, with `lines` added at the end of its frontmatter and, when `format` is
+ * set, its `format:` line replaced by `format: <format>` (first in the frontmatter when it had
+ * none). Undefined when it has no frontmatter.
+ */
+export declare function withFrontmatter(text: string, lines: readonly string[], format?: string): string | undefined;
+/** `nylorun migrate folder <dir> --to 2` */
+export declare function migrateFormatCommand(deps: StackDeps, dir: string, to: string): Promise<number>;

package/dist/client/migrate-format.js

@@ -0,0 +1,141 @@
+/**
+ * `nylorun migrate folder <dir> --to 2` (ADR-100): makes an `agent-folder/1` folder an
+ * `agent-folder/2` one, in place, declaring every engine feature it gets today by default, so no
+ * prompt and no tool changes until the author removes a line:
+ *
+ * - `format: agent-folder/2`;
+ * - `engine:` in `AGENT.md` and in each `agents/<id>/AGENT.md`: the six sandbox tools,
+ *   `save_artifact` and the outputs folder when the runtime has a computer, `read_artifact`
+ *   always, and tool search.
+ *
+ * It checks the folder before and after, offline, with the compiler the Runtime runs, and that
+ * every agent's system text and tool list are the same (`previewTurn`), and writes nothing when
+ * they are not. Reads no Runtime.
+ */
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { AGENT_FOLDER_FILE, checkFolder } from "@nylorun/agents";
+import { SANDBOX_TOOL_NAMES } from "@nylorun/core/define";
+import { previewTurn } from "@nylorun/core/engine";
+import { CliError } from "../errors.js";
+import { diagnosticLines, packed } from "./folder.js";
+import { usageError } from "./runtime.js";
+export const migrateFormatUsage = `nylorun migrate folder <dir> --to 2
+
+Makes the agent folder <dir> agent-folder/2, in place: it adds format: agent-folder/2 to its
+AGENT.md, and to it and each subagent's AGENT.md the engine: block that declares every engine
+feature the folder gets today by default (the sandbox tools, save_artifact and the outputs folder
+when runtime.json has a computer, read_artifact, tool search). Nothing the model reads or may
+call changes, which it checks before it writes; then remove the lines the agent does not need.
+Reads no Runtime.`;
+/** The `engine:` block that keeps what an agent-folder/1 agent gets, as YAML lines. */
+export function engineLines(computer) {
+    return computer
+        ? [
+            "engine:",
+            `  sandbox: [${SANDBOX_TOOL_NAMES.join(", ")}]`,
+            "  artifacts: { read: true, save: true }",
+            "  outputs: true",
+            "  toolSearch: true",
+        ]
+        : ["engine:", "  artifacts: { read: true, save: false }", "  toolSearch: true"];
+}
+/**
+ * `text`, an `AGENT.md`, with `lines` added at the end of its frontmatter and, when `format` is
+ * set, its `format:` line replaced by `format: <format>` (first in the frontmatter when it had
+ * none). Undefined when it has no frontmatter.
+ */
+export function withFrontmatter(text, lines, format) {
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const bom = text.startsWith("") ? "" : "";
+    const all = text.slice(bom.length).split(/\r?\n/);
+    if (all[0]?.trimEnd() !== "---")
+        return undefined;
+    const end = all.findIndex((line, index) => index > 0 && line.trimEnd() === "---");
+    if (end < 0)
+        return undefined;
+    let front = all.slice(1, end);
+    if (format !== undefined) {
+        const at = front.findIndex((line) => /^format\s*:/.test(line));
+        if (at >= 0)
+            front[at] = `format: ${format}`;
+        else
+            front = [`format: ${format}`, ...front];
+    }
+    return bom + ["---", ...front, ...lines, ...all.slice(end)].join(eol);
+}
+/** What each agent of a compiled folder reads and may call, by agent, for a comparison. */
+function seen(manifest) {
+    if ("kind" in manifest.harness)
+        return "";
+    const preview = previewTurn(manifest);
+    const one = (item) => ({ system: item.system, tools: item.tools });
+    return JSON.stringify({ root: one(preview), pinned: preview.pinned, agents: Object.fromEntries(Object.entries(preview.agents).map(([id, item]) => [id, one(item)])) });
+}
+/** `nylorun migrate folder <dir> --to 2` */
+export async function migrateFormatCommand(deps, dir, to) {
+    if (to !== "2" && to !== "agent-folder/2")
+        throw usageError(`--to takes 2 (agent-folder/2).\n${migrateFormatUsage}`);
+    const cwd = deps.cwd ?? process.cwd();
+    const where = relative(cwd, dir) || ".";
+    const before = await checkFolder(await packed(dir));
+    if (!before.manifest) {
+        for (const line of diagnosticLines(dir, cwd, before.diagnostics))
+            deps.err(line);
+        throw new CliError(`${where} does not compile: fix it first (nylorun check ${where}).`, 1);
+    }
+    if (before.compiler === "agent-folder/2") {
+        deps.out(`${where} is agent-folder/2 already: nothing to do.`);
+        return 0;
+    }
+    const harness = before.manifest.harness;
+    if ("kind" in harness)
+        throw new CliError(`${where} is a flow: migrate each agent folder it holds instead.`, 1);
+    const kind = before.manifest.runtime?.kind ?? "none";
+    const computer = kind === "virtual" || kind === "pod";
+    // The root, then each subagent (`agents/<id>/`), each with the declarations it gets today.
+    const edits = new Map();
+    const read = async (path) => readFile(join(dir, ...path.split("/")), "utf8");
+    const root = withFrontmatter(await read(AGENT_FOLDER_FILE), engineLines(computer), "agent-folder/2");
+    if (root === undefined)
+        throw new CliError(`${join(where, AGENT_FOLDER_FILE)} has no frontmatter.`, 1);
+    edits.set(AGENT_FOLDER_FILE, root);
+    for (const tool of harness.tools ?? []) {
+        if (!tool.agent)
+            continue;
+        const path = `agents/${tool.name}/${AGENT_FOLDER_FILE}`;
+        const edited = withFrontmatter(await read(path), engineLines(computer));
+        if (edited === undefined)
+            throw new CliError(`${join(where, path)} has no frontmatter.`, 1);
+        edits.set(path, edited);
+    }
+    // The folder as it would be, compiled and compared before anything is written.
+    const pack = await packed(dir);
+    const encoder = new TextEncoder();
+    const files = new Map(pack.files);
+    const entries = pack.entries.map((entry) => {
+        const text = edits.get(entry.path);
+        if (text === undefined)
+            return entry;
+        const bytes = encoder.encode(text);
+        const source = files.get(entry.path);
+        files.set(entry.path, { ...source, size: bytes.byteLength, read: async () => bytes });
+        return { ...entry, size: bytes.byteLength, sha256: sha256Hex(bytes) };
+    });
+    const after = await checkFolder({ ...pack, entries, files });
+    if (!after.manifest) {
+        for (const line of diagnosticLines(dir, cwd, after.diagnostics))
+            deps.err(line);
+        throw new CliError(`${where} would not compile as agent-folder/2: nothing was written.`, 1);
+    }
+    if (seen(after.manifest) !== seen(before.manifest))
+        throw new CliError(`${where} as agent-folder/2 would change what its model reads or may call: nothing was written.`, 1);
+    for (const [path, text] of edits)
+        await writeFile(join(dir, ...path.split("/")), text);
+    for (const path of edits.keys())
+        deps.out(`wrote ${join(where, path)}`);
+    deps.out(`${where} is agent-folder/2, and its agents get what they got before. Remove the engine features they do not use, and see what each adds with nylorun check --explain ${where}.`);
+    return 0;
+}
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");

package/dist/client/migrate.js

@@ -26,6 +26,8 @@ import { harnessSectionOf, sectionGaps } from "@nylorun/core/define";
 import { CliError } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { migrateFolderCommand, migrateFolderUsage } from "./convert.js";
+import { migrateFormatCommand, migrateFormatUsage } from "./migrate-format.js";
+import { isHelp } from "../errors.js";
 import { readJson, usageError } from "./runtime.js";
 export const migrateUsage = `nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]
 
@@ -69,11 +71,24 @@ function hasSkills(loop) {
 export async function migrateCommand(deps, args) {
     const [version, ...rest] = args;
     if (version === "--help" || version === "-h") {
-        deps.out(`${migrateUsage}\n\n${migrateFolderUsage}`);
+        deps.out(`${migrateUsage}\n\n${migrateFolderUsage}\n\n${migrateFormatUsage}`);
         return 0;
     }
-    if (version === "folder")
-        return migrateFolderCommand(deps, rest);
+    if (version === "folder") {
+        // `--to 2`: an agent folder made agent-folder/2 in place (ADR-100).
+        const to = rest.indexOf("--to");
+        if (to < 0)
+            return migrateFolderCommand(deps, rest);
+        const value = rest[to + 1];
+        const others = rest.filter((_, index) => index !== to && index !== to + 1);
+        if (others.some(isHelp)) {
+            deps.out(migrateFormatUsage);
+            return 0;
+        }
+        if (value === undefined || value.startsWith("-") || others.length !== 1 || others[0].startsWith("-"))
+            throw usageError(`Usage: ${migrateFormatUsage.split("\n")[0]}`);
+        return migrateFormatCommand(deps, resolve(deps.cwd ?? process.cwd(), others[0]), value);
+    }
     if (version !== "v8")
         throw usageError(version === undefined ? migrateUsage : `nylorun migrate knows v8 and folder only.\n${migrateUsage}\n\n${migrateFolderUsage}`);
     const flags = parseStackFlags(rest, { values: ["--runtime", "--name", "--out"] }, migrateUsage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.24.0-beta",
+  "version": "0.25.0-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run local Nylorun Tenants (Runtime and Studio) with Docker Compose, and act on a Tenant through its Runtime and Management APIs",
@@ -30,9 +30,9 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/admin": "0.19.8-beta",
-    "@nylorun/agents": "0.31.0-beta",
-    "@nylorun/core": "0.32.0-beta"
+    "@nylorun/admin": "0.19.10-beta",
+    "@nylorun/agents": "0.32.0-beta",
+    "@nylorun/core": "0.34.0-beta"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
@@ -46,7 +46,7 @@
     "nylo": "dist/nylo.js"
   },
   "nylorun": {
-    "runtime": "0.37.0-beta",
-    "studio": "0.35.0-beta"
+    "runtime": "0.39.0-beta",
+    "studio": "0.35.2-beta"
   }
 }