nylorun 0.18.2-beta → 0.19.0-beta

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # nylorun
 
+## 0.19.0-beta
+
+### Minor Changes
+
+- aaa079f: Agent folders in the SDK and the CLI (track T6). `@nylorun/agents` adds `packFolder(dir)`, which lists a folder's files with their sizes and hashes (skipping `.git` and `node_modules`, following no symbolic link), `checkFolder`, which compiles it offline with the Runtime's compiler, and `client.agentManifests.saveFolder` and `planFolder`, which upload the files the Runtime lacks and send the folder by hash; `source` and `sourceFile` read a version's folder back. `nylorun init <name>` writes a new folder's `AGENT.md`, `nylorun check [dir…]` prints every problem by file, line and column with no Runtime, and `nylorun apply` saves a folder with `AGENT.md` (`--dry-run` prints the compiled manifest). A folder that does not compile sends nothing.
+
+### 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 [9ba6634]
+- Updated dependencies [aaa079f]
+- Updated dependencies [aaa079f]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.27.0-beta
+  - @nylorun/agents@0.27.0-beta
+  - @nylorun/admin@0.19.3-beta
+
+## 0.18.3-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 [fce0c9b]
+- Updated dependencies [ab7c08a]
+- Updated dependencies [4a563e7]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.26.0-beta
+  - @nylorun/agents@0.26.0-beta
+  - @nylorun/admin@0.19.2-beta
+
 ## 0.18.2-beta
 
 ### Patch Changes

package/README.md

@@ -53,7 +53,9 @@ 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 apply [<dir>...] [--dry-run] [--if-match <n>]   # plan, then save each folder's agent.manifest.json, its files uploaded
+nylorun init <name> [--description <text>]   # write <name>/AGENT.md, a new agent folder
+nylorun check [<dir>...]           # compile each agent folder offline: every problem by file, line and column
+nylorun apply [<dir>...] [--dry-run] [--if-match <n>]   # plan, then save each folder (AGENT.md or agent.manifest.json), its files uploaded
 nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]   # the three files from a v7 manifest; reads no Runtime
 nylorun agent-manifests list [--json]       # name, latest version, runtime kind, harness, Agents
 nylorun agent-manifests get <name>[@<n>] | versions <name> | rm <name>
@@ -476,7 +478,25 @@ from a terminal.
 An agent runs from a saved **agent manifest** (protocol 16): one named, versioned
 document with a harness section (instructions, tools, skills, MCP servers,
 plugins) and a runtime section (kind, image, network, setup, files, secret
-slots). Author it as files, one folder per agent:
+slots). Author it as an agent folder (track T6), one folder per agent:
+
+```
+agents/support/AGENT.md        # frontmatter (name, description), then the instructions
+agents/support/mcp.json        # MCP servers; "Authorization": "Bearer ${GITHUB_TOKEN}" names a slot
+agents/support/runtime.json    # kind, network, secrets (optional)
+agents/support/skills/<skill>/SKILL.md, tools/<tool>.json, triggers/<id>.md, files/**
+```
+
+`nylorun init support` writes the `AGENT.md`; `nylorun check agents/support`
+compiles the folder offline with the Runtime's compiler and prints every problem
+as `file:line:column severity: message`, exiting 1 when it does not compile.
+`nylorun apply agents/support` checks it the same way (sending nothing when it
+does not compile), plans it, prints the compiler's notes (such as a slot derived
+from `mcp.json`) and saves it, uploading its files by hash; the Runtime keeps the
+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`.
+
+Or as three files:
 
 ```
 agents/triage/agent.manifest.json     # { "manifestSchemaVersion": 8, "name": "triage",

package/dist/cli.js

@@ -13,9 +13,12 @@ ${stackUsage}
                                       the sandbox backend the Tenant's Host offers
 
 Agent manifests:
+  init <name> [--description <text>]  write <name>/AGENT.md, a new agent folder
+  check [<dir>...]                    compile each agent folder offline and print every problem
+                                      by file, line and column (reads no Runtime)
   apply [<dir>...] [--dry-run] [--if-match <n>]
-                                      save the agent manifest each folder's agent.manifest.json
-                                      describes, with the files it names (Runtime API)
+                                      save the agent manifest each folder describes (its AGENT.md,
+                                      or its agent.manifest.json), with its files (Runtime API)
   migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]
                                       write the three manifest files from an agent manifest v7
                                       and an environment manifest v1 (reads no Runtime)
@@ -164,6 +167,8 @@ async function main() {
         return;
     }
     if (command === "apply" ||
+        command === "check" ||
+        command === "init" ||
         command === "migrate" ||
         command === "agent-manifests" ||
         command === "agents" ||
@@ -171,6 +176,8 @@ async function main() {
         command === "artifacts") {
         const group = {
             apply: async () => (await import("./client/apply.js")).applyCommand,
+            check: async () => (await import("./client/folder.js")).checkCommand,
+            init: async () => (await import("./client/folder.js")).initCommand,
             migrate: async () => (await import("./client/migrate.js")).migrateCommand,
             "agent-manifests": async () => (await import("./client/agent-manifests.js")).agentManifestsCommand,
             agents: async () => (await import("./client/agents.js")).agentsCommand,

package/dist/client/apply.js

@@ -7,24 +7,33 @@
  * 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/`).
+ *
+ * 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.
  */
 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 { agentFolders, diagnosticLines, packed } from "./folder.js";
 import { integerFlag, parseFlags, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError } from "./runtime.js";
 export const applyUsage = `nylorun apply [<dir>...] [--dry-run] [--if-match <n>]
 
 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)
 
 ${runtimeFlagsUsage}`;
@@ -48,6 +57,13 @@ export function planLines(plan) {
         ...plan.errors.map((error) => `  error: ${error}`),
     ];
 }
+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>]` */
 export async function applyCommand(deps, args) {
     if (args[0] === "--help" || args[0] === "-h") {
@@ -60,38 +76,79 @@ export async function applyCommand(deps, args) {
     const cwd = deps.cwd ?? process.cwd();
     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);
+    // 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) {
+                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");
+    for (const item of work) {
+        const options = ifMatch === undefined ? {} : { ifMatch };
+        if ("pack" in item) {
+            const plan = await runtimeCall(() => client.agentManifests.planFolder(item.pack, options));
+            for (const line of planLines(plan))
+                deps.out(line);
+            for (const line of diagnosticLines(item.folder, cwd, (plan.diagnostics ?? []).filter((d) => d.severity !== "error")))
+                deps.out(`  ${line}`);
+            if (dryRun && plan.manifest)
+                deps.out(JSON.stringify(plan.manifest, null, 2));
+            if (plan.errors.length > 0) {
+                blocked = true;
+                continue;
+            }
+            if (dryRun || plan.unchanged)
+                continue;
+            const saved = await runtimeCall(() => client.agentManifests.saveFolder(item.pack, { ifMatch: ifMatch ?? plan.from ?? 0 }));
+            reportSaved(deps, saved, connection.label);
+            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, options));
         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 || plan.unchanged)
             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}`);
+        reportSaved(deps, saved, connection.label);
     }
     if (blocked)
         deps.err("Nothing was saved for a manifest with errors.");

package/dist/client/folder.d.ts

@@ -0,0 +1,15 @@
+import { type PackedFolder } from "@nylorun/agents";
+import type { AgentFolderDiagnostic } from "@nylorun/core/folder";
+import { type StackDeps } from "../stack/commands.js";
+export declare const checkUsage = "nylorun check [<dir>...]\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.";
+export declare const initUsage = "nylorun init <name> [--description <text>]\n\nWrites <name>/AGENT.md, the smallest agent folder: frontmatter with its name and description, and\nits instructions below. Save it with nylorun apply <name>.";
+/** 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`. */
+export declare function diagnosticLines(folder: string, cwd: string, diagnostics: readonly AgentFolderDiagnostic[]): string[];
+/** `nylorun check [dir…]` */
+export declare function checkCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
+/** `nylorun init <name> [--description <text>]` */
+export declare function initCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/folder.js

@@ -0,0 +1,99 @@
+/**
+ * Agent folders (track T6, D79) on the command line, offline: `nylorun check [dir…]` compiles each
+ * agent folder with the compiler the Runtime runs (`@nylorun/core/folder`) and prints every
+ * diagnostic by file, line and column; `nylorun init <name>` writes a new folder's `AGENT.md`.
+ * Neither reads a Runtime. `nylorun apply` saves a folder (`apply.ts`).
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { isAgentManifestName } from "@nylorun/core/contracts";
+import { AGENT_FOLDER_FILE, FolderError, checkFolder, diagnosticLine, isAgentFolder, packFolder, } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { usageError } from "./runtime.js";
+export const checkUsage = `nylorun check [<dir>...]
+
+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
+subfolder that has one. Exits 1 when a folder does not compile. Reads no Runtime.`;
+export const initUsage = `nylorun init <name> [--description <text>]
+
+Writes <name>/AGENT.md, the smallest agent folder: frontmatter with its name and description, and
+its instructions below. Save it with nylorun apply <name>.`;
+/** 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);
+    if (await isAgentFolder(root))
+        return [root];
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const found = [];
+    for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => (a.name < b.name ? -1 : 1)))
+        if (await isAgentFolder(join(root, entry.name)))
+            found.push(join(root, entry.name));
+    return found;
+}
+/** Packs the folder, or a `CliError` naming why it cannot be. */
+export async function packed(folder) {
+    return packFolder(folder).catch((error) => {
+        if (error instanceof FolderError)
+            throw new CliError(error.message, 1);
+        throw error;
+    });
+}
+/** A folder's diagnostics as lines, each path relative to `cwd`. */
+export function diagnosticLines(folder, cwd, diagnostics) {
+    const prefix = relative(cwd, folder);
+    return diagnostics.map((item) => diagnosticLine(item.file && prefix ? { ...item, file: `${prefix}/${item.file}` } : item));
+}
+/** `nylorun check [dir…]` */
+export async function checkCommand(deps, args) {
+    const flags = parseStackFlags(args, {}, checkUsage);
+    const cwd = deps.cwd ?? process.cwd();
+    const folders = [];
+    for (const dir of flags.rest.length > 0 ? flags.rest : ["."]) {
+        const found = await agentFolders(resolve(cwd, dir));
+        if (found.length === 0)
+            throw usageError(`${dir} holds no ${AGENT_FOLDER_FILE}, and no subfolder does.`);
+        folders.push(...found);
+    }
+    let failed = false;
+    for (const folder of folders) {
+        const pack = await packed(folder);
+        const compiled = await checkFolder(pack);
+        for (const skipped of pack.skipped)
+            deps.err(`${relative(cwd, folder) || "."}: skipped ${skipped}`);
+        for (const line of diagnosticLines(folder, cwd, compiled.diagnostics))
+            if (compiled.manifest)
+                deps.out(line);
+            else
+                deps.err(line);
+        const label = relative(cwd, folder) || basename(folder);
+        if (compiled.manifest)
+            deps.out(`${label}: ok, agent manifest ${compiled.manifest.name} (${pack.entries.length} files, ${compiled.compiler})`);
+        else {
+            failed = true;
+            const errors = compiled.diagnostics.filter((item) => item.severity === "error").length;
+            deps.err(`${label}: ${errors} ${errors === 1 ? "error" : "errors"}`);
+        }
+    }
+    return failed ? 1 : 0;
+}
+/** `nylorun init <name> [--description <text>]` */
+export async function initCommand(deps, args) {
+    const flags = parseStackFlags(args, { values: ["--description"] }, initUsage);
+    const [name, ...rest] = flags.rest;
+    if (name === undefined || rest.length > 0)
+        throw usageError(`Usage: ${initUsage.split("\n")[0]}`);
+    if (!isAgentManifestName(name))
+        throw usageError(`${name} is not an agent's name: 1-64 letters, digits, '.', '_' and '-', starting with a letter or digit.`);
+    const dir = resolve(deps.cwd ?? process.cwd(), name);
+    const file = join(dir, AGENT_FOLDER_FILE);
+    if (existsSync(file))
+        throw new CliError(`${relative(deps.cwd ?? process.cwd(), file)} exists already.`, 1);
+    const description = flags.values.get("--description") ?? `Describe what ${name} does in one sentence.`;
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\n---\nYou are ${name}. Write the agent's instructions here, in Markdown.\n`, { flag: "wx" });
+    deps.out(`Wrote ${relative(deps.cwd ?? process.cwd(), file)}. Check it with nylorun check ${name}, and save it with nylorun apply ${name}.`);
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.18.2-beta",
+  "version": "0.19.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.1-beta",
-    "@nylorun/agents": "0.25.0-beta",
-    "@nylorun/core": "0.25.0-beta"
+    "@nylorun/admin": "0.19.3-beta",
+    "@nylorun/agents": "0.27.0-beta",
+    "@nylorun/core": "0.27.0-beta"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.2.0",
@@ -46,7 +46,7 @@
     "nylo": "dist/nylo.js"
   },
   "nylorun": {
-    "runtime": "0.29.0-beta",
-    "studio": "0.30.0-beta"
+    "runtime": "0.31.0-beta",
+    "studio": "0.31.1-beta"
   }
 }