@agfpd/iapeer 0.1.0

package/src/transport/index.ts

@@ -0,0 +1,522 @@
+// Transport — liveness scan + delivery target resolution + tmux delivery, plus
+// the Ф1 route-and-deliver orchestration (NO wake yet — a miss returns an
+// explicit "offline" signal; wake-on-miss lands in Ф2). Consolidated from
+// inter-agent-protocol/src/lib/transport.ts (wins) + send.ts (rewritten so the
+// caller identity comes FROM THE REQUEST, not a per-process Identity).
+//
+// The TUI submit TIMING (inputHoldsPaste / submitIntoTui poll+re-press / deliver
+// ViaTmux byte layout) is ported BYTE-FOR-BYTE — it is the validated 0.7.6
+// deterministic submit and must not be refactored (anti-regression of the
+// Enter-swallow flap; blueprint §5 "submit-надёжность"). The ONLY contract-
+// sanctioned change (07.06 refactor, docs/Рантайм-адаптеры): the prompt glyphs /
+// paste patterns are no longer a hardcoded union here — they come from the target
+// runtime's adapter.deliveryMarkers. The poll/re-press logic is untouched; only the
+// marker SOURCE moved, so the timing behaviour is identical.
+
+import { readdirSync } from 'fs'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import {
+  MAX_ATTACHMENTS,
+  MAX_MESSAGE_LEN,
+  MAX_TOPIC_LEN,
+  isRuntime,
+  isSupportedLocalRuntime,
+  isValidName,
+  resolveSockDir,
+  type TmuxRuntime,
+} from '../core/constants.ts'
+import { err, ok, type Result } from '../core/errors.ts'
+import {
+  buildProcessAddress,
+  buildSocketPath,
+  parseSessionName,
+  parseSocketPath,
+  type ProcessAddress,
+} from '../core/socket.ts'
+import { buildEnvelope } from '../codec/index.ts'
+import { findPeer, readPeersIndex, type PeerRecord } from '../registry/index.ts'
+import type { ResolvedCaller } from '../identity/index.ts'
+// Delivery markers are OWNED by the runtime adapter (07.06 refactor). transport
+// reads them from getAdapter(target.runtime) for the tui submit path. One-way
+// dependency: launch does NOT import transport, so no cycle.
+import { getAdapter } from '../launch/index.ts'
+import type { ControlCommand, DeliveryMarkers } from '../launch/types.ts'
+
+export interface OnlinePeer {
+  personality: string
+  runtime: TmuxRuntime
+}
+
+export interface DeliveryTarget extends ProcessAddress {
+  socketPath: string
+}
+
+export interface TmuxResult {
+  ok: boolean
+  out: string
+  err: string
+}
+
+export function tmux(sock: string, ...args: string[]): TmuxResult {
+  const r = spawnSync('tmux', ['-S', sock, ...args], { encoding: 'utf8' })
+  return { ok: r.status === 0, out: r.stdout ?? '', err: r.stderr ?? '' }
+}
+
+// Settle delay between bracketed paste and the submit Enter — non-TUI path only.
+const PASTE_SETTLE_MS = (() => {
+  const raw = process.env.IAP_TMUX_PASTE_SETTLE_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 250
+})()
+
+const SUBMIT_POLL_MS = 40
+const SUBMIT_LANDED_TIMEOUT_MS = 1500
+const SUBMIT_CONFIRM_WINDOW_MS = 500
+function submitTotalTimeoutMs(): number {
+  const raw = process.env.IAP_TMUX_SUBMIT_TIMEOUT_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 4000
+}
+
+function sleepSync(ms: number): void {
+  if (ms <= 0) return
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+function monotonicMs(): number {
+  return Number(process.hrtime.bigint() / 1_000_000n)
+}
+
+function listSessions(sock: string): string[] {
+  const r = tmux(sock, 'list-sessions', '-F', '#{session_name}')
+  if (!r.ok) return []
+  return r.out.split(/\r?\n/).map(line => line.trim()).filter(Boolean)
+}
+
+function sessionAlive(sock: string, address: string): boolean {
+  return listSessions(sock).includes(address)
+}
+
+/** Is the (runtime,personality) endpoint live right now? Public liveness predicate. */
+export function isPeerLive(runtime: string, personality: string, sockDir = resolveSockDir()): boolean {
+  const socketPath = buildSocketPath(runtime, personality, sockDir)
+  return sessionAlive(socketPath, buildProcessAddress(runtime, personality))
+}
+
+export function listOnlinePeers(sockDir = resolveSockDir()): OnlinePeer[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(sockDir)
+  } catch {
+    return []
+  }
+  const out = new Map<string, OnlinePeer>()
+  for (const entry of entries) {
+    const parsedSocket = parseSocketPath(join(sockDir, entry))
+    if (!parsedSocket) continue
+    for (const sessionName of listSessions(join(sockDir, entry))) {
+      const parsedSession = parseSessionName(sessionName)
+      if (!parsedSession) continue
+      if (parsedSession.address !== parsedSocket.address) continue
+      out.set(parsedSession.address, {
+        personality: parsedSession.personality,
+        runtime: parsedSession.runtime,
+      })
+    }
+  }
+  return Array.from(out.values()).sort(
+    (a, b) =>
+      a.personality.localeCompare(b.personality) || a.runtime.localeCompare(b.runtime),
+  )
+}
+
+export function resolveDeliveryTarget(args: {
+  personality: string
+  runtime?: string
+  sockDir?: string
+}): Result<DeliveryTarget> {
+  const sockDir = args.sockDir ?? resolveSockDir()
+  if (!isValidName(args.personality)) {
+    return err(`invalid personality "${args.personality}" — must match /^[a-z][a-z0-9-]{0,31}$/`)
+  }
+  if (args.runtime) {
+    if (!isRuntime(args.runtime)) return err(`invalid runtime "${args.runtime}"`)
+    const runtime = args.runtime
+    const socketPath = buildSocketPath(runtime, args.personality, sockDir)
+    const address = buildProcessAddress(runtime, args.personality)
+    if (!sessionAlive(socketPath, address)) {
+      return err(`peer offline: ${args.personality} (${args.runtime})`)
+    }
+    return ok({ runtime, personality: args.personality, address, socketPath })
+  }
+  const matches = listOnlinePeers(sockDir).filter(peer => peer.personality === args.personality)
+  if (matches.length === 0) return err(`peer offline: ${args.personality}`)
+  if (matches.length > 1) {
+    return err(
+      `${args.personality} is online in multiple runtimes (${matches
+        .map(peer => peer.runtime)
+        .join(', ')}) — specify runtime`,
+    )
+  }
+  const match = matches[0]
+  const socketPath = buildSocketPath(match.runtime, match.personality, sockDir)
+  return ok({
+    runtime: match.runtime,
+    personality: match.personality,
+    address: buildProcessAddress(match.runtime, match.personality),
+    socketPath,
+  })
+}
+
+export function resolvePeerDeliveryTarget(
+  personality: string,
+  runtime: string | undefined,
+  peer: PeerRecord,
+): Result<DeliveryTarget> {
+  if (runtime) return resolveDeliveryTarget({ personality, runtime })
+  if (peer.runtime) {
+    const exactDefault = resolveDeliveryTarget({ personality, runtime: peer.runtime })
+    if (exactDefault.ok) return exactDefault
+  }
+  return resolveDeliveryTarget({ personality })
+}
+
+// ─── TUI submit (ported byte-for-byte from transport.ts) ────────────────────
+
+function inputHoldsPaste(
+  sock: string,
+  address: string,
+  tailMarker: string,
+  markers: DeliveryMarkers,
+): boolean {
+  const cap = tmux(sock, 'capture-pane', '-p', '-t', address)
+  if (!cap.ok) return true
+  const lines = cap.out.split('\n')
+  let promptRow = -1
+  for (let i = 0; i < lines.length; i++) {
+    const ch = lines[i]?.[0] ?? ''
+    if (markers.promptGlyphs.includes(ch)) promptRow = i
+  }
+  if (promptRow < 0) return true
+  const band = lines.slice(promptRow).join('\n')
+  if (band.includes(tailMarker)) return true
+  return markers.pastePatterns?.some(re => re.test(band)) ?? false
+}
+
+// Returns TRUE iff the input cleared after Enter within the budget — i.e. an
+// (idle, responsive) TUI accepted the submit. FALSE on timeout (the input never
+// cleared): either a DEAD/hung session, OR a BUSY session mid-turn whose input row
+// is not even rendered (then liveness is confirmed by the transcript-mtime advance
+// in deliverViaTmux, not here). The poll/re-press TIMING is the byte-for-byte 0.7.6
+// port; only the return value is new (Ф-B: feed the delivery-liveness decision).
+function submitIntoTui(sock: string, address: string, envelope: string, markers: DeliveryMarkers): boolean {
+  const tailMarker =
+    envelope.split('\n').map(line => line.trim()).filter(Boolean).pop() ?? envelope.trim()
+  const start = monotonicMs()
+  while (monotonicMs() - start < SUBMIT_LANDED_TIMEOUT_MS) {
+    if (inputHoldsPaste(sock, address, tailMarker, markers)) break
+    sleepSync(SUBMIT_POLL_MS)
+  }
+  while (monotonicMs() - start < submitTotalTimeoutMs()) {
+    tmux(sock, 'send-keys', '-t', address, 'Enter')
+    const windowStart = monotonicMs()
+    while (
+      monotonicMs() - windowStart < SUBMIT_CONFIRM_WINDOW_MS &&
+      monotonicMs() - start < submitTotalTimeoutMs()
+    ) {
+      sleepSync(SUBMIT_POLL_MS)
+      if (!inputHoldsPaste(sock, address, tailMarker, markers)) return true
+    }
+  }
+  return false
+}
+
+// Ф-B liveness: how long to keep polling the activity proxy for a transcript
+// advance when the submit did NOT clear the input (a busy session whose input row
+// is not rendered). Env-tunable for LIVE calibration (busy/idle/cold). Conservative
+// default — long enough that a busy-but-alive session reliably shows an advance,
+// short enough that a genuinely dead session is failed promptly. Prefer a false-
+// FAIL (sender retries) over a false-OK (silent loss, which the contract forbids).
+const LIVENESS_POLL_MS = 100
+function livenessGraceMs(): number {
+  const raw = process.env.IAP_LIVENESS_GRACE_MS
+  const n = raw === undefined ? NaN : Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 3000
+}
+
+/**
+ * Deliver `envelope` into the target's tmux session and CONFIRM it landed in a LIVE
+ * session (Ф-B delivery guarantee, contract Демон §Гарантия доставки). `cwd` (the
+ * target peer's working dir) enables the transcript-mtime liveness probe; omit it and
+ * the tui path falls back to submit-confirmation only (existing direct callers/tests).
+ *
+ * tui liveness — ok ⟺ message landed in a live session, by EITHER strong signal:
+ *   (a) submit confirmed — the input cleared after Enter (an idle session accepted it);
+ *   (b) transcript-mtime advanced past the pre-submit baseline (a BUSY session is
+ *       mid-turn — our message is queued and surfaces on its next tool call).
+ * Neither within the grace budget → the session is listed live but UNRESPONSIVE
+ * (dead/hung) → fail LOUDLY. Silent loss is forbidden; when in doubt prefer a false-
+ * FAIL (sender retries) over a false-OK. router (telegram/notifier) is always-on by
+ * launchd → its liveness is structural, the C-j path keeps its prior semantics.
+ */
+export function deliverViaTmux(target: DeliveryTarget, envelope: string, cwd?: string): Result<void> {
+  const bufferName = `iap-${process.pid}-${Date.now()}`
+  const load = spawnSync(
+    'tmux',
+    ['-S', target.socketPath, 'load-buffer', '-b', bufferName, '-'],
+    { input: envelope, encoding: 'utf8' },
+  )
+  if (load.status !== 0) {
+    return err(`tmux load-buffer failed: ${(load.stderr ?? '').trim() || `exit ${load.status}`}`)
+  }
+  const isTui = isSupportedLocalRuntime(target.runtime)
+  const pasteArgs = isTui
+    ? ['paste-buffer', '-p', '-b', bufferName, '-t', target.address]
+    : ['paste-buffer', '-p', '-r', '-b', bufferName, '-t', target.address]
+  const paste = tmux(target.socketPath, ...pasteArgs)
+  if (!paste.ok) {
+    tmux(target.socketPath, 'delete-buffer', '-b', bufferName)
+    return err(`tmux paste-buffer failed: ${paste.err.trim() || 'unknown error'}`)
+  }
+  if (isTui) {
+    const adapter = getAdapter(target.runtime)
+    // Baseline the activity proxy BEFORE the submit (a paste does not move the
+    // transcript — only a model turn does), so an advance afterwards proves a busy
+    // session is alive. null proxy / no cwd → 0 (the advance check is skipped below).
+    const baselineMtime = cwd ? adapter.newestActivityMtime(cwd) ?? 0 : 0
+    // Submit markers come from the target runtime's adapter (07.06 refactor).
+    const confirmed = submitIntoTui(target.socketPath, target.address, envelope, adapter.deliveryMarkers)
+    tmux(target.socketPath, 'delete-buffer', '-b', bufferName)
+    if (confirmed) return ok(undefined) // idle session accepted the submit
+    if (!cwd) return ok(undefined) // no activity proxy available → confirmed-only (legacy callers)
+    // Busy session: the input never cleared, so confirm liveness by a transcript
+    // advance. Grace-poll the proxy (the model may take a beat to write its turn).
+    const graceDeadline = monotonicMs() + livenessGraceMs()
+    do {
+      if ((adapter.newestActivityMtime(cwd) ?? 0) > baselineMtime) return ok(undefined)
+      sleepSync(LIVENESS_POLL_MS)
+    } while (monotonicMs() < graceDeadline)
+    return err(
+      `peer "${target.personality}" (${target.runtime}) is listed live but did not accept the message ` +
+        `(no input-clear, no transcript advance within ${livenessGraceMs()}ms) — treated as dead; message NOT delivered`,
+    )
+  }
+  sleepSync(PASTE_SETTLE_MS)
+  const enter = tmux(target.socketPath, 'send-keys', '-t', target.address, 'C-j')
+  tmux(target.socketPath, 'delete-buffer', '-b', bufferName)
+  if (!enter.ok) return err(`tmux send-keys failed: ${enter.err.trim() || 'unknown error'}`)
+  return ok(undefined)
+}
+
+// ─── Control channel (Ф-E) — in-session control via the adapter, UNCONDITIONAL ──
+
+/**
+ * Perform an in-session control command on a LIVE target (Ф-E, docs/Control-команды).
+ * The target's adapter maps the abstract command to a tmux send-keys sequence
+ * (ControlPlan); each step is sent IN ORDER, UNCONDITIONALLY — NO ready-gate, NO
+ * submit-confirm (the point of `interrupt` is to break a stuck/raving turn exactly
+ * when normal delivery would not land). An unsupported command (router runtimes,
+ * unknown name) → explicit refusal, not a silent no-op.
+ */
+export function executeControlOnTarget(target: DeliveryTarget, command: ControlCommand): Result<void> {
+  const plan = getAdapter(target.runtime).executeControl(command)
+  if (!plan) {
+    return err(`runtime "${target.runtime}" does not support control command "${command.name}"`)
+  }
+  for (const keys of plan.sequence) {
+    const r = tmux(target.socketPath, 'send-keys', '-t', target.address, ...keys)
+    if (!r.ok) return err(`tmux send-keys failed for control "${command.name}": ${r.err.trim() || 'unknown error'}`)
+    if (plan.stepDelayMs) sleepSync(plan.stepDelayMs)
+  }
+  return ok(undefined)
+}
+
+export interface ControlResult {
+  ok: true
+  controlled: { personality: string; runtime: string }
+  command: string
+  ts: string
+}
+
+/**
+ * Route an in-session control command to a peer: resolve the LIVE target (control
+ * acts on a running session — a non-live peer has nothing to interrupt) then
+ * executeControlOnTarget. Without a runtime, resolves the single live runtime (2+ →
+ * "specify runtime"). The clean-slash control namespace (interrupt/compact/…) is the
+ * caller's; /alias-* expansions are message, not control (docs/Control §namespace).
+ */
+export function routeControl(personality: string, runtime: string | undefined, command: ControlCommand): Result<ControlResult> {
+  if (!isValidName(personality)) {
+    return err(`invalid personality "${personality}" — must match /^[a-z][a-z0-9-]{0,31}$/`)
+  }
+  if (runtime && !isRuntime(runtime)) return err(`invalid runtime "${runtime}"`)
+  const target = resolveDeliveryTarget({ personality, runtime })
+  if (!target.ok) return err(`cannot control "${personality}": ${target.error.message}`)
+  const done = executeControlOnTarget(target.value, command)
+  if (!done.ok) return done
+  return ok({
+    ok: true,
+    controlled: { personality: target.value.personality, runtime: target.value.runtime },
+    command: command.name,
+    ts: new Date().toISOString(),
+  })
+}
+
+// ─── Route + deliver orchestration (Ф1: no wake; miss → explicit offline) ────
+
+export interface SendToPeerInput {
+  personality: string
+  runtime?: string
+  message: string
+  topic?: string
+  attachments?: readonly string[]
+}
+
+export interface RouteResult {
+  ok: true
+  delivered_to: { personality: string; runtime: string }
+  woke: boolean
+  ts: string
+}
+
+// WakeFn — the lifecycle wake primitive, INJECTED (transport never imports
+// lifecycle; the daemon wires lifecycle.wakeOrSpawn as this contract — §2). H4
+// (don't wake launchd peers) and the wake-runtime choice live inside the impl.
+export interface WakeRequest {
+  personality: string
+  runtime?: string
+  topic?: string
+  /** First message delivered to the woken session (the routed envelope). */
+  task: string
+}
+export interface WakeOutcome {
+  status: 'READY' | 'FAILED'
+  woke: boolean
+  runtime?: string
+  process_address?: string
+  reason?: string
+  /** C1: the peer is durably STOPPED (a deliberate operator halt) — the wake was
+   *  refused, not failed. routeSend surfaces an explicit "stopped" error to the
+   *  sender (contract Демон §stopped: stopped → no wake, no queue, clear error). */
+  stopped?: boolean
+}
+export type WakeFn = (req: WakeRequest) => Promise<WakeOutcome>
+
+export interface RouteDeps {
+  /** On a miss, wake the dead peer instead of returning offline (Ф2). */
+  wake?: WakeFn
+}
+
+function truncateTopic(raw: string | undefined): string | undefined {
+  if (!raw) return undefined
+  return raw.slice(0, MAX_TOPIC_LEN)
+}
+
+function validateAttachments(value: readonly string[] = []): Result<string[]> {
+  if (value.length > MAX_ATTACHMENTS) return err(`attachments exceeds ${MAX_ATTACHMENTS} item limit`)
+  const out: string[] = []
+  for (const item of value) {
+    if (typeof item !== 'string' || !item.startsWith('/')) {
+      return err('attachments must contain only absolute local paths')
+    }
+    // Audit #17: a newline in a path corrupts the envelope's attachments framing (paths
+    // are joined by '\n') — reject it rather than emit a malformed envelope.
+    if (/[\n\r]/.test(item)) {
+      return err('attachment paths must not contain newline characters')
+    }
+    out.push(item)
+  }
+  return ok(out)
+}
+
+/**
+ * Route a send from a request-resolved caller to a target peer and deliver it.
+ *  hit (live)  → build envelope from the CALLER → deliverViaTmux → {woke:false}
+ *  miss (dead) → if deps.wake: wake the peer (envelope = boot first-message) →
+ *                verify-before-act re-resolve → {woke:true}; else explicit
+ *                "offline" (Ф1 behaviour). H4 (don't wake launchd peers) and the
+ *                wake-runtime choice live INSIDE the injected WakeFn.
+ * "cannot send to self" compares the resolved target address with the CALLER's
+ * address from the request, not a per-process identity.
+ */
+export async function routeSend(
+  caller: ResolvedCaller,
+  input: SendToPeerInput,
+  deps: RouteDeps = {},
+): Promise<Result<RouteResult>> {
+  const { personality, runtime, message } = input
+  const topic = truncateTopic(input.topic)
+  const attachmentsResult = validateAttachments(input.attachments ?? [])
+  if (!attachmentsResult.ok) return attachmentsResult
+
+  if (!personality || !message) {
+    return err('send_to_peer requires non-empty "personality" and "message"')
+  }
+  if (!isValidName(personality)) {
+    return err(`invalid personality "${personality}" — must match /^[a-z][a-z0-9-]{0,31}$/`)
+  }
+  if (runtime && !isRuntime(runtime)) {
+    return err(`invalid runtime "${runtime}"`)
+  }
+  if (input.topic && input.topic.length > MAX_TOPIC_LEN) {
+    return err(`topic exceeds ${MAX_TOPIC_LEN} char limit (got ${input.topic.length})`)
+  }
+  if (message.length > MAX_MESSAGE_LEN) {
+    return err(`message exceeds ${MAX_MESSAGE_LEN} char limit (got ${message.length})`)
+  }
+
+  const index = readPeersIndex()
+  const peer = findPeer(index, personality)
+  if (!peer) {
+    return err(`peer "${personality}" is not in the IAPeer peers index; message NOT delivered`)
+  }
+
+  // Built once — it is both the live-delivery payload and, on a miss, the wake
+  // first-message (the woken session receives it as its boot task).
+  const envelope = buildEnvelope({
+    fromPersonality: caller.personality,
+    fromRuntime: caller.runtime,
+    fromIntelligence: caller.intelligence,
+    topic,
+    attachments: attachmentsResult.value,
+    message,
+  })
+
+  const target = resolvePeerDeliveryTarget(personality, runtime, peer)
+  if (target.ok) {
+    if (target.value.address === caller.address) return err('cannot send to self')
+    // peer.cwd enables the Ф-B transcript-mtime liveness probe (busy-session case).
+    const delivered = deliverViaTmux(target.value, envelope, peer.cwd)
+    if (!delivered.ok) return delivered
+    return ok({
+      ok: true,
+      delivered_to: { personality: target.value.personality, runtime: target.value.runtime },
+      woke: false,
+      ts: new Date().toISOString(),
+    })
+  }
+
+  // MISS — peer offline.
+  if (!deps.wake) return target // Ф1: explicit offline, no wake
+  const woke = await deps.wake({ personality, runtime, topic, task: envelope })
+  if (woke.status === 'FAILED') {
+    // C1 — a durably STOPPED peer is a deliberate halt, not a transient miss:
+    // surface the explicit "stopped" reason (no "offline and wake failed" wrapping).
+    if (woke.stopped) return err(woke.reason ?? `peer "${personality}" is stopped and not accepting messages`)
+    return err(`peer "${personality}" offline and wake failed: ${woke.reason ?? 'unknown'}`)
+  }
+  // verify-before-act: re-resolve the now-live target before declaring success.
+  const live = resolvePeerDeliveryTarget(personality, woke.runtime, peer)
+  if (!live.ok) {
+    return err(`woke "${personality}" but the session is not live (verify-before-act): ${live.error.message}`)
+  }
+  if (live.value.address === caller.address) return err('cannot send to self')
+  // The envelope was delivered as the boot first-message during wake.
+  return ok({
+    ok: true,
+    delivered_to: { personality: live.value.personality, runtime: live.value.runtime },
+    woke: true,
+    ts: new Date().toISOString(),
+  })
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["bun", "node"],
+    "lib": ["ESNext"]
+  },
+  "include": ["src/**/*.ts"]
+}