@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/codec/flow.js

@@ -0,0 +1,164 @@
+import { canonicalString } from "../util/json.js";
+const LINK_KEYS = ['nextAction', 'firstLoopAction', 'children'];
+/** Split the linked list into an ordered array, recording the links as metadata. */
+export const unlinkFlow = (flowRow) => {
+    const { version, ...flow } = flowRow;
+    const v = (version ?? {});
+    const { trigger, ...versionRest } = v;
+    const nodes = [];
+    const visit = (n) => {
+        if (!n)
+            return;
+        const { nextAction, firstLoopAction, children, ...rest } = n;
+        const node = {
+            ...rest,
+            name: String(n['name'] ?? ''),
+            type: String(n['type'] ?? ''),
+        };
+        if (firstLoopAction)
+            node['_firstLoopAction'] = String(firstLoopAction['name']);
+        if (children) {
+            node['_children'] = children.map((c) => (c ? String(c['name']) : null));
+        }
+        if (nextAction)
+            node['_nextAction'] = String(nextAction['name']);
+        nodes.push(node);
+        if (firstLoopAction)
+            visit(firstLoopAction);
+        for (const c of (children ?? []))
+            visit(c);
+        visit(nextAction);
+    };
+    visit(trigger);
+    return { flow: flow, version: versionRest, nodes };
+};
+/** Reassemble the linked list from the ordered array. The inverse of `unlinkFlow`. */
+export const linkFlow = (tree) => {
+    const byName = new Map();
+    for (const n of tree.nodes)
+        byName.set(n.name, n);
+    /**
+     * Rebuilt depth-first from the trigger, so a node the chain does not reach is
+     * simply not in the result — and `assertFlowRoundTrip` then reports it, rather
+     * than the node vanishing silently into a flow that looks fine.
+     */
+    const seen = new Set();
+    const build = (name) => {
+        if (!name)
+            return undefined;
+        const node = byName.get(name);
+        if (!node)
+            return undefined;
+        if (seen.has(name)) {
+            throw new Error(`flow codec: node ${JSON.stringify(name)} is reachable twice — the chain has a cycle`);
+        }
+        seen.add(name);
+        const { _nextAction, _firstLoopAction, _children, ...rest } = node;
+        const out = { ...rest };
+        if (_firstLoopAction) {
+            const first = build(String(_firstLoopAction));
+            if (first)
+                out['firstLoopAction'] = first;
+        }
+        if (_children) {
+            out['children'] = _children.map((c) => build(c ?? undefined) ?? null);
+        }
+        if (_nextAction) {
+            const next = build(String(_nextAction));
+            if (next)
+                out['nextAction'] = next;
+        }
+        return out;
+    };
+    const trigger = build(tree.nodes[0]?.name);
+    return { ...tree.flow, version: { ...tree.version, ...(trigger ? { trigger } : {}) } };
+};
+/**
+ * `link(unlink(F))` must equal `F`. The exit criterion PLAN-IPAAS sets for the
+ * read path, checked per flow rather than asserted once.
+ *
+ * A linear chain is the easy case; routers with empty branches and nested loops
+ * are where a fold like this breaks, so this runs on every pull.
+ */
+export const assertFlowRoundTrip = (flowRow) => {
+    const differences = [];
+    let rebuilt;
+    try {
+        rebuilt = linkFlow(unlinkFlow(flowRow));
+    }
+    catch (e) {
+        return { ok: false, differences: [{ where: '$', detail: e.message }] };
+    }
+    const a = canonicalString(flowRow);
+    const b = canonicalString(rebuilt);
+    if (a === b)
+        return { ok: true, differences: [] };
+    // Narrow it to the node that drifted; "the flow differs" is not actionable.
+    const before = unlinkFlow(flowRow);
+    const after = unlinkFlow(rebuilt);
+    if (before.nodes.length !== after.nodes.length) {
+        differences.push({
+            where: 'nodes',
+            detail: `${before.nodes.length} nodes before, ${after.nodes.length} after — ` +
+                `${before.nodes
+                    .map((n) => n.name)
+                    .filter((n) => !after.nodes.some((m) => m.name === n))
+                    .join(', ') || 'order changed'} did not survive`,
+        });
+    }
+    for (const n of before.nodes) {
+        const m = after.nodes.find((x) => x.name === n.name);
+        if (!m)
+            continue;
+        if (canonicalString(n) !== canonicalString(m)) {
+            const keys = [...new Set([...Object.keys(n), ...Object.keys(m)])].filter((k) => canonicalString(n[k]) !== canonicalString(m[k]));
+            differences.push({ where: `node ${n.name}`, detail: `differs at ${keys.join(', ')}` });
+        }
+    }
+    if (canonicalString(before.version) !== canonicalString(after.version)) {
+        differences.push({ where: 'version', detail: 'the version row differs' });
+    }
+    if (!differences.length)
+        differences.push({ where: '$', detail: 'canonical forms differ but no node did' });
+    return { ok: false, differences };
+};
+/** The node names a flow reaches, in execution order. */
+export const nodeOrder = (tree) => tree.nodes.map((n) => n.name);
+/**
+ * Which nodes run strictly before a given one.
+ *
+ * Execution order is the array order, which is depth-first through the chain — so
+ * a node in one router branch does precede a node in a later branch positionally
+ * while never running with it. That is why this walks the links instead: only the
+ * nodes on the path from the trigger to this node can be referenced by it.
+ */
+export const ancestorsOf = (tree, name) => {
+    const byName = new Map(tree.nodes.map((n) => [n.name, n]));
+    const path = [];
+    const found = new Set();
+    const walk = (current) => {
+        if (!current)
+            return false;
+        const node = byName.get(current);
+        if (!node)
+            return false;
+        if (current === name) {
+            for (const p of path)
+                found.add(p);
+            return true;
+        }
+        path.push(current);
+        const branches = [
+            node['_firstLoopAction'],
+            ...(node['_children'] ?? []),
+            node['_nextAction'],
+        ];
+        for (const b of branches)
+            if (walk(b ?? undefined))
+                return true;
+        path.pop();
+        return false;
+    };
+    walk(tree.nodes[0]?.name);
+    return found;
+};

package/dist/codec/pack.js

@@ -0,0 +1,88 @@
+import { emptyRelations } from "../model/payload.js";
+/**
+ * tree → payload. The exact inverse of unpack: it restores the owner-pointer
+ * columns that folding dropped and re-flattens the arrays.
+ *
+ * PLAN.md §3 — pack is not on v1's write path, and is built anyway, because it
+ * is the only rigorous proof that unpack is lossless, and because it is v2's
+ * engine arriving pre-tested.
+ */
+const num = (v) => {
+    if (v === null || v === undefined || v === '')
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+export const unfoldCondition = (cond, sourceType, sourceId, conditions, expressions) => {
+    const { expressions: exprs, ...rest } = cond;
+    const condRow = { ...rest, source_type: sourceType, source_id: sourceId };
+    conditions.push(condRow);
+    for (const e of exprs ?? []) {
+        expressions.push({ ...e, condition_id: condRow['id'] ?? null });
+    }
+};
+export const pack = (tree) => {
+    const relations = emptyRelations();
+    for (const phase of tree.phases) {
+        const { fields, jump_target_ids, team_member_ids, ...phaseRow } = phase;
+        const memberKey = String(phaseRow['_team_member_key'] ?? 'user_id');
+        relations.phases.push(phaseRow);
+        for (const f of fields ?? []) {
+            relations.fields.push({ ...f, phase_id: num(phaseRow['id']) ?? phaseRow['id'] });
+        }
+        for (const t of jump_target_ids ?? []) {
+            relations.phase_jumps.push({ source_phase_id: num(phaseRow['id']), target_phase_id: num(t) });
+        }
+        for (const m of team_member_ids ?? []) {
+            relations.phase_team_memberships.push({ phase_id: num(phaseRow['id']), [memberKey]: num(m) });
+        }
+    }
+    for (const auto of tree.automations) {
+        const { condition, field_maps, distribute_assignments, response_schemas, ...autoRow } = auto;
+        relations.automations.push(autoRow);
+        const id = autoRow['id'];
+        if (condition)
+            unfoldCondition(condition, 'Automation', id, relations.conditions, relations.condition_expressions);
+        for (const m of field_maps ?? []) {
+            relations.field_maps.push({ ...m, owner_type: 'Automation', owner_id: id });
+        }
+        for (const d of distribute_assignments ?? []) {
+            relations.distribute_assignments.push({ ...d, automation_id: id });
+        }
+        for (const s of response_schemas ?? []) {
+            relations.response_schemas.push({ ...s, automation_id: id });
+        }
+    }
+    for (const fc of tree.field_conditions) {
+        const { actions, condition, ...fcRow } = fc;
+        relations.field_conditions.push(fcRow);
+        for (const a of actions ?? []) {
+            relations.field_condition_actions.push({ ...a, field_condition_id: fcRow['id'] });
+        }
+        if (condition) {
+            unfoldCondition(condition, 'FieldCondition', fcRow['id'], relations.conditions, relations.condition_expressions);
+        }
+    }
+    relations.labels = tree.labels.map((r) => ({ ...r }));
+    relations.webhooks = tree.webhooks.map((r) => ({ ...r }));
+    relations.pipe_relations = tree.pipe_relations.map((r) => ({ ...r }));
+    relations.public_forms = tree.public_form ? [{ ...tree.public_form }] : [];
+    relations.repo_preferences = tree.preferences ? [{ ...tree.preferences }] : [];
+    relations.email_templates = tree.readonly.email_templates.map((r) => ({ ...r }));
+    relations.email_inboxes = tree.readonly.email_inboxes.map((r) => ({ ...r }));
+    relations.visibilities = tree.readonly.visibilities.map((r) => ({ ...r }));
+    // Restores the non-Automation field_maps rows the loop above never sees.
+    for (const m of tree.readonly.field_maps)
+        relations.field_maps.push({ ...m });
+    return { ...tree.repo, id: Number(tree.repo['id']), relations };
+};
+/** Pack back into an envelope, preserving the provenance the tree carries. */
+export const packEnvelope = (tree) => ({
+    source: tree.meta.source,
+    versionId: tree.meta.versionId ?? null,
+    readAt: tree.meta.readAt,
+    repoKind: tree.meta.repoKind,
+    coverage: tree.meta.coverage,
+    notes: tree.meta.notes,
+    payload: pack(tree),
+});

package/dist/codec/roundtrip.js

@@ -0,0 +1,86 @@
+import { canonical, canonicalString } from "../util/json.js";
+import { ENTITIES, ENTITY_NAMES } from "../model/payload.js";
+import { VOLATILE_KEYS } from "../model/volatile.js";
+import { pack } from "./pack.js";
+import { unpack } from "./unpack.js";
+/**
+ * `pack(unpack(P)) ≡ P` under a canonical form — PLAN.md §3, corrected there
+ * from byte equality to semantic equality. Chasing byte-identity would waste a
+ * week and then fail: JSON.parse turns `index: 6.0` into `6`.
+ *
+ * Two normalisations beyond canonical JSON, both principled rather than
+ * convenient:
+ *
+ *  1. Volatile columns are dropped from both sides. The codec strips them by
+ *     design (PLAN.md §9); comparing them would only ever report noise.
+ *  2. For `owned` entities — the fourteen arrays with no `uuid` and no
+ *     identity of their own — `id` is dropped. ROUTE-B-V2.md §4 argues these
+ *     are replace-sets under their owner, which is precisely the claim that
+ *     their `id` is not identity. Rows are then compared as sorted sets.
+ *
+ * Anything else that differs is a real codec bug and blocks planning.
+ */
+const stripDeep = (v) => {
+    if (Array.isArray(v))
+        return v.map(stripDeep);
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (VOLATILE_KEYS.has(k))
+                continue;
+            if (k.startsWith('_'))
+                continue; // tool metadata, never pipe structure
+            out[k] = stripDeep(val);
+        }
+        return out;
+    }
+    return v;
+};
+const normaliseRows = (name, rows) => {
+    const owned = ENTITIES[name].identity === 'owned';
+    const cleaned = rows.map((r) => {
+        const row = stripDeep(r);
+        if (owned)
+            delete row['id'];
+        return canonicalString(row);
+    });
+    // Owned rows are sets; identified rows keep their order-independent identity
+    // too, so sorting is safe for both and removes ordering noise the codec
+    // introduces by grouping fields under phases.
+    return cleaned.sort();
+};
+export const compare = (before, after) => {
+    const differences = [];
+    const rootBefore = canonical(stripDeep({ ...before, relations: undefined }));
+    const rootAfter = canonical(stripDeep({ ...after, relations: undefined }));
+    const rootKeys = new Set([...Object.keys(rootBefore), ...Object.keys(rootAfter)]);
+    for (const k of [...rootKeys].sort()) {
+        const a = JSON.stringify(rootBefore[k]);
+        const b = JSON.stringify(rootAfter[k]);
+        if (a !== b)
+            differences.push({ where: `repo.${k}`, detail: `${a} -> ${b}` });
+    }
+    for (const name of ENTITY_NAMES) {
+        const a = normaliseRows(name, before.relations?.[name] ?? []);
+        const b = normaliseRows(name, after.relations?.[name] ?? []);
+        if (JSON.stringify(a) === JSON.stringify(b))
+            continue;
+        if (a.length !== b.length) {
+            differences.push({ where: name, detail: `${a.length} rows before, ${b.length} after` });
+        }
+        const setB = new Set(b);
+        const lost = a.filter((r) => !setB.has(r));
+        const setA = new Set(a);
+        const gained = b.filter((r) => !setA.has(r));
+        for (const l of lost.slice(0, 3))
+            differences.push({ where: `${name} (lost)`, detail: l.slice(0, 300) });
+        for (const g of gained.slice(0, 3))
+            differences.push({ where: `${name} (gained)`, detail: g.slice(0, 300) });
+        if (lost.length + gained.length > 6) {
+            differences.push({ where: name, detail: `…and ${lost.length + gained.length - 6} more row differences` });
+        }
+    }
+    return { ok: differences.length === 0, differences };
+};
+/** The Phase 0 exit criterion, callable on any payload. */
+export const assertRoundTrip = (env) => compare(env.payload, pack(unpack(env)));

package/dist/codec/unpack.js

@@ -0,0 +1,181 @@
+import { rel } from "../model/payload.js";
+import { stripVolatile } from "../model/volatile.js";
+/**
+ * payload → tree.
+ *
+ * Folding is *movement only*: a folded row is the payload row, unchanged, moved
+ * under its owner. The only rewriting is (a) stripping volatile columns and
+ * (b) dropping the owner-pointer columns that folding makes redundant, both of
+ * which `pack` restores. That is what makes `pack(unpack(P)) ≡ P` a property of
+ * the design rather than of the care taken.
+ *
+ * Keys beginning with `_` are tool metadata, not pipe structure. They survive a
+ * round trip and are ignored by every comparator.
+ */
+const idOf = (r) => String(r['id'] ?? '');
+const num = (v) => {
+    if (v === null || v === undefined || v === '')
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+const byIndex = (a, b) => {
+    const ai = num(a['index']);
+    const bi = num(b['index']);
+    if (ai !== null && bi !== null && ai !== bi)
+        return ai - bi;
+    return (num(a['id']) ?? 0) - (num(b['id']) ?? 0);
+};
+/** Which key a phase_team_memberships row uses for the user id. */
+const teamMemberKey = (row) => {
+    for (const k of ['user_id', 'member_id', 'team_member_id', 'user']) {
+        if (k in row && num(row[k]) !== null)
+            return k;
+    }
+    return null;
+};
+/**
+ * Attach a condition to its owner. `conditions` rows point at their owner with
+ * (source_type, source_id); expressions point at the condition with
+ * `condition_id`, except in a reconstructed payload where no condition id
+ * exists and `_condition_owner` carries the same information.
+ */
+const takeCondition = (payload, sourceType, sourceId) => {
+    const cond = rel(payload, 'conditions').find((c) => String(c['source_type']) === sourceType && String(c['source_id']) === sourceId);
+    if (!cond)
+        return null;
+    const condId = idOf(cond);
+    const expressions = rel(payload, 'condition_expressions')
+        .filter((e) => {
+        if (condId && String(e['condition_id'] ?? '') === condId)
+            return true;
+        const owner = e['_condition_owner'];
+        return Boolean(owner && String(owner['source_type']) === sourceType && String(owner['source_id']) === sourceId);
+    })
+        .map((e) => {
+        const row = stripVolatile({ ...e });
+        // Restored by pack from the owning condition.
+        delete row['condition_id'];
+        delete row['_condition_owner'];
+        return row;
+    })
+        .sort((a, b) => (num(a['structure_id']) ?? 0) - (num(b['structure_id']) ?? 0) || (num(a['id']) ?? 0) - (num(b['id']) ?? 0));
+    const node = stripVolatile({ ...cond });
+    // Restored by pack from the owner it is nested under.
+    delete node['source_type'];
+    delete node['source_id'];
+    node.expressions = expressions;
+    return node;
+};
+export const unpack = (env) => {
+    const p = env.payload;
+    const root = {};
+    for (const [k, v] of Object.entries(p)) {
+        if (k === 'relations')
+            continue;
+        root[k] = v;
+    }
+    const fieldsByPhase = new Map();
+    for (const f of rel(p, 'fields')) {
+        const key = String(f['phase_id'] ?? '');
+        const arr = fieldsByPhase.get(key) ?? [];
+        arr.push(f);
+        fieldsByPhase.set(key, arr);
+    }
+    const phases = [...rel(p, 'phases')].sort(byIndex).map((raw) => {
+        const phaseId = idOf(raw);
+        const node = stripVolatile({ ...raw });
+        node.fields = (fieldsByPhase.get(phaseId) ?? [])
+            .slice()
+            .sort(byIndex)
+            .map((f) => stripVolatile({ ...f }));
+        // A jump row can have a null target — a jump slot enabled in the UI with
+        // no destination phase chosen yet. Kept, not filtered: a flat id array
+        // has no other way to represent "the row exists, its target does not",
+        // and dropping it here is unrecoverable by the time `pack` runs.
+        node.jump_target_ids = rel(p, 'phase_jumps')
+            .filter((j) => String(j['source_phase_id']) === phaseId)
+            .map((j) => num(j['target_phase_id']))
+            .sort((a, b) => (a === null ? 1 : b === null ? -1 : a - b));
+        const memberships = rel(p, 'phase_team_memberships').filter((m) => String(m['phase_id']) === phaseId);
+        const key = memberships.length ? teamMemberKey(memberships[0]) : null;
+        node.team_member_ids = key
+            ? memberships.map((m) => num(m[key])).filter((v) => v !== null).sort((a, b) => a - b)
+            : [];
+        if (key && key !== 'user_id')
+            node['_team_member_key'] = key;
+        return node;
+    });
+    const automations = rel(p, 'automations').map((raw) => {
+        const id = idOf(raw);
+        const node = stripVolatile({ ...raw });
+        node.condition = takeCondition(p, 'Automation', id);
+        node.field_maps = rel(p, 'field_maps')
+            .filter((m) => String(m['owner_type']) === 'Automation' && String(m['owner_id']) === id)
+            .map((m) => {
+            const row = stripVolatile({ ...m });
+            delete row['owner_type'];
+            delete row['owner_id'];
+            return row;
+        });
+        node.distribute_assignments = rel(p, 'distribute_assignments')
+            .filter((d) => String(d['automation_id'] ?? d['owner_id'] ?? '') === id)
+            .map((d) => {
+            const row = stripVolatile({ ...d });
+            delete row['automation_id'];
+            return row;
+        });
+        node.response_schemas = rel(p, 'response_schemas')
+            .filter((s) => String(s['automation_id'] ?? s['owner_id'] ?? '') === id)
+            .map((s) => {
+            const row = stripVolatile({ ...s });
+            delete row['automation_id'];
+            return row;
+        });
+        return node;
+    });
+    const field_conditions = [...rel(p, 'field_conditions')].sort(byIndex).map((raw) => {
+        const id = idOf(raw);
+        const node = stripVolatile({ ...raw });
+        node.actions = rel(p, 'field_condition_actions')
+            .filter((a) => String(a['field_condition_id']) === id)
+            .map((a) => {
+            const row = stripVolatile({ ...a });
+            delete row['field_condition_id'];
+            return row;
+        });
+        node.condition = takeCondition(p, 'FieldCondition', id);
+        return node;
+    });
+    const simple = (n) => rel(p, n).map((r) => stripVolatile({ ...r }));
+    return {
+        meta: {
+            source: env.source,
+            versionId: env.versionId ?? null,
+            readAt: env.readAt,
+            repoKind: env.repoKind,
+            coverage: env.coverage,
+            repo_columns: env.repo_columns ?? 'complete',
+            notes: env.notes,
+        },
+        repo: stripVolatile(root),
+        phases,
+        automations,
+        field_conditions,
+        labels: simple('labels'),
+        webhooks: simple('webhooks'),
+        pipe_relations: simple('pipe_relations'),
+        public_form: simple('public_forms')[0] ?? null,
+        preferences: simple('repo_preferences')[0] ?? null,
+        readonly: {
+            email_templates: simple('email_templates'),
+            email_inboxes: simple('email_inboxes'),
+            visibilities: simple('visibilities'),
+            // owner_type/owner_id kept — see model/tree.ts. The automation-owned half
+            // above already claimed and stripped its rows; this is everything left.
+            field_maps: rel(p, 'field_maps')
+                .filter((m) => String(m['owner_type']) !== 'Automation')
+                .map((m) => stripVolatile({ ...m })),
+        },
+    };
+};

package/dist/commands/agents.js

@@ -0,0 +1,145 @@
+import { info, dim, ok, warn, debug } from "../util/log.js";
+import { fetchAgents } from "../pipefy/agents.js";
+import { writeAgents, writeAgentBaseline, readAgents, readAgentBaseline, unknownAgents, agentDirName, } from "../workspace/agents.js";
+import { readTree } from "../workspace/read.js";
+import { diffAgents, groupBehaviorsByAgentDir } from "../diff/agents.js";
+import { compileAgents } from "../apply/agentops.js";
+/**
+ * The agent half of the pipe loop: read, diff, plan, apply.
+ *
+ * A behavior's own edits already flow through the ordinary automation
+ * diff/plan/apply once it is placed under its agent's `behaviors/`
+ * (workspace/agents.ts) — the row is folded into `tree.automations` like any
+ * other automation. But *sending* one is not the automation mutations: this
+ * pipe's action catalogue does not offer `ai_behavior` to `createAutomation`
+ * (confirmed live, refused), and the confirmed write path — captured from
+ * real Pipefy web UI traffic and reproduced directly — is a single
+ * `createAiAgent` / `updateAiAgent` call carrying the agent's *entire*
+ * behaviors list. So `diff/diff.ts` and `apply/compile.ts` are taught to skip
+ * any automation tagged `_agent_dir`, and this module is the whole agent-side
+ * pipeline instead: read the agent's fields plus its current behaviors
+ * (grouped from the already-read tree, since `agent.json` never carries them),
+ * diff against the baseline, compile straight to `createAiAgent` /
+ * `updateAiAgent` / `deleteAiAgent`, and send.
+ */
+/** Read a pipe's AI agents, or record why they could not be read. */
+export const pullAgentsFor = async (client, repoUuid) => {
+    if (!repoUuid)
+        return unknownAgents('this repo has no uuid on the row that was read, so agents cannot be looked up');
+    const read = await fetchAgents(client, repoUuid);
+    return {
+        meta: {
+            coverage: read.status,
+            readAt: new Date().toISOString(),
+            agents: read.status === 'complete' ? read.agents.length : undefined,
+            notes: read.note ? [read.note] : [],
+        },
+        agents: read.agents,
+    };
+};
+/** Pull and write, mirroring `pullAndWriteFlows`. Returns what was read. */
+export const pullAndWriteAgents = async (client, repoId, repoUuid, repoDir, opts = {}) => {
+    const section = await pullAgentsFor(client, repoUuid);
+    await writeAgents(repoDir, section);
+    if (opts.workspaceRoot)
+        await writeAgentBaseline(opts.workspaceRoot, repoId, section);
+    return section;
+};
+/**
+ * The agent diff: baseline against the workspace's own files.
+ *
+ * `tree`, if the caller already read one for the pipe half, is reused rather
+ * than reading the whole workspace a second time — `agent.json` alone cannot
+ * answer "what are this agent's current behaviors", only `tree.automations`
+ * (filtered to what `_agent_dir` tags) can.
+ */
+export const diffAgentsFor = async (root, repoId, dir, opts = {}) => {
+    const baseline = await readAgentBaseline(root, repoId);
+    const authored = await readAgents(dir);
+    const tree = opts.tree ?? (await readTree(dir));
+    const behaviorsByDir = groupBehaviorsByAgentDir(tree.automations);
+    return diffAgents(baseline, authored, behaviorsByDir);
+};
+export const planAgents = (client, cs) => compileAgents(client, cs);
+/**
+ * The revert change set, given both sides already read — the pure half of
+ * `planAgentRevert`, mirroring `buildFlowRevertPlan` (commands/flows.ts).
+ *
+ * A live agent read is self-contained — `AgentRow.behaviors` carries the full
+ * list (pipefy/agents.ts), unlike the authored-files side, which needs a
+ * whole tree to answer the same question because a behavior's file lives
+ * under its agent's `behaviors/` folder, not inside `agent.json`. So `before`
+ * alone is enough to build the map `diffAgents` needs for the *target* side.
+ *
+ * Direction is the mirror of an ordinary apply: `live` is the current state
+ * (baseline), `before` is the old pre-apply one (intended target).
+ */
+export const buildAgentRevertChangeSet = (live, before) => {
+    const behaviorsByDir = new Map(before.agents.map((a) => [agentDirName(a), a.behaviors ?? []]));
+    return diffAgents(live, before, behaviorsByDir);
+};
+/**
+ * What reverting to a pre-apply agent state would take — computed, not sent.
+ *
+ * `before` is a live read taken right before this apply's own agent diff was
+ * computed — the only rollback point agents have, since they are not part of
+ * the snapshot payload at all (ROUTE-B-V2.md ask 5) and their diff is
+ * ordinarily computed offline against the local baseline, which never took
+ * this read on its own. `live` here is read fresh, because some steps may
+ * have landed since `before` was taken.
+ */
+export const planAgentRevert = async (client, repoUuid, before) => {
+    const live = await pullAgentsFor(client, repoUuid);
+    const changeSet = buildAgentRevertChangeSet(live, before);
+    return { plan: await planAgents(client, changeSet), live };
+};
+export const renderAgentPlan = (plan) => {
+    const lines = [];
+    if (!plan.steps.length) {
+        lines.push('  agents: nothing to apply');
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push(`  ${plan.steps.length} agent step(s)`);
+    for (const s of plan.steps) {
+        lines.push(`    ${s.id} ${s.description}${s.destructive ? '  destructive' : ''}`);
+    }
+    return lines.join('\n');
+};
+/**
+ * Execute the agent steps.
+ *
+ * No resumability, no placeholder substitution — unlike the pipe half's
+ * executor, an agent step never depends on an id created earlier in the same
+ * plan (an agent's own uuid is not referenced by anything else this tool
+ * writes), so the machinery `apply/execute.ts` needs for that would be
+ * unused weight here. Same simplification the flow half already makes.
+ */
+export const applyAgentSteps = async (client, plan, opts = {}) => {
+    for (const step of plan.steps) {
+        if (opts.dryRun) {
+            step.status = 'skipped';
+            info(dim(`   (dry run) ${step.id} ${step.description} — not sent`));
+            continue;
+        }
+        step.status = 'running';
+        try {
+            if (step.request.missingRequired?.length) {
+                throw new Error(`missing required field(s): ${step.request.missingRequired.join(', ')}`);
+            }
+            debug(JSON.stringify(step.request.variables ?? {}).slice(0, 400));
+            step.result = await client.raw(step.request.query ?? '', step.request.variables, step.description);
+            step.status = 'done';
+            ok(`${step.id} ${step.description}`);
+        }
+        catch (e) {
+            step.status = 'failed';
+            step.error = e.message;
+            warn(`${step.id} ${step.description} — ${step.error}`);
+            if (!opts.continueOnError)
+                break;
+        }
+    }
+    const count = (s) => plan.steps.filter((x) => x.status === s).length;
+    return { done: count('done'), failed: count('failed'), skipped: count('skipped'), steps: plan.steps };
+};