@metrio-ai/cli 1.3.1 → 1.5.0

package/README.md

@@ -31,6 +31,8 @@ metrio prompt list
 metrio version get 34 -o system.md          # the system prompt as a file
 metrio version create 12 -f system.md --model-provider openai --model-name gpt-5
 metrio version get 34 -o v.yaml && metrio version update 34 -f v.yaml   # round-trip
+metrio version get 34 -o greeter.md --frontmatter    # settings as YAML frontmatter + the prompt verbatim
+metrio version create 12 -f greeter.md --frontmatter # one file carries the whole version
 metrio skill get 5 -o skill.md              # frontmatter (name, description, references) + body
 metrio skill update 5 -f skill.md
 metrio workflow version create intake -f definition.json --activate
@@ -68,7 +70,9 @@ metrio version list pick-products     # prompt directories work wherever a promp
 - Renaming a prompt or skill directory is detected by content (status `renamed`); pull/push move the state entry. Workflow directories are named by workflow id and cannot be renamed locally; push refuses it.
 - Known limitation: renaming AND editing a prompt/skill directory in one go looks like a delete plus a new resource (push would create a second one; `--prune --yes` would delete the old one). Rename first, sync, then edit.
 
-## Verify prompts and workflows
+Metrio agents sync too: `agents/<dir>/agent.yaml` (entry prompt and version, sub-agents with version pins, tool policies), `--only agents`, with a sub-agent pin bumped automatically when its entry prompt gets a new head version (`push --activate`, or a new prompt's first version; `--no-bump-pins` to opt out). Manage them with `metrio agent ...`. This needs a console that has the agent tools (metrioai-console IMP-3). Details: `docs/cli.md` in the repository.
+
+## Verify prompts, workflows and agents
 
 Put a `cases.yaml` next to a synced resource (`prompts/<name>/cases.yaml`, `workflows/<id>/cases.yaml`) and run it with the project API key (`METRIOAI_API_KEY` in `.env`, or `--api-key`; it must belong to the workspace's project):
 
@@ -93,4 +97,6 @@ metrio push --activate                # make it live once the cases pass
 metrio verify -p 12 --cases cases.yaml --junit report.xml   # outside a workspace
 ```
 
+Agents work the same way (`agents/<dir>/cases.yaml` or `-a <id|dir>`), with the extra assertion `stop_reason` (`final`, `terminal_tool`, `max_turns`, `interrupted`, `cancelled`); they always run live.
+
 Every `cases.yaml` is validated before the first request (a typo in an assertion is exit 2). A failed case prints each failing assertion with expected vs actual and exits 1. `--json` prints machine-readable results, `--junit <file>` writes JUnit XML, `--fail-fast` stops starting new cases after the first failure. Run `metrio verify --help` for the full format.

package/dist/commands/sync.js

@@ -47,14 +47,15 @@ const diff_1 = require("diff");
 const client_1 = require("../console/client");
 const errors_1 = require("../errors");
 const push_1 = require("../sync/push");
+const push_agents_1 = require("../sync/push-agents");
 const remote_1 = require("../sync/remote");
 const status_1 = require("../sync/status");
 const workspace_1 = require("../sync/workspace");
-const ONLY = { prompts: 'prompt', skills: 'skill', workflows: 'workflow' };
+const ONLY = { prompts: 'prompt', skills: 'skill', workflows: 'workflow', agents: 'agent' };
 function parseSyncArgs(argv) {
     const o = {
-        paths: [], kinds: ['prompt', 'skill', 'workflow'], force: false, activate: false, publish: false,
-        prune: false, yes: false, dryRun: false, json: false,
+        paths: [], kinds: ['prompt', 'skill', 'workflow', 'agent'], force: false, activate: false, publish: false,
+        prune: false, yes: false, bumpPins: true, dryRun: false, json: false,
     };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -68,7 +69,7 @@ function parseSyncArgs(argv) {
         if (arg === '--only') {
             const kind = ONLY[value()];
             if (!kind)
-                throw new errors_1.CliError('--only must be prompts, skills or workflows');
+                throw new errors_1.CliError('--only must be prompts, skills, workflows or agents');
             o.kinds = [kind];
         }
         else if (arg === '-m' || arg === '--message')
@@ -85,6 +86,8 @@ function parseSyncArgs(argv) {
             o.prune = true;
         else if (arg === '--yes')
             o.yes = true;
+        else if (arg === '--no-bump-pins')
+            o.bumpPins = false;
         else if (arg === '--dry-run')
             o.dryRun = true;
         else if (arg === '--json')
@@ -123,25 +126,37 @@ function filterEntries(entries, root, paths) {
 async function loadEntries(ctx, opts) {
     const state = (0, workspace_1.readState)(ctx.root, ctx.project);
     const remote = await (0, remote_1.fetchRemote)(ctx.client, ctx.project, opts.kinds);
-    return filterEntries((0, status_1.computeEntries)(ctx.root, state, remote, opts.kinds), ctx.root, opts.paths);
+    if (remote.agentsUnavailable) {
+        process.stderr.write('agents skipped: this console has no agent tools (list_agents)\n');
+        opts.kinds = opts.kinds.filter((k) => k !== 'agent'); // later re-reads in this run leave agents out too
+    }
+    for (const a of remote.skippedAgents) {
+        process.stderr.write(safe(`agent ${a.id} "${a.name}" skipped: its entry prompt was deleted (fix it with "metrio agent update")\n`));
+    }
+    // A tracked agent left out is kept as it is, not shown as deleted in the console.
+    const skipped = new Set(remote.skippedAgents.map((a) => a.id));
+    const entries = (0, status_1.computeEntries)(ctx.root, state, remote.resources, opts.kinds).filter((e) => !(e.kind === 'agent' && e.state && skipped.has(e.state.id)));
+    return filterEntries(entries, ctx.root, opts.paths);
 }
 /** Console-sourced text must not carry terminal control sequences. */
 function safe(text) {
     return text.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
 }
-exports.SYNC_HELP = `metrio pull | diff | push - sync prompts, skills and workflows with local files
+exports.SYNC_HELP = `metrio pull | diff | push - sync prompts, skills, workflows and agents with local files
 
   metrio pull --project <slug>   First pull: creates metrio.yaml here and writes:
                                    prompts/<name>/prompt.yaml + system.md
                                    skills/<name>.md
                                    workflows/<id>/workflow.yaml + definition.json
+                                   agents/<name>/agent.yaml
   metrio pull [paths…]           Update files from the console (keeps local edits unless --force)
   metrio diff [paths…]           Show what differs: modified, remote-changed, conflict, new, …
   metrio push [paths…]           Send local edits: new prompt version (not live unless --activate),
-                                 skill update, workflow version (draft; --publish / --activate)
+                                 skill update, workflow version (draft; --publish / --activate),
+                                 agent create/update (sub-agents before their parents)
 
 Options:
-  --only prompts|skills|workflows   Limit to one kind
+  --only prompts|skills|workflows|agents   Limit to one kind
   --force                           pull: overwrite local edits; push: push over console changes
                                     (local wins — bindings and MCP list are replaced), allow
                                     pruning resources changed in the console, and allow a prompt
@@ -150,6 +165,9 @@ Options:
   --activate                        push: make new prompt versions head / workflow versions live
   --publish                         push: publish new workflow versions without activating
   --prune --yes                     push: delete console resources whose local files were removed
+  --no-bump-pins                    push: keep sub-agent pins; by default a pin moves to the head
+                                    version this push creates for the sub-agent's entry prompt
+                                    (--activate, or a new prompt's first version)
   --dry-run                         Print the plan without changing anything
   --json                            diff: machine-readable statuses
 
@@ -312,7 +330,7 @@ function remoteContent(r) {
     }
 }
 const remoteMoved = (e) => (0, workspace_1.hashFiles)(e.remote.files) !== e.state.remote;
-function planPush(entries, opts, options) {
+function planPush(entries, state, opts, options) {
     const actions = [];
     for (const entry of entries) {
         switch (entry.status) {
@@ -369,14 +387,47 @@ function planPush(entries, opts, options) {
                 break;
         }
     }
-    return sortForExecution(actions);
+    const withOp = (op) => actions.flatMap((a) => ('op' in a && a.op === op ? [a.entry] : []));
+    (0, push_agents_1.checkAgentRefs)(entries.filter((e) => e.kind === 'agent' && e.local), new Set([...withOp('create'), ...withOp('rename')].map((e) => e.key)), withOp('delete'), withOp('rename'), entries.filter((e) => e.status === 'remote-deleted'), state);
+    return sortForExecution(actions, entries);
 }
-const KIND_RANK = { skill: 0, prompt: 1, workflow: 2 };
-const DELETE_RANK = { prompt: 3, workflow: 3, skill: 4 };
-/** Skills first (prompts may name new ones), then prompts, workflows; deletes last, skills after what uses them. */
-function sortForExecution(actions) {
+const isAgentWrite = (a) => a.entry.kind === 'agent' && 'op' in a && (a.op === 'create' || a.op === 'update');
+const isAgentDelete = (a) => a.entry.kind === 'agent' && 'op' in a && a.op === 'delete';
+const KIND_RANK = { skill: 0, prompt: 1, workflow: 2, agent: 3 };
+const DELETE_RANK = { agent: 4, prompt: 5, workflow: 5, skill: 6 };
+/**
+ * Skills first (prompts may name new ones), then prompts, workflows, and agents (sub-agents before
+ * their parents; a local cycle fails before any write). Deletes come after every create/update:
+ * agents first (parents before children, so a parent drops a link before its child goes), then
+ * prompts and workflows, skills after what uses them.
+ */
+function sortForExecution(actions, entries) {
     const rank = (a) => ('op' in a && a.op === 'delete' ? DELETE_RANK : KIND_RANK)[a.entry.kind];
-    return [...actions].sort((a, b) => rank(a) - rank(b));
+    const sorted = [...actions].sort((a, b) => rank(a) - rank(b));
+    const written = new Set(sorted.filter(isAgentWrite).map((a) => a.entry.key));
+    const writeOrder = (0, push_agents_1.agentWriteOrder)(entries, written);
+    const deleteOrder = (0, push_agents_1.agentDeleteOrder)(sorted.filter(isAgentDelete).map((a) => a.entry), entries);
+    const reorder = (list, pick, order) => {
+        const picked = list.filter(pick).sort((a, b) => order.indexOf(a.entry.key) - order.indexOf(b.entry.key));
+        let i = 0;
+        return list.map((a) => (pick(a) ? picked[i++] : a));
+    };
+    return reorder(reorder(sorted, isAgentWrite, writeOrder), isAgentDelete, deleteOrder);
+}
+/** The keys and ids state will hold once `done` is recorded (what agent references render against). */
+function stateAfter(state, done) {
+    const resources = { ...state.resources };
+    for (const d of done) {
+        if (d.op === 'delete')
+            delete resources[d.entry.key];
+        else if (d.op === 'rename') {
+            resources[d.entry.key] = resources[d.entry.from];
+            delete resources[d.entry.from];
+        }
+        else
+            resources[d.entry.key] = { ...(resources[d.entry.key] ?? {}), kind: d.entry.kind, id: d.result.id };
+    }
+    return { ...state, resources };
 }
 const PAST = { create: 'created', update: 'updated', delete: 'deleted', rename: 'renamed' };
 const describeOp = (op, e) => (op === 'rename' ? `${e.from} -> ${e.key}` : e.key);
@@ -392,14 +443,21 @@ async function runPushCommand(argv) {
         const state = (0, workspace_1.readState)(ctx.root, ctx.project);
         const options = { activate: opts.activate, publish: opts.publish, message: opts.message, force: opts.force };
         const entries = await loadEntries(ctx, opts);
-        const actions = planPush(entries, opts, options);
+        const actions = planPush(entries, state, opts, options);
         if (opts.dryRun) {
             for (const a of actions) {
                 process.stdout.write(safe('op' in a ? `would ${a.op} ${describeOp(a.op, a.entry)}\n` : `skip ${a.entry.key}: ${a.skip}\n`));
             }
             return;
         }
-        const pushCtx = { client: ctx.client, project: ctx.project, options };
+        const agents = {
+            root: ctx.root,
+            ids: new Map(Object.entries(state.resources).map(([key, s]) => [key, s.id])),
+            promptSerials: new Map(),
+            entries,
+            bumpPins: opts.bumpPins,
+        };
+        const pushCtx = { client: ctx.client, project: ctx.project, options, agents };
         const done = [];
         let failed = 0;
         for (const a of actions) {
@@ -418,6 +476,15 @@ async function runPushCommand(argv) {
                     await (0, push_1.deleteEntry)(pushCtx, a.entry);
                 else if (a.op !== 'rename')
                     result = await (0, push_1.pushEntry)(pushCtx, a.entry);
+                // Later agents resolve references to what this push created or renamed.
+                if (result)
+                    agents.ids.set(a.entry.key, result.id);
+                if (a.op === 'rename' && state.resources[a.entry.from])
+                    agents.ids.set(a.entry.key, state.resources[a.entry.from].id);
+                // Only a version that went live moves pins: a non-head one is still to be verified.
+                if (a.entry.kind === 'prompt' && result?.pushed_head && result.pushed_serial !== undefined) {
+                    agents.promptSerials.set(result.id, result.pushed_serial);
+                }
                 done.push({ entry: a.entry, op: a.op, result });
                 process.stdout.write(safe(`${PAST[a.op]} ${describeOp(a.op, a.entry)}${result ? ` (${result.summary})` : ''}\n`));
             }
@@ -426,6 +493,21 @@ async function runPushCommand(argv) {
                 process.stderr.write(safe(`failed ${a.entry.key}: ${error instanceof Error ? error.message : String(error)}\n`));
             }
         }
+        // Unchanged agents whose sub-agent's entry prompt got a new version: move their pins.
+        try {
+            await (0, push_agents_1.bumpUnchangedPins)(pushCtx, entries.filter((e) => !done.some((d) => d.entry === e)), (entry, result) => {
+                done.push({ entry, op: 'update', result });
+                process.stdout.write(safe(`updated ${entry.key} (${result.summary})\n`));
+            });
+        }
+        catch (error) {
+            failed += 1;
+            process.stderr.write(safe(`failed: ${error instanceof Error ? error.message : String(error)}\n`));
+        }
+        const unbumped = (0, push_agents_1.parentsOutOfScope)(agents);
+        if (unbumped.length) {
+            process.stderr.write(safe(`sub-agent pins not bumped for ${unbumped.join(', ')}: not in this push (run "metrio push" or "metrio agent bump-pins")\n`));
+        }
         // Converged resources (same content on both sides, stale state): record them as synced.
         const converged = entries.filter((e) => e.refresh && !done.some((d) => d.entry === e));
         for (const e of converged) {
@@ -439,8 +521,11 @@ async function runPushCommand(argv) {
             const pushed = done.filter((d) => d.result);
             let refreshed;
             if (pushed.length) {
+                // Agent files reference other resources by directory: re-read every loaded kind to render them as diff will.
+                const kinds = pushed.some((d) => d.entry.kind === 'agent') ? opts.kinds : [...new Set(pushed.map((d) => d.entry.kind))];
                 try {
-                    refreshed = await (0, remote_1.fetchRemote)(ctx.client, ctx.project, [...new Set(pushed.map((d) => d.entry.kind))]);
+                    refreshed = (await (0, remote_1.fetchRemote)(ctx.client, ctx.project, kinds)).resources;
+                    (0, status_1.renderRemoteAgents)(stateAfter(state, done), refreshed, opts.kinds);
                 }
                 catch (error) {
                     refetchFailed = true;
@@ -464,7 +549,7 @@ async function runPushCommand(argv) {
                         ...(previous ?? {}),
                         kind: d.entry.kind,
                         id: r.id,
-                        base: (0, workspace_1.hashFiles)(d.entry.local),
+                        base: (0, workspace_1.hashFiles)(r.files ?? d.entry.local),
                         // Without a re-read, keep the last known remote hash: the next diff then shows what really changed.
                         remote: refreshed ? (remote ? (0, workspace_1.hashFiles)(remote.files) : '') : (previous?.remote ?? ''),
                         ...(r.pushed_version_id !== undefined ? { pushed_version_id: r.pushed_version_id, pushed_serial: r.pushed_serial } : {}),

package/dist/commands/verify.js

@@ -38,7 +38,7 @@ exports.parseVerifyArgs = parseVerifyArgs;
 exports.resolveTargets = resolveTargets;
 exports.runVerifyCommand = runVerifyCommand;
 /**
- * `metrio verify` — runs cases.yaml against prompts and workflows and checks every reply.
+ * `metrio verify` — runs cases.yaml against prompts, workflows and Metrio agents and checks every reply.
  * Execution uses the project API key, like `chat` and `run-batch`. Targets come from the
  * workspace (.metrio/state.json) or from -p / -w with --cases. Every cases.yaml is
  * validated before the first request.
@@ -56,10 +56,13 @@ const report_1 = require("../verify/report");
 exports.VERIFY_HELP = `metrio verify - run cases.yaml and check every reply
 
 Usage:
-  metrio verify [paths…] [options]               Workspace prompts/<name>/cases.yaml and
-                                                 workflows/<id>/cases.yaml
+  metrio verify [paths…] [options]               Workspace prompts/<name>/cases.yaml,
+                                                 workflows/<id>/cases.yaml and
+                                                 agents/<name>/cases.yaml
   metrio verify -p <prompt-id> --cases <file>    One prompt, any cases file
   metrio verify -w <workflow-id> --cases <file>  One workflow, any cases file
+  metrio verify -a <id|dir> --cases <file>       One Metrio agent (external id, or an agents/<dir>
+                                                 name from .metrio/state.json), any cases file
 
 In a workspace (see "metrio pull --help") each cases.yaml runs against the resource
 recorded in .metrio/state.json. Paths narrow the run: a resource directory, prompts/,
@@ -68,7 +71,8 @@ workflows/ or the root.
 Options:
   --version active|pushed|<n>   active (default): the live version; pushed: the version
                                 the last "metrio push" created; <n>: prompt version serial
-                                or workflow version
+                                or workflow version. Agents always run live (also for
+                                pushed); a number is rejected for them
                                 (a number needs a single prompt or workflow path)
   --concurrency <n>             Cases in flight (default 4)
   --json                        Print results as JSON instead of the text report
@@ -99,6 +103,8 @@ cases.yaml:
         max_latency_ms: 8000
         max_tokens: 4000                          # input + output
         max_llm_calls: 3                          # workflows
+        stop_reason: final                        # agents: final | terminal_tool | max_turns |
+                                                  #   interrupted | cancelled
 
 Agent loop: pull → edit → push → verify --version pushed → push --activate
 
@@ -151,6 +157,14 @@ function parseVerifyArgs(argv) {
                 o.workflowId = v;
                 break;
             }
+            case '-a':
+            case '--agent-id': {
+                const v = value().trim();
+                if (!v)
+                    throw new errors_1.CliError(`${arg} cannot be empty`);
+                o.agent = v;
+                break;
+            }
             case '--cases':
                 o.cases = value();
                 break;
@@ -173,22 +187,44 @@ function parseVerifyArgs(argv) {
                 o.paths.push(arg);
         }
     }
-    const direct = o.promptId !== undefined || o.workflowId !== undefined;
-    if (o.promptId !== undefined && o.workflowId !== undefined)
-        throw new errors_1.CliError('Use -p or -w, not both');
+    const direct = o.promptId !== undefined || o.workflowId !== undefined || o.agent !== undefined;
+    if ([o.promptId, o.workflowId, o.agent].filter((v) => v !== undefined).length > 1)
+        throw new errors_1.CliError('Use only one of -p, -w, -a');
     if (direct && !o.cases)
-        throw new errors_1.CliError('-p / -w need --cases <file>');
+        throw new errors_1.CliError('-p / -w / -a need --cases <file>');
     if (!direct && o.cases)
-        throw new errors_1.CliError('--cases needs -p <prompt-id> or -w <workflow-id>');
+        throw new errors_1.CliError('--cases needs -p <prompt-id>, -w <workflow-id> or -a <agent-id|dir>');
     if (direct && o.paths.length)
-        throw new errors_1.CliError('Workspace paths cannot be combined with -p / -w');
-    if (direct && o.version === 'pushed') {
+        throw new errors_1.CliError('Workspace paths cannot be combined with -p / -w / -a');
+    // Agents always run live, so --version pushed is a no-op for -a.
+    if (direct && o.agent === undefined && o.version === 'pushed') {
         throw new errors_1.CliError('--version pushed reads .metrio/state.json; with -p / -w use active or a version number');
     }
+    if (o.agent !== undefined && typeof o.version === 'number')
+        throw new errors_1.CliError('Agents have no versions; --version <n> does not apply to -a');
     return o;
 }
+/** `-a` takes an external id, or a workspace directory (agents/<dir> or <dir>) resolved through state. */
+function agentRef(raw) {
+    if (/^\d+$/.test(raw))
+        return agentId(raw, `-a ${raw}`);
+    const root = (0, workspace_1.findRoot)();
+    if (!root)
+        throw new errors_1.CliError(`-a ${raw}: not a numeric id, and not inside a metrio workspace to look the directory up`);
+    const key = raw.startsWith('agents/') ? raw : `agents/${raw}`;
+    const entry = (0, workspace_1.readState)(root, (0, workspace_1.readProject)(root)).resources[key];
+    if (!entry || entry.kind !== 'agent')
+        throw new errors_1.CliError(`-a ${raw}: ${key} is not an agent in .metrio/state.json; run "metrio push" first`);
+    return agentId(entry.id, key);
+}
+function agentId(raw, label) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new errors_1.CliError(`${label}: agent id "${raw}" is not a positive integer`);
+    return n;
+}
 function directTarget(o) {
-    const kind = o.promptId !== undefined ? 'prompt' : 'workflow';
+    const kind = o.promptId !== undefined ? 'prompt' : o.agent !== undefined ? 'agent' : 'workflow';
     const file = o.cases;
     let raw;
     try {
@@ -199,12 +235,12 @@ function directTarget(o) {
     catch (err) {
         throw new errors_1.CliError(`Cannot read cases file ${file}: ${err.message}`);
     }
-    const ref = kind === 'prompt' ? o.promptId : o.workflowId;
+    const ref = kind === 'prompt' ? o.promptId : kind === 'agent' ? agentRef(o.agent) : o.workflowId;
     return {
-        label: `${kind} ${ref}`,
+        label: `${kind} ${kind === 'agent' ? o.agent : ref}`,
         kind,
         ref,
-        version: typeof o.version === 'number' ? o.version : undefined,
+        version: kind !== 'agent' && typeof o.version === 'number' ? o.version : undefined,
         cases: (0, cases_1.parseCasesYaml)(raw, { kind, file, baseDir: path.dirname(path.resolve(file)) }),
     };
 }
@@ -215,7 +251,7 @@ function resolveTargets(o) {
     if (!root)
         throw new errors_1.CliError('Not in a metrio workspace (no metrio.yaml). Run it inside one, or use -p / -w with --cases.');
     const state = (0, workspace_1.readState)(root, (0, workspace_1.readProject)(root));
-    const listed = (0, workspace_1.listLocal)(root, ['prompt', 'workflow']);
+    const listed = (0, workspace_1.listLocal)(root, ['prompt', 'workflow', 'agent']);
     // Filter by path first so an unrelated resource's cases.yaml is never read.
     const inScope = (0, sync_1.filterEntries)(listed, root, o.paths);
     const read = (rs) => rs.map((r) => ({ ...r, cases: (0, workspace_1.readResourceFile)(root, r.key, 'cases.yaml') }));
@@ -225,18 +261,23 @@ function resolveTargets(o) {
     }
     const selected = read(inScope).filter((r) => r.cases !== undefined);
     if (!selected.length) {
-        throw new errors_1.CliError('No cases.yaml in this workspace. Add prompts/<name>/cases.yaml or workflows/<id>/cases.yaml.');
+        throw new errors_1.CliError('No cases.yaml in this workspace. Add prompts/<name>/cases.yaml, workflows/<id>/cases.yaml or agents/<name>/cases.yaml.');
     }
     if (typeof o.version === 'number' && selected.length > 1) {
         throw new errors_1.CliError(`--version <n> pins one resource; name a single prompt or workflow path (matched: ${selected.map((r) => r.key).join(', ')})`);
     }
+    if (typeof o.version === 'number' && selected.some((r) => r.kind === 'agent')) {
+        throw new errors_1.CliError('Agents have no versions; --version <n> does not apply to agents');
+    }
     return selected.map((r) => {
         const entry = state.resources[r.key];
         if (!entry)
             throw new errors_1.CliError(`${r.key} is not in .metrio/state.json yet; run "metrio push" first`);
         const kind = r.kind;
         let version;
-        if (typeof o.version === 'number')
+        if (kind === 'agent')
+            version = undefined;
+        else if (typeof o.version === 'number')
             version = o.version;
         else if (o.version === 'pushed') {
             version = kind === 'prompt' ? entry.pushed_serial : entry.pushed_workflow_version;
@@ -244,9 +285,9 @@ function resolveTargets(o) {
                 throw new errors_1.CliError(`${r.key}: no pushed version recorded in .metrio/state.json; run "metrio push"; a resource created by its first push (e.g. a new workflow) has none, so use --version active for it`);
             }
         }
-        const ref = kind === 'prompt' ? Number(entry.id) : entry.id;
-        if (kind === 'prompt' && (!Number.isInteger(ref) || ref <= 0)) {
-            throw new errors_1.CliError(`${r.key}: prompt id "${entry.id}" in .metrio/state.json is not a positive integer`);
+        const ref = kind === 'prompt' || kind === 'agent' ? Number(entry.id) : entry.id;
+        if (kind !== 'workflow' && (!Number.isInteger(ref) || ref <= 0)) {
+            throw new errors_1.CliError(`${r.key}: ${kind} id "${entry.id}" in .metrio/state.json is not a positive integer`);
         }
         return {
             label: r.key,
@@ -265,11 +306,14 @@ async function runVerifyCommand(argv) {
     const o = parseVerifyArgs(argv);
     const targets = resolveTargets(o);
     (0, shared_1.loadEnv)(o.envFile);
-    const client = new client_1.MetrioAI({ apiKey: (0, shared_1.resolveApiKey)(o.apiKey), baseUrl: (0, shared_1.resolveBaseUrl)(o.baseUrl) });
+    const apiKey = (0, shared_1.resolveApiKey)(o.apiKey);
+    const baseUrl = (0, shared_1.resolveBaseUrl)(o.baseUrl) || 'https://api.metrio.ai'; // the SDK's default
+    const client = new client_1.MetrioAI({ apiKey, baseUrl });
     const results = await (0, execute_1.runAll)(client, targets, {
         concurrency: o.concurrency,
         failFast: o.failFast,
         timezone: o.timezone,
+        agentApi: { apiKey, baseUrl },
         onResult: (r, done, total) => process.stderr.write((0, sync_1.safe)(`[${done}/${total}] ${r.resource} › ${r.case} ${r.status}\n`)),
     });
     process.stdout.write(o.json ? (0, report_1.formatJson)(results) : (0, report_1.formatHuman)(results));

package/dist/index.js

@@ -40,10 +40,10 @@ Account (console OAuth):
   whoami                Show the signed-in user and scopes
 
 Manage (console OAuth; run "metrio <group> --help"):
-  project | prompt | version | skill | workflow | schedule | mcp | run | admin | model-tiers
+  project | prompt | version | skill | workflow | agent | schedule | mcp | run | admin | model-tiers
                         e.g. metrio version create 12 -f system.md
                              metrio skill get 5 -o skill.md
-  pull | diff | push    Sync prompts, skills and workflows with local files ("metrio pull --help")
+  pull | diff | push    Sync prompts, skills, workflows and agents with local files ("metrio pull --help")
   tools                 List the console tools your login can call
   call <tool>           Call any console tool with JSON args (-f file | --args json)
 

package/dist/manage/output.js

@@ -87,7 +87,9 @@ async function writeFile(data, opts, file) {
         const text = opts.textField ? record[opts.textField] : undefined;
         if (typeof text !== 'string')
             throw new errors_1.CliError(`-o ${file}: this result has no text body; use .json or .yaml`);
-        const front = Object.fromEntries((opts.frontmatterKeys ?? []).filter((k) => record[k] !== undefined && record[k] !== null).map((k) => [k, record[k]]));
+        const front = Object.fromEntries((opts.frontmatterKeys ?? [])
+            .filter((k) => record[k] !== undefined && (record[k] !== null || (opts.frontmatterKeepNull ?? []).includes(k)))
+            .map((k) => [k, record[k]]));
         const head = Object.keys(front).length ? `---\n${(0, yaml_1.stringify)(front)}---\n\n` : '';
         body = `${head}${text}`;
     }

package/dist/manage/registry.js

@@ -1,10 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MANAGE_GROUPS = exports.COMMANDS = void 0;
+exports.MANAGE_GROUPS = exports.COMMANDS = exports.READ_ONLY_FRONTMATTER = void 0;
 exports.findCommand = findCommand;
 exports.groupHelp = groupHelp;
 exports.commandHelp = commandHelp;
 const P = (prop, label) => ({ prop, label });
+/** Identity of the version a file came from: written for reference, never sent back. */
+exports.READ_ONLY_FRONTMATTER = ['version_id', 'serial'];
+const VERSION_FRONTMATTER = [
+    ...exports.READ_ONLY_FRONTMATTER, 'description', 'tier_key', 'model_provider', 'model_name',
+    'output_format', 'model_settings', 'model_fallbacks', 'output_schema',
+];
+/** get_version → the create_version/update_version field names the frontmatter uses. */
+function versionFrontmatterView(r) {
+    const tier = r.model_tier?.tier_key;
+    // A file describes the whole version: "no schema" / "no fallbacks" are written explicitly, so
+    // update -f clears them instead of keeping what the target version had (omission keeps).
+    const view = {
+        ...r,
+        version_id: r.id,
+        output_schema: r.output_schema ?? null,
+        model_fallbacks: r.model_fallbacks ?? [],
+    };
+    if (typeof tier === 'string' && tier) {
+        view.tier_key = tier;
+        delete view.model_provider;
+        delete view.model_name;
+    }
+    return view;
+}
+const VERSION_FILE = {
+    optionalFrontmatterKeys: VERSION_FRONTMATTER,
+    frontmatterView: versionFrontmatterView,
+    frontmatterKeepNull: ['output_schema'],
+};
 const PROMPT = P('prompt_external_id', '<prompt-id>');
 const VERSION_ID = P('version_id', '<version-id>');
 const SKILL = P('skill_id', '<skill-id>');
@@ -13,6 +42,8 @@ const WF_VERSION = P('version', '<version>');
 const SCHEDULE = P('schedule_id', '<schedule-id>');
 const INSTANCE = P('mcp_instance_id', '<instance-id>');
 const TASK = P('task_id', '<task-id>');
+const AGENT = P('agent_id', '<agent>');
+const RUN = P('run_id', '<run>');
 exports.COMMANDS = [
     { path: ['project', 'list'], tool: 'list_projects', summary: 'List your projects' },
     { path: ['project', 'create'], tool: 'create_project', summary: 'Create a project (-f or --team-id/--name)' },
@@ -28,9 +59,9 @@ exports.COMMANDS = [
     { path: ['prompt', 'set-mcp-tools'], tool: 'set_prompt_mcp_tools', summary: 'Set the MCP tool allowlist (-f tools.yaml)', args: [PROMPT] },
     { path: ['prompt', 'diff'], tool: 'diff_prompt', summary: 'Diff two versions', args: [PROMPT, P('from_serial', '<from>'), P('to_serial', '<to>')] },
     { path: ['version', 'list'], tool: 'list_versions', summary: 'List versions of a prompt', args: [PROMPT] },
-    { path: ['version', 'get'], tool: 'get_version', summary: 'Get a version (-o v.yaml | system.md)', args: [VERSION_ID], textField: 'system_prompt' },
-    { path: ['version', 'create'], tool: 'create_version', summary: 'Create a version (-f system.md | v.yaml)', args: [PROMPT], textField: 'system_prompt' },
-    { path: ['version', 'update'], tool: 'update_version', summary: 'Update a version (-f system.md | v.yaml)', args: [VERSION_ID], textField: 'system_prompt' },
+    { path: ['version', 'get'], tool: 'get_version', summary: 'Get a version (-o v.yaml | system.md [--frontmatter])', args: [VERSION_ID], textField: 'system_prompt', ...VERSION_FILE },
+    { path: ['version', 'create'], tool: 'create_version', summary: 'Create a version (-f system.md [--frontmatter] | v.yaml)', args: [PROMPT], textField: 'system_prompt', ...VERSION_FILE },
+    { path: ['version', 'update'], tool: 'update_version', summary: 'Update a version (-f system.md [--frontmatter] | v.yaml)', args: [VERSION_ID], textField: 'system_prompt', ...VERSION_FILE },
     { path: ['version', 'create-batch'], tool: 'create_versions', summary: 'Create versions for several prompts (-f versions.jsonl)', wrap: 'versions' },
     { path: ['skill', 'list'], tool: 'list_skills', summary: 'List skills' },
     { path: ['skill', 'get'], tool: 'get_skill', summary: 'Get a skill (-o skill.md)', args: [SKILL], textField: 'content', frontmatterKeys: ['name', 'description', 'references'] },
@@ -49,6 +80,17 @@ exports.COMMANDS = [
     { path: ['workflow', 'version', 'diff'], tool: 'diff_workflow_version', summary: 'Diff two workflow versions', args: [WF, P('from_version', '<from>'), P('to_version', '<to>')] },
     { path: ['workflow', 'version', 'publish'], tool: 'publish_workflow_version', summary: 'Publish a draft (--activate to go live)', args: [WF, WF_VERSION] },
     { path: ['workflow', 'version', 'activate'], tool: 'set_active_workflow_version', summary: 'Make a published version live (rollback too)', args: [WF, WF_VERSION] },
+    { path: ['agent', 'list'], tool: 'list_agents', summary: 'List Metrio agents' },
+    { path: ['agent', 'get'], tool: 'get_agent', summary: 'Get an agent with its sub-agents and tool policies', args: [AGENT] },
+    { path: ['agent', 'create'], tool: 'create_agent', summary: 'Create an agent (-f agent.json, console field names)' },
+    { path: ['agent', 'update'], tool: 'update_agent', summary: 'Update an agent (-f agent.json, console field names)', args: [AGENT] },
+    { path: ['agent', 'delete'], tool: 'delete_agent', summary: 'Delete an agent (blocked while it is a sub-agent)', args: [AGENT], destructive: true },
+    { path: ['agent', 'tools'], tool: 'set_agent_tools', summary: 'Replace sub-agents and tool policies (-f tools.yaml)', args: [AGENT] },
+    { path: ['agent', 'bump-pins'], tool: 'bump_agent_pins', summary: 'Repoint sub-agent version pins (-f pins.yaml)', wrap: 'pins' },
+    { path: ['agent', 'run', 'list'], tool: 'list_agent_runs', summary: 'List runs of an agent, newest first', args: [AGENT] },
+    { path: ['agent', 'run', 'get'], tool: 'get_agent_run', summary: 'Get a run with children and pending approvals', args: [AGENT, RUN] },
+    { path: ['agent', 'run', 'approve'], tool: 'approve_agent_run', summary: 'Approve or reject gated tool calls (-f decisions.yaml)', args: [AGENT, RUN], wrap: 'decisions' },
+    { path: ['agent', 'run', 'cancel'], tool: 'cancel_agent_run', summary: 'Cancel an unfinished run', args: [AGENT, RUN], destructive: true },
     { path: ['schedule', 'list'], tool: 'list_schedules', summary: 'List schedules' },
     { path: ['schedule', 'create'], tool: 'create_schedule', summary: 'Create a schedule (-f schedule.yaml)' },
     { path: ['schedule', 'update'], tool: 'update_schedule', summary: 'Update a schedule (-f schedule.yaml)', args: [SCHEDULE] },
@@ -107,10 +149,16 @@ function commandHelp(spec) {
     ];
     if (spec.destructive)
         lines.push('      --yes           Confirm the delete');
+    if (spec.optionalFrontmatterKeys) {
+        lines.push('      --frontmatter   .md files carry the version settings as YAML frontmatter (see below)');
+    }
     if (spec.textField)
         lines.push('', `A .md/.txt file fills ${spec.textField}.`);
     if (spec.frontmatterKeys)
         lines.push(`Its YAML frontmatter may set: ${spec.frontmatterKeys.join(', ')}.`);
+    if (spec.optionalFrontmatterKeys) {
+        lines.push(`With --frontmatter, a .md file starts with YAML frontmatter (${spec.optionalFrontmatterKeys.join(', ')})`, `and the rest is ${spec.textField} verbatim. ${exports.READ_ONLY_FRONTMATTER.join(' and ')} are written by -o and ignored by -f.`, 'Without --frontmatter the whole file is the text, so a prompt that starts with --- stays intact.');
+    }
     if (spec.wrap)
         lines.push('', `A file without a "${spec.wrap}" key is sent as ${spec.wrap}.`);
     if (spec.downloadField)