@nylorun/agents 0.26.0-beta → 0.27.0-beta

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @nylorun/agents
 
+## 0.27.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.
+- Updated dependencies [9ba6634]
+- Updated dependencies [aaa079f]
+  - @nylorun/core@0.27.0-beta
+
 ## 0.26.0-beta
 
 ### Minor Changes

package/README.md

@@ -303,6 +303,19 @@ const session = await client.createSession({ id: "alice-q3", agent: "users/alice
 
 `agentManifests.save(input, { ifMatch, requestId })` and `plan(input, { ifMatch })` (a dry run that saves nothing) take a v8 document, what `composeManifest` read, or `{ agent, runtime?, harness?, loop?, memory?, name?, description?, metadata? }`: the SDK makes the harness section from the built agent or flow (`harnessSectionOf`, with its skills' `secrets`; `harness` is the harness's id; `memory`, `{ access?, instructions? }`, turns on an agent's memory, not a flow's) and names the manifest after the agent's id. First it uploads every file the manifest names by hash that the Runtime does not hold: the agent's skills, a flow's agents' skills, and the runtime's files (`runtimeFiles(path, contents)` hashes a `files` entry; pass its `bytes` as `files`). `If-Match` is the version you read (`0` for a new manifest). A save that changes nothing answers the latest version, `unchanged`. `get(name, version?)`, `list()`, `versions(name)` (with the Agents made from each) and `delete(name)` (refused while an Agent was made from it: `409 manifest_in_use`) read and remove them.
 
+### Agent folders: `packFolder`, `checkFolder`, `saveFolder`
+
+An agent can be a folder of Markdown and JSON (track T6): `AGENT.md` with `name`, `description` and the instructions, and beside it `mcp.json`, `runtime.json`, `skills/`, `tools/`, `triggers/` and `files/` as it needs them. `packFolder(dir)` (Node only) lists every file with its size and SHA-256, skipping `.git` and `node_modules`; `checkFolder(folder)` compiles it offline with the Runtime's compiler (`@nylorun/core/folder`) and returns `{ manifest?, diagnostics, compiler }`, each diagnostic with its file, line and column (`diagnosticLine` formats one). `agentManifests.saveFolder(folder, { ifMatch })` and `planFolder` compile it first, refuse one that does not compile (`FolderInvalidError`), upload the files the Runtime lacks and send the folder by hash; the Runtime keeps it as the version's source, which `source(name, version)` and `sourceFile(name, version, path)` read back.
+
+```ts
+import { createClient, packFolder } from "@nylorun/agents";
+
+const client = await createClient();
+const plan = await client.agentManifests.planFolder(await packFolder("agents/triage"));
+console.log(plan.manifest, plan.diagnostics); // the compiled manifest, and e.g. the derived GITHUB_TOKEN slot
+await client.agentManifests.saveFolder(await packFolder("agents/triage"), { ifMatch: plan.from ?? 0 });
+```
+
 ### Three files: `composeManifest`
 
 A manifest can also be authored as files, so a runtime is shared by many agents and skills stay folders. `composeManifest(dir)` (Node only) reads `<dir>/agent.manifest.json` and the files it names, each path relative to the file that names it, and returns `{ manifest, files, gaps, warnings }`; `agentManifests.save` takes it as it is and uploads `files`. `npx nylorun apply <dir>` does the same from the command line.

package/dist/agent-manifests.d.ts

@@ -13,9 +13,15 @@
  * uploads the files the manifest names by hash that the Runtime does not hold (skills, a flow's
  * agents' skills, runtime files), and refuses before sending a tool that runs your code or an
  * `approval`, as the Runtime runs agents from their manifests alone.
+ *
+ * `saveFolder` and `planFolder` take an agent folder (`packFolder`, track T6): they compile it
+ * first with the Runtime's compiler and refuse one that does not compile (`FolderInvalidError`),
+ * upload its files by hash, and send the folder, which the Runtime compiles again and keeps as the
+ * version's source.
  */
-import { AGENT_MANIFEST_V8_SCHEMA_VERSION, type AgentManifestPlan, type AgentManifestV8, type AgentMemorySettings, type AgentManifestVersions, type AgentManifestView, type DeleteAgentManifestResponse, type RuntimeSection, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
+import { AGENT_MANIFEST_V8_SCHEMA_VERSION, type AgentManifestPlan, type AgentManifestSource, type AgentManifestV8, type AgentMemorySettings, type AgentManifestVersions, type AgentManifestView, type DeleteAgentManifestResponse, type RuntimeSection, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
 import { type AgentManifest, type BuiltAgent, type BuiltWorkflow, type JsonObject, type SkillFileSource, type WorkflowManifest } from "@nylorun/core/define";
+import { type PackedFolder } from "./folder.js";
 import { type Transport } from "./http.js";
 /** A built agent or flow, or anything with its id and manifest. */
 export interface AgentSource {
@@ -113,6 +119,23 @@ export declare class AgentManifestsClient {
      * finds itself are among `errors`. Its files are uploaded, since they are stored by content.
      */
     plan(input: AgentManifestInput, options?: Omit<AgentManifestSaveOptions, "requestId">): Promise<AgentManifestPlan>;
+    /**
+     * Saves an agent folder (`packFolder`) as its manifest's next version, keeping the folder as the
+     * version's source; `unchanged` when its manifest is. The folder is compiled first, and one that
+     * does not compile is refused before anything is sent (`FolderInvalidError`).
+     */
+    saveFolder(folder: PackedFolder, options?: Omit<AgentManifestSaveOptions, "files">): Promise<SaveAgentManifestResponse>;
+    /** What saving an agent folder would do (`?dryRun=true`), with the compiled `manifest` and its `diagnostics`. */
+    planFolder(folder: PackedFolder, options?: Omit<AgentManifestSaveOptions, "files" | "requestId">): Promise<AgentManifestPlan>;
+    private sendFolder;
+    /** The folder version `version` of manifest `name` was saved from; a version saved as JSON has none (`404`). */
+    source(name: string, version: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentManifestSource>;
+    /** The bytes of file `path` in the folder version `version` of manifest `name` was saved from. */
+    sourceFile(name: string, version: number, path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
     /** The latest version of manifest `name`, or version `version`. */
     get(name: string, version?: number, options?: {
         signal?: AbortSignal;

package/dist/agent-manifests.js

@@ -13,10 +13,16 @@
  * uploads the files the manifest names by hash that the Runtime does not hold (skills, a flow's
  * agents' skills, runtime files), and refuses before sending a tool that runs your code or an
  * `approval`, as the Runtime runs agents from their manifests alone.
+ *
+ * `saveFolder` and `planFolder` take an agent folder (`packFolder`, track T6): they compile it
+ * first with the Runtime's compiler and refuse one that does not compile (`FolderInvalidError`),
+ * upload its files by hash, and send the folder, which the Runtime compiles again and keeps as the
+ * version's source.
  */
-import { AGENT_MANIFEST_V8_SCHEMA_VERSION, AgentManifestV8Schema, isAgentManifestName, } from "@nylorun/core/contracts";
+import { AGENT_FOLDER_MEDIA_TYPE, AGENT_MANIFEST_V8_SCHEMA_VERSION, AgentManifestV8Schema, isAgentManifestName, } from "@nylorun/core/contracts";
 import { approvalRefusal, codeToolRefusal, delegateOf, harnessSectionOf, isBuiltWorkflow, loopManifestOf, } from "@nylorun/core/define";
 import { FilesClient } from "./files.js";
+import { FolderInvalidError } from "./folder.js";
 import { id, segment } from "./http.js";
 /** A manifest the SDK refuses before sending: its sections do not fit, or it misses its `requires`. */
 export class ManifestGapsError extends Error {
@@ -209,6 +215,53 @@ export class AgentManifestsClient {
         const errors = [...plan.errors, ...prepared.gaps.filter((gap) => !plan.errors.includes(gap))];
         return { ...plan, errors };
     }
+    /**
+     * Saves an agent folder (`packFolder`) as its manifest's next version, keeping the folder as the
+     * version's source; `unchanged` when its manifest is. The folder is compiled first, and one that
+     * does not compile is refused before anything is sent (`FolderInvalidError`).
+     */
+    async saveFolder(folder, options = {}) {
+        return this.sendFolder(folder, "", options);
+    }
+    /** What saving an agent folder would do (`?dryRun=true`), with the compiled `manifest` and its `diagnostics`. */
+    async planFolder(folder, options = {}) {
+        return this.sendFolder(folder, "?dryRun=true", options);
+    }
+    async sendFolder(folder, query, options) {
+        const { ifMatch, signal } = options;
+        // Loaded only now: the compiler's YAML parser needs Node.
+        const { checkFolder } = await import("./folder-check.js");
+        const compiled = await checkFolder(folder);
+        if (!compiled.manifest)
+            throw new FolderInvalidError(folder.dir, compiled.diagnostics);
+        const path = this.path(compiled.manifest.name);
+        const files = new Map(folder.entries.map((entry) => [`sha256:${entry.sha256}`, folder.files.get(entry.path)]));
+        await new FilesClient(this.transport).ensure(files, signal ? { signal } : {});
+        const transport = ifMatch === undefined ? this.transport : this.transport.withHeaders({ "If-Match": String(ifMatch) });
+        const response = await transport.request(`${path}${query}`, {
+            method: "PUT",
+            headers: { "content-type": AGENT_FOLDER_MEDIA_TYPE },
+            body: JSON.stringify({
+                requestId: options.requestId ?? id(),
+                format: "nylorun.folder.v2",
+                entries: folder.entries.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
+            }),
+            ...(signal ? { signal } : {}),
+        });
+        return (await response.json());
+    }
+    /** The folder version `version` of manifest `name` was saved from; a version saved as JSON has none (`404`). */
+    async source(name, version, options = {}) {
+        return this.transport.json(`${this.path(name)}/versions/${version}/source`, "GET", undefined, options.signal);
+    }
+    /** The bytes of file `path` in the folder version `version` of manifest `name` was saved from. */
+    async sourceFile(name, version, path, options = {}) {
+        const response = await this.transport.request(`${this.path(name)}/versions/${version}/source/files/${segment(path)}`, {
+            method: "GET",
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        return new Uint8Array(await response.arrayBuffer());
+    }
     /** The latest version of manifest `name`, or version `version`. */
     async get(name, version, options = {}) {
         return this.transport.json(`${this.path(name)}${version === undefined ? "" : `/versions/${version}`}`, "GET", undefined, options.signal);

package/dist/folder-check.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `checkFolder`: compiles an agent folder offline with the compiler the Runtime runs
+ * (`@nylorun/core/folder`). Its YAML parser loads Node modules, so the client entry imports this
+ * module only when a folder is sent.
+ */
+import { type CompiledAgentFolder } from "@nylorun/core/folder";
+import type { PackedFolder } from "./folder.js";
+/**
+ * Compiles a packed folder offline, as the Runtime will: the manifest when it compiles, and every
+ * diagnostic either way. With `name`, the name it will be saved as, `AGENT.md`'s must match.
+ */
+export declare function checkFolder(packed: PackedFolder, options?: {
+    name?: string;
+}): Promise<CompiledAgentFolder>;

package/dist/folder-check.js

@@ -0,0 +1,20 @@
+/**
+ * `checkFolder`: compiles an agent folder offline with the compiler the Runtime runs
+ * (`@nylorun/core/folder`). Its YAML parser loads Node modules, so the client entry imports this
+ * module only when a folder is sent.
+ */
+import { AGENT_FOLDER_LIMITS, compileAgentFolder, folderTextPaths, } from "@nylorun/core/folder";
+/**
+ * Compiles a packed folder offline, as the Runtime will: the manifest when it compiles, and every
+ * diagnostic either way. With `name`, the name it will be saved as, `AGENT.md`'s must match.
+ */
+export async function checkFolder(packed, options = {}) {
+    const text = new Map();
+    for (const path of folderTextPaths(packed.entries)) {
+        const source = packed.files.get(path);
+        // The compiler reports a file over its limit; it needs no bytes for it.
+        if (source.size <= AGENT_FOLDER_LIMITS.textFileBytes)
+            text.set(path, await source.read());
+    }
+    return compileAgentFolder({ entries: packed.entries, files: text, ...(options.name === undefined ? {} : { name: options.name }) });
+}

package/dist/folder-pack.d.ts

@@ -0,0 +1,5 @@
+import { type PackedFolder } from "./folder.js";
+/** Whether `dir` holds an `AGENT.md`. */
+export declare function isAgentFolder(dir: string): Promise<boolean>;
+/** Lists the agent folder at `dir` with each file's size and SHA-256. */
+export declare function packFolder(dir: string): Promise<PackedFolder>;

package/dist/folder-pack.js

@@ -0,0 +1,54 @@
+/**
+ * Packing an agent folder (track T6): `packFolder(dir)` lists every file with its size and SHA-256
+ * and reads its bytes on demand. It skips `.git`, `.hg`, `.svn` and `node_modules` and follows no
+ * symbolic link. Node only: it reads the folder.
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { AGENT_FOLDER_LIMITS } from "@nylorun/core/folder";
+import { AGENT_FOLDER_FILE, FolderError } from "./folder.js";
+const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", "node_modules"]);
+/** Whether `dir` holds an `AGENT.md`. */
+export async function isAgentFolder(dir) {
+    return stat(join(dir, AGENT_FOLDER_FILE)).then((found) => found.isFile(), () => false);
+}
+/** Lists the agent folder at `dir` with each file's size and SHA-256. */
+export async function packFolder(dir) {
+    const root = resolve(dir);
+    const entries = [];
+    const files = new Map();
+    const skipped = [];
+    let bytes = 0;
+    const walk = async (at) => {
+        const children = await readdir(at, { withFileTypes: true }).catch((error) => {
+            throw new FolderError(root, `Cannot read ${at}: ${error.code ?? error}`);
+        });
+        for (const child of children.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+            const full = join(at, child.name);
+            const path = relative(root, full).split(sep).join("/");
+            if (child.isDirectory()) {
+                if (!SKIPPED_DIRECTORIES.has(child.name))
+                    await walk(full);
+                continue;
+            }
+            if (child.isSymbolicLink()) {
+                skipped.push(`${path}: a symbolic link, not followed`);
+                continue;
+            }
+            if (!child.isFile())
+                continue;
+            if (entries.length >= AGENT_FOLDER_LIMITS.files)
+                throw new FolderError(root, `${dir} holds more than ${AGENT_FOLDER_LIMITS.files} files, an agent folder's limit`);
+            const data = await readFile(full);
+            bytes += data.byteLength;
+            if (bytes > AGENT_FOLDER_LIMITS.totalBytes)
+                throw new FolderError(root, `${dir} holds more than ${AGENT_FOLDER_LIMITS.totalBytes} bytes, an agent folder's limit`);
+            entries.push({ path, size: data.byteLength, sha256: createHash("sha256").update(data).digest("hex") });
+            files.set(path, { size: data.byteLength, read: () => readFile(full) });
+        }
+    };
+    await walk(root);
+    entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { dir: root, entries, files, skipped };
+}

package/dist/folder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent folders (track T6, D79): a folder of Markdown and JSON (`AGENT.md`, `mcp.json`,
+ * `runtime.json`, `skills/`, `tools/`, `triggers/`, `files/`) that `@nylorun/core/folder`
+ * compiles into agent manifest v8. `packFolder(dir)` (`folder-pack.ts`, Node only) lists it with
+ * each file's size and hash, `checkFolder` compiles it offline with the same compiler the Runtime
+ * runs, and `client.agentManifests.saveFolder` sends it by hash, so the Runtime keeps the folder
+ * as the version's source. This module loads neither the file system nor the compiler, whose
+ * YAML parser needs Node: the client entry loads it, and `checkFolder` (`folder-check.ts`) only
+ * when a folder is sent.
+ */
+import type { AgentFolderDiagnostic, AgentFolderEntry } from "@nylorun/core/folder";
+import type { SkillFileSource } from "@nylorun/core/define";
+/** The file that makes a folder an agent folder. */
+export declare const AGENT_FOLDER_FILE = "AGENT.md";
+/** A folder as the Runtime takes it: each file's path, size and hash, and a way to read its bytes. */
+export interface PackedFolder {
+    /** The folder's absolute path. */
+    readonly dir: string;
+    /** Every file, sorted by path, with `/` between segments. */
+    readonly entries: readonly AgentFolderEntry[];
+    /** Each file's bytes, by path. */
+    readonly files: ReadonlyMap<string, SkillFileSource>;
+    /** What packing left out, and why (a symbolic link). */
+    readonly skipped: readonly string[];
+}
+/** A folder that cannot be packed: too many files, or more bytes than an agent folder holds. */
+export declare class FolderError extends Error {
+    readonly dir: string;
+    constructor(dir: string, message: string);
+}
+/** A folder that does not compile; `diagnostics` holds every problem, by file, line and column. */
+export declare class FolderInvalidError extends Error {
+    readonly dir: string;
+    readonly diagnostics: readonly AgentFolderDiagnostic[];
+    constructor(dir: string, diagnostics: readonly AgentFolderDiagnostic[]);
+}
+/** A diagnostic as a person reads it: `file:line:column severity message`. */
+export declare function diagnosticLine(diagnostic: AgentFolderDiagnostic): string;

package/dist/folder.js

@@ -0,0 +1,30 @@
+/** The file that makes a folder an agent folder. */
+export const AGENT_FOLDER_FILE = "AGENT.md";
+/** A folder that cannot be packed: too many files, or more bytes than an agent folder holds. */
+export class FolderError extends Error {
+    dir;
+    constructor(dir, message) {
+        super(message);
+        this.dir = dir;
+        this.name = "FolderError";
+    }
+}
+/** A folder that does not compile; `diagnostics` holds every problem, by file, line and column. */
+export class FolderInvalidError extends Error {
+    dir;
+    diagnostics;
+    constructor(dir, diagnostics) {
+        const errors = diagnostics.filter((item) => item.severity === "error");
+        super(`Agent folder ${dir} does not compile:\n${errors.map((item) => `  ${diagnosticLine(item)}`).join("\n")}`);
+        this.dir = dir;
+        this.diagnostics = diagnostics;
+        this.name = "FolderInvalidError";
+    }
+}
+/** A diagnostic as a person reads it: `file:line:column severity message`. */
+export function diagnosticLine(diagnostic) {
+    const where = diagnostic.file
+        ? `${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}${diagnostic.column ? `:${diagnostic.column}` : ""}` : ""} `
+        : "";
+    return `${where}${diagnostic.severity}: ${diagnostic.message}`;
+}

package/dist/index.d.ts

@@ -16,6 +16,10 @@ export type { ArtifactBody, ArtifactPageOptions, ArtifactLinkWithUrl, UploadArti
 export type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSessionOptions, SessionSandbox, AgentFilter, AgentInput, AgentSecretInput, RuntimeFileBytes, AgentManifestDocument, AgentManifestFromAgent, AgentManifestInput, AgentManifestSaveOptions, ComposedManifest, DefinitionFiles, } from "./client.js";
 export { AgentInstancesClient, AgentManifestsClient, AgentMemoriesClient, AgentSecretsClient, ManifestGapsError, agentManifest, requirementGaps, runtimeFiles, } from "./client.js";
 export { composeManifest, manifestFolders, ComposeError, AGENT_MANIFEST_FILE } from "./compose.js";
+export { AGENT_FOLDER_FILE, FolderError, FolderInvalidError, diagnosticLine } from "./folder.js";
+export { checkFolder } from "./folder-check.js";
+export type { PackedFolder } from "./folder.js";
+export { packFolder, isAgentFolder } from "./folder-pack.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export type { ResolvedConnection } from "./connection.js";

package/dist/index.js

@@ -10,6 +10,9 @@ export { ArtifactsClient } from "./artifacts.js";
 export { FilesClient, definitionFileHash } from "./files.js";
 export { AgentInstancesClient, AgentManifestsClient, AgentMemoriesClient, AgentSecretsClient, ManifestGapsError, agentManifest, requirementGaps, runtimeFiles, } from "./client.js";
 export { composeManifest, manifestFolders, ComposeError, AGENT_MANIFEST_FILE } from "./compose.js";
+export { AGENT_FOLDER_FILE, FolderError, FolderInvalidError, diagnosticLine } from "./folder.js";
+export { checkFolder } from "./folder-check.js";
+export { packFolder, isAgentFolder } from "./folder-pack.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";

package/dist/session-client.d.ts

@@ -421,4 +421,6 @@ export { AccessClient } from "./access.js";
 export { AgentInstancesClient, AgentMemoriesClient, AgentSecretsClient, runtimeFiles } from "./agents.js";
 export type { AgentFilter, AgentInput, AgentSecretInput, RuntimeFileBytes } from "./agents.js";
 export { AgentManifestsClient, ManifestGapsError, agentManifest, requirementGaps } from "./agent-manifests.js";
+export { AGENT_FOLDER_FILE, FolderError, FolderInvalidError, diagnosticLine } from "./folder.js";
+export type { PackedFolder } from "./folder.js";
 export type { AgentManifestDocument, AgentManifestFromAgent, AgentManifestInput, AgentManifestSaveOptions, AgentSource, ComposedManifest, DefinitionFiles, } from "./agent-manifests.js";

package/dist/session-client.js

@@ -336,3 +336,4 @@ export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { AccessClient } from "./access.js";
 export { AgentInstancesClient, AgentMemoriesClient, AgentSecretsClient, runtimeFiles } from "./agents.js";
 export { AgentManifestsClient, ManifestGapsError, agentManifest, requirementGaps } from "./agent-manifests.js";
+export { AGENT_FOLDER_FILE, FolderError, FolderInvalidError, diagnosticLine } from "./folder.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.26.0-beta",
+  "version": "0.27.0-beta",
   "description": "Nylorun agent definitions and session client",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,7 +43,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.26.0-beta",
+    "@nylorun/core": "0.27.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {