@agfpd/iapeer 0.4.5 → 0.4.7

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.5",
+  "version": "0.4.7",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -37,10 +37,10 @@ import {
   isEphemeralPeer,
   isStopped,
   killSession,
-  lastActiveRuntime,
   loadLifecycleConfig,
   purgeIdentityState,
   removeSessionState,
+  resolvePeerRuntime,
   setEphemeralArmed,
   setFreshNext,
   setIdleReaped,
@@ -518,7 +518,10 @@ export async function newPeer(
     }
   }
   if (runtime && !isRuntime(runtime)) throw new Error(`invalid runtime "${runtime}"`)
-  const rt: Runtime = (runtime as Runtime | undefined) ?? peer.runtime
+  // Omitted runtime resolves IDENTICALLY to `attach` (resolvePeerRuntime): default_runtime
+  // anchored, sole-live refinement — so `iapeer new <peer>` and `iapeer attach <peer>` never
+  // target different runtimes (the "new had no effect, attach resurrected the other" footgun).
+  const rt: Runtime = (runtime as Runtime | undefined) ?? resolvePeerRuntime(peer, cfg)
   if (!peer.runtimes.includes(rt)) {
     return {
       personality,
@@ -638,7 +641,9 @@ export async function compactPeer(
     return { personality, runtime: r.value.controlled.runtime, action: 'compacted', woke: false }
   }
 
-  const rt: Runtime = (runtime as Runtime | undefined) ?? lastActiveRuntime(peer, cfg) ?? peer.runtime
+  // Asleep branch: omitted runtime resolves like new/attach (resolvePeerRuntime) — consistent
+  // default_runtime anchoring instead of the old hidden last-active-by-mtime.
+  const rt: Runtime = (runtime as Runtime | undefined) ?? resolvePeerRuntime(peer, cfg)
   if (!peer.runtimes.includes(rt)) {
     return {
       personality,

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/lifecycle/index.ts

@@ -1552,9 +1552,11 @@ export async function folderLaunch(opts: FolderLaunchOptions): Promise<WakeResul
 }
 
 /**
- * The runtime with the freshest transcript activity for a peer (contract: attach
- * resolves the runtime by last-active transcript-mtime, NOT the profile default).
- * undefined when no runtime has any activity (a never-run peer).
+ * The runtime with the freshest transcript activity for a peer. undefined when no
+ * runtime has any activity (a never-run peer). NOTE: this is NO LONGER the attach
+ * default — operator runtime resolution moved to `resolvePeerRuntime` (default_runtime
+ * anchored) because last-active-by-mtime is hidden state and unreliable for codex
+ * (rollout flushed only on a real turn). Kept as a diagnostic / `list` helper.
  */
 export function lastActiveRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runtime | undefined {
   let best: Runtime | undefined
@@ -1573,6 +1575,46 @@ export function lastActiveRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runti
   return best
 }
 
+/** Runtimes of `peer` whose session is LIVE right now (lifecycle-local liveness,
+ *  same `sessionAlive` predicate the wake/attach paths use). */
+function liveRuntimesOf(peer: PeerRecord, cfg: LifecycleConfig): Runtime[] {
+  return peer.runtimes.filter(rt =>
+    sessionAlive(buildSocketPath(rt, peer.personality, cfg.sockDir), buildProcessAddress(rt, peer.personality)),
+  )
+}
+
+/**
+ * The SINGLE runtime an operator verb (new / attach / compact) acts on when the
+ * runtime arg is OMITTED, for a peer that may declare several. PREDICTABLE by
+ * construction and IDENTICAL across those verbs — this is the fix for the
+ * multi-runtime footgun where `new` defaulted to `default_runtime` while `attach`
+ * defaulted to last-active-by-mtime, so `iapeer new <peer>` freshed one runtime
+ * while `iapeer attach <peer>` resurrected the other ("new had no effect, attach
+ * came up on the old session").
+ *
+ * Precedence (never refuses — the naive flow must self-resolve, no explicit arg):
+ *   1. sole declared runtime → it.
+ *   2. `default_runtime` is LIVE → `default_runtime` (the configured anchor AND the
+ *      obvious running target).
+ *   3. exactly ONE other runtime is live (default dead) → that live one.
+ *   4. otherwise (nothing live, or 2+ live without the default) → `default_runtime`.
+ *
+ * The peer's runtime is governed by its CONFIGURABLE `default_runtime` (the
+ * documented `iapeer default-runtime` lever), NOT by which transcript was touched
+ * last — last-active-by-mtime is hidden state and unreliable for codex (its rollout
+ * file is flushed only on a real model turn, so a just-spawned fresh codex session
+ * reads as "older" than a stale one). To make `iapeer new/attach <peer>` (no runtime
+ * arg) resolve to codex, set the peer's default to codex once; per-command runtime
+ * args remain the explicit override.
+ */
+export function resolvePeerRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runtime {
+  if (peer.runtimes.length === 1) return peer.runtimes[0]
+  const live = liveRuntimesOf(peer, cfg)
+  if (live.includes(peer.runtime)) return peer.runtime
+  if (live.length === 1) return live[0]
+  return peer.runtime
+}
+
 export interface AttachOptions {
   personality: string
   runtime?: string
@@ -1586,10 +1628,11 @@ export type AttachResult =
 /**
  * `iapeer attach <peer> [runtime]` — ensure the peer is live, then hand back the
  * socket/identity for the caller to `tmux attach`. ALWAYS RESUME (contract: attach
- * never starts fresh). Runtime: explicit arg, else the LAST-ACTIVE runtime by
- * transcript-mtime (not the profile default), else the profile default. A warm-live
- * session is attached directly; a warm-asleep one is woken with --resume first
- * (fail-loud if there is nothing to resume — a never-run peer must be folder-launched).
+ * never starts fresh). Runtime: explicit arg, else `resolvePeerRuntime` (the SAME
+ * resolver `new`/`compact` use — default_runtime anchored with a sole-live
+ * refinement), so attach and new never disagree on which runtime "peer" means. A
+ * warm-live session is attached directly; a warm-asleep one is woken with --resume
+ * first (fail-loud if there is nothing to resume — a never-run peer must be folder-launched).
  */
 export async function attachPeer(opts: AttachOptions): Promise<AttachResult> {
   const env = opts.env ?? process.env
@@ -1598,8 +1641,10 @@ export async function attachPeer(opts: AttachOptions): Promise<AttachResult> {
   if (!peer) return { ok: false, reason: `peer "${opts.personality}" is not registered` }
   const runtimeResult = resolveWakeRuntime(opts.runtime, peer)
   if (opts.runtime && !runtimeResult.ok) return { ok: false, reason: runtimeResult.error.message }
-  // last-active (by mtime) wins over the profile default when no runtime is given.
-  const runtime = opts.runtime ?? lastActiveRuntime(peer, cfg) ?? peer.runtime
+  // Omitted runtime resolves IDENTICALLY to `new`/`compact` (resolvePeerRuntime):
+  // default_runtime anchored, sole-live refinement, never hidden last-active — so
+  // `iapeer attach <peer>` and `iapeer new <peer>` never disagree on the runtime.
+  const runtime = opts.runtime ?? resolvePeerRuntime(peer, cfg)
   const identity = buildProcessAddress(runtime, opts.personality)
   const sock = buildSocketPath(runtime, opts.personality, cfg.sockDir)
   if (sessionAlive(sock, identity)) return { ok: true, identity, socketPath: sock, woke: false, runtime }