@metrio-ai/cli 1.3.1 → 1.5.0

package/dist/manage/run.js

@@ -10,7 +10,7 @@ const registry_1 = require("./registry");
 const workspace_1 = require("../sync/workspace");
 const schema_1 = require("./schema");
 function parse(rest) {
-    const parsed = { tokens: [], json: false, yes: false };
+    const parsed = { tokens: [], json: false, yes: false, frontmatter: false };
     const take = (i, name) => {
         const v = rest[i + 1];
         if (v === undefined)
@@ -38,6 +38,8 @@ function parse(rest) {
             parsed.json = true;
         else if (arg === '--yes')
             parsed.yes = true;
+        else if (arg === '--frontmatter')
+            parsed.frontmatter = true;
         else if (arg.startsWith('--')) {
             const eq = arg.indexOf('=');
             parsed.tokens.push(eq === -1 ? { flag: arg.slice(2) } : { flag: arg.slice(2, eq), value: arg.slice(eq + 1) });
@@ -47,13 +49,17 @@ function parse(rest) {
     }
     return parsed;
 }
-function fromFile(spec, file, readStdin) {
-    const loaded = (0, input_1.loadInputFile)(file, readStdin, { frontmatter: !!spec.frontmatterKeys, stdinText: !!spec.textField });
+function fromFile(spec, file, frontmatter, readStdin) {
+    const loaded = (0, input_1.loadInputFile)(file, readStdin, { frontmatter: !!spec.frontmatterKeys || frontmatter, stdinText: !!spec.textField });
     const cmd = `metrio ${spec.path.join(' ')}`;
     if (loaded.kind === 'text') {
         if (!spec.textField)
             throw new errors_1.CliError(`${cmd} does not take a text file; use .json or .yaml`);
-        return { ...(loaded.frontmatter ?? {}), [spec.textField]: loaded.value };
+        const front = { ...(loaded.frontmatter ?? {}) };
+        if (frontmatter)
+            for (const key of registry_1.READ_ONLY_FRONTMATTER)
+                delete front[key];
+        return { ...front, [spec.textField]: loaded.value };
     }
     if (loaded.kind === 'array') {
         if (!spec.wrap)
@@ -67,21 +73,28 @@ function isCommandPrefix(argv) {
     const words = argv.filter((a) => !a.startsWith('-'));
     return registry_1.COMMANDS.some((c) => words.length < c.path.length && words.every((w, i) => c.path[i] === w));
 }
+/** Positionals that may name a tracked directory instead of the numeric id. */
+const DIR_REFS = {
+    prompt_external_id: { kind: 'prompt', noun: 'prompt' },
+    agent_id: { kind: 'agent', noun: 'agent' },
+};
 /**
- * A prompt positional may name a tracked directory (prompts/<dir> or <dir>) instead of the
- * numeric id — only for the workspace's own project, since ids are per project.
+ * A prompt or agent positional may name a tracked directory (prompts/<dir> or <dir>) instead of
+ * the numeric id — only for the workspace's own project, since ids are per project.
  */
-function promptRef(raw, project) {
+function dirRef(raw, project, prop) {
     if (/^\d+$/.test(raw))
         return raw;
+    const { kind, noun } = DIR_REFS[prop];
+    const prefix = workspace_1.KIND_DIR[kind];
     const root = (0, workspace_1.findRoot)();
     const dir = raw.replace(/\/+$/, '');
-    const key = dir.startsWith('prompts/') ? dir : `prompts/${dir}`;
+    const key = dir.startsWith(`${prefix}/`) ? dir : `${prefix}/${dir}`;
     // A broken workspace surfaces its own (informative) CliError.
     const workspaceProject = root ? (0, workspace_1.readProject)(root) : undefined;
     const entry = root ? (0, workspace_1.readState)(root, workspaceProject).resources[key] : undefined;
-    if (!entry || entry.kind !== 'prompt') {
-        throw new errors_1.CliError(`Unknown prompt "${raw}": use the numeric id, or a prompts/<dir> tracked in .metrio/state.json`);
+    if (!entry || entry.kind !== kind) {
+        throw new errors_1.CliError(`Unknown ${noun} "${raw}": use the numeric id, or a ${prefix}/<dir> tracked in .metrio/state.json`);
     }
     if (project !== undefined && project !== workspaceProject) {
         throw new errors_1.CliError(`"${raw}" is a directory of project ${workspaceProject}, but this command targets project ${String(project)}`);
@@ -103,6 +116,9 @@ async function runManageCommand(argv, readStdin) {
     }
     const { spec, rest } = match;
     const opts = parse(rest);
+    if (opts.frontmatter && !spec.optionalFrontmatterKeys) {
+        throw new errors_1.CliError(`--frontmatter only applies to metrio version get | create | update, not metrio ${spec.path.join(' ')}`);
+    }
     const client = new client_1.ConsoleClient(await (0, client_1.resolveConsoleAuth)());
     const tool = (await client.listTools()).find((t) => t.name === spec.tool);
     if (!tool) {
@@ -123,17 +139,23 @@ async function runManageCommand(argv, readStdin) {
         sources[key] = source;
     };
     if (opts.file)
-        for (const [k, v] of Object.entries(fromFile(spec, opts.file, readStdin)))
+        for (const [k, v] of Object.entries(fromFile(spec, opts.file, opts.frontmatter, readStdin)))
             put(k, v, `file ${opts.file}`);
     if (opts.project && 'project_slug' in props)
         put('project_slug', opts.project, 'project');
     for (const [k, v] of Object.entries(values))
         put(k, v, `--${(0, schema_1.kebab)(k)}`);
-    // A prompt directory resolves against the final project_slug, so it waits for it.
-    let promptDir;
+    // A version uses a tier OR a specific model, and the console lets tier_key win when both are
+    // sent; so a model chosen by flag must drop a tier that came from the file, or the flag is ignored.
+    if (('model_provider' in values || 'model_name' in values) && !('tier_key' in values) && 'tier_key' in args) {
+        delete args.tier_key;
+        delete sources.tier_key;
+    }
+    // A directory name resolves against the final project_slug, so it waits for it.
+    const dirRefs = [];
     expected.forEach((arg, i) => {
-        if (arg.prop === 'prompt_external_id' && !/^\d+$/.test(positionals[i]))
-            promptDir = { prop: arg.prop, raw: positionals[i], label: arg.label };
+        if (arg.prop in DIR_REFS && !/^\d+$/.test(positionals[i]))
+            dirRefs.push({ prop: arg.prop, raw: positionals[i], label: arg.label });
         else
             put(arg.prop, (0, schema_1.coercePositional)(positionals[i], props[arg.prop], arg.label), arg.label);
     });
@@ -148,8 +170,8 @@ async function runManageCommand(argv, readStdin) {
                 throw err;
         }
     }
-    if (promptDir) {
-        put(promptDir.prop, (0, schema_1.coercePositional)(promptRef(promptDir.raw, args.project_slug), props[promptDir.prop], promptDir.label), promptDir.label);
+    for (const ref of dirRefs) {
+        put(ref.prop, (0, schema_1.coercePositional)(dirRef(ref.raw, args.project_slug, ref.prop), props[ref.prop], ref.label), ref.label);
     }
     if ((schema.required ?? []).includes('project_slug') && args.project_slug === undefined) {
         throw new errors_1.CliError('No project. Pass --project <slug>, set METRIO_PROJECT, or add "project: <slug>" to metrio.yaml.');
@@ -163,11 +185,14 @@ async function runManageCommand(argv, readStdin) {
         throw new errors_1.CliError('Re-run with --yes to confirm.', 2);
     }
     const data = await client.callTool(spec.tool, accepted, { retry: tool.scope === 'read' });
-    await (0, output_1.writeOutput)(data, {
+    const textOut = !!opts.outFile && /\.(md|markdown|txt)$/i.test(opts.outFile);
+    const withFrontmatter = opts.frontmatter && textOut && isRecord(data) && spec.frontmatterView;
+    await (0, output_1.writeOutput)(withFrontmatter ? spec.frontmatterView(data) : data, {
         json: opts.json,
         outFile: opts.outFile,
         textField: spec.textField,
-        frontmatterKeys: spec.frontmatterKeys,
+        frontmatterKeys: spec.frontmatterKeys ?? (opts.frontmatter ? spec.optionalFrontmatterKeys : undefined),
+        frontmatterKeepNull: withFrontmatter ? spec.frontmatterKeepNull : undefined,
         downloadField: spec.downloadField,
     });
     if (isRecord(data) && data.valid === false) {

package/dist/sync/push-agents.js

@@ -0,0 +1,380 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentDirRefs = agentDirRefs;
+exports.unresolvedRef = unresolvedRef;
+exports.subAgentKeys = subAgentKeys;
+exports.pushAgent = pushAgent;
+exports.bumpUnchangedPins = bumpUnchangedPins;
+exports.parentsOutOfScope = parentsOutOfScope;
+exports.checkAgentRefs = checkAgentRefs;
+exports.agentWriteOrder = agentWriteOrder;
+exports.agentDeleteOrder = agentDeleteOrder;
+const yaml_1 = require("yaml");
+const errors_1 = require("../errors");
+const push_1 = require("./push");
+const render_1 = require("./render");
+const workspace_1 = require("./workspace");
+/*
+ * Agents (plan Decisions 3-4). agent.yaml names its entry prompt and sub-agents by workspace
+ * directory (resolved through state, or through what this push created: prompts and children
+ * are pushed first) or by numeric id. Pin bumping: a sub-agent link whose child's entry prompt
+ * got a new head version in this push (--activate, or a new prompt's first version) moves to
+ * that version's serial, written through the parent's own set_agent_tools when the parent is
+ * pushed anyway, else through bump_agent_pins; the parent's agent.yaml is rewritten so the next
+ * diff is clean. A plain push's non-head version is not live yet (push, verify, push --activate),
+ * so it moves no pin. Entry versions are never bumped.
+ */
+/** The directory references of an agent file, with the field that holds each. */
+function agentDirRefs(doc) {
+    const refs = doc.entry_prompt !== undefined ? [{ key: `prompts/${doc.entry_prompt}`, field: 'entry_prompt', dir: doc.entry_prompt }] : [];
+    doc.sub_agents.forEach((s, i) => {
+        if (s.agent !== undefined)
+            refs.push({ key: `agents/${s.agent}`, field: `sub_agents[${i}].agent`, dir: s.agent });
+    });
+    return refs;
+}
+function unresolvedRef(agentKey, ref, why = `${ref.key} is not tracked and not created by this push`) {
+    return new errors_1.CliError(`${agentKey}/agent.yaml: ${ref.field} "${ref.dir}" does not resolve (${why})`);
+}
+const parseAgentEntry = (e) => (0, render_1.parseAgent)(e.local['agent.yaml'] ?? '', `${e.key}/agent.yaml`);
+/** Workspace keys of an agent's sub-agents among `entries` (local file, else the remote links), sorted. */
+function subAgentKeys(e, entries) {
+    const keyOf = (id) => entries.find((x) => x.kind === 'agent' && (x.state?.id ?? x.remote?.id) === String(id))?.key;
+    let keys;
+    if (e.local) {
+        try {
+            keys = parseAgentEntry(e).sub_agents.map((s) => (s.agent !== undefined ? `agents/${s.agent}` : keyOf(s.agent_id)));
+        }
+        catch {
+            return []; // the push reports the parse error
+        }
+    }
+    else
+        keys = (e.remote?.data?.sub_agents ?? []).map((s) => keyOf(s.agent_id));
+    return [...new Set(keys.filter((k) => k !== undefined))].sort();
+}
+/** The console id of the entry prompt an agent file names, if its directory resolves. */
+const entryPromptId = (sync, doc) => doc.entry_prompt !== undefined ? sync.ids.get(`prompts/${doc.entry_prompt}`) : String(doc.entry_prompt_id);
+/** The local agent.yaml of a tracked agent outside this push's scope, if it has one. */
+function trackedAgentFile(sync, key) {
+    const local = (0, workspace_1.readLocal)(sync.root, key, 'agent');
+    return local ? (0, render_1.parseAgent)(local['agent.yaml'] ?? '', `${key}/agent.yaml`) : undefined;
+}
+/** The serial this push gave the entry prompt of agent `agentId`, if it created one. */
+function newEntrySerial(sync, agentId) {
+    const child = sync.entries.find((x) => x.kind === 'agent' && (sync.ids.get(x.key) ?? x.remote?.id) === String(agentId));
+    let promptId;
+    try {
+        if (child?.local)
+            promptId = entryPromptId(sync, parseAgentEntry(child));
+        else if (child?.remote)
+            promptId = String(child.remote.data.entry_prompt_external_id);
+        else if (!child) {
+            // A tracked child outside the scope: its local agent.yaml names the entry prompt.
+            const key = [...sync.ids].find(([k, id]) => k.startsWith('agents/') && id === String(agentId))?.[0];
+            const doc = key === undefined ? undefined : trackedAgentFile(sync, key);
+            promptId = doc && entryPromptId(sync, doc);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const serial = promptId === undefined ? undefined : sync.promptSerials.get(promptId);
+    return serial === undefined ? undefined : String(serial);
+}
+function resolveAgent(sync, e, doc) {
+    const refs = agentDirRefs(doc);
+    const idOf = (field) => {
+        const ref = refs.find((r) => r.field === field);
+        const id = sync.ids.get(ref.key);
+        if (id === undefined)
+            throw unresolvedRef(e.key, ref);
+        return Number(id);
+    };
+    const entryPrompt = doc.entry_prompt !== undefined ? idOf('entry_prompt') : doc.entry_prompt_id;
+    const remoteLinks = e.remote?.data?.sub_agents ?? [];
+    const pins = new Map();
+    const subAgents = doc.sub_agents.map((s, i) => {
+        const agentId = s.agent !== undefined ? idOf(`sub_agents[${i}].agent`) : s.agent_id;
+        // Only a numeric pin still equal to the console's moves: tags and pins edited by hand stay.
+        const untouched = /^\d+$/.test(s.version) && remoteLinks.some((l) => l.agent_id === agentId && l.version_pin === s.version);
+        const bumped = sync.bumpPins && untouched ? newEntrySerial(sync, agentId) : undefined;
+        if (bumped !== undefined && bumped !== s.version)
+            pins.set(i, bumped);
+        return { agent_id: agentId, version_pin: pins.get(i) ?? s.version };
+    });
+    return { entryPrompt, subAgents, pins };
+}
+const policy = (p) => ({
+    tool_name: p.tool_name, needs_approval: p.needs_approval, ...(typeof p.timeout_ms === 'number' ? { timeout_ms: p.timeout_ms } : {}),
+});
+const toolSet = (subAgents, policies) => (0, render_1.canonical)({
+    sub_agents: [...subAgents].sort((a, b) => a.agent_id - b.agent_id),
+    tool_policies: policies.map(policy).sort((a, b) => (a.tool_name < b.tool_name ? -1 : a.tool_name > b.tool_name ? 1 : 0)),
+});
+/** agent.yaml with agent_id written back (first key) and bumped pins; comments and layout are kept. */
+function rewriteAgentYaml(text, agentId, pins) {
+    const doc = (0, yaml_1.parseDocument)(text);
+    if (agentId !== undefined)
+        doc.contents.items.unshift(doc.createPair('agent_id', agentId));
+    for (const [i, version] of pins)
+        doc.setIn(['sub_agents', i, 'version'], version);
+    return doc.toString();
+}
+function writeAgentFile(sync, e, text) {
+    const files = { 'agent.yaml': text };
+    if (text !== e.local['agent.yaml'])
+        (0, workspace_1.writeLocal)(sync.root, e.key, 'agent', files);
+    return files;
+}
+const bumpSummary = (doc, r) => [...r.pins].map(([i, v]) => `pinned ${doc.sub_agents[i].agent ?? doc.sub_agents[i].agent_id} to version ${v}`);
+async function pushAgent(ctx, e) {
+    const sync = ctx.agents;
+    if (!sync)
+        throw new errors_1.CliError('pushing agents needs the workspace context');
+    const text = e.local['agent.yaml'] ?? '';
+    const doc = parseAgentEntry(e);
+    const resolved = resolveAgent(sync, e, doc);
+    const { entryPrompt, subAgents, pins } = resolved;
+    const fields = {
+        name: doc.name, description: doc.description, entry_prompt_external_id: entryPrompt, entry_version_pin: doc.entry_version,
+        max_turns: doc.max_turns, status: doc.status,
+    };
+    const remote = e.remote?.data;
+    if (!remote) {
+        const tools = subAgents.length || doc.tool_policies.length ? { sub_agents: subAgents, tool_policies: doc.tool_policies } : undefined;
+        const row = await (0, push_1.call)(ctx, 'create_agent', { external_id: doc.agent_id, ...fields, tools });
+        const created = row.agent?.agent_id;
+        if (typeof created !== 'number') {
+            throw new errors_1.CliError(`${e.key}: create_agent answered without an agent_id; check "metrio agent list" before pushing again`);
+        }
+        const id = String(created);
+        try {
+            const files = writeAgentFile(sync, e, rewriteAgentYaml(text, doc.agent_id === undefined ? created : undefined, pins));
+            return { id, files, summary: ['created', ...bumpSummary(doc, resolved)].join(', ') };
+        }
+        catch (error) {
+            throw await (0, push_1.undoCreate)(ctx, 'delete_agent', { agent_id: created }, `agent ${id}`, error);
+        }
+    }
+    const id = e.remote.id;
+    if (doc.agent_id !== undefined && String(doc.agent_id) !== id) {
+        throw new errors_1.CliError(`${e.key}/agent.yaml: agent_id must be ${id} (agent ids cannot change)`);
+    }
+    const before = {
+        name: remote.name, description: remote.description, entry_prompt_external_id: remote.entry_prompt_external_id,
+        entry_version_pin: remote.entry_version_pin, max_turns: remote.max_turns, status: remote.status,
+    };
+    const changed = Object.fromEntries(Object.entries(fields).filter(([k, v]) => v !== undefined && v !== before[k]));
+    const done = [];
+    if (Object.keys(changed).length) {
+        await (0, push_1.call)(ctx, 'update_agent', { agent_id: Number(id), ...changed });
+        done.push(`${Object.keys(changed).join(', ')} updated`);
+    }
+    if (toolSet(subAgents, doc.tool_policies) !== toolSet(remote.sub_agents, remote.tool_policies)) {
+        await (0, push_1.call)(ctx, 'set_agent_tools', { agent_id: Number(id), sub_agents: subAgents, tool_policies: doc.tool_policies });
+        done.push('tools replaced');
+    }
+    const files = pins.size ? writeAgentFile(sync, e, rewriteAgentYaml(text, undefined, pins)) : undefined;
+    return { id, ...(files ? { files } : {}), summary: [...done, ...bumpSummary(doc, resolved)].join(', ') || 'no change' };
+}
+/**
+ * Moves the sub-agent pins of agents this push did not write (an unchanged agent whose child's
+ * entry prompt got a new version) with bump_agent_pins, and rewrites their agent.yaml. Parents
+ * are sent in chunks of up to 200 pins; `onBumped` runs for each parent once its chunk applied,
+ * so a later failing chunk leaves the earlier bumps recorded.
+ */
+async function bumpUnchangedPins(ctx, entries, onBumped) {
+    const sync = ctx.agents;
+    if (!sync.bumpPins || !sync.promptSerials.size)
+        return;
+    const bumps = [];
+    for (const e of entries) {
+        if (e.kind !== 'agent' || e.status !== 'unchanged' || !e.local || !e.remote)
+            continue;
+        try {
+            const doc = parseAgentEntry(e);
+            const resolved = resolveAgent(sync, e, doc);
+            const pins = [...resolved.pins].map(([i, version]) => ({ agent_id: Number(e.remote.id), sub_agent_id: resolved.subAgents[i].agent_id, version_pin: version }));
+            if (pins.length)
+                bumps.push({ entry: e, doc, resolved, pins });
+        }
+        catch {
+            continue; // an unchanged file that no longer resolves: nothing to bump
+        }
+    }
+    const chunks = [];
+    for (const b of bumps) {
+        const last = chunks[chunks.length - 1];
+        if (last && last.reduce((n, x) => n + x.pins.length, 0) + b.pins.length <= 200)
+            last.push(b);
+        else
+            chunks.push([b]);
+    }
+    for (const chunk of chunks) {
+        const pins = chunk.flatMap((b) => b.pins);
+        try {
+            // A parent with more than 200 links still needs several calls.
+            for (let i = 0; i < pins.length; i += 200)
+                await (0, push_1.call)(ctx, 'bump_agent_pins', { pins: pins.slice(i, i + 200) });
+        }
+        catch (error) {
+            throw new errors_1.CliError(`sub-agent pins of ${chunk.map((b) => b.entry.key).join(', ')} not bumped: ${(0, push_1.message)(error)}`);
+        }
+        for (const { entry, doc, resolved } of chunk) {
+            const files = writeAgentFile(sync, entry, rewriteAgentYaml(entry.local['agent.yaml'], undefined, resolved.pins));
+            onBumped(entry, { id: entry.remote.id, files, summary: bumpSummary(doc, resolved).join(', ') });
+        }
+    }
+}
+/**
+ * Tracked agents outside this push's scope with a numeric sub-agent pin behind the head version
+ * this push gave the child's entry prompt: their pins did not move.
+ */
+function parentsOutOfScope(sync) {
+    if (!sync.bumpPins || !sync.promptSerials.size)
+        return [];
+    const inScope = new Set(sync.entries.map((e) => e.key));
+    const keys = [];
+    for (const key of sync.ids.keys()) {
+        if (!key.startsWith('agents/') || inScope.has(key))
+            continue;
+        try {
+            const doc = trackedAgentFile(sync, key);
+            if (!doc)
+                continue;
+            const stale = doc.sub_agents.some((s) => {
+                const id = s.agent !== undefined ? sync.ids.get(`agents/${s.agent}`) : String(s.agent_id);
+                const serial = id === undefined || !/^\d+$/.test(s.version) ? undefined : newEntrySerial(sync, Number(id));
+                return serial !== undefined && serial !== s.version;
+            });
+            if (stale)
+                keys.push(key);
+        }
+        catch {
+            continue; // unreadable files: nothing to hint
+        }
+    }
+    return keys.sort();
+}
+/**
+ * Every local agent in scope, written or not, must still resolve once this push is done: no
+ * reference (directory or numeric id) to something it deletes or that was deleted in the console,
+ * none to a directory it renames away, and every directory tracked or created by this push.
+ * Checked before any write.
+ */
+function checkAgentRefs(agents, created, deleted, renamed, remoteDeleted, state) {
+    const gone = [
+        ...deleted.map((d) => ({ entry: d, why: `${d.key} is deleted by this push` })),
+        ...remoteDeleted.map((d) => ({ entry: d, why: `${d.key} was deleted in the console` })),
+    ];
+    const goneWhy = new Map([
+        ...gone.map((g) => [g.entry.key, g.why]),
+        ...renamed.map((r) => [r.from, `${r.from} is renamed to ${r.key} by this push`]),
+    ]);
+    for (const e of agents) {
+        let doc;
+        try {
+            doc = parseAgentEntry(e);
+        }
+        catch {
+            continue; // the push reports the parse error
+        }
+        const refs = agentDirRefs(doc);
+        const goneRef = refs.find((r) => goneWhy.has(r.key));
+        if (goneRef)
+            throw unresolvedRef(e.key, goneRef, goneWhy.get(goneRef.key));
+        const missing = refs.find((r) => !state.resources[r.key] && !created.has(r.key));
+        if (missing)
+            throw unresolvedRef(e.key, missing);
+        const idRefs = [
+            ...(doc.entry_prompt_id !== undefined ? [{ field: 'entry_prompt_id', kind: 'prompt', id: doc.entry_prompt_id }] : []),
+            ...doc.sub_agents.flatMap((s, i) => (s.agent_id !== undefined ? [{ field: `sub_agents[${i}].agent_id`, kind: 'agent', id: s.agent_id }] : [])),
+        ];
+        for (const ref of idRefs) {
+            const g = gone.find((x) => x.entry.kind === ref.kind && x.entry.state?.id === String(ref.id));
+            if (g)
+                throw new errors_1.CliError(`${e.key}/agent.yaml: ${ref.field} ${ref.id} does not resolve (${g.why})`);
+        }
+    }
+}
+/**
+ * The sub-agent graph over `nodes` as strongly connected components (Tarjan), each emitted after
+ * every component it calls: children first.
+ */
+function agentComponents(nodes, entries) {
+    const keys = new Set(nodes.map((e) => e.key));
+    const edges = new Map(nodes.map((e) => [e.key, subAgentKeys(e, entries).filter((k) => keys.has(k))]));
+    const index = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    const connect = (v) => {
+        index.set(v, index.size);
+        low.set(v, index.get(v));
+        stack.push(v);
+        onStack.add(v);
+        for (const w of edges.get(v)) {
+            if (!index.has(w)) {
+                connect(w);
+                low.set(v, Math.min(low.get(v), low.get(w)));
+            }
+            else if (onStack.has(w))
+                low.set(v, Math.min(low.get(v), index.get(w)));
+        }
+        if (low.get(v) !== index.get(v))
+            return;
+        const members = [];
+        let w;
+        do {
+            w = stack.pop();
+            onStack.delete(w);
+            members.push(w);
+        } while (w !== v);
+        components.push({ keys: members.sort(), cyclic: members.length > 1 || edges.get(v).includes(v) });
+    };
+    for (const e of nodes)
+        if (!index.has(e.key))
+            connect(e.key);
+    return { components, edges };
+}
+/** A shortest cycle from `start` back to itself inside one component, for the error message. */
+function cycleFrom(start, members, edges) {
+    const prev = new Map();
+    const queue = [start];
+    while (queue.length) {
+        const v = queue.shift();
+        for (const w of edges.get(v)) {
+            if (w === start) {
+                const path = [v];
+                for (let x = v; x !== start; x = prev.get(x))
+                    path.unshift(prev.get(x));
+                return [...path, start];
+            }
+            if (members.has(w) && !prev.has(w)) {
+                prev.set(w, v);
+                queue.push(w);
+            }
+        }
+    }
+    return [start];
+}
+/**
+ * Agents being written, children first. A cycle (a component of several agents, or a self-link)
+ * holding an agent being written fails before any write; one only among agents this push leaves
+ * alone does not (the backend rejects only cycles through the agent being edited).
+ */
+function agentWriteOrder(entries, written) {
+    const { components, edges } = agentComponents(entries.filter((e) => e.kind === 'agent' && e.local), entries);
+    for (const c of components) {
+        const start = c.keys.find((k) => written.has(k));
+        if (c.cyclic && start)
+            throw new errors_1.CliError(`sub-agent cycle in local agent files: ${cycleFrom(start, new Set(c.keys), edges).join(' -> ')}`);
+    }
+    return components.flatMap((c) => c.keys);
+}
+/** Agents being deleted, parents before children (so a parent's link never blocks its child's delete). */
+function agentDeleteOrder(deleted, entries) {
+    return agentComponents(deleted, entries).components.flatMap((c) => c.keys).reverse();
+}

package/dist/sync/push.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.message = void 0;
+exports.call = call;
+exports.undoCreate = undoCreate;
 exports.versionContent = versionContent;
 exports.hasPendingVersion = hasPendingVersion;
 exports.pushEntry = pushEntry;
@@ -7,6 +10,7 @@ exports.deleteEntry = deleteEntry;
 const crypto_1 = require("crypto");
 const errors_1 = require("../errors");
 const remote_1 = require("./remote");
+const push_agents_1 = require("./push-agents");
 const render_1 = require("./render");
 const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
 async function call(ctx, tool, args) {
@@ -14,14 +18,15 @@ async function call(ctx, tool, args) {
 }
 const sha = (text) => (0, crypto_1.createHash)('sha256').update(text).digest('hex');
 const message = (err) => (err instanceof Error ? err.message : String(err));
+exports.message = message;
 /** Best-effort removal of a resource this push just created, so a failed push leaves no orphan. */
 async function undoCreate(ctx, tool, args, what, error) {
     try {
         await call(ctx, tool, args);
-        return new errors_1.CliError(`${message(error)} (the half-created ${what.split(' ')[0]} was removed)`);
+        return new errors_1.CliError(`${(0, exports.message)(error)} (the half-created ${what.split(' ')[0]} was removed)`);
     }
     catch (cleanup) {
-        return new errors_1.CliError(`${message(error)} (cleanup failed: ${message(cleanup)}; ${what} exists in the console)`);
+        return new errors_1.CliError(`${(0, exports.message)(error)} (cleanup failed: ${(0, exports.message)(cleanup)}; ${what} exists in the console)`);
     }
 }
 /*
@@ -164,6 +169,7 @@ async function pushPrompt(ctx, e) {
             });
             result.pushed_version_id = Number(v.id);
             result.pushed_serial = Number(v.serial);
+            result.pushed_head = head;
             result.pushed_content = content;
             result.versioned = true;
             result.summary = `version ${v.serial}${head ? ' (head)' : ''}`;
@@ -199,7 +205,7 @@ async function pushPrompt(ctx, e) {
             }
             catch (err) {
                 failedIds.push(m.instance_id);
-                failures.push(`instance ${m.instance_id}: ${message(err)}`);
+                failures.push(`instance ${m.instance_id}: ${(0, exports.message)(err)}`);
             }
         }
         if (failedIds.length) {
@@ -316,6 +322,8 @@ function pushEntry(ctx, e) {
         return pushPrompt(ctx, e);
     if (e.kind === 'skill')
         return pushSkill(ctx, e);
+    if (e.kind === 'agent')
+        return (0, push_agents_1.pushAgent)(ctx, e);
     return pushWorkflow(ctx, e);
 }
 async function deleteEntry(ctx, e) {
@@ -324,6 +332,10 @@ async function deleteEntry(ctx, e) {
         await call(ctx, 'delete_prompt', { prompt_external_id: Number(id) });
     else if (e.kind === 'skill')
         await call(ctx, 'delete_skill', { skill_id: Number(id) });
-    else
+    else if (e.kind === 'workflow')
         await call(ctx, 'delete_workflow', { workflow_id: id });
+    else if (e.kind === 'agent')
+        await call(ctx, 'delete_agent', { agent_id: Number(id) });
+    else
+        throw new errors_1.CliError(`cannot delete unknown resource kind ${String(e.kind)}`);
 }

package/dist/sync/remote.js

@@ -66,14 +66,62 @@ async function fetchWorkflows(client, project) {
         return { kind: 'workflow', id: data.workflow_id, name: data.workflow_id, files: (0, render_1.renderWorkflow)(data), data };
     });
 }
+/** Agents, minus those whose entry prompt is gone (deleted prompts leave entry_prompt_external_id null). */
+async function fetchAgents(client, project) {
+    const rows = await fetchAll(client, 'list_agents', { project_slug: project });
+    const fetched = await (0, shared_1.mapWithConcurrency)(rows, CONCURRENCY, async (row) => {
+        const res = (await read(client, 'get_agent', { project_slug: project, agent_id: row.agent_id }));
+        const a = (res.agent ?? res);
+        const tools = (a.tools ?? {});
+        for (const field of ['agent_id', 'max_turns']) {
+            if (!Number.isFinite(Number(a[field])) || a[field] === null || a[field] === undefined) {
+                throw new errors_1.CliError(`get_agent returned no valid ${field} for agent ${String(row.agent_id)}`);
+            }
+        }
+        if (a.entry_prompt_external_id === null || a.entry_prompt_external_id === undefined || !Number.isFinite(Number(a.entry_prompt_external_id))) {
+            return { skipped: { id: String(a.agent_id), name: String(a.name) } };
+        }
+        const data = {
+            agent_id: String(a.agent_id),
+            name: String(a.name),
+            description: a.description ?? null,
+            entry_prompt_external_id: Number(a.entry_prompt_external_id),
+            entry_version_pin: a.entry_version_pin ?? null,
+            max_turns: Number(a.max_turns),
+            status: String(a.status),
+            sub_agents: (tools.sub_agents ?? []).map((s) => ({ agent_id: Number(s.agent_id), version_pin: String(s.version_pin) })),
+            tool_policies: (tools.tool_policies ?? []),
+        };
+        // Directory references need the workspace's keys: computeEntries re-renders with them.
+        const files = { 'agent.yaml': (0, render_1.renderAgent)(data, { prompts: new Map(), agents: new Map() }) };
+        return { resource: { kind: 'agent', id: data.agent_id, name: data.name, files, data } };
+    });
+    return {
+        resources: fetched.flatMap((f) => (f.resource ? [f.resource] : [])),
+        skipped: fetched.flatMap((f) => (f.skipped ? [f.skipped] : [])),
+    };
+}
 /** Rendered remote resources of the given kinds, in kind order. */
 async function fetchRemote(client, project, kinds) {
-    const out = [];
+    const out = { resources: [], skippedAgents: [], agentsUnavailable: false };
     if (kinds.includes('prompt'))
-        out.push(...(await fetchPrompts(client, project)));
+        out.resources.push(...(await fetchPrompts(client, project)));
     if (kinds.includes('skill'))
-        out.push(...(await fetchSkills(client, project)));
+        out.resources.push(...(await fetchSkills(client, project)));
     if (kinds.includes('workflow'))
-        out.push(...(await fetchWorkflows(client, project)));
+        out.resources.push(...(await fetchWorkflows(client, project)));
+    if (kinds.includes('agent')) {
+        try {
+            const agents = await fetchAgents(client, project);
+            out.resources.push(...agents.resources);
+            out.skippedAgents = agents.skipped;
+        }
+        catch (error) {
+            const unknownTool = error instanceof errors_1.ConsoleApiError && error.status === 404 && error.code === 'unknown_tool';
+            if (!unknownTool || kinds.length === 1)
+                throw error;
+            out.agentsUnavailable = true;
+        }
+    }
     return out;
 }