agents-pod 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to agents-pod. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.7] — 2026-11-05
+
+One Feishu app, many groups, one group per project: intake could not say which
+group an item belonged to, so one channel could only serve one project. While
+designing the filter, two intake bugs surfaced that any partition would have
+spread: a capacity-deferred claim lost its item when the cursor moved (#47), and
+a claim was pruned while the overlap was still re-emitting it, so the same
+message came back as a second pod (#46). ADR 0034 answers all three: a Source
+claim owns its item, re-emission (not a generation count) prunes it, and a
+Listener filters on the group. Alongside it, the list stops carrying what can no
+longer act: terminal pods are hidden, and `rm` discards the ones nothing owns.
+
+### Added
+
+- `listener add|edit --chat <chat_id>` — a routing filter over the item's
+  `chat_id`, ANDed with `--match`; one Source feeds N Listeners, so one channel
+  routes each group to its own project (#45, ADR 0034). A directory inbox is
+  refused with exit `2`: its items carry no group.
+- `listener edit <id>` changing `--match`, `--chat`, `--project` and
+  `--max-concurrent` in place, claims included; `rm` + `add` stays a fresh claim
+  namespace and replays the overlap window.
+- `source rewind <name> --to <cursor|"">` — re-read past the cursor after an
+  unrouted batch or a route fixed too late; claims dedupe what returns.
+- `lastDrainUnrouted` recorded per Source, printed by `source list` and `doctor`,
+  and one `cron.log` line per pass with a non-zero count — a group nobody
+  listens to is legitimate, a group nothing wants is not silent.
+- `list` hides `done` and `cancelled` pods by default (`--all` brings them back,
+  the footer counts them), and `rm <podId>` discards a pod no wake-up owns — its
+  record and its workspace (ADR 0035). `rm` refuses a live pod, a bound Listener,
+  a dependent's `after`, and an undelivered Outbox entry.
+
+### Fixed
+
+- A capacity-deferred Source claim carries its item, so it materializes when
+  capacity frees instead of vanishing with the drain that produced it (#47).
+- A claim is pruned by re-emission, not by a two-generation count, so a quiet
+  chat's re-delivered last message no longer returns as a second pod (#46).
+- `parseFlags` keeps every value of a repeatable flag; before, `--chat a --chat b`
+  silently dropped `a`.
+
 ## [0.3.6] — 2026-11-05
 
 One pod woke 41 times in five hours, and the store could not say why. Every

package/README.md

@@ -146,26 +146,31 @@ agents-pod spawn <goal prompt> [--project <dir>] [--agent <id>] [--model <id>] [
                               [--after <podId>]                 # wait for the upstream pod to reach done
                               [--admission intake|external|self | --external]   # who may wake it (ADR 0030)
                               [--wake-budget <n>]               # daily ceiling, default 24 (ADR 0032)
+                              [--dormant]                       # write the record and launch nothing (ADR 0033)
 agents-pod project cap [n|unlimited] [--project <dir>]          # per-project live wake-up cap
 agents-pod project move <old> <new> [--apply] [--move-artifacts]  # the tree was renamed: relocate records (ADR 0028)
-agents-pod list [--json]
+agents-pod list [--all] [--json]                             # live pods; --all includes terminal ones
 agents-pod status <podId>
 agents-pod logs <podId> [--follow]
 agents-pod wake <podId> [--agent <id>] [--warm] [--over-budget]
                                                     # fresh by default; --warm resumes a lost wake-up's session
-agents-pod cancel <podId>
+agents-pod cancel <podId>                           # signals a live wake-up
+agents-pod rm <podId>                               # discard a pod no wake-up owns, with its workspace (ADR 0035)
 agents-pod reconcile                                # the cron entry point; idempotent
 agents-pod agent add <id> --type <pi|claude|codex> [--model <id>] [--instructions <file>]
 agents-pod agent edit <id>                          # $EDITOR on the stored definition
 agents-pod agent rm <id>                            # pods left referencing it park at reconcile (ADR 0012)
 agents-pod agent list [--json]                      # named agents: type, model, role
 agents-pod listener add (--inbox <dir|file> | --source <name>) (--pod <podId> | --template <file>)
-                         [--match <substr>] [--max-concurrent <n>] [--project <dir>]
+                         [--match <substr>] [--chat <chat_id> ...] [--max-concurrent <n>] [--project <dir>]
+agents-pod listener edit <listenerId> [--match <substr>] [--chat <chat_id> ... | --no-chat]
+                         [--max-concurrent <n>] [--project <dir>]
 agents-pod listener list [--json]
 agents-pod listener rm <listenerId>
 agents-pod source add <name> --cmd <path> [--timeout <s>]
 agents-pod source list [--json]
 agents-pod source rm <name>
+agents-pod source rewind <name> --to <cursor|"">   # re-read past the cursor (ADR 0034)
 agents-pod deliver add <name> --cmd <path> [--timeout <s>]
 agents-pod deliver list [--json]
 agents-pod deliver rm <name>
@@ -181,6 +186,25 @@ at a time is a schedule's job, and a pod carrying a clock is the incident
 upstream pod's `done`; a cancelled upstream never releases it. When the
 project's cap is full, the new pod likewise waits idle with its document store
 ready. Manual `wake` overrides park/backoff, never dependencies or capacity.
+With `--dormant` the record, the workspace and the owner are written and
+**nothing is launched**: the first wake-up belongs to the owner, which is what a
+hybrid pod needs so the schedule owns every firing, including the first one
+([ADR 0033 amendment](docs/adr/0033-a-hybrid-ask-decomposes-on-two-axes.md)).
+`--dormant` is refused with `admission: self` — the tick admits an idle pod on
+its next pass, so the stop would last a minute and the flag would lie. A manual
+`wake` starts a dormant pod of any owner: the human is the override, not a
+fourth admission owner, and the wake-up records `trigger: wake` rather than
+claiming a batch arrived.
+
+`list` shows the pods that are still live work: `done` and `cancelled` records
+are hidden unless `--all` is passed, and the footer says how many are hidden.
+`rm` is the record's end, not a stop ([ADR
+0035](docs/adr/0035-removal-is-garbage-collection.md)): it refuses `active` and
+`spawning` pods (`cancel` first), and deletes the record plus
+`<project>/.agents/pods/<podId>/` — documents, log and wake-up sessions
+included. It refuses while a Listener is bound to the pod, while another pod's
+`after` names it, or while its Outbox still holds an undelivered entry; clear
+those first, because each would be left dangling.
 Exit codes follow the house rule: `0` success
 or nothing to do, `1` at least one pod failed (or `doctor` found something
 that blocks a channel), `2` configuration or storage error.
@@ -190,7 +214,7 @@ first, record before exiting.
 
 The Pi extension has two planes, gated by the env the wrapper injects
 ([ADR 0010](docs/adr/0010-two-extension-planes.md)). The **management
-plane** (`/pod list|status|logs|spawn|wake|cancel|agents|listeners` and the
+plane** (`/pod list|status|logs|spawn|wake|cancel|rm|agents|listeners` and the
 `spawn_pod` tool) registers only in an interactive session: inside a pod
 those tools and commands are not registered at all, so fan-out is
 structurally impossible rather than forbidden. The **self plane** registers
@@ -209,10 +233,16 @@ tool is a guarantee on top of that contract, never a replacement for it.
 | --- | --- | --- |
 | `spawning` | record created, first wake-up not yet confirmed | `spawn` |
 | `active` | a wake-up is live: wrapper alive, heartbeat fresh | wake / reconcile |
-| `idle` | goal open, nothing live; documents current — `idle (awaiting)` when the last window declared itself satisfied | wrapper / reconcile |
+| `idle` | goal open, nothing live; documents current — `idle (awaiting)` when the last window declared itself satisfied, `idle (dormant: no wake-up yet)` when none has run | wrapper / reconcile |
 | `done` | goal reached; terminal | wrapper |
 | `cancelled` | user cancel completed; terminal | wrapper |
 
+A terminal pod is not deleted by reaching its state: it stays visible to
+`status`, `list --all` and its documents until `rm` discards it, and it is never
+re-woken (ADR 0035). `rm` accepts `done`, `cancelled` and `idle` — a pod that no
+wake-up owns — and refuses `active`/`spawning`, a bound Listener, a dependent's
+`after`, and an undelivered Outbox entry.
+
 A pod never exits — its wake-ups do. Wake-up outcomes — declared in the
 handoff's first line, in this order of preference: `more` (`status: rotating`,
 the goal needs another wake-up now), `quiet` (`status: quiet`, this window is
@@ -283,6 +313,16 @@ placeholders: `{{id}}` `{{title}}` `{{body}}` `{{path}}` and `{{reply_to}}`.
 The last placeholder carries the Delivery Address consumed by the outbound
 contract below (ADRs 0013, 0026).
 
+One Source may feed several Listeners, so one channel can serve many
+groups: `--chat <chat_id>` (repeatable) is a routing filter over the item's
+`chat_id`, ANDed with `--match`, and the first Listener in `listeners.json`
+order that holds claims the item (ADR 0034). A Source drained once, its items
+split by their group to as many projects as there are Listeners. What no
+Listener claims is counted, not silently dropped: `source list`/`doctor`
+report `lastDrainUnrouted` and the pass writes one `cron.log` line. A
+`--chat` filter needs an item that carries a group, so `listener add --chat`
+against a directory inbox exits `2`; JSONL and Source items are filterable.
+
 For a standing pod, claimed items land in its `TASKS.md` `## Inbox`
 section — below the agent-owned `## Waiting`, and appended only while no
 wake-up is live, then one batch, one wake on the ordinary wake path; the
@@ -319,6 +359,13 @@ and hands the work over. The canonical example is replayed in
 [`tests/fixtures/first-turn/`](tests/fixtures/first-turn/), where the incident's
 own ask is the fixture.
 
+The handover's first firing needs one more promise: `spawn --dormant` (or
+`spawn_pod`'s `dormant: true`). A hybrid pod is written without its spawn
+wake-up, so the schedule owns every firing and the first Inbox Item — or the
+first `agents-pod wake` — is wake-up 1. `status` shows such a pod as
+`idle (dormant: no wake-up yet)`, derived from an empty wake-up list rather than
+stored: nothing has run, so nothing has to be cleared when it does.
+
 ### Reading a rate
 
 Every wake-up records `at` and `trigger` (`spawn` / `tick` / `wake`, ADR 0032), so
@@ -403,6 +450,9 @@ name, removing an in-use Source, or adding a second deliverer returns `2`.
 `--pod <podId>`. With `--template`, `--project <dir>` selects the new Pods'
 project and defaults to the reconcile invocation's cwd; with `--pod` it is a
 configuration error (exit `2`), because the bound Pod keeps its own project.
+`--chat` may repeat and replaces the whole filter; `listener edit` changes a
+rule in place, claims included — `rm` + `add` is a fresh claim namespace and
+the replay window hands the old ids back (ADR 0034).
 
 ### Writing a Source drain
 

package/examples/feishu/README.md

@@ -31,6 +31,29 @@ behaviour alone cannot report it. A file you edited yourself is reported as a
 local edit and kept; `--force` is the only way to replace it. Plain `cp` still
 works; it just leaves nothing for `doctor` to compare against.
 
+## One app, one drain, many groups
+
+A tenant usually runs several groups, one per project. That needs **one**
+drain and one Listener per group — the drain already walks every chat the bot
+sits in, and every item carries its `chat_id` (ADR 0034):
+
+```bash
+agents-pod source add feishu --cmd ~/.agents/pods/adapters/feishu_drain.py --timeout 60
+agents-pod listener add --source feishu --chat oc_aaaa --template ~/work/app-a/TASK.md --project ~/work/app-a
+agents-pod listener add --source feishu --chat oc_bbbb --template ~/work/app-b/TASK.md --project ~/work/app-b
+```
+
+One cursor, one poll per pass, one Pod per group's message; a reply goes back to
+the group it came from because the Delivery Address travels with the item. A
+group no Listener names is **counted as `unrouted`** and printed by `doctor` —
+the bot is reading it and nothing wants it, which is worth being told. Add
+`--chat` to an existing Listener with `listener edit`, never `rm` + `add`: the
+claims live in the record, and re-adding replays the overlap window as new work.
+
+`FEISHU_CHATS` is a different axis: the adapter-level allowlist limits what the
+**drain** reads at all (and gives each group its own cursor if you run one copy
+per group). Use it for hard isolation, `--chat` for routing.
+
 ## The one thing this cannot do for you: the app
 
 Feishu's console is a human surface. In order:
@@ -160,3 +183,45 @@ message is still subject to `FEISHU_REQUIRE_MENTION`.
 The pair shares a client file and nothing else. A different platform is a
 second pair of commands and needs nothing from core; a second Feishu app needs
 nothing from this directory but another `.env`.
+
+## Limits the code meets, and the road not taken (push)
+
+Facts from Feishu's own docs, recorded because they bound the *next* change
+rather than this one. Every claim names the page it came from; none of them is
+in the code yet.
+
+**Frequency.** Error `230020` is the rate limit: **5 QPS to one group**, shared
+by every bot in it, and 5 QPS to one user. A chat walk is one call per chat, so
+the per-group cap — not the per-tenant one — is what a wide `FEISHU_CHATS`
+meets first. ([message list](https://open.feishu.cn/document/server-docs/im-v1/message/list))
+
+**Reply payloads** (what `feishu_deliver.py` may send): `content` is a
+*serialized JSON string* whose shape follows `msg_type`; text is capped at
+150 KB, cards and rich text at 30 KB; `uuid` is ≤50 characters with one hour of
+idempotency. `reply_in_thread` refuses with `230071` (the group does not support
+topic replies) and `230072` (aggregated messages). ([reply message](https://open.feishu.cn/document/server-docs/im-v1/message/reply))
+
+**Message-list parameters** the drain does not pass yet: `sort_type`
+(`ByCreateTimeAsc` default, fixed once paging starts), `page_size` 1–50
+(default 20), `card_msg_content_type`, `only_thread_root_messages`,
+`with_sender_name`. ([message list](https://open.feishu.cn/document/server-docs/im-v1/message/list))
+
+**Push, if anyone ever wants it** (ADR 0024 leaves the door open; core stays
+pull-only). The two transports share the at-least-once contract and the retry
+schedule — 15 s, 5 min, 1 h, 6 h, at most four retries, ≈7 h — and differ in
+everything else:
+
+- *Webhook* needs a **public IPv4** URL, must echo `url_verification` within
+  **1 s** before the URL can even be saved, and must return HTTP 200 within
+  **3 s** (TCP connect 2 s + callback 3 s). A laptop that sleeps or changes
+  network fails that ack, and the retry window is the only recovery.
+- *Long connection* (outbound WebSocket) needs no public address — only
+  outbound internet — and is **enterprise self-built apps only**. Success is the
+  handler returning within **3 s** without throwing. The hard limits: **at most
+  50 connections per app**, each initialized client being one connection, and
+  delivery is **cluster mode with no broadcast** — with several clients of one
+  app, only one randomly chosen client receives each message. A shim is
+  therefore one connection, never a pool.
+
+That last fact is why "push" here can only be a single resident process with a
+file inbox behind it: any fan-out is the platform's, not ours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "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",