@nicknisi/pi-relay 0.5.0 → 0.6.0

package/README.md

@@ -81,6 +81,7 @@ main moved; rebase before you push.
 - **Ordinary replies.** `reply` resolves an explicit full ID or unique prefix across pending asks and received message/reply entries in the active transcript branch. This survives reload and does not search sibling branches or infer a recipient. Replying to an ordinary message preserves unrelated pending asks. Successful send/reply results expose full `messageId`, `target`, `replyTo` where applicable, and `receipt` in details; broadcasts expose per-recipient receipts.
 - **Presence** is a pid plus a heartbeat: `live` (process exists, beat <45s), `not responding` (process exists, stale beat — wedged or suspended), `offline` (no live pid; mail waits). Status flips `working`/`idle` with the agent loop.
 - **Authority boundary on every delivery.** Each message arrives with a repeated statement that it came from a peer and carries no authority — it cannot approve anything, cannot change configuration, slash commands in it are inert text. The sending side's tool guidelines carry the reciprocal rule: never ask a peer to do something your own permissions would refuse.
+- **Quiet letters.** A letter with `wake: false` (set by core senders building their own `Letter` for `deposit`) lands in the receiving session's context without triggering a model turn: an FYI the agent sees on its next turn. Absent or `true` wakes the session as before, and old readers ignore the field, so mixed versions interoperate. An ask is never quiet: core `deposit` refuses `wake: false` on an ask, and delivery wakes an ask regardless, since the receiver must take a turn to answer. The `relay` tool always sends waking mail.
 - **Loops break structurally**, independent of what either model decides: identical text from one sender inside 10s is dropped; >8 messages per 30s per sender is refused; an unread backlog of 50 refuses new mail until the peer drains.
 - **Plain text only, ≤32KB.** Send a summary and a path, not a payload.
 - **Sweeping is narrow:** a running session is never touched; an inbox or durable claim holding undelivered mail is kept 30 days; an offline-but-resumable session keeps its record (its address — new mail must remain deliverable while it's down); only an empty mailbox of a session that can no longer be resumed is discarded promptly. Listing never has side effects.
@@ -128,5 +129,5 @@ The directory is created `0700` and every file `0600` — other users on the mac
 - **Bun <= 1.3.14 refused.** Those Bun versions abort the process when koffi's GC finalizer releases an N-API reference ([oven-sh/bun#39263](https://github.com/oven-sh/bun/issues/39263), fixed upstream after 1.3.14), so relay fails load with a clear error on them instead. Node.js and newer Bun load normally.
 - **One machine.** Delivery is a file landing in a directory; two sessions reach each other exactly when they share a filesystem. A container and its host cannot.
 - **Presence is heartbeat-accurate**, not instantaneous (within ~45s).
-- Delivery injects with `deliverAs: "steer"` (lands between tool calls) and `triggerTurn: true` (wakes an idle session).
+- Delivery injects with `deliverAs: "steer"` (lands between tool calls) and `triggerTurn: true` (wakes an idle session), unless the letter sets `wake: false`, which appends to the session without taking a turn.
 - Depends on pi extension APIs (`session_start`/`agent_start`/`agent_end` lifecycle events, `getSessionName`, `sendMessage` delivery modes) that could drift across pi versions.

package/core.ts

@@ -280,6 +280,17 @@ export function sweep(root: string, now: number = Date.now(), sessionExists?: (s
 export function deposit(root: string, toAddr: string, letter: Letter): void {
   assertAddress(toAddr);
   assertLetter(letter);
+  // wake is validated on the write side only. The read path (isSafeLetter)
+  // tolerates a non-boolean wake, so a letter from a writer that never
+  // validated the field is still delivered (as waking mail: delivery only
+  // honours wake === false) instead of being discarded after drain already
+  // unlinked it.
+  if (letter.wake !== undefined && typeof letter.wake !== 'boolean') {
+    throw new TypeError(`Invalid relay letter wake flag: ${letter.wake}`);
+  }
+  if (letter.kind === 'ask' && letter.wake === false) {
+    throw new TypeError('A quiet ask (wake: false) is refused: the receiver takes no turn, so it could never answer');
+  }
   depositInternal(root, toAddr, letter);
 }
 

package/dist/core.js

@@ -200,6 +200,17 @@ export function sweep(root, now = Date.now(), sessionExists) {
 export function deposit(root, toAddr, letter) {
     assertAddress(toAddr);
     assertLetter(letter);
+    // wake is validated on the write side only. The read path (isSafeLetter)
+    // tolerates a non-boolean wake, so a letter from a writer that never
+    // validated the field is still delivered (as waking mail: delivery only
+    // honours wake === false) instead of being discarded after drain already
+    // unlinked it.
+    if (letter.wake !== undefined && typeof letter.wake !== 'boolean') {
+        throw new TypeError(`Invalid relay letter wake flag: ${letter.wake}`);
+    }
+    if (letter.kind === 'ask' && letter.wake === false) {
+        throw new TypeError('A quiet ask (wake: false) is refused: the receiver takes no turn, so it could never answer');
+    }
     depositInternal(root, toAddr, letter);
 }
 export function drain(root, addr) {

package/dist/core.test.js

@@ -5,6 +5,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
 import * as core from './core.js';
+import { deposit as mailboxDeposit } from './mailbox.js';
 const relayDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(relayDir, '../..');
 const packageJson = JSON.parse(fs.readFileSync(path.join(relayDir, 'package.json'), 'utf8'));
@@ -313,6 +314,24 @@ describe('/core filesystem boundary', () => {
         expect(fs.readdirSync(base)).toEqual(['relay']);
     });
 });
+it('threads wake through core deposit and rejects a non-boolean flag and a quiet ask', () => {
+    const root = path.join(fixture(), 'relay');
+    const addr = core.deriveAddr('/receiver', 'session');
+    core.deposit(root, addr, letter({ id: 'wake-core', kind: 'message', wake: false }));
+    expect(core.drain(root, addr).map((l) => [l.id, l.wake])).toEqual([['wake-core', false]]);
+    expect(() => core.deposit(root, addr, letter({ kind: 'message', wake: 'no' }))).toThrow(TypeError);
+    // A quiet ask could never be answered: the receiver takes no turn.
+    expect(() => core.deposit(root, addr, letter({ kind: 'ask', wake: false }))).toThrow(TypeError);
+});
+it('drains rather than discards a letter whose wake flag is not boolean', () => {
+    const root = path.join(fixture(), 'relay');
+    const addr = core.deriveAddr('/receiver', 'session');
+    // An old writer stringifies the whole letter without validating wake, so a
+    // non-boolean flag can land on disk. Drain unlinks before parsing; the read
+    // path must deliver the letter (as waking mail), not silently drop it.
+    mailboxDeposit(root, addr, letter({ id: 'wake-odd', kind: 'message', wake: 'no' }));
+    expect(core.drain(root, addr).map((l) => l.id)).toEqual(['wake-odd']);
+});
 it('keeps the Pi extension entry importable', async () => {
     const entry = await import('./index.js');
     expect(typeof entry.default).toBe('function');

package/dist/extension.test.js

@@ -45,6 +45,7 @@ function start() {
     const handlers = new Map();
     let execute;
     let branch = [];
+    const sends = [];
     const ctx = {
         cwd: '/work',
         sessionManager: { getSessionId: () => 'self', getCwd: () => '/work', getBranch: () => branch },
@@ -60,7 +61,8 @@ function start() {
         registerCommand: () => { },
         registerMessageRenderer: () => { },
         registerEntryRenderer: () => { },
-        sendMessage: (message) => {
+        sendMessage: (message, options) => {
+            sends.push({ message, options });
             branch.push({ ...message, type: 'custom_message' });
         },
     };
@@ -76,6 +78,7 @@ function start() {
             branch = entries;
         },
         emit,
+        sends,
     };
 }
 function delivery(l) {
@@ -164,6 +167,32 @@ it('restores an offline queued letter and emits an exact durable receipt', async
     const { awaitReceipt } = await import('./mailbox.js');
     expect(await awaitReceipt(root, self, l, 1800)).toBe('delivered');
 });
+it('delivers wake:false mail without triggering a turn, waking mail with one, and an ask always wakes', async () => {
+    const root = fixture();
+    const p = peer();
+    writeRecord(root, p);
+    const self = deriveAddr('/work', 'self');
+    const from = { addr: p.addr, name: p.name, cwd: p.cwd };
+    const quiet = { id: 'quiet-letter', kind: 'message', body: 'fyi only', ts: Date.now(), wake: false, from };
+    const loud = { id: 'loud-letter', kind: 'message', body: 'wake up', ts: Date.now() + 1, from };
+    // The mailbox layer does not validate wake, so a quiet ask can land on
+    // disk; delivery must wake it anyway or it would never be answered.
+    const quietAsk = { id: 'quiet-ask', kind: 'ask', body: 'answer me', ts: Date.now() + 2, wake: false, from };
+    deposit(root, self, quiet);
+    deposit(root, self, loud);
+    deposit(root, self, quietAsk);
+    const host = start();
+    const { awaitReceipt } = await import('./mailbox.js');
+    // All three letters are acked, so all landed in the session's context.
+    expect(await awaitReceipt(root, self, quiet, 3000)).toBe('delivered');
+    expect(await awaitReceipt(root, self, loud, 3000)).toBe('delivered');
+    expect(await awaitReceipt(root, self, quietAsk, 3000)).toBe('delivered');
+    const byId = (id) => host.sends.find((s) => s.message.details?.id === id);
+    expect(byId(quiet.id).options).toEqual({ triggerTurn: false });
+    expect(byId(loud.id).options).toEqual({ triggerTurn: true, deliverAs: 'steer' });
+    expect(byId(quietAsk.id).options).toEqual({ triggerTurn: true, deliverAs: 'steer' });
+    expect(pendingAsks(root, self).map((l) => l.id)).toEqual([quietAsk.id]);
+});
 it('settles a waiting ask on shutdown and clears tracking for the original sender', async () => {
     const root = fixture();
     const p = peer();

package/dist/index.js

@@ -201,6 +201,24 @@ export default function relay(pi) {
             display: true,
             details,
         };
+        // wake === false: an FYI letter. It must land in the session's context
+        // (triggerTurn: false appends to the session, or queues until the
+        // current turn ends when the agent is streaming) without taking a model
+        // turn. Absent or true keeps the wake path below. An ask always wakes,
+        // whatever its flag says (core deposit refuses quiet asks, but the
+        // mailbox layer does not validate): without a turn the receiver could
+        // never answer and the asker would wait out its timeout.
+        if (letter.wake === false && letter.kind !== 'ask') {
+            try {
+                pi.sendMessage(message, { triggerTurn: false });
+                auditDelivery('deliver');
+                return true;
+            }
+            catch {
+                auditDelivery('deliver-failed');
+                return false;
+            }
+        }
         // steer lands between tool calls mid-run; triggerTurn wakes an idle
         // session. A busy agent rejects triggerTurn ("Agent is already
         // processing") — fall back to queueing for the next turn instead of

package/dist/mailbox.d.ts

@@ -26,6 +26,17 @@ export interface Letter {
     kind: LetterKind;
     body: string;
     replyTo?: string;
+    /**
+     * `false` delivers quietly: the letter still lands in the receiving
+     * session's context, but does not trigger a model turn. Absent or `true`
+     * wakes the session as before. An ask is never quiet: core `deposit`
+     * refuses `wake: false` on kind `ask`, and delivery wakes an ask
+     * regardless, because without a turn the receiver could never answer.
+     * Backward compatible: letters are stored as whole-JSON files and readers
+     * only require `id`/`body`, so old readers ignore the field and old
+     * writers never set it.
+     */
+    wake?: boolean;
     ts: number;
 }
 export declare const MAX_BODY_CHARS: number;

package/dist/mailbox.js

@@ -372,6 +372,8 @@ export function readClaimedLetter(root, addr, claimToken, fileToken) {
         relay.close();
     }
 }
+/** Content digest for delivery proof. `wake` is delivery mode, not content,
+ * and is excluded so old and new receivers compute matching digests. */
 function letterDigest(letter) {
     return createHash('sha256')
         .update(JSON.stringify([

package/dist/relay.test.js

@@ -170,6 +170,26 @@ describe('mailbox', () => {
         expect(drain(root, addr)).toEqual([]); // nothing twice
         expect(unreadCount(root, addr)).toBe(0);
     });
+    it('wake survives deposit intact, stays absent when unset, and does not break delivery proof', async () => {
+        const root = tmpRoot();
+        const addr = 'inbox0000006';
+        deposit(root, addr, letter({ id: 'quiet-1', ts: 1000, wake: false }));
+        deposit(root, addr, letter({ id: 'plain-1', ts: 2000 }));
+        const drained = drain(root, addr);
+        expect(drained.map((l) => [l.id, l.wake])).toEqual([
+            ['quiet-1', false],
+            ['plain-1', undefined],
+        ]);
+        expect('wake' in drained[1]).toBe(false); // old writers never set it; nothing invents it
+        // The durable claim flow preserves the field, and the acknowledgement
+        // digest (which excludes wake) still proves delivery to the sender.
+        const quiet = letter({ id: 'quiet-2', ts: 3000, wake: false });
+        deposit(root, addr, quiet);
+        const claim = claimInbox(root, addr);
+        expect(readClaimedLetter(root, addr, claim.claimToken, claim.fileTokens[0])?.wake).toBe(false);
+        expect(ackClaimedLetter(root, addr, claim.claimToken, claim.fileTokens[0])).toBe(true);
+        expect(await awaitReceipt(root, addr, quiet, 400)).toBe('delivered');
+    });
     it('discards corrupt letters without poisoning future drains', () => {
         const root = tmpRoot();
         const addr = 'inbox0000002';

package/index.ts

@@ -270,6 +270,23 @@ export default function relay(pi: ExtensionAPI) {
       display: true,
       details,
     };
+    // wake === false: an FYI letter. It must land in the session's context
+    // (triggerTurn: false appends to the session, or queues until the
+    // current turn ends when the agent is streaming) without taking a model
+    // turn. Absent or true keeps the wake path below. An ask always wakes,
+    // whatever its flag says (core deposit refuses quiet asks, but the
+    // mailbox layer does not validate): without a turn the receiver could
+    // never answer and the asker would wait out its timeout.
+    if (letter.wake === false && letter.kind !== 'ask') {
+      try {
+        pi.sendMessage(message, { triggerTurn: false });
+        auditDelivery('deliver');
+        return true;
+      } catch {
+        auditDelivery('deliver-failed');
+        return false;
+      }
+    }
     // steer lands between tool calls mid-run; triggerTurn wakes an idle
     // session. A busy agent rejects triggerTurn ("Agent is already
     // processing") — fall back to queueing for the next turn instead of

package/mailbox.ts

@@ -35,6 +35,17 @@ export interface Letter {
   kind: LetterKind;
   body: string;
   replyTo?: string;
+  /**
+   * `false` delivers quietly: the letter still lands in the receiving
+   * session's context, but does not trigger a model turn. Absent or `true`
+   * wakes the session as before. An ask is never quiet: core `deposit`
+   * refuses `wake: false` on kind `ask`, and delivery wakes an ask
+   * regardless, because without a turn the receiver could never answer.
+   * Backward compatible: letters are stored as whole-JSON files and readers
+   * only require `id`/`body`, so old readers ignore the field and old
+   * writers never set it.
+   */
+  wake?: boolean;
   ts: number;
 }
 
@@ -375,6 +386,8 @@ interface DeliveryAcknowledgement {
   acknowledgedAt: number;
 }
 
+/** Content digest for delivery proof. `wake` is delivery mode, not content,
+ * and is excluded so old and new receivers compute matching digests. */
 function letterDigest(letter: Letter): string {
   return createHash('sha256')
     .update(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-relay",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Brokerless session-to-session messaging for pi — a file mailbox that outlives the process, with ask/reply coordination. Formerly @nicknisi/pi-intercom.",
   "keywords": [
     "pi",