agents-pod 0.3.1 → 0.3.4

package/examples/feishu/test_feishu_drain.py

@@ -0,0 +1,157 @@
+"""Offline tests for the drain's intake rules (issue #27, ADR 0024).
+
+Nothing here touches the network, the environment or a store: whether one
+message becomes an Inbox item is a pure decision, so the tests feed hand-written
+message dicts and assert on the JSONL a pass would print.
+
+Run from this directory: python3 -m unittest test_feishu_drain -v
+"""
+
+import io
+import json
+import unittest
+from contextlib import redirect_stderr
+
+import feishu_drain as drain
+
+CHAT_ID = "oc_chat"
+CHAT_NAME = "测试群"
+BASE_AT = 1_700_000_000
+
+
+def text_message(msg_id, text, at=BASE_AT, sender_type="user", mentions=None):
+    message = {
+        "message_id": msg_id,
+        "msg_type": "text",
+        "create_time": str(at * 1000),
+        "sender": {
+            "id": "ou_human",
+            "id_type": "open_id",
+            "sender_type": sender_type,
+            "tenant_key": "tenant",
+        },
+        "body": {"content": json.dumps({"text": text}, ensure_ascii=False)},
+    }
+    if mentions is not None:
+        message["mentions"] = mentions
+    return message
+
+
+def system_message(msg_id, at=BASE_AT + 1):
+    """The measured shape: a template body and an all-empty sender."""
+    return {
+        "message_id": msg_id,
+        "msg_type": "system",
+        "create_time": str(at * 1000),
+        "sender": {"id": "", "id_type": "", "sender_type": "", "tenant_key": ""},
+        "body": {
+            "content": json.dumps(
+                {
+                    "template": "{from_user} invited {to_chatters} to the chat.",
+                    "from_user": ["徐福洋"],
+                    "to_chatters": ["邹文", "大肥鱼"],
+                },
+                ensure_ascii=False,
+            )
+        },
+    }
+
+
+def run_pass(messages, *, cursor=None, require_mention=False, open_id=None, max_items=40):
+    """One pass over a message list, as main() would assemble it."""
+    state = drain.new_pass(require_mention=require_mention, open_id=open_id)
+    kinds = [drain.absorb(state, msg, CHAT_ID, CHAT_NAME) for msg in messages]
+    collected = state["collected"]
+    collected.sort(key=lambda item: item["at"])
+    emitted = collected[:max_items]
+    lines = drain.output_lines(
+        emitted,
+        drain.advance_cursor(cursor, emitted, collected, state["consumed_at"]),
+    )
+    return kinds, [json.loads(line) for line in lines]
+
+
+class SystemEventTest(unittest.TestCase):
+    def test_system_only_pass_prints_cursor_and_no_item(self):
+        kinds, lines = run_pass([system_message("om_sys", at=BASE_AT)])
+
+        self.assertEqual(kinds, ["system"])
+        self.assertEqual(lines, [{"cursor": str(BASE_AT)}])
+
+    def test_system_then_human_yields_only_the_human_and_cursor_past_both(self):
+        kinds, lines = run_pass(
+            [
+                system_message("om_sys", at=BASE_AT),
+                text_message("om_human", "大家好", at=BASE_AT + 5),
+            ]
+        )
+
+        self.assertEqual(kinds, ["system", "item"])
+        self.assertEqual(len(lines), 2)
+        self.assertEqual(lines[0]["id"], "om_human")
+        self.assertEqual(lines[0]["body"], "大家好")
+        self.assertNotIn("system", lines[0]["body"])
+        self.assertEqual(lines[1], {"cursor": str(BASE_AT + 5)})
+
+    def test_system_event_is_logged_once_on_stderr(self):
+        stderr = io.StringIO()
+        with redirect_stderr(stderr):
+            drain.note_system_event(system_message("om_sys"), CHAT_ID)
+
+        self.assertEqual(
+            stderr.getvalue().strip(),
+            "[feishu-drain] skip system event om_sys in %s" % CHAT_ID,
+        )
+
+
+class ExistingFiltersTest(unittest.TestCase):
+    def test_require_mention_drops_unmentioned_human(self):
+        mentioned = [
+            {
+                "key": "@bot",
+                "id": {"union_id": "on_bot", "user_id": "u_bot", "open_id": "ou_bot"},
+                "name": "pod",
+            }
+        ]
+        kinds, lines = run_pass(
+            [
+                text_message("om_plain", "没人叫我", at=BASE_AT),
+                text_message("om_at", "@pod 在吗", at=BASE_AT + 1, mentions=mentioned),
+            ],
+            require_mention=True,
+            open_id="ou_bot",
+        )
+
+        self.assertEqual(kinds, ["skip", "item"])
+        self.assertEqual([line["id"] for line in lines[:-1]], ["om_at"])
+        self.assertEqual(lines[-1], {"cursor": str(BASE_AT + 1)})
+
+    def test_app_sender_is_still_dropped(self):
+        kinds, lines = run_pass(
+            [text_message("om_bot", "机器人发言", at=BASE_AT, sender_type="app")]
+        )
+
+        self.assertEqual(kinds, ["skip"])
+        self.assertEqual(lines, [{"cursor": str(BASE_AT)}])
+
+
+class CursorTest(unittest.TestCase):
+    def test_nothing_read_prints_nothing(self):
+        _, lines = run_pass([], cursor=BASE_AT)
+
+        self.assertEqual(lines, [])
+
+    def test_cursor_does_not_jump_a_queued_item(self):
+        messages = [
+            text_message("om_1", "一", at=BASE_AT),
+            text_message("om_2", "二", at=BASE_AT + 1),
+            text_message("om_3", "三", at=BASE_AT + 2),
+        ]
+        _, lines = run_pass(messages, max_items=2)
+
+        self.assertEqual([line["id"] for line in lines[:-1]], ["om_1", "om_2"])
+        self.assertEqual(lines[-1], {"cursor": str(BASE_AT + 1)})
+
+
+if __name__ == "__main__":
+    unittest.main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "Supervision for long-running coding agents: detached pods, heartbeat liveness, cron-ticked reconcile, and a Pi extension for spawning and handoff",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/src/adapters.ts

@@ -0,0 +1,303 @@
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { adaptersFile, storeRoot } from "./paths.ts";
+
+/**
+ * Adapter copies are the operator's files, outside the repository (ADRs 0023,
+ * 0024): core ships an example, the operator copies it beside their
+ * credentials. The gap this module closes is *provenance*: `--check` proves an
+ * adapter answers, never that it is current, so a copy can sit a release behind
+ * and every `doctor` line still reads ✓ (issue #26).
+ *
+ * Nothing here writes into a copy unless a human ran `adapter sync`: a package
+ * update must not silently change a command that holds live credentials.
+ */
+export interface AdapterFile {
+  name: string;
+  sha256: string;
+}
+
+/** One registered copy: where it lives, and the package state it came from. */
+export interface AdapterRecord {
+  name: string;
+  dir: string;
+  packageVersion: string;
+  files: AdapterFile[];
+}
+
+/**
+ * Files a copy owns but the package must never overwrite: credentials and the
+ * caches a platform writes for itself. Enforced even though `examples/` ships
+ * none of them — a future example that did would otherwise leak a credential
+ * over an operator's real one.
+ */
+const RUNTIME_ONLY = new Set([".env", ".token.json", ".bot.json", "state.json"]);
+
+/** `same` needs no action; `update` is a pristine copy one version behind. */
+export type AdapterFileState = "same" | "update" | "missing-in-copy" | "local-edit";
+
+export interface AdapterFilePlan {
+  name: string;
+  state: AdapterFileState;
+}
+
+export interface AdapterSyncPlan {
+  name: string;
+  dir: string;
+  packageDir: string;
+  packageVersion: string;
+  files: AdapterFilePlan[];
+  /** Package entries that are not files an operator copy can take. */
+  skipped: string[];
+}
+
+/** A fact for `doctor`; the caller decides how to print it (ADR 0027). */
+export interface AdapterFact {
+  mark: "ok" | "bad" | "note";
+  text: string;
+  next?: string;
+}
+
+/**
+ * The installed package root, derived from this module's own location: `src/`
+ * and `examples/` are siblings there, which is what makes the copy source the
+ * *installed* package rather than whatever working tree is nearby.
+ */
+export function packageRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export async function readPackageVersion(root = packageRoot()): Promise<string> {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
+      version?: string;
+    };
+    return parsed.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export function adapterPackageDir(name: string, root = packageRoot()): string {
+  return join(root, "examples", name);
+}
+
+export async function readAdapters(): Promise<AdapterRecord[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(adaptersFile(), "utf8"));
+    return Array.isArray(parsed) ? (parsed as AdapterRecord[]) : [];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/** Atomic like every other store write: a crash never leaves half a manifest. */
+export async function writeAdapters(records: AdapterRecord[]): Promise<void> {
+  const file = adaptersFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(records, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+export function sha256(content: Buffer | string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function fileSha(path: string): Promise<string | undefined> {
+  try {
+    return sha256(await readFile(path));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The files a copy takes: regular files at the top of the package's example
+ * directory. `__pycache__` and a `.pyc` would be the package's build residue,
+ * not the adapter; runtime caches are excluded by name in `RUNTIME_ONLY`.
+ */
+async function packageFiles(packageDir: string): Promise<{ files: string[]; skipped: string[] }> {
+  const entries = await readdir(packageDir, { withFileTypes: true });
+  const files: string[] = [];
+  const skipped: string[] = [];
+  for (const entry of entries) {
+    if (RUNTIME_ONLY.has(entry.name) || entry.name === "__pycache__" || entry.name.endsWith(".pyc")) {
+      skipped.push(entry.name);
+      continue;
+    }
+    if (!entry.isFile()) {
+      skipped.push(entry.name);
+      continue;
+    }
+    files.push(entry.name);
+  }
+  files.sort();
+  return { files, skipped };
+}
+
+/**
+ * What a sync would do, without doing it. A file whose copy matches the
+ * manifest but not the package is one version behind (`update`); a file that
+ * matches neither is the operator's own edit (`local-edit`) and is reported,
+ * never overwritten without `--force`.
+ */
+export async function planAdapterSync(
+  name: string,
+  options: { root?: string; dest?: string } = {},
+): Promise<AdapterSyncPlan> {
+  const root = options.root ?? packageRoot();
+  const packageDir = adapterPackageDir(name, root);
+  const info = await stat(packageDir).catch(() => undefined);
+  if (info === undefined || !info.isDirectory()) {
+    throw new Error(`the package ships no adapter named ${name} (${packageDir})`);
+  }
+  // The store root, not $HOME: a test store and a secondary install must not
+  // sync into the machine-wide copy (ADR 0004).
+  const dir = resolve(options.dest ?? join(storeRoot(), "adapters"));
+  const packageVersion = await readPackageVersion(root);
+  const { files, skipped } = await packageFiles(packageDir);
+  const recorded = (await readAdapters()).find((record) => record.name === name);
+
+  const plan: AdapterFilePlan[] = [];
+  for (const file of files) {
+    const wanted = await fileSha(join(packageDir, file));
+    const present = await fileSha(join(dir, file));
+    if (present === undefined) {
+      plan.push({ name: file, state: "missing-in-copy" });
+      continue;
+    }
+    if (present === wanted) {
+      plan.push({ name: file, state: "same" });
+      continue;
+    }
+    const known = recorded?.files.find((entry) => entry.name === file)?.sha256;
+    plan.push({ name: file, state: known !== undefined && known === present ? "update" : "local-edit" });
+  }
+  return { name, dir, packageDir, packageVersion, files: plan, skipped };
+}
+
+/** Writes the copy and records its provenance; returns what it changed. */
+export async function applyAdapterSync(
+  plan: AdapterSyncPlan,
+  options: { force?: boolean } = {},
+): Promise<{ copied: string[]; kept: string[]; manifest: string }> {
+  await mkdir(plan.dir, { recursive: true });
+  const copied: string[] = [];
+  const kept: string[] = [];
+  const files: AdapterFile[] = [];
+
+  for (const file of plan.files) {
+    const from = join(plan.packageDir, file.name);
+    const to = join(plan.dir, file.name);
+    if (file.state === "local-edit" && options.force !== true) {
+      kept.push(file.name);
+    } else if (file.state !== "same") {
+      await copyFile(from, to);
+      copied.push(file.name);
+    }
+    // The manifest records the *package* hash, never what a kept local edit
+    // happens to be: otherwise a kept file would later read as "stale" instead
+    // of "the operator edited this", which is the fact worth reporting.
+    files.push({ name: file.name, sha256: sha256(await readFile(from)) });
+  }
+
+  const records = await readAdapters();
+  const record: AdapterRecord = {
+    name: plan.name,
+    dir: plan.dir,
+    packageVersion: plan.packageVersion,
+    files: files.sort((left, right) => left.name.localeCompare(right.name)),
+  };
+  const remaining = records.filter((entry) => entry.name !== plan.name);
+  remaining.push(record);
+  await writeAdapters(remaining);
+  return { copied, kept, manifest: adaptersFile() };
+}
+
+/**
+ * Provenance facts for `doctor` (ADR 0027). Only registered copies are
+ * reported: an unregistered directory is not something core was asked to
+ * watch, and guessing would put a platform name into core.
+ */
+export async function adapterFacts(
+  records: AdapterRecord[],
+  root = packageRoot(),
+): Promise<AdapterFact[]> {
+  const facts: AdapterFact[] = [];
+  const version = await readPackageVersion(root);
+
+  for (const record of records) {
+    const dirInfo = await stat(record.dir).catch(() => undefined);
+    if (dirInfo === undefined || !dirInfo.isDirectory()) {
+      facts.push({
+        mark: "bad",
+        text: `adapters ${record.name}: ${record.dir} is gone (a registered copy)`,
+        next: `next: agents-pod adapter sync ${record.name}`,
+      });
+      continue;
+    }
+
+    if (record.files.length === 0) {
+      // A record without hashes cannot be compared, so it must not read as ✓:
+      // an empty manifest is the shape of "registered before hashes were kept".
+      facts.push({
+        mark: "note",
+        text: `adapters ${record.name}: no file hashes recorded, so nothing can be compared`,
+        next: `next: agents-pod adapter sync ${record.name} --apply`,
+      });
+      continue;
+    }
+
+    const stale: string[] = [];
+    const edited: string[] = [];
+    const absent: string[] = [];
+    for (const file of record.files) {
+      const wanted = await fileSha(join(adapterPackageDir(record.name, root), file.name));
+      const present = await fileSha(join(record.dir, file.name));
+      if (present === undefined) {
+        absent.push(file.name);
+        continue;
+      }
+      if (wanted === undefined) {
+        // The package stopped shipping it: the copy's file is now the only one.
+        continue;
+      }
+      if (present === wanted) continue;
+      if (present === file.sha256) stale.push(file.name);
+      else edited.push(file.name);
+    }
+
+    if (absent.length > 0) {
+      facts.push({
+        mark: "bad",
+        text: `adapters ${record.name}: ${absent.join(", ")} missing from ${record.dir}`,
+        next: `next: agents-pod adapter sync ${record.name}`,
+      });
+    }
+    if (stale.length > 0) {
+      facts.push({
+        mark: "bad",
+        text:
+          `adapters ${record.name}: ${stale.join(", ")} is from ${record.packageVersion}, ` +
+          `the package ships ${version}`,
+        next: `next: agents-pod adapter sync ${record.name}`,
+      });
+    }
+    if (edited.length > 0) {
+      facts.push({
+        mark: "note",
+        text: `adapters ${record.name}: ${edited.join(", ")} differs from the package (kept: a local edit)`,
+        next: `      agents-pod adapter sync ${record.name} --dry-run names it; --force overwrites it`,
+      });
+    }
+    if (absent.length === 0 && stale.length === 0 && edited.length === 0) {
+      facts.push({ mark: "ok", text: `adapters ${record.name}: matches package ${version}` });
+    }
+  }
+  return facts;
+}

package/src/cli.ts

@@ -46,6 +46,17 @@ import {
   readProjects,
   writeProjects,
 } from "./projects.ts";
+import {
+  applyProjectMove,
+  planProjectMove,
+  type ProjectMovePlan,
+} from "./relocate.ts";
+import {
+  applyAdapterSync,
+  planAdapterSync,
+  type AdapterFileState,
+  type AdapterSyncPlan,
+} from "./adapters.ts";
 import type { PodRecord } from "./registry.ts";
 import { readPods, withRegistryLock, writePods } from "./registry.ts";
 import {
@@ -1285,7 +1296,169 @@ async function spawnCmd(
   return 0;
 }
 
-/** Per-project wake-up capacity: a small persistent guardrail, not a scheduler. */
+const PROJECT_USAGE =
+  "Usage: agents-pod project cap [n|unlimited] [--project <dir>]\n" +
+  "       agents-pod project move <old> <new> [--apply] [--move-artifacts]";
+
+function printProjectMove(
+  plan: ProjectMovePlan,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): void {
+  for (const pod of plan.pods) {
+    if (pod.artifact === "missing") continue; // its refusal below is the pod's line
+    const artifact =
+      pod.artifact === "present"
+        ? `artifacts at ${pod.to}`
+        : `move artifacts from ${pod.from}`;
+    out(`✓ relocate ${pod.id}  ${plan.oldPath} → ${plan.newPath}  (${artifact})`);
+  }
+  for (const listener of plan.listeners) {
+    out(`✓ relocate ${listener.id} (template)  ${plan.oldPath} → ${plan.newPath}`);
+  }
+  for (const project of plan.projects) {
+    out(
+      `✓ relocate capacity record ${plan.oldPath} → ${plan.newPath}  (maxActive ${project.maxActive})`,
+    );
+  }
+  for (const refusal of plan.refusals) err(`✗ ${refusal.reason}`);
+}
+
+/** Relocate records after the operator moved the tree; identity stays put (ADR 0028). */
+async function projectMoveCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const apply = words.includes("--apply");
+  const moveArtifacts = words.includes("--move-artifacts");
+  const positional = words.filter((word) => word !== "--apply" && word !== "--move-artifacts");
+  if (
+    positional.length !== 2 ||
+    positional.some((word) => word.startsWith("--")) ||
+    positional[0] === undefined ||
+    positional[1] === undefined
+  ) {
+    err(PROJECT_USAGE);
+    return 2;
+  }
+
+  const cwd = deps.cwd ?? process.cwd();
+  const oldPath = resolve(cwd, positional[0]);
+  const newPath = resolve(cwd, positional[1]);
+  if (oldPath === newPath) {
+    err("old and new paths are the same; nothing to move");
+    err(PROJECT_USAGE);
+    return 2;
+  }
+
+  const plan = await planProjectMove(oldPath, newPath, { moveArtifacts });
+  if (plan.matched === 0) {
+    out(`no record is bound to ${oldPath}`);
+    if (apply) out("nothing to do");
+    return 0;
+  }
+  printProjectMove(plan, out, err);
+  if (plan.refusals.length > 0) return 1;
+  if (!apply) {
+    out("run again with --apply to write");
+    return 0;
+  }
+
+  try {
+    const result = await applyProjectMove(plan);
+    if (result.files.length === 0) {
+      out("nothing to do");
+      return 0;
+    }
+    for (const file of result.files) {
+      out(`wrote ${file.name}: ${file.changed} record${file.changed === 1 ? "" : "s"} changed`);
+    }
+    return 0;
+  } catch (error) {
+    err(`project move failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+const ADAPTER_USAGE =
+  "Usage: agents-pod adapter sync <name> [--dest <dir>] [--apply] [--force]";
+
+/** One mark per file, so a dry run reads like a diff (ADR 0029). */
+const ADAPTER_MARKS: Record<AdapterFileState, string> = {
+  same: "=",
+  update: "↑",
+  "missing-in-copy": "+",
+  "local-edit": "!",
+};
+
+function printAdapterPlan(plan: AdapterSyncPlan, out: (line: string) => void): void {
+  out(`adapter ${plan.name}  ${plan.packageDir} → ${plan.dir}  (package ${plan.packageVersion})`);
+  for (const file of plan.files) {
+    const kept = file.state === "local-edit" ? "  (kept: a local edit; --force overwrites)" : "";
+    out(`  ${ADAPTER_MARKS[file.state]} ${file.name}  ${file.state}${kept}`);
+  }
+}
+
+/**
+ * The package ships, the operator copies, `doctor` reports drift (ADR 0029).
+ * Dry run by default: nothing writes into a directory that holds a live
+ * credential unless a human asked for it in this invocation.
+ */
+async function adapterCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  if (sub !== "sync") {
+    err(`Unknown adapter command: ${sub ?? "(none)"}. Try: sync`);
+    err(ADAPTER_USAGE);
+    return 2;
+  }
+  const apply = rest.includes("--apply");
+  const force = rest.includes("--force");
+  const { flags, rest: positional } = parseFlags(
+    rest.filter((word) => word !== "--apply" && word !== "--force"),
+    ["dest"],
+  );
+  const name = positional[0];
+  if (positional.length !== 1 || name === undefined) {
+    err(ADAPTER_USAGE);
+    return 2;
+  }
+
+  let plan: AdapterSyncPlan;
+  try {
+    plan = await planAdapterSync(name, {
+      dest: flags.dest === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), flags.dest),
+    });
+  } catch (error) {
+    err((error as Error).message);
+    return 2;
+  }
+
+  printAdapterPlan(plan, out);
+  const pending = plan.files.filter((file) => file.state !== "same").length;
+  if (pending === 0) {
+    out(`already matches package ${plan.packageVersion}`);
+    return 0;
+  }
+  if (!apply) {
+    out("run again with --apply to write");
+    return 0;
+  }
+
+  const result = await applyAdapterSync(plan, { force });
+  if (result.copied.length > 0) out(`copied ${result.copied.join(", ")}`);
+  if (result.kept.length > 0) out(`kept ${result.kept.join(", ")} (local edits; --force overwrites)`);
+  out(`recorded package ${plan.packageVersion} in ${result.manifest}`);
+  return 0;
+}
+
+/** Per-project capacity and project-location record maintenance (ADR 0022, 0028). */
 async function projectCmd(
   words: string[],
   deps: CliDeps,
@@ -1293,10 +1466,17 @@ async function projectCmd(
   err: (line: string) => void,
 ): Promise<number> {
   const [sub, ...rest] = words;
+  if (sub === "move") return projectMoveCmd(rest, deps, out, err);
+  if (sub !== "cap") {
+    err(`Unknown project command: ${sub ?? "(none)"}. Try: cap | move`);
+    err(PROJECT_USAGE);
+    return 2;
+  }
+
   const { flags, rest: positional } = parseFlags(rest, ["project"]);
   const project = resolve(flags.project ?? deps.cwd ?? process.cwd());
-  if (sub !== "cap" || positional.length > 1) {
-    err("Usage: agents-pod project cap [n|unlimited] [--project <dir>]");
+  if (positional.length > 1) {
+    err(PROJECT_USAGE);
     return 2;
   }
 
@@ -1928,7 +2108,7 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
     out("");
     out("start here  agents-pod doctor   what is missing on this machine, and the command that fixes it");
     out("pods        spawn | list | status <id> | logs <id> | wake <id> | cancel <id>");
-    out("records     agent | listener | source | deliver | project | reconcile");
+    out("records     agent | listener | source | deliver | adapter | project | reconcile");
     return 0;
   }
 
@@ -1955,6 +2135,8 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
       return sourceCmd(rest, deps, out, err);
     case "deliver":
       return deliverCmd(rest, deps, out, err);
+    case "adapter":
+      return adapterCmd(rest, deps, out, err);
     case "project":
       return projectCmd(rest, deps, out, err);
     case "doctor":