agents-pod 0.3.1 → 0.3.4

package/src/doctor.ts

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { constants } from "node:fs";
 import { access, readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { adapterFacts, readAdapters, type AdapterRecord } from "./adapters.ts";
 import { readListeners, type ListenerRecord } from "./listeners.ts";
 import { readLock } from "./locks.ts";
 import { loadNotifyConfig } from "./notify/config.ts";
@@ -89,6 +90,20 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
   } else {
     const active = registry.pods.filter((pod) => pod.state === "active").length;
     storeLines.push({ mark: "ok", text: `${registry.pods.length} pods, ${active} active` });
+    // A Pod Record bound to no Listener has no other line to carry its path
+    // (ADR 0028): terminal Pods are exempt, they block no conversation.
+    const bound = new Set(
+      listeners.filter((listener) => listener.mode === "pod").map((listener) => listener.podId),
+    );
+    for (const pod of registry.pods) {
+      if (pod.state === "done" || pod.state === "cancelled" || bound.has(pod.id)) continue;
+      if (await exists(pod.project)) continue;
+      storeLines.push({
+        mark: "bad",
+        text: `pod ${pod.id}: its project ${pod.project} does not exist`,
+        detail: [`next: agents-pod project move ${pod.project} <new>`],
+      });
+    }
   }
   const lock = await readLock(reconcileLockPath());
   if (lock !== undefined) {
@@ -102,6 +117,29 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
 
   sections.push({ title: "pass", lines: await passLines(lastPass, now, sources, listeners, registry.pods) });
   sections.push({ title: "intake", lines: await intakeLines(sources, listeners, now) });
+  // A corrupt provenance file is a fact, not silence: swallowing it would
+  // restore exactly the blindness adapters.json exists to end (ADR 0029).
+  let adapters: AdapterRecord[] = [];
+  let adaptersError: string | undefined;
+  try {
+    adapters = await readAdapters();
+  } catch (error) {
+    adaptersError = (error as Error).message;
+  }
+  if (adaptersError !== undefined) {
+    sections.push({
+      title: "adapters",
+      lines: [
+        {
+          mark: "note",
+          text: `adapters.json is unreadable: ${adaptersError}`,
+          detail: ["next: agents-pod adapter sync <name> --apply rewrites it"],
+        },
+      ],
+    });
+  } else if (adapters.length > 0) {
+    sections.push({ title: "adapters", lines: await adapterLines(adapters) });
+  }
   sections.push({ title: "listeners", lines: await listenerLines(listeners, sources, registry.pods) });
   sections.push({ title: "outbound", lines: await outboundLines(deliverer, registry.pods) });
   sections.push({ title: "notify", lines: notifyLines(notify, warnings, env) });
@@ -249,6 +287,8 @@ async function listenerLines(
   const lines: DoctorLine[] = [];
   for (const listener of listeners) {
     const problems: string[] = [];
+    /** The path a `project move` would fix; `undefined` means "not a path problem". */
+    let deadPath: string | undefined;
     const origin =
       listener.source !== undefined
         ? `source ${listener.source}`
@@ -265,15 +305,32 @@ async function listenerLines(
       }
       if (listener.project !== undefined && !(await exists(listener.project))) {
         problems.push(`its project ${listener.project} does not exist`);
+        deadPath = listener.project;
       }
     } else if (!pods.some((pod) => pod.id === listener.podId)) {
       problems.push(`its Pod ${listener.podId ?? "(none)"} is not in the registry`);
+    } else {
+      // #24: a bound Pod's project is what a wake-up starts in, so a renamed
+      // directory makes the whole channel inert while this line used to read ✓.
+      const pod = pods.find((candidate) => candidate.id === listener.podId)!;
+      if (!(await exists(pod.project))) {
+        problems.push(`its Pod ${pod.id} project ${pod.project} does not exist`);
+        deadPath = pod.project;
+      } else if (!(await exists(join(pod.project, ".agents", "pods", pod.id)))) {
+        problems.push(`its Pod ${pod.id} workspace is missing under ${pod.project}`);
+      }
     }
     if (problems.length > 0) {
       lines.push({
         mark: "bad",
         text: `${listener.id}: ${problems.join("; ")}`,
-        detail: [`next: agents-pod listener rm ${listener.id}`, "      then add it again with a path that exists"],
+        detail:
+          deadPath === undefined
+            ? ["next: agents-pod listener rm " + listener.id, "      then add it again with a path that exists"]
+            : [
+                `next: agents-pod project move ${deadPath} <new>`,
+                "      a renamed repository carries <project>/.agents/pods/<id> with it (ADR 0028)",
+              ],
       });
       continue;
     }
@@ -292,6 +349,23 @@ async function listenerLines(
   return lines;
 }
 
+/**
+ * Provenance, not behaviour (issue #26): an adapter's `--check` proves it
+ * answers, never that the package's fix reached the copy. Only registered
+ * copies appear — an unregistered directory is not something core watches.
+ */
+async function adapterLines(adapters: AdapterRecord[]): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  for (const fact of await adapterFacts(adapters)) {
+    lines.push({
+      mark: fact.mark,
+      text: fact.text,
+      ...(fact.next === undefined ? {} : { detail: [fact.next] }),
+    });
+  }
+  return lines;
+}
+
 async function outboundLines(deliverer: DelivererRecord | undefined, pods: PodRecord[]): Promise<DoctorLine[]> {
   const lines: DoctorLine[] = [];
   const { pending, dead } = await outboxFacts(pods);

package/src/extension/management.ts

@@ -99,10 +99,11 @@ export function registerManagementTools(pi: ExtensionAPI): void {
     name: "spawn_pod",
     label: "Spawn Pod",
     description:
-      "Spawn a pod: a standing unit that outlives this session and wakes fresh agents inside it, one context window per wake-up, for as long as its goal stays open. A pod does not finish on its own — cancel it, or retire the goal, to end it: a router, a watcher, an inbox server, a multi-day refactor are all one pod. A pod is fed from a chat or an inbox (a source, e.g. feishu, plus a listener bound to it), sleeps between batches, and routes work to other pods by writing inbox items — a pod never spawns pods. Returns the pod id.",
+      "Spawn a pod: a standing unit that outlives this session and wakes fresh agents inside it, one context window per wake-up, for as long as its goal stays open. A pod does not finish on its own — cancel it, or retire the goal, to end it: a router, a watcher, an inbox server, a multi-day refactor are all one pod. A pod is fed from a chat or an inbox (a source, e.g. feishu, plus a listener bound to it), sleeps between batches, and routes work to other pods by writing inbox items — a pod never spawns pods. A pod has NO CLOCK: it never runs at 9:00 or every 30 minutes, it wakes when it has work. Returns the pod id.",
     promptSnippet: "Spawn a standing pod for work that outlives this session",
     promptGuidelines: [
-      "Call spawn_pod as your FIRST tool call when the user asks for anything standing or recurring — 常驻／一直跑／每天／监听／收消息／路由／服务某个 inbox／until I say stop. Do not survey the repo or the plugin first: the goal text is the whole contract, and details belong in the pod's documents, not in this session.",
+      "Decide by the signal. A TIME rule — 每天, 每小时, 每 30 分钟, 到点, 明天提醒我 — is a schedule: use schedule_task / agents-cron, which owns when work starts. A MESSAGE or a ROLE that must stay alive — 常驻, 一直跑, 监听, 收消息, 路由, 服务某个 inbox, 直到我说停, one job spanning days — is a pod: call spawn_pod as your FIRST tool call, without surveying the repo or the plugin first.",
+      "Never put a clock in a pod's goal. If the ask needs 09:00, the schedule owns the time and a pod owns the work it hands over; a pod is woken by intake, never by the clock.",
       "A pod is the right shape for a role, not only for a big job: a router that judges incoming messages, a watcher, an inbox server.",
       "A pod's agents share documents, not this conversation: put everything the successor must know into the goal text.",
       "spawn_pod returns a pod id; report that id back to the user so they can run /pod status on it. The pod owns the work from there — do not start doing its work in this session.",

package/src/paths.ts

@@ -36,6 +36,11 @@ export function sourcesFile(): string {
   return join(storeRoot(), "sources.json");
 }
 
+/** Registered adapter copies and their provenance (issue #26): beside, not inside. */
+export function adaptersFile(): string {
+  return join(storeRoot(), "adapters.json");
+}
+
 /** The single outbound delivery command, beside the Source records (ADR 0025). */
 export function delivererFile(): string {
   return join(storeRoot(), "deliverer.json");

package/src/relocate.ts

@@ -0,0 +1,395 @@
+import { randomBytes } from "node:crypto";
+import { cp, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { readListeners } from "./listeners.ts";
+import { listenersFile, podDir, podsFile, projectsFile } from "./paths.ts";
+import { readProjects } from "./projects.ts";
+import { readPods, withRegistryLock } from "./registry.ts";
+
+export type MoveArtifact = "present" | "missing" | "moved";
+
+export interface ProjectMovePod {
+  id: string;
+  from: string;
+  to: string;
+  artifact: MoveArtifact;
+}
+
+export interface ProjectMoveListener {
+  id: string;
+  from: string;
+  to: string;
+}
+
+export interface ProjectMoveCapacity {
+  from: string;
+  to: string;
+  maxActive: number;
+}
+
+export interface ProjectMoveRefusal {
+  reason: string;
+}
+
+export interface ProjectMovePlan {
+  oldPath: string;
+  newPath: string;
+  moveArtifacts: boolean;
+  pods: ProjectMovePod[];
+  listeners: ProjectMoveListener[];
+  projects: ProjectMoveCapacity[];
+  refusals: ProjectMoveRefusal[];
+  matched: number;
+}
+
+export interface ProjectMoveResult {
+  files: Array<{ name: "pods.json" | "listeners.json" | "projects.json"; changed: number }>;
+}
+
+async function exists(path: string): Promise<boolean> {
+  return stat(path).then(
+    () => true,
+    () => false,
+  );
+}
+
+/**
+ * A project path is a location, not Pod identity (ADR 0028). The plan is a
+ * read-only snapshot; apply re-reads every record under the registry lock.
+ */
+export async function planProjectMove(
+  oldPath: string,
+  newPath: string,
+  { moveArtifacts = false }: { moveArtifacts?: boolean },
+): Promise<ProjectMovePlan> {
+  const oldRoot = resolve(oldPath);
+  const newRoot = resolve(newPath);
+  const [pods, listeners, projects] = await Promise.all([
+    readPods(),
+    readListeners(),
+    readProjects(),
+  ]);
+
+  const movingPods = pods.filter((pod) => resolve(pod.project) === oldRoot);
+  const movingListeners = listeners.filter(
+    (listener) =>
+      listener.mode === "template" &&
+      listener.project !== undefined &&
+      resolve(listener.project) === oldRoot,
+  );
+  const movingProjects = projects.filter((project) => resolve(project.project) === oldRoot);
+  const matched = movingPods.length + movingListeners.length + movingProjects.length;
+  const plan: ProjectMovePlan = {
+    oldPath: oldRoot,
+    newPath: newRoot,
+    moveArtifacts,
+    pods: [],
+    listeners: movingListeners.map((listener) => ({
+      id: listener.id,
+      from: oldRoot,
+      to: newRoot,
+    })),
+    projects: movingProjects.map((project) => ({
+      from: oldRoot,
+      to: newRoot,
+      maxActive: project.maxActive,
+    })),
+    refusals: [],
+    matched,
+  };
+
+  // An empty old binding is already the desired end state. In particular, a
+  // repeated apply must not mistake the records just moved to newPath for an
+  // ambiguous target.
+  if (matched === 0) return plan;
+
+  for (const pod of pods) {
+    if (resolve(pod.project) === newRoot) {
+      plan.refusals.push({
+        reason: `target ${newRoot} is already bound to pod ${pod.id}; choose a different new path`,
+      });
+    }
+  }
+  for (const listener of listeners) {
+    if (
+      listener.mode === "template" &&
+      listener.project !== undefined &&
+      resolve(listener.project) === newRoot
+    ) {
+      plan.refusals.push({
+        reason: `target ${newRoot} is already bound to template listener ${listener.id}; choose a different new path`,
+      });
+    }
+  }
+  if (projects.some((project) => resolve(project.project) === newRoot)) {
+    plan.refusals.push({
+      reason: `target ${newRoot} is already bound to a capacity record; choose a different new path`,
+    });
+  }
+
+  for (const pod of movingPods) {
+    const from = podDir(oldRoot, pod.id);
+    const to = podDir(newRoot, pod.id);
+    const present = await exists(to);
+    const artifact: MoveArtifact = present ? "present" : moveArtifacts ? "moved" : "missing";
+    plan.pods.push({ id: pod.id, from, to, artifact });
+    if (artifact === "missing") {
+      plan.refusals.push({
+        reason: `pod ${pod.id}: artifacts missing at ${to} (pass --move-artifacts)`,
+      });
+    }
+  }
+
+  // Normally an existing old root means the operator has not moved the tree.
+  // --move-artifacts is the explicit exception: its source workspace must
+  // still exist under oldRoot so apply can carry it to newRoot.
+  if (!moveArtifacts && (await exists(oldRoot))) {
+    plan.refusals.push({
+      reason: `old path ${oldRoot} still exists; move it to ${newRoot} before relocating records`,
+    });
+  }
+
+  return plan;
+}
+
+interface RegistryUpdate {
+  name: "pods.json" | "listeners.json" | "projects.json";
+  file: string;
+  changed: number;
+  body: string;
+}
+
+interface StagedUpdate extends RegistryUpdate {
+  tmp: string;
+  original: string | undefined;
+  committed: boolean;
+}
+
+async function readOriginal(file: string): Promise<string | undefined> {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+async function stageUpdate(update: RegistryUpdate): Promise<StagedUpdate> {
+  await mkdir(dirname(update.file), { recursive: true });
+  const tmp = `${update.file}.${randomBytes(4).toString("hex")}.tmp`;
+  const original = await readOriginal(update.file);
+  await writeFile(tmp, update.body, { flag: "wx" });
+  return { ...update, tmp, original, committed: false };
+}
+
+async function restoreOriginal(update: StagedUpdate): Promise<void> {
+  if (update.original === undefined) {
+    await rm(update.file, { force: true });
+    return;
+  }
+  const tmp = `${update.file}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    await writeFile(tmp, update.original, { flag: "wx" });
+    await rename(tmp, update.file);
+  } catch (error) {
+    await rm(tmp, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+async function moveDirectory(from: string, to: string): Promise<void> {
+  await mkdir(dirname(to), { recursive: true });
+  try {
+    await rename(from, to);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EXDEV") throw error;
+    // rename cannot cross filesystems. Copy the complete tree before removing
+    // the source so an EXDEV move has the same all-or-nothing visible result.
+    await cp(from, to, { recursive: true, force: false, errorOnExist: true });
+    await rm(from, { recursive: true, force: true });
+  }
+}
+
+function changedCount<T>(before: T[], after: T[]): number {
+  let changed = 0;
+  for (let index = 0; index < before.length; index += 1) {
+    if (before[index] !== after[index]) changed += 1;
+  }
+  return changed;
+}
+
+/**
+ * Commit all three registries as one lock-held operation (ADRs 0018, 0028).
+ * Every complete JSON body and temp file is prepared before an artifact or
+ * registry changes. A later failure restores earlier renames and moved dirs.
+ */
+export async function applyProjectMove(plan: ProjectMovePlan): Promise<ProjectMoveResult> {
+  if (plan.matched === 0) return { files: [] };
+  if (plan.refusals.length > 0) {
+    throw new Error(`project move refused: ${plan.refusals.map((refusal) => refusal.reason).join("; ")}`);
+  }
+
+  const applied = await withRegistryLock(async (): Promise<ProjectMoveResult> => {
+    const [pods, listeners, projects] = await Promise.all([
+      readPods(),
+      readListeners(),
+      readProjects(),
+    ]);
+    const podIds = new Set(plan.pods.map((pod) => pod.id));
+    const listenerIds = new Set(plan.listeners.map((listener) => listener.id));
+
+    // "The target is already bound" was decided by the dry run, outside this
+    // lock: a spawn or a second listener could have bound it in between, and
+    // merging two projects' records into one path is the ambiguity the refusal
+    // exists for. Re-read the fact instead of trusting the plan.
+    const foreignPod = pods.find(
+      (pod) => resolve(pod.project) === plan.newPath && !podIds.has(pod.id),
+    );
+    if (foreignPod !== undefined) {
+      throw new Error(
+        `target ${plan.newPath} is now bound to pod ${foreignPod.id}; nothing was moved — re-run project move`,
+      );
+    }
+    const foreignListener = listeners.find(
+      (listener) =>
+        listener.mode === "template" &&
+        listener.project !== undefined &&
+        resolve(listener.project) === plan.newPath &&
+        !listenerIds.has(listener.id),
+    );
+    if (foreignListener !== undefined) {
+      throw new Error(
+        `target ${plan.newPath} is now bound to template listener ${foreignListener.id}; nothing was moved — re-run project move`,
+      );
+    }
+    if (projects.some((project) => resolve(project.project) === plan.newPath)) {
+      throw new Error(
+        `target ${plan.newPath} is now bound to a capacity record; nothing was moved — re-run project move`,
+      );
+    }
+
+    const nextPods = pods.map((pod) =>
+      podIds.has(pod.id) && resolve(pod.project) === plan.oldPath
+        ? { ...pod, project: plan.newPath }
+        : pod,
+    );
+    const nextListeners = listeners.map((listener) =>
+      listenerIds.has(listener.id) &&
+      listener.mode === "template" &&
+      listener.project !== undefined &&
+      resolve(listener.project) === plan.oldPath
+        ? { ...listener, project: plan.newPath }
+        : listener,
+    );
+    const nextProjects = projects.map((project) =>
+      plan.projects.length > 0 && resolve(project.project) === plan.oldPath
+        ? { ...project, project: plan.newPath }
+        : project,
+    );
+
+    const updates: RegistryUpdate[] = [];
+    const podChanges = changedCount(pods, nextPods);
+    const listenerChanges = changedCount(listeners, nextListeners);
+    const projectChanges = changedCount(projects, nextProjects);
+    if (podChanges > 0) {
+      updates.push({
+        name: "pods.json",
+        file: podsFile(),
+        changed: podChanges,
+        body: `${JSON.stringify(nextPods, null, 2)}\n`,
+      });
+    }
+    if (listenerChanges > 0) {
+      updates.push({
+        name: "listeners.json",
+        file: listenersFile(),
+        changed: listenerChanges,
+        body: `${JSON.stringify(nextListeners, null, 2)}\n`,
+      });
+    }
+    if (projectChanges > 0) {
+      updates.push({
+        name: "projects.json",
+        file: projectsFile(),
+        changed: projectChanges,
+        body: `${JSON.stringify(nextProjects, null, 2)}\n`,
+      });
+    }
+
+    const changedPodIds = new Set(
+      plan.pods
+        .filter((pod) => {
+          const before = pods.find((candidate) => candidate.id === pod.id);
+          return before !== undefined && resolve(before.project) === plan.oldPath;
+        })
+        .map((pod) => pod.id),
+    );
+    const artifactMoves = plan.pods.filter(
+      (pod) => pod.artifact === "moved" && changedPodIds.has(pod.id),
+    );
+    if (updates.length === 0 && artifactMoves.length === 0) return { files: [] };
+
+    // Re-check the dry-run's filesystem facts before any write. A workspace
+    // that vanished between planning and apply must not become an empty Pod.
+    for (const pod of plan.pods) {
+      if (pod.artifact === "present" && changedPodIds.has(pod.id) && !(await exists(pod.to))) {
+        throw new Error(`pod ${pod.id}: artifacts missing at ${pod.to}; run project move again`);
+      }
+    }
+
+    const staged: StagedUpdate[] = [];
+    const moved: ProjectMovePod[] = [];
+    try {
+      for (const update of updates) staged.push(await stageUpdate(update));
+      for (const pod of artifactMoves) {
+        if (!(await exists(pod.from))) {
+          throw new Error(`pod ${pod.id}: artifacts missing at ${pod.from}`);
+        }
+        if (await exists(pod.to)) {
+          throw new Error(`pod ${pod.id}: artifacts already exist at ${pod.to}`);
+        }
+        await moveDirectory(pod.from, pod.to);
+        moved.push(pod);
+      }
+      for (const update of staged) {
+        await rename(update.tmp, update.file);
+        update.committed = true;
+      }
+    } catch (error) {
+      const rollbackErrors: unknown[] = [];
+      for (const update of [...staged].reverse()) {
+        if (!update.committed) continue;
+        try {
+          await restoreOriginal(update);
+        } catch (rollbackError) {
+          rollbackErrors.push(rollbackError);
+        }
+      }
+      for (const pod of [...moved].reverse()) {
+        try {
+          await moveDirectory(pod.to, pod.from);
+        } catch (rollbackError) {
+          rollbackErrors.push(rollbackError);
+        }
+      }
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError(
+          [error, ...rollbackErrors],
+          "project move failed and rollback was incomplete",
+        );
+      }
+      throw error;
+    } finally {
+      for (const update of staged) {
+        if (!update.committed) await rm(update.tmp, { force: true }).catch(() => undefined);
+      }
+    }
+
+    return {
+      files: updates.map((update) => ({ name: update.name, changed: update.changed })),
+    };
+  });
+
+  if (applied === undefined) throw new Error("registry lock unavailable: project move not applied");
+  return applied;
+}