nylorun 0.16.0-beta → 0.18.0-beta

package/dist/client/apply.js

@@ -0,0 +1,99 @@
+/**
+ * `nylorun apply [dir…]`: saves the agent manifest each folder describes (protocol 16, track T2),
+ * through the Runtime API. A folder's `agent.manifest.json` names its harness and runtime files;
+ * `composeManifest` (`@nylorun/agents`) resolves them, hashes the skills, plugins and runtime
+ * 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/`).
+ */
+import { resolve } from "node:path";
+import { ComposeError, PluginError, SkillsError, composeManifest, manifestFolders, } from "@nylorun/agents";
+import { CliError } from "../errors.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.
+
+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
+  --if-match <n>                      save only over version n (one folder)
+
+${runtimeFlagsUsage}`;
+/** What a folder could not be composed for, as a person reads it. */
+function composeFailure(folder, error) {
+    if (error instanceof ComposeError || error instanceof SkillsError || error instanceof PluginError || error instanceof TypeError)
+        throw new CliError(`${folder}: ${error.message}`, 1);
+    throw error;
+}
+/** A plan as lines: the move, then each change, warning and error. */
+export function planLines(plan) {
+    const move = plan.unchanged
+        ? `unchanged at version ${plan.to}`
+        : plan.from === null
+            ? `new, version ${plan.to}`
+            : `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.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") {
+        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 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));
+        if (found.length === 0)
+            throw usageError(`${dir} holds no 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);
+    let blocked = false;
+    for (const { manifest } of composed) {
+        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 }));
+        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)
+            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 (blocked)
+        deps.err("Nothing was saved for a manifest with errors.");
+    return blocked ? 1 : 0;
+}

package/dist/client/artifacts.js

@@ -1,7 +1,7 @@
 /**
  * `nylorun artifacts`: the Tenant's file artifacts (`/v1/artifacts`, Runtime API): upload a file
  * (to name in a message with `sessions send --file`), list, download, browse a folder artifact
- * (an Environment's disk), share a version with a capability link, and delete.
+ * (an Agent's disk versions), share a version with a capability link, and delete.
  */
 import { createWriteStream } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -62,8 +62,8 @@ async function list(deps, args) {
                 String(item.latestVersion),
                 item.sessionId
                     ? `session ${item.sessionId}`
-                    : item.environmentId
-                        ? `environment ${item.environmentId}`
+                    : item.agentId
+                        ? `agent ${item.agentId}`
                         : "tenant",
             ]),
         ]);

package/dist/client/doctor.d.ts

@@ -12,7 +12,7 @@ export type SandboxReport = {
         version?: string;
     }[];
     defaultImage?: string;
-    /** The Tenant's Environment settings in force (`environments.config`, protocol 11). */
+    /** The Tenant's settings for Agents' environments in force (`environments.config`). */
     config?: {
         limits?: {
             network?: readonly string[];

package/dist/client/doctor.js

@@ -45,7 +45,7 @@ export async function doctorSandbox(deps, options) {
     ]);
     rows.push([
         "sessions",
-        "get a sandbox only on an Environment (createSession({ environment }) names one)",
+        "run on an Agent, with the sandbox its manifest's runtime.kind gives (createSession({ agent }))",
     ]);
     const limits = report.config?.limits;
     if (limits)
@@ -53,7 +53,7 @@ export async function doctorSandbox(deps, options) {
             "limits",
             [
                 limits.idle ? `idle ${limits.idle}` : undefined,
-                limits.environments === undefined ? undefined : `${limits.environments} environments`,
+                limits.environments === undefined ? undefined : `${limits.environments} Agents`,
                 limits.network ? `${limits.network.length} allowed hosts` : undefined,
             ]
                 .filter((item) => item !== undefined)

package/dist/client/io.d.ts

@@ -14,6 +14,8 @@ export interface BodySchema<T> {
         };
     };
 }
+/** The text in file `source`, or on standard input for `-`, as it is. */
+export declare function readText(deps: StackDeps, source: string): Promise<string>;
 /**
  * The JSON body in file `source`, or on standard input for `-`, as `schema` parses it. Fields
  * named in `readOnly` (a view's, so a `get` can be edited and put back) are dropped first. A

package/dist/client/io.js

@@ -13,6 +13,17 @@ async function readStdin(deps, refusal) {
         throw usageError(refusal);
     return await deps.stdin.text();
 }
+/** The text in file `source`, or on standard input for `-`, as it is. */
+export async function readText(deps, source) {
+    if (source === "-")
+        return readStdin(deps, "Pipe the text in on standard input, or name a file.");
+    try {
+        return await readFile(resolve(deps.cwd ?? process.cwd(), source), "utf8");
+    }
+    catch (error) {
+        throw usageError(`Cannot read ${source}: ${error.code ?? error}.`);
+    }
+}
 /**
  * The JSON body in file `source`, or on standard input for `-`, as `schema` parses it. Fields
  * named in `readOnly` (a view's, so a `get` can be edited and put back) are dropped first. A

package/dist/client/mcp.d.ts

@@ -1,11 +1,13 @@
 import type { McpPreview } from "@nylorun/core/contracts";
 import { type StackDeps } from "../stack/commands.js";
-export declare const mcpUsage = "  mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]\n                                      list a remote MCP server's tools, with Environment <id>'s\n                                      credential for <url> (none without it): model names, schema\n                                      sizes, renames, or that it needs a person's sign-in (the\n                                      Runtime calls no tool)";
+export declare const mcpUsage = "  mcp inspect <url> [--server <name>] [--agent <id>] [--sse] [--tenant <name>] [--json]\n                                      list a remote MCP server's tools, with Agent <id>'s\n                                      credential for <url> (none without it): model names, schema\n                                      sizes, renames, or that it needs a person's sign-in (the\n                                      Runtime calls no tool)";
 /** What `--vault` says since protocol 11. */
-export declare const MCP_VAULT_REMOVED = "--vault was removed in protocol 11: a credential is a secret of an Environment, in its own vault. Pass --environment <id> to send that Environment's credential for the URL.";
+export declare const MCP_VAULT_REMOVED = "--vault was removed in protocol 11: a credential is a secret of an Agent, in its own vault. Pass --agent <id> to send that Agent's credential for the URL.";
+/** What `--environment` says since protocol 16. */
+export declare const MCP_ENVIRONMENT_REMOVED = "--environment was removed in protocol 16: Environments are Agents. Pass --agent <id> to send that Agent's credential for the URL.";
 /** What the removed `connect` subcommand says since protocol 10. */
 export declare const MCP_CONNECT_REMOVED: string;
 /** A preview as a person reads it: the server, a table of tools, the renames, or the sign-in hint. */
-export declare function previewLines(preview: McpPreview, environmentId?: string): string[];
+export declare function previewLines(preview: McpPreview, agentId?: string): string[];
 /** `nylorun tenant mcp <inspect|connect> ...` */
 export declare function mcpCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/mcp.js

@@ -1,38 +1,43 @@
 /**
  * `nylorun tenant mcp inspect <url>`: a remote MCP server's tools before an agent names it (R2b
  * C12), through the Management API (`POST /v1/tenant/mcp/preview`) of the installation
- * `target.ts` picks. It never starts a local Tenant, and the Runtime never calls a tool. `--environment <id>` sends that Environment's
- * credential for the URL (protocol 11; it replaced `--vault`); an Environment's secrets are
- * written on the Runtime API (`client.environments.secrets.put` of `@nylorun/agents`). Its
- * `connect` subcommand (MCP OAuth) was removed in protocol 10, and says so.
+ * `target.ts` picks. It never starts a local Tenant, and the Runtime never calls a tool. `--agent <id>`
+ * sends that Agent's credential for the URL (protocol 16; it replaced `--environment`, which
+ * replaced `--vault`); an Agent's secrets are written on the Runtime API
+ * (`client.agents.secrets.put` of `@nylorun/agents`). Its `connect` subcommand (MCP OAuth) was
+ * removed in protocol 10, and says so.
  */
 import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
-import { CliError } from "../errors.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { connect } from "./target.js";
-export const mcpUsage = `  mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]
-                                      list a remote MCP server's tools, with Environment <id>'s
+export const mcpUsage = `  mcp inspect <url> [--server <name>] [--agent <id>] [--sse] [--tenant <name>] [--json]
+                                      list a remote MCP server's tools, with Agent <id>'s
                                       credential for <url> (none without it): model names, schema
                                       sizes, renames, or that it needs a person's sign-in (the
                                       Runtime calls no tool)`;
-const INSPECT_USAGE = "nylorun tenant mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]";
-/** Where a credential for an MCP server goes since protocol 11. */
-const SECRET_HINT = "write it as a bearer or headers secret of an Environment (nylorun environments secrets put, client.environments.secrets.put of @nylorun/agents, or Studio)";
+const INSPECT_USAGE = "nylorun tenant mcp inspect <url> [--server <name>] [--agent <id>] [--sse] [--tenant <name>] [--json]";
+/** Where a credential for an MCP server goes since protocol 16. */
+const SECRET_HINT = "write it as a bearer or headers secret of an Agent (nylorun agents secrets put, client.agents.secrets.put of @nylorun/agents, or Studio)";
 /** What `--vault` says since protocol 11. */
-export const MCP_VAULT_REMOVED = "--vault was removed in protocol 11: a credential is a secret of an Environment, in its own vault. Pass --environment <id> to send that Environment's credential for the URL.";
+export const MCP_VAULT_REMOVED = "--vault was removed in protocol 11: a credential is a secret of an Agent, in its own vault. Pass --agent <id> to send that Agent's credential for the URL.";
+/** What `--environment` says since protocol 16. */
+export const MCP_ENVIRONMENT_REMOVED = "--environment was removed in protocol 16: Environments are Agents. Pass --agent <id> to send that Agent's credential for the URL.";
 /** What the removed `connect` subcommand says since protocol 10. */
-export const MCP_CONNECT_REMOVED = `The connect subcommand of nylorun mcp was removed with MCP OAuth (protocol 10): ${SECRET_HINT.replace("write it", "write the server's key")}, or reach a server that needs a person's sign-in through a gateway (a secret with via). See its tools with nylorun tenant mcp inspect <url> --environment <id>.`;
+export const MCP_CONNECT_REMOVED = `The connect subcommand of nylorun mcp was removed with MCP OAuth (protocol 10): ${SECRET_HINT.replace("write it", "write the server's key")}, or reach a server that needs a person's sign-in through a gateway (a secret with via). See its tools with nylorun tenant mcp inspect <url> --agent <id>.`;
 const DESCRIPTION_CHARS = 60;
 const usageError = (message) => new CliError(message, 2);
 async function inspect(deps, args) {
     if (args.some((arg) => arg === "--vault" || arg.startsWith("--vault=")))
         throw usageError(MCP_VAULT_REMOVED);
-    const flags = parseStackFlags(args, { booleans: ["--json", "--sse"], values: ["--server", "--environment", "--tenant"] }, INSPECT_USAGE);
+    if (args.some((arg) => arg === "--environment" || arg.startsWith("--environment=")))
+        throw usageError(MCP_ENVIRONMENT_REMOVED);
+    const flags = parseStackFlags(args, { booleans: ["--json", "--sse"], values: ["--server", "--agent", "--tenant"] }, INSPECT_USAGE);
     if (flags.rest.length !== 1)
         throw usageError(`Usage: ${INSPECT_USAGE}`);
     const url = flags.rest[0];
     const name = flags.values.get("--server");
-    const environmentId = flags.values.get("--environment");
+    const agentId = flags.values.get("--agent");
     const tenant = flags.values.get("--tenant");
     const api = await connect(deps, "management", tenant);
     if (!api.managementKey)
@@ -49,7 +54,7 @@ async function inspect(deps, args) {
             url,
             ...(flags.booleans.has("--sse") ? { type: "sse" } : {}),
             ...(name === undefined ? {} : { name }),
-            ...(environmentId === undefined ? {} : { environmentId }),
+            ...(agentId === undefined ? {} : { agentId }),
         }),
         // The Runtime bounds the preview (its Runtime limit mcpPreviewMs, each step); the CLI waits.
         redirect: "error",
@@ -69,17 +74,17 @@ async function inspect(deps, args) {
         deps.out(JSON.stringify(preview, null, 2));
         return 0;
     }
-    for (const line of previewLines(preview, environmentId))
+    for (const line of previewLines(preview, agentId))
         deps.out(line);
     return 0;
 }
 /** A preview as a person reads it: the server, a table of tools, the renames, or the sign-in hint. */
-export function previewLines(preview, environmentId) {
+export function previewLines(preview, agentId) {
     const credential = preview.credentialSent
-        ? `with Environment ${environmentId ?? "(unnamed)"}'s credential`
-        : environmentId === undefined
-            ? "with no credential (pass --environment <id> to send an Environment's)"
-            : `with no credential (Environment ${environmentId} holds none for this URL)`;
+        ? `with Agent ${agentId ?? "(unnamed)"}'s credential`
+        : agentId === undefined
+            ? "with no credential (pass --agent <id> to send an Agent's)"
+            : `with no credential (Agent ${agentId} holds none for this URL)`;
     if (preview.authRequired) {
         const metadata = preview.authRequired.resourceMetadata;
         const servers = Array.isArray(metadata?.authorization_servers)
@@ -87,13 +92,13 @@ export function previewLines(preview, environmentId) {
             : [];
         return [
             preview.credentialSent
-                ? `The MCP server at ${preview.url} answered 401: it rejected Environment ${environmentId ?? "(unnamed)"}'s credential.`
+                ? `The MCP server at ${preview.url} answered 401: it rejected Agent ${agentId ?? "(unnamed)"}'s credential.`
                 : `The MCP server at ${preview.url} answered 401: it needs a credential.`,
             ...(servers.length > 0
                 ? [`It signs people in with ${servers.join(", ")} (${preview.authRequired.resourceMetadataUrl}).`]
                 : []),
             `Nylorun holds no OAuth client: ${SECRET_HINT.replace("write it", "write the server's API key")},`,
-            "and pass --environment <id>; or reach it through a gateway that keeps each person's sign-in",
+            "and pass --agent <id>; or reach it through a gateway that keeps each person's sign-in",
             "(a secret with via and an identity header).",
         ];
     }
@@ -146,6 +151,8 @@ function oneLine(text) {
 /** `nylorun tenant mcp <inspect|connect> ...` */
 export async function mcpCommand(deps, args) {
     const [sub, ...rest] = args;
+    if (isHelp(sub))
+        throw new HelpRequest(`Usage:\n${mcpUsage}`);
     if (sub === "inspect")
         return inspect(deps, rest);
     if (sub === "connect")

package/dist/client/migrate.d.ts

@@ -0,0 +1,4 @@
+import { type StackDeps } from "../stack/commands.js";
+export declare const migrateUsage = "nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]\n\nWrites agent.manifest.json, harness.manifest.json and runtime.manifest.json (in --out, default\n.) from an agent manifest v7 or a workflow manifest v3, as nylorun agents save took it, and the\nenvironment manifest v1 its sessions ran in. Then save it with nylorun apply <dir>.\n\n  --runtime <file>                    the environment manifest: its fields become the runtime\n                                      section, its harness the harness file's id\n  --name <name>                       the manifest's name (default: the agent's id)\n  --out <dir>                         where the files are written; none is overwritten";
+/** `nylorun migrate v8 <agent.json> [--runtime <file>] [--name <name>] [--out <dir>]` */
+export declare function migrateCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/migrate.js

@@ -0,0 +1,140 @@
+/**
+ * `nylorun migrate v8 <agent.json>`: a one-off for protocol 16 (track T2). It writes the three
+ * authoring files `nylorun apply` reads from an agent manifest v7 (or a workflow manifest v3), as
+ * `agents save` took it, and the environment manifest v1 its sessions ran in, if any:
+ *
+ * - `agent.manifest.json`: the name (the v7 id), description and metadata, naming the two files;
+ * - `harness.manifest.json`: the loop (`harnessSectionOf`: instructions, tools, skills, MCP
+ *   servers, output schema, the plugins they came from), the environment manifest's `harness` as
+ *   `id`, and v7's `requires`, which the composer checks against the runtime;
+ * - `runtime.manifest.json`: the environment manifest's fields without its identity; with none,
+ *   kind `pod` when the agent requires one, `virtual` when it has skills or requires a sandbox,
+ *   else `none`.
+ *
+ * It writes nothing over an existing file, reads nothing from a Runtime, and prints the gaps
+ * `nylorun apply` would refuse, to fix in the files first.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { requirementGaps } from "@nylorun/agents";
+import { AgentManifestSchema, RuntimeManifestFileSchema, WorkflowManifestSchema, isAgentManifestName, } from "@nylorun/core/contracts";
+import { harnessSectionOf, sectionGaps } from "@nylorun/core/define";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { readJson, usageError } from "./runtime.js";
+export const migrateUsage = `nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]
+
+Writes agent.manifest.json, harness.manifest.json and runtime.manifest.json (in --out, default
+.) from an agent manifest v7 or a workflow manifest v3, as nylorun agents save took it, and the
+environment manifest v1 its sessions ran in. Then save it with nylorun apply <dir>.
+
+  --runtime <file>                    the environment manifest: its fields become the runtime
+                                      section, its harness the harness file's id
+  --name <name>                       the manifest's name (default: the agent's id)
+  --out <dir>                         where the files are written; none is overwritten`;
+const SCHEMAS = {
+    agent: "https://docs.nylorun.com/schemas/agent-manifest/v8.json",
+    harness: "https://docs.nylorun.com/schemas/harness-manifest/v1.json",
+    runtime: "https://docs.nylorun.com/schemas/runtime-manifest/v1.json",
+};
+/** Environment manifest v1's identity: the agent manifest holds it now, or nothing does. */
+const ENVIRONMENT_IDENTITY = ["$schema", "name", "description", "manifestSchemaVersion", "harness"];
+function issuesOf(error) {
+    return error.issues
+        .map((issue) => `  ${issue.path.length ? `${issue.path.map(String).join(".")}: ` : ""}${issue.message}`)
+        .join("\n");
+}
+/** The loop manifest in `path`: an agent manifest v7 or a workflow manifest v3. */
+async function loopManifest(path) {
+    const { $schema: _, ...raw } = await readJson(path, "The agent manifest");
+    const parsed = raw.kind === "workflow" ? WorkflowManifestSchema.safeParse(raw) : AgentManifestSchema.safeParse(raw);
+    if (!parsed.success)
+        throw usageError(`${path} is not an agent manifest v7 or a workflow manifest v3:\n${issuesOf(parsed.error)}`);
+    return parsed.data;
+}
+/** Whether a loop manifest, or an agent it embeds or delegates to, carries skills. */
+function hasSkills(loop) {
+    if ("kind" in loop)
+        return Object.values(loop.agents).some(hasSkills);
+    if (Object.keys(loop.skills ?? {}).length > 0)
+        return true;
+    return (loop.tools ?? []).some((tool) => tool.agent !== undefined && hasSkills(tool.agent));
+}
+/** `nylorun migrate v8 <agent.json> [--runtime <file>] [--name <name>] [--out <dir>]` */
+export async function migrateCommand(deps, args) {
+    const [version, ...rest] = args;
+    if (version === "--help" || version === "-h") {
+        deps.out(migrateUsage);
+        return 0;
+    }
+    if (version !== "v8")
+        throw usageError(version === undefined ? migrateUsage : `nylorun migrate knows v8 only.\n${migrateUsage}`);
+    const flags = parseStackFlags(rest, { values: ["--runtime", "--name", "--out"] }, migrateUsage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${migrateUsage.split("\n")[0]}`);
+    const cwd = deps.cwd ?? process.cwd();
+    const loop = await loopManifest(resolve(cwd, flags.rest[0]));
+    const name = flags.values.get("--name") ?? loop.id;
+    if (!isAgentManifestName(name))
+        throw usageError(`${name} is not an agent manifest's name (1-64 letters, digits, '.', '_' and '-', starting with a letter or digit): pass --name.`);
+    // The environment manifest: its fields are the runtime section, its harness the loop's.
+    let harnessId;
+    let runtime;
+    const runtimePath = flags.values.get("--runtime");
+    const requires = "kind" in loop ? undefined : loop.requires;
+    if (runtimePath !== undefined) {
+        const environment = await readJson(resolve(cwd, runtimePath), "The environment manifest");
+        if (typeof environment.harness === "string")
+            harnessId = environment.harness;
+        const fields = Object.fromEntries(Object.entries(environment).filter(([key]) => !ENVIRONMENT_IDENTITY.includes(key)));
+        // Environment manifest v1 made kind `virtual` when it named none.
+        const parsed = RuntimeManifestFileSchema.safeParse({ kind: "virtual", ...fields });
+        if (!parsed.success)
+            throw usageError(`${runtimePath} does not make a runtime section:\n${issuesOf(parsed.error)}`);
+        const { $schema: _, ...section } = parsed.data;
+        runtime = section;
+    }
+    else {
+        const kind = requires?.sandbox === "pod" ? "pod" : hasSkills(loop) || requires?.sandbox === "any" ? "virtual" : "none";
+        runtime = { kind };
+    }
+    const harness = harnessSectionOf(loop, harnessId === undefined ? {} : { harness: harnessId });
+    const out = resolve(cwd, flags.values.get("--out") ?? ".");
+    const files = {
+        "agent.manifest.json": {
+            $schema: SCHEMAS.agent,
+            manifestSchemaVersion: 8,
+            name,
+            ...(loop.description === undefined ? {} : { description: loop.description }),
+            ...(loop.metadata === undefined ? {} : { metadata: loop.metadata }),
+            harness: "./harness.manifest.json",
+            runtime: "./runtime.manifest.json",
+        },
+        // A flow's harness section is the flow itself; an agent's keeps `requires` for the composer.
+        "harness.manifest.json": {
+            ...("kind" in harness ? {} : { $schema: SCHEMAS.harness }),
+            ...harness,
+            ...(requires === undefined ? {} : { requires }),
+        },
+        "runtime.manifest.json": { $schema: SCHEMAS.runtime, ...runtime },
+    };
+    const existing = Object.keys(files).filter((file) => existsSync(join(out, file)));
+    if (existing.length > 0)
+        throw new CliError(`${relative(cwd, out) || "."} already holds ${existing.join(", ")}: nothing was written. Pass another --out.`, 1);
+    await mkdir(out, { recursive: true });
+    for (const [file, body] of Object.entries(files))
+        await writeFile(join(out, file), `${JSON.stringify(body, null, 2)}\n`);
+    const where = relative(cwd, out) || ".";
+    deps.out(`Wrote ${Object.keys(files).map((file) => join(where, file)).join(", ")}.`);
+    const gaps = [
+        ...requirementGaps(requires, runtime).map((gap) => `harness.${gap}`),
+        ...sectionGaps({ harness, runtime }),
+    ];
+    for (const gap of gaps)
+        deps.err(`  fix before apply: ${gap}`);
+    if (!("kind" in harness) && harness.skills !== undefined)
+        deps.err("  its skills stay inline, by hash: the Runtime must hold their files. To upload them from source, set harness.manifest.json skills to their folder.");
+    deps.err(`Save it with nylorun apply ${where}.`);
+    return 0;
+}

package/dist/client/model/pi-ai.d.ts

@@ -2,7 +2,7 @@
  * The pi-ai `nylorun tenant models set` loads; nylorun's devDependency has the same version
  * (scripts/check-package.mjs).
  */
-export declare const PI_AI_VERSION = "0.99.1";
+export declare const PI_AI_VERSION = "1.2.0";
 /** What `nylorun tenant models set` uses of pi-ai: its provider registry and login flows. */
 export interface PiAi {
     createProvider: typeof import("@earendil-works/pi-ai").createProvider;

package/dist/client/model/pi-ai.js

@@ -10,7 +10,7 @@ import { CliError } from "../../errors.js";
  * The pi-ai `nylorun tenant models set` loads; nylorun's devDependency has the same version
  * (scripts/check-package.mjs).
  */
-export const PI_AI_VERSION = "0.99.1";
+export const PI_AI_VERSION = "1.2.0";
 const PI_AI = "@earendil-works/pi-ai";
 /** The module written beside an on-demand install, which resolves pi-ai from there. */
 const ENTRY = "pi-ai.js";

package/dist/client/models.d.ts

@@ -1,9 +1,12 @@
 import { type StackDeps } from "../stack/commands.js";
 export declare const modelsUsage = "  models catalog [--tenant <name>] [--json]\n                                      every provider and model the Runtime knows\n  models providers [--tenant <name>] [--json]\n                                      the providers with a credential, and the one in use\n  models get [--tenant <name>] [--json]\n                                      the Tenant's model\n  models set [--tenant <name>]        sign in to a model provider and set the Tenant's model\n  models set --provider <id> --model <id> [--base-url <url>] [--tenant <name>]\n                                      the same with an API key piped in on stdin (CI)\n  models select <provider> [--model <id>] [--tenant <name>]\n                                      use a provider that has a credential (default: its model)";
-export declare const usageUsage = "  usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]\n                                      what the model calls used and cost (JSON)\n  calls [--after <cursor>] [--limit <n>] [--tenant <name>]\n                                      every recorded model call, one JSON line each, until\n                                      caught up; prints the cursor to resume from on stderr";
+export declare const usageUsage = "  usage [--scope tenant|manifest|turn] [--id <id>] [--period day|month|total] [--tenant <name>]\n                                      what the model calls used and cost (JSON); --scope\n                                      manifest: the Agents made from agent manifest <id>\n  calls [--after <cursor>] [--limit <n>] [--tenant <name>]\n                                      every recorded model call, one JSON line each, until\n                                      caught up; prints the cursor to resume from on stderr";
 /** `nylorun tenant models <verb> ...` */
 export declare function modelsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
-/** `nylorun tenant usage`: one scope's totals for one period, as JSON. */
+/**
+ * `nylorun tenant usage`: one scope's totals for one period, as JSON: the Tenant's, the Agents
+ * made from one agent manifest (`--scope manifest --id <name>`), or one turn's.
+ */
 export declare function usageCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
 /**
  * `nylorun tenant calls`: every recorded model call from `--after`, one JSON object per line

package/dist/client/models.js

@@ -5,7 +5,7 @@
  * for CI. A key is never an argument.
  */
 import { randomUUID } from "node:crypto";
-import { CliError } from "../errors.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { printJson, printTable, readSecret } from "./io.js";
 import { connect, managementClient } from "./target.js";
@@ -20,8 +20,9 @@ export const modelsUsage = `  models catalog [--tenant <name>] [--json]
                                       the same with an API key piped in on stdin (CI)
   models select <provider> [--model <id>] [--tenant <name>]
                                       use a provider that has a credential (default: its model)`;
-export const usageUsage = `  usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]
-                                      what the model calls used and cost (JSON)
+export const usageUsage = `  usage [--scope tenant|manifest|turn] [--id <id>] [--period day|month|total] [--tenant <name>]
+                                      what the model calls used and cost (JSON); --scope
+                                      manifest: the Agents made from agent manifest <id>
   calls [--after <cursor>] [--limit <n>] [--tenant <name>]
                                       every recorded model call, one JSON line each, until
                                       caught up; prints the cursor to resume from on stderr`;
@@ -139,6 +140,8 @@ async function select(deps, args) {
 /** `nylorun tenant models <verb> ...` */
 export async function modelsCommand(deps, args) {
     const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(`Usage:\n${modelsUsage}`);
     if (verb === "catalog" || verb === "providers" || verb === "get")
         return read(deps, verb, rest);
     if (verb === "set")
@@ -147,15 +150,20 @@ export async function modelsCommand(deps, args) {
         return select(deps, rest);
     throw usageError();
 }
-const SCOPES = ["tenant", "agent", "turn"];
+const SCOPES = ["tenant", "manifest", "turn"];
 const PERIODS = ["day", "month", "total"];
-const USAGE_USAGE = "nylorun tenant usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]";
-/** `nylorun tenant usage`: one scope's totals for one period, as JSON. */
+const USAGE_USAGE = "nylorun tenant usage [--scope tenant|manifest|turn] [--id <id>] [--period day|month|total] [--tenant <name>]";
+/**
+ * `nylorun tenant usage`: one scope's totals for one period, as JSON: the Tenant's, the Agents
+ * made from one agent manifest (`--scope manifest --id <name>`), or one turn's.
+ */
 export async function usageCommand(deps, args) {
     const flags = parseStackFlags(args, { values: ["--tenant", "--scope", "--id", "--period"] }, USAGE_USAGE);
     if (flags.rest.length)
         throw usageError(`Usage: ${USAGE_USAGE}`);
     const scope = flags.values.get("--scope") ?? "tenant";
+    if (scope === "agent")
+        throw usageError("--scope agent is --scope manifest in protocol 16: --id names an agent manifest.");
     const period = flags.values.get("--period") ?? "total";
     const id = flags.values.get("--id");
     if (!SCOPES.includes(scope))
@@ -163,7 +171,9 @@ export async function usageCommand(deps, args) {
     if (!PERIODS.includes(period))
         throw usageError(`--period is one of ${PERIODS.join(", ")}.`);
     if ((scope === "tenant") !== (id === undefined))
-        throw usageError(scope === "tenant" ? "--id names an agent or a turn: pass --scope agent or turn." : `--scope ${scope} needs --id.`);
+        throw usageError(scope === "tenant"
+            ? "--id names an agent manifest or a turn: pass --scope manifest or turn."
+            : `--scope ${scope} needs --id.`);
     const query = {
         scope: scope,
         period: period,

package/dist/client/runtime.d.ts

@@ -10,7 +10,7 @@ export declare const RUNTIME_FLAGS: {
 export declare const runtimeFlagsUsage: string;
 export declare const usageError: (message: string) => CliError;
 export type Flags = ReturnType<typeof parseStackFlags>;
-/** `args` parsed with the Runtime flags added to `allowed`. */
+/** `args` parsed with the Runtime flags added to `allowed`; `--help` names them too. */
 export declare function parseFlags(args: readonly string[], allowed: {
     booleans?: readonly string[];
     values?: readonly string[];

package/dist/client/runtime.js

@@ -1,20 +1,22 @@
 /**
- * What the Runtime API groups (`agents`, `sessions`, `environments`, `artifacts`) share: their
- * flags, the `@nylorun/agents` client of the installation `target.ts` picks, acting for a subject
- * with `--as`, and how they read input and print output.
+ * What the Runtime API commands (`apply`, `agent-manifests`, `agents`, `sessions`, `artifacts`)
+ * share: their flags, the `@nylorun/agents` client of the installation `target.ts` picks, acting
+ * for a subject with `--as`, and how they read input and print output.
  */
 import { readFile } from "node:fs/promises";
 import { AgentsClient, RuntimeError, SUBJECT_SCOPES, } from "@nylorun/agents";
-import { CliError } from "../errors.js";
-import { parseStackFlags } from "../stack/commands.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
+import { parseStackFlags, usageText } from "../stack/commands.js";
 import { connect } from "./target.js";
 /** Flags every Runtime API command takes. */
 export const RUNTIME_FLAGS = { values: ["--tenant", "--as"], lists: ["--scope"] };
 export const runtimeFlagsUsage = `Every command takes --tenant <name>, and --as <subject> [--scope <scope>]... to act for a
 person (default scope sessions:own; scopes: ${SUBJECT_SCOPES.join(", ")}).`;
 export const usageError = (message) => new CliError(message, 2);
-/** `args` parsed with the Runtime flags added to `allowed`. */
+/** `args` parsed with the Runtime flags added to `allowed`; `--help` names them too. */
 export function parseFlags(args, allowed, usage) {
+    if (args.some(isHelp))
+        throw new HelpRequest(`${usageText(usage)}\n\n${runtimeFlagsUsage}`);
     return parseStackFlags(args, {
         booleans: allowed.booleans ?? [],
         values: [...RUNTIME_FLAGS.values, ...(allowed.values ?? [])],