agents-pod 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.0] — 2026-11-04
+
+A machine whose IM surface has never been exercised can now say so. Discovery
+was the one thing ADRs 0024/0025 left without a home: credentials and sockets
+moved into operator commands, so core could not check any of it, and every
+failure mode — a drain that runs and yields nothing, a missing deliverer, no
+channels, no cron line — was exit-`0`-silent by design (issue #19).
+
+### Added
+
+- **`agents-pod doctor [--probe] [--json]`** — a read-only Health Report over
+  the store (ADR 0027): store and registry, the last pass, each Source (command,
+  cursor, drain age and yield, last failure), each Listener (Source or inbox,
+  template, project, bound Pod), the deliverer with pending and dead Outbox
+  entries, and the notification config including a `passwordEnv` that is not
+  set. `✓` nothing to do, `✗` blocks a channel, `?` worth knowing; exit `0`
+  clean, `1` otherwise, `2` for usage errors.
+- **The first run, printed** — with no Source, no deliverer and no channel,
+  `doctor` prints the ordered recipe instead of a report, shrinking to the
+  missing steps once anything exists. A bare `agents-pod` now names `doctor`
+  instead of answering `Unknown command`.
+- **`<cmd> --check`** — the operator command's own self-check (exit `0`
+  healthy, `3` none here, anything else unhealthy), run by `doctor --probe`
+  under the ten-second budget and quoted verbatim. Core still holds no
+  credentials; the side that owns them does the checking.
+- **`examples/feishu/`** — a worked Source and deliverer pair for Feishu with
+  `--check` implemented, a `.env.example`, and the platform facts measured
+  while wiring it to a real tenant: the four scopes, `230027`/`99991672`, the
+  group that must be created by a human, and the endpoints that are not there.
+- **Two facts that end the silence**: `sources.json` now records
+  `lastDrainItems`, `lastError` and `lastFailureAt` (a zero-yield drain is
+  visible; a failure is reportable without tailing `cron.log`), and every pass
+  writes `last-pass.json`, so "cron is not installed" and "cron runs and finds
+  nothing" read differently.
+
+### Changed
+
+- A failed drain's record keeps the failure fact; the cursor, drain horizon and
+  yield still do not move (ADR 0024, amended in ADR 0027).
+
+## [0.2.0] — 2026-11-04
+
+Work that arrives in a chat can now be picked up there, and answered there,
+without a resident process holding a socket: a **Source** drains a conversation
+into a pod once per pass, a **Deliverer** posts a pod's **Outbox** back, and a
+**Delivery Address** rides the Goal so a Worker can reply without asking anyone.
+
+### Added
+
+- **IM intake and outbound — Source, Deliverer, Outbox, and Delivery Address** —
+  a pull-based intake and file-based reply path, with platform credentials and
+  API behavior kept in operator commands.
+- **Sources and drains** — `source add|list|rm`, cursor-based JSONL drains with
+  platform ids and routing fields, bounded execution, claim-before-cursor
+  commits, and two-generation claim retention.
+- **Source Listeners and standing Pod intake** — `listener add --source`, batched
+  `TASKS.md` Inbox delivery with Waiting state, the `{{reply_to}}` template
+  placeholder, and `--project` for template-materialized Pods.
+- **Outbox delivery** — `deliver add|list|rm`, one operator deliverer, named
+  per-wake-up entry files carrying `{to, text}`, stable delivery uuids, bounded
+  wrapper and reconcile flushes, same-uuid retries, one-hour dead-lettering,
+  and retained `*.dead` entries for expired or invalid input.
+
+### Fixed
+
+- Wake-up outcomes are recorded under the registry lock, so concurrent passes
+  and wrappers no longer overwrite each other's registry updates.
+
 ## [0.1.0] — 2026-11-03
 
 First release: one pod, many wake-ups, and the machinery that keeps a standing

package/README.md

@@ -4,9 +4,11 @@ Supervision for long-running coding agents: spawn a **pod** — a standing
 unit that outlives every context window — and wake **agents** inside it,
 again and again, each wake-up fresh, documents carrying the work across.
 
-> **Status: `0.1.0` — first release.** The CLI runs (spawn, wake, cancel,
-> logs, reconcile, listeners, notifications) and the Pi extension ships its two
-> planes. Wake-ups are **Pi only** in this release. Interfaces may still move
+> **Status: `0.2.0` — IM intake and outbound.** The CLI runs (spawn, wake,
+> cancel, logs, reconcile, listeners, sources, deliverers, notifications) and the
+> Pi extension ships its two planes. A pod can now be fed from a chat and answer
+> into it, through operator commands that keep credentials and sockets out of
+> core. Wake-ups are **Pi only** in this release. Interfaces may still move
 > before `1.0`. The design lives in `CONTEXT.md` and `docs/adr/`; a reader's
 > companion — the design principles and an explained vocabulary — in
 > [docs/DESIGN.md](docs/DESIGN.md).
@@ -73,11 +75,11 @@ agent (planner, coder, reviewer; pi, claude, codex) across its life
 
 **Wake-ups are the context unit; the pod isolates them.** One **wake-up** =
 one agent, one fresh context window: read the pod documents first, work,
-record (handoff, decisions, task state), exit with an outcome. Nothing
-crosses wake-ups except documents — agents in a pod share its documents,
-never one another's windows. Context exhaustion ends a wake-up, never the
-pod; waking again is routine, not recovery. The store's contract is three
-slots, two hard lines ([ADR 0008](docs/adr/0008-document-store-contract.md)).
+record (handoff, decisions, task state), exit with an outcome. Agents in a
+pod share its documents, never one another's windows; pending Outbox entries
+are files, not context. Context exhaustion ends a wake-up, never the pod;
+waking again is routine, not recovery. The store's contract is three slots,
+two hard lines ([ADR 0008](docs/adr/0008-document-store-contract.md)).
 
 **A wrapper owns each wake-up's liveness.** Every wake-up gets a tiny
 **wrapper** — detached, session and process-group leader — that spawns the
@@ -135,6 +137,7 @@ package until both plugins demonstrably need one.
 ## CLI
 
 ```text
+agents-pod doctor [--probe] [--json]                     # what is missing, and the command that fixes it
 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
@@ -148,10 +151,16 @@ agents-pod agent add <id> --type <pi|claude|codex> [--model <id>] [--instruction
 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> [--pod <podId> | --template <file>]
-                         [--match <substr>] [--max-concurrent <n>]
+agents-pod listener add (--inbox <dir|file> | --source <name>) (--pod <podId> | --template <file>)
+                         [--match <substr>] [--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 deliver add <name> --cmd <path> [--timeout <s>]
+agents-pod deliver list [--json]
+agents-pod deliver rm <name>
 ```
 
 `spawn` claims a pod id, writes the pod record, wakes the first agent, and
@@ -160,8 +169,8 @@ 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.
 Exit codes follow the house rule: `0` success
-or nothing to do, `1` at least one pod failed, `2` configuration or storage
-error.
+or nothing to do, `1` at least one pod failed (or `doctor` found something
+that blocks a channel), `2` configuration or storage error.
 
 Every goal prompt carries the wake-up protocol: read the pod documents
 first, record before exiting.
@@ -222,21 +231,28 @@ policy, per record:
 - terminal → no-op (terminal is terminal: `wake` refuses; continuation is
   a new pod).
 
-After pods, the same pass materializes listeners: scan each inbox, claim new
-items by id (registry-first, so a lost tick cannot double-claim), then
-either spawn a pod from the listener's template or wake the bound standing
-pod — bounded by `--max-concurrent` and the per-project pod cap.
+After pods, the same pass materializes listeners: use each Source's drained
+items or scan each inbox, claim new items by id (registry-first, so a lost tick
+cannot double-claim), then either spawn a pod from the listener's template —
+bounded by `--max-concurrent` and the per-project pod cap — or append a batch
+to the bound standing pod and use the ordinary capacity-checked wake path.
 
 An inbox is a directory (one item per top-level non-dot file; claimable once
 its mtime and size hold across two passes) or one append-only JSONL file
-(`body` required; malformed lines skipped with a warning). Item ids are
-filenames or line numbers — never content — claimed per inbox; templates
-bind `{{id}}` `{{title}}` `{{body}}` `{{path}}` (ADR 0013).
+(`body` required, `title` optional; malformed lines skipped with a warning).
+A JSONL line may also carry the routing fields `chat_id`, `root_id` and
+`thread_id`; any other key is ignored. Item ids are filenames or line
+numbers — never content — claimed per inbox; templates bind five
+placeholders: `{{id}}` `{{title}}` `{{body}}` `{{path}}` and `{{reply_to}}`.
+The last placeholder carries the Delivery Address consumed by the outbound
+contract below (ADRs 0013, 0026).
 
 For a standing pod, claimed items land in its `TASKS.md` `## Inbox`
-section — appended only while no wake-up is live, then one batch, one wake
-on the ordinary wake path; the agent serves entries and flips their
-checkboxes (ADR 0014).
+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
+agent serves entries and flips their checkboxes. A block with a Delivery
+Address carries ` — to: <Delivery Address>` on its checkbox line, never in
+the copied body (ADRs 0014, 0026).
 
 Overlapping passes: one TTL'd single-flight lock (`reconcile.lock`, stale
 after 5 minutes by wall clock — never PID liveness) skips fresh-held ticks
@@ -247,7 +263,228 @@ registry-lock CAS on every state transition, so two passes — or a human
 Notifications (P1): two events only — park (with the failure verdict)
 and done — through the copied channels (webhook/email/system) in
 `~/.agents/pods/config.json`; once per episode; individual outcomes
-never notify (ADR 0021).
+never notify (ADR 0021). A store with no channels at all stays silent by
+design, so `agents-pod doctor` reports it as a `?` line rather than letting
+silence look like health.
+
+## First run
+
+`agents-pod doctor` answers one question, read-only: what does this machine
+still lack for a conversation to reach a Pod, and a reply to leave one? With
+nothing configured it prints the ordered first run instead of a report — write
+a Source command, `source add`, `listener add`, `deliver add`, the cron line,
+`doctor` again — and exits `1` until every line is `✓`
+([ADR 0027](docs/adr/0027-discovery-doctor-and-the-self-check.md)).
+
+```text
+store     ✓ 1 pods, 0 active
+pass      ✓ last pass 41s ago
+intake    ✗ source feishu: the last drain (2s ago) failed — exit 1
+                  run: agents-pod doctor --probe
+listeners ✓ listener-4f1a: source feishu → template triage.md → /work/app
+outbound  ✓ deliverer feishu-reply: ~/.agents/pods/adapters/feishu_deliver.py
+notify    ? no notification channels: parks and dones stay silent
+```
+
+`✓` nothing to do, `✗` the channel cannot work, `?` worth knowing — a quiet
+chat, no channels, a pass that has not run. Exit `0` when nothing is `✗`, `1`
+otherwise, `2` for store or usage errors; `--json` prints the same report as
+data. Two small records make the silent cases visible: `sources.json` keeps
+the last drain's yield and its last failure, and every pass marks
+`last-pass.json`, so "cron is not installed" and "cron runs and finds nothing"
+stop looking identical.
+
+**Credentials belong to the operator command, so only it can check them.** The
+convention is `<cmd> --check`: exit `0` healthy, `3` no self-check here,
+anything else unhealthy. `doctor --probe` runs it once for each Source and
+once for the deliverer and quotes its lines verbatim — which is how a missing
+platform scope, with its console URL, reaches the person who can grant it:
+
+```text
+checks    ✗ source feishu: self-check failed (exit 1)
+                  read failed in 联调: code=230027 msg=Lack of necessary permissions, ext=need scope: im:message.group_msg
+                  https://open.feishu.cn/app/cli_…/auth?q=im:message.group_msg&op_from=openapi&token_type=tenant
+```
+
+Plain `doctor` never executes operator code. `examples/feishu/` is a worked
+pair that implements `--check` and records the platform facts measured while
+wiring it up: the four scopes, the error codes, and the two traps that cost an
+afternoon.
+
+## IM intake and outbound
+
+The operator owns platform I/O. A **Source** is an executable pull drain; the
+single **deliverer** is an executable push command. Source definitions and
+their committed cursors live in `~/.agents/pods/sources.json`; Listener claims
+live in `~/.agents/pods/listeners.json`; the deliverer lives in
+`~/.agents/pods/deliverer.json`. `source add` and `deliver add` resolve `--cmd`
+against the add command's cwd and require an executable regular file.
+`--timeout` is a positive number of seconds, default `10`. Their add/list/rm
+commands return `0` on success; invalid arguments, an unknown or duplicate
+name, removing an in-use Source, or adding a second deliverer returns `2`.
+
+`listener add --source <name>` takes either `--template <file>` or
+`--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.
+
+### Writing a Source drain
+
+Each reconcile pass invokes every distinct Source consumed by a Listener once,
+before any Pod work and before taking the registry lock. The command receives
+no arguments. Its cwd is the reconcile invocation's project (its cwd, not a
+Listener's `--project`), and it inherits that invocation's environment plus:
+
+- `AGENTS_POD_SOURCE_ID` — the registered Source name;
+- `AGENTS_POD_CURSOR` — the last committed cursor, or the empty string when no
+  cursor has been committed.
+
+The command writes JSONL to stdout; stdin is closed and stderr is ignored. A
+successful stream contains zero or more items followed by an optional cursor
+as the last non-empty line:
+
+```jsonl
+{"id":"message-123","body":"Please review this","title":"Review request","chat_id":"chat-1","root_id":"root-1","thread_id":"thread-1"}
+{"cursor":"next-page-token"}
+```
+
+- `id` is a non-empty string and `body` is a string; both are required. The id
+  is the platform's stable deduplication key.
+- `title` is optional. A missing or blank title defaults to the trimmed first
+  line of `body`.
+- `chat_id`, `root_id` and `thread_id` are optional routing strings. Non-empty
+  values are trimmed; blank or non-string values are ignored. They feed
+  `{{reply_to}}`. Source items have no filesystem path, so `{{path}}` is empty.
+  Unknown keys are ignored.
+- The final `{"cursor":"…"}` line takes a string. Omitting it leaves the
+  stored cursor unchanged. Blank lines are ignored. A malformed JSON line, an
+  invalid item, or an invalid final cursor is skipped with one
+  `~/.agents/pods/cron.log` warning and is not claimed; other valid lines still
+  count.
+
+Exit `0` commits the successful drain. Claims use `source:<name>` as their
+inbox namespace and the item's platform id, shared by every Listener on that
+Source. Claims are written to `listeners.json` before the Source's cursor is
+atomically written to `sources.json`, so a crash between those writes replays
+into id deduplication. A committed drain also advances the record's
+`lastDrainAt` and records its yield as `lastDrainItems` — zero is a fact, not a
+gap, and it is what makes a pull that is pointed at nothing visible to
+`agents-pod doctor` (ADR 0027). Claims from the current and previous
+successful drain generations are retained and older timestamped claims are
+pruned. Claims with
+no generation timestamp are retained. For a Source bound to a standing Pod,
+the claimed batch must also be appended to `TASKS.md` before cursor and
+`lastDrainAt` commit; a live wake-up holds that append, so the next pass drains
+from the unchanged cursor again.
+
+A non-zero exit, termination by a signal, spawn failure, timeout, or total
+stdout larger than **1 MiB** abandons the whole drain: no items are claimed,
+neither cursor nor `lastDrainAt` nor `lastDrainItems` moves, no claims are
+pruned, and exactly one `cron.log` line records the failure. The record also
+keeps `lastError` and `lastFailureAt`, cleared by the next success, so the
+report can name a Source that fails every pass without tailing the log
+(ADR 0027). Reconcile still exits `0`; the next pass retries the whole drain
+from the same cursor (ADR 0024).
+
+A Source command may also answer `<cmd> --check` (exit `0` healthy, `3` no
+self-check here, anything else unhealthy) with its own diagnosis on
+stdout/stderr; `agents-pod doctor --probe` runs it and quotes it (ADR 0027).
+The drain invocation never passes an argument — the check is a second calling
+convention, opted into by the command that implements it.
+
+### Writing the deliverer
+
+Exactly one deliverer may be configured; remove it before adding a replacement.
+A Wake-up writes one JSON file per outgoing message in its own Pod:
+
+```text
+<project>/.agents/pods/<podId>/outbox/<wakeup>-<seq>-<name>.json
+```
+
+`<wakeup>` is the positive integer wake-up number, `<seq>` is a zero-padded
+increasing sequence such as `001`, `002`, and `<name>` is a filename-safe slug.
+Files are delivered serially in filename order. Each file contains a JSON
+object with a non-empty string `to` and a string `text`:
+
+```json
+{"to":"<Delivery Address>","text":"The reply text"}
+```
+
+`to` is the **Delivery Address** rendered by `{{reply_to}}` or carried on a
+standing Pod's Inbox checkbox line. The worker copies it verbatim; the
+deliverer parses it; core never reads it back. Its shape is:
+
+```text
+chat=<chat_id>;affinity=<root_id ?? item id>[;thread=<thread_id>]
+```
+
+An item with no `chat_id` renders the empty string, which is not a valid `to`
+and cannot be delivered. When `thread` is present, the deliverer can use it to
+reply in that thread.
+
+The Wrapper invokes the deliverer once per current-wake-up entry after the
+agent exits and before the Pod becomes idle. Reconcile retries entries for
+every non-active Pod, outside the registry lock. Each invocation receives the
+entry file's bytes verbatim on stdin, takes no arguments, runs with the Pod's
+project as cwd, and ignores stdout and stderr. It inherits the operator
+environment plus exactly these core-provided values:
+
+- `AGENTS_POD_POD_ID` — the owning Pod id;
+- `AGENTS_POD_WAKEUP_N` — the wake-up number parsed from the filename;
+- `AGENTS_POD_OUTBOX_ENTRY` — the entry filename, not its full path;
+- `AGENTS_POD_OUTBOX_UUID` — the 50-character lowercase hexadecimal idempotency
+  key derived from Pod id, wake-up number, and filename. Pass this same value
+  to the platform on every retry.
+
+One flush per Pod makes at most **10 delivery attempts** within a shared
+**10-second budget**, in filename order. The configured per-invocation timeout
+defaults to 10 seconds and is additionally capped by the flush's remaining
+budget. Entries left beyond either bound wait for a later pass.
+
+Exit `0` is the only acknowledgement: core deletes the entry and writes no
+completion marker. A non-zero exit, signal, spawn failure, or timeout leaves
+the file unchanged, writes one `cron.log` line, and lets the next pass retry
+with the same uuid. Delivery failure does not change the Wake-up outcome,
+failure streak, or notifications.
+
+An entry whose mtime is more than **one hour** old is not delivered: core
+renames it by appending `.dead`, logs one line, and keeps its contents
+unchanged. A malformed entry, a filename with no valid leading wake-up number,
+or a future-wake-up entry seen by a Wrapper is likewise dead-lettered on first
+sight. `*.dead` files are never scanned again or automatically removed. With
+no deliverer configured, the Wrapper flush is a no-op; each reconcile pass
+writes one `cron.log` line per Pod with waiting entries, and the same one-hour
+aging still applies (ADR 0025).
+
+A deliverer may answer `<cmd> --check` on the same convention as a Source
+command (exit `0` healthy, `3` no self-check here, anything else unhealthy);
+`agents-pod doctor --probe` runs it, and `agents-pod doctor` reports any
+entries waiting in Pod outboxes while no deliverer is configured (ADR 0027).
+
+### Role Instructions for replying agents
+
+Save the following as the replying Agent's instructions file and pass it to
+`agent add --instructions <file>`:
+
+```text
+When you reply to a Conversation, write one JSON file per reply into your own
+Pod's outbox at .agents/pods/$AGENTS_POD_POD_ID/outbox/ under the Pod project.
+Name each file $AGENTS_POD_WAKEUP_N-<seq>-<name>.json, using a zero-padded
+increasing <seq> (001, 002, ...) and a filename-safe <name>. Write
+{"to":"<Delivery Address>","text":"<reply>"}; copy the address verbatim from
+Reply-To in the Goal or from "to:" on the item's TASKS.md Inbox checkbox line.
+Do not write an entry when that address is empty.
+
+If you ask a question in a thread, reply in that same thread by reusing its
+Delivery Address, including the thread component. Ask at most two clarification
+rounds per uncertainty; then proceed on a stated assumption and record that
+assumption in HANDOFF.md.
+
+Core deletes an entry only after the deliverer exits 0. A failed delivery keeps
+the file, logs one line, and is retried on the next pass with the same uuid; an
+entry older than one hour is renamed with a .dead suffix and kept. Do not
+rename, delete, or rewrite pending or dead entries yourself.
+```
 
 ## Storage
 
@@ -256,12 +493,17 @@ never notify (ADR 0021).
 ├── pods.json          # global pod registry: definitions + state, 0600
 ├── agents.json        # named agents: adapter type, model, role instructions, 0600
 ├── listeners.json     # listeners, bounds, claimed item ids, 0600
+├── sources.json       # named drain commands, committed cursors, lastDrainAt
+│                      # + lastDrainItems and the last failure (ADR 0027)
+├── deliverer.json     # the single outbound delivery command
+├── last-pass.json     # when a pass last finished, so "never ran" is a fact
 ├── inboxes/<id>/      # default listener inboxes; any dir/file may serve instead
 └── registry.lock      # short-lived registry write lock, 0600
 
 <project>/.agents/pods/
 └── <podId>/
-    ├── docs/          # HANDOFF.md · DECISIONS.md · TASKS.md — the only cross-wake state (ADR 0008)
+    ├── docs/          # HANDOFF.md · DECISIONS.md · TASKS.md — cross-wake work memory (ADR 0008)
+    ├── outbox/        # pending <wakeup>-<seq>-<name>.json replies and retained *.dead entries
     ├── output.log     # every wake-up, append-only, wake-up delimited; trimmed idle by
     │                   # reconcile: cap 10 MB, keep 2 MB, oldest sections dropped (ADR 0016), 0600
     ├── heartbeat      # touched by the live wake-up's wrapper every 30s; mtime = last beat;
@@ -317,7 +559,18 @@ adapted from agents-cron); listeners — inbox directory and JSONL file
 sources, per-item pods from templates, bound standing pods; wake admission
 honouring `--after` dependencies and the per-project cap; the Pi extension's
 two planes (ADR 0010) — `/pod` commands, `spawn_pod`, and `pod_handoff`.
-No default timeout anywhere — liveness is heartbeat-based or it is nothing.
+No default Wake-up timeout — liveness is heartbeat-based or it is nothing.
+
+**Shipped in `0.2.0`.** Chat as an intake and an outlet, both as operator
+commands rather than a daemon: sources (`source add|list|rm`) drained once per
+pass with a committed cursor and claim-before-cursor ordering; source-fed
+Listeners, batched `## Inbox` delivery to a standing pod, and `## Waiting` above
+it; outbox delivery (`deliver add|list|rm`) at wake-up exit and in every pass,
+with stable uuids, one-hour dead-lettering and retained `*.dead` entries; the
+Affinity Key and the `{{reply_to}}` Delivery Address riding the Goal or an Inbox
+line; `listener add --project` for tuning intake and workers apart. A wrapper's
+outcome is now recorded under the registry lock, so a concurrent pass or wrapper
+cannot overwrite it and force the same wake-up to run twice (ADR 0018).
 
 **Next.** The Claude Code and Codex adapters (`--type` is refused today, not
 silently downgraded). Default pod expiry and guarded fan-out — the
@@ -342,3 +595,8 @@ is refused at the surface and at launch. The extension lives in
 `src/extension/` (one module per plane, plus `handoff.ts` for the document
 rendering), with `index.mjs` at the package root as Pi's entry so the footer
 label stays `agents-pod`.
+
+`examples/` ships operator commands that core never imports — today the Feishu
+Source/deliverer pair — as copyable starting points. `src/doctor.ts` is the
+read-only Health Report; it is tested through the CLI like everything else,
+with fake operator commands that answer `--check` on each exit code.

package/examples/feishu/.env.example

@@ -0,0 +1,23 @@
+# A copy of this file is your own: `cp .env.example .env` (0600), then fill in.
+# Nothing here is ever committed; core never reads these — the commands do
+# (ADRs 0024, 0025), and `agents-pod doctor --probe` asks the commands.
+
+# Self-built app credentials: open platform → app → 凭证与基础信息.
+FEISHU_APP_ID=
+FEISHU_APP_SECRET=
+
+# Comma-separated chat_id allowlist; empty = every group chat the app is in.
+# Read a chat_id from state.json's known_chats after one successful drain.
+FEISHU_CHATS=
+
+# 1 = only messages that @-mention the bot (a mixed-use group); 0 = everything.
+FEISHU_REQUIRE_MENTION=0
+
+# First-run window when there is no cursor yet, and the re-read overlap behind
+# an existing one, in seconds.
+FEISHU_LOOKBACK_SECONDS=3600
+FEISHU_OVERLAP_SECONDS=60
+
+# Per-pass item cap; the cursor stops at the last item printed, so a bigger
+# burst simply arrives over several passes.
+FEISHU_MAX_ITEMS=40

package/examples/feishu/README.md

@@ -0,0 +1,92 @@
+# A Feishu command pair for agents-pod
+
+Two operator commands that hold every platform concern — app credentials, token
+rotation, chat and thread paging, message flattening, reply addressing — so
+core stays credential- and socket-free (ADRs [0024](../../docs/adr/0024-sources-pull-drain-and-cursor.md),
+[0025](../../docs/adr/0025-outbox-operator-delivery-and-entry-files.md)).
+
+| file | role | registered as |
+|---|---|---|
+| `feishu_drain.py` | Source: chats + threads → JSONL items + a cursor line | `agents-pod source add feishu --cmd <path>` |
+| `feishu_deliver.py` | Deliverer: one Outbox entry → one Feishu reply | `agents-pod deliver add feishu-reply --cmd <path>` |
+| `feishu_client.py` | shared client: token cache, paging, message flattening | — |
+| `.env.example` | the switchboard; copy to `.env` (0600) and fill | — |
+
+Copy all four next to each other anywhere outside this repository — the pair is
+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 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
+```
+
+## The one thing this cannot do for you: the app
+
+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 |
+
+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.
+
+## Smoke test
+
+```bash
+cd ~/.agents/pods/adapters
+env AGENTS_POD_SOURCE_ID=feishu AGENTS_POD_CURSOR= ./feishu_drain.py   # JSONL items, then {"cursor":"…"}
+printf '%s' '{"to":"chat=oc_xxx;affinity=om_xxx","text":"通道自检"}' | ./feishu_deliver.py
+```
+
+`exit 0` on both is the wiring. A drain that prints nothing **and** exits `0`
+is not proof of health — it is the shape of "the pull is pointed at nothing",
+which is why `sources.json` records `lastDrainItems` and why
+`agents-pod doctor` prints a `?` line for a zero-yield drain (ADR 0027).
+
+Both commands answer `--check` (exit `0` healthy, `1` not) with their own
+diagnosis, including the console URL for a missing scope; `agents-pod doctor
+--probe` runs those and quotes them.
+
+## Measured traps
+
+Facts observed while wiring this pair to a real tenant, in the order they bite:
+
+| trap | what actually happens |
+|---|---|
+| **Send works while read is denied** | The bot can post into a group and cannot read a word of it, so a half-granted app looks alive. `im:message.group_msg` is the one that blocks intake (`230027`), and the error message carries its own console link. |
+| **An app-created chat is invisible to humans** | `POST /im/v1/chats` succeeds (so does the local test above), but the group is created *by the app*: you do not see it in Feishu, and you cannot join it without another write scope. Create the group in the client and add the bot — that is the only shape a human can also type into. |
+| **A new chat can take a moment to appear** | `GET /im/v1/chats` may return `items: []` for a chat that exists; a retry a few seconds later lists it. Treat one empty page as inconclusive before concluding the bot is in no group. |
+| **p2p is not enumerable** | The chat list excludes p2p conversations, so a pull drain cannot see a direct message (ADR 0024). Group chats are the supported intake shape. |
+| **`/im/v1/chats/:chat_id/link` is 404** | Not every endpoint in older notes exists on the tenant's version; do not build an invite flow on it. |
+| **A version must be published** | Granting scopes without 版本管理与发布 changes nothing at runtime, and the refusal looks identical to "scope not granted". |
+| **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). |
+
+## Switchboard (`.env`, or the environment — the environment wins)
+
+- `FEISHU_CHATS` — comma-separated `chat_id` allowlist; empty = every chat.
+- `FEISHU_REQUIRE_MENTION` — `1` reads only messages that @-mention the bot.
+- `FEISHU_LOOKBACK_SECONDS` (3600) / `FEISHU_OVERLAP_SECONDS` (60) /
+  `FEISHU_MAX_ITEMS` (40) — first-run window, re-read overlap behind the
+  cursor, per-pass cap. The cap never loses messages: the cursor stops at the
+  last item printed.
+
+## Two independent commands, one platform
+
+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`.