nylorun 0.16.0-beta → 0.18.0-beta

package/dist/client/agents.js

@@ -1,148 +1,498 @@
-/**
- * `nylorun agents`: the Tenant's saved agents (`/v1/agents`, Runtime API). `save` takes a manifest
- * and the folders that hold its files: a manifest names each definition file by the SHA-256 of
- * its bytes (a skill's `files`), so the files are matched by content, whatever their paths.
- */
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { definitionFileHash } from "@nylorun/agents";
-import { CliError } from "../errors.js";
-import { parseFlags, positional, printJson, printTable, readJson, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
-export const agentsUsage = `nylorun agents <list|get|save>
+import { parseAgentManifestRef } from "@nylorun/core/contracts";
+import { HelpRequest, isHelp } from "../errors.js";
+import { usageLinesOf } from "../stack/commands.js";
+import { readSecret, readText } from "./io.js";
+import { integerFlag, labelsOf, parseFlags, positional, printCursor, printJson, printTable, readJson, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
+export const agentsUsage = `nylorun agents <command>
 
-The Tenant's saved agents, through the Runtime API with an application key (or NYLORUN_TOKEN).
+The Tenant's Agents (each one version of an agent manifest made live, with one environment and
+one vault; sessions run on them), through the Runtime API with an application key (or
+NYLORUN_TOKEN).
 
-  list [--json]                       id, kind and description of each agent
-  get <id>                            the agent's manifest, as JSON
-  save <manifest.json|-> [--files <dir>]... [--implementation-version <v>] [--dry-run]
-                                      save the agent the manifest describes, first uploading the
-                                      definition files it names from the folders given (found by
-                                      their SHA-256, whatever their paths); --dry-run checks it
-                                      and saves nothing
+  list [--state <state>] [--manifest <name>] [--label <key=value>]... [--outdated]
+       [--limit <n>] [--cursor <c>] [--json]
+                                      id, manifest version (tracks or pinned, and the version
+                                      it moves to), kind, state, sessions, owner and labels;
+                                      --outdated (or --behind): those moving to another version
+  get <id>                            the Agent, as JSON
+  put <id> --manifest <name[@n]> [--owner <user>] [--label <key=value>]... [--dry-run]
+                                      create it from a saved manifest (name tracks its latest
+                                      version, name@n pins version n), or find it, change its
+                                      owner and labels and move it to that version; --dry-run
+                                      prints what the move would do
+  pin <id> <version>                  move it to that version of its manifest, and keep it there
+  track <id>                          move it to its manifest's latest version, and with each save
+  restart <id> [--retry]              apply the version it waits to start on now (a running pod
+                                      stops; the next turn starts it); --retry: the version that
+                                      failed to start, again
+  fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>]
+       [--secrets <copy|none>] [--label <key=value>]... [--dry-run]
+                                      a new Agent from a manifest version (default its
+                                      manifest's latest), with this one's disk and the secrets
+                                      it declares; --dry-run prints the plan
+  stop <id> | reset <id>              stop its sandbox; reset its disk
+  rm <id>                             delete it: its sandbox, files and vault (refused while a
+                                      turn runs on it)
+  snapshot <id>                       keep a version of its disk
+  versions <id>                       its disk versions
+  restore <id> <version|latest>       put a version of its disk back
+  delete-version <id> <version>
+  events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]
+                                      its events (lifecycle, and agent.egress for every
+                                      connection, naming the turns running), as JSON
+  secrets list <id>                   its secrets' names, types and bindings (never a value)
+  secrets get <id> <name>
+  secrets put <id> <name>             the value of a slot its manifest declares, piped in
+                                      on standard input
+  secrets put <id> <name> <secret.json|->
+                                      create or replace a secret: {"type": "bearer", ...}, read
+                                      from a file or standard input
+  secrets rm <id> <name>
+  triggers list <id>                  its triggers: status, next and last run, as JSON
+  triggers pause|resume <id> <trigger>
+  triggers run <id> <trigger> [--idempotency-key <k>]
+                                      run it once now, as if it fired
+  triggers new-secret <id> <trigger>  a webhook trigger's new signing secret (whsec_…), shown
+                                      once with its URL; the one before stops working
+  runs <id> [--trigger <id>] [--limit <n>] [--cursor <c>]
+                                      what each fire came to (started, queued, skipped,
+                                      failed), newest first, as JSON
+  memories ls <id> [--prefix <folder>] [--limit <n>] [--cursor <c>]
+                                      its memories by path, as JSON
+  memories cat <id> <path>            one memory's content
+  memories put <id> <path> <file|->   write a memory whole (seed it), from a file or stdin
+  memories rm <id> <path>             delete a memory, or every memory in a folder
+  memories versions <id> [--path <path>] [--limit <n>] [--cursor <c>]
+                                      every change to its memories, newest first, as JSON
 
 ${runtimeFlagsUsage}`;
-const HASH = /^sha256:[0-9a-f]{64}$/;
-/** Every `sha256:<hex>` a manifest names under a `files` map, with where it names it. */
-export function namedFiles(manifest) {
-    const named = new Map();
-    const walk = (value, path) => {
-        if (!value || typeof value !== "object")
-            return;
-        if (Array.isArray(value))
-            return value.forEach((item, index) => walk(item, `${path}[${index}]`));
-        for (const [key, child] of Object.entries(value)) {
-            if (key === "files" && child && typeof child === "object" && !Array.isArray(child)) {
-                for (const [file, hash] of Object.entries(child))
-                    if (typeof hash === "string" && HASH.test(hash) && !named.has(hash))
-                        named.set(hash, `${path}.files["${file}"]`);
-            }
-            else
-                walk(child, `${path}.${key}`);
-        }
-    };
-    walk(manifest, "manifest");
-    return named;
-}
-/** The files under `dirs`, by their hash. */
-async function filesByHash(dirs) {
-    const found = new Map();
-    const visit = async (dir) => {
-        for (const entry of await readdir(dir, { withFileTypes: true })) {
-            const path = join(dir, entry.name);
-            if (entry.isDirectory())
-                await visit(path);
-            else if (entry.isFile())
-                found.set(await definitionFileHash(new Uint8Array(await readFile(path))), path);
-        }
-    };
-    for (const dir of dirs) {
-        try {
-            await visit(dir);
-        }
-        catch (error) {
-            throw new CliError(`Cannot read --files ${dir}: ${error.message}`, 1);
-        }
-    }
-    return found;
+/** What `agents save` (a definition, before protocol 16) says now. */
+const SAVE_REMOVED = "nylorun agents save was removed in protocol 16: agents run from saved agent manifests. Save one with nylorun apply <dir> (agent.manifest.json; nylorun migrate v8 <agent.json> writes one from a v7 manifest), then make an Agent from it with nylorun agents put <id> --manifest <name>.";
+/**
+ * The manifest an Agent runs, as the list prints it: `name@version`, the version it moves to
+ * (track T3), and whether it tracks.
+ */
+function manifestOf(agent) {
+    const name = parseAgentManifestRef(agent.manifest)?.name ?? agent.manifest;
+    const target = agent.targetVersion ? ` → ${agent.targetVersion}` : "";
+    return `${name}@${agent.resolvedVersion}${target} ${agent.tracking === "tracking" ? "tracks" : "pinned"}`;
+}
+/** What a move left pending, for a person: the version, and what it waits for. */
+function pendingOf(agent) {
+    if (!agent.targetVersion)
+        return "";
+    return agent.waitingFor === "secrets"
+        ? `; version ${agent.targetVersion} waits for its required secrets (nylorun agents secrets put ${agent.id} <name>)`
+        : `; version ${agent.targetVersion} applies at its pod's next start (nylorun agents restart ${agent.id} applies it now)`;
 }
 async function list(deps, args) {
-    const usage = "nylorun agents list [--json]";
-    const flags = parseFlags(args, { booleans: ["--json"] }, usage);
+    const usage = "nylorun agents list [--state <state>] [--manifest <name>] [--label <key=value>]... [--outdated] [--limit <n>] [--cursor <c>] [--json]";
+    const flags = parseFlags(args, {
+        booleans: ["--json", "--outdated", "--behind"],
+        values: ["--limit", "--cursor", "--state", "--manifest"],
+        lists: ["--label"],
+    }, usage);
     positional(flags, 0, usage);
-    const { client } = await runtimeClient(deps, flags);
-    const { agents } = await runtimeCall(() => client.listAgents());
+    const labels = labelsOf(flags);
+    const state = flags.values.get("--state");
+    const manifest = flags.values.get("--manifest");
+    // Moving to another version (track T3); --behind is its former name.
+    const outdated = flags.booleans.has("--outdated") || flags.booleans.has("--behind");
+    const filter = {
+        ...(labels ? { labels } : {}),
+        ...(state ? { state } : {}),
+        ...(manifest ? { manifest } : {}),
+        ...(outdated ? { outdated: true } : {}),
+    };
+    const limit = integerFlag(flags, "--limit");
+    const cursor = flags.values.get("--cursor");
+    const { client, connection } = await runtimeClient(deps, flags);
+    const paged = limit !== undefined || cursor !== undefined;
+    const page = paged
+        ? await runtimeCall(() => client.agents.page({
+            ...filter,
+            ...(limit === undefined ? {} : { limit }),
+            ...(cursor ? { cursor } : {}),
+        }))
+        : { agents: await runtimeCall(() => client.agents.list(filter)), nextCursor: null };
+    const agents = page.agents;
     if (flags.booleans.has("--json")) {
-        printJson(deps, agents);
+        printJson(deps, paged ? page : agents);
         return 0;
     }
-    if (agents.length === 0) {
-        deps.out("No agents saved.");
+    if (agents.length === 0)
+        deps.out(`No Agents on ${connection.label}.`);
+    else
+        printTable(deps, [
+            ["ID", "MANIFEST", "KIND", "STATE", "SESSIONS", "OWNER", "LABELS"],
+            ...agents.map((agent) => [
+                agent.id,
+                manifestOf(agent),
+                agent.kind,
+                agent.state,
+                String(agent.sessions.length),
+                agent.owner ?? "-",
+                Object.entries(agent.labels)
+                    .map(([key, value]) => `${key}=${value}`)
+                    .join(",") || "-",
+            ]),
+        ]);
+    printCursor(deps, page.nextCursor);
+    return 0;
+}
+/** A command that takes one Agent id and prints the Runtime's answer. */
+function byId(name, call) {
+    return async (deps, args) => {
+        const usage = `nylorun agents ${name} <id>`;
+        const flags = parseFlags(args, {}, usage);
+        const [id] = positional(flags, 1, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => call(client, id)));
+        return 0;
+    };
+}
+async function put(deps, args) {
+    const usage = "nylorun agents put <id> --manifest <name[@n]> [--owner <user>] [--label <key=value>]... [--dry-run]";
+    for (const removed of ["--kind", "--image"])
+        if (args.includes(removed))
+            throw usageError(`${removed} was removed in protocol 16: an Agent is made from a saved manifest only. Put what it runs in the manifest's runtime section (nylorun apply), then --manifest <name>.`);
+    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--manifest", "--owner"], lists: ["--label"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const manifest = flags.values.get("--manifest");
+    if (manifest === undefined)
+        throw usageError(`Usage: ${usage}`);
+    if (parseAgentManifestRef(manifest) === undefined)
+        throw usageError(`--manifest is an agent manifest's name, or name@version such as triage@3, not ${manifest}.`);
+    const owner = flags.values.get("--owner");
+    const labels = labelsOf(flags);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const input = { manifest, ...(owner ? { owner } : {}), ...(labels ? { labels } : {}) };
+    if (flags.booleans.has("--dry-run")) {
+        printJson(deps, await runtimeCall(() => client.agents.plan(id, input)));
         return 0;
     }
-    printTable(deps, [
-        ["ID", "KIND", "DESCRIPTION"],
-        ...agents.map((agent) => {
-            const manifest = "manifest" in agent ? agent.manifest : undefined;
-            const description = ("description" in agent ? agent.description : undefined) ?? manifest?.description;
-            return [agent.agentId, manifest?.kind ?? "agent", description ?? "-"];
-        }),
-    ]);
+    const agent = await runtimeCall(() => client.agents.put(id, input));
+    deps.err(`Agent ${agent.id} runs ${manifestOf(agent)} on ${connection.label}${pendingOf(agent)}.`);
+    printJson(deps, agent);
     return 0;
 }
-async function get(deps, args) {
-    const usage = "nylorun agents get <id>";
+/** `pin <id> <version>` and `track <id>`: moves an Agent within its manifest (track T3). */
+async function move(deps, args, pin) {
+    const usage = pin ? "nylorun agents pin <id> <version>" : "nylorun agents track <id>";
     const flags = parseFlags(args, {}, usage);
+    const [id, version] = positional(flags, pin ? 2 : 1, usage);
+    if (pin && !/^[1-9]\d*$/.test(version))
+        throw usageError("The version is a positive number.");
+    const { client, connection } = await runtimeClient(deps, flags);
+    const current = await runtimeCall(() => client.agents.get(id));
+    const name = parseAgentManifestRef(current.manifest)?.name ?? current.manifest;
+    const agent = await runtimeCall(() => client.agents.put(id, { manifest: pin ? `${name}@${version}` : name }));
+    deps.err(`Agent ${agent.id} runs ${manifestOf(agent)} on ${connection.label}${pendingOf(agent)}.`);
+    printJson(deps, agent);
+    return 0;
+}
+async function restart(deps, args) {
+    const usage = "nylorun agents restart <id> [--retry]";
+    const flags = parseFlags(args, { booleans: ["--retry"] }, usage);
     const [id] = positional(flags, 1, usage);
     const { client, connection } = await runtimeClient(deps, flags);
-    const { agents } = await runtimeCall(() => client.listAgents());
-    const agent = agents.find((item) => item.agentId === id);
-    if (!agent) {
-        deps.err(`No agent ${id} on ${connection.label}.`);
-        return 1;
-    }
+    const agent = await runtimeCall(() => client.agents.restart(id, { ...(flags.booleans.has("--retry") ? { retry: true } : {}) }));
+    deps.err(`Agent ${agent.id} runs ${manifestOf(agent)} on ${connection.label}${pendingOf(agent)}.`);
     printJson(deps, agent);
     return 0;
 }
-async function save(deps, args) {
-    const usage = "nylorun agents save <manifest.json|-> [--files <dir>]... [--implementation-version <v>] [--dry-run]";
-    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--implementation-version"], lists: ["--files"] }, usage);
-    const dryRun = flags.booleans.has("--dry-run");
-    const [path] = positional(flags, 1, usage);
-    const manifest = await readJson(path, "The manifest");
-    if (typeof manifest.id !== "string" || manifest.id === "")
-        throw usageError("The manifest has no id.");
-    const named = namedFiles(manifest);
-    const found = named.size === 0 ? new Map() : await filesByHash(flags.lists.get("--files") ?? []);
-    const missing = [...named].filter(([hash]) => !found.has(hash));
-    if (missing.length > 0)
-        throw new CliError(`The manifest names ${missing.length} ${missing.length === 1 ? "file" : "files"} not found under ${flags.lists.get("--files")?.join(", ") || "any --files folder"}:\n${missing.map(([hash, where]) => `  ${where} = ${hash}`).join("\n")}`, 1);
+async function fork(deps, args) {
+    const usage = "nylorun agents fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>] [--secrets <copy|none>] [--label <key=value>]... [--dry-run]";
+    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--manifest", "--disk", "--secrets"], lists: ["--label"] }, usage);
+    const [id, next] = positional(flags, 2, usage);
+    const disk = flags.values.get("--disk");
+    if (disk !== undefined && disk !== "latest" && disk !== "empty" && !/^[1-9]\d*$/.test(disk))
+        throw usageError("--disk is latest, empty or a version number.");
+    const secrets = flags.values.get("--secrets");
+    if (secrets !== undefined && secrets !== "copy" && secrets !== "none")
+        throw usageError("--secrets is copy or none.");
+    const manifest = flags.values.get("--manifest");
+    const labels = labelsOf(flags);
+    const options = {
+        id: next,
+        ...(manifest ? { manifest } : {}),
+        ...(disk === undefined ? {} : { disk: disk === "latest" || disk === "empty" ? disk : Number(disk) }),
+        ...(secrets ? { secrets: secrets } : {}),
+        ...(labels ? { labels } : {}),
+    };
     const { client, connection } = await runtimeClient(deps, flags);
-    let uploaded = 0;
-    for (const hash of named.keys()) {
-        if (await runtimeCall(() => client.files.has(hash)))
-            continue;
-        const bytes = new Uint8Array(await readFile(found.get(hash)));
-        await runtimeCall(() => client.files.upload(bytes, { sha256: hash }));
-        uploaded += 1;
-    }
-    const version = flags.values.get("--implementation-version");
-    const saved = await runtimeCall(() => client.saveAgent({ id: manifest.id, manifest: manifest }, { ...(version === undefined ? {} : { implementationVersion: version }), ...(dryRun ? { dryRun } : {}) }));
-    deps.err(`${dryRun ? "Checked (and saved nothing of)" : "Saved"} agent ${manifest.id} on ${connection.label}${named.size ? ` (${named.size} files, ${uploaded} uploaded)` : ""}.`);
-    printJson(deps, saved);
+    if (flags.booleans.has("--dry-run")) {
+        printJson(deps, await runtimeCall(() => client.agents.planFork(id, options)));
+        return 0;
+    }
+    const forked = await runtimeCall(() => client.agents.fork(id, options));
+    const { plan } = forked;
+    deps.err(`Forked Agent ${id} into ${next} on ${connection.label}: ${plan.manifest.name}@${plan.manifest.version}, ${plan.disk === null ? "an empty disk" : `disk version ${plan.disk}`}, ${plan.secrets.copied.length} secrets copied${plan.setup ? "; its setup runs before the first turn" : ""}.`);
+    if (plan.secrets.missing.length > 0)
+        deps.err(`  set before use: ${plan.secrets.missing.join(", ")} (nylorun agents secrets put ${next} <name>)`);
+    printJson(deps, forked);
+    return 0;
+}
+async function deleteAgent(deps, args) {
+    const usage = "nylorun agents rm <id>";
+    const flags = parseFlags(args, {}, usage);
+    const [id] = positional(flags, 1, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const deleted = await runtimeCall(async () => {
+        try {
+            return await client.agents.delete(id);
+        }
+        catch (error) {
+            if (error.status === 404)
+                return undefined;
+            throw error;
+        }
+    });
+    if (!deleted || deleted.deleted === false) {
+        deps.err(`No Agent ${id} on ${connection.label}.`);
+        return 1;
+    }
+    deps.out(`Deleted Agent ${id}: its sandbox, files and vault.`);
+    return 0;
+}
+async function restore(deps, args) {
+    const usage = "nylorun agents restore <id> <version|latest>";
+    const flags = parseFlags(args, {}, usage);
+    const [id, version] = positional(flags, 2, usage);
+    if (version !== "latest" && !/^[1-9]\d*$/.test(version))
+        throw usageError("The version is a positive number or latest.");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.agents.restore(id, version === "latest" ? "latest" : Number(version))));
+    return 0;
+}
+async function deleteVersion(deps, args) {
+    const usage = "nylorun agents delete-version <id> <version>";
+    const flags = parseFlags(args, {}, usage);
+    const [id, version] = positional(flags, 2, usage);
+    if (!/^[1-9]\d*$/.test(version))
+        throw usageError("The version is a positive number.");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.agents.deleteVersion(id, Number(version))));
+    return 0;
+}
+async function events(deps, args) {
+    const usage = "nylorun agents events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]";
+    const flags = parseFlags(args, { values: ["--from", "--types", "--since", "--until"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const from = integerFlag(flags, "--from");
+    const types = flags.values.get("--types")?.split(",").map((type) => type.trim()).filter(Boolean);
+    const since = flags.values.get("--since");
+    const until = flags.values.get("--until");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.agents.events(id, {
+        ...(from === undefined ? {} : { from }),
+        ...(types === undefined || types.length === 0 ? {} : { types }),
+        ...(since === undefined ? {} : { since }),
+        ...(until === undefined ? {} : { until }),
+    })));
+    return 0;
+}
+async function secrets(deps, args) {
+    const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(usageLinesOf(agentsUsage, "secrets"));
+    if (verb === "list" || verb === "ls") {
+        const usage = "nylorun agents secrets list <id>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id] = positional(flags, 1, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.secrets.list(id)));
+        return 0;
+    }
+    if (verb === "get") {
+        const usage = "nylorun agents secrets get <id> <name>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, name] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.secrets.get(id, name)));
+        return 0;
+    }
+    if (verb === "put") {
+        const usage = "nylorun agents secrets put <id> <name> [<secret.json|->]";
+        const flags = parseFlags(rest, {}, usage);
+        if (flags.rest.length < 2 || flags.rest.length > 3)
+            throw usageError(`Usage: ${usage}`);
+        const [id, name, path] = flags.rest;
+        if (path === undefined) {
+            // A slot its manifest declares (D64): the value only, piped in; the binding is the slot's.
+            const value = await readSecret(deps, `value of ${name}`, `printf %s "$TOKEN" | nylorun agents secrets put ${id} ${name}`);
+            const { client } = await runtimeClient(deps, flags);
+            printJson(deps, await runtimeCall(() => client.agents.secrets.put(id, name, { value })));
+            return 0;
+        }
+        const secret = await readJson(path, "The secret");
+        if (typeof secret.type !== "string")
+            throw usageError('The secret needs a "type".');
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.secrets.put(id, name, secret)));
+        return 0;
+    }
+    if (verb === "rm" || verb === "delete") {
+        const usage = "nylorun agents secrets rm <id> <name>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, name] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        await runtimeCall(() => client.agents.secrets.delete(id, name));
+        deps.out(`Deleted secret ${name} of Agent ${id}.`);
+        return 0;
+    }
+    throw usageError(`Usage: nylorun agents secrets <list|get|put|rm> …\n\n${agentsUsage}`);
+}
+/** `nylorun agents triggers <list|pause|resume|run> …` (track T4). */
+async function triggers(deps, args) {
+    const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(usageLinesOf(agentsUsage, "triggers"));
+    if (verb === "list" || verb === "ls") {
+        const usage = "nylorun agents triggers list <id>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id] = positional(flags, 1, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.triggers(id)));
+        return 0;
+    }
+    if (verb === "pause" || verb === "resume") {
+        const usage = `nylorun agents triggers ${verb} <id> <trigger>`;
+        const flags = parseFlags(rest, {}, usage);
+        const [id, trigger] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => verb === "pause" ? client.agents.pauseTrigger(id, trigger) : client.agents.resumeTrigger(id, trigger)));
+        return 0;
+    }
+    if (verb === "run") {
+        const usage = "nylorun agents triggers run <id> <trigger> [--idempotency-key <k>]";
+        const flags = parseFlags(rest, { values: ["--idempotency-key"] }, usage);
+        const [id, trigger] = positional(flags, 2, usage);
+        const key = flags.values.get("--idempotency-key");
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.runTrigger(id, trigger, key === undefined ? {} : { idempotencyKey: key })));
+        return 0;
+    }
+    if (verb === "new-secret") {
+        const usage = "nylorun agents triggers new-secret <id> <trigger>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, trigger] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.rotateWebhookSecret(id, trigger)));
+        return 0;
+    }
+    throw usageError(`Usage: nylorun agents triggers <list|pause|resume|run|new-secret> …\n\n${agentsUsage}`);
+}
+/** `nylorun agents memories <ls|cat|put|rm|versions> …` (track T5). */
+async function memories(deps, args) {
+    const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(usageLinesOf(agentsUsage, "memories"));
+    const pageOf = (flags) => {
+        const limit = flags.values.get("--limit");
+        if (limit !== undefined && !/^[1-9]\d*$/.test(limit))
+            throw usageError("--limit must be a positive number.");
+        const cursor = flags.values.get("--cursor");
+        return { ...(limit === undefined ? {} : { limit: Number(limit) }), ...(cursor === undefined ? {} : { cursor }) };
+    };
+    if (verb === "ls" || verb === "list") {
+        const usage = "nylorun agents memories ls <id> [--prefix <folder>] [--limit <n>] [--cursor <c>]";
+        const flags = parseFlags(rest, { values: ["--prefix", "--limit", "--cursor"] }, usage);
+        const [id] = positional(flags, 1, usage);
+        const prefix = flags.values.get("--prefix");
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.memories.list(id, { ...(prefix === undefined ? {} : { pathPrefix: prefix }), ...pageOf(flags) })));
+        return 0;
+    }
+    if (verb === "cat") {
+        const usage = "nylorun agents memories cat <id> <path>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, path] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        deps.out((await runtimeCall(() => client.agents.memories.get(id, path))).content);
+        return 0;
+    }
+    if (verb === "put") {
+        const usage = "nylorun agents memories put <id> <path> <file|->";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, path, source] = positional(flags, 3, usage);
+        const content = await readText(deps, source);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.memories.put(id, path, content)));
+        return 0;
+    }
+    if (verb === "rm" || verb === "delete") {
+        const usage = "nylorun agents memories rm <id> <path>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, path] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        const deleted = await runtimeCall(() => client.agents.memories.delete(id, path));
+        deps.out(`Deleted ${deleted.deleted} ${deleted.deleted === 1 ? "memory" : "memories"} at ${deleted.path} of Agent ${id}.`);
+        return 0;
+    }
+    if (verb === "versions") {
+        const usage = "nylorun agents memories versions <id> [--path <path>] [--limit <n>] [--cursor <c>]";
+        const flags = parseFlags(rest, { values: ["--path", "--limit", "--cursor"] }, usage);
+        const [id] = positional(flags, 1, usage);
+        const path = flags.values.get("--path");
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.agents.memories.versions(id, { ...(path === undefined ? {} : { path }), ...pageOf(flags) })));
+        return 0;
+    }
+    throw usageError(`Usage: nylorun agents memories <ls|cat|put|rm|versions> …\n\n${agentsUsage}`);
+}
+/** `nylorun agents runs <id>` (track T4). */
+async function runs(deps, args) {
+    const usage = "nylorun agents runs <id> [--trigger <id>] [--limit <n>] [--cursor <c>]";
+    const flags = parseFlags(args, { values: ["--trigger", "--limit", "--cursor"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const limit = flags.values.get("--limit");
+    if (limit !== undefined && !/^[1-9]\d*$/.test(limit))
+        throw usageError("--limit must be a positive number.");
+    const trigger = flags.values.get("--trigger");
+    const cursor = flags.values.get("--cursor");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.agents.runs(id, {
+        ...(trigger === undefined ? {} : { triggerId: trigger }),
+        ...(limit === undefined ? {} : { limit: Number(limit) }),
+        ...(cursor === undefined ? {} : { cursor }),
+    })));
     return 0;
 }
-/** `nylorun agents <list|get|save> ...` */
+const COMMANDS = {
+    list,
+    ls: list,
+    get: byId("get", (client, id) => client.agents.get(id)),
+    put,
+    pin: (deps, args) => move(deps, args, true),
+    track: (deps, args) => move(deps, args, false),
+    restart,
+    stop: byId("stop", (client, id) => client.agents.stop(id)),
+    reset: byId("reset", (client, id) => client.agents.reset(id)),
+    rm: deleteAgent,
+    delete: deleteAgent,
+    snapshot: byId("snapshot", (client, id) => client.agents.snapshot(id)),
+    versions: byId("versions", (client, id) => client.agents.versions(id)),
+    restore,
+    "delete-version": deleteVersion,
+    events,
+    secrets,
+    fork,
+    triggers,
+    runs,
+    memories,
+};
+/** `nylorun agents <command> ...` */
 export async function agentsCommand(deps, args) {
     const [sub, ...rest] = args;
     if (sub === "--help" || sub === "-h") {
         deps.out(agentsUsage);
         return 0;
     }
-    if (sub === "list" || sub === "ls")
-        return list(deps, rest);
-    if (sub === "get")
-        return get(deps, rest);
     if (sub === "save")
-        return save(deps, rest);
-    throw usageError(sub ? `Unknown agents command ${sub}.\n${agentsUsage}` : agentsUsage);
+        throw usageError(SAVE_REMOVED);
+    const command = sub !== undefined && Object.hasOwn(COMMANDS, sub) ? COMMANDS[sub] : undefined;
+    if (!command)
+        throw usageError(sub ? `Unknown agents command ${sub}.\n${agentsUsage}` : agentsUsage);
+    return command(deps, rest);
 }

package/dist/client/apply.d.ts

@@ -0,0 +1,7 @@
+import { type AgentManifestPlan } from "@nylorun/agents";
+import type { StackDeps } from "../stack/commands.js";
+export declare const applyUsage: string;
+/** A plan as lines: the move, then each change, warning and error. */
+export declare function planLines(plan: AgentManifestPlan): string[];
+/** `nylorun apply [dir…] [--dry-run] [--if-match <n>]` */
+export declare function applyCommand(deps: StackDeps, args: readonly string[]): Promise<number>;