@agfpd/iapeer 0.2.10 → 0.2.11

package/src/lifecycle/queue.ts

@@ -0,0 +1,159 @@
+// Ephemeral serial queue (wake_policy:"ephemeral" M3) — per-peer disk FIFO of
+// pending tasks for a stateless worker. Deliveries to an ephemeral target are
+// NEVER injected into a live session (one task = one clean context window =
+// the whole point of the policy); they are ALWAYS enqueued here, and the drain
+// (drainEphemeralQueue in index.ts) feeds the worker one task per fresh session.
+//
+// Layout: `<stateDir>/<identity>.queue/<seq>` — one JSON file per task
+// ({ task, topic? }), zero-padded numeric names so lexicographic order IS the
+// FIFO order. Durable by construction: the queue survives a daemon restart and
+// is drained by the supervise tick (the same scan that retries a failed wake).
+//
+// Concurrency: the daemon is the main writer, but a direct CLI `iap send`
+// (daemon down) can race it from another process. Enqueue is therefore
+// EXCLUSIVE-CREATE: write a temp file, then linkSync it to the next seq —
+// linkSync fails with EEXIST on a taken name (atomic on POSIX), so two
+// concurrent enqueues can never share a seq; the loser just advances. Content
+// is complete before the link lands (no partial reads).
+//
+// Retry semantics (boris acceptance (b)): the consumer PEEKS (reads without
+// removing), wakes the worker, and removes the item ONLY on READY — a failed
+// wake leaves the task at the head for the next supervise-tick drain. See
+// drainEphemeralQueue.
+
+import { linkSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { LifecycleConfig } from './index.ts'
+
+/** One queued task for an ephemeral worker. */
+export interface EphemeralQueueItem {
+  /** The routed envelope — becomes the boot first-message of the fresh session. */
+  task: string
+  /** Optional topic (threading; recorded by the wake as the session topic). */
+  topic?: string
+}
+
+/** A peeked item: the queue position (for the later remove) plus the payload. */
+export interface PeekedQueueItem extends EphemeralQueueItem {
+  seq: string
+}
+
+export function ephemeralQueueDir(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.queue`)
+}
+
+const SEQ_PAD = 6
+
+function listSeqs(dir: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return [] // no dir yet → empty queue
+  }
+  // Only the numbered items — temp files (.tmp-*) and strays are not queue entries.
+  return entries.filter(name => /^\d+$/.test(name)).sort()
+}
+
+/** Queue depth (pending tasks). 0 for a missing dir. */
+export function ephemeralQueueDepth(cfg: LifecycleConfig, identity: string): number {
+  return listSeqs(ephemeralQueueDir(cfg, identity)).length
+}
+
+/**
+ * Append a task to the identity's FIFO. Returns the depth AFTER the append
+ * (≥1 — usable as the "qd" observability field). Exclusive-create: safe against
+ * a concurrent enqueue from another process. Throws only on a real FS failure
+ * (the caller surfaces it as a delivery error — an un-enqueued task must NOT be
+ * reported queued).
+ */
+export function enqueueEphemeralTask(
+  cfg: LifecycleConfig,
+  identity: string,
+  item: EphemeralQueueItem,
+): number {
+  const dir = ephemeralQueueDir(cfg, identity)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const tmp = join(dir, `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  writeFileSync(tmp, JSON.stringify({ task: item.task, ...(item.topic ? { topic: item.topic } : {}) }), {
+    mode: 0o600,
+  })
+  try {
+    // Next seq = max existing + 1; on an EEXIST race, advance and retry.
+    let seq = (() => {
+      const seqs = listSeqs(dir)
+      return seqs.length ? parseInt(seqs[seqs.length - 1]!, 10) + 1 : 1
+    })()
+    // Bounded retry: a competitor can win a name at most once per its own enqueue.
+    for (let attempt = 0; attempt < 1000; attempt++, seq++) {
+      const target = join(dir, String(seq).padStart(SEQ_PAD, '0'))
+      try {
+        linkSync(tmp, target) // atomic exclusive-create (EEXIST when taken)
+        return listSeqs(dir).length
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+      }
+    }
+    throw new Error(`ephemeral queue enqueue: could not claim a seq for ${identity} after 1000 attempts`)
+  } finally {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/**
+ * Read the HEAD of the FIFO without removing it (retry semantics: the item is
+ * removed only after the wake went READY — removeEphemeralTask). null on empty.
+ * A corrupt head (unparseable JSON) is dropped with its slot — a poison task
+ * must not wedge the whole queue — and the next item (if any) is returned.
+ */
+export function peekEphemeralTask(cfg: LifecycleConfig, identity: string): PeekedQueueItem | null {
+  const dir = ephemeralQueueDir(cfg, identity)
+  for (const seq of listSeqs(dir)) {
+    const path = join(dir, seq)
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+      if (typeof raw.task === 'string' && raw.task.length > 0) {
+        return { seq, task: raw.task, topic: typeof raw.topic === 'string' ? raw.topic : undefined }
+      }
+    } catch {
+      /* unreadable/corrupt → drop the slot below */
+    }
+    try {
+      rmSync(path, { force: true }) // poison/corrupt item: drop, do not wedge the queue
+    } catch {
+      return null // cannot even drop it — give up this round, retry next tick
+    }
+  }
+  return null
+}
+
+/** Remove a consumed item (after its wake went READY). Idempotent. */
+export function removeEphemeralTask(cfg: LifecycleConfig, identity: string, seq: string): void {
+  try {
+    rmSync(join(ephemeralQueueDir(cfg, identity), seq), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
+/** Identities with a non-empty queue (the supervise-tick drain scan; also the
+ *  drain-on-start surface — the queue is durable across daemon restarts). */
+export function listQueuedIdentities(cfg: LifecycleConfig): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(cfg.stateDir)
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const name of entries) {
+    if (!name.endsWith('.queue')) continue
+    const identity = name.slice(0, -'.queue'.length)
+    if (listSeqs(join(cfg.stateDir, name)).length > 0) out.push(identity)
+  }
+  return out.sort()
+}

package/src/provision/index.ts

@@ -91,6 +91,27 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
     runtimeBin,
     warn: opts.warn,
   })
+  // wake_policy:"ephemeral" sanity (M2 edge cases — warn, don't refuse: the policy
+  // lives in the hand-editable local profile, provision just surfaces the mismatch):
+  //   • + interfaces.telegram: ephemeral WINS in resolveWakeMode (explicit policy
+  //     beats the inferred human type), so a human dialogue channel would die-after-
+  //     reply and never resume — almost certainly a config mistake.
+  //   • + infra (always-on) runtime: launchd KeepAlive owns the session (H4 read-only)
+  //     — the daemon never wakes/reaps it, so the ephemeral policy is INERT.
+  if (profile.wake_policy === 'ephemeral') {
+    if (profile.interfaces?.telegram != null) {
+      opts.warn?.(
+        `peer "${profile.personality}" declares BOTH wake_policy:"ephemeral" AND interfaces.telegram — ` +
+          `ephemeral wins (always-fresh, die-after-reply); a human telegram dialogue should not be ephemeral`,
+      )
+    }
+    if (isInfraRuntime(opts.runtime)) {
+      opts.warn?.(
+        `peer "${profile.personality}" declares wake_policy:"ephemeral" on always-on infra runtime ` +
+          `"${opts.runtime}" — launchd owns the session (H4), the daemon never wakes/reaps it, the policy is inert`,
+      )
+    }
+  }
   // 2) registry entry — without it the daemon does not see the peer (tool-list,
   //    caller resolution, wake-on-miss findPeer all read peers-profiles.json).
   await upsertPeer(

package/src/provision/provision.test.ts

@@ -3,7 +3,7 @@
 // IAPEER_LAUNCHAGENTS_DIR temp dirs so the suite never touches the live fleet.
 
 import { afterEach, describe, expect, test } from 'bun:test'
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { provisionPeer } from './index.ts'
@@ -102,3 +102,59 @@ describe('provisionPeer', () => {
     expect(findPeer(readPeersIndex({ env }), 'timer')?.cwd).toBe(cwd)
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:"ephemeral" provision warnings (M2 edge cases — warn, not refuse)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('provisionPeer ephemeral warnings', () => {
+  test('ephemeral + interfaces.telegram → WARN (ephemeral wins; human dialogue should not die-after-reply)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'wtg')
+    // pre-existing profile (provision returns it unchanged) carrying the bad combo
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({
+        personality: 'wtg',
+        runtime: 'claude',
+        intelligence: 'natural',
+        interfaces: { telegram: { user_id: 1 } },
+        wake_policy: 'ephemeral',
+      }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(warns.some(w => /ephemeral/.test(w) && /telegram/.test(w))).toBe(true)
+  })
+
+  test('plain ephemeral worker (claude, no telegram) → NO ephemeral warn', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'weph')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'weph', runtime: 'claude', wake_policy: 'ephemeral' }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(warns.filter(w => /ephemeral/.test(w))).toEqual([])
+  })
+
+  test('ephemeral + always-on infra runtime → WARN (H4: launchd owns it, the policy is inert)', async () => {
+    const root = mkTmp()
+    const { dir: bindir } = fakeBinDir()
+    const env = envFor(root, bindir)
+    const cwd = join(root, 'winf')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'winf', runtime: 'notifier', wake_policy: 'ephemeral' }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'notifier', env, warn: m => warns.push(m) })
+    expect(warns.some(w => /ephemeral/.test(w) && /inert|launchd/i.test(w))).toBe(true)
+  })
+})

package/src/transport/index.ts

@@ -378,6 +378,14 @@ export interface RouteResult {
   delivered_to: { personality: string; runtime: string }
   woke: boolean
   ts: string
+  /** wake_policy:"ephemeral" M3 — true when the message was ENQUEUED for a
+   *  stateless worker rather than injected/woken synchronously: the daemon
+   *  drains the per-peer FIFO one task per fresh session (async). The
+   *  substantive result arrives as the worker's own reply (FaaS semantics);
+   *  `delivered_to` names the ACCEPTING queue identity, not a live session. */
+  queued?: boolean
+  /** Queue depth right after the enqueue (observability; only with queued). */
+  queueDepth?: number
 }
 
 // WakeFn — the lifecycle wake primitive, INJECTED (transport never imports
@@ -403,9 +411,29 @@ export interface WakeOutcome {
 }
 export type WakeFn = (req: WakeRequest) => Promise<WakeOutcome>
 
+/** wake_policy:"ephemeral" M3 — the injected serial-queue delivery seam. Like
+ *  WakeFn, transport never imports lifecycle: the daemon composition (main.ts)
+ *  wires the queue + drain behind this contract; absent → every target takes
+ *  the normal live/miss path (library/CLI/test callers unchanged). */
+export interface EphemeralRouteDeps {
+  /** Is the target peer (by its registry cwd) an ephemeral stateless worker? */
+  isEphemeral: (cwd: string) => boolean
+  /** Always-enqueue delivery: enqueue + async drain kick → fast `{queued:true}`
+   *  ack. MUST NOT block on the wake (the sender's content-level answer is the
+   *  worker's own reply, not this transport ack). */
+  deliver: (args: {
+    peer: PeerRecord
+    envelope: string
+    topic?: string
+    runtime?: string
+  }) => Promise<Result<RouteResult>>
+}
+
 export interface RouteDeps {
   /** On a miss, wake the dead peer instead of returning offline (Ф2). */
   wake?: WakeFn
+  /** Ephemeral-target serial-queue delivery (M3); absent → normal routing. */
+  ephemeral?: EphemeralRouteDeps
 }
 
 function truncateTopic(raw: string | undefined): string | undefined {
@@ -483,6 +511,17 @@ export async function routeSend(
     message,
   })
 
+  // M3 wake_policy:"ephemeral" — an ephemeral target is NEVER injected into a live
+  // session and never woken synchronously here: the delivery is ALWAYS enqueued
+  // (per-peer disk FIFO) and drained one task per fresh session, asynchronously.
+  // ONE delivery path by design: no live/miss race, strict FIFO, a clean context
+  // window per task. Self-send is refused up front (a worker enqueueing to itself
+  // would deadlock its own die-after-reply reap on a forever-non-empty queue).
+  if (deps.ephemeral?.isEphemeral(peer.cwd)) {
+    if (caller.personality === peer.personality) return err('cannot send to self')
+    return deps.ephemeral.deliver({ peer, envelope, topic, runtime })
+  }
+
   const target = resolvePeerDeliveryTarget(personality, runtime, peer)
   if (target.ok) {
     if (target.value.address === caller.address) return err('cannot send to self')