agents-pod 0.3.6 → 0.3.7

package/src/doctor.ts

@@ -397,6 +397,19 @@ async function intakeLines(
     }
     lines.push({ mark: "ok", text: `source ${source.name}: ${source.cmd}` });
     lines.push({ mark: "ok", text: `  ${drained}, ${cursor}` });
+    // Routing leaves items behind on purpose (ADR 0034), so the count is a
+    // question and not a failure: a group nobody listens to is legitimate, a
+    // group nobody wanted is what the operator has to see.
+    if ((source.lastDrainUnrouted ?? 0) > 0) {
+      lines.push({
+        mark: "note",
+        text: `source ${source.name}: ${source.lastDrainUnrouted} item(s) of the last drain matched no listener — unrouted`,
+        detail: [
+          `      the cursor passed them; a route added now applies to what arrives next`,
+          `next: agents-pod listener add --source ${source.name} --chat <chat_id> --template <file> [--project <dir>]`,
+        ],
+      });
+    }
   }
   if (sources.length === 0) {
     lines.push({

package/src/extension/management.ts

@@ -49,6 +49,7 @@ const POD_HELP = [
   "/pod spawn <goal…>       spawn a pod in this project",
   "/pod wake <podId>        wake an idle pod now",
   "/pod cancel <podId>      cancel a live wake-up",
+  "/pod rm <podId>          discard a pod that no wake-up owns, with its workspace",
   "/pod agents              named agents",
   "/pod listeners           listeners and their claims",
 ].join("\n");
@@ -67,7 +68,7 @@ export function registerManagementCommands(pi: ExtensionAPI): void {
         ctx.ui.notify(POD_HELP, "info");
         return;
       }
-      const needsPodId = ["status", "logs", "wake", "cancel", "spawn"].includes(action);
+      const needsPodId = ["status", "logs", "wake", "cancel", "rm", "spawn"].includes(action);
       if (needsPodId && rest.length === 0) {
         ctx.ui.notify(POD_HELP, "info");
         return;
@@ -109,7 +110,7 @@ export function registerManagementTools(pi: ExtensionAPI): void {
     promptSnippet: "Spawn a standing pod for work that outlives this session",
     promptGuidelines: [
       "Read two axes before you call anything, because one ask can carry both signals, and a trigger alone does not decide — `time` without memory is a schedule (agents-cron / `schedule_task`), `message` or `role alive` is a pod (`spawn_pod`), and only the work axis separates the hybrid. trigger: `time` — 每天, 每小时, 每 30 分钟, 到点, 明天提醒我, 09:00; `message` — 收消息, 服务某个 inbox, 有活就干; `role alive` — 常驻, 监听, 路由, 直到我说停, or one job that spans days. work: `stateless` — one firing produces one answer and keeps nothing; `memory` — it needs what an earlier firing learned (跨天对比, 累计, 记得上次, 一份持续更新的报告).",
-      "Three shapes fall out of those two axes, and there is no fourth. (1) time + stateless → `schedule_task` alone: agents-cron owns the clock and the work, and a pod here is the incident. (2) time + memory → `schedule_task` owns the clock and hands the work over, `spawn_pod` owns it: bind the pod to the inbox the task appends to (`agents-pod listener add --inbox <file> --pod <podId>`) and give it `admission: intake`, or — when no batch has to be queued — let the task call `agents-pod wake <podId>` with `admission: external`. Its spawn wake-up runs once immediately; every firing after that belongs to the handover. Never a pod alone, and never `self`. (3) message / role alive → one pod via `spawn_pod`, `intake` when a listener or an inbox feeds it and `self` only when the goal reaches done, with no clock anywhere in its goal — call it as your FIRST tool call, without surveying the repo or the plugin first.",
+      "Three shapes fall out of those two axes, and there is no fourth. (1) time + stateless → `schedule_task` alone: agents-cron owns the clock and the work, and a pod here is the incident. (2) time + memory → `schedule_task` owns the clock and hands the work over, `spawn_pod` owns it: bind the pod to the inbox the task appends to (`agents-pod listener add --inbox <file> --pod <podId>`) and give it `admission: intake`, or — when no batch has to be queued — let the task call `agents-pod wake <podId>` with `admission: external`. Spawn it with `dormant: true`: the record exists and nothing runs, so the clock owns every firing including the first, and the handover's first batch or `wake` is wake-up 1. Never a pod alone, never `self`, and never a spawn wake-up the clock did not order. (3) message / role alive → one pod via `spawn_pod`, `intake` when a listener or an inbox feeds it and `self` only when the goal reaches done, with no clock anywhere in its goal — call it as your FIRST tool call, without surveying the repo or the plugin first.",
       "Say the rewrite in one line before the first tool call, naming every unit the ask actually has — and, whenever a pod is involved, its admission owner: 「这句我拆成：09:00 由 schedule_task 写 ci-daily.jsonl → pod X 被 intake 唤醒；pod X 负责汇总与跨天对比」. A schedule-only ask names no pod. If your line comes out as a pod plus a hand-written `crontab wake`, as a clock inside the pod's goal, or as a pod on `self`, that is the illegal combination (#31): say so and fix the shape instead of proceeding.",
       "Never put a clock in a pod's goal: the phrases the guard recognises — 09:00, 每天, 每 30 分钟, 9 点, every 30 minutes, daily, 到点 — are refused at spawn when the pod's owner is the tick, and a pod re-armed on every pass is the storm. The clock belongs to the schedule; a pod is woken by its admission owner — a listener's batch, an outside wake, or the tick — never by a time rule written inside the goal.",
       "Say who admits the pod's wake-ups (`admission`), because the tick is only one of three owners and it is the wrong one for a standing pod: `intake` when a listener or inbox feeds it (the router/watcher/inbox-server shape), `external` when an outside clock or a human wakes it with `agents-pod wake`, `self` only for a bounded goal the tick may re-wake until done. Left unstated it defaults to `self`, which wakes a standing pod every tick — the incident #31 exists to prevent.",
@@ -137,6 +138,12 @@ export function registerManagementTools(pi: ExtensionAPI): void {
             "Who admits this pod's wake-ups (ADR 0030): `intake` — a listener feeds it (the standing/inbox shape); `external` — an outside clock or a human calls `agents-pod wake`; `self` — the tick, legal only for a bounded goal that reaches done. Default is `self`; a standing pod left there is woken on every tick.",
         }),
       ),
+      dormant: Type.Optional(
+        Type.Boolean({
+          description:
+            "Write the pod and launch nothing, so its first wake-up belongs to its owner (ADR 0033 amendment, #43). Required for the hybrid shape: a schedule owns every firing including the first one. Needs `admission: intake` or `external` — with `self` the tick would wake it on its next pass, so the flag is refused there.",
+        }),
+      ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
       const argv = ["spawn", params.goal, "--project", ctx.cwd];
@@ -145,6 +152,7 @@ export function registerManagementTools(pi: ExtensionAPI): void {
       if (params.after !== undefined) argv.push("--after", params.after);
       if (params.cwd !== undefined) argv.push("--cwd", params.cwd);
       if (params.admission !== undefined) argv.push("--admission", params.admission);
+      if (params.dormant === true) argv.push("--dormant");
 
       const outcome = await runCli(argv, ctx.cwd);
       const podId = outcome.lines.join("\n").trim();
@@ -157,10 +165,13 @@ export function registerManagementTools(pi: ExtensionAPI): void {
         content: [
           {
             type: "text" as const,
-            text: `Spawned pod ${podId}. Wake-ups run detached; /pod status ${podId} shows progress.`,
+            text:
+              params.dormant === true
+                ? `Spawned pod ${podId} dormant: the record exists and no wake-up has run, so its first window belongs to its owner. The first handover starts it — an inbox item for \`intake\`, or \`agents-pod wake ${podId}\` for \`external\`. /pod status ${podId} shows it as "dormant: no wake-up yet".`
+                : `Spawned pod ${podId}. Wake-ups run detached; /pod status ${podId} shows progress.`,
           },
         ],
-        details: { podId },
+        details: { podId, ...(params.dormant === true ? { dormant: true } : {}) },
       };
     },
   });

package/src/listeners.ts

@@ -17,13 +17,19 @@ export type ListenerMode = "template" | "pod";
  * `blocked` is a reason materialization will not happen
  * (a configuration error, or an item that vanished). `appended` is ADR 0014's
  * one boolean for a bound standing pod: the block is in the pod's `## Inbox`.
- * Beyond that the document is the truth — there is no per-item lifecycle.
+ * The item copy lets a Source claim outlive the drain that produced it (ADR
+ * 0034). Beyond that the document is the truth — there is no per-item lifecycle.
  */
 export interface ClaimRecord {
   inbox: string;
   item: string;
-  /** Source claims retain the current and previous successful drain (ADR 0024). */
+  /** The successful drain that made the claim; re-emission, not age, is its horizon (ADR 0034). */
   claimedAt?: number;
+  title?: string;
+  body?: string;
+  chatId?: string;
+  rootId?: string;
+  threadId?: string;
   spawnedPodId?: string;
   blocked?: string;
   appended?: boolean;
@@ -43,6 +49,12 @@ export interface ListenerRecord {
   source?: string;
   /** P0's rule: a plain substring; absent means every item matches. */
   match?: string;
+  /**
+   * Routing filter (ADR 0034): the groups this Listener claims, by the item's
+   * `chat_id`. Absent means every group. A filter is ANDed with `match`, and the
+   * first Listener in registry order that holds claims the item.
+   */
+  chats?: string[];
   mode: ListenerMode;
   /** Template mode: the goal template file. */
   template?: string;

package/src/sources.ts

@@ -3,7 +3,7 @@ import { randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import type { BadInboxLine, InboxItem } from "./inbox.ts";
-import type { ListenerRecord } from "./listeners.ts";
+import type { ClaimRecord, ListenerRecord } from "./listeners.ts";
 import { sourcesFile } from "./paths.ts";
 
 /** A Source outlives its Listeners; its opaque cursor lives beside them (ADR 0024). */
@@ -12,13 +12,19 @@ export interface SourceRecord {
   cmd: string;
   timeoutMs: number;
   cursor?: string;
-  /** The previous successful drain is the claim-retention horizon (ADR 0024). */
+  /** The last successful drain's timestamp; the cursor, not its age, bounds claims (ADR 0034). */
   lastDrainAt?: number;
   /**
    * That drain's yield (ADR 0027): zero is a fact, not a gap — a pull that runs
    * and delivers nothing is the shape of a conversation that never reaches it.
    */
   lastDrainItems?: number;
+  /**
+   * How many of that drain's items no Listener claimed (ADR 0034). A group nobody
+   * listens to is legitimate; a group being drained into nothing is the number an
+   * operator needs, and `doctor` prints it as a question rather than a failure.
+   */
+  lastDrainUnrouted?: number;
   /** A failed drain's fact (ADR 0027): a report cannot say `ok` while every pass fails. */
   lastFailureAt?: number;
   lastError?: string;
@@ -29,9 +35,10 @@ export interface SourceDrain {
   items: InboxItem[];
   bad: BadInboxLine[];
   cursor?: string;
-  /** Successful drains carry their generation and the preceding one's boundary. */
+  /** A successful drain's timestamp, retained for its Source and claim records. */
   drainedAt?: number;
-  previousDrainAt?: number;
+  /** Items this drain delivered that no Listener claimed (ADR 0034). */
+  unrouted?: number;
   /** A failed drain contributes nothing and leaves the cursor untouched. */
   error?: string;
 }
@@ -202,13 +209,12 @@ async function drainOne(source: SourceRecord, project: string): Promise<SourceDr
     });
   });
   if (result.error !== undefined) return { ...empty, error: result.error };
-  // Distinct generations need distinct boundaries even when two local drains
-  // finish within one wall-clock millisecond.
+  // Distinct drains need distinct timestamps even when two local drains finish
+  // within one wall-clock millisecond.
   const drainedAt = Math.max(Date.now(), (source.lastDrainAt ?? 0) + 1);
   return {
     ...parseDrainOutput(source.name, result.stdout ?? ""),
     drainedAt,
-    ...(source.lastDrainAt === undefined ? {} : { previousDrainAt: source.lastDrainAt }),
   };
 }
 
@@ -232,30 +238,39 @@ export async function drainSources(
 }
 
 /**
- * Two generations are enough: after this drain, anything older than the prior
- * successful one is behind the committed cursor and cannot arrive again. The
- * store is transformed without I/O; the caller writes it inside the registry
- * lock before advancing the Source records (ADR 0024). Legacy claims without a
- * timestamp are retained because their generation cannot be proven.
+ * A successful drain is the claim's horizon (ADRs 0024, 0034): an id it did not
+ * re-emit is behind the cursor, while an id it keeps re-emitting stays claimed
+ * for any number of passes. Failed drains and other inbox kinds have no say.
+ * Legacy claims without `claimedAt` stay because their provenance is unproven.
+ *
+ * Claims that began this pass unserved are sheltered until the next one. Their
+ * own item copy must get a chance to materialize, and a legacy miss must remain
+ * `blocked` long enough to be observed; pruning either here would recreate the
+ * silent loss this rule is meant to end. The caller writes the transformed store
+ * inside the registry lock before advancing the Source records.
  */
 export function pruneSourceClaims(
   listeners: ListenerRecord[],
   drained: SourceDrain[],
+  deferredClaims: ReadonlySet<ClaimRecord> = new Set(),
 ): { listeners: ListenerRecord[]; changed: boolean } {
-  const horizons = new Map<string, number>();
+  const reemitted = new Map<string, Set<string>>();
   for (const drain of drained) {
-    if (drain.error === undefined && drain.previousDrainAt !== undefined) {
-      horizons.set(`source:${drain.name}`, drain.previousDrainAt);
+    if (drain.error === undefined) {
+      reemitted.set(`source:${drain.name}`, new Set(drain.items.map((item) => item.id)));
     }
   }
-  if (horizons.size === 0) return { listeners, changed: false };
+  if (reemitted.size === 0) return { listeners, changed: false };
 
   let changed = false;
   const pruned = listeners.map((listener) => {
     const claimed = listener.claimed.filter((claim) => {
-      const horizon = horizons.get(claim.inbox);
+      const emitted = reemitted.get(claim.inbox);
       return (
-        horizon === undefined || claim.claimedAt === undefined || claim.claimedAt >= horizon
+        emitted === undefined ||
+        claim.claimedAt === undefined ||
+        deferredClaims.has(claim) ||
+        emitted.has(claim.item)
       );
     });
     if (claimed.length === listener.claimed.length) return listener;
@@ -265,7 +280,7 @@ export function pruneSourceClaims(
   return { listeners: pruned, changed };
 }
 
-/** Claims and pruning land before this cursor/retention-horizon write (ADR 0024). */
+/** Claims and pruning land before this cursor write (ADRs 0024, 0034). */
 export async function commitSourceCursors(drained: SourceDrain[]): Promise<void> {
   const sources = await readSources();
   let changed = false;
@@ -287,6 +302,12 @@ export async function commitSourceCursors(drained: SourceDrain[]): Promise<void>
       source.lastDrainItems = drain.items.length;
       changed = true;
     }
+    // What the filters left behind is a fact of this drain (ADR 0034), recorded
+    // whether it is zero or not for the same reason the yield is.
+    if (drain.unrouted !== undefined && source.lastDrainUnrouted !== drain.unrouted) {
+      source.lastDrainUnrouted = drain.unrouted;
+      changed = true;
+    }
     // A success clears the failure it disproved (ADR 0027).
     if (source.lastError !== undefined) {
       delete source.lastError;