@agfpd/iapeer 0.4.6 → 0.4.8

package/README.md

@@ -9,6 +9,12 @@
 
 iapeer keeps a team of AI agents, humans, and services on one host **always reachable — every one of them a single message away.** Each participant is a **peer**: a Claude Code or Codex CLI agent, a person on Telegram, or a scheduler/watcher service. Any agent reaches any other with one call — `send_to_peer(<name>, <text>)` — and a peer that is asleep is still reachable: the daemon wakes it and delivers. Agents on Claude and on Codex — different AI runtimes from different vendors — talk as equal peers; humans take part over Telegram, or directly in the terminal — attached to a peer's live session with `iapeer attach`.
 
+<p align="center">
+  <img src=".github/assets/iapeer-pingpong.gif" width="800" alt="A person messages one peer on Telegram; heterogeneous peers (Claude + Codex) relay a baton over one protocol and report back to Telegram.">
+  <br>
+  <em>One Telegram message in → Claude and Codex peers pass a baton over the same protocol → a report back in Telegram.</em>
+</p>
+
 ## How it works
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/launch/readyGateModel.ts

@@ -134,9 +134,15 @@ export async function paneLogViewport(log: string, cols: number, rows: number, s
  * validated `composerOccupancyFromModel` (REUSED, not reimplemented). The hosted equivalent of
  * `targetComposerBlocksDelivery`'s capture-pane occupancy. @xterm loads dynamically here (flag-on
  * hosted only; the leaf `composerOccupancyFromModel` import is type-only at runtime, so the warm path
- * stays @xterm-free with the flip off). UNCERTAINTY → BUSY (true): a model-build failure mirrors the
- * tmux predicate's capture-fail-is-busy stance — prefer a false-busy hold over a false-free paste into
- * a human composer.
+ * stays @xterm-free with the flip off). UNREADABLE PANE-LOG → NOT busy (false): the hold exists ONLY to
+ * avoid clobbering VISIBLE human composer text; if the model can't be built there is NO observed text to
+ * protect. This deliberately does NOT mirror the tmux predicate's capture-fail-is-busy stance: tmux
+ * `capture-pane` fails ~only when the session is GONE (then the queue's session-token/alive check fails
+ * the job loudly), but a hosted pane-log can be absent/unreadable while the session is ALIVE (e.g. a
+ * long-lived session whose lifecycle pane-log was rotated/removed) — so "uncertainty → busy" would stall
+ * EVERY delivery to such a peer until the 120 s force-timeout, starving the core addressed-delivery
+ * feature. The narrow cost (no composer protection while the log is unreadable) is acceptable: a session
+ * actively being typed into is precisely one whose pane-log IS being written.
  *
  * NB (sequence): this is the DETECTION primitive. The end-to-end gate (attached-supervisor-
  * client + enqueue + host-aware drain) lands with the attach client in Ф0b-3 — until a human can
@@ -145,7 +151,7 @@ export async function paneLogViewport(log: string, cols: number, rows: number, s
  */
 export async function paneLogComposerOccupied(log: string, cols: number, rows: number, runtime: string): Promise<boolean> {
   const term = await loadPaneLogModel(log, cols, rows)
-  if (!term) return true // uncertainty → busy: never paste into a maybe-occupied composer
+  if (!term) return false // unreadable pane-log → no observed human composer text → deliver, never stall (see JSDoc)
   const { composerOccupancyFromModel } = await import('../shadow/render.ts')
   return composerOccupancyFromModel(term, cols, rows, runtime)
 }

package/src/supervisor/daemon.ts

@@ -12,7 +12,7 @@
 // @xterm/headless bundles under `bun build --compile` (pure JS; the Bun-native pty has no native addon).
 import { Terminal } from '@xterm/headless'
 import { SerializeAddon } from '@xterm/addon-serialize'
-import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
 import { dirname } from 'node:path'
 import {
   BackpressureWriter,
@@ -157,14 +157,43 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   // corrupts multibyte glyphs like ❯/›; the canonical latin1/Buffer grabli). Parent dir 0700, matching
   // launch's mkdir before pipe-pane. Unset paneLogPath → no log (throwaway/tick).
   let paneLogFd = -1
-  if (opts.paneLogPath) {
+  let paneLogIno = -1 // inode the fd points at — to detect an out-from-under-us unlink/replace
+  let paneLogCheckedMs = 0
+  const PANELOG_HEAL_MS = 1000 // throttle the path-existence re-check to ≤1/sec regardless of output volume
+  const openPaneLog = (): void => {
+    if (!opts.paneLogPath) return
     try {
       mkdirSync(dirname(opts.paneLogPath), { recursive: true, mode: 0o700 })
+      if (paneLogFd >= 0) try { closeSync(paneLogFd) } catch { /* */ }
       paneLogFd = openSync(opts.paneLogPath, 'a')
+      paneLogIno = fstatSync(paneLogFd).ino
     } catch {
       paneLogFd = -1 // best-effort: a log open hiccup never blocks serving the session
+      paneLogIno = -1
     }
   }
+  // SELF-HEAL (Defect 2): the pane-log path can be unlinked out from under a live session (observed on
+  // the fleet: long-lived sessions' lifecycle pane-logs vanished while the supervisor ran). The fd then
+  // keeps writing to a now-unlinked inode — the path stays gone and every occupancy reader of
+  // `<logDir>/<identity>.log` goes blind: composer-busy delivery detection AND telegram-runtime's
+  // mtime-based typing/activity indicator (shared file). Throttled re-check before a write: if the path
+  // vanished or now maps to a DIFFERENT inode than the fd, reopen 'a'. capPaneLogs truncates IN PLACE
+  // (same inode) so a normal cap never triggers a spurious reopen. Tied to output (no idle wakeups) —
+  // exactly when the log matters.
+  const healPaneLog = (): void => {
+    if (!opts.paneLogPath || paneLogFd < 0) return
+    const now = Date.now()
+    if (now - paneLogCheckedMs < PANELOG_HEAL_MS) return
+    paneLogCheckedMs = now
+    let ino = -1
+    try {
+      ino = statSync(opts.paneLogPath).ino
+    } catch {
+      ino = -1 // path gone
+    }
+    if (ino !== paneLogIno) openPaneLog()
+  }
+  openPaneLog()
 
   const clients = new Set<unknown>()
   const writers = new WeakMap<object, BackpressureWriter>()
@@ -234,12 +263,14 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
         const buf = Buffer.isBuffer(d) ? d : typeof d === 'string' ? Buffer.from(d, 'utf8') : Buffer.from(d)
         // PANE-LOG: the RAW child bytes, exactly as pipe-pane writes them (before any query-stripping
         // for clients) — written as a Buffer, never a string. The `s` below is for query DETECTION only.
-        if (paneLogFd >= 0)
+        if (paneLogFd >= 0) {
+          healPaneLog() // reopen if the path was unlinked/replaced out from under us (Defect 2)
           try {
             writeSync(paneLogFd, buf)
           } catch {
             /* best-effort */
           }
+        }
         const s = buf.toString('latin1')
         writeSeq++ // a new write arrived (lets the attach drain detect bytes that land mid-await)
         writeChain = new Promise<void>(resolve => xterm.write(buf, () => resolve())) // authoritative model (+ parse barrier)