@pipefy/pipefy-process-coder 0.1.0

package/src/validate/schema.ts

@@ -0,0 +1,328 @@
+import type { Row } from '../model/payload.ts';
+import type { Tree } from '../model/tree.ts';
+
+/**
+ * Structural validation — is this still a pipe?
+ *
+ * Hand-written rather than JSON-Schema-generated, for one reason: the payload
+ * has no `schema_version` and no documented column list (ROUTE-B-V2.md ask 9),
+ * so a generated schema would be as speculative as this and much harder to read
+ * when it rejects something. What is checked here is what actually breaks an
+ * apply.
+ */
+
+export type Severity = 'error' | 'warning';
+
+export type Finding = {
+  severity: Severity;
+  /** Workspace-relative file, when the finding belongs to one. */
+  file?: string;
+  entity: string;
+  message: string;
+  /** What to do about it, in one line. */
+  fix?: string;
+  /**
+   * The same finding is present in the baseline, so the pipe arrived this way
+   * and the edit did not cause it. Reported, never blocking: refusing to plan
+   * because of a pre-existing inconsistency would make some pipes uneditable.
+   */
+  preExisting?: boolean;
+};
+
+/**
+ * Field types, as a **fallback only**.
+ *
+ * The authority is `REFERENCE.md` / `.ppc/reference.json`, read from the API on
+ * the last pull and checked in `validate/reference.ts`. This list is what remains
+ * when a workspace has no reference yet, and it is kept a warning because a
+ * hand-maintained list of what an API accepts goes stale invisibly: this one
+ * carried `time_range`, which the API does not offer, and omitted
+ * `dynamic_content`, which it does — warning about a valid type and passing an
+ * invalid one, with nothing to reveal either.
+ */
+const FIELD_TYPES = new Set([
+  'assignee_select',
+  'attachment',
+  'checklist_horizontal',
+  'checklist_vertical',
+  'cnpj',
+  'connector',
+  'cpf',
+  'currency',
+  'date',
+  'datetime',
+  'due_date',
+  'dynamic_content',
+  'email',
+  'id',
+  'label_select',
+  'long_text',
+  'number',
+  'phone',
+  'radio_horizontal',
+  'radio_vertical',
+  'select',
+  'short_text',
+  'statement',
+  'time',
+  'time_range',
+]);
+
+const isNewEntity = (row: Row) => row['id'] === null || row['id'] === undefined || row['_new'] === true;
+
+const requireString = (row: Row, key: string, entity: string, file: string, findings: Finding[]) => {
+  const v = row[key];
+  if (typeof v !== 'string' || !v.trim()) {
+    findings.push({ severity: 'error', file, entity, message: `${key} is required and must be a non-empty string` });
+  }
+};
+
+export const validateSchema = (tree: Tree): Finding[] => {
+  const findings: Finding[] = [];
+
+  // ── repo ───────────────────────────────────────────────────────────────────
+  if (!tree.repo['id']) {
+    findings.push({ severity: 'error', file: 'pipe.json', entity: 'repo', message: 'id is missing — the repo row must keep its server-owned id' });
+  }
+  requireString(tree.repo, 'name', 'repo', 'pipe.json', findings);
+
+  // ── the start form is a phase, and must stay one ───────────────────────────
+  const startForm = tree.phases.find((p) => Number(p['index']) === 0);
+  if (!startForm) {
+    findings.push({
+      severity: 'error',
+      entity: 'phases',
+      message: 'no phase at index 0 — the start form is a real phase and must exist',
+      fix: 'restore the phase file whose index is 0, or re-pull',
+    });
+  }
+
+  const seenPhaseIndex = new Map<number, string>();
+  const seenUuid = new Map<string, string>();
+  const seenFieldId = new Map<string, string>();
+  const seenFieldLabel = new Map<string, string>();
+
+  const checkUuid = (row: Row, entity: string, file: string, required: boolean) => {
+    const uuid = row['uuid'];
+    if (uuid === undefined || uuid === null || uuid === '') {
+      if (required && isNewEntity(row)) {
+        findings.push({
+          severity: 'error',
+          file,
+          entity,
+          message: `new ${entity} "${String(row['name'] ?? row['label'] ?? '?')}" has no uuid`,
+          fix: `add a fresh v4 uuid — ${entity} is one of the four entity types identified by uuid`,
+        });
+      }
+      return;
+    }
+    if (typeof uuid !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid)) {
+      findings.push({ severity: 'error', file, entity, message: `uuid "${String(uuid)}" is not a v4 uuid` });
+      return;
+    }
+    const prior = seenUuid.get(uuid);
+    if (prior) {
+      findings.push({
+        severity: 'error',
+        file,
+        entity,
+        message: `uuid ${uuid} is used twice (also in ${prior})`,
+        fix: 'two entities can never share a uuid — generate a new one',
+      });
+    } else {
+      seenUuid.set(uuid, file);
+    }
+  };
+
+  for (const phase of tree.phases) {
+    const file = `phases/… ${String(phase['name'] ?? '')}`;
+    requireString(phase, 'name', 'phases', file, findings);
+    checkUuid(phase, 'phases', file, true);
+
+    const index = Number(phase['index']);
+    if (!Number.isFinite(index)) {
+      findings.push({ severity: 'error', file, entity: 'phases', message: 'index must be a number' });
+    } else {
+      const prior = seenPhaseIndex.get(index);
+      if (prior) {
+        findings.push({
+          severity: 'error',
+          file,
+          entity: 'phases',
+          message: `index ${index} is used by two phases (also "${prior}")`,
+          fix: 'phase indexes must be unique — note that reordering phases is not applicable at all',
+        });
+      }
+      seenPhaseIndex.set(index, String(phase['name'] ?? ''));
+    }
+
+    if (!Array.isArray(phase.fields)) {
+      findings.push({ severity: 'error', file, entity: 'phases', message: 'fields must be an array' });
+      continue;
+    }
+
+    for (const f of phase.fields) {
+      const ffile = `${file} / ${String(f['label'] ?? '')}`;
+      requireString(f, 'label', 'fields', ffile, findings);
+      checkUuid(f, 'fields', ffile, true);
+
+      const type = String(f['type_id'] ?? '');
+      if (!type) {
+        findings.push({ severity: 'error', file: ffile, entity: 'fields', message: 'type_id is required' });
+      } else if (!FIELD_TYPES.has(type)) {
+        findings.push({
+          severity: 'warning',
+          file: ffile,
+          entity: 'fields',
+          message: `type_id "${type}" is not one this build has seen`,
+          fix: 'run pipe pull to read the accepted list from the API — see REFERENCE.md',
+        });
+      }
+
+      if (type === 'connector' && !f['connected_pipe_id']) {
+        findings.push({
+          severity: 'error',
+          file: ffile,
+          entity: 'fields',
+          message: 'a connector field must name the repo it connects to in connected_pipe_id',
+        });
+      }
+
+      if ((type === 'select' || type === 'radio_vertical' || type === 'radio_horizontal') && !Array.isArray(f['options'])) {
+        findings.push({ severity: 'error', file: ffile, entity: 'fields', message: `a ${type} field needs an options array` });
+      }
+
+      const id = f['id'];
+      if (id !== null && id !== undefined) {
+        const prior = seenFieldId.get(String(id));
+        if (prior) {
+          findings.push({
+            severity: 'error',
+            file: ffile,
+            entity: 'fields',
+            message: `field id ${String(id)} appears twice (also in ${prior})`,
+          });
+        }
+        seenFieldId.set(String(id), ffile);
+      }
+
+      /**
+       * A duplicate label is not refused on create — `createPhaseField` happily
+       * minted two fields both labelled "Classification" (one in another phase,
+       * one in the same phase) and just disambiguated the slug underneath,
+       * confirmed live against pipe 307321096. It bites later instead:
+       * `UpdatePhaseFieldInput.label` is non-null, so *every* `updatePhaseField`
+       * call resends the field's current label whether or not it changed, and
+       * that is where a pipe-wide duplicate surfaces as "Field label has already
+       * been taken" — the exact error this rule exists to catch before an apply
+       * reaches that step. Scoped to the whole repo, not the phase, matching the
+       * already-measured table rule (a table field label is unique per table).
+       */
+      const fieldLabel = String(f['label'] ?? '').trim();
+      if (fieldLabel) {
+        const priorLabel = seenFieldLabel.get(fieldLabel);
+        if (priorLabel) {
+          findings.push({
+            severity: 'error',
+            file: ffile,
+            entity: 'fields',
+            message: `label "${fieldLabel}" is also used by another field in this pipe (${priorLabel})`,
+            fix: 'updatePhaseField resends the current label on every call and the API rejects a repeat with "Field label has already been taken" — rename one of the two before either is updated for any reason',
+          });
+        } else {
+          seenFieldLabel.set(fieldLabel, ffile);
+        }
+      }
+    }
+
+    if (!Array.isArray(phase.jump_target_ids)) {
+      findings.push({ severity: 'error', file, entity: 'phase_jumps', message: 'jump_target_ids must be an array of phase ids' });
+    }
+  }
+
+  for (const a of tree.automations) {
+    const file = `automations/${String(a['name'] ?? '')}`;
+    requireString(a, 'name', 'automations', file, findings);
+    requireString(a, 'event_id', 'automations', file, findings);
+    requireString(a, 'action_id', 'automations', file, findings);
+    checkUuid(a, 'automations', file, true);
+    if (a['_incomplete']) {
+      findings.push({
+        severity: 'warning',
+        file,
+        entity: 'automations',
+        message: 'this automation was read without its action_params — the internal API did not return its full definition',
+        fix: 'do not edit it; re-pull once the internal endpoint answers, or it will be recreated with an empty configuration',
+      });
+    }
+  }
+
+  for (const fc of tree.field_conditions) {
+    const file = `field-conditions/${String(fc['name'] ?? '')}`;
+    requireString(fc, 'name', 'field_conditions', file, findings);
+    if (!fc['phase_id']) {
+      findings.push({
+        severity: 'error',
+        file,
+        entity: 'field_conditions',
+        message: 'phase_id is required',
+        fix: 'for a phase being created in the same edit, use the placeholder "%{_new:<phase uuid>}"',
+      });
+    }
+    if (!Array.isArray(fc.actions) || fc.actions.length === 0) {
+      findings.push({ severity: 'error', file, entity: 'field_conditions', message: 'a field condition with no actions does nothing' });
+    }
+
+    /**
+     * A condition must not test the field it shows or hides.
+     *
+     * "Hide this field while it is empty" reads sensibly and is a trap: the
+     * field's visibility depends on its own value, so nobody can ever fill it,
+     * and the phase form failed to open until the condition was deleted.
+     *
+     * The API is no help here. Measured on a live pipe: it stores a
+     * self-referential condition, an `is_empty` operation and even
+     * `not_a_real_operation` without complaint, so nothing surfaces until the
+     * form is opened by a person. Every field condition read from real pipes
+     * points its expressions at one field and its actions at another.
+     *
+     * Reported as an error rather than a warning because the damage is to a form
+     * humans use, and the fix — test a different field, or drop the expression
+     * for an unconditional hide — is always available.
+     */
+    const targets = new Set(
+      (Array.isArray(fc.actions) ? fc.actions : [])
+        .map((a) => String((a as Row)['field_id'] ?? ''))
+        .filter(Boolean),
+    );
+    const cond = fc['condition'] as Row | null | undefined;
+    for (const e of ((cond?.['expressions'] as Row[] | undefined) ?? [])) {
+      /**
+       * `field_address` is not always a field: real conditions address
+       * `assignees` and `created_by` too. Only a numeric id can collide with an
+       * action target, and a placeholder is compared as written because a field
+       * created in this edit is referenced the same way on both sides.
+       */
+      const addr = String(e['field_address'] ?? e['field_id'] ?? '');
+      if (!addr || !targets.has(addr)) continue;
+      findings.push({
+        severity: 'error',
+        file,
+        entity: 'field_conditions',
+        message: `the condition tests field ${addr}, which is also the field it shows or hides`,
+        fix: 'test a different field, or remove the expression so the action applies unconditionally',
+      });
+    }
+  }
+
+  for (const l of tree.labels) checkUuid(l, 'labels', 'labels.json', true);
+
+  for (const w of tree.webhooks) {
+    requireString(w, 'url', 'webhooks', 'webhooks.json', findings);
+    if (typeof w['url'] === 'string' && !/^https?:\/\//.test(w['url'])) {
+      findings.push({ severity: 'error', file: 'webhooks.json', entity: 'webhooks', message: `url "${w['url']}" is not http(s)` });
+    }
+  }
+
+  return findings;
+};

package/src/workspace/agents.ts

@@ -0,0 +1,290 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { mkdirp, exists, writeJson, readJson } from '../util/fsx.ts';
+import { agentBaselineFile } from './layout.ts';
+import { slug } from '../util/slug.ts';
+import { unfoldCondition } from '../codec/pack.ts';
+import type { Row, PayloadEnvelope } from '../model/payload.ts';
+import type { ConditionNode } from '../model/tree.ts';
+import type { AgentRow } from '../pipefy/agents.ts';
+
+/**
+ * The `agents/` half of a workspace.
+ *
+ * AI agents are entities of the pipe but not of the snapshot payload (ROUTE-B-V2.md
+ * ask 5), so — same as `flows/` — they are read by a different query and kept
+ * beside `pipes/<id>--<name>/`, not folded into the payload tree:
+ *
+ *   pipes/<id>--<name>/agents/
+ *     _meta.json                    coverage, readAt, count
+ *     <uuid>--<slug>/
+ *       agent.json                  name, instruction, disabledAt, needReview, dataSourceIds
+ *       behaviors/<slug>.json       the agent's behaviors — each one an ordinary
+ *                                   automation (action_id: "ai_behavior"), the
+ *                                   same shape a file in automations/ has
+ *
+ * A behavior is not stored twice and not cross-referenced by id either: which
+ * agent it belongs to is not a column on the automation (the API only answers
+ * that question from the agent's side, `AiAgent.behaviors`), so *location on
+ * disk is the only record of the link*. `workspace/read.ts` tags each behavior
+ * it finds here with `_agent_dir` (which agent's folder it came from) when it
+ * folds them into `tree.automations`, and `workspace/write.ts` reads that tag
+ * back off to route the file to the same place — the same "folding is movement
+ * only" rule phases and fields already follow, just carried by a tag instead of
+ * a `phase_id` column, because automations do not have one to spare.
+ *
+ * A behavior's *content* comes only from `pipefy/agents.ts` — the snapshot
+ * payload's copy of the same automation is a stub (`behavior_uuid` plus two
+ * field-id lists, no `instruction`, no `actionsAttributes`), so a fresh pull
+ * discards it and uses this query's answer instead (`foldFreshBehaviors`,
+ * below), rather than merely tagging it in place the way `tagBehaviors` does
+ * for a tree that already has the real content — a live read-back after an
+ * apply, or an already-pulled workspace's own files.
+ *
+ * Writing a behavior is a single `createAiAgent` / `updateAiAgent` call, not
+ * `createAutomation` — confirmed against real Pipefy web UI traffic and
+ * reproduced directly. Both take the **entire** agent, including every
+ * existing behavior unchanged (by `id`) alongside whatever is new — omitting
+ * one deletes it. Not yet built in `pipe apply`.
+ */
+
+export const AGENTS_DIR = 'agents';
+/** The tag `workspace/read.ts` puts on a behavior automation, and `workspace/write.ts` reads back. */
+export const AGENT_DIR_TAG = '_agent_dir';
+
+export type AgentsMeta = {
+  coverage: 'complete' | 'unknown';
+  readAt: string;
+  agents?: number;
+  reason?: string;
+  notes: string[];
+};
+
+export type AgentsSection = {
+  meta: AgentsMeta;
+  /**
+   * `behaviors` is populated fresh from `pipefy/agents.ts` right after a pull
+   * (for `foldFreshBehaviors` to fold into `tree.automations`) and is not
+   * itself persisted to `agent.json` — the files under that agent's
+   * `behaviors/` already hold the same content, more durably. Reading an
+   * already-pulled workspace back returns it empty.
+   */
+  agents: AgentRow[];
+};
+
+export const agentsRoot = (repoDir: string) => join(repoDir, AGENTS_DIR);
+
+export const agentDirName = (agent: Pick<AgentRow, 'uuid' | 'name'>) => `${agent.uuid}--${slug(agent.name)}`;
+
+/** The empty section, for a pipe whose agents could not be read. */
+export const unknownAgents = (reason: string): AgentsSection => ({
+  meta: { coverage: 'unknown', readAt: new Date().toISOString(), reason, notes: [reason] },
+  agents: [],
+});
+
+/** id -> the directory of the agent it is a behavior of. */
+export const behaviorDirMapFrom = (agents: AgentRow[]): Map<string, string> => {
+  const dirById = new Map<string, string>();
+  for (const agent of agents) {
+    const dir = agentDirName(agent);
+    for (const b of agent.behaviors) dirById.set(String(b['id']), dir);
+  }
+  return dirById;
+};
+
+/**
+ * A fresh pull's `tree.automations` holds the *stub* the snapshot payload
+ * gives a behavior — `behavior_uuid` plus a couple of field-id lists, no
+ * `instruction`, no `actionsAttributes`. `pipefy/agents.ts` reads the real
+ * content of the same rows over a different query, so those stubs are
+ * dropped here and replaced with it — not merely tagged, the way an already-
+ * pulled workspace's behaviors are (see `tagBehaviors`) — because the stub
+ * has nothing worth keeping.
+ */
+export const foldFreshBehaviors = <T extends Row>(automations: T[], agents: AgentRow[]): T[] => {
+  const dirById = behaviorDirMapFrom(agents);
+  if (!dirById.size) return automations;
+  const withoutStubs = automations.filter((a) => !dirById.has(String(a['id'])));
+  const behaviors = agents.flatMap((agent) => {
+    const dir = agentDirName(agent);
+    return agent.behaviors.map((b) => ({ ...b, [AGENT_DIR_TAG]: dir }) as unknown as T);
+  });
+  return [...withoutStubs, ...behaviors];
+};
+
+/**
+ * The same replacement, done on the raw envelope instead of a `Tree` — for the
+ * *baseline* a fresh pull records, which is a payload envelope, not a tree.
+ *
+ * Skipping this leaves the baseline holding the snapshot's stub forever: the
+ * workspace files get the rich content (`foldFreshBehaviors`, above), the
+ * baseline does not, and `pipe diff` reports a phantom change on every single
+ * behavior on every single pull, forever, since the two can never agree.
+ *
+ * Reuses `codec/pack.ts`'s own unfolding — the exact inverse of what
+ * `codec/unpack.ts` does to build `condition` back up from `relations.conditions`
+ * / `relations.condition_expressions` — so a condition this replaces is found
+ * correctly on the next read, not silently dropped for want of a `condition_id`
+ * nothing points at.
+ */
+export const foldBehaviorsIntoEnvelope = (env: PayloadEnvelope, agents: AgentRow[]): PayloadEnvelope => {
+  const behaviorIds = new Set(agents.flatMap((a) => a.behaviors.map((b) => String(b['id']))));
+  if (!behaviorIds.size) return env;
+
+  const relations = env.payload['relations'] as Record<string, Row[]>;
+  const isRemovedAutomation = (id: unknown) => behaviorIds.has(String(id));
+
+  const automations = (relations['automations'] ?? []).filter((a) => !isRemovedAutomation(a['id']));
+  const removedConditionIds = new Set(
+    (relations['conditions'] ?? [])
+      .filter((c) => c['source_type'] === 'Automation' && isRemovedAutomation(c['source_id']))
+      .map((c) => String(c['id'])),
+  );
+  const conditions = (relations['conditions'] ?? []).filter(
+    (c) => !(c['source_type'] === 'Automation' && isRemovedAutomation(c['source_id'])),
+  );
+  const conditionExpressions = (relations['condition_expressions'] ?? []).filter(
+    (e) => !removedConditionIds.has(String(e['condition_id'])),
+  );
+  const fieldMaps = (relations['field_maps'] ?? []).filter(
+    (m) => !(m['owner_type'] === 'Automation' && isRemovedAutomation(m['owner_id'])),
+  );
+
+  for (const agent of agents) {
+    for (const raw of agent.behaviors) {
+      const { condition, field_maps: behaviorFieldMaps, ...autoRow } = raw as Row & {
+        condition?: ConditionNode | null;
+        field_maps?: Row[];
+      };
+      const id = Number(autoRow['id']);
+      automations.push({ ...autoRow, id });
+      if (condition) unfoldCondition(condition, 'Automation', id, conditions, conditionExpressions);
+      for (const m of behaviorFieldMaps ?? []) fieldMaps.push({ ...m, owner_type: 'Automation', owner_id: id });
+    }
+  }
+
+  return {
+    ...env,
+    payload: {
+      ...env.payload,
+      relations: {
+        ...relations,
+        automations,
+        conditions,
+        condition_expressions: conditionExpressions,
+        field_maps: fieldMaps,
+      } as unknown as PayloadEnvelope['payload']['relations'],
+    },
+  };
+};
+
+/**
+ * The same map, rebuilt by reading whichever agent directories already exist
+ * on disk, rather than from a fresh fetch.
+ *
+ * Needed wherever a tree gets read back from the *live* pipe rather than from
+ * this workspace — `pipe apply`'s and `pipe verify --update`'s "adopt what the
+ * server has" step, both of which `unpack()` a fresh envelope with no agent
+ * folders in sight to derive `_agent_dir` from. Without this, adopting a
+ * verified apply would write every behavior straight into `automations/`,
+ * undoing the split on every single successful apply.
+ */
+export const behaviorDirMapOnDisk = async (workspace: string): Promise<Map<string, string>> => {
+  const root = agentsRoot(workspace);
+  const dirById = new Map<string, string>();
+  if (!(await exists(root))) return dirById;
+  for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const behaviorsDir = join(root, entry.name, 'behaviors');
+    if (!(await exists(behaviorsDir))) continue;
+    for (const file of await fs.readdir(behaviorsDir)) {
+      if (!file.endsWith('.json')) continue;
+      const row = await readJson<Row>(join(behaviorsDir, file));
+      if (row['id'] !== undefined && row['id'] !== null) dirById.set(String(row['id']), entry.name);
+    }
+  }
+  return dirById;
+};
+
+/**
+ * Tag each automation that is some agent's behavior with the directory it
+ * belongs under, by id. `workspace/write.ts` reads the tag back off to route
+ * the file; `workspace/read.ts` sets the same tag itself, from wherever it
+ * actually found the file, so this is only needed for a tree that did not come
+ * from `readTree` — a fresh pull, or a live read-back adopted after an apply.
+ */
+export const tagBehaviors = <T extends Row>(automations: T[], dirById: Map<string, string>): T[] => {
+  if (!dirById.size) return automations;
+  return automations.map((a) => {
+    const dir = dirById.get(String(a['id']));
+    return dir ? ({ ...a, [AGENT_DIR_TAG]: dir } as T) : a;
+  });
+};
+
+// ── write ───────────────────────────────────────────────────────────────────
+
+export const writeAgents = async (workspace: string, section: AgentsSection): Promise<string[]> => {
+  const root = agentsRoot(workspace);
+  /**
+   * Rewritten wholesale, same reasoning as `flows/`: an agent deleted upstream
+   * must disappear from the workspace too. Behaviors are not touched here —
+   * `writeTree` owns `behaviors/`, and runs after this, so an agent's folder
+   * exists (even empty) by the time it needs somewhere to put them.
+   */
+  if (await exists(root)) await fs.rm(root, { recursive: true, force: true });
+  await mkdirp(root);
+
+  const written: string[] = [];
+  const put = async (path: string, value: unknown) => {
+    await writeJson(path, value);
+    written.push(path);
+  };
+
+  await put(join(root, '_meta.json'), section.meta);
+  for (const agent of section.agents) {
+    const dir = join(root, agentDirName(agent));
+    await mkdirp(join(dir, 'behaviors'));
+    const { behaviors: _behaviors, ...persisted } = agent;
+    await put(join(dir, 'agent.json'), persisted);
+  }
+  return written;
+};
+
+// ── read ────────────────────────────────────────────────────────────────────
+
+export const readAgents = async (workspace: string): Promise<AgentsSection | null> => {
+  const root = agentsRoot(workspace);
+  if (!(await exists(root))) return null;
+
+  const meta = (await readJson<AgentsMeta>(join(root, '_meta.json')).catch(() => null)) ?? {
+    coverage: 'unknown' as const,
+    readAt: new Date().toISOString(),
+    notes: ['agents/_meta.json is missing, so coverage is unknown'],
+  };
+
+  const agents: AgentRow[] = [];
+  for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const agentJson = join(root, entry.name, 'agent.json');
+    if (!(await exists(agentJson))) continue;
+    const persisted = await readJson<Row>(agentJson);
+    agents.push({ ...persisted, behaviors: [] } as unknown as AgentRow);
+  }
+
+  return { meta, agents };
+};
+
+/** Record what was just read as the baseline, so the next diff needs no network. */
+export const writeAgentBaseline = (workspaceRoot: string, repoId: number, section: AgentsSection) =>
+  writeJson(agentBaselineFile(workspaceRoot, repoId), section);
+
+/** The recorded agent baseline, or null when this repo has never been pulled. */
+export const readAgentBaseline = async (workspaceRoot: string, repoId: number): Promise<AgentsSection | null> => {
+  try {
+    return await readJson<AgentsSection>(agentBaselineFile(workspaceRoot, repoId));
+  } catch {
+    return null;
+  }
+};
+
+export const isNewAgent = (agent: AgentRow): boolean => !agent['uuid'] || agent['_new'] === true;