@pipefy/pipefy-process-coder 0.1.0

package/src/commands/skills.ts

@@ -0,0 +1,137 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import type { Parsed } from '../cli/args.ts';
+import { exists } from '../util/fsx.ts';
+import { UserError, bold, dim, out, info } from '../util/log.ts';
+
+export const help = `pipe skills [list|install] [options]
+
+  list          the agent skills this install ships with (default). Local,
+                offline, no network
+
+  install       hand off to \`npx skills add\` (vercel-labs/skills), which
+                installs these skills for whichever agents you have —
+                Claude Code, Cursor, Codex, and 75+ others — choosing each
+                agent's own directory and, by default, symlinking rather than
+                copying. Needs network (fetches the \`skills\` package via npx
+                on first run) and Node's npx on PATH. Every flag after
+                \`install\` is forwarded to it verbatim; see
+                https://github.com/vercel-labs/skills or \`npx skills add --help\`.
+                Common ones:
+                  -g, --global        install to the home directory, not the
+                                       project
+                  -a, --agent <...>   target specific agents (e.g. claude-code)
+                  -s, --skill <...>   install specific skills, not all four
+                  -y, --yes           skip confirmation prompts
+                  --copy              copy instead of symlinking`;
+
+/**
+ * These skills live at \`.agents/skills/\` in this repo — one of the standard
+ * discovery locations \`npx skills add\` already walks — so they only ever
+ * triggered for an agent session opened *inside* this repo until installed
+ * somewhere every session reads from. A pulled workspace (PLAN.md, README
+ * "Where `pipe` can run") is meant to live anywhere — a client's own folder,
+ * a completely different repo — so the guidance on how to use `pipe` needs
+ * to travel with the binary, not stay pinned to one checkout.
+ *
+ * `install` used to copy the folders and manage a `~/.claude/skills`
+ * compatibility link by hand — this repo's own version of the exact problem
+ * vercel-labs/skills already solves generically, for 75+ agents, not just
+ * Claude Code. Delegating to it is less code and more correct than
+ * reinventing it, at the cost of the one thing this CLI otherwise has none
+ * of: a runtime dependency (network + npx) for this one subcommand only.
+ */
+
+/** Resolved from this file's own URL — survives `npm link` and `npm i -g .`
+ *  the same way `pipe --version` locates package.json (cli.ts). */
+const packageRoot = (): string => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, '..', '..');
+};
+
+const sourceDir = (): string => join(packageRoot(), '.agents', 'skills');
+
+const skillDirs = async (src: string): Promise<string[]> => {
+  let entries;
+  try {
+    entries = await readdir(src, { withFileTypes: true });
+  } catch (e) {
+    throw new UserError(`could not read ${src}`, (e as Error).message);
+  }
+  const names: string[] = [];
+  for (const e of entries) {
+    if (e.isDirectory() && (await exists(join(src, e.name, 'SKILL.md')))) names.push(e.name);
+  }
+  return names.sort();
+};
+
+const readSkillMeta = async (dir: string): Promise<{ description?: string }> => {
+  try {
+    const md = await readFile(join(dir, 'SKILL.md'), 'utf8');
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md)?.[1] ?? '';
+    const description = /^description:\s*(.+)$/m.exec(frontmatter)?.[1]?.trim().replace(/\r$/, '');
+    return { description };
+  } catch {
+    return {};
+  }
+};
+
+const list = async (): Promise<number> => {
+  const src = sourceDir();
+  const names = await skillDirs(src);
+  if (!names.length) throw new UserError(`no skills found under ${src}`, 'the install may be incomplete — re-clone or re-install');
+
+  out(bold(`${names.length} skill(s) ship with this install`));
+  for (const name of names) {
+    const meta = await readSkillMeta(join(src, name));
+    out(`  ${name}`);
+    if (meta.description) out(dim(`    ${meta.description}`));
+  }
+  info('');
+  info(dim('   `pipe skills install` hands off to `npx skills add`, which installs'));
+  info(dim('   these for whichever agents you have — Claude Code, Cursor, Codex and'));
+  info(dim('   75+ others — not only a session opened inside this repo.'));
+  return 0;
+};
+
+/**
+ * Everything typed after the `install`/`list` subcommand, forwarded to
+ * `npx skills add` byte for byte — reconstructing it from the parsed flags
+ * would round-trip lossily (repeated `-a`, bare `-y`, `--skill '*'`, …).
+ * `argv` is `process.argv` (node, script, `skills`, `install`, …flags).
+ */
+export const npxInstallArgs = (argv: string[], root: string): string[] => {
+  const raw = argv.slice(3);
+  const forwarded = raw[0] === 'install' || raw[0] === 'list' ? raw.slice(1) : raw;
+  return ['skills', 'add', root, ...forwarded];
+};
+
+const install = async (): Promise<number> => {
+  const src = sourceDir();
+  const names = await skillDirs(src);
+  if (!names.length) throw new UserError(`no skills found under ${src}`, 'the install may be incomplete — re-clone or re-install');
+
+  const args = npxInstallArgs(process.argv, packageRoot());
+  out(dim(`+ npx ${args.join(' ')}`));
+
+  // `shell: true` on Windows: `npx` resolves to `npx.cmd`, a batch file, and
+  // Node refuses to spawn `.cmd` directly without a shell (the CVE-2024-27980
+  // fix) — spawning `npx.cmd` outright fails with EINVAL. Node warns that the
+  // args array is then shell-concatenated unescaped, which matters for
+  // untrusted input; there is none here — `args` is this CLI's own resolved
+  // package path plus whatever the person invoking `pipe` typed themselves.
+  return new Promise<number>((resolve, reject) => {
+    const child = spawn('npx', args, { stdio: 'inherit', shell: process.platform === 'win32' });
+    child.on('error', (e) => reject(new UserError('could not run `npx skills add`', (e as Error).message)));
+    child.on('exit', (code) => resolve(code ?? 1));
+  });
+};
+
+export const run = async (p: Parsed): Promise<number> => {
+  const sub = p.positionals[0] ?? 'list';
+  if (sub === 'list') return list();
+  if (sub === 'install') return install();
+  throw new UserError(`unknown \`pipe skills ${sub}\``, 'use `pipe skills list` or `pipe skills install`');
+};

package/src/commands/verify.ts

@@ -0,0 +1,253 @@
+import { bool, type Parsed } from '../cli/args.ts';
+import { writeJson } from '../util/fsx.ts';
+import { dim, info, ok, out, stripAnsi, warn } from '../util/log.ts';
+import { fullCoverage, type PayloadEnvelope } from '../model/payload.ts';
+import { unpack } from '../codec/unpack.ts';
+import { readTree } from '../workspace/read.ts';
+import { baselineFile } from '../workspace/layout.ts';
+import { diffTrees } from '../diff/diff.ts';
+import { renderChangeSet } from '../diff/render.ts';
+import { connect, openWorkspace } from './context.ts';
+import type { Lock, LockRepo } from '../workspace/lock.ts';
+import type { IdMap } from '../apply/idmap.ts';
+import { RunRecorder, invocation } from '../report/run.ts';
+
+export const help = `pipe verify [workspace] [options]
+
+  --repo <id>    which repo in the workspace (default: the root pipe)
+  --update       adopt the live state wholesale, once it matches the workspace
+  --adopt        adopt only the server-assigned ids of entities the workspace
+                 still marks as new, keeping every unapplied edit. This is the
+                 repair for a partial apply: without it a re-plan would create
+                 those entities a second time.
+  --json         machine-readable output
+  --report       write a run report into runs/ (payload copy included)`;
+
+/**
+ * `pipe verify` — read the pipe back and diff it against what the workspace asks
+ * for. PLAN.md §5 step 6: "Empty diff = provably correct."
+ *
+ * This is the same routine the apply runs at the end, and the same one a draft
+ * rehearsal would run first. That symmetry is the safety model, and it survives
+ * the Route B applier swap untouched.
+ */
+export const run = async (p: Parsed) => {
+  const { root, lock, repo, repoDir: dir } = await openWorkspace(p);
+  const net = await connect(p);
+
+  /**
+   * `--adopt` runs before any comparison, because its whole purpose is to fix a
+   * workspace that cannot verify: entities that exist on the pipe but still read
+   * `"id": null` in the files they were authored in.
+   */
+  if (bool(p, 'adopt')) {
+    const { stampCreated, renderStamp } = await import('../workspace/stamp.ts');
+    const { writeTree } = await import('../workspace/write.ts');
+    const caps = await net.capabilities();
+    info(dim(`reading pipe ${repo.id} to match against (${caps.snapshots ? 'snapshot' : 'GraphQL reconstruction'})`));
+    const envelope =
+      caps.snapshots
+        ? await (async () => {
+            const { payload, versionId } = await net.snapshots.pull(repo.id);
+            return {
+              source: 'snapshot' as const,
+              versionId,
+              readAt: new Date().toISOString(),
+              repoKind: repo.kind,
+              coverage: fullCoverage('complete'),
+              notes: [],
+              payload,
+            };
+          })()
+        : await net.reconstructor.reconstruct(repo.id, { organizationId: lock.organizationId });
+
+    const authored = await readTree(dir);
+    const { loadBaselineEnvelope } = await import('./diff.ts');
+    const previous = await loadBaselineEnvelope(root, repo.id);
+    const stamp = stampCreated(authored, unpack(envelope), previous ? unpack(previous) : null);
+    if (!stamp.changed && !stamp.unmatched.length) {
+      ok('nothing to adopt — the workspace marks no entity as new');
+      return 0;
+    }
+    if (stamp.changed) await writeTree(dir, authored);
+    // The baseline is updated regardless: the read just done is newer than it,
+    // and leaving it stale is what makes a plan re-create what already exists.
+
+    /**
+     * The baseline has to learn about them too.
+     *
+     * A diff is baseline versus workspace. Stamping the ids into the files while
+     * leaving the baseline at its pre-apply state means the baseline has never
+     * heard of those entities, so the diff goes on proposing to create them —
+     * which is the very loop this is meant to break. The read that was just done
+     * is exactly the right new baseline.
+     */
+    await writeJson(baselineFile(root, repo.id), envelope);
+    const adoptRec = recorderFor(p, root, repo, 'verify');
+    adoptRec?.after(envelope);
+    for (const line of renderStamp(stamp)) adoptRec?.note(stripAnsi(line).trim());
+    adoptRec?.note(`adopted ${stamp.stamped.length} server id(s); ${stamp.unmatched.length} still unmatched`);
+    await write(adoptRec, stamp.changed ? 'ok' : 'no-op', `--adopt: ${stamp.stamped.length} id(s) adopted into the workspace`);
+    for (const line of renderStamp(stamp)) info(line);
+    info(dim('   the baseline now reflects the pipe, so the next diff shows only what is still unapplied'));
+    return 0;
+  }
+
+  const rec = recorderFor(p, root, repo, 'verify');
+  const result = await verifyRepo({ net, root, lock, repo, expectedTreeDir: dir });
+  rec?.after(result.envelope);
+  rec?.verified(result.ok, result.ok ? undefined : `${result.changeCount} difference(s) remain`);
+
+  if (bool(p, 'json')) {
+    out(JSON.stringify({ ok: result.ok, changes: result.changeCount }, null, 2));
+  } else {
+    out(result.render);
+  }
+
+  if (result.ok && bool(p, 'update')) {
+    /**
+     * Adopt the live state as both the files and the baseline. Updating only the
+     * baseline would leave a created entity still reading `"id": null` in the
+     * file it came from, so the next diff would propose creating it again.
+     */
+    const { writeTree } = await import('../workspace/write.ts');
+    const { upsertRepo, writeLock } = await import('../workspace/lock.ts');
+    const { refFor } = await import('./diff.ts');
+    const { tagBehaviors, behaviorDirMapOnDisk } = await import('../workspace/agents.ts');
+    const live = unpack(result.envelope);
+    // See the identical comment in apply.ts's success path: a live read-back
+    // does not know which automations are behaviors on its own.
+    live.automations = tagBehaviors(live.automations, await behaviorDirMapOnDisk(dir));
+    await writeTree(dir, live);
+    await writeJson(baselineFile(root, repo.id), result.envelope);
+    upsertRepo(lock, refFor(repo), root, live);
+    await writeLock(root, lock);
+    ok('workspace and baseline updated to the live state');
+    rec?.note('--update: workspace and baseline adopted the live state');
+  }
+
+  await write(
+    rec,
+    result.ok ? 'ok' : 'failed',
+    result.ok ? 'the pipe satisfies the workspace intent' : `${result.changeCount} difference(s) between the pipe and the workspace`,
+  );
+
+  return result.ok ? 0 : 1;
+};
+
+/**
+ * A verify is a run too — it is the read that says whether the pipe is what the
+ * workspace claims, and the payload it read is the evidence. Written only on
+ * `--report`, and never for `--json`, where the caller is a script that wants
+ * one line of output.
+ */
+const recorderFor = (p: Parsed, root: string, repo: LockRepo, kind: 'verify') =>
+  !bool(p, 'report') || bool(p, 'json')
+    ? null
+    : new RunRecorder(kind, {
+        workspace: root,
+        repo: { id: repo.id, uuid: repo.uuid, name: repo.name ?? String(repo.id), kind: repo.kind },
+        command: invocation(),
+      });
+
+const write = async (rec: RunRecorder | null, outcome: 'ok' | 'failed' | 'no-op', summary: string) => {
+  if (!rec) return;
+  const res = await rec.write(outcome, summary);
+  if (res?.error) warn(`could not write the run report: ${res.error}`);
+  else if (res) info(dim(`   run recorded in runs/${rec.id}/`));
+};
+
+export type VerifyArgs = {
+  net: Awaited<ReturnType<typeof connect>>;
+  root: string;
+  lock: Lock;
+  repo: LockRepo;
+  expectedTreeDir: string;
+  /**
+   * The id map from the apply that just ran. With it, the intent is resolved
+   * before comparison — `"phase_id": "%{_new:<uuid>}"` becomes the phase that was
+   * created — so verification compares what was actually requested. Without it
+   * (a standalone `pipe verify`), placeholder values are treated as satisfied.
+   */
+  idMap?: IdMap;
+  /**
+   * Read via GraphQL/internal-API reconstruction even when this endpoint has
+   * snapshots. `SnapshotClient.pull()` always creates a brand-new snapshot
+   * (snapshot.ts) — that is what makes a pre-apply rollback snapshot stop
+   * being restorable the moment this runs. Set when the caller has decided
+   * not to spend a snapshot on this verification, trading full coverage for
+   * leaving the rollback point alone.
+   */
+  preferReconstruct?: boolean;
+};
+
+export const verifyRepo = async (args: VerifyArgs) => {
+  const { net, lock, repo, expectedTreeDir, idMap, preferReconstruct } = args;
+  const caps = await net.capabilities();
+  const useSnapshot = caps.snapshots && !preferReconstruct;
+
+  const authored = await readTree(expectedTreeDir);
+  const expected = idMap ? (idMap.rewrite(authored) as typeof authored) : authored;
+
+  info(dim(`reading pipe ${repo.id} back (${useSnapshot ? 'snapshot' : 'GraphQL reconstruction'})`));
+  let envelope: PayloadEnvelope;
+  /**
+   * A database reads back through the snapshot path too.
+   *
+   * It used to fall through to reconstruction, which is a *weaker* check: no
+   * reconstructed group is ever 'complete', so coverage suppresses part of the
+   * comparison and a verified-clean apply proves less than it appears to.
+   * `preferReconstruct` trades that away deliberately — see its doc comment.
+   */
+  if (useSnapshot) {
+    const { payload, versionId } = await net.snapshots.pull(repo.id, `post-apply/${new Date().toISOString()}`);
+    envelope = {
+      source: 'snapshot',
+      versionId,
+      readAt: new Date().toISOString(),
+      repoKind: repo.kind,
+      coverage: fullCoverage('complete'),
+      notes: [],
+      payload,
+    };
+  } else {
+    envelope = await net.reconstructor.reconstruct(repo.id, { organizationId: lock.organizationId });
+  }
+
+  const live = unpack(envelope);
+
+  /**
+   * Direction matters: live -> expected. A change in this diff means "the pipe
+   * still needs this done", which is exactly what verification should report.
+   */
+  const createdIds = idMap
+    ? Object.values(idMap.snapshot().placeholders).map(Number).filter((n) => Number.isFinite(n))
+    : [];
+
+  if (!idMap && JSON.stringify(authored).includes('%{_new:')) {
+    warn(
+      'this workspace still names entities by placeholder, and there is no apply to resolve them against — ' +
+        'those values are reported as satisfied rather than checked. Run pipe apply, which verifies with its own id map.',
+    );
+  }
+
+  const changeSet = diffTrees(live, expected, { intentOnly: true, createdIds });
+
+  if (changeSet.changes.length === 0) {
+    return { ok: true, changeCount: 0, render: 'verified — the pipe matches the workspace', envelope, changeSet };
+  }
+
+  const residual = changeSet.changes.filter((c) => !c.flags.includes('readonly-edit'));
+  if (residual.length === 0) {
+    warn('the only differences are in read-only entities, which were never going to be applied');
+    return { ok: true, changeCount: 0, render: renderChangeSet(changeSet), envelope, changeSet };
+  }
+
+  return {
+    ok: false,
+    changeCount: residual.length,
+    render: renderChangeSet(changeSet),
+    envelope,
+    changeSet,
+  };
+};

package/src/config.ts

@@ -0,0 +1,168 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { exists, readJson, writeJson } from './util/fsx.ts';
+import { UserError, debug } from './util/log.ts';
+import { readBearer, INSTALL_HINT } from './pipefy/toolkit.ts';
+
+/**
+ * Endpoints. `internal` is the unversioned app endpoint the web UI uses; both
+ * accept the same personal API token, which is why this CLI stays token-only
+ * with no login webview or session store (PLAN.md §2.1).
+ */
+export const ENDPOINTS = {
+  graphql: process.env.PPC_GRAPHQL_URL ?? 'https://api.pipefy.com/graphql',
+  internal: process.env.PPC_INTERNAL_URL ?? 'https://app.pipefy.com/internal_api',
+  internalSettings: process.env.PPC_INTERNAL_SETTINGS_URL ?? 'https://app.pipefy.com/internal_api/settings',
+} as const;
+
+export type CredentialStore = { token?: string; organizationId?: string };
+
+const configDir = () => process.env.PPC_CONFIG_DIR ?? join(homedir(), '.ppc');
+const credPath = () => join(configDir(), 'credentials.json');
+
+export type CredentialSource =
+  /** PIPEFY_TOKEN / PPC_TOKEN in the environment. */
+  | 'env'
+  /** Resolved by the official ai-toolkit: `pipefy auth login`, or its own env vars. */
+  | 'toolkit:stored-session'
+  | 'toolkit:static-token'
+  | 'toolkit:service-account'
+  /** This tool's own file store, from `pipe login --token`. */
+  | 'file';
+
+export type Credential = {
+  token: string;
+  source: CredentialSource;
+  /** Human-readable note for `pipe doctor`. */
+  detail?: string;
+};
+
+/**
+ * Credential resolution, in order:
+ *
+ *   1. `PIPEFY_TOKEN` / `PPC_TOKEN` — an explicit override, and the only path
+ *      that needs nothing installed. CI uses this.
+ *   2. The **Pipefy AI toolkit** — `pipefy auth login` stores an OAuth session in
+ *      the OS keychain, and the toolkit resolves its own precedence (static
+ *      token, service account, stored session) on top of it. This is the
+ *      intended path: one login shared with the MCP server and the `pipefy` CLI.
+ *   3. `~/.ppc/credentials.json` — `pipe login --token`, for machines without
+ *      the toolkit.
+ *
+ * The toolkit's bearer is short-lived, so nothing caches it to disk and callers
+ * take a provider that can re-resolve. See src/pipefy/toolkit.ts.
+ */
+export const resolveCredential = async (): Promise<Credential | null> => {
+  const env = process.env.PIPEFY_TOKEN ?? process.env.PPC_TOKEN;
+  if (env && env.trim()) {
+    return { token: env.trim(), source: 'env', detail: 'PIPEFY_TOKEN in the environment' };
+  }
+
+  const toolkit = await readBearer();
+  if (toolkit?.ok) {
+    return {
+      token: toolkit.token,
+      source: `toolkit:${toolkit.source}` as CredentialSource,
+      detail:
+        toolkit.source === 'stored-session'
+          ? `ai-toolkit session${toolkit.issuer ? ` (${toolkit.issuer})` : ''}`
+          : `ai-toolkit ${toolkit.source}`,
+    };
+  }
+
+  if (await exists(credPath())) {
+    const c = await readJson<CredentialStore>(credPath());
+    if (c.token) return { token: c.token, source: 'file', detail: credPath() };
+  }
+
+  if (toolkit && !toolkit.ok) {
+    debug(`toolkit holds no credential: ${toolkit.reason}`);
+  }
+  return null;
+};
+
+/** Legacy shape, kept for callers that only need a token. */
+export const readToken = async (): Promise<string | null> => (await resolveCredential())?.token ?? null;
+
+export const requireCredential = async (): Promise<Credential> => {
+  const c = await resolveCredential();
+  if (!c) {
+    const toolkit = await readBearer();
+    throw new UserError(
+      'No Pipefy credential found.',
+      toolkit === null
+        ? `${INSTALL_HINT}. Or run \`pipe login --token <token>\`, or set PIPEFY_TOKEN.`
+        : 'run `pipe login` (browser sign-in through the Pipefy AI toolkit), ' +
+          '`pipe login --token <token>`, or set PIPEFY_TOKEN.',
+    );
+  }
+  return c;
+};
+
+export const requireToken = async (): Promise<string> => (await requireCredential()).token;
+
+/**
+ * A token provider rather than a token.
+ *
+ * The toolkit hands out short-lived OAuth access tokens, and an apply or a
+ * snapshot pull can outlive one — a snapshot alone takes ~63s. So the client
+ * holds this, caches the value, and calls again after a 401 instead of failing
+ * at step 90 of a plan.
+ */
+export type TokenProvider = (opts?: { forceRefresh?: boolean }) => Promise<string>;
+
+export const credentialProvider = async (): Promise<{ provider: TokenProvider; initial: Credential }> => {
+  const initial = await requireCredential();
+  let cached: Credential = initial;
+
+  const provider: TokenProvider = async (opts) => {
+    if (!opts?.forceRefresh) return cached.token;
+    // Only the toolkit can mint a fresh token; a static token that stopped
+    // working will not become valid by asking again.
+    if (!cached.source.startsWith('toolkit:')) return cached.token;
+    const next = await resolveCredential();
+    if (next) {
+      cached = next;
+      debug(`credential re-resolved from ${next.source}`);
+    }
+    return cached.token;
+  };
+
+  return { provider, initial };
+};
+
+export const writeToken = async (token: string, organizationId?: string) => {
+  const p = credPath();
+  const current = (await exists(p)) ? await readJson<CredentialStore>(p) : {};
+  await writeJson(p, { ...current, token, ...(organizationId ? { organizationId } : {}) });
+  try {
+    await fs.chmod(p, 0o600);
+  } catch {
+    /* best effort — Windows ACLs are not chmod */
+  }
+  return p;
+};
+
+export const readOrgId = async (): Promise<string | null> => {
+  const env = process.env.PIPEFY_ORG_ID ?? process.env.PPC_ORG_ID;
+  if (env) return env;
+  if (await exists(credPath())) {
+    const c = await readJson<CredentialStore>(credPath());
+    if (c.organizationId) return String(c.organizationId);
+  }
+  return null;
+};
+
+export const credentialsPath = credPath;
+
+/** Tunables that matter when a real client pipe is 50x the test pipe. */
+export const LIMITS = {
+  /** Parallel GraphQL/internal reads. Conservative: rate limits are unmeasured. */
+  readConcurrency: Number(process.env.PPC_READ_CONCURRENCY ?? 4),
+  /** Snapshot generation measured at ~63s (PLAN.md §1.1). */
+  snapshotPollMs: Number(process.env.PPC_SNAPSHOT_POLL_MS ?? 5_000),
+  snapshotTimeoutMs: Number(process.env.PPC_SNAPSHOT_TIMEOUT_MS ?? 300_000),
+  /** Writes are serial by default: ordering is the correctness argument. */
+  writeConcurrency: 1,
+} as const;

package/src/diff/agents.ts

@@ -0,0 +1,122 @@
+import { canonicalString } from '../util/json.ts';
+import { agentDirName, type AgentsSection } from '../workspace/agents.ts';
+import type { AgentRow } from '../pipefy/agents.ts';
+import type { Row } from '../model/payload.ts';
+
+/**
+ * The agent diff: baseline against the workspace's own files.
+ *
+ * Deliberately coarse compared to the pipe diff — an agent change is always
+ * applied as "send the whole thing" (`createAiAgent` / `updateAiAgent` replace
+ * the entire behaviors list, PLAN.md-style granular field deltas do not apply
+ * here), so there is nothing to gain from reporting which specific behavior
+ * field moved. What matters is *whether* anything did.
+ */
+
+export type AgentChangeOp = 'create' | 'update' | 'delete';
+
+export type AgentChange = {
+  key: string;
+  op: AgentChangeOp;
+  label: string;
+  before?: AgentRow;
+  after?: AgentRow;
+  /** The complete behaviors list to send — a create/update always sends all of it. */
+  behaviors: Row[];
+  destructive?: boolean;
+};
+
+export type AgentChangeSet = { changes: AgentChange[] };
+
+const isNewAgent = (a: AgentRow): boolean => !a['uuid'] || a['_new'] === true;
+
+/** Strip the tool's own routing tag before comparing — never part of the real row. */
+const forCompare = (b: Row): Row => {
+  const { _agent_dir, ...rest } = b as Row & { _agent_dir?: string };
+  return rest;
+};
+
+const sameBehaviors = (a: Row[], b: Row[]): boolean => {
+  const norm = (list: Row[]) => list.map((x) => canonicalString(forCompare(x))).sort();
+  return canonicalString(norm(a)) === canonicalString(norm(b));
+};
+
+const sameAgentFields = (before: AgentRow, after: AgentRow): boolean =>
+  String(before['name'] ?? '') === String(after['name'] ?? '') &&
+  String(before['instruction'] ?? '') === String(after['instruction'] ?? '') &&
+  canonicalString(before['dataSourceIds'] ?? []) === canonicalString(after['dataSourceIds'] ?? []) &&
+  canonicalString(before['disabledAt'] ?? null) === canonicalString(after['disabledAt'] ?? null);
+
+/**
+ * @param authoredBehaviorsByDir The workspace's current behaviors for each
+ * agent, grouped by `agentDirName` — from `tree.automations`, filtered to the
+ * ones `_agent_dir` tags, and grouped by that tag. `readAgents` alone cannot
+ * answer this: `agent.json` never carries `behaviors` (workspace/agents.ts).
+ */
+export const diffAgents = (
+  before: AgentsSection | null,
+  after: AgentsSection | null,
+  authoredBehaviorsByDir: Map<string, Row[]>,
+): AgentChangeSet => {
+  const changes: AgentChange[] = [];
+  const beforeByUuid = new Map(
+    (before?.agents ?? []).filter((a) => a['uuid']).map((a) => [String(a['uuid']), a] as const),
+  );
+  const matched = new Set<string>();
+
+  for (const a of after?.agents ?? []) {
+    const uuid = a['uuid'] ? String(a['uuid']) : null;
+    const dir = agentDirName(a);
+    const behaviors = authoredBehaviorsByDir.get(dir) ?? [];
+    const label = String(a['name'] ?? uuid ?? dir);
+    const b = uuid ? beforeByUuid.get(uuid) : undefined;
+
+    if (!b || isNewAgent(a)) {
+      changes.push({ key: uuid ? `uuid:${uuid}` : `new:${dir}`, op: 'create', label, after: a, behaviors });
+      continue;
+    }
+    matched.add(uuid as string);
+    if (!sameAgentFields(b, a) || !sameBehaviors(b.behaviors ?? [], behaviors)) {
+      changes.push({ key: `uuid:${uuid}`, op: 'update', label, before: b, after: a, behaviors });
+    }
+  }
+
+  for (const [uuid, b] of beforeByUuid) {
+    if (matched.has(uuid)) continue;
+    changes.push({
+      key: `uuid:${uuid}`,
+      op: 'delete',
+      label: String(b['name'] ?? uuid),
+      before: b,
+      behaviors: [],
+      destructive: true,
+    });
+  }
+
+  return { changes };
+};
+
+export const renderAgentChanges = (cs: AgentChangeSet): string => {
+  if (!cs.changes.length) return '';
+  const lines: string[] = [];
+  for (const c of cs.changes) {
+    const mark = c.op === 'create' ? '+' : c.op === 'delete' ? '-' : '~';
+    const tag = c.destructive ? ' [destructive]' : '';
+    const behaviorNote = c.op === 'delete' ? '' : ` (${c.behaviors.length} behavior${c.behaviors.length === 1 ? '' : 's'})`;
+    lines.push(`  ${mark} agents ${c.label}${tag}${behaviorNote}`);
+  }
+  return lines.join('\n');
+};
+
+/** This workspace's automations, grouped by which agent's `behaviors/` they came from. */
+export const groupBehaviorsByAgentDir = (automations: Row[]): Map<string, Row[]> => {
+  const byDir = new Map<string, Row[]>();
+  for (const a of automations) {
+    const dir = a['_agent_dir'] as string | undefined;
+    if (!dir) continue;
+    const arr = byDir.get(dir) ?? [];
+    arr.push(a);
+    byDir.set(dir, arr);
+  }
+  return byDir;
+};