@metrio-ai/cli 1.4.0 → 1.5.0

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;
 }

package/dist/sync/render.js

@@ -8,6 +8,8 @@ exports.renderSkill = renderSkill;
 exports.parseSkill = parseSkill;
 exports.renderWorkflow = renderWorkflow;
 exports.parseWorkflow = parseWorkflow;
+exports.renderAgent = renderAgent;
+exports.parseAgent = parseAgent;
 const yaml_1 = require("yaml");
 const errors_1 = require("../errors");
 const VERSION_FIELDS = ['output_format', 'model_settings', 'model_fallbacks', 'output_schema'];
@@ -179,3 +181,120 @@ function parseWorkflow(files, where) {
     }
     return { enabled: meta.enabled === undefined ? true : meta.enabled, definition: definition };
 }
+const dirName = (key) => key.slice(key.indexOf('/') + 1);
+function renderAgent(a, refs) {
+    const doc = { agent_id: Number(a.agent_id), name: a.name, description: a.description ?? null };
+    const promptKey = refs.prompts.get(String(a.entry_prompt_external_id));
+    if (promptKey)
+        doc.entry_prompt = dirName(promptKey);
+    else
+        doc.entry_prompt_id = a.entry_prompt_external_id;
+    doc.entry_version = a.entry_version_pin ?? null;
+    doc.max_turns = a.max_turns;
+    doc.status = a.status;
+    const subs = a.sub_agents.map((s) => {
+        const key = refs.agents.get(String(s.agent_id));
+        return { dir: key ? dirName(key) : undefined, entry: key ? { agent: dirName(key), version: s.version_pin } : { agent_id: s.agent_id, version: s.version_pin }, id: s.agent_id };
+    });
+    subs.sort((x, y) => x.dir !== undefined && y.dir !== undefined ? (x.dir < y.dir ? -1 : x.dir > y.dir ? 1 : 0)
+        : x.dir !== undefined ? -1 : y.dir !== undefined ? 1 : x.id - y.id);
+    doc.sub_agents = subs.map((s) => s.entry);
+    doc.tool_policies = [...a.tool_policies]
+        .sort((x, y) => (x.tool_name < y.tool_name ? -1 : x.tool_name > y.tool_name ? 1 : 0))
+        .map((p) => ({
+        tool_name: p.tool_name,
+        needs_approval: p.needs_approval,
+        ...(typeof p.timeout_ms === 'number' ? { timeout_ms: p.timeout_ms } : {}),
+    }));
+    return (0, yaml_1.stringify)(doc);
+}
+const AGENT_KEYS = ['agent_id', 'name', 'description', 'entry_prompt', 'entry_prompt_id', 'entry_version', 'max_turns', 'status', 'sub_agents', 'tool_policies'];
+function checkKeys(obj, allowed, where) {
+    const unknown = Object.keys(obj).filter((k) => !allowed.includes(k));
+    if (unknown.length)
+        throw new errors_1.CliError(`${where}: unknown key${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => `"${k}"`).join(', ')}`);
+}
+function mapping(value, where) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new errors_1.CliError(`${where} must be a mapping`);
+    return value;
+}
+const isId = (v) => typeof v === 'number' && Number.isInteger(v) && v > 0;
+const isText = (v) => typeof v === 'string' && v.trim() !== '';
+/** A pin is a serial or tag; YAML may read an unquoted 3 as a number. */
+function pin(value) {
+    if (typeof value === 'number' && Number.isInteger(value))
+        return String(value);
+    return isText(value) ? value : undefined;
+}
+function parseAgent(text, file) {
+    const raw = yamlObject(text, file);
+    checkKeys(raw, AGENT_KEYS, file);
+    if (!isText(raw.name))
+        throw new errors_1.CliError(`${file}: "name" is required`);
+    if (raw.agent_id !== undefined && !isId(raw.agent_id))
+        throw new errors_1.CliError(`${file}: "agent_id" must be a positive integer`);
+    if (raw.description !== undefined && raw.description !== null && typeof raw.description !== 'string') {
+        throw new errors_1.CliError(`${file}: "description" must be a string or null`);
+    }
+    if ((raw.entry_prompt === undefined) === (raw.entry_prompt_id === undefined)) {
+        throw new errors_1.CliError(`${file}: set exactly one of "entry_prompt" (directory) or "entry_prompt_id"`);
+    }
+    if (raw.entry_prompt !== undefined && !isText(raw.entry_prompt))
+        throw new errors_1.CliError(`${file}: "entry_prompt" must be a directory name`);
+    if (raw.entry_prompt_id !== undefined && !isId(raw.entry_prompt_id))
+        throw new errors_1.CliError(`${file}: "entry_prompt_id" must be a positive integer`);
+    let entryVersion = null;
+    if (raw.entry_version !== undefined && raw.entry_version !== null) {
+        const v = pin(raw.entry_version);
+        if (v === undefined)
+            throw new errors_1.CliError(`${file}: "entry_version" must be a serial, a tag, or null`);
+        entryVersion = v;
+    }
+    if (raw.max_turns !== undefined && !isId(raw.max_turns))
+        throw new errors_1.CliError(`${file}: "max_turns" must be a positive integer`);
+    if (raw.status !== undefined && !isText(raw.status))
+        throw new errors_1.CliError(`${file}: "status" must be a string`);
+    for (const field of ['sub_agents', 'tool_policies']) {
+        if (raw[field] !== undefined && !Array.isArray(raw[field]))
+            throw new errors_1.CliError(`${file}: "${field}" must be a list`);
+    }
+    const sub_agents = (raw.sub_agents ?? []).map((item, i) => {
+        const where = `${file}: sub_agents[${i}]`;
+        const s = mapping(item, where);
+        checkKeys(s, ['agent', 'agent_id', 'version'], where);
+        if ((s.agent === undefined) === (s.agent_id === undefined))
+            throw new errors_1.CliError(`${where} needs exactly one of "agent" (directory) or "agent_id"`);
+        if (s.agent !== undefined && !isText(s.agent))
+            throw new errors_1.CliError(`${where}: "agent" must be a directory name`);
+        if (s.agent_id !== undefined && !isId(s.agent_id))
+            throw new errors_1.CliError(`${where}: "agent_id" must be a positive integer`);
+        const version = pin(s.version);
+        if (version === undefined)
+            throw new errors_1.CliError(`${where}: "version" is required (a serial or tag)`);
+        return { ...(s.agent !== undefined ? { agent: s.agent } : { agent_id: s.agent_id }), version };
+    });
+    const tool_policies = (raw.tool_policies ?? []).map((item, i) => {
+        const where = `${file}: tool_policies[${i}]`;
+        const p = mapping(item, where);
+        checkKeys(p, ['tool_name', 'needs_approval', 'timeout_ms'], where);
+        if (!isText(p.tool_name))
+            throw new errors_1.CliError(`${where}: "tool_name" is required`);
+        if (typeof p.needs_approval !== 'boolean')
+            throw new errors_1.CliError(`${where}: "needs_approval" must be true or false`);
+        if (p.timeout_ms !== undefined && p.timeout_ms !== null && !isId(p.timeout_ms))
+            throw new errors_1.CliError(`${where}: "timeout_ms" must be a positive integer`);
+        return { tool_name: p.tool_name, needs_approval: p.needs_approval, ...(typeof p.timeout_ms === 'number' ? { timeout_ms: p.timeout_ms } : {}) };
+    });
+    return {
+        ...(raw.agent_id !== undefined ? { agent_id: raw.agent_id } : {}),
+        name: raw.name,
+        description: raw.description ?? null,
+        ...(raw.entry_prompt !== undefined ? { entry_prompt: raw.entry_prompt } : { entry_prompt_id: raw.entry_prompt_id }),
+        entry_version: entryVersion,
+        ...(raw.max_turns !== undefined ? { max_turns: raw.max_turns } : {}),
+        ...(raw.status !== undefined ? { status: raw.status } : {}),
+        sub_agents,
+        tool_policies,
+    };
+}