@nylorun/agents 0.23.0-beta → 0.25.0-beta

package/dist/agents.js

@@ -0,0 +1,331 @@
+/**
+ * Agents (protocol 16): `client.agents`. An Agent is the live instance of one version of an agent
+ * manifest (`client.agentManifests`): one environment of the manifest's runtime kind (`virtual`,
+ * `pod` or `none`), one vault of secrets for its shell, MCP servers and HTTP tools, and the
+ * sessions that run on it. It is made only from a saved manifest, `name` (tracking) or `name@n`
+ * (pinned), and runs one version of it at a time: `put` with another version moves it, and a save
+ * moves every Agent that tracks the manifest. Its manifest, kind, harness and storage
+ * are fixed (`409 agent_fixed_field`): `fork` makes a new Agent to change them. It has
+ * its own id and outlives its sessions; whether it serves one person or a project is the app's
+ * choice, made by its id:
+ *
+ * - `agents.put("users/alice/triage", { manifest: "triage", owner: "alice" })`: get-or-create
+ *   in one call. Write its secrets with `agents.secrets.put(id, name, { value })` and open
+ *   sessions on it with `createSession({ agent: id, ... })`. Creating it opens no session.
+ *
+ * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
+ * write-only: no call reads one back.
+ *
+ * Triggers: what its manifest's `runtime.triggers` declares starts its turns with
+ * no client connected. `triggers(id)` lists them with their status and next run, `pauseTrigger`,
+ * `resumeTrigger` and `runTrigger` change or run one, `rotateWebhookSecret` makes a webhook
+ * trigger's signing secret, and `runs(id)` pages what each fire came to.
+ *
+ * Memory: an Agent whose manifest sets `harness.memory` keeps Markdown files under
+ * `/memories` across sessions. `agents.memories` lists, reads, writes (to seed it), deletes and
+ * pages the versions every change leaves.
+ *
+ * Disk versions (Host feature `environment-disk-versions`): `snapshot(id)` keeps a version of
+ * the Agent's disk between turns, `restore(id, version)` puts one back, and
+ * `put(id, { manifest, from: { agent, version } })` creates a new Agent from another's version.
+ */
+import { AgentPageSchema, isAgentId, } from "@nylorun/core/contracts";
+import { definitionFileHash } from "./files.js";
+import { id, segment } from "./http.js";
+/**
+ * A runtime section's `files` entry by content hash: `contents` (each file's path under
+ * `path` and its bytes or text) hashed, as `entry` for the manifest's `runtime.files` and `bytes`
+ * for `agentManifests.save`'s `files`, which uploads them. Each file holds at most 2 GiB.
+ */
+export async function runtimeFiles(path, contents) {
+    const files = {};
+    const bytes = {};
+    for (const [name, content] of Object.entries(contents).sort(([a], [b]) => a.localeCompare(b))) {
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const sha256 = await definitionFileHash(data);
+        files[name] = sha256;
+        bytes[sha256] = data;
+    }
+    return { entry: { path, files }, bytes };
+}
+function filterQuery(filter, query = new URLSearchParams()) {
+    for (const [key, value] of Object.entries(filter.labels ?? {}))
+        query.append("label", `${key}=${value}`);
+    if (filter.state !== undefined)
+        query.set("state", filter.state);
+    if (filter.manifest !== undefined)
+        query.set("manifest", filter.manifest);
+    if (filter.outdated !== undefined)
+        query.set("outdated", String(filter.outdated));
+    return query;
+}
+/** An Agent's secrets: `client.agents.secrets`. */
+export class AgentSecretsClient {
+    transport;
+    path;
+    constructor(transport, path) {
+        this.transport = transport;
+        this.path = path;
+    }
+    /**
+     * Creates or replaces secret `name` (`PUT /v1/agents/{id}/secrets/{name}`): for
+     * `environment_secret` and `environment_variable` the name is the variable's. A second
+     * credential for a host or a URL is a 409 `credential_conflict`. When the Agent's manifest
+     * declares the secret's slot, send only `{ value }` (or `{ headers }`); a name it does
+     * not declare is `409 secret_not_in_manifest`.
+     */
+    async put(agentId, name, secret, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/secrets/${segment(name)}`, "PUT", { requestId: id(), ...secret }, options.signal);
+    }
+    /** The secrets' names, types and bindings; never a value. */
+    async list(agentId, options = {}) {
+        const reply = await this.transport.json(`${this.path(agentId)}/secrets`, "GET", undefined, options.signal);
+        return reply.secrets;
+    }
+    async get(agentId, name, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/secrets/${segment(name)}`, "GET", undefined, options.signal);
+    }
+    async delete(agentId, name, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/secrets/${segment(name)}`, "DELETE", undefined, options.signal);
+    }
+}
+/**
+ * An Agent's memories: `client.agents.memories`. A path is a memory's path under
+ * `/memories` (`conventions/release.md` or `/memories/conventions/release.md`).
+ */
+export class AgentMemoriesClient {
+    transport;
+    path;
+    constructor(transport, path) {
+        this.transport = transport;
+        this.path = path;
+    }
+    memoryPath(agentId, path) {
+        const relative = path.replace(/^\/+/, "").replace(/^memories\//, "");
+        return `${this.path(agentId)}/memories/${segment(relative)}`;
+    }
+    /** The Agent's memories by path; `pathPrefix` keeps one folder's. */
+    async list(agentId, options = {}) {
+        const query = new URLSearchParams({ limit: String(options.limit ?? 100) });
+        if (options.pathPrefix !== undefined)
+            query.set("pathPrefix", options.pathPrefix);
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        return this.transport.json(`${this.path(agentId)}/memories?${query}`, "GET", undefined, options.signal);
+    }
+    /** One memory with its content. */
+    async get(agentId, path, options = {}) {
+        return this.transport.json(this.memoryPath(agentId, path), "GET", undefined, options.signal);
+    }
+    /**
+     * Writes the memory whole, creating or replacing it: how an app seeds an Agent's memory. With
+     * `contentSha256` the write applies only while the memory still has that content (`""`: only
+     * while there is none); otherwise `409 memory_conflict`.
+     */
+    async put(agentId, path, content, options = {}) {
+        return this.transport.json(this.memoryPath(agentId, path), "PUT", { content, ...(options.contentSha256 === undefined ? {} : { contentSha256: options.contentSha256 }) }, options.signal);
+    }
+    /** Deletes a memory, or every memory in a folder. */
+    async delete(agentId, path, options = {}) {
+        return this.transport.json(this.memoryPath(agentId, path), "DELETE", undefined, options.signal);
+    }
+    /** Every change to the Agent's memories, newest first; `path` keeps one memory's. */
+    async versions(agentId, options = {}) {
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.path !== undefined)
+            query.set("path", options.path);
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        return this.transport.json(`${this.path(agentId)}/memory_versions?${query}`, "GET", undefined, options.signal);
+    }
+    /** One version with the content it left (`null` for a delete). */
+    async version(agentId, versionId, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/memory_versions/${segment(versionId)}`, "GET", undefined, options.signal);
+    }
+}
+/** The Tenant's Agents: `client.agents`. */
+export class AgentInstancesClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    path(agentId) {
+        if (!isAgentId(agentId))
+            throw new TypeError(`${agentId} is not an Agent id: up to 200 characters, /-separated segments of letters, digits, '.', '_' and '-'`);
+        return `/v1/agents/${segment(agentId)}`;
+    }
+    /** The Agent's secrets. */
+    get secrets() {
+        return new AgentSecretsClient(this.transport, (agentId) => this.path(agentId));
+    }
+    /** The Agent's memories. */
+    get memories() {
+        return new AgentMemoriesClient(this.transport, (agentId) => this.path(agentId));
+    }
+    /**
+     * Creates the Agent, its vault and its compute from a saved agent manifest, or finds the one
+     * with this id (`PUT /v1/agents/{id}`): `{ manifest: "name" }` tracks the manifest (its latest
+     * version when the Agent is made), `"name@n"` pins version n. On an existing Agent, labels
+     * replace, `owner` sets or clears the owner guard, and `manifest` moves it to that version of
+     * its manifest: at once, at its pod's next start for a runtime change (`targetVersion`,
+     * `waitingFor: "start"`), or once a required secret the version adds is set. Another manifest,
+     * kind, harness or storage is `409 agent_fixed_field` (fork it instead).
+     */
+    async put(agentId, input, options = {}) {
+        return this.transport.json(this.path(agentId), "PUT", { requestId: id(), ...input }, options.signal);
+    }
+    /**
+     * What `put` would do to the existing Agent (`PUT /v1/agents/{id}?dryRun=true`): the
+     * version it runs and the one `input.manifest` names, when that applies (`now`, `next_start`,
+     * `secrets`, or `refused` with each fixed field), the changes, and the secrets it would wait
+     * for or leave unused. Nothing changes.
+     */
+    async plan(agentId, input, options = {}) {
+        const reply = await this.transport.json(`${this.path(agentId)}?dryRun=true`, "PUT", { requestId: id(), ...input }, options.signal);
+        return reply.plan;
+    }
+    async get(agentId, options = {}) {
+        return this.transport.json(this.path(agentId), "GET", undefined, options.signal);
+    }
+    /** The Agents this client reaches with every label in `labels`, and the `state` or `manifest` given. */
+    async list(options = {}) {
+        const search = filterQuery(options).toString();
+        const reply = await this.transport.json(`/v1/agents${search ? `?${search}` : ""}`, "GET", undefined, options.signal);
+        return reply.agents;
+    }
+    /** One page of `list` (Host feature `session-reads`). */
+    async page(options = {}) {
+        await this.transport.requireFeature("session-reads", options.signal);
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        filterQuery(options, query);
+        return AgentPageSchema.parse(await this.transport.json(`/v1/agents?${query}`, "GET", undefined, options.signal));
+    }
+    /** Stops a pod Agent's compute: its volume is kept, and the next turn starts it again. */
+    async stop(agentId, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/stop`, "POST", {}, options.signal);
+    }
+    /**
+     * Applies a version the Agent waits to apply (`POST /v1/agents/{id}/restart`): a
+     * running pod stops, so the next turn starts it on the version; a stopped one starts at once.
+     * `retry` first moves it to the version that failed to start again. Refused during a turn.
+     */
+    async restart(agentId, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/restart`, "POST", { requestId: id(), ...(options.retry ? { retry: true } : {}) }, options.signal);
+    }
+    /** Resets a pod Agent: a new pod on a new, empty volume, with its runtime section applied. */
+    async reset(agentId, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/reset`, "POST", {}, options.signal);
+    }
+    /**
+     * Keeps a version of the Agent's disk (`POST /v1/agents/{id}/snapshot`), between turns;
+     * `unchanged` when the disk is as the latest version has it.
+     */
+    async snapshot(agentId, options = {}) {
+        await this.transport.requireFeature("environment-disk-versions", options.signal);
+        return this.transport.json(`${this.path(agentId)}/snapshot`, "POST", {}, options.signal);
+    }
+    /**
+     * Puts disk version `version` back: at once for a virtual Agent (`done`), on a new volume
+     * seeded before the next turn for a pod (`pending`).
+     */
+    async restore(agentId, version, options = {}) {
+        await this.transport.requireFeature("environment-disk-versions", options.signal);
+        return this.transport.json(`${this.path(agentId)}/restore`, "POST", { requestId: id(), version }, options.signal);
+    }
+    /**
+     * Forks the Agent into a new one, `options.id`: how an Agent changes what is fixed for its
+     * life (its manifest, kind, harness or storage). It is made from `options.manifest` (default the source's manifest,
+     * tracking), its disk starts from `options.disk` (`latest`, the default, snapshots first; a
+     * version; or `empty`) and the secrets the new manifest declares are copied
+     * (`options.secrets: "none"` copies none). The source keeps what it runs, its disk and its
+     * sessions. Answers the new Agent and the plan it ran.
+     */
+    async fork(agentId, options) {
+        const { signal, ...body } = options;
+        return this.transport.json(`${this.path(agentId)}/fork`, "POST", { requestId: id(), ...body }, signal);
+    }
+    /** What `fork` would do (the disk, the secrets copied and left behind, the changes), making nothing. */
+    async planFork(agentId, options) {
+        const { signal, ...body } = options;
+        const answer = await this.transport.json(`${this.path(agentId)}/fork`, "POST", { ...body, dryRun: true }, signal);
+        return answer.plan;
+    }
+    /** The Agent's disk versions, newest first. */
+    async versions(agentId, options = {}) {
+        await this.transport.requireFeature("environment-disk-versions", options.signal);
+        return this.transport.json(`${this.path(agentId)}/versions`, "GET", undefined, options.signal);
+    }
+    /** Deletes disk version `version`; `deleted` is false when there was none. */
+    async deleteVersion(agentId, version, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/versions/${version}`, "DELETE", undefined, options.signal);
+    }
+    /** Deletes the Agent, its vault and its files; `deleted` is false when there was none. */
+    async delete(agentId, options = {}) {
+        return this.transport.json(this.path(agentId), "DELETE", undefined, options.signal);
+    }
+    /**
+     * The Agent's events, from `from` on: its lifecycle, and `agent.egress` for every connection
+     * its sandbox opens (with the turns that were running). `types` keeps only those types;
+     * `since` and `until` keep events recorded in that window (ISO times or `Date`s).
+     */
+    async events(agentId, options = {}) {
+        const query = new URLSearchParams();
+        if (options.from !== undefined)
+            query.set("from", String(options.from));
+        if (options.types !== undefined && options.types.length > 0)
+            query.set("types", options.types.join(","));
+        const iso = (at) => (at instanceof Date ? at.toISOString() : at);
+        if (options.since !== undefined)
+            query.set("since", iso(options.since));
+        if (options.until !== undefined)
+            query.set("until", iso(options.until));
+        const search = query.toString();
+        const reply = await this.transport.json(`${this.path(agentId)}/events${search === "" ? "" : `?${search}`}`, "GET", undefined, options.signal);
+        return reply.events;
+    }
+    /** The Agent's triggers: each one's status (`active`, `paused`, `completed`), next and last run. */
+    async triggers(agentId, options = {}) {
+        const reply = await this.transport.json(`${this.path(agentId)}/triggers`, "GET", undefined, options.signal);
+        return reply.triggers;
+    }
+    /** Pauses trigger `triggerId`: it stops firing until it is resumed. Answers the Agent's triggers. */
+    async pauseTrigger(agentId, triggerId, options = {}) {
+        const reply = await this.transport.json(`${this.path(agentId)}/triggers/${segment(triggerId)}/pause`, "POST", {}, options.signal);
+        return reply.triggers;
+    }
+    /** Resumes trigger `triggerId` from its next time after now. Answers the Agent's triggers. */
+    async resumeTrigger(agentId, triggerId, options = {}) {
+        const reply = await this.transport.json(`${this.path(agentId)}/triggers/${segment(triggerId)}/resume`, "POST", {}, options.signal);
+        return reply.triggers;
+    }
+    /**
+     * Runs trigger `triggerId` once now, as if it fired: `idempotencyKey` (default a new one) makes a
+     * retried call answer the same run.
+     */
+    async runTrigger(agentId, triggerId, options = {}) {
+        const response = await this.transport.request(`${this.path(agentId)}/triggers/${segment(triggerId)}/run`, {
+            method: "POST",
+            headers: { "idempotency-key": options.idempotencyKey ?? id() },
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        return (await response.json()).run;
+    }
+    /**
+     * A new Standard Webhooks signing secret for webhook trigger `triggerId` (`whsec_…`), shown this
+     * once with the trigger's `webhookUrl`; the one before stops working at once.
+     */
+    async rotateWebhookSecret(agentId, triggerId, options = {}) {
+        return this.transport.json(`${this.path(agentId)}/triggers/${segment(triggerId)}/secret`, "POST", {}, options.signal);
+    }
+    /** The Agent's runs, newest first; `triggerId` keeps one trigger's. */
+    async runs(agentId, options = {}) {
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.triggerId !== undefined)
+            query.set("triggerId", options.triggerId);
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        return this.transport.json(`${this.path(agentId)}/runs?${query}`, "GET", undefined, options.signal);
+    }
+}

package/dist/artifacts.d.ts

@@ -5,7 +5,7 @@
  * short-lived URL that needs no credential, for `<img>` tags and sharing. A message names an
  * artifact in a file part (`session.inputParts`), and the model reads it.
  *
- * Folders (F8.2): at the end of each turn the Runtime exports `/workspace/outputs` of the
+ * Folders: at the end of each turn the Runtime exports `/workspace/outputs` of the
  * session's sandbox as a version of its `outputs` folder. Read one as a tree, one file by path,
  * a diff between versions or a zip.
  *

package/dist/artifacts.js

@@ -5,7 +5,7 @@
  * short-lived URL that needs no credential, for `<img>` tags and sharing. A message names an
  * artifact in a file part (`session.inputParts`), and the model reads it.
  *
- * Folders (F8.2): at the end of each turn the Runtime exports `/workspace/outputs` of the
+ * Folders: at the end of each turn the Runtime exports `/workspace/outputs` of the
  * session's sandbox as a version of its `outputs` folder. Read one as a tree, one file by path,
  * a diff between versions or a zip.
  *

package/dist/compose.d.ts

@@ -0,0 +1,23 @@
+import { type ComposedManifest } from "./agent-manifests.js";
+/** The file `composeManifest` reads in a folder. */
+export declare const AGENT_MANIFEST_FILE = "agent.manifest.json";
+/** An authoring file that cannot be read or does not validate; `path` names it. */
+export declare class ComposeError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/**
+ * Composes the agent manifest in `dir` (its `agent.manifest.json`, or `options.file`): the v8
+ * document to save, the bytes of every file it names by hash (skills, plugins' skills, runtime
+ * files) for `client.agentManifests.save` to upload, its gaps (the harness file's `requires`
+ * the runtime misses, and `sectionGaps`, which the Runtime would refuse it for), and the skills
+ * and servers skipped. Throws `ComposeError` for a file that cannot be read or does not validate.
+ */
+export declare function composeManifest(dir: string, options?: {
+    file?: string;
+}): Promise<ComposedManifest>;
+/**
+ * The folders `nylorun apply` composes for `dir`: `dir` itself when it holds an
+ * `agent.manifest.json`, else each of its subfolders that does, by name.
+ */
+export declare function manifestFolders(dir: string): Promise<string[]>;

package/dist/compose.js

@@ -0,0 +1,257 @@
+/**
+ * Three-file authoring (protocol 16): `composeManifest(dir)` reads `agent.manifest.json`
+ * and the files it names, and makes the one agent manifest v8 document the Runtime saves, with
+ * the bytes of every file it names by hash. `nylorun apply` runs it for each folder.
+ *
+ * - `agent.manifest.json` (`AgentManifestFileSchema`): the manifest's name, description and
+ *   metadata, with `harness` and `runtime` inline or as paths to the two files below.
+ * - `harness.manifest.json` (`HarnessManifestFileSchema`): the harness section, whose `skills`
+ *   may be a folder of skill folders (each skill's `secrets` from its SKILL.md's frontmatter),
+ *   `mcpServers` an `mcp.json` (the Agent Plugins format), and
+ *   `plugins` Agent Plugin folders, folded in as `.plugin()` folds them; `credentials` names the
+ *   `runtime.secrets` slot each MCP server or HTTP tool authenticates with; `requires` is checked
+ *   against the runtime section here, since the API never sees it.
+ * - `runtime.manifest.json` (`RuntimeManifestFileSchema`): the runtime section, often shared by
+ *   many agents; a `files` entry `{ path, from }` is a folder beside the file, hashed into
+ *   `{ path, files }`.
+ *
+ * Each path is relative to the file that names it. Node only: it reads the files.
+ */
+import { existsSync, statSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { AGENT_MANIFEST_V8_SCHEMA_VERSION, AgentManifestFileSchema, AgentManifestV8Schema, HarnessManifestFileSchema, RuntimeManifestFileSchema, WorkflowHarnessSectionSchema, } from "@nylorun/core/contracts";
+import { sectionGaps } from "@nylorun/core/define";
+import { requirementGaps } from "./agent-manifests.js";
+import { loadMcpServers, loadPlugin } from "./plugins/load.js";
+import { hashFolder, loadSkillsFromDirectory } from "./skills/load.js";
+/** The file `composeManifest` reads in a folder. */
+export const AGENT_MANIFEST_FILE = "agent.manifest.json";
+/** An authoring file that cannot be read or does not validate; `path` names it. */
+export class ComposeError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.path = path;
+        this.name = "ComposeError";
+    }
+}
+/** The JSON file at `path`, as `schema` parses it, or a `ComposeError` naming every issue. */
+async function readFileAs(path, schema, where) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new ComposeError(path, `Cannot read ${where}: ${error.code ?? error}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ComposeError(path, `${where} is not JSON: ${error.message}`);
+    }
+    return parsedAs(value, schema, path, where);
+}
+function parsedAs(value, schema, path, where) {
+    const parsed = schema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    const issues = parsed.error.issues.map((issue) => `  ${issue.path.length ? `${issue.path.map(String).join(".")}: ` : ""}${issue.message}`);
+    throw new ComposeError(path, `${where} is not valid:\n${issues.join("\n")}`);
+}
+const isWorkflow = (value) => !!value && typeof value === "object" && value.kind === "workflow";
+/** `$schema` dropped: it is for editors. */
+function withoutSchema(value) {
+    const { $schema: _, ...rest } = value;
+    return rest;
+}
+/** Reads the runtime section, its `{ path, from }` files hashed into `{ path, files }`. */
+async function runtimeSection(runtime, base, agentFile, files, warnings) {
+    const file = typeof runtime === "string" ? resolve(base, runtime) : agentFile;
+    const parsed = typeof runtime === "string"
+        ? await readFileAs(file, RuntimeManifestFileSchema, relativeTo(file))
+        : parsedAs(runtime, RuntimeManifestFileSchema, file, `${relativeTo(file)} runtime`);
+    const at = dirname(file);
+    const entries = [];
+    for (const entry of parsed.files ?? []) {
+        if (!("from" in entry)) {
+            entries.push(entry);
+            continue;
+        }
+        const folder = resolve(at, entry.from);
+        if (!existsSync(folder) || !statSync(folder).isDirectory())
+            throw new ComposeError(file, `runtime.files: ${entry.from} (for ${entry.path}) is not a folder beside ${relativeTo(file)}`);
+        const diagnostics = [];
+        const hashed = hashFolder(folder, diagnostics);
+        warnings.push(...warningsOf(diagnostics));
+        if (Object.keys(hashed.files).length === 0)
+            throw new ComposeError(file, `runtime.files: ${entry.from} (for ${entry.path}) holds no files`);
+        for (const [sha256, source] of Object.entries(hashed.sources))
+            files.set(sha256, source);
+        entries.push({ path: entry.path, files: { ...hashed.files } });
+    }
+    const section = withoutSchema(parsed);
+    return { ...section, ...(parsed.files === undefined ? {} : { files: entries }) };
+}
+function warningsOf(diagnostics) {
+    return diagnostics.filter((item) => item.severity === "warning").map((item) => item.message);
+}
+/** `path` relative to the working directory, as a person reads it. */
+function relativeTo(path) {
+    return relative(process.cwd(), path) || path;
+}
+/** A skill read from its folder as the harness section declares it, with its SKILL.md's `secrets`. */
+function harnessSkill(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        files: { ...skill.files },
+        ...(skill.secrets === undefined ? {} : { secrets: [...skill.secrets] }),
+    };
+}
+/** The agent harness section a `harness.manifest.json` describes, its paths resolved. */
+function agentHarness(file, base, where, files, warnings) {
+    const skills = {};
+    const servers = {};
+    const plugins = [];
+    const addSkill = (skill, from) => {
+        if (skills[skill.name])
+            throw new ComposeError(where, `Skill ${skill.name} of ${from} is declared twice`);
+        skills[skill.name] = skill;
+    };
+    const addServer = (key, server, from) => {
+        if (servers[key])
+            throw new ComposeError(where, `MCP server ${key} of ${from} is declared twice`);
+        servers[key] = server;
+    };
+    // Skills: a folder of skill folders, each hashed as `.skills()` hashes it.
+    if (typeof file.skills === "string") {
+        const diagnostics = [];
+        for (const skill of Object.values(loadSkillsFromDirectory(resolve(base, file.skills), diagnostics))) {
+            addSkill(harnessSkill(skill), file.skills);
+            for (const [sha256, source] of Object.entries(skill.sources))
+                files.set(sha256, source);
+        }
+        warnings.push(...warningsOf(diagnostics));
+    }
+    else
+        for (const skill of Object.values(file.skills ?? {}))
+            addSkill(skill, where);
+    // MCP servers: an `mcp.json` in the Agent Plugins format.
+    if (typeof file.mcpServers === "string") {
+        const path = resolve(base, file.mcpServers);
+        if (!existsSync(path))
+            throw new ComposeError(where, `mcpServers: ${file.mcpServers} does not exist`);
+        const diagnostics = [];
+        const loaded = loadMcpServers(path, diagnostics, { codePrefix: "harness" });
+        const invalid = diagnostics.find((item) => item.code === "harness.mcp-invalid");
+        if (invalid)
+            throw new ComposeError(path, `mcpServers: ${invalid.message}`);
+        warnings.push(...warningsOf(diagnostics));
+        for (const [key, server] of Object.entries(loaded))
+            addServer(key, server, file.mcpServers);
+    }
+    else
+        for (const [key, server] of Object.entries(file.mcpServers ?? {}))
+            addServer(key, server, where);
+    // Plugins: a folder is folded in as `.plugin()` folds it, each part labelled with the plugin.
+    for (const entry of file.plugins ?? []) {
+        if (typeof entry !== "string") {
+            plugins.push(entry);
+            continue;
+        }
+        const loaded = loadPlugin(resolve(base, entry));
+        warnings.push(...warningsOf(loaded.diagnostics).map((message) => `Plugin '${loaded.name}': ${message}`));
+        const label = { name: loaded.name, ...(loaded.version === undefined ? {} : { version: loaded.version }) };
+        for (const skill of Object.values(loaded.skills)) {
+            addSkill({ ...harnessSkill(skill), plugin: label }, entry);
+            for (const [sha256, source] of Object.entries(skill.sources))
+                files.set(sha256, source);
+        }
+        for (const [key, server] of Object.entries(loaded.mcpServers))
+            addServer(key, { ...server, plugin: label }, entry);
+        plugins.push(label);
+    }
+    // Credentials: the slot each server or HTTP tool authenticates with.
+    let tools = file.tools;
+    for (const [name, slot] of Object.entries(file.credentials ?? {})) {
+        const server = servers[name];
+        const tool = tools?.find((item) => item.name === name && item.http !== undefined);
+        if (!server && !tool)
+            throw new ComposeError(where, `credentials names ${name}, which is no MCP server or HTTP tool of the harness`);
+        if (server)
+            servers[name] = { ...server, credential: slot };
+        if (tool)
+            tools = tools.map((item) => (item === tool ? { ...item, http: { ...item.http, credential: slot } } : item));
+    }
+    return {
+        ...(file.id === undefined ? {} : { id: file.id }),
+        ...(file.instructions === undefined ? {} : { instructions: file.instructions }),
+        ...(tools === undefined ? {} : { tools }),
+        ...(Object.keys(skills).length === 0 ? {} : { skills }),
+        ...(Object.keys(servers).length === 0 ? {} : { mcpServers: servers }),
+        ...(plugins.length === 0 ? {} : { plugins }),
+        ...(file.outputSchema === undefined ? {} : { outputSchema: file.outputSchema }),
+        ...(file.loop === undefined ? {} : { loop: file.loop }),
+        ...(file.memory === undefined ? {} : { memory: file.memory }),
+    };
+}
+/**
+ * Composes the agent manifest in `dir` (its `agent.manifest.json`, or `options.file`): the v8
+ * document to save, the bytes of every file it names by hash (skills, plugins' skills, runtime
+ * files) for `client.agentManifests.save` to upload, its gaps (the harness file's `requires`
+ * the runtime misses, and `sectionGaps`, which the Runtime would refuse it for), and the skills
+ * and servers skipped. Throws `ComposeError` for a file that cannot be read or does not validate.
+ */
+export async function composeManifest(dir, options = {}) {
+    const agentFile = resolve(dir, options.file ?? AGENT_MANIFEST_FILE);
+    const base = dirname(agentFile);
+    const authored = await readFileAs(agentFile, AgentManifestFileSchema, relativeTo(agentFile));
+    const files = new Map();
+    const warnings = [];
+    const runtime = authored.runtime === undefined ? undefined : await runtimeSection(authored.runtime, base, agentFile, files, warnings);
+    let harness;
+    let requires;
+    const harnessFile = typeof authored.harness === "string" ? resolve(base, authored.harness) : agentFile;
+    const where = relativeTo(harnessFile);
+    const raw = typeof authored.harness === "string"
+        ? await readFileAs(harnessFile, { safeParse: (value) => ({ success: true, data: value }) }, where)
+        : authored.harness;
+    if (isWorkflow(raw)) {
+        // A flow: its agents are embedded, with their skills by hash; nothing to resolve.
+        harness = parsedAs(withoutSchema(raw), WorkflowHarnessSectionSchema, harnessFile, where);
+    }
+    else {
+        const file = parsedAs(raw, HarnessManifestFileSchema, harnessFile, where);
+        requires = file.requires;
+        harness = agentHarness(file, dirname(harnessFile), where, files, warnings);
+    }
+    const manifest = parsedAs({
+        manifestSchemaVersion: AGENT_MANIFEST_V8_SCHEMA_VERSION,
+        name: authored.name,
+        ...(authored.description === undefined ? {} : { description: authored.description }),
+        ...(authored.metadata === undefined ? {} : { metadata: authored.metadata }),
+        harness,
+        ...(runtime === undefined ? {} : { runtime }),
+    }, AgentManifestV8Schema, agentFile, `The agent manifest ${authored.name}`);
+    const gaps = [...requirementGaps(requires, manifest.runtime).map((gap) => `harness.${gap}`), ...sectionGaps(manifest)];
+    return { manifest, files, gaps, warnings };
+}
+/**
+ * The folders `nylorun apply` composes for `dir`: `dir` itself when it holds an
+ * `agent.manifest.json`, else each of its subfolders that does, by name.
+ */
+export async function manifestFolders(dir) {
+    const root = resolve(dir);
+    if (existsSync(join(root, AGENT_MANIFEST_FILE)))
+        return [root];
+    const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+        throw new ComposeError(root, `Cannot read ${dir}: ${error.code ?? error}`);
+    });
+    return entries
+        .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, AGENT_MANIFEST_FILE)))
+        .map((entry) => join(root, entry.name))
+        .sort();
+}

package/dist/files.d.ts

@@ -1,8 +1,8 @@
 /**
- * Definition files (track R2 M4): `client.files`. A definition names the files it needs by the
+ * Definition files: `client.files`. A definition names the files it needs by the
  * SHA-256 of their bytes (a skill's folder, `SkillManifest.files`); the Runtime holds each one
- * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a definition naming a file it
- * does not hold (`400 definition_files_missing`). `saveAgent` uploads an agent's files itself.
+ * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a manifest naming a file it
+ * does not hold (`400 definition_files_missing`). `agentManifests.save` uploads them itself.
  */
 import { type DefinitionFileView } from "@nylorun/core/contracts";
 import type { SkillFileSource } from "@nylorun/core/define";

package/dist/files.js

@@ -1,8 +1,8 @@
 /**
- * Definition files (track R2 M4): `client.files`. A definition names the files it needs by the
+ * Definition files: `client.files`. A definition names the files it needs by the
  * SHA-256 of their bytes (a skill's folder, `SkillManifest.files`); the Runtime holds each one
- * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a definition naming a file it
- * does not hold (`400 definition_files_missing`). `saveAgent` uploads an agent's files itself.
+ * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a manifest naming a file it
+ * does not hold (`400 definition_files_missing`). `agentManifests.save` uploads them itself.
  */
 import { isDefinitionFileHash, } from "@nylorun/core/contracts";
 import { RuntimeError } from "./http.js";