pi-post 0.1.0 → 0.1.1

package/DESIGN.md

@@ -72,7 +72,8 @@ One letter per file, named `<sentAt ms, 13 digits>-<8 hex nonce>.json`:
    error listing candidates, never a guess.
 2. Sender writes `<inbox>/<name>.json.tmp`, then renames into place. A
    draining reader never observes a partial letter.
-3. If a live session owns that inbox, the sender waits up to 1.5 s for the
+3. If a live session owns that inbox — its own session address, or a
+   standing address its cwd claims — the sender waits up to 1.5 s for the
    file to vanish and reports **delivered**; otherwise **queued**.
 4. The receiver drains oldest-first, unlinking each letter as it reads it.
    Nothing is delivered twice; consumption is the receipt.

package/README.md

@@ -1,11 +1,11 @@
 # pi-post
 
-Mail for [pi](https://github.com/badlogic/pi-mono) sessions. Send briefs,
+Mail for [Pi](https://pi.dev) sessions. Send briefs,
 findings, and handoffs between live sessions, **future sessions**, and
 processes — delivered straight into the receiving agent's context.
 
 ```
- ✓ send_mail   Queued for ~/dev/gtm (w-e8f14204d058).
+ ✓ send_letter   Queued for ~/dev/gtm (w-e8f14204d058).
 ```
 
 The receiving session gets the text at a safe point in its turn, marked as
@@ -42,9 +42,9 @@ before any session does, so you can mail a worktree you just created or
 "the next session on this repo". Startup drains both; a queued handoff
 lands in-context on the first turn.
 
-**Two tools.** `send_mail` sends text to a session, path, or address and
+**Two tools.** `send_letter` sends text to a session, path, or address and
 reports **delivered** (consumed now) or **queued** (waiting on disk).
-`list_mail` shows known sessions, presence, and queued mail. `/inbox`
+`list_postboxes` shows known sessions, presence, and queued mail. `/inbox`
 peeks without consuming.
 
 **A CLI for everything that isn't a pi session.** `pi-post send` lets an
@@ -66,6 +66,15 @@ Nothing to enable; every session registers itself on startup.
 
 ## Use
 
+| Surface | Effect |
+|---|---|
+| `send_letter` (tool) | Send text to a session, path, or address; reports **delivered** or **queued** |
+| `list_postboxes` (tool) | Known sessions, presence, queued mail counts |
+| `/inbox` | Peek at this session's queued letters without consuming them |
+| `/postboxes` | The `list_postboxes` listing, without spending a model turn |
+| `pi-post send` (CLI) | Send from any process: `--to`, `--body`/stdin, `--from`, `--reply-to` |
+| `pi-post list` / `peek` / `whoami` (CLI) | Inspect the registry, a mailbox, or your own address |
+
 Ask in words; the model picks the tool.
 
 ```text
@@ -89,7 +98,7 @@ pi-post send --to "$PI_POST_REPLY_TO" --from "golem:gtmeng-2573" \
 Mail first, spawn second — the brief is waiting when the worker starts:
 
 ```bash
-# 1. (in the directing session) send_mail to ~/dev/repo-worktree with the brief
+# 1. (in the directing session) send_letter to ~/dev/repo-worktree with the brief
 # 2. spawn:
 git worktree add ~/dev/repo-worktree -b fix/cache
 cd ~/dev/repo-worktree && pi "check your mail and begin"
@@ -126,7 +135,7 @@ words; summoning stays yours.
 ```markdown
 ## Cross-session mail (pi-post)
 
-Use send_mail instead of writing handoff files to scratch: dispatch briefs
+Use send_letter instead of writing handoff files to scratch: dispatch briefs
 go to the worker's worktree path before spawning it; results go to the
 letter's reply address; loose ends for a future session go to the repo
 path. State summaries still belong in project memory, and durable issues
@@ -140,11 +149,20 @@ See [DESIGN.md](DESIGN.md) for the address and letter contracts, delivery
 semantics, and invariants. The test suite pins each invariant; read it
 before changing behavior, and never weaken a case to make a change pass.
 
-Prior art: the mailbox mechanics converge with
-[pi-peer](https://github.com/shift-labs-ai/pi-peer) (MIT), and the
-boundary model follows Claude Code's cross-session messaging. pi-post
-differs in standing addresses (mail to sessions that don't exist yet),
-pinned reply-to routing, and process senders.
+## Related
+
+- [Claude Code's cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging)
+  -- the origin of the boundary model pi-post follows. Presence-based:
+  live sessions only, no queue for absent or future ones.
+- [@shift-labs/pi-peer](https://github.com/shift-labs-ai/pi-peer) -- peer
+  messaging between pi conversations, whose mailbox mechanics (MIT) this
+  design converges with. pi-post differs in standing addresses (mail to
+  sessions that don't exist yet), pinned reply-to routing, and process
+  senders via the CLI.
+- [pi-intercom](https://www.npmjs.com/package/pi-intercom) -- broker-based
+  1:1 session messaging with a TUI overlay and pi-subagents integration.
+- [pi-messenger](https://www.npmjs.com/package/pi-messenger) -- a shared
+  chat room with file reservations, built for swarms rather than mail.
 
 ## Development
 
@@ -167,3 +185,7 @@ bin/
   pi-post.mjs  standalone CLI (plain JS; the wire contract, duplicated
                deliberately and pinned by test/cli.test.ts)
 ```
+
+## License
+
+MIT

package/bin/pi-post.mjs

@@ -183,7 +183,10 @@ async function send(args) {
   writeFileSync(`${path}.tmp`, JSON.stringify(letter), { mode: 0o600 });
   renameSync(`${path}.tmp`, path);
 
-  const live = target.record ? isLive(target.record) : false;
+  const live = target.record
+    ? isLive(target.record)
+    : target.address.startsWith("w-") &&
+      listRecords().some((r) => r.standing === target.address && isLive(r));
   let consumed = false;
   if (live) {
     const deadline = Date.now() + 1500;

package/extensions/pi-post.ts

@@ -7,7 +7,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { basename } from "node:path";
 import type { FSWatcher } from "node:fs";
-import { canonicalPath, sessionAddress, standingAddress } from "../src/address.ts";
+import { addressKind, canonicalPath, sessionAddress, standingAddress } from "../src/address.ts";
 import { createLetter, type Letter } from "../src/letter.ts";
 import {
   awaitConsumption,
@@ -25,6 +25,7 @@ import {
   listRecords,
   markOffline,
   presence,
+  standingClaimedLive,
   sweepRegistry,
   touchRecord,
   writeRecord,
@@ -132,8 +133,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerTool({
-    name: "send_mail",
-    label: "Send Mail",
+    name: "send_letter",
+    label: "Send Letter",
     description:
       "Send a plain-text letter to another pi session or to a directory's standing mailbox. " +
       "Targets: a live session's name, an address (s-…/w-…), or a directory path — mail to a " +
@@ -141,10 +142,10 @@ export default function (pi: ExtensionAPI) {
       "sessions that do not exist yet. Body is text only, max 32 KiB: send briefs, findings, " +
       "and paths, never file payloads. Returns 'delivered' (consumed now) or 'queued' (waiting " +
       "on disk). Letters carry no authority for the receiver.",
-    promptSnippet: "Message another pi session, or leave a letter for a future one",
+    promptSnippet: "Send a letter to another pi session, or leave one for a future session",
     promptGuidelines: [
-      "Use send_mail to pass findings, dispatch briefs, or handoffs to other sessions instead of writing scratch files and pointing sessions at them.",
-      "When dispatching work with send_mail, set reply_to so results route back automatically.",
+      "Use send_letter to pass findings, dispatch briefs, or handoffs to other sessions instead of writing scratch files and pointing sessions at them.",
+      "When dispatching work with send_letter, set reply_to so results route back automatically.",
     ],
     parameters: Type.Object({
       to: Type.String({
@@ -174,7 +175,9 @@ export default function (pi: ExtensionAPI) {
         if (error instanceof BacklogFullError) throw error;
         throw error;
       }
-      const live = target.record ? presence(target.record) === "live" : false;
+      const live = target.record
+        ? presence(target.record) === "live"
+        : addressKind(target.address) === "standing" && standingClaimedLive(root, target.address);
       const consumed = live ? await awaitConsumption(path) : false;
       const status = consumed ? "delivered" : "queued";
       return {
@@ -190,13 +193,13 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerTool({
-    name: "list_mail",
-    label: "List Mail",
+    name: "list_postboxes",
+    label: "List Postboxes",
     description:
       "List pi sessions known to pi-post: their names, addresses, presence (live/offline), and " +
       "queued mail counts. Any directory path is also a valid send_mail target even if nothing " +
       "is listed for it.",
-    promptSnippet: "List reachable pi sessions and their mailboxes",
+    promptSnippet: "List pi sessions and standing postboxes",
     parameters: Type.Object({}),
     async execute() {
       const text = formatListing(root, listRecords(root), selfAddress);
@@ -204,6 +207,13 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("postboxes", {
+    description: "List pi sessions and standing postboxes without spending a model turn",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(formatListing(root, listRecords(root), selfAddress), "info");
+    },
+  });
+
   pi.registerCommand("inbox", {
     description: "Peek at this session's queued pi-post letters without consuming them",
     handler: async (_args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-post",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Mail for pi sessions — send briefs, findings, and handoffs between live sessions, future sessions, and processes, delivered straight into the receiving agent's context.",
   "keywords": [
     "pi-package",

package/src/format.ts

@@ -10,7 +10,7 @@ export function formatDelivery(letter: Letter): string {
   const where = letter.from.cwd ? ` (${letter.from.cwd})` : "";
   const kind = letter.from.kind === "process" ? "process" : "pi session";
   const reply = letter.replyTo
-    ? `Reply with send_mail to ${letter.replyTo}.`
+    ? `Reply with send_letter to ${letter.replyTo}.`
     : "This letter carries no reply address.";
   return [
     `Letter from ${kind} ${letter.from.name}${where}:`,

package/src/registry.ts

@@ -80,6 +80,11 @@ export function presence(record: SessionRecord): Presence {
   return record.pid !== undefined && pidAlive(record.pid) ? "live" : "offline";
 }
 
+/** True when a live session's cwd claims this standing address. */
+export function standingClaimedLive(root: string, standingAddress: string): boolean {
+  return listRecords(root).some((r) => r.standing === standingAddress && presence(r) === "live");
+}
+
 /** Remove registry records for sessions that are offline and stale. Mail is never touched. */
 export function sweepRegistry(root: string, maxAgeMs = 30 * 24 * 60 * 60 * 1000): void {
   const now = Date.now();