@nicknisi/pi-relay 0.4.0 → 0.5.0

package/README.md

@@ -19,6 +19,26 @@ import { OutboundPolicy, claimInbox, deposit, deriveAddr, type Letter } from '@n
 
 The `@nicknisi/pi-relay/core` subpath exports a narrow record and alias registry, mailbox and ask/audit operations, presence and sweep utilities, policy guards and constants, and their public types. Filesystem-facing operations validate canonical relay addresses, aliases, claim tokens, and ask/message IDs before accessing the relay root; path constructors and raw persistence helpers remain internal. Core uses Node built-ins plus Koffi's prebuilt native bridge for descriptor-relative Unix syscalls; Pi and TUI remain optional peers, so core-only installations do not fetch them. The package root remains the pi extension entry point; import `/core` from plain Node services and CLIs.
 
+### Registering a non-Pi host
+
+A host that isn't a pi session (a supervisor, a CLI daemon) can join the relay so it shows in `list`, can be messaged by name, and can hold an alias:
+
+```ts
+import { claimAlias, heartbeat, register, unregister } from '@nicknisi/pi-relay/core';
+
+const { addr } = register(root, { sessionId, name: 'supervisor', cwd: process.cwd() }); // pid defaults to process.pid, status to 'idle'
+claimAlias(root, 'supervisor', addr, sessionId);
+const timer = setInterval(() => heartbeat(root, addr), 15_000); // optional patch: { status, name }
+// on shutdown:
+clearInterval(timer);
+unregister(root, addr);
+```
+
+- `register` writes the same `<addr>.json` record the extension writes. The address is derived from `cwd` + `sessionId`, so re-registering keeps the address and the original `startedAt`.
+- `heartbeat` refreshes `lastSeenAt` (and clears `offline`). Core runs no timers: the host must call it less than `HEARTBEAT_STALE_MS` (45 s) apart — every 15 s, like the extension — or it reads as `stalled`. It returns `null`, writing nothing, if the record is gone; it never re-creates an unregistered session.
+- `unregister` deletes the record (missing is fine). Unlike the extension's shutdown, which marks the session offline so queued mail stays addressable, the address stops existing.
+- An alias lives only as long as its record: `sweep` keeps aliases whose record exists and clears the rest, so an alias survives while the host keeps registered and is reclaimed by the next `sweep` after `unregister`.
+
 ### Durable core inbox claims
 
 A non-Pi consumer can atomically detach the current inbox with `claimInbox(root, addr)`. It receives only a stable `claimToken` and stable `fileTokens`, never filesystem paths. New deposits immediately land in a fresh inbox. `readClaimedLetter` reopens and validates a claimed letter without following links; after the consumer durably writes and `fsync`s its own journal, `ackClaimedLetter` atomically persists exact delivery proof in `<addr>.acks` before deleting the claimed file, or `requeueClaimedLetter` atomically returns it to the current inbox. `recoverInboxClaims` enumerates the same tokens after a process crash. All claim, read, ack, and requeue work is relative to pinned root/inbox/claim/ack descriptors, and empty completed claims are removed automatically. `sweep` removes proof more than seven days after acknowledgement, including for live sessions; proof never keeps an expired session's record alive. The destructive `drain` API does not acknowledge delivery.

package/core.ts

@@ -27,13 +27,16 @@ import {
 import {
   claimAlias as claimAliasInternal,
   clearAlias as clearAliasInternal,
+  deriveAddr,
   isValidAliasName as isValidAliasNameInternal,
   listAliases as listAliasesInternal,
   listRecords as listRecordsInternal,
   presenceOf as presenceOfInternal,
   readAlias as readAliasInternal,
   readRecord as readRecordInternal,
+  removeRecord,
   sweep as sweepInternal,
+  writeRecord,
   type AliasRecord,
   type Presence,
   type SessionRecord,
@@ -110,6 +113,14 @@ function assertLetter(letter: Letter): void {
   }
 }
 
+function assertNonEmptyString(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError(`Invalid relay ${label}: ${value}`);
+}
+
+function assertStatus(status: unknown): asserts status is SessionRecord['status'] {
+  if (status !== 'idle' && status !== 'working') throw new TypeError(`Invalid relay session status: ${status}`);
+}
+
 function isSafeLetter(letter: Letter): boolean {
   try {
     assertLetter(letter);
@@ -174,6 +185,70 @@ export function presenceOf(record: SessionRecord, now: number = Date.now()): Pre
   return presenceOfInternal(record, now);
 }
 
+/**
+ * Register (or re-register) a non-Pi host as a relay session. The address is
+ * derived from `cwd` + `sessionId`, so re-registering keeps it, along with the
+ * existing `startedAt`. The host must call `heartbeat` well inside
+ * `HEARTBEAT_STALE_MS`.
+ */
+export function register(
+  root: string,
+  input: { sessionId: string; name: string; cwd: string; pid?: number; status?: SessionRecord['status'] },
+): SessionRecord {
+  assertNonEmptyString(input.sessionId, 'session id');
+  assertNonEmptyString(input.name, 'session name');
+  assertNonEmptyString(input.cwd, 'session cwd');
+  const pid = input.pid ?? process.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new TypeError(`Invalid relay session pid: ${pid}`);
+  const status = input.status ?? 'idle';
+  assertStatus(status);
+  const addr = deriveAddr(input.cwd, input.sessionId);
+  const now = Date.now();
+  const record: SessionRecord = {
+    addr,
+    sessionId: input.sessionId,
+    name: input.name,
+    cwd: input.cwd,
+    pid,
+    startedAt: readRecord(root, addr)?.startedAt ?? now,
+    lastSeenAt: now,
+    status,
+  };
+  writeRecord(root, record);
+  return record;
+}
+
+/**
+ * Refresh a registered session's `lastSeenAt` (clearing `offline`), applying an
+ * optional status or name. Returns null, writing nothing, if no record exists.
+ */
+export function heartbeat(
+  root: string,
+  addr: string,
+  patch: { status?: SessionRecord['status']; name?: string } = {},
+): SessionRecord | null {
+  assertAddress(addr);
+  if (patch.status !== undefined) assertStatus(patch.status);
+  if (patch.name !== undefined) assertNonEmptyString(patch.name, 'session name');
+  const existing = readRecord(root, addr);
+  if (existing === null) return null;
+  const { offline: _offline, ...rest } = existing;
+  const record: SessionRecord = {
+    ...rest,
+    name: patch.name ?? rest.name,
+    status: patch.status ?? rest.status,
+    lastSeenAt: Date.now(),
+  };
+  writeRecord(root, record);
+  return record;
+}
+
+/** Delete a session's record. Aliases pointing at it are cleared by the next `sweep`. */
+export function unregister(root: string, addr: string): void {
+  assertAddress(addr);
+  removeRecord(root, addr);
+}
+
 export function readAlias(root: string, name: string): AliasRecord | null {
   assertAliasName(name);
   const alias = readAliasInternal(root, name);

package/dist/core.d.ts

@@ -7,6 +7,29 @@ export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, t
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
 export declare function listRecords(root: string): SessionRecord[];
 export declare function presenceOf(record: SessionRecord, now?: number): Presence;
+/**
+ * Register (or re-register) a non-Pi host as a relay session. The address is
+ * derived from `cwd` + `sessionId`, so re-registering keeps it, along with the
+ * existing `startedAt`. The host must call `heartbeat` well inside
+ * `HEARTBEAT_STALE_MS`.
+ */
+export declare function register(root: string, input: {
+    sessionId: string;
+    name: string;
+    cwd: string;
+    pid?: number;
+    status?: SessionRecord['status'];
+}): SessionRecord;
+/**
+ * Refresh a registered session's `lastSeenAt` (clearing `offline`), applying an
+ * optional status or name. Returns null, writing nothing, if no record exists.
+ */
+export declare function heartbeat(root: string, addr: string, patch?: {
+    status?: SessionRecord['status'];
+    name?: string;
+}): SessionRecord | null;
+/** Delete a session's record. Aliases pointing at it are cleared by the next `sweep`. */
+export declare function unregister(root: string, addr: string): void;
 export declare function readAlias(root: string, name: string): AliasRecord | null;
 export declare function listAliases(root: string): AliasRecord[];
 export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;

package/dist/core.js

@@ -1,6 +1,6 @@
 /** Pi-free relay registry, mailbox, and policy API for non-extension consumers. */
 import { ackClaimedLetter as ackClaimedLetterInternal, awaitReceipt as awaitReceiptInternal, claimInbox as claimInboxInternal, clearAsk as clearAskInternal, deposit as depositInternal, drain as drainInternal, pendingAsks as pendingAsksInternal, readAudit as readAuditInternal, readClaimedLetter as readClaimedLetterInternal, readIncomingAsk as readIncomingAskInternal, readOutgoingAsk as readOutgoingAskInternal, recoverInboxClaims as recoverInboxClaimsInternal, requeueClaimedLetter as requeueClaimedLetterInternal, resolveAskByRef as resolveAskByRefInternal, trackIncomingAsk as trackIncomingAskInternal, trackOutgoingAsk as trackOutgoingAskInternal, unreadCount as unreadCountInternal, watchInbox as watchInboxInternal, } from './mailbox.js';
-import { claimAlias as claimAliasInternal, clearAlias as clearAliasInternal, isValidAliasName as isValidAliasNameInternal, listAliases as listAliasesInternal, listRecords as listRecordsInternal, presenceOf as presenceOfInternal, readAlias as readAliasInternal, readRecord as readRecordInternal, sweep as sweepInternal, } from './registry.js';
+import { claimAlias as claimAliasInternal, clearAlias as clearAliasInternal, deriveAddr, isValidAliasName as isValidAliasNameInternal, listAliases as listAliasesInternal, listRecords as listRecordsInternal, presenceOf as presenceOfInternal, readAlias as readAliasInternal, readRecord as readRecordInternal, removeRecord, sweep as sweepInternal, writeRecord, } from './registry.js';
 export { MAX_BODY_CHARS, previewBody, } from './mailbox.js';
 export { BACKLOG_CAP, DEDUPE_WINDOW_MS, OutboundPolicy, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, inboundAccepts, } from './policy.js';
 export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, } from './registry.js';
@@ -47,6 +47,14 @@ function assertLetter(letter) {
         throw new TypeError(`Invalid relay letter timestamp: ${letter.ts}`);
     }
 }
+function assertNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new TypeError(`Invalid relay ${label}: ${value}`);
+}
+function assertStatus(status) {
+    if (status !== 'idle' && status !== 'working')
+        throw new TypeError(`Invalid relay session status: ${status}`);
+}
 function isSafeLetter(letter) {
     try {
         assertLetter(letter);
@@ -108,6 +116,64 @@ export function presenceOf(record, now = Date.now()) {
     assertAddress(record.addr);
     return presenceOfInternal(record, now);
 }
+/**
+ * Register (or re-register) a non-Pi host as a relay session. The address is
+ * derived from `cwd` + `sessionId`, so re-registering keeps it, along with the
+ * existing `startedAt`. The host must call `heartbeat` well inside
+ * `HEARTBEAT_STALE_MS`.
+ */
+export function register(root, input) {
+    assertNonEmptyString(input.sessionId, 'session id');
+    assertNonEmptyString(input.name, 'session name');
+    assertNonEmptyString(input.cwd, 'session cwd');
+    const pid = input.pid ?? process.pid;
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new TypeError(`Invalid relay session pid: ${pid}`);
+    const status = input.status ?? 'idle';
+    assertStatus(status);
+    const addr = deriveAddr(input.cwd, input.sessionId);
+    const now = Date.now();
+    const record = {
+        addr,
+        sessionId: input.sessionId,
+        name: input.name,
+        cwd: input.cwd,
+        pid,
+        startedAt: readRecord(root, addr)?.startedAt ?? now,
+        lastSeenAt: now,
+        status,
+    };
+    writeRecord(root, record);
+    return record;
+}
+/**
+ * Refresh a registered session's `lastSeenAt` (clearing `offline`), applying an
+ * optional status or name. Returns null, writing nothing, if no record exists.
+ */
+export function heartbeat(root, addr, patch = {}) {
+    assertAddress(addr);
+    if (patch.status !== undefined)
+        assertStatus(patch.status);
+    if (patch.name !== undefined)
+        assertNonEmptyString(patch.name, 'session name');
+    const existing = readRecord(root, addr);
+    if (existing === null)
+        return null;
+    const { offline: _offline, ...rest } = existing;
+    const record = {
+        ...rest,
+        name: patch.name ?? rest.name,
+        status: patch.status ?? rest.status,
+        lastSeenAt: Date.now(),
+    };
+    writeRecord(root, record);
+    return record;
+}
+/** Delete a session's record. Aliases pointing at it are cleared by the next `sweep`. */
+export function unregister(root, addr) {
+    assertAddress(addr);
+    removeRecord(root, addr);
+}
 export function readAlias(root, name) {
     assertAliasName(name);
     const alias = readAliasInternal(root, name);

package/dist/index.js

@@ -509,6 +509,7 @@ export default function relay(pi) {
     pi.registerTool({
         name: 'relay',
         label: 'Relay',
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
         description: 'Message other pi sessions on this machine. list/list-cwd return bounded pages of sessions, online first (offline sessions still receive mail); filter with presence or exact sessionIds. Target a full sessionId, address, name, or @alias. send returns a message id and delivered/queued/uncertain receipt. Reply to received messages or pending asks with explicit replyTo. ask waits for a correlated reply, default 120s. Also supports cancel, pending, status, claim, watch, and send broadcasts to "*" or "cwd". Plain text only, ≤32KB: send summaries and paths.',
         promptSnippet: 'Message other pi sessions on this machine',
         promptGuidelines: [

package/dist/registration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/registration.test.js

@@ -0,0 +1,93 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import * as core from './core.js';
+const fixtures = [];
+function relayRoot() {
+    const dir = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'pi-relay-registration-')));
+    fixtures.push(dir);
+    return path.join(dir, 'relay');
+}
+const host = { sessionId: 'riker-supervisor', name: 'riker', cwd: '/work/riker' };
+afterEach(() => {
+    vi.useRealTimers();
+    while (fixtures.length > 0)
+        fs.rmSync(fixtures.pop(), { recursive: true, force: true });
+});
+describe('/core session registration', () => {
+    it('registers a live session visible in listRecords', () => {
+        const root = relayRoot();
+        const record = core.register(root, host);
+        expect(record).toMatchObject({
+            addr: core.deriveAddr(host.cwd, host.sessionId),
+            sessionId: host.sessionId,
+            name: 'riker',
+            cwd: host.cwd,
+            pid: process.pid,
+            status: 'idle',
+        });
+        expect(record.startedAt).toBe(record.lastSeenAt);
+        expect(core.listRecords(root)).toEqual([record]);
+        expect(core.presenceOf(record)).toBe('live');
+    });
+    it('heartbeat refreshes lastSeenAt and applies the patch; unknown addresses stay unknown', () => {
+        vi.useFakeTimers({ now: 1_000_000 });
+        const root = relayRoot();
+        const { addr } = core.register(root, host);
+        vi.setSystemTime(1_015_000);
+        const beat = core.heartbeat(root, addr, { status: 'working', name: 'riker-2' });
+        expect(beat).toMatchObject({
+            addr,
+            lastSeenAt: 1_015_000,
+            startedAt: 1_000_000,
+            status: 'working',
+            name: 'riker-2',
+        });
+        expect(core.readRecord(root, addr)).toEqual(beat);
+        const unknown = core.deriveAddr('/nowhere', 'ghost');
+        expect(core.heartbeat(root, unknown)).toBeNull();
+        expect(core.readRecord(root, unknown)).toBeNull();
+        expect(core.listRecords(root)).toHaveLength(1);
+    });
+    it('keeps a heartbeating session alias through sweep, and sweep clears it after unregister', () => {
+        const root = relayRoot();
+        const { addr } = core.register(root, host);
+        core.claimAlias(root, 'riker', addr, host.sessionId);
+        core.heartbeat(root, addr);
+        core.sweep(root);
+        expect(core.readAlias(root, 'riker')).toMatchObject({ addr });
+        core.unregister(root, addr);
+        expect(core.listRecords(root)).toEqual([]);
+        core.sweep(root);
+        expect(core.readAlias(root, 'riker')).toBeNull();
+        expect(() => core.unregister(root, addr)).not.toThrow();
+    });
+    it('re-registering keeps addr and startedAt', () => {
+        vi.useFakeTimers({ now: 2_000_000 });
+        const root = relayRoot();
+        const first = core.register(root, host);
+        vi.setSystemTime(2_060_000);
+        const second = core.register(root, { ...host, name: 'renamed', status: 'working' });
+        expect(second).toMatchObject({ addr: first.addr, startedAt: 2_000_000, lastSeenAt: 2_060_000, name: 'renamed' });
+        expect(core.listRecords(root)).toEqual([second]);
+    });
+    it('rejects invalid input', () => {
+        const root = relayRoot();
+        const { addr } = core.register(root, host);
+        const calls = [
+            () => core.register(root, { ...host, sessionId: '' }),
+            () => core.register(root, { ...host, name: 42 }),
+            () => core.register(root, { ...host, cwd: '' }),
+            () => core.register(root, { ...host, pid: 0 }),
+            () => core.register(root, { ...host, pid: 1.5 }),
+            () => core.register(root, { ...host, status: 'busy' }),
+            () => core.heartbeat(root, '../../escaped'),
+            () => core.heartbeat(root, addr, { status: 'busy' }),
+            () => core.heartbeat(root, addr, { name: '' }),
+            () => core.unregister(root, '../../escaped'),
+        ];
+        for (const call of calls)
+            expect(call).toThrow(TypeError);
+    });
+});

package/dist/registry.d.ts

@@ -70,6 +70,8 @@ export declare function listAliases(root: string): AliasRecord[];
 export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;
 export declare function clearAlias(root: string, name: string): void;
 export declare function writeRecord(root: string, record: SessionRecord): void;
+/** Delete `<addr>.json`. A missing record or relay root is fine. */
+export declare function removeRecord(root: string, addr: string): void;
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
 /** Read-only listing, oldest first. Never mutates anything. */
 export declare function listRecords(root: string): SessionRecord[];

package/dist/registry.js

@@ -223,6 +223,19 @@ export function writeRecord(root, record) {
         relay.close();
     }
 }
+/** Delete `<addr>.json`. A missing record or relay root is fine. */
+export function removeRecord(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return;
+    try {
+        relay.unlinkFile(`${addr}.json`);
+    }
+    finally {
+        relay.close();
+    }
+}
 function readRecordFromDirectory(directory, addr) {
     const raw = directory.readFile(`${addr}.json`);
     if (raw === null)

package/index.ts

@@ -567,6 +567,7 @@ export default function relay(pi: ExtensionAPI) {
   pi.registerTool({
     name: 'relay',
     label: 'Relay',
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     description:
       'Message other pi sessions on this machine. list/list-cwd return bounded pages of sessions, online first (offline sessions still receive mail); filter with presence or exact sessionIds. Target a full sessionId, address, name, or @alias. send returns a message id and delivered/queued/uncertain receipt. Reply to received messages or pending asks with explicit replyTo. ask waits for a correlated reply, default 120s. Also supports cancel, pending, status, claim, watch, and send broadcasts to "*" or "cwd". Plain text only, ≤32KB: send summaries and paths.',
     promptSnippet: 'Message other pi sessions on this machine',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-relay",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/registry.ts

@@ -244,6 +244,18 @@ export function writeRecord(root: string, record: SessionRecord): void {
   }
 }
 
+/** Delete `<addr>.json`. A missing record or relay root is fine. */
+export function removeRecord(root: string, addr: string): void {
+  assertPathSegment(addr, 'relay address');
+  const relay = openRelayRoot(root);
+  if (relay === null) return;
+  try {
+    relay.unlinkFile(`${addr}.json`);
+  } finally {
+    relay.close();
+  }
+}
+
 function readRecordFromDirectory(directory: RelayDirectoryHandle, addr: string): SessionRecord | null {
   const raw = directory.readFile(`${addr}.json`);
   if (raw === null) return null;