pi-session-mail 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,58 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-31
+
+### Added
+
+- The `message:reply` hook: an extension that took over a request answers it
+  by emitting `{ to, inReplyTo, body, status }`. `pi-session-mail` writes a
+  reply from the current session (the caller cannot set `from`) with that
+  body and status exactly as given, at once, without waiting for the run to
+  settle or using the model's answer, and sets `envelope` or `error` on the
+  payload before `emit` returns, as `message:send` does. `status` is
+  required and is `done`, `stopped` or `failed`; `inReplyTo` is a non-empty
+  list of at most 50 non-empty ids, checked for shape only and not looked up
+  in the mailbox; `body` is any string; `to` is checked as `message:send`
+  checks it. There is no duplicate guard: every valid call writes a reply.
+  With no provider installed, neither field is set. The reply travels like any
+  other: it waits in a closed sender's inbox, and the sender gets it through
+  `message:inbound` with its request copies. Asks are still answered with
+  `session_mail_reply` or at settle. The README documents the hook with a
+  runnable request-to-reply example. It is how an extension answers a request
+  now that requests get no automatic answer (see the second **Breaking** entry
+  under Removed).
+
+### Removed
+
+- **Breaking:** the hop limit is gone entirely. There is no per-turn hop
+  count, `hops` is no longer written to new envelopes or part of the
+  supported envelope, `session_mail_send` and `session_mail_ask` are never
+  refused because of hops, and the `hopLimit` setting in `session-mail.json`
+  has no effect (no migration; `pruneAfterDays` is unchanged). No other loop
+  guard replaces it: sessions can keep waking each other, which is accepted.
+  An old stored envelope with a `hops` property is still read and delivered;
+  the property is ignored. The test that pinned the old behaviour changed with
+  it.
+- **Breaking:** a request (mail another extension sends through
+  `message:send`) no longer gets an automatic answer. The receiving session
+  sends no reply when the run settles, whether a `message:inbound` listener
+  took the request over or not, and whether the run completed, stopped or
+  failed or never read the request; a request is no longer held across a stop
+  and answered "took over" later. The extension that consumes a request now
+  owns its reply. A request is still stored, delivered and woken on as before,
+  keeps its `sent/` copy and shows in `/mailbox`. Its label no longer says the
+  final answer goes back automatically, and `session_mail_reply` now refuses a
+  request saying the extension that consumes it answers it. Asks are
+  unchanged. pi-squire's `delegate` relied on the automatic answer, so this
+  release and pi-squire must be upgraded together: the matching pi-squire
+  release sends its replies with `message:reply`. There is no version check,
+  capability negotiation or fallback answering, and mixing this release with
+  another pi-squire release is unsupported, with no particular failure
+  promised. The tests that pinned automatic request answers
+  changed with it: they now pin that no answer is sent, and the reply-delivery
+  tests write their replies directly.
+
 ## [0.5.0] - 2026-10-23
 
 ### Changed
@@ -188,7 +240,8 @@ author's dotfiles; the changes below are against that copy.
 - CI on Node 22.19 and 24: lint, typecheck, tests, and a check of the
   published file list.
 
-[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.2...v0.3.0

package/README.md

@@ -5,8 +5,10 @@ A file mailbox between Pi sessions on the same machine.
 Each Pi session gets an address and an inbox. You send a message to another
 running session with `/mailbox:send`, and the model lists, asks, answers and
 sends through four `session_mail_*` tools. Mail waits on disk until the
-recipient starts or resumes, and the recipient's final answer goes back to the
-sender automatically.
+recipient starts or resumes. An ask's answer goes back to its sender
+automatically; a request another extension sends through `message:send` gets
+no automatic answer, because the extension that consumes it owns its reply and
+sends it through `message:reply`.
 
 ## Install
 
@@ -60,9 +62,9 @@ and then typing the text:
 ```
 
 The sender sees `Sent <id> to <address>`. A message wakes the recipient's model
-and expects no answer. The model sends requests, asks and answers through the
-`session_mail_*` tools, and a request's last answer comes back to the sender as
-a reply when that run settles.
+and expects no answer. The model sends asks, messages and answers through the
+`session_mail_*` tools, and an ask's last answer comes back to the sender as a
+reply when that run settles.
 
 The footer shows `📬 N unread` while mail has reached this session but not yet
 entered its conversation, such as mail queued behind a busy run; it is hidden
@@ -95,18 +97,18 @@ quotes each request it answers, capped at 2 KiB each with the `sent/` copy's
 path, or the request's id alone when this session has no copy.
 
 When the recipient's agent settles, its last answer goes back to each sender as
-one reply listing the requests it answers. Each of the sender's asks not
-already answered with `session_mail_reply` gets a separate reply. The status is
-`done` normally, `stopped` when the user stopped the run (with the partial
-text), or `failed` when the run ended on an error (with the error and the
-partial text).
-
-A request is never answered `stopped`. When the user stops a run, the requests
-it read are held for the next run that completes, which answers them `done` and
-says the user took over (see [Delivery](#delivery)). A request the session was
-stopped before reading gets a `failed` reply instead. Replies and messages are
-never answered. The answer to an ask its sender is still waiting on becomes
-that sender's `session_mail_ask` result.
+one reply listing that sender's asks not already answered with
+`session_mail_reply`. The status is `done` normally, `stopped` when the user
+stopped the run (with the partial text), or `failed` when the run ended on an
+error (with the error and the partial text). An ask the session was stopped
+before reading gets a `failed` reply instead. The answer to an ask its sender
+is still waiting on becomes that sender's `session_mail_ask` result.
+
+A request gets no automatic answer: not when its run completes, stops or
+fails, not when the session never read it, and not when a `message:inbound`
+listener took it over. The extension that consumes it owns its reply, and
+sends it with the [`message:reply`](#messagereply) hook. Replies
+and messages are never answered.
 
 ## Running sessions
 
@@ -131,9 +133,9 @@ The model gets four tools:
 | Tool | Parameters | What it does |
 | --- | --- | --- |
 | `session_mail_list` | none | Lists every running session, in every agent directory: its name (or short id, the first 8 characters of its id, when it has no name), full id, working directory, idle or busy state and whom it is waiting on, and marks the calling session. |
-| `session_mail_ask` | `to`, `message` | Writes an ask (`kind: "ask"`). In a TUI session without `PI_UNATTENDED=1` it returns at once with outcome `background`, sets no `waitingOn`, and the answer arrives as a message. Everywhere else (print, JSON and RPC modes, and a TUI marked unattended, such as a pi-squire delegate) it waits for the answer, which is the result: its status and body, labelled as not an answer when the status is `stopped` or `failed`. The wait ends when the answer arrives, after 10 minutes ("no answer yet"), when the target's running record disappears ("stopped running"), or when the user stops the run; `waitingOn` is set while it waits and cleared in every case. Refused at once, writing nothing, when another ask of this session is waiting, when the target is not running, when the target is waiting on this session, at the [hop limit](#hop-limit), and when `to` does not resolve, is ambiguous or is this session. |
-| `session_mail_reply` | `ask`, `message` | Answers one open ask this session received, at once, with status `done` and the turn's hop count, without ending the run; the asker's `session_mail_ask` returns with it. The answer at settle then leaves that ask out, while the sender's other requests and asks are still answered. Refused, sending nothing, for an ask already answered (by this tool or at settle), for a request (answered at settle), a message or a reply, for an id that never reached this session, and for an empty text. |
-| `session_mail_send` | `to`, `message` | Writes a message (`kind: "message"`) and returns its id. To a running session it is delivered at once; to a closed session, by full id, it waits in that session's inbox and the result says so. Refused when `to` does not resolve, is ambiguous or is this session, when the text is empty, and at the [hop limit](#hop-limit). |
+| `session_mail_ask` | `to`, `message` | Writes an ask (`kind: "ask"`). In a TUI session without `PI_UNATTENDED=1` it returns at once with outcome `background`, sets no `waitingOn`, and the answer arrives as a message. Everywhere else (print, JSON and RPC modes, and a TUI marked unattended, such as a pi-squire delegate) it waits for the answer, which is the result: its status and body, labelled as not an answer when the status is `stopped` or `failed`. The wait ends when the answer arrives, after 10 minutes ("no answer yet"), when the target's running record disappears ("stopped running"), or when the user stops the run; `waitingOn` is set while it waits and cleared in every case. Refused at once, writing nothing, when another ask of this session is waiting, when the target is not running, when the target is waiting on this session, and when `to` does not resolve, is ambiguous or is this session. |
+| `session_mail_reply` | `ask`, `message` | Answers one open ask this session received, at once, with status `done`, without ending the run; the asker's `session_mail_ask` returns with it. The answer at settle then leaves that ask out, while the sender's other asks are still answered. Refused, sending nothing, for an ask already answered (by this tool or at settle), for a request (the extension that consumes it answers it), a message or a reply, for an id that never reached this session, and for an empty text. |
+| `session_mail_send` | `to`, `message` | Writes a message (`kind: "message"`) and returns its id. To a running session it is delivered at once; to a closed session, by full id, it waits in that session's inbox and the result says so. Refused when `to` does not resolve, is ambiguous or is this session, and when the text is empty. |
 
 ## Addressing
 
@@ -155,10 +157,10 @@ A `to` given to a tool resolves as follows:
 
 | Kind | Written by | Delivered as | Answered |
 | --- | --- | --- | --- |
-| `request` | `message:send` | `triggerTurn`, `deliverAs: "steer"` | yes, when a run completes; held while the user has taken over |
-| `ask` | `session_mail_ask` | `triggerTurn`, `deliverAs: "steer"` | yes, when the run settles |
+| `request` | `message:send` | `triggerTurn`, `deliverAs: "steer"` | never automatically; the extension that consumes it replies |
+| `ask` | `session_mail_ask` | `triggerTurn`, `deliverAs: "steer"` | yes, with `session_mail_reply` or when the run settles |
 | `message` | `session_mail_send`, `/mailbox:send` | `triggerTurn`, `deliverAs: "steer"` | never |
-| `reply` | the answering session | `deliverAs: "followUp"`, no turn; see below for answers to asks | never |
+| `reply` | the answering session: `session_mail_reply` or settle for an ask, `message:reply` for a request | `deliverAs: "followUp"`, no turn; see below for answers to asks | never |
 
 Mail for the model wakes an idle session, and reaches a busy one at its next
 gap between tool calls rather than after the run. It is never held back while
@@ -172,8 +174,8 @@ ask that is not waiting (a background ask, or one that timed out, that the
 user stopped, or whose session restarted) is delivered like a message: it
 starts a turn, and its label says the ask is not waiting for it. An
 unattended session waits rather than asking in the background because ending
-its turn ends its work: a delegate's settle is its result, and print mode
-exits.
+its turn ends its work: print mode exits, and an unattended TUI has no person
+to read a late answer.
 
 Every injected message opens with a neutral label: `[mailbox] From <name>
 (<full id>, working in <cwd>), another Pi session on this machine.` The short
@@ -182,7 +184,7 @@ sender is not running. The label carries no distrust wording. Safety stays
 outside the model: an owner-only mail root on one machine. The rest of the
 label depends on the kind:
 
-- A request's label says the final answer this turn goes back automatically.
+- A request's label is the sender line alone; it promises no answer.
 - An ask's label says its sender is waiting, gives the ask id and
   `session_mail_reply` as the way to answer, and says this run's last message
   is sent as the answer otherwise.
@@ -207,29 +209,22 @@ user message, and the Anthropic API joins it with the next typed prompt into
 one turn. A quiet reply starts no turn, so the user's next prompt lands right
 after it; without the end line, models read that prompt as part of the mail.
 
-Mail counts as read when it enters the conversation (`message_end`). A request
-an abort dropped before that is answered `failed`.
-
-A request the user stops a run on is held, not answered: stopping a run (Esc)
-means the user took over, not that the request is finished. Its sender sees no
-reply yet. It stays owed through further stopped runs and through runs that end
-on an error, and the next run that completes answers it `done`. That reply's
-body opens with `(The user stopped an earlier run partway and took over; the
-answer that follows is from the run that completed after that.)`, then that
-run's answer; the stopped runs' partial text is not included. Asks are never
-held, because their sender is blocked waiting: a stopped run answers them
-`stopped` at once. A held request lives in memory only, so a session that shuts
-down while holding one never answers it.
+Mail counts as read when it enters the conversation (`message_end`). An ask
+an abort dropped before that is answered `failed`. Asks are never held across a
+stop, because their sender is blocked waiting: a stopped run answers them
+`stopped` at once.
 
 ## Envelopes
 
-Every envelope is a JSON file with `id`, `from`, `to`, `kind`, `hops`,
+Every envelope is a JSON file with `id`, `from`, `to`, `kind`,
 `in_reply_to`, `status`, `ts` and `body`. `kind` is one of:
 
-- `request`, answered when the recipient settles.
+- `request`, mail another extension sends through `message:send`; the
+  extension that consumes it in the recipient answers it, if anything does.
 - `reply`, an answer that names what it answers in `in_reply_to`.
 - `message`, plain mail that expects no answer.
-- `ask`, a question whose sender waits for the answer, answered like a request.
+- `ask`, a question whose sender waits for the answer, answered with
+  `session_mail_reply` or when the recipient settles.
 
 A `kind` this version does not know is read as `message`: the envelope is
 delivered, wakes the session and expects no answer. The original value is not
@@ -240,42 +235,30 @@ An envelope whose `in_reply_to` names more than 50 requests (50 is allowed) is
 set aside with a warning, like any other envelope that cannot be read: it stays in `cur/`
 and is not delivered.
 
-`hops` is a non-negative integer counting how many times a chain of mail has
-woken or steered a session with no person typing (see
-[Hop limit](#hop-limit)). An envelope written before `kind` and `hops` existed
-is read as a reply when `in_reply_to` is non-empty and as a request otherwise,
-with hops 0.
+An envelope written before `kind` existed is read as a reply when `in_reply_to`
+is non-empty and as a request otherwise.
+
+There is no hop count or other limit on chains of mail: sessions can keep waking
+each other. An old envelope that still carries a `hops` property is read and
+delivered like any other, and the property is ignored.
 
-A reply's `status` says how the run ended, not whether the job succeeded.
-Requests, asks and messages carry no status.
+Requests, asks and messages carry no status. A reply's `status` is one of
+`done`, `stopped` and `failed`.
+
+The answer to an ask, from `session_mail_reply` (always `done`) or at settle,
+uses the status to say how the run ended, not whether the job succeeded, and
+`pi-session-mail` writes the body:
 
 | `status` | Meaning |
 | --- | --- |
-| `done` | the run settled; the body is its answer, opening with a note that the user took over when the request was held across a stop |
-| `stopped` | the user stopped the run before it settled; the body says so, then the partial text. Only asks are answered `stopped`; requests are held instead |
-| `failed` | the run did not do the job, and the body says why: either the run ended on an error (such as an API error Pi's retries gave up on), and the body gives the error, then the partial text; or the session was stopped before it read the request or ask, and nothing was done |
-
-## Hop limit
-
-Each session keeps a hop count for its current turn. It is 0 once the user
-starts or steers the turn: any Pi `input` event, whether typed, sent over RPC,
-or a prompt a command sent. Otherwise it is the highest `hops` plus one among
-the envelopes that started the turn or steered into it, requests and messages
-alike, and a reply a `message:inbound` listener took over. A reply shown
-quietly starts no turn and does not count. The count starts afresh when the
-run settles.
-
-`session_mail_send` and `session_mail_ask` stamp the count on their mail, and
-are refused before anything is written once the count has reached the limit (5
-unless `session-mail.json` says otherwise; see
-[Configuration](#configuration)). The refusal says that a person typing in
-either session starts the count again. Automatic answers carry the count and
-are never refused. A `message:send` is never refused at send time: its consumer
-acts for the user. Emitted while the session is idle it carries 0; during a run
-it carries that run's count, and the session that receives it counts it like
-any other mail, so a chain that reaches the limit is refused there as a loop.
-The limit is a loop guard, not a security boundary: a hand-written envelope
-can claim any `hops`.
+| `done` | the run settled; the body is its answer |
+| `stopped` | the user stopped the run before it settled; the body says so, then the partial text |
+| `failed` | the run did not do the job, and the body says why: either the run ended on an error (such as an API error Pi's retries gave up on), and the body gives the error, then the partial text; or the session was stopped before it read the ask, and nothing was done |
+
+A reply to a request is different: its consumer sets the status and the body
+through [`message:reply`](#messagereply), and `pi-session-mail` writes them as
+given. It adds no wording and waits for nothing. What `done`, `stopped` and
+`failed` mean for a request is for the consumer to define.
 
 ## Pruning
 
@@ -304,29 +287,30 @@ reports `Removed <N> mailbox folders of closed sessions`.
 (`PI_CODING_AGENT_DIR`, or `~/.pi/agent`), so each agent directory sets its own:
 
 ```json
-{ "hopLimit": 5, "pruneAfterDays": 30 }
+{ "pruneAfterDays": 30 }
 ```
 
 | Key | Effect |
 | --- | --- |
-| `hopLimit` | A positive integer: how many hops a chain of sessions waking each other may reach before `session_mail_send` and `session_mail_ask` are refused. Default 5. |
 | `pruneAfterDays` | A positive integer: how many days a closed session's mailbox folder is kept before it is [pruned](#pruning). Default 30. |
 
-The file is read at each send and at session start. A missing file, or one
+The file is read at session start. A missing file, or one
 without a key, means that key's default. An unreadable or invalid file, or an
-invalid value, also means the default (5 hops, 30 days), with one warning per
-session.
+invalid value, also means the default (30 days), with one warning per
+session. A key this version does not know, such as the former `hopLimit`, is ignored.
 
-The only environment variable it reads is the standard `XDG_STATE_HOME`, at
-every call, to place the mail root (see [How mail works](#how-mail-works)). It
-sets no environment variable of its own.
+It reads two environment variables: the standard `XDG_STATE_HOME`, at every
+call, to place the mail root (see [How mail works](#how-mail-works)), and
+`PI_UNATTENDED`, which `session_mail_ask` checks to tell whether a person is
+watching a TUI session (see [the tools](#running-sessions)). It sets no
+environment variable of its own.
 
 ## Hooks
 
 Other extensions integrate through the `pi.events` hooks below. They never
 import this package or read its files.
 
-`pi-session-mail` provides all three hooks and consumes none. All three depend
+`pi-session-mail` provides all four hooks and consumes none. All four depend
 on listeners doing all their work **synchronously**: the emitter reads the
 results off the payload the moment `emit` returns, so a listener must finish
 before its first `await`.
@@ -335,7 +319,9 @@ The `js` blocks below are the contract's worked examples, and
 `test/hooks.test.ts` extracts and runs them verbatim, one per block, on a real
 `createEventBus`. Their scope is the test harness's: `pi` is the extension
 API, `peer` is another session's address, `bareBus` is an event bus with no
-`message:send` provider, and `assert` is `node:assert/strict`. Write them as
+`message:send` provider, `peerPi` is the extension API of the session at
+`peer` (in the examples that need both ends), and `assert` is
+`node:assert/strict`. Write them as
 plain JavaScript so they stay runnable; the name after `js` is the test that
 runs that block.
 
@@ -352,18 +338,13 @@ refuse rather than pretend the message was sent.
 | --- | --- | --- |
 | `to` | consumer | the recipient's address: a session id |
 | `body` | consumer | the message text |
-| `envelope` | provider | the written request: `id`, `from`, `to`, `kind` (`"request"`), `hops` (the run's hop count during a run, `0` when idle), `in_reply_to`, `status`, `ts`, `body` |
+| `envelope` | provider | the written request: `id`, `from`, `to`, `kind` (`"request"`), `in_reply_to`, `status`, `ts`, `body` |
 | `error` | provider | why nothing was written: no active session, or an invalid `to` or `body` |
 
-While a run is active, between `agent_start` and `agent_settled`, the request
-carries that run's hop count (see [Hop limit](#hop-limit)), so two models that
-delegate to each other through an extension cannot escape the limit. While the
-session is idle it carries 0, as the example below does. The provider never
-refuses a send for its hop count; the receiving session refuses past the limit
-as a loop.
-
 The request's `id` is what a reply names in its `in_reply_to`, so a consumer
-that wants its answers back should keep it.
+that wants its answers back should keep it. `pi-session-mail` never answers a
+request by itself: the extension that consumes it in the recipient session
+sends any reply, through [`message:reply`](#messagereply).
 
 ```js message:send
 // Send a request from this session and keep the id a reply will name.
@@ -374,7 +355,7 @@ assert.equal(payload.error, undefined);
 assert.ok(payload.envelope, "a provider sets `envelope` before `emit` returns");
 assert.equal(typeof payload.envelope.id, "string");
 assert.equal(payload.envelope.kind, "request");
-assert.equal(payload.envelope.hops, 0);
+assert.equal("hops" in payload.envelope, false);
 ```
 
 ```js no-provider
@@ -385,10 +366,92 @@ assert.equal(probe.envelope, undefined);
 assert.equal(probe.error, undefined);
 ```
 
+### `message:reply`
+
+A consumer that took over a request emits `{ to, inReplyTo, body, status }` to
+answer it, whenever its work is done. A provider writes a reply (`kind:
+"reply"`) from its own session's address and sets `envelope` on the same
+object before `emit` returns, or sets `error` instead and writes nothing.
+**If neither is set, no provider is installed**, as with `message:send`.
+
+| Field | Set by | Meaning |
+| --- | --- | --- |
+| `to` | consumer | the request's sender: a session id, checked as `message:send` checks it |
+| `inReplyTo` | consumer | the ids of the requests this answers: a non-empty list of non-empty strings, at most 50 |
+| `body` | consumer | the reply text: any string, empty included |
+| `status` | consumer | required: `"done"`, `"stopped"` or `"failed"`; the consumer defines what each means for its request (see [Envelopes](#envelopes)) |
+| `envelope` | provider | the written reply: `id`, `from`, `to`, `kind` (`"reply"`), `in_reply_to`, `status`, `ts`, `body` |
+| `error` | provider | why nothing was written: no active session, an invalid field, or a failed write |
+
+The hook is for answering requests. The reply's `from` is always this
+session; a `from` on the payload is ignored. `body` and `status` are written
+exactly as given: the reply does not wait for the run to settle, does not use
+the model's answer and adds no wording. `inReplyTo` is checked for shape only:
+its ids are not looked up in this session's mailbox, so the hook does not
+check that they name requests this session received. Nothing stops a second
+reply to the same request either: every valid call writes one, and the
+consumer makes sure it answers once. An ask is answered with
+`session_mail_reply` or at settle, never through this hook, which leaves an
+ask's bookkeeping alone.
+
+The reply goes through the mailbox like any other: one the sender is not
+running to receive waits in its inbox and is claimed when it starts again.
+The sender then gets it through `message:inbound` with its `requests` copies,
+and a listener there can take it over.
+
+```js message:reply
+// The consumer in the peer session takes over the requests it receives.
+const taken = [];
+peerPi.events.on("message:inbound", (inbound) => {
+  if (inbound.handled || inbound.envelope.kind !== "request") return;
+  inbound.handled = true;
+  taken.push(inbound.envelope);
+});
+
+// This session sends a request, and the peer claims it now.
+const request = { to: peer, body: "Please run the test suite." };
+pi.events.emit("message:send", request);
+peerPi.events.emit("message:scan", {});
+assert.equal(taken.length, 1);
+
+// When its work is done, the consumer answers from the peer session.
+const reply = { to: taken[0].from, inReplyTo: [taken[0].id], body: "All 42 tests pass.", status: "done" };
+peerPi.events.emit("message:reply", reply);
+assert.equal(reply.error, undefined);
+assert.ok(reply.envelope, "a provider sets `envelope` before `emit` returns");
+assert.equal(reply.envelope.kind, "reply");
+assert.equal(reply.envelope.from, peer);
+
+// The reply reaches this session through `message:inbound`, unchanged.
+const replies = [];
+pi.events.on("message:inbound", (inbound) => replies.push(inbound));
+pi.events.emit("message:scan", {});
+assert.equal(replies.length, 1);
+const [{ envelope, requests }] = replies;
+assert.deepEqual(envelope.in_reply_to, [request.envelope.id]);
+assert.equal(envelope.body, "All 42 tests pass.");
+assert.equal(envelope.status, "done");
+assert.equal(requests[0].envelope.id, request.envelope.id);
+
+// Invalid input sets `error` and writes nothing.
+const unknown = { to: peer, inReplyTo: [request.envelope.id], body: "?", status: "maybe" };
+pi.events.emit("message:reply", unknown);
+assert.equal(unknown.envelope, undefined);
+assert.match(unknown.error, /status/);
+
+// With no provider installed, neither field is set.
+const probe = { to: peer, inReplyTo: [request.envelope.id], body: "hello", status: "done" };
+bareBus.emit("message:reply", probe);
+assert.equal(probe.envelope, undefined);
+assert.equal(probe.error, undefined);
+```
+
 ### `message:inbound`
 
 `pi-session-mail` emits this for every claimed envelope before injecting it,
-requests, messages and replies alike.
+requests, asks, messages and replies alike, except the reply to an ask this
+session is waiting on: that goes to the waiting `session_mail_ask` call as its
+result and is neither emitted nor injected.
 
 `pi-session-mail` never emits it from inside a `session_start` handler. Mail
 waiting when a session starts is claimed on a later event-loop turn
@@ -400,15 +463,16 @@ listener's handler. The watcher and the poll timer deliver later mail as usual.
 
 | Field | Meaning |
 | --- | --- |
-| `envelope` | the claimed envelope, with `from`, `kind`, `hops`, `in_reply_to`, `status`, `body` and the rest; an old envelope without `kind` or `hops` gets them filled in as described above |
+| `envelope` | the claimed envelope, with `from`, `kind`, `in_reply_to`, `status`, `body` and the rest; an old envelope without `kind` gets it filled in as described above |
 | `path` | the envelope's path in this session's `cur/` |
 | `requests` | a reply's `in_reply_to` requests found in this session's `sent/`, each as `{ envelope, path }`; empty for a request, and shorter than `in_reply_to` when a copy is missing |
 | `handled` | set to `true` by a listener that shows the message itself; `pi-session-mail` then injects nothing |
 
 A listener that sets `handled` owns the display, and chooses whether its own
-message starts a turn (`triggerTurn`). A request a listener handled still
-arms this session's reply and counts as read, so a takeover never leaves a
-sender without an answer. A reply `pi-session-mail` injects itself quotes each
+message starts a turn (`triggerTurn`). Handled mail counts as read, and an
+ask a listener handled is still answered when this session settles. A request
+arms no answer, handled or not: the listener that consumes it owns its reply. A
+reply `pi-session-mail` injects itself quotes each
 request the same way, capped at 2 KiB with the copy's path.
 
 ```js message:inbound
@@ -436,7 +500,9 @@ pi.events.on("message:inbound", (payload) => {
 A consumer emits `{}` to have `pi-session-mail` claim the mail waiting in its
 inbox now, instead of at the next watcher event or poll. The listener runs the
 inbox scan synchronously, so every waiting envelope has been emitted as
-`message:inbound` (and delivered) by the time `emit` returns, and then sets
+`message:inbound` (and delivered) by the time `emit` returns, except the
+reply to an ask this session is waiting on, which goes to the waiting
+`session_mail_ask` call instead. The listener then sets
 `scanned` to `true`. **If `scanned` is not set, no provider is installed**,
 and the consumer must not conclude that no reply is waiting.
 
@@ -469,21 +535,21 @@ assert.equal(probe.scanned, undefined);
 Sessions running older and newer copies of `pi-session-mail` share one mail
 root, and other extensions depend on its hooks, so these are stable:
 
-- The three hooks, `message:send`, `message:inbound` and `message:scan`, and
-  their payloads as [Hooks](#hooks) describes them.
+- The four hooks, `message:send`, `message:reply`, `message:inbound` and
+  `message:scan`, and their payloads as [Hooks](#hooks) describes them.
 - The `[mailbox] From …` label and the `[mailbox] End of the mail …` line that
   frame injected mail.
 - The mail root path, `$XDG_STATE_HOME/pi-session-mail/`, or
   `~/.local/state/pi-session-mail/` when `XDG_STATE_HOME` is unset or not
   absolute.
-- The envelope fields (`id`, `from`, `to`, `kind`, `hops`, `in_reply_to`,
+- The envelope fields (`id`, `from`, `to`, `kind`, `in_reply_to`,
   `status`, `ts`, `body`), the kinds (`request`, `reply`, `message`, `ask`)
   and a reply's statuses (`done`, `stopped`, `failed`); see
   [Envelopes](#envelopes).
 - The names of the tools (`session_mail_list`, `session_mail_send`,
   `session_mail_ask`, `session_mail_reply`) and of the `/mailbox`,
   `/mailbox:send` and `/mailbox:prune` commands.
-- The keys of `session-mail.json`, today `hopLimit` and `pruneAfterDays`.
+- The keys of `session-mail.json`, today `pruneAfterDays`.
 
 Changing any of them needs a major version from 1.0 on, and a minor version
 while the package is at 0.x.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-session-mail",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "A file mailbox between Pi sessions on the same machine",
 	"keywords": [
 		"pi-package",

package/src/config.ts

@@ -1,14 +1,11 @@
 // The settings in `<agent dir>/session-mail.json`, parsed from its text.
 // Pure: reading the file is the caller's job, so this module imports nothing.
 
-/** The hop limit when `session-mail.json` is missing or broken. */
-export const DEFAULT_HOP_LIMIT = 5;
-
 /** Days a closed session's mailbox folder is kept before it is pruned. */
 export const DEFAULT_PRUNE_AFTER_DAYS = 30;
 
 /** The settings, each valid or its default, and what was wrong with the file, if anything. */
-export type Config = { hopLimit: number; pruneAfterDays: number; problems: string[] };
+export type Config = { pruneAfterDays: number; problems: string[] };
 
 const isPositiveInteger = (value: unknown): value is number =>
 	typeof value === "number" && Number.isInteger(value) && value >= 1;
@@ -20,9 +17,9 @@ const isPositiveInteger = (value: unknown): value is number =>
  * every default and one problem.
  */
 export function parseConfig(text: string | undefined, path: string): Config {
-	const defaults = { hopLimit: DEFAULT_HOP_LIMIT, pruneAfterDays: DEFAULT_PRUNE_AFTER_DAYS };
+	const defaults = { pruneAfterDays: DEFAULT_PRUNE_AFTER_DAYS };
 	if (text === undefined) return { ...defaults, problems: [] };
-	const using = `using the hop limit ${DEFAULT_HOP_LIMIT} and pruning after ${DEFAULT_PRUNE_AFTER_DAYS} days`;
+	const using = `using the default, pruning after ${DEFAULT_PRUNE_AFTER_DAYS} days`;
 	let config: unknown;
 	try {
 		config = JSON.parse(text);
@@ -31,16 +28,16 @@ export function parseConfig(text: string | undefined, path: string): Config {
 	}
 	if (typeof config !== "object" || config === null || Array.isArray(config))
 		return { ...defaults, problems: [`${path} is not a JSON object; ${using}`] };
-	const values = config as { hopLimit?: unknown; pruneAfterDays?: unknown };
+	const values = config as { pruneAfterDays?: unknown };
 	const problems: string[] = [];
-	const read = (key: "hopLimit" | "pruneAfterDays"): number => {
-		const value = values[key];
-		if (value === undefined) return defaults[key];
-		if (isPositiveInteger(value)) return value;
-		problems.push(`${key} in ${path} must be a positive integer, not ${JSON.stringify(value)}; using ${defaults[key]}`);
-		return defaults[key];
-	};
-	const hopLimit = read("hopLimit");
-	const pruneAfterDays = read("pruneAfterDays");
-	return { hopLimit, pruneAfterDays, problems };
+	const value = values.pruneAfterDays;
+	let pruneAfterDays = defaults.pruneAfterDays;
+	if (value !== undefined) {
+		if (isPositiveInteger(value)) pruneAfterDays = value;
+		else
+			problems.push(
+				`pruneAfterDays in ${path} must be a positive integer, not ${JSON.stringify(value)}; using ${defaults.pruneAfterDays}`,
+			);
+	}
+	return { pruneAfterDays, problems };
 }

package/src/index.ts

@@ -13,15 +13,16 @@
 // expects no answer. Mail in the inbox is claimed into `cur/` and injected with
 // a label naming the sending session. Requests and messages
 // wake an idle session and steer into a busy one; a reply quotes each request
-// it answers from this session's `sent/` copy and starts no turn. When the recipient settles, its
-// last answer goes back to each sender as one reply — `done` normally, or
-// `stopped` when the user stopped the run, with any partial text, or `failed`
-// when the run ended on an error, with the error and any partial text. A
-// request is never answered `stopped`: a run the user stopped holds it, owed,
-// until a run completes, and that answer says the user took over. Requests
-// that never entered the conversation (an abort drops queued follow-ups) get
-// a `failed` reply instead. Replies and messages are never answered. Other extensions use
-// `pi.events` (below).
+// it answers from this session's `sent/` copy and starts no turn. A request
+// gets no automatic answer: the extension that consumes it owns its reply and
+// sends it through `message:reply`. An
+// ask not answered with `session_mail_reply` is answered when the recipient
+// settles, its last answer going back to each sender as one reply — `done`
+// normally, `stopped` when the user stopped the run, with any partial text, or
+// `failed` when the run ended on an error, with the error and any partial
+// text. Asks that never entered the conversation (an abort drops queued
+// follow-ups) get a `failed` reply instead. Replies and messages are never
+// answered. Other extensions use `pi.events` (below).
 //
 // The hook contracts live in this package's README.
 import { type FSWatcher, statSync, watch } from "node:fs";
@@ -31,7 +32,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { mailStatus } from "./mail-status.ts";
 import { type Peer, type PickerFilter, type PickerItem, type PickResult, picker } from "./picker.ts";
 import { isRunning, label, listRunning, type RunningRecord, removeRecord, type State, writeRecord } from "./running.ts";
-import { type SettleInput, settle } from "./settle.ts";
+import { type SettleAsksInput, settleAsks } from "./settle.ts";
 import {
 	boxPath,
 	claim,
@@ -41,6 +42,7 @@ import {
 	findSent,
 	isAddress,
 	listNew,
+	MAX_REPLY_IDS,
 	pruneClosed,
 	readEnvelope,
 	readMailbox,
@@ -142,7 +144,6 @@ function inboundText(
 	const id = plain(envelope.id);
 	const replyIds = envelope.in_reply_to.map(plain);
 	const header = [sender.line];
-	if (envelope.kind === "request") header.push("Your final answer this turn goes back to it automatically.");
 	if (envelope.kind === "ask")
 		header.push(
 			`It is waiting for your answer to its ask ${id}. Answer with session_mail_reply (ask ${id}); otherwise this run's last message is sent as the answer.`,
@@ -167,20 +168,35 @@ function inboundText(
  * synchronous code before `emit` returns; do all work before any `await`.
  *
  * - `message:send`: the caller emits `{ to, body }`; `pi-session-mail` writes a
- *   request, stamped with the run's hop count during a run and 0 when idle,
- *   and sets `envelope` (or `error`) on the same object. Neither set means no
+ *   request and sets `envelope` (or `error`) on the same object. Neither set means no
  *   provider is installed.
  * - `message:inbound`: emitted for every claimed envelope, requests and
- *   replies alike, before injection; `requests` holds a reply's request
- *   copies from this session's `sent/`, and a listener sets `handled` to show
- *   the message itself.
+ *   replies alike, before injection, except the reply to an ask this session
+ *   is waiting on, which is the waiting tool call's result; `requests` holds
+ *   a reply's request copies from this session's `sent/`, and a listener sets
+ *   `handled` to show the message itself.
+ * - `message:reply`: the caller emits `{ to, inReplyTo, body, status }`;
+ *   `pi-session-mail` writes a reply from this session and sets `envelope`
+ *   (or `error`), as for `message:send`. It answers requests a consumer took
+ *   over; the ids are checked for shape only, never looked up.
  */
 const SEND = "message:send";
+const REPLY = "message:reply";
+/** The statuses a `message:reply` caller may give, the same as a settled ask's. */
+const REPLY_STATUSES: readonly string[] = ["done", "stopped", "failed"];
 const INBOUND = "message:inbound";
 /** A consumer's request to claim waiting mail now; see the README's `message:scan`. */
 const SCAN = "message:scan";
 
 type SendPayload = { to: unknown; body: unknown; envelope?: Envelope; error?: string };
+type ReplyPayload = {
+	to: unknown;
+	inReplyTo: unknown;
+	body: unknown;
+	status: unknown;
+	envelope?: Envelope;
+	error?: string;
+};
 type InboundPayload = { envelope: Envelope; path: string; requests: SentCopy[]; handled: boolean };
 
 type Message = { role?: string; content?: unknown; stopReason?: unknown; errorMessage?: unknown };
@@ -222,15 +238,8 @@ export default function mailbox(pi: ExtensionAPI) {
 	let timer: ReturnType<typeof setInterval> | undefined;
 	/** Envelope ids already handed to Pi in this process. */
 	const delivered = new Set<string>();
-	/** Request ids awaiting this session's reply, keyed by sender. In memory only. */
-	let owed = new Map<string, string[]>();
-	/** Owed request ids whose message entered the conversation (or a listener took over). */
+	/** Ids of mail whose message entered the conversation (or a listener took over); settle reads it for asks. */
 	let seen = new Set<string>();
-	/**
-	 * Request ids held across a stop: the user stopped a run while they were
-	 * owed, so they wait, still owed, for the next run that completes.
-	 */
-	let held = new Set<string>();
 	/** Text of the last assistant message, remembered at `agent_end`. */
 	let lastAnswer: string | undefined;
 	/** Whether the user stopped that run, whatever its last message's `stopReason`. */
@@ -239,12 +248,6 @@ export default function mailbox(pi: ExtensionAPI) {
 	let lastError: string | undefined;
 	/** Ids of injected mail that has not entered the conversation yet, for the status's unread count. */
 	let unread = new Set<string>();
-	/**
-	 * The hop count of the current turn: 0 once the user starts or steers it,
-	 * otherwise the highest `hops` + 1 among the envelopes that started or
-	 * steered into it. Mail sent from the turn carries it.
-	 */
-	let hops = 0;
 	/** The problems with `session-mail.json` this session has already warned about. */
 	let configWarned = new Set<string>();
 	/** What this session's running-session record says. */
@@ -395,13 +398,9 @@ export default function mailbox(pi: ExtensionAPI) {
 		// Listeners run synchronously inside emit, so `handled` is final when it returns.
 		const inbound: InboundPayload = { envelope, path, requests, handled: false };
 		pi.events.emit(INBOUND, inbound);
-		// Only requests arm an answer: replies are never answered, and messages
-		// expect none. A request arms one even when a listener took over its display.
-		if (envelope.kind === "request") owed.set(envelope.from, [...(owed.get(envelope.from) ?? []), envelope.id]);
+		// Only asks arm an answer: the extension that consumes a request owns its
+		// reply, replies are never answered, and messages expect none.
 		tools?.armAsk(envelope);
-		// Mail that wakes or steers the session raises its count; a reply shown
-		// quietly starts no turn, but one a listener took over may.
-		if (wakes || inbound.handled) hops = Math.max(hops, envelope.hops + 1);
 		// `pi-session-mail` cannot observe a listener's own message, so a takeover counts as seen.
 		if (inbound.handled) {
 			seen.add(envelope.id);
@@ -458,11 +457,32 @@ export default function mailbox(pi: ExtensionAPI) {
 		try {
 			if (address === undefined) throw new Error("no active session has a mailbox address");
 			if (typeof payload.body !== "string") throw new Error("body must be a string");
-			// During a run the caller is the model acting through an extension, so the
-			// request continues the run's chain; idle, it acts for the user and starts a
-			// fresh one. It is never refused here: the receiving side enforces the limit.
-			const hopsNow = state === "busy" ? hops : 0;
-			payload.envelope = send(address, payload.to as string, payload.body, { kind: "request", hops: hopsNow });
+			payload.envelope = send(address, payload.to as string, payload.body, { kind: "request" });
+		} catch (err) {
+			payload.error = (err as Error).message;
+		}
+	});
+
+	// Synchronous on purpose, like `message:send`. The reply is written as the
+	// caller gives it, now: no settle, no assistant text, no added wording, and
+	// no lookup or duplicate guard on `inReplyTo`; the consumer owns all that.
+	pi.events.on(REPLY, (data) => {
+		const payload = data as ReplyPayload;
+		if (typeof payload !== "object" || payload === null) return;
+		try {
+			if (address === undefined) throw new Error("no active session has a mailbox address");
+			const ids = payload.inReplyTo;
+			if (!Array.isArray(ids) || ids.length === 0 || !ids.every((id) => typeof id === "string" && id !== ""))
+				throw new Error("inReplyTo must be a non-empty list of non-empty request ids");
+			if (ids.length > MAX_REPLY_IDS) throw new Error(`inReplyTo names more than ${MAX_REPLY_IDS} requests`);
+			if (typeof payload.body !== "string") throw new Error("body must be a string");
+			if (typeof payload.status !== "string" || !REPLY_STATUSES.includes(payload.status))
+				throw new Error(`status must be one of ${REPLY_STATUSES.map((s) => JSON.stringify(s)).join(", ")}`);
+			payload.envelope = send(address, payload.to as string, payload.body, {
+				kind: "reply",
+				inReplyTo: [...ids],
+				status: payload.status,
+			});
 		} catch (err) {
 			payload.error = (err as Error).message;
 		}
@@ -497,14 +517,11 @@ export default function mailbox(pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, context) => {
 		stop();
 		ctx = context;
-		owed = new Map();
 		seen = new Set();
-		held = new Set();
 		lastAnswer = undefined;
 		lastAborted = false;
 		lastError = undefined;
 		unread = new Set();
-		hops = 0;
 		tools?.abandonAsk();
 		waitingOn = "";
 		configWarned = new Set();
@@ -563,12 +580,6 @@ export default function mailbox(pi: ExtensionAPI) {
 		if (unread.delete(message.details.id)) updateStatus();
 	});
 
-	// Typed text, RPC input and a prompt a command sends all come from the
-	// user, so each starts the chain again.
-	pi.on("input", async () => {
-		hops = 0;
-	});
-
 	pi.on("session_info_changed", async (event) => {
 		name = event.name || undefined;
 		announce();
@@ -606,24 +617,12 @@ export default function mailbox(pi: ExtensionAPI) {
 	// queued follow-up after `agent_end` would otherwise get a premature answer.
 	pi.on("agent_settled", async () => {
 		const me = address;
-		// Answers carry the settled turn's count; the next turn counts afresh.
-		const answerHops = hops;
-		hops = 0;
-		const end: SettleInput["end"] = lastAborted
+		const end: SettleAsksInput["end"] = lastAborted
 			? { kind: "stopped" }
 			: lastError !== undefined
 				? { kind: "failed", error: lastError }
 				: { kind: "done" };
-		const decision = settle({
-			requests: owed,
-			asks: tools?.takeOwedAsks() ?? new Map(),
-			seen,
-			held,
-			end,
-			answer: lastAnswer,
-		});
-		owed = decision.owed;
-		held = decision.held;
+		const replies = settleAsks({ asks: tools?.takeOwedAsks() ?? new Map(), seen, end, answer: lastAnswer });
 		seen = new Set();
 		lastAnswer = undefined;
 		lastAborted = false;
@@ -632,11 +631,10 @@ export default function mailbox(pi: ExtensionAPI) {
 		state = "idle";
 		announce();
 		if (me === undefined) return;
-		for (const reply of decision.replies) {
+		for (const reply of replies) {
 			const { to } = reply;
 			try {
-				// Answers are never refused by the hop limit.
-				send(me, to, reply.body, { kind: "reply", hops: answerHops, inReplyTo: reply.ids, status: reply.status });
+				send(me, to, reply.body, { kind: "reply", inReplyTo: reply.ids, status: reply.status });
 			} catch (err) {
 				warn(`could not reply to ${to}: ${(err as Error).message}`);
 			}
@@ -663,8 +661,6 @@ export default function mailbox(pi: ExtensionAPI) {
 			waitingOn = to;
 			announce();
 		},
-		hops: () => hops,
-		configProblem,
 	});
 
 	pi.registerCommand("mailbox", {
@@ -721,7 +717,7 @@ export default function mailbox(pi: ExtensionAPI) {
 			const text = (await context.ui.input("Message", "type a message"))?.trim();
 			if (text === undefined || text === "") return;
 			try {
-				const envelope = send(me, target.address, text, { kind: "message", hops: 0 });
+				const envelope = send(me, target.address, text, { kind: "message" });
 				context.ui.notify(`Sent ${envelope.id} to ${envelope.to}`, "info");
 			} catch (err) {
 				context.ui.notify(`mailbox: ${(err as Error).message}`, "error");

package/src/settle.ts

@@ -1,30 +1,28 @@
-export type SettleInput = {
-	requests: ReadonlyMap<string, string[]>;
+/** What a settle decides on: the open asks, the ids seen, how the run ended and the answer text it left. */
+export type SettleAsksInput = {
 	asks: ReadonlyMap<string, string[]>;
 	seen: ReadonlySet<string>;
-	held: ReadonlySet<string>;
 	end: { kind: "done" } | { kind: "stopped" } | { kind: "failed"; error: string };
 	answer: string | undefined;
 };
 export type Reply = { to: string; ids: string[]; body: string; status: "done" | "stopped" | "failed" };
-export type SettleOutput = { replies: Reply[]; owed: Map<string, string[]>; held: Set<string> };
 
 /** Reply body when the run ended with no assistant text. */
 export const NO_ANSWER = "(The session settled with no answer text.)";
 /** Reply body of a run the user stopped, with any partial answer text after it. */
 export const STOPPED = "(The user stopped this run before it finished; the text that follows, if any, is partial.)";
-/** Opening line of the reply body to a request held across a stop, before the answer of the run that completed it. */
-export const TOOK_OVER =
-	"(The user stopped an earlier run partway and took over; the answer that follows is from the run that completed after that.)";
 /** Opening line of the reply body of a run that ended on an error. */
 export const ERRORED = (error: string): string =>
 	`(The run ended on an error before it finished: ${error}. The text that follows, if any, is partial.)`;
-/** Body of a `failed` reply to requests that never entered the conversation. */
+/** Body of a `failed` reply to asks that never entered the conversation. */
 export const UNSEEN =
 	"(The session was stopped before it read the message. Nothing was done; send it again if it is still needed.)";
 
 /** The body and status of the reply to a run that ended this way: how it ended, then what it had. */
-function describeEnd(end: SettleInput["end"], answer: string | undefined): { body: string; status: Reply["status"] } {
+function describeEnd(
+	end: SettleAsksInput["end"],
+	answer: string | undefined,
+): { body: string; status: Reply["status"] } {
 	const text = answer ?? NO_ANSWER;
 	const withOpening = (opening: string): string => (answer === undefined ? opening : `${opening}\n\n${answer}`);
 	if (end.kind === "stopped") return { body: withOpening(STOPPED), status: "stopped" };
@@ -32,12 +30,14 @@ function describeEnd(end: SettleInput["end"], answer: string | undefined): { bod
 	return { body: text, status: "done" };
 }
 
-/** The replies to the asks: read ones get the run's answer, the rest fail as unseen. */
-function askReplies(
-	asks: SettleInput["asks"],
-	seen: SettleInput["seen"],
-	run: Pick<Reply, "body" | "status">,
-): Reply[] {
+/**
+ * The replies to the open asks when a run settles: read ones get the run's
+ * answer, the rest fail as unseen. Asks are never held across a stop, and
+ * requests are never answered here; the extension that consumes one owns its reply.
+ */
+export function settleAsks(input: SettleAsksInput): Reply[] {
+	const { asks, seen, end, answer } = input;
+	const run = describeEnd(end, answer);
 	const replies: Reply[] = [];
 	for (const [to, ids] of asks) {
 		const read = ids.filter((id) => seen.has(id));
@@ -47,36 +47,3 @@ function askReplies(
 	}
 	return replies;
 }
-
-/**
- * Decide the replies when a run settles, and which requests stay owed.
- *
- * A request the user stopped a run on is held: it stays owed, through stops
- * and failed runs alike, until a run completes, and is then answered "took
- * over". A request or ask never read is failed as unseen. Asks are never held;
- * their asker is blocked waiting.
- */
-export function settle(input: SettleInput): SettleOutput {
-	const { end, answer, seen, held: wasHeld } = input;
-	const stopped = end.kind === "stopped";
-	const failed = end.kind === "failed";
-	const { body, status } = describeEnd(end, answer);
-	const tookOverBody = `${TOOK_OVER}\n\n${answer ?? NO_ANSWER}`;
-	const replies: Reply[] = [];
-	const owed = new Map<string, string[]>();
-	const held = new Set<string>();
-	for (const [to, ids] of input.requests) {
-		const unseen = ids.filter((id) => !seen.has(id) && !wasHeld.has(id));
-		const keep = ids.filter((id) => !unseen.includes(id) && (stopped || (failed && wasHeld.has(id))));
-		const answered = ids.filter((id) => !unseen.includes(id) && !keep.includes(id));
-		if (keep.length > 0) owed.set(to, keep);
-		for (const id of keep) held.add(id);
-		const plain = answered.filter((id) => !wasHeld.has(id));
-		const tookOver = answered.filter((id) => wasHeld.has(id));
-		if (plain.length > 0) replies.push({ to, ids: plain, body, status });
-		if (tookOver.length > 0) replies.push({ to, ids: tookOver, body: tookOverBody, status: "done" });
-		if (unseen.length > 0) replies.push({ to, ids: unseen, body: UNSEEN, status: "failed" });
-	}
-	replies.push(...askReplies(input.asks, seen, { body, status }));
-	return { replies, owed, held };
-}

package/src/store.ts

@@ -12,7 +12,7 @@ import { dirname, isAbsolute, join } from "node:path";
 
 import { type MailFile, mailStatus } from "./mail-status.ts";
 
-/** What an envelope is: answered at settle, waited on, plain, or an answer. */
+/** What an envelope is: a request its consuming extension answers, an ask answered at settle, a plain message, or an answer. */
 export type Kind = "request" | "ask" | "message" | "reply";
 const KINDS: readonly Kind[] = ["request", "ask", "message", "reply"];
 
@@ -21,8 +21,6 @@ export type Envelope = {
 	from: string;
 	to: string;
 	kind: Kind;
-	/** How many times this chain of mail has woken or steered a session with no person typing. */
-	hops: number;
 	/** Request ids this envelope answers; empty for a request. */
 	in_reply_to: string[];
 	status: string;
@@ -36,7 +34,7 @@ const BOXES: Box[] = ["tmp", "new", "cur", "sent"];
 const ADDRESS = /^[A-Za-z0-9_-]+$/;
 
 /** The most requests one reply may name; an envelope over this is not read. */
-const MAX_REPLY_IDS = 50;
+export const MAX_REPLY_IDS = 50;
 
 /** An address is a single safe path segment: letters, digits, `-` and `_`. */
 export const isAddress = (value: unknown): value is string => typeof value === "string" && ADDRESS.test(value);
@@ -80,7 +78,7 @@ function stamp(): number {
 const fileName = (ms: number, id: string) => `${String(ms).padStart(15, "0")}-${id}.json`;
 
 /** How `send` writes an envelope. A reply names what it answers in `inReplyTo`. */
-export type SendOptions = { kind: Kind; hops: number; inReplyTo?: string[]; status?: string };
+export type SendOptions = { kind: Kind; inReplyTo?: string[]; status?: string };
 
 /**
  * Write an envelope to `to`'s inbox: into its `tmp/`, then renamed into its
@@ -94,7 +92,6 @@ export function send(from: string, to: string, body: string, options: SendOption
 	if (!isAddress(from)) throw new Error(`invalid sender address: ${JSON.stringify(from)}`);
 	if (!isAddress(to)) throw new Error(`invalid address: ${JSON.stringify(to)} (expected a session id)`);
 	if (!KINDS.includes(options.kind)) throw new Error(`invalid kind: ${JSON.stringify(options.kind)}`);
-	if (!isHops(options.hops)) throw new Error(`invalid hops: ${JSON.stringify(options.hops)}`);
 	const inReplyTo = options.inReplyTo ?? [];
 	const ms = stamp();
 	const envelope: Envelope = {
@@ -102,7 +99,6 @@ export function send(from: string, to: string, body: string, options: SendOption
 		from,
 		to,
 		kind: options.kind,
-		hops: options.hops,
 		in_reply_to: inReplyTo,
 		status: options.kind === "reply" ? (options.status ?? "done") : "",
 		ts: new Date(ms).toISOString(),
@@ -179,8 +175,6 @@ export function claim(address: string, name: string): string | null {
 /** A request's copy in its sender's `sent/`, with its path. */
 export type SentCopy = { envelope: Envelope; path: string };
 
-const isHops = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 0;
-
 /** The request ids an envelope answers; throws when the list is not a short list of strings. */
 function replyIds(value: unknown): string[] {
 	if (!Array.isArray(value) || !value.every((id) => typeof id === "string"))
@@ -191,8 +185,8 @@ function replyIds(value: unknown): string[] {
 
 /**
  * Parse an envelope value; throws when it is not a well-formed envelope from a
- * valid address. An envelope written before `kind` and `hops` existed is read
- * as a reply when it answers something and as a request otherwise, with hops 0.
+ * valid address. An envelope written before `kind` existed is read as a reply
+ * when it answers something and as a request otherwise.
  * A `kind` this version does not know is read as `message`, so mail from a
  * newer copy is delivered rather than stranded; the original value is dropped.
  */
@@ -206,8 +200,6 @@ function parseEnvelope(value: unknown): Envelope {
 	if (typeof envelope.body !== "string") throw new Error("missing body");
 	if (envelope.kind === undefined) envelope.kind = envelope.in_reply_to.length > 0 ? "reply" : "request";
 	else if (!KINDS.includes(envelope.kind)) envelope.kind = "message";
-	if (envelope.hops === undefined) envelope.hops = 0;
-	else if (!isHops(envelope.hops)) throw new Error(`invalid hops ${JSON.stringify(envelope.hops)}`);
 	return envelope as Envelope;
 }
 

package/src/tools.ts

@@ -8,29 +8,23 @@
 // `session_mail_ask` leaves an ask. In a session a person is watching it
 // returns at once and the answer arrives as a message; elsewhere it waits, one
 // at a time, for the answer, which comes back as its result. An unattended
-// session must wait because ending its turn ends its work: a delegate's settle
-// is its result, and print mode exits.
+// session must wait because ending its turn ends its work: print mode exits,
+// and an unattended TUI has no person to read a late answer.
 // `session_mail_reply` answers an ask this session received, mid-run; the asks
 // this session owes, and the kind of every envelope it has received, are kept
-// here for it. Mail a
-// tool sends carries the turn's hop count and is refused once the count
-// reaches `hopLimit` from `<agent dir>/session-mail.json`.
+// here for it.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { DEFAULT_HOP_LIMIT, DEFAULT_PRUNE_AFTER_DAYS, parseConfig } from "./config.ts";
+import { DEFAULT_PRUNE_AFTER_DAYS, parseConfig } from "./config.ts";
 import { label, listRunning, type RunningRecord, resolveTo } from "./running.ts";
 import { type Envelope, send } from "./store.ts";
 
 /** What the tools need from the extension around them. */
 export type ToolHooks = {
-	/** The current turn's hop count, which mail sent now carries. */
-	hops: () => number;
-	/** Report a broken `session-mail.json`; the extension shows one warning per session. */
-	configProblem: (message: string) => void;
 	/** The address this session's ask now waits on, or "" when it waits on none; written to its running record. */
 	waitingOn: (address: string) => void;
 };
@@ -92,7 +86,7 @@ function askText(ask: Envelope, target: string, outcome: AskOutcome): string {
 
 /** Why `session_mail_reply` refuses mail that is not an ask, by the kind of that mail. */
 const NOT_AN_ASK: Record<Exclude<Envelope["kind"], "ask">, string> = {
-	request: "A request is answered automatically when this run settles.",
+	request: "A request is answered by the extension that consumes it, not by this tool.",
 	message: "A message expects no answer; session_mail_send sends one if it is wanted.",
 	reply: "A reply is never answered.",
 };
@@ -101,7 +95,7 @@ const NOT_AN_ASK: Record<Exclude<Envelope["kind"], "ask">, string> = {
  * The settings from `<agent dir>/session-mail.json`, read at each call; each
  * problem goes to `onProblem`, which the extension shows once per session.
  */
-export function readSettings(onProblem: (message: string) => void): { hopLimit: number; pruneAfterDays: number } {
+export function readSettings(onProblem: (message: string) => void): { pruneAfterDays: number } {
 	const path = join(getAgentDir(), "session-mail.json");
 	let text: string | undefined;
 	try {
@@ -109,7 +103,7 @@ export function readSettings(onProblem: (message: string) => void): { hopLimit:
 	} catch (err) {
 		if ((err as NodeJS.ErrnoException).code !== "ENOENT")
 			onProblem(
-				`could not read ${path} (${(err as Error).message}); using the hop limit ${DEFAULT_HOP_LIMIT} and pruning after ${DEFAULT_PRUNE_AFTER_DAYS} days`,
+				`could not read ${path} (${(err as Error).message}); using the default, pruning after ${DEFAULT_PRUNE_AFTER_DAYS} days`,
 			);
 		text = undefined;
 	}
@@ -118,15 +112,6 @@ export function readSettings(onProblem: (message: string) => void): { hopLimit:
 	return settings;
 }
 
-/** Refuse, before anything is written, once the turn's hop count has reached the limit. */
-function checkHops(hops: number, hooks: ToolHooks): void {
-	const limit = readSettings(hooks.configProblem).hopLimit;
-	if (hops < limit) return;
-	throw new Error(
-		`nothing was sent: this turn is ${hops} hops into a chain of sessions waking each other with nobody typing, and the hop limit of ${limit} is reached. A person typing in either session starts the count again.`,
-	);
-}
-
 /**
  * The one result every tool returns. `structuredContent` is what codemode scripts
  * receive; it must match the tool's `outputSchema`, which Pi does not check.
@@ -203,7 +188,7 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 	let waiting: WaitingAsk | undefined;
 	/** The kind of each envelope this session has claimed, by id, so a reply can say why it is refused. */
 	const receivedKinds = new Map<string, Envelope["kind"]>();
-	/** Ask ids awaiting this session's answer, keyed by sender; answered apart from requests. */
+	/** Ask ids awaiting this session's answer, keyed by sender. */
 	let owedAsks = new Map<string, string[]>();
 	/** This session's address as the extension last set it; undefined when it has none. */
 	let address: string | undefined;
@@ -219,8 +204,7 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 		const from = [...owedAsks].find(([, ids]) => ids.includes(id))?.[0];
 		// An answered ask, by this tool or at settle, is no longer owed.
 		if (from === undefined) throw new Error(`ask ${id} is already answered; nothing was sent`);
-		// Answers carry the turn's count and are never refused by the hop limit.
-		const answer = send(me, from, body, { kind: "reply", hops: hooks.hops(), inReplyTo: [id], status: "done" });
+		const answer = send(me, from, body, { kind: "reply", inReplyTo: [id], status: "done" });
 		const rest = (owedAsks.get(from) ?? []).filter((owedId) => owedId !== id);
 		if (rest.length > 0) owedAsks.set(from, rest);
 		else owedAsks.delete(from);
@@ -287,9 +271,7 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 			const body = typeof params.message === "string" ? params.message.trim() : "";
 			if (body === "") throw new Error("the message is empty; nothing was sent");
 			const to = resolveTo(typeof params.to === "string" ? params.to : "", me);
-			const hops = hooks.hops();
-			checkHops(hops, hooks);
-			const envelope = send(me, to, body, { kind: "message", hops });
+			const envelope = send(me, to, body, { kind: "message" });
 			const target = listRunning().find((record) => record.address === to);
 			const text =
 				target === undefined
@@ -340,9 +322,7 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 				throw new Error(
 					`nothing was sent: ${target} is waiting on an answer from this session, so asking it back would leave both waiting; answer it first`,
 				);
-			const hops = hooks.hops();
-			checkHops(hops, hooks);
-			const ask = send(me, to, body, { kind: "ask", hops });
+			const ask = send(me, to, body, { kind: "ask" });
 			const outcome: AskOutcome = attended(ctx)
 				? { outcome: "background" }
 				: await new Promise<AskOutcome>((resolve) => {
@@ -374,7 +354,7 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 		name: "session_mail_reply",
 		label: "Session mail: reply",
 		description:
-			"Answer an ask another Pi session sent this session, at once, without ending this run. The asker is waiting, and gets the message as the answer to its ask; the answer this run's last message would otherwise send is then skipped for that ask. `ask` is the ask id its label gives. Each ask is answered once; requests are answered automatically when the run settles, and messages expect no answer.",
+			"Answer an ask another Pi session sent this session, at once, without ending this run. The asker is waiting, and gets the message as the answer to its ask; the answer this run's last message would otherwise send is then skipped for that ask. `ask` is the ask id its label gives. Each ask is answered once; requests are answered by the extension that consumes them, and messages expect no answer.",
 		parameters: Type.Object({
 			ask: Type.String({ description: "The ask id, as given in the ask's label." }),
 			message: Type.String({ description: "The answer." }),