nylorun 0.18.3-beta → 0.20.0-beta

package/dist/client/apply.js

@@ -5,27 +5,47 @@
  * files they name and checks the harness file's `requires`. Each manifest is planned first
  * (a dry run: from → to, each change, warnings, errors), and saved under `If-Match` set to the
  * version the plan was made against, so a save that raced another fails (`412 manifest_changed`)
- * instead of overwriting it. A folder without an `agent.manifest.json` applies each subfolder
- * that has one (`nylorun apply agents/`).
+ * instead of overwriting it. A folder with neither an `AGENT.md` nor an `agent.manifest.json`
+ * applies each subfolder that has one (`nylorun apply agents/`).
+ *
+ * An agent folder (a folder with `AGENT.md`, track T6) is compiled offline first, and one that does
+ * not compile sends nothing; otherwise its files go up by hash and the Runtime compiles it again
+ * and keeps it as the version's source. Its plan adds the compiler's notes, and `--dry-run` prints
+ * the compiled manifest.
+ *
+ * Track T7: a plan's change to the instructions prints their text diff (`plan-diff.ts`);
+ * `--agent [<id>]` makes or moves the Agent after a save (`apply-agent.ts`); `--watch` checks and
+ * plans again on each change, saving only with `--save` (`watch.ts`).
  */
 import { resolve } from "node:path";
-import { ComposeError, PluginError, SkillsError, composeManifest, manifestFolders, } from "@nylorun/agents";
+import { ComposeError, PluginError, SkillsError, checkFolder, composeManifest, isAgentFolder, manifestFolders, } from "@nylorun/agents";
 import { CliError } from "../errors.js";
+import { putAgent, takeAgentFlag } from "./apply-agent.js";
+import { agentFolders, diagnosticLines, packed } from "./folder.js";
+import { changeDiffLines } from "./plan-diff.js";
 import { integerFlag, parseFlags, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError } from "./runtime.js";
-export const applyUsage = `nylorun apply [<dir>...] [--dry-run] [--if-match <n>]
+export const applyUsage = `nylorun apply [<dir>...] [--dry-run] [--if-match <n>] [--agent [<id>]] [--watch [--save]]
 
 Saves the agent manifest each folder describes (default .), through the Runtime API with an
-application key (or NYLORUN_TOKEN). A folder holds agent.manifest.json, which names its
-harness.manifest.json and runtime.manifest.json (paths relative to the file that names them);
-a folder without one applies each subfolder that has one.
+application key (or NYLORUN_TOKEN). An agent folder holds AGENT.md (nylorun init): it is checked
+offline as nylorun check does, sent by hash, and kept as the version's source. A folder may hold
+agent.manifest.json instead, which names its harness.manifest.json and runtime.manifest.json
+(paths relative to the file that names them). A folder with neither applies each subfolder that
+has one.
 
 Each manifest is planned first: the version it moves from and to, each change (section, path,
 op), warnings and errors. With no errors it is saved, its skills', plugins' and runtime files
 uploaded first, under If-Match set to the version planned against (0 for a new manifest).
 Errors, the gaps between its sections included, save nothing and exit 1.
 
-  --dry-run                           print the plans and save nothing
+  --dry-run                           print the plans, and an agent folder's compiled manifest, and
+                                      save nothing
   --if-match <n>                      save only over version n (one folder)
+  --agent [<id>]                      then make the Agent <id> (default the manifest's name) from
+                                      the manifest, or move it to the version saved, as nylorun
+                                      agents put does; --agent=<id> when <id> names a directory
+  --watch                             check and plan again on each change to the folders, until
+                                      interrupted; with --save, also save each change
 
 ${runtimeFlagsUsage}`;
 /** What a folder could not be composed for, as a person reads it. */
@@ -43,55 +63,129 @@ export function planLines(plan) {
             : `version ${plan.from} → ${plan.to}`;
     return [
         `${plan.name}: ${move}${plan.behind > 0 ? ` (${plan.behind} ${plan.behind === 1 ? "Agent" : "Agents"} on older versions)` : ""}`,
-        ...plan.changes.map((change) => `  ${change.section} ${change.path} ${change.op}`),
+        ...plan.changes.flatMap((change) => [`  ${change.section} ${change.path} ${change.op}`, ...changeDiffLines(change)]),
         ...plan.warnings.map((warning) => `  warning: ${warning.message}`),
         ...plan.errors.map((error) => `  error: ${error}`),
     ];
 }
-/** `nylorun apply [dir…] [--dry-run] [--if-match <n>]` */
-export async function applyCommand(deps, args) {
-    if (args[0] === "--help" || args[0] === "-h") {
+function reportSaved(deps, saved, label) {
+    deps.err(saved.unchanged
+        ? `Agent manifest ${saved.manifest.name} is unchanged at version ${saved.manifest.version} on ${label}.`
+        : `Saved agent manifest ${saved.manifest.name} version ${saved.manifest.version} on ${label}.`);
+    for (const warning of saved.warnings)
+        deps.err(`  warning: ${warning.message}`);
+}
+/** `nylorun apply [dir…] [--dry-run] [--if-match <n>] [--agent [<id>]] [--watch [--save]]` */
+export async function applyCommand(deps, given, options = {}) {
+    if (given[0] === "--help" || given[0] === "-h") {
         deps.out(applyUsage);
         return 0;
     }
-    const usage = "nylorun apply [<dir>...] [--dry-run] [--if-match <n>]";
-    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--if-match"] }, usage);
-    const ifMatch = integerFlag(flags, "--if-match");
+    const usage = "nylorun apply [<dir>...] [--dry-run] [--if-match <n>] [--agent [<id>]] [--watch [--save]]";
     const cwd = deps.cwd ?? process.cwd();
+    const { args, agent } = takeAgentFlag(given, cwd);
+    const flags = parseFlags(args, { booleans: ["--dry-run", "--watch", "--save"], values: ["--if-match"] }, usage);
+    if (flags.booleans.has("--save") && !flags.booleans.has("--watch"))
+        throw usageError("--save goes with --watch: apply saves anyway.");
+    if (flags.booleans.has("--watch")) {
+        if (flags.booleans.has("--dry-run"))
+            throw usageError("--watch saves nothing unless --save: drop --dry-run.");
+        const { watchApply } = await import("./watch.js");
+        return watchApply(deps, {
+            dirs: flags.rest,
+            args: given.filter((arg) => arg !== "--watch" && arg !== "--save"),
+            save: flags.booleans.has("--save"),
+        });
+    }
+    const ifMatch = integerFlag(flags, "--if-match");
     const folders = [];
     for (const dir of flags.rest.length > 0 ? flags.rest : ["."]) {
-        const found = await manifestFolders(resolve(cwd, dir)).catch((error) => composeFailure(dir, error));
+        const at = resolve(cwd, dir);
+        const found = (await isAgentFolder(at))
+            ? [at]
+            : [
+                ...new Set([
+                    ...(await manifestFolders(at).catch((error) => composeFailure(dir, error))),
+                    ...(await agentFolders(at)),
+                ]),
+            ].sort();
         if (found.length === 0)
-            throw usageError(`${dir} holds no agent.manifest.json, and no subfolder does.`);
+            throw usageError(`${dir} holds no AGENT.md or agent.manifest.json, and no subfolder does.`);
         folders.push(...found);
     }
     if (ifMatch !== undefined && folders.length > 1)
         throw usageError("--if-match takes one manifest: name one folder.");
-    // Every folder composes before anything is sent: a broken file stops the whole apply.
-    const composed = [];
-    for (const folder of folders)
-        composed.push({ folder, manifest: await composeManifest(folder).catch((error) => composeFailure(folder, error)) });
-    const { client, connection } = await runtimeClient(deps, flags);
+    if (agent?.id !== undefined && folders.length > 1)
+        throw usageError("--agent <id> takes one manifest: name one folder, or drop the id.");
+    // Every folder composes, or compiles, before anything is sent: a broken file stops the whole apply.
+    const work = [];
     let blocked = false;
-    for (const { manifest } of composed) {
+    for (const folder of folders) {
+        if (await isAgentFolder(folder)) {
+            const pack = await packed(folder);
+            const compiled = await checkFolder(pack);
+            if (!compiled.manifest) {
+                if (!options.checked)
+                    for (const line of diagnosticLines(folder, cwd, compiled.diagnostics))
+                        deps.err(line);
+                blocked = true;
+            }
+            work.push({ folder, pack });
+        }
+        else
+            work.push({ folder, manifest: await composeManifest(folder).catch((error) => composeFailure(folder, error)) });
+    }
+    if (blocked) {
+        deps.err("Nothing was sent: an agent folder does not compile (nylorun check).");
+        return 1;
+    }
+    const { client, connection } = await runtimeClient(deps, flags);
+    const dryRun = flags.booleans.has("--dry-run") || options.planOnly === true;
+    // `--agent`: make or move the Agent once its manifest is saved, or found unchanged.
+    const agentFor = async (name) => {
+        if (agent && !dryRun)
+            await putAgent(deps, client, connection.label, agent.id ?? name, name);
+    };
+    for (const item of work) {
+        const saveOptions = ifMatch === undefined ? {} : { ifMatch };
+        if ("pack" in item) {
+            const plan = await runtimeCall(() => client.agentManifests.planFolder(item.pack, saveOptions));
+            for (const line of planLines(plan))
+                deps.out(line);
+            if (!options.checked)
+                for (const line of diagnosticLines(item.folder, cwd, (plan.diagnostics ?? []).filter((d) => d.severity !== "error")))
+                    deps.out(`  ${line}`);
+            if (flags.booleans.has("--dry-run") && plan.manifest)
+                deps.out(JSON.stringify(plan.manifest, null, 2));
+            if (plan.errors.length > 0) {
+                blocked = true;
+                continue;
+            }
+            if (dryRun)
+                continue;
+            if (!plan.unchanged)
+                reportSaved(deps, await runtimeCall(() => client.agentManifests.saveFolder(item.pack, { ifMatch: ifMatch ?? plan.from ?? 0 })), connection.label);
+            await agentFor(plan.name);
+            continue;
+        }
+        const { manifest } = item;
         for (const warning of manifest.warnings)
             deps.err(`${manifest.manifest.name}: warning: ${warning}`);
         // The plan's errors include the gaps the composer found (its sections, the harness's requires).
-        const plan = await runtimeCall(() => client.agentManifests.plan(manifest, ifMatch === undefined ? {} : { ifMatch }));
+        const plan = await runtimeCall(() => client.agentManifests.plan(manifest, saveOptions));
         for (const line of planLines(plan))
             deps.out(line);
         if (plan.errors.length > 0) {
             blocked = true;
             continue;
         }
-        if (flags.booleans.has("--dry-run") || plan.unchanged)
+        if (dryRun)
             continue;
-        const saved = await runtimeCall(() => client.agentManifests.save(manifest, { ifMatch: ifMatch ?? plan.from ?? 0 }));
-        deps.err(saved.unchanged
-            ? `Agent manifest ${saved.manifest.name} is unchanged at version ${saved.manifest.version} on ${connection.label}.`
-            : `Saved agent manifest ${saved.manifest.name} version ${saved.manifest.version} on ${connection.label}.`);
-        for (const warning of saved.warnings)
-            deps.err(`  warning: ${warning.message}`);
+        if (!plan.unchanged) {
+            const saved = await runtimeCall(() => client.agentManifests.save(manifest, { ifMatch: ifMatch ?? plan.from ?? 0 }));
+            reportSaved(deps, saved, connection.label);
+        }
+        await agentFor(plan.name);
     }
     if (blocked)
         deps.err("Nothing was saved for a manifest with errors.");

package/dist/client/chat.d.ts

@@ -0,0 +1,8 @@
+import type { StackDeps } from "../stack/commands.js";
+export declare const chatUsage: string;
+/** Where `chat` reads its messages when `--message` is not given. */
+export interface ChatIo {
+    lines?: AsyncIterable<string>;
+}
+/** `nylorun chat <agent> [--session <id>] [--message <text>] [--owner <user>]` */
+export declare function chatCommand(deps: StackDeps, args: readonly string[], io?: ChatIo): Promise<number>;

package/dist/client/chat.js

@@ -0,0 +1,145 @@
+/**
+ * `nylorun chat <agent> [--session <id>] [--message <text>]` (track T7): a conversation with an
+ * Agent from the terminal. It opens a session on the Agent (or reuses `--session`, opening it
+ * with that id when it does not exist), sends `--message` once or each line of standard input,
+ * and prints the assistant's text as each model step lands, until the turn ends. A turn that
+ * waits for a person (an approval, a question) prints how to answer it with `nylorun sessions`.
+ * Exits 1 when a turn fails or is cancelled.
+ */
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { RuntimeError } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { parseFlags, positional, runtimeCall, runtimeClient, runtimeFlagsUsage } from "./runtime.js";
+export const chatUsage = `nylorun chat <agent> [--session <id>] [--message <text>] [--owner <user>]
+
+Talks to Agent <agent> (nylorun apply <dir> --agent makes one): sends --message once, or each
+line of standard input, and prints the reply as it comes. A new session is opened unless
+--session names one, which is opened with that id when it does not exist.
+
+  --session <id>                      the session to use, kept across runs
+  --message <text>                    send this one message, print the reply, and exit
+  --owner <user>                      the session's owner (default the Agent's owner, else --as,
+                                      else $USER)
+
+${runtimeFlagsUsage}`;
+const errorStatus = (error) => (error instanceof RuntimeError ? error.status : undefined);
+/** Sends `text` and prints the turn it starts as it streams; false when the turn failed. */
+async function converse(deps, session, text) {
+    const accepted = await runtimeCall(() => session.input(text, { idempotencyKey: randomUUID() }));
+    // A message to a busy session waits in its queue; its turn starts when `queue.taken` names it.
+    let turnId = accepted.status === "accepted" ? accepted.turnId : null;
+    const queued = accepted.status === "queued" ? accepted.queuedMessageId : undefined;
+    if (queued)
+        deps.err(`(queued at position ${accepted.status === "queued" ? accepted.position : 0}: a turn is running)`);
+    const controller = new AbortController();
+    let ok = true;
+    let spoke = false;
+    try {
+        await runtimeCall(async () => {
+            for await (const event of session.observe({
+                signal: controller.signal,
+                ...(accepted.cursor ? { cursor: accepted.cursor } : {}),
+            })) {
+                const payload = (event.payload ?? {});
+                if (event.type === "queue.taken" && queued && Array.isArray(payload.queuedMessageIds) && payload.queuedMessageIds.includes(queued))
+                    turnId = String(payload.turnId);
+                if (turnId === null || event.turnId !== turnId)
+                    continue;
+                if (event.type === "message.assistant") {
+                    if (typeof payload.text === "string" && payload.text.trim() !== "") {
+                        deps.out(payload.text.replace(/\n+$/, ""));
+                        spoke = true;
+                    }
+                    for (const call of Array.isArray(payload.toolCalls) ? payload.toolCalls : [])
+                        deps.err(`[${call.name}]`);
+                    continue;
+                }
+                if (event.type === "turn.completed") {
+                    // A turn whose answer is structured output said no text: print the output.
+                    if (!spoke && payload.output !== undefined && payload.output !== null)
+                        deps.out(typeof payload.output === "string" ? payload.output : JSON.stringify(payload.output, null, 2));
+                    break;
+                }
+                if (event.type === "turn.failed" || event.type === "turn.cancelled") {
+                    const why = payload.error?.message ?? payload.message ?? payload.reason;
+                    deps.err(`The turn ${event.type === "turn.failed" ? "failed" : "was cancelled"}${why ? `: ${why}` : ""}.`);
+                    ok = false;
+                    break;
+                }
+                if (event.type === "turn.paused") {
+                    for (const item of Array.isArray(payload.interactions) ? payload.interactions : []) {
+                        const id = item?.interaction?.id;
+                        const kind = item?.interaction?.kind;
+                        deps.err(kind === "approval"
+                            ? `The turn waits for an approval: nylorun sessions approve ${session.id} ${id} [--deny]`
+                            : `The turn waits for an answer (${kind}): nylorun sessions respond ${session.id} ${id} <json>`);
+                    }
+                    break;
+                }
+            }
+        });
+    }
+    finally {
+        controller.abort();
+    }
+    return ok;
+}
+/** The session to talk in: `--session`, opened when missing, or a new one. */
+async function sessionFor(deps, client, agentId, sessionId, owner) {
+    if (sessionId !== undefined) {
+        try {
+            await client.session(sessionId).inspect();
+            return client.session(sessionId);
+        }
+        catch (error) {
+            if (errorStatus(error) !== 404)
+                await runtimeCall(() => Promise.reject(error));
+        }
+    }
+    const id = sessionId ?? `chat-${randomUUID()}`;
+    const session = await runtimeCall(() => client.createSession({ agent: agentId, ownerUserId: owner, id }));
+    if (sessionId === undefined)
+        deps.err(`Session ${id} on Agent ${agentId} (continue it with --session ${id}).`);
+    return session;
+}
+/** Standard input's lines. */
+async function* stdinLines() {
+    const lines = createInterface({ input: process.stdin, ...(process.stdin.isTTY ? { output: process.stderr, prompt: "> " } : {}) });
+    if (process.stdin.isTTY)
+        lines.prompt();
+    for await (const line of lines) {
+        yield line;
+        if (process.stdin.isTTY)
+            lines.prompt();
+    }
+}
+/** `nylorun chat <agent> [--session <id>] [--message <text>] [--owner <user>]` */
+export async function chatCommand(deps, args, io = {}) {
+    const usage = "nylorun chat <agent> [--session <id>] [--message <text>] [--owner <user>]";
+    if (args[0] === "--help" || args[0] === "-h") {
+        deps.out(chatUsage);
+        return 0;
+    }
+    const flags = parseFlags(args, { values: ["--session", "--message", "--owner"] }, usage);
+    const [agentId] = positional(flags, 1, usage);
+    const message = flags.values.get("--message");
+    const { client } = await runtimeClient(deps, flags);
+    const agent = await client.agents.get(agentId).catch((error) => {
+        if (errorStatus(error) === 404)
+            throw new CliError(`No Agent ${agentId}: make one with nylorun apply <dir> --agent ${agentId}.`, 1);
+        return runtimeCall(() => Promise.reject(error));
+    });
+    const owner = flags.values.get("--owner") ?? agent.owner ?? flags.values.get("--as") ?? deps.env.USER ?? deps.env.USERNAME ?? "nylorun-cli";
+    const session = await sessionFor(deps, client, agentId, flags.values.get("--session"), owner);
+    if (message !== undefined)
+        return (await converse(deps, session, message)) ? 0 : 1;
+    let failed = false;
+    for await (const line of io.lines ?? stdinLines()) {
+        if (line.trim() === "")
+            continue;
+        if (!(await converse(deps, session, line)))
+            failed = true;
+    }
+    return failed ? 1 : 0;
+}

package/dist/client/convert.d.ts

@@ -0,0 +1,18 @@
+import { type StackDeps } from "../stack/commands.js";
+export declare const exportUsage: string;
+export declare const migrateFolderUsage = "nylorun migrate folder <dir> [--out <dir>]\n\nWrites the agent folder of the three-file folder <dir> (agent.manifest.json, with its\nharness.manifest.json and runtime.manifest.json), offline: the manifest nylorun apply composes\nfrom it, as AGENT.md, mcp.json, tools/, skills/ and runtime.json. A SKILL.md's secrets move to\nAGENT.md. It says whether the folder compiles to the same manifest. Reads no Runtime.\n\n  --out <dir>                         where the folder goes (default ./<name>); no file is\n                                      written over";
+export declare const pullUsage: string;
+/**
+ * Writes `files` under `out`. A file already there with the same bytes is left; one with other
+ * bytes is a conflict, and with any conflict nothing is written. Answers how many it wrote and left.
+ */
+export declare function writeFolder(out: string, files: ReadonlyMap<string, Uint8Array | string>, cwd: string): Promise<{
+    written: number;
+    same: number;
+}>;
+/** `nylorun export --folder <name>[@<version>] [--out <dir>]` */
+export declare function exportCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
+/** `nylorun migrate folder <dir> [--out <dir>]` */
+export declare function migrateFolderCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
+/** `nylorun pull <name>[@<version>] [--out <dir>]` */
+export declare function pullCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/convert.js

@@ -0,0 +1,195 @@
+/**
+ * Converting to agent folders (track T7, D80):
+ *
+ * - `nylorun export --folder <name>[@<version>]` writes the agent folder of a saved manifest, from
+ *   JSON or TypeScript (`folderOfManifest`, `@nylorun/core/folder`), read with the Runtime API.
+ * - `nylorun migrate folder <dir>` does the same, offline, for a three-file folder
+ *   (`agent.manifest.json`), composed as `nylorun apply` composes it, with its skills' bytes.
+ * - `nylorun pull <name>[@<version>]` writes back the folder a version was saved from, byte for
+ *   byte, from the version's source (`agentManifests.source` and `sourceFile`).
+ *
+ * None writes over a file whose bytes differ: a file that is already there with the same bytes
+ * is left as it is, and a conflict writes nothing.
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { AGENT_MANIFEST_FILE, ComposeError, PluginError, RuntimeError, SkillsError, composeManifest, } from "@nylorun/agents";
+import { isAgentManifestName } from "@nylorun/core/contracts";
+import { folderOfManifest } from "@nylorun/core/folder";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { parseFlags, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError } from "./runtime.js";
+export const exportUsage = `nylorun export --folder <name>[@<version>] [--out <dir>]
+
+Writes the agent folder of a saved agent manifest (its latest version, or <version>), for one
+saved as JSON or from TypeScript: AGENT.md with its instructions, instructions/, tools/, mcp.json,
+triggers/ and runtime.json, subagents as agents/<name>/, and a flow as flow.json with its agents
+under agents/. It says whether the folder compiles back to the same manifest, and notes what it
+cannot write the same way. Skills' files are not in a saved manifest: see the notes.
+
+  --folder                            write an agent folder (the only export there is)
+  --out <dir>                         where the folder goes (default ./<name>); no file is
+                                      written over
+
+${runtimeFlagsUsage}`;
+export const migrateFolderUsage = `nylorun migrate folder <dir> [--out <dir>]
+
+Writes the agent folder of the three-file folder <dir> (agent.manifest.json, with its
+harness.manifest.json and runtime.manifest.json), offline: the manifest nylorun apply composes
+from it, as AGENT.md, mcp.json, tools/, skills/ and runtime.json. A SKILL.md's secrets move to
+AGENT.md. It says whether the folder compiles to the same manifest. Reads no Runtime.
+
+  --out <dir>                         where the folder goes (default ./<name>); no file is
+                                      written over`;
+export const pullUsage = `nylorun pull <name>[@<version>] [--out <dir>]
+
+Writes the agent folder a version of manifest <name> (default its latest) was saved from, byte
+for byte, as the Runtime keeps it. A version saved as JSON has none: nylorun export --folder
+writes one from its manifest.
+
+  --out <dir>                         where the folder goes (default ./<name>); a file with the
+                                      same bytes is left, and no file is written over
+
+${runtimeFlagsUsage}`;
+/** `name` or `name@version`. */
+function nameAndVersion(ref, usage) {
+    const at = ref.lastIndexOf("@");
+    const name = at < 0 ? ref : ref.slice(0, at);
+    const version = at < 0 ? undefined : ref.slice(at + 1);
+    if (!isAgentManifestName(name))
+        throw usageError(`${name} is not an agent manifest's name.\nUsage: ${usage.split("\n")[0]}`);
+    if (version !== undefined && !/^[1-9]\d{0,8}$/.test(version))
+        throw usageError(`${ref}: the version after @ is a whole number from 1.\nUsage: ${usage.split("\n")[0]}`);
+    return version === undefined ? { name } : { name, version: Number(version) };
+}
+const sameBytes = (a, b) => a.byteLength === b.byteLength && a.every((byte, index) => byte === b[index]);
+/**
+ * Writes `files` under `out`. A file already there with the same bytes is left; one with other
+ * bytes is a conflict, and with any conflict nothing is written. Answers how many it wrote and left.
+ */
+export async function writeFolder(out, files, cwd) {
+    const encoder = new TextEncoder();
+    const plan = [];
+    const conflicts = [];
+    let same = 0;
+    for (const [path, content] of files) {
+        const target = resolve(out, path);
+        if (!target.startsWith(`${out}${sep}`))
+            throw new CliError(`${path} would be written outside ${relative(cwd, out) || "."}: nothing was written.`, 1);
+        const bytes = typeof content === "string" ? encoder.encode(content) : content;
+        if (existsSync(target)) {
+            if (sameBytes(new Uint8Array(await readFile(target)), bytes))
+                same++;
+            else
+                conflicts.push(relative(cwd, target));
+            continue;
+        }
+        plan.push([target, bytes]);
+    }
+    if (conflicts.length > 0)
+        throw new CliError(`${conflicts.length === 1 ? `${conflicts[0]} exists` : `These files exist: ${conflicts.join(", ")}`} with other bytes: nothing was written. Pass another --out, or move ${conflicts.length === 1 ? "it" : "them"} first.`, 1);
+    for (const [target, bytes] of plan) {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes, { flag: "wx" });
+    }
+    return { written: plan.length, same };
+}
+/** "Wrote 3 files to triage" and, when some were there already, how many. */
+function wroteLine(where, result) {
+    const files = (count) => `${count} ${count === 1 ? "file" : "files"}`;
+    return `Wrote ${files(result.written)} to ${where}${result.same > 0 ? ` (${files(result.same)} already there, the same)` : ""}.`;
+}
+/** The folder written, then what differs from the manifest, then the next step. */
+async function writeDecompiled(deps, folder, out, cwd) {
+    const where = relative(cwd, out) || ".";
+    deps.out(wroteLine(where, await writeFolder(out, folder.files, cwd)));
+    for (const note of folder.notes)
+        deps.err(`  note: ${note}`);
+    deps.err(folder.exact
+        ? `It compiles back to the same manifest. Check it with nylorun check ${where}, and save it with nylorun apply ${where}.`
+        : `It compiles to a different manifest: see the notes, then check it with nylorun check ${where}.`);
+    return 0;
+}
+/** `nylorun export --folder <name>[@<version>] [--out <dir>]` */
+export async function exportCommand(deps, args) {
+    const usage = exportUsage.split("\n")[0];
+    const flags = parseFlags(args, { booleans: ["--folder"], values: ["--out"] }, exportUsage);
+    if (!flags.booleans.has("--folder"))
+        throw usageError(`nylorun export writes an agent folder: pass --folder.\nUsage: ${usage}`);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const { name, version } = nameAndVersion(flags.rest[0], exportUsage);
+    const cwd = deps.cwd ?? process.cwd();
+    const { client } = await runtimeClient(deps, flags);
+    const view = await runtimeCall(() => client.agentManifests.get(name, version));
+    if (view.source)
+        deps.err(`${name}@${view.version} was saved from a folder: nylorun pull ${name}@${view.version} writes it as it was saved.`);
+    const out = resolve(cwd, flags.values.get("--out") ?? name);
+    return writeDecompiled(deps, folderOfManifest(view.manifest), out, cwd);
+}
+/** What a three-file folder could not be composed for, as a person reads it. */
+function composeFailure(dir, error) {
+    if (error instanceof ComposeError || error instanceof SkillsError || error instanceof PluginError || error instanceof TypeError)
+        throw new CliError(`${dir}: ${error.message}`, 1);
+    throw error;
+}
+/** `nylorun migrate folder <dir> [--out <dir>]` */
+export async function migrateFolderCommand(deps, args) {
+    const flags = parseStackFlags(args, { values: ["--out"] }, migrateFolderUsage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${migrateFolderUsage.split("\n")[0]}`);
+    const cwd = deps.cwd ?? process.cwd();
+    const dir = resolve(cwd, flags.rest[0]);
+    if (!existsSync(join(dir, AGENT_MANIFEST_FILE)))
+        throw usageError(`${flags.rest[0]} holds no ${AGENT_MANIFEST_FILE}.`);
+    const composed = await composeManifest(dir).catch((error) => composeFailure(flags.rest[0], error));
+    const out = resolve(cwd, flags.values.get("--out") ?? composed.manifest.name);
+    if (out === dir)
+        throw usageError(`The folder would be written over the three files in ${relative(cwd, dir) || "."}: pass --out.`);
+    // The bytes behind the manifest's hashes, so its skills and runtime files are written as files.
+    const bytes = new Map();
+    for (const [hash, source] of composed.files)
+        bytes.set(hash, await source.read());
+    // This command is what the deprecation warning names.
+    for (const warning of composed.warnings.filter((item) => !item.includes("nylorun migrate folder")))
+        deps.err(`  warning: ${warning}`);
+    for (const gap of composed.gaps)
+        deps.err(`  fix before apply: ${gap}`);
+    return writeDecompiled(deps, folderOfManifest(composed.manifest, { files: bytes }), out, cwd);
+}
+/** The source of `name@version`, or a `CliError` that says a JSON save has none. */
+async function sourceOf(client, name, version) {
+    try {
+        return await client.agentManifests.source(name, version);
+    }
+    catch (error) {
+        if (error instanceof RuntimeError && error.status === 404 && error.body?.code !== "manifest_not_found")
+            throw new CliError(`${name}@${version} was saved as JSON, not from a folder, so it has no source. nylorun export --folder ${name}@${version} writes a folder from its manifest.`, 1);
+        return runtimeCall(() => Promise.reject(error));
+    }
+}
+/** `nylorun pull <name>[@<version>] [--out <dir>]` */
+export async function pullCommand(deps, args) {
+    const flags = parseFlags(args, { values: ["--out"] }, pullUsage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${pullUsage.split("\n")[0]}`);
+    const ref = nameAndVersion(flags.rest[0], pullUsage);
+    const cwd = deps.cwd ?? process.cwd();
+    const { client } = await runtimeClient(deps, flags);
+    const version = ref.version ?? (await runtimeCall(() => client.agentManifests.get(ref.name))).version;
+    const source = await sourceOf(client, ref.name, version);
+    const files = new Map();
+    for (const entry of source.entries) {
+        const bytes = await runtimeCall(() => client.agentManifests.sourceFile(ref.name, version, entry.path));
+        if (createHash("sha256").update(bytes).digest("hex") !== entry.sha256)
+            throw new CliError(`${entry.path} came back with other bytes than the source lists: nothing was written. Pull again.`, 1);
+        files.set(entry.path, bytes);
+    }
+    const out = resolve(cwd, flags.values.get("--out") ?? ref.name);
+    const where = relative(cwd, out) || ".";
+    deps.out(wroteLine(where, await writeFolder(out, files, cwd)));
+    deps.err(`${ref.name}@${version}, compiled by ${source.compiler}. Check it with nylorun check ${where}, and save an edit with nylorun apply ${where}.`);
+    return 0;
+}

package/dist/client/folder.d.ts

@@ -0,0 +1,13 @@
+import { type PackedFolder } from "@nylorun/agents";
+import { type AgentFolderDiagnostic } from "@nylorun/core/folder";
+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";
+/** 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[];
+/** `nylorun check [dir…] [--fix] [--json]` */
+export declare function checkCommand(deps: StackDeps, args: readonly string[]): Promise<number>;