@trim21/personal-pi-extensions 0.0.192 → 0.0.194

package/src/talk/policy.ts

@@ -0,0 +1,84 @@
+/**
+ * Loop-breaking and inbound policy. Core layer, pi-free.
+ *
+ * A loop between two agents must terminate independently of what either
+ * model decides: repeats, rate, and backlog are all capped here, at the
+ * transport, not in the prompts.
+ */
+
+import { MAX_BODY_CHARS } from "./mailbox.js";
+
+export const DEDUPE_WINDOW_MS = 10_000;
+export const RATE_LIMIT_MAX = 8;
+export const RATE_LIMIT_WINDOW_MS = 30_000;
+export const BACKLOG_CAP = 50;
+
+export type OutboundVerdict = { ok: true } | { ok: false; reason: string };
+
+export class OutboundPolicy {
+  private readonly sentAt: number[] = [];
+  private readonly recentBodies = new Map<string, number>();
+  private readonly now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.now = now;
+  }
+
+  /**
+   * Gate one outbound letter. `unreadBacklog` is the target's current
+   * unread count (report 0 when the target is idle — an idle agent has by
+   * definition worked through what it was handed). `target` scopes the
+   * identical-body dedupe to a single peer (loop-breaking) so a broadcast
+   * of one body to N peers is not deduped after the first.
+   */
+  check(body: string, unreadBacklog: number, target?: string): OutboundVerdict {
+    if (body.length > MAX_BODY_CHARS) {
+      return {
+        ok: false,
+        reason: `Message is ${body.length} chars; cap is ${MAX_BODY_CHARS}. Send a summary and a path, not a payload.`,
+      };
+    }
+    if (unreadBacklog >= BACKLOG_CAP) {
+      return {
+        ok: false,
+        reason: `Peer has ${unreadBacklog} unread messages (cap ${BACKLOG_CAP}); wait for it to drain.`,
+      };
+    }
+    const now = this.now();
+    const dedupeKey = `${body}\u0000${target ?? ""}`;
+    const lastSame = this.recentBodies.get(dedupeKey);
+    if (lastSame !== undefined && now - lastSame < DEDUPE_WINDOW_MS) {
+      return {
+        ok: false,
+        reason: "Identical message to the same peer less than 10s ago — dropped to break loops.",
+      };
+    }
+    const windowStart = now - RATE_LIMIT_WINDOW_MS;
+    while (this.sentAt.length > 0 && this.sentAt[0] < windowStart) this.sentAt.shift();
+    if (this.sentAt.length >= RATE_LIMIT_MAX) {
+      return {
+        ok: false,
+        reason: `Rate limited: ${RATE_LIMIT_MAX} messages per ${RATE_LIMIT_WINDOW_MS / 1000}s per session.`,
+      };
+    }
+    return { ok: true };
+  }
+
+  /** Record a successful send so dedupe/rate state stays current. */
+  recordSend(body: string, target?: string): void {
+    this.sentAt.push(this.now());
+    this.recentBodies.set(`${body}\u0000${target ?? ""}`, this.now());
+    // bound the dedupe map
+    if (this.recentBodies.size > 200) {
+      const cutoff = this.now() - DEDUPE_WINDOW_MS;
+      for (const [key, ts] of this.recentBodies) {
+        if (ts < cutoff) this.recentBodies.delete(key);
+      }
+    }
+  }
+}
+
+/** Inbound guard: PI_TALK_INBOUND=refuse drops all peer mail. */
+export function inboundAccepts(env: string | undefined = process.env.PI_TALK_INBOUND): boolean {
+  return env !== "refuse";
+}

package/src/talk/registry.ts

@@ -0,0 +1,148 @@
+/**
+ * Session registry for the talk mailbox: who is around, where, and whether
+ * they are reachable. Core layer — depends only on TalkStorage, never on pi.
+ *
+ * Design:
+ * - An address belongs to a conversation, not a process: hash of cwd + pi
+ *   session id, so a resumed session (`pi -c`) answers to the same address and
+ *   two sessions on one directory never share an inbox.
+ * - A record outlives the process that wrote it — that's what makes a session
+ *   addressable while it's down (mail waits on disk).
+ * - Presence is a pid PLUS a heartbeat: pid alone can't tell wedged from
+ *   healthy (and pids get reused); heartbeat alone can't tell crash from pause.
+ * - Listing has NO side effects.
+ *
+ * All values read from storage are validated with TypeBox before use.
+ */
+
+import { createHash } from "node:crypto";
+
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+import type { TalkStorage } from "./storage.js";
+
+export const SessionRecordSchema = Type.Object({
+  addr: Type.String(),
+  sessionId: Type.String(),
+  name: Type.String(),
+  cwd: Type.String(),
+  pid: Type.Number(),
+  startedAt: Type.Number(),
+  lastSeenAt: Type.Number(),
+  status: Type.Union([Type.Literal("idle"), Type.Literal("working")]),
+  offline: Type.Optional(Type.Boolean()),
+});
+export type SessionRecord = Static<typeof SessionRecordSchema>;
+
+export type Presence = "live" | "stalled" | "offline";
+
+export const HEARTBEAT_STALE_MS = 45_000;
+/** A mailbox holding undelivered mail is kept this long after last contact. */
+export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
+
+const ADDRESS_PATTERN = /^[a-f0-9]{12}$/;
+
+export function deriveAddr(cwd: string, sessionId: string): string {
+  return createHash("sha256").update(`${cwd}${sessionId}`).digest("hex").slice(0, 12);
+}
+
+/** Validate a talk address before it becomes a storage key. */
+export function assertAddress(addr: string): void {
+  if (!ADDRESS_PATTERN.test(addr)) throw new TypeError(`Invalid talk address: ${addr}`);
+}
+
+// ── Storage namespaces ───────────────────────────────────────────────────
+
+export const RECORDS_NS = "records";
+
+export function inboxNs(addr: string): string {
+  assertAddress(addr);
+  return `inbox/${addr}`;
+}
+
+export function asksNs(addr: string): string {
+  assertAddress(addr);
+  return `asks/${addr}`;
+}
+
+function recordKey(addr: string): string {
+  assertAddress(addr);
+  return `${addr}.json`;
+}
+
+// ── Session records ──────────────────────────────────────────────────────
+
+export async function writeRecord(storage: TalkStorage, record: SessionRecord): Promise<void> {
+  await storage.writeJson(RECORDS_NS, recordKey(record.addr), record);
+}
+
+export async function readRecord(
+  storage: TalkStorage,
+  addr: string,
+): Promise<SessionRecord | null> {
+  const raw = await storage.readJson(RECORDS_NS, recordKey(addr));
+  return Value.Check(SessionRecordSchema, raw) ? raw : null;
+}
+
+/** Read-only listing, oldest first. Never mutates anything. */
+export async function listRecords(storage: TalkStorage): Promise<SessionRecord[]> {
+  const out: SessionRecord[] = [];
+  for (const key of await storage.listKeys(RECORDS_NS)) {
+    const addr = key.slice(0, -".json".length);
+    if (!ADDRESS_PATTERN.test(addr)) continue;
+    const record = await readRecord(storage, addr);
+    if (record) out.push(record);
+  }
+  return out.toSorted((a, b) => a.startedAt - b.startedAt);
+}
+
+function pidAlive(pid: number): boolean {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but isn't ours — still alive
+    return (error as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+export function presenceOf(record: SessionRecord, now: number = Date.now()): Presence {
+  if (record.offline) return "offline";
+  if (!pidAlive(record.pid)) return "offline";
+  return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? "live" : "stalled";
+}
+
+// ── Sweep ────────────────────────────────────────────────────────────────
+
+/**
+ * Reclaim dead sessions' data. Rules (mail outranks tidiness):
+ * - a running session is never touched;
+ * - a mailbox holding undelivered mail is kept for SWEEP_MAIL_KEEP_MS;
+ * - 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.
+ *
+ * `sessionExists(sessionId)` reports whether pi can still resume the session
+ * (its session file is present). When omitted, every offline session is
+ * treated as resumable (the conservative choice).
+ */
+export async function sweep(
+  storage: TalkStorage,
+  now: number = Date.now(),
+  sessionExists?: (sessionId: string) => boolean,
+): Promise<void> {
+  for (const record of await listRecords(storage)) {
+    if (presenceOf(record, now) !== "offline") continue;
+    const hasMail =
+      (await storage.hasKeys(inboxNs(record.addr))) || (await storage.hasKeys(asksNs(record.addr)));
+    const expired = now - record.lastSeenAt >= SWEEP_MAIL_KEEP_MS;
+    if (hasMail && !expired) continue;
+    if (!expired && (sessionExists?.(record.sessionId) ?? true)) continue;
+    await storage.removeNamespace(inboxNs(record.addr));
+    await storage.removeNamespace(asksNs(record.addr));
+    await storage.removeKey(RECORDS_NS, recordKey(record.addr));
+  }
+}

package/src/talk/storage.ts

@@ -0,0 +1,142 @@
+/**
+ * Storage abstraction for the talk store.
+ *
+ * The talk core (registry + mailbox) is written against this interface, so
+ * the persistence backend can be swapped: today SQLite, later a remote/HTTP
+ * service without touching the talk logic.
+ *
+ * The model is deliberately minimal and HTTP-friendly:
+ * - a `namespace` is a collection;
+ * - a `key` is a single entry inside a namespace;
+ * - values are opaque JSON (validated by the core layer, not here);
+ * - audit is an append-only log.
+ *
+ * `readJson` returns `unknown` on purpose: the core layer validates it with
+ * TypeBox schemas, so a corrupt/foreign payload is rejected rather than
+ * blindly cast.
+ */
+
+import { DatabaseSync } from "node:sqlite";
+
+export interface TalkStorage {
+  /** Ensure the store is ready (create root, connect, handshake, etc.). */
+  init(): Promise<void>;
+  /** List all keys in a namespace, sorted. No side effects. */
+  listKeys(namespace: string): Promise<string[]>;
+  /** Read a JSON value by key; null when absent or not valid JSON. */
+  readJson(namespace: string, key: string): Promise<unknown>;
+  /** Atomically write a JSON value under a key. */
+  writeJson(namespace: string, key: string, value: unknown): Promise<void>;
+  /** Remove a key. Returns true when the key existed and was removed. */
+  removeKey(namespace: string, key: string): Promise<boolean>;
+  /** Whether a namespace holds at least one key. */
+  hasKeys(namespace: string): Promise<boolean>;
+  /** Remove an entire namespace and everything in it. */
+  removeNamespace(namespace: string): Promise<void>;
+  /** Append one line to a named log. */
+  appendLog(logName: string, line: string): Promise<void>;
+  /** Read all lines of a named log, oldest first. */
+  readLog(logName: string): Promise<string[]>;
+}
+
+/**
+ * SQLite backend (Node's built-in `node:sqlite`, no npm dependency).
+ *
+ * A single database file holds everything; WAL mode plus a busy timeout lets
+ * multiple pi sessions read and write it concurrently. SQL parameter binding
+ * removes the need for path/symlink hardening entirely.
+ *
+ * The backend is synchronous; each method wraps its result in a resolved
+ * promise to satisfy the async interface that a future HTTP backend needs.
+ */
+export class SqliteTalkStorage implements TalkStorage {
+  private readonly db: DatabaseSync;
+
+  constructor(dbPath: string) {
+    this.db = new DatabaseSync(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA busy_timeout = 5000");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS talk_kv (
+        namespace TEXT NOT NULL,
+        key       TEXT NOT NULL,
+        value     TEXT NOT NULL,
+        PRIMARY KEY (namespace, key)
+      )
+    `);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS talk_log (
+        name TEXT NOT NULL,
+        seq  INTEGER PRIMARY KEY AUTOINCREMENT,
+        line TEXT NOT NULL
+      )
+    `);
+  }
+
+  init(): Promise<void> {
+    // schema is created in the constructor
+    return Promise.resolve();
+  }
+
+  /** Close the underlying database handle (test teardown). */
+  close(): void {
+    this.db.close();
+  }
+
+  listKeys(namespace: string): Promise<string[]> {
+    const rows = this.db
+      .prepare("SELECT key FROM talk_kv WHERE namespace = ? ORDER BY key")
+      .all(namespace) as unknown as { key: string }[];
+    return Promise.resolve(rows.map((r) => r.key));
+  }
+
+  readJson(namespace: string, key: string): Promise<unknown> {
+    const row = this.db
+      .prepare("SELECT value FROM talk_kv WHERE namespace = ? AND key = ?")
+      .get(namespace, key) as { value: string } | undefined;
+    if (row === undefined) return Promise.resolve(null);
+    try {
+      return Promise.resolve(JSON.parse(row.value) as unknown);
+    } catch {
+      return Promise.resolve(null);
+    }
+  }
+
+  writeJson(namespace: string, key: string, value: unknown): Promise<void> {
+    this.db
+      .prepare("INSERT OR REPLACE INTO talk_kv (namespace, key, value) VALUES (?, ?, ?)")
+      .run(namespace, key, JSON.stringify(value));
+    return Promise.resolve();
+  }
+
+  removeKey(namespace: string, key: string): Promise<boolean> {
+    const result = this.db
+      .prepare("DELETE FROM talk_kv WHERE namespace = ? AND key = ?")
+      .run(namespace, key);
+    return Promise.resolve(result.changes > 0);
+  }
+
+  hasKeys(namespace: string): Promise<boolean> {
+    return Promise.resolve(
+      this.db.prepare("SELECT 1 FROM talk_kv WHERE namespace = ? LIMIT 1").get(namespace) !==
+        undefined,
+    );
+  }
+
+  removeNamespace(namespace: string): Promise<void> {
+    this.db.prepare("DELETE FROM talk_kv WHERE namespace = ?").run(namespace);
+    return Promise.resolve();
+  }
+
+  appendLog(logName: string, line: string): Promise<void> {
+    this.db.prepare("INSERT INTO talk_log (name, line) VALUES (?, ?)").run(logName, line);
+    return Promise.resolve();
+  }
+
+  readLog(logName: string): Promise<string[]> {
+    const rows = this.db
+      .prepare("SELECT line FROM talk_log WHERE name = ? ORDER BY seq")
+      .all(logName) as unknown as { line: string }[];
+    return Promise.resolve(rows.map((r) => r.line));
+  }
+}