agents-pod 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,81 @@ 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).
 
+## [Unreleased]
+
+## [0.3.4] — 2026-11-04
+
+Two failures shared one shape: the store knew a fact and could not say it. A
+renamed repository left every record pointing at a path that no longer existed
+while `doctor` printed `✓` for the row that mattered, and an adapter copy a
+release behind answered `--check` perfectly because a self-check measures
+behaviour, never provenance. Both are now facts with a command behind them.
+
+### Added
+
+- **`agents-pod project move <old> <new>` relocates records after a rename**
+  (issue #25, ADR 0028). A Pod's identity is its id; `project` is a location,
+  and the workspace lives inside the tree (`<project>/.agents/pods/<id>`), so a
+  `mv` already carried the Document Store along. Dry run by default; `--apply`
+  rewrites `pods.json`, template Listeners' `project` and the `projects.json`
+  capacity key inside the registry lock, computing every body before writing
+  any, with rollback. Three refusals: the target already holds records, a
+  Pod's workspace is missing there (pass `--move-artifacts`), or the old path
+  still exists. Measured on the store that lost three hours: the dry run named
+  two Pods and one Listener, `--apply` wrote 3 records, and the second run said
+  `nothing to do`.
+- **`agents-pod adapter sync <name>` copies an adapter from the installed
+  package and records its provenance** (issue #26, ADR 0029). Dry run by
+  default; `--force` is the only way to replace a local edit, and `.env`,
+  `.token.json`, `.bot.json` and `state.json` are never candidates. The new
+  `adapters.json` records `{name, dir, packageVersion, files: sha256}`.
+
+### Fixed
+
+- **A chat `system` event is no longer an Inbox Item** (issue #27). An invite,
+  rename or pin reached the Inbox as the placeholder `[system]` — `is_bot()`
+  filtered `sender_type == "app"` and a system event's sender is empty — so a
+  router Pod spent a whole wake-up judging one. Events now go to stderr, one
+  line each; the cursor still crosses them, so a pass that saw only a rename
+  prints `{"cursor":…}` and no item. The intake rule moved into pure
+  `is_item`/`item_from`/`absorb` functions, tested offline by
+  `examples/feishu/test_feishu_drain.py` (7 cases) and from `npm test`.
+- **`doctor` checks every path a record holds** (issues #24, #25). A pod-mode
+  Listener whose bound Pod's project is gone was `✓` while every wake-up was
+  doomed; the `next:` advice was `listener rm`, which would have thrown away a
+  surviving Document Store. Both the bound Pod (`listeners` section) and an
+  unbound non-terminal Pod (`store` section) now report the dead path and name
+  `agents-pod project move <old> <new>`. Terminal Pods are exempt: they block
+  no conversation.
+
+### Notes
+
+- `doctor` gains an `adapters` section only when `adapters.json` has entries, so
+  an existing store's report is byte-identical until a copy is registered.
+- `CONTEXT.md`: the `Goal` entry said the Goal carries "its working directory";
+  the Pod Record carries it. New term: **Relocate**, with *resume* and *fork*
+  named as the different operations they are.
+
+### Fixed (0.3.3, carried — the release was tagged but never published)
+
+- **The Feishu client caches per app, so swapping the app is not a silent
+  two-hour lie.** `.token.json` and `.bot.json` were keyed by time only: after
+  changing `FEISHU_APP_*` in `.env`, the old app's `tenant_access_token` (2 h)
+  and the old bot's `open_id` would keep answering, so the new app looked like
+  it had missing scopes and `FEISHU_REQUIRE_MENTION` never matched. Both caches
+  now record their `app_id` and a mismatch is a miss.
+
+### Documentation (0.3.3)
+
+- **`examples/feishu/README.md` now maps every scope to the endpoint it admits**
+  (`im:chat:readonly` → `/im/v1/chats`, `im:message:readonly` + the required
+  addition `im:message.group_msg` → `/im/v1/messages`, `im:message:send_as_bot`
+  → send and reply), with the console names, the "any one of these" variants,
+  the three-scope alternative (`im:message` replaces two), and what is not a
+  scope but still required: 机器人能力, a published version, the bot in the
+  group. A new **Swapping the app** section lists the three artifacts that
+  survive a credential change.
+
 ## [0.3.2] — 2026-11-04
 
 0.3.1 taught `spawn_pod` to name standing work and got one word wrong: 每天. Two

package/README.md

@@ -141,6 +141,7 @@ agents-pod doctor [--probe] [--json]                     # what is missing, and
 agents-pod spawn <goal prompt> [--project <dir>] [--agent <id>] [--model <id>] [--cwd <dir>]
                               [--after <podId>]                 # wait for the upstream pod to reach done
 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 status <podId>
 agents-pod logs <podId> [--follow]
@@ -161,6 +162,7 @@ agents-pod source rm <name>
 agents-pod deliver add <name> --cmd <path> [--timeout <s>]
 agents-pod deliver list [--json]
 agents-pod deliver rm <name>
+agents-pod adapter sync <name> [--dest <dir>] [--apply] [--force]  # copy the package's adapter, record its provenance (ADR 0029)
 ```
 
 `spawn` claims a pod id, writes the pod record, wakes the first agent, and

package/examples/feishu/README.md

@@ -17,13 +17,20 @@ meant to be *yours*, not core's. `chmod +x feishu_drain.py feishu_deliver.py`.
 `state.json` and `.token.json` appear on first use; both are rebuilt if lost.
 
 ```bash
-cp examples/feishu/*.py ~/.agents/pods/adapters/          # or wherever
-cp examples/feishu/.env.example ~/.agents/pods/adapters/.env && chmod 600 …
+agents-pod adapter sync feishu --apply                     # into <store>/adapters/
+cp ~/.agents/pods/adapters/.env.example ~/.agents/pods/adapters/.env && chmod 600 …
 agents-pod source add feishu --cmd ~/.agents/pods/adapters/feishu_drain.py --timeout 60
 agents-pod deliver add feishu-reply --cmd ~/.agents/pods/adapters/feishu_deliver.py --timeout 20
 agents-pod doctor --probe      # the pair answers for itself; fix what it names
 ```
 
+`adapter sync` copies from the **installed package** and records the hashes it
+copied in `adapters.json`, which is what lets `doctor` tell you a copy fell a
+release behind (ADR 0029) — a stale copy answers `--check` perfectly, so
+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.
+
 ## The one thing this cannot do for you: the app
 
 Feishu's console is a human surface. In order:
@@ -31,19 +38,57 @@ Feishu's console is a human surface. In order:
 1. **Create a self-built app** (自建应用) and take `App ID` / `App Secret` from
    凭证与基础信息 into `.env`.
 2. **Grant four tenant permissions**, then **publish a version** (权限变更 only
-   takes effect with a new version; sensitive ones need an admin's approval):
-
-   | scope | why | measured failure without it |
-   |---|---|---|
-   | `im:message.group_msg` | read group history | `GET /im/v1/messages` → `code=230027 lack of necessary permissions` |
-   | `im:message:readonly` | read messages generally | same class of refusal |
-   | `im:message:send_as_bot` | post as the bot | send refused |
-   | `im:chat:readonly` | enumerate the chats the bot is in | chat list comes back empty |
-
+   takes effect with a new version; sensitive ones need an admin's approval).
+
+   Every endpoint this pair calls, and the scope that admits it — the console
+   names are the ones the permission picker shows, and the failure column is
+   what the tick actually reports:
+
+   | scope | console name | admits | measured failure without it |
+   |---|---|---|---|
+   | `im:chat:readonly` | 获取群组信息 | `GET /im/v1/chats` — the chats the bot is in | chat list comes back empty |
+   | `im:message:readonly` | 获取单聊、群组消息 | the base read grant for `GET /im/v1/messages` | `code=230027` on read |
+   | `im:message.group_msg` | 获取群组中所有消息 | group history — the base grant alone is **not** enough for a group | `code=230027` on read, with the base grant already on |
+   | `im:message:send_as_bot` | 以应用的身份发消息 | `POST /im/v1/messages` and `POST /im/v1/messages/:id/reply` | send refused |
+
+   Three of those four are "any one of a set" in the API docs, which matters
+   when ticking boxes in the console:
+
+   - read base: `im:message` · `im:message:readonly` · `im:message.history:readonly`
+   - group history: `im:message.group_msg` — **required in addition**, app identity only
+   - send: `im:message` · `im:message:send_as_bot` · `im:message:send`
+   - chat list: `im:chat` · `im:chat:readonly` · `im:chat:read` · `im:chat.group_info:readonly`
+
+   So the least-privilege set is those four; `im:message` replaces two of them
+   (read base + send) and the set becomes three, at the price of also being
+   allowed to send direct messages. `GET /bot/v3/info` (the bot's own id, for
+   @-mention detection) needs no scope — only 机器人能力.
+
+   Not scopes, but the same console and the same publish step: **机器人能力**
+   must be on (应用能力 → 机器人), the version must be published, and the bot
+   added to the group (`im:chat:readonly` cannot invent a membership).
 3. **Add the bot to a group chat** — 群设置 → 群机器人 → 添加机器人. Create that
    group yourself, in the Feishu app: see the trap table below.
 4. **Say one thing in the group**, then run the smoke test below.
 
+## Swapping the app
+
+A new app is a new identity. Three things on this machine still belong to the
+old one, and only the first is in `.env`:
+
+| what | why it matters | what to do |
+|---|---|---|
+| `.env` | the credentials | write the new `FEISHU_APP_ID` / `FEISHU_APP_SECRET`, then `chmod 600` |
+| `.token.json` | the old app's `tenant_access_token`, valid 2 h — keyed by time, so it would keep answering as the old app | delete it, or let this version notice: the cache now records its `app_id` and a mismatch is a miss |
+| `.bot.json` | the old app's bot `open_id`, used to spot an @-mention — a stale id makes `FEISHU_REQUIRE_MENTION=1` never match | same: cached per `app_id`, so a swap is a miss |
+
+`state.json`'s `known_chats` survives a swap (chat ids are tenant-level, not
+app-level), but a group the **new** bot was never added to will never yield an
+item — re-add it and say one thing there.
+
+After the swap: `agents-pod doctor --probe`; `token ok` + `N chat(s) visible` +
+`read ok in <group>` is the whole handshake.
+
 ## Smoke test
 
 ```bash
@@ -76,6 +121,31 @@ Facts observed while wiring this pair to a real tenant, in the order they bite:
 | **Chat anonymity hides history** | A group with 保密模式 or hidden history answers intake with `230050`/`231203` and no item ever arrives — a configuration fact, not a bug. |
 | **Tokens and dedup windows are hours long** | `tenant_access_token` lives 2 h (`.token.json` caches it), so a 1-minute pass is cheap; the reply `uuid` window is 1 h, which is exactly what core's dead-lettering assumes (ADR 0025). |
 
+## Events go to the log, messages go to the Inbox
+
+A chat `system` event — an invite, a rename, a pin, a member join, the bot
+being added — is something the conversation *did*, not something a human said.
+It has no author to answer, so the drain does not turn it into an item. It
+prints one line on stderr instead:
+
+```
+[feishu-drain] skip system event om_x100…443 in 徐福洋的小组
+```
+
+The rule is the same for any adapter that forwards platform events: **events →
+the operator's log, messages → the Inbox.** A system event never spends a
+pod wake-up.
+
+Skipped events are *consumed*, not deferred: the cursor crosses them exactly as
+it crosses a delivered message. So a pass whose only traffic was a rename
+prints no item and still prints `{"cursor":"…"}` — that is a quiet chat, not
+the "pointed at nothing" shape (zero items **and** no cursor) that `doctor`
+reports (ADR 0027).
+
+`msg_type: "system"` is excluded by content, not by identity: the existing
+`sender_type == "app"` filter still drops the bot's own messages, and a human
+message is still subject to `FEISHU_REQUIRE_MENTION`.
+
 ## Switchboard (`.env`, or the environment — the environment wins)
 
 - `FEISHU_CHATS` — comma-separated `chat_id` allowlist; empty = every chat.

package/examples/feishu/feishu_client.py

@@ -107,12 +107,26 @@ def _write_json(path, value, mode=0o600):
     os.replace(tmp, path)
 
 
+def _app_id():
+    return os.environ.get("FEISHU_APP_ID", "").strip()
+
+
 def tenant_token(force=False):
-    """`tenant_access_token` lives 2 h; caching keeps a 1-minute tick cheap."""
+    """`tenant_access_token` lives 2 h; caching keeps a 1-minute tick cheap.
+
+    The cache records the app it belongs to: swapping `FEISHU_APP_*` in `.env`
+    must not keep using the previous app's token until it expires, or the new
+    app's first failures read as missing scopes on the wrong identity.
+    """
+    app_id = _app_id()
     cached = _read_json(TOKEN_FILE)
-    if not force and cached.get("token") and cached.get("expires_at", 0) > time.time() + 60:
+    if (
+        not force
+        and cached.get("token")
+        and cached.get("app_id") == app_id
+        and cached.get("expires_at", 0) > time.time() + 60
+    ):
         return cached["token"]
-    app_id = os.environ.get("FEISHU_APP_ID", "").strip()
     app_secret = os.environ.get("FEISHU_APP_SECRET", "").strip()
     if not app_id or not app_secret:
         raise FeishuError("/auth/v3/tenant_access_token/internal", "no-credentials",
@@ -124,20 +138,26 @@ def tenant_token(force=False):
                           answer.get("code"), answer.get("msg"))
     token = answer["tenant_access_token"]
     expires_at = time.time() + int(answer.get("expire", 7200))
-    _write_json(TOKEN_FILE, {"token": token, "expires_at": expires_at})
+    _write_json(TOKEN_FILE, {"token": token, "expires_at": expires_at, "app_id": app_id})
     return token
 
 
 def bot_open_id(token):
-    """The bot's own `open_id`, used to spot an @-mention of us."""
+    """The bot's own `open_id`, used to spot an @-mention of us.
+
+    Cached per app: a swapped app is a different bot, and a stale id would make
+    an @-mention check answer for an identity that is no longer in the chat.
+    """
+    app_id = _app_id()
     cached = _read_json(BOT_FILE)
-    if cached.get("open_id"):
+    if cached.get("open_id") and cached.get("app_id") == app_id:
         return cached["open_id"]
     data = api("GET", "/bot/v3/info", token=token)
     bot = data.get("bot") or {}
     open_id = bot.get("open_id")
     if open_id:
-        _write_json(BOT_FILE, {"open_id": open_id, "app_name": bot.get("app_name")})
+        _write_json(BOT_FILE, {"open_id": open_id, "app_name": bot.get("app_name"),
+                               "app_id": app_id})
     return open_id
 
 

package/examples/feishu/feishu_drain.py

@@ -3,7 +3,9 @@
 
 One invocation = one reconcile pass. Reads every group chat the bot is in
 (plus the thread containers those chats reveal) from the committed cursor,
-prints one JSONL item per human message, then the new cursor.
+prints one JSONL item per human message, then the new cursor. Chat `system`
+events (invites, renames, pins) are logged to stderr instead: an event is
+something the conversation did, not something a human said (ADR 0024).
 
 Environment (all optional, read from `~/.agents/pods/adapters/.env` too):
   FEISHU_APP_ID / FEISHU_APP_SECRET   the bot app credentials
@@ -32,6 +34,7 @@ import feishu_client as fc
 PAGE_SIZE = 50
 THREAD_PAGE_CEILING = 6
 THREAD_KEEP_SECONDS = 7 * 24 * 3600
+SYSTEM_MSG_TYPE = "system"
 
 
 def env_int(name, default):
@@ -105,6 +108,130 @@ def mentions_bot(msg, open_id):
     return False
 
 
+def is_system(msg):
+    """A conversation event — invite, rename, pin — rather than a message."""
+    return (msg.get("msg_type") or "") == SYSTEM_MSG_TYPE
+
+
+def is_item(msg, *, require_mention, open_id):
+    """Whether one message is Inbox material (ADR 0024).
+
+    The `system` exclusion is about what a conversation contains, not about
+    identity: an event has no author to answer, so it cannot become an item.
+    `sender_type == "app"` stays a separate filter — a bot message is still a
+    message, just not one the pod needs to answer.
+    """
+    if not msg.get("message_id"):
+        return False
+    if is_bot(msg):
+        return False
+    if is_system(msg):
+        return False
+    if require_mention and not mentions_bot(msg, open_id):
+        return False
+    return True
+
+
+def item_from(msg, chat_id, chat_name):
+    """The Inbox record for one message, or None when it flattens to nothing.
+
+    Pure, so the item's shape is testable without a tenant (ADR 0024: `id`,
+    `body` and the optional routing fields).
+    """
+    body = fc.flatten_message(msg)
+    if not body:
+        return None
+    msg_id = msg.get("message_id")
+    return {
+        "id": msg_id,
+        "title": "%s: %s" % (chat_name, body.splitlines()[0][:60]),
+        "body": body,
+        "chat_id": chat_id,
+        "root_id": msg.get("root_id") or msg.get("parent_id") or msg_id,
+        "thread_id": msg.get("thread_id") or "",
+        "at": created_at(msg),
+    }
+
+
+def new_pass(*, require_mention, open_id):
+    """The per-pass intake state: what this pass saw, kept, and consumed."""
+    return {
+        "seen": set(),
+        "collected": [],
+        "consumed_at": 0,
+        "require_mention": require_mention,
+        "open_id": open_id,
+    }
+
+
+def absorb(pass_state, msg, chat_id, chat_name):
+    """Fold one message into a pass; returns `item`, `system`, `skip` or `seen`.
+
+    Pure — no network, no environment, no store. A `system` event is consumed
+    like any other message (so the cursor crosses it) but yields no item: it
+    belongs in the operator's log, not the Inbox.
+    """
+    msg_id = msg.get("message_id")
+    if not msg_id or msg_id in pass_state["seen"]:
+        return "seen"
+    if is_system(msg):
+        pass_state["seen"].add(msg_id)
+        pass_state["consumed_at"] = max(pass_state["consumed_at"], created_at(msg))
+        return "system"
+    if not is_item(msg, require_mention=pass_state["require_mention"],
+                   open_id=pass_state["open_id"]):
+        pass_state["consumed_at"] = max(pass_state["consumed_at"], created_at(msg))
+        return "skip"
+    item = item_from(msg, chat_id, chat_name)
+    if item is None:
+        pass_state["consumed_at"] = max(pass_state["consumed_at"], created_at(msg))
+        return "skip"
+    pass_state["seen"].add(msg_id)
+    pass_state["collected"].append(item)
+    pass_state["consumed_at"] = max(pass_state["consumed_at"], item["at"])
+    return "item"
+
+
+def advance_cursor(cursor, emitted, collected, consumed_at):
+    """Where the next pass starts (ADR 0024).
+
+    The cursor never jumps a message this pass left for later, so while items
+    remain queued it stops at the last one printed. With nothing queued it also
+    crosses skipped messages, because they are consumed rather than deferred:
+    a pass of nothing but system events still advances, and zero items with a
+    cursor stays distinguishable from a drain pointed at nothing (ADR 0027).
+    `None` means "no cursor line": the pass read and consumed nothing at all.
+    """
+    if not emitted and not consumed_at:
+        return None  # nothing read and nothing skipped: the "pointed at nothing" shape
+    next_cursor = max(cursor or 0, emitted[-1]["at"] if emitted else 0)
+    if len(collected) <= len(emitted):
+        next_cursor = max(next_cursor, consumed_at)
+    return next_cursor
+
+
+def output_lines(items, cursor):
+    """The drain's stdout: one item per line, then the cursor line (ADR 0024).
+
+    `at` is internal ordering only. A cursor-only output is the whole answer of
+    a pass that consumed events but had nothing to deliver — deliberately not
+    the same shape as empty stdout.
+    """
+    lines = []
+    for item in items:
+        record = {key: value for key, value in item.items() if key != "at"}
+        lines.append(json.dumps(record, ensure_ascii=False))
+    if cursor:
+        lines.append(json.dumps({"cursor": str(cursor)}))
+    return lines
+
+
+def note_system_event(msg, chat_id):
+    """A skipped event is the operator's line, never an Inbox item."""
+    warn("skip system event %s in %s"
+         % (msg.get("message_id") or "?", chat_id or "?"))
+
+
 def main():
     if "--check" in sys.argv[1:]:
         return self_check()
@@ -141,32 +268,22 @@ def main():
     chats = [c for c in chats if not allowlist or c.get("chat_id") in allowlist]
     chat_names = {c.get("chat_id"): (c.get("name") or c.get("chat_id")) for c in chats}
 
-    collected, seen = [], set()
+    pass_state = new_pass(require_mention=require_mention, open_id=open_id)
+    collected = pass_state["collected"]
 
-    def absorb(chat_id, msg):
-        msg_id = msg.get("message_id")
-        if not msg_id or msg_id in seen or is_bot(msg):
+    def handle(chat_id, msg):
+        kind = absorb(pass_state, msg, chat_id,
+                      chat_names.get(chat_id, chat_id or "chat"))
+        if kind == "system":
+            note_system_event(msg, chat_id)
             return
-        if require_mention and not mentions_bot(msg, open_id):
+        if kind != "item":
             return
-        body = fc.flatten_message(msg)
-        if not body:
-            return
-        seen.add(msg_id)
-        thread_id = msg.get("thread_id") or ""
-        collected.append({
-            "id": msg_id,
-            "title": "%s: %s" % (chat_names.get(chat_id, chat_id or "chat"),
-                                 body.splitlines()[0][:60]),
-            "body": body,
-            "chat_id": chat_id,
-            "root_id": msg.get("root_id") or msg.get("parent_id") or msg_id,
-            "thread_id": thread_id,
-            "at": created_at(msg),
-        })
+        item = collected[-1]
+        thread_id = item["thread_id"]
         # A thread container is the only place its replies appear (ADR 0024).
         if thread_id and thread_id not in threads:
-            threads[thread_id] = {"chat_id": chat_id, "seen_at": created_at(msg) or now}
+            threads[thread_id] = {"chat_id": chat_id, "seen_at": item["at"] or now}
 
     for chat in chats:
         chat_id = chat.get("chat_id")
@@ -176,7 +293,7 @@ def main():
         chat_since = since if chat_id in known_chats else max(0, now - lookback)
         try:
             for msg in iter_messages(token, "chat", chat_id, chat_since):
-                absorb(chat_id, msg)
+                handle(chat_id, msg)
         except fc.FeishuError as err:
             warn("chat %s: %s" % (chat_id, err))
             return 1
@@ -192,7 +309,7 @@ def main():
             for msg in iter_messages(token, "thread", thread_id):
                 if created_at(msg) < since:
                     continue
-                absorb(chat_id or msg.get("chat_id") or "", msg)
+                handle(chat_id or msg.get("chat_id") or "", msg)
         except fc.FeishuError as err:
             warn("thread %s: %s" % (thread_id, err))
             continue
@@ -208,17 +325,13 @@ def main():
 
     collected.sort(key=lambda item: item["at"])
     emitted = collected[:max_items]
-    # The cursor stops at the last item printed: the rest must not be skipped.
-    next_cursor = max(cursor or 0, emitted[-1]["at"] if emitted else 0)
+    next_cursor = advance_cursor(cursor, emitted, collected, pass_state["consumed_at"])
 
-    for item in emitted:
-        item.pop("at", None)
-        sys.stdout.write(json.dumps(item, ensure_ascii=False) + "\n")
+    for line in output_lines(emitted, next_cursor):
+        sys.stdout.write(line + "\n")
 
     if len(collected) > len(emitted):
         warn("%d more messages wait for the next pass" % (len(collected) - len(emitted)))
-    if emitted and next_cursor:
-        sys.stdout.write(json.dumps({"cursor": str(next_cursor)}) + "\n")
     sys.stdout.flush()
     return 0
 

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()