agents-pod 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.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
@@ -148,10 +150,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
@@ -222,21 +230,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
@@ -249,6 +264,164 @@ and done — through the copied channels (webhook/email/system) in
 `~/.agents/pods/config.json`; once per episode; individual outcomes
 never notify (ADR 0021).
 
+## 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`; 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` moves, no claims are pruned, and exactly one
+`cron.log` line records the failure. Reconcile still exits `0`; the next pass
+retries the whole drain from the same cursor (ADR 0024).
+
+### 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).
+
+### 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
 
 ```text
@@ -256,12 +429,15 @@ 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
+├── deliverer.json     # the single outbound delivery command
 ├── 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 +493,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

package/package.json

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