@agfpd/iapeer 0.2.80 → 0.2.82

package/README.md

@@ -1,29 +1,77 @@
 # iapeer
 
-Ядро мультиагентной системы на одном хосте: реестр пиров, единый демон-роутер для обмена сообщениями между ними и команды управления — создание, запуск, усыпление, перезапуск, подключение к внешним каналам. Пиром может быть AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс; все адресуются одинаково через один протокол.
+**Host-level core for a team of AI agents on one machine.**
 
-## Ключевые возможности
+[![npm](https://img.shields.io/npm/v/@agfpd/iapeer)](https://www.npmjs.com/package/@agfpd/iapeer)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+[![platform](https://img.shields.io/badge/platform-macOS-lightgrey)](#quick-start)
 
-iapeer держит AI-агентов как **живые интерактивные сессии настоящего CLI** (Claude Code, Codex CLI) — со всем поведением реального CLI, а не headless-режим одноразовых вызовов (`claude -p`, `codex exec`). Поскольку это реальный интерактивный CLI, пиры работают в рамках обычной подписки на Claude Code (изменение тарификации headless-режима от 15 июня 2026 интерактивный CLI не затрагивает).
+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.
 
-Отдельные свойства ниже встречаются и в других инструментах; сильная сторона iapeer — их **комбинация целиком**:
+## How it works
 
-1. **Реальный интерактивный CLI в фоне.** Каждый AI-пир — полноценная сессия Claude Code или Codex CLI, поднятая в фоне и доступная по сообщению.
+```text
+send_to_peer(name, text)     ← from any peer
+        │
+        ▼
+router daemon   — always on; finds the recipient, checks liveness, delivers
+        │
+        ▼
+recipient peer  — asleep? the daemon wakes it and delivers on wake
+```
 
-2. **Постоянная сессия (persistent).** На входящее демон поднимает пира через возобновление (`--continue` / `--resume`) — диалог **продолжается**, а не начинается заново; контекст и история сохраняются между обращениями.
+## Quick start
 
-3. **Событийный warm-on-demand жизненный цикл.** Сессия «тёплая» → быстро обрабатывает входящие; после ~часа простоя демон закрывает её (idle-reap); новое входящее → демон поднимает заново **автоматически**, с возобновлением контекста. Жизненным циклом правит поток сообщений, а не присутствие человека: это не привязанный к разработчику TUI и не одноразовый воркер на задачу. Ресурсы заняты, только пока пир работает.
+Requirements: **macOS**, [bun](https://bun.sh) on `PATH`, `~/.local/bin` on `PATH`, and at least one agent runtime installed — Claude Code or Codex CLI (each AI peer is a live session of one).
 
-4. **Переносимость пиров между рантаймами.** Личность пира (`personality`) отделена от рантайма: один пир присутствует и в Claude, и в Codex, а основной рантайм переключается командой (`claude ↔ codex`) без потери идентичности и адресации.
+```sh
+# 1. install — the iapeer binary and the ~/.iapeer layout
+npx @agfpd/iapeer
 
-5. **Подключение человека к живой сессии.** `iapeer attach` открывает **живую** сессию пира прямо в вашем терминале через pty-супервизор — мышь, прокрутка и цвета работают нативно; отсоединение (`Ctrl-]`) сессию не закрывает.
+# 2. set up the host — starts the router daemon, then adds scheduler peers, Telegram, and shared memory
+iapeer onboard
 
-Целиком эту связку — событийный warm-on-demand жизненный цикл (не attached-разработчиком TUI и не воркер-на-задачу), переносимость пиров между рантаймами и единую ткань обмена (протокол IAP, память-vault с поиском, Telegram-мост) — даёт iapeer.
+# 3. create your first agent
+iapeer create assistant --runtime claude
 
-## Документация
+# 4. talk to it live in your terminal — detach with Ctrl-]
+iapeer attach assistant
+```
 
-Документация проекта — в [`docs/`](https://github.com/agfpd/iapeer/tree/main/docs): продуктовая часть (что это и как пользоваться) и механика изнутри ([`docs/internals/`](https://github.com/agfpd/iapeer/tree/main/docs/internals)). Этот репозиторий — кодовая реализация.
+**Already have a project folder?** In step 3, use `init` instead of `create`: `cd` into the project and register that folder itself as a peer.
 
-## Статус
+```sh
+cd ~/projects/myagent
+iapeer init
+```
 
-Платформа — macOS/launchd. Актуальная версия — в `package.json` / `iapeer version`.
+The peer's name is the folder name, normalized (`myagent`). `create` sets up a fresh folder under `~/.iapeer/peers/<name>`; `init` turns the folder you are in into a peer. The setup is identical either way.
+
+Two ways to work with an agent locally in your terminal:
+
+- **Join its live session** — `iapeer attach assistant`. The daemon wakes the peer first if it is asleep; detach with `Ctrl-]` and the session keeps running.
+- **Open a fresh session in the peer's folder** — go to the peer's directory and launch its runtime:
+
+  ```sh
+  cd ~/.iapeer/peers/assistant
+  iapeer claude
+  ```
+
+  This starts a full session with the peer's identity and doctrine and drops you straight into it. In effect, `iapeer claude` is `claude` for that peer — the same interactive CLI, but the session has a stable identity, its own memory, and an address other peers can reach.
+
+Agents reach each other with `send_to_peer`; you can also message any peer over Telegram.
+
+## What makes it different
+
+- **Real interactive CLI sessions, not headless one-shots.** Each AI peer is a full Claude Code or Codex CLI session, not a disposable `claude -p` / `codex exec` call.
+- **Warm-on-demand lifecycle.** A live session answers fast; after about an hour idle the daemon closes it; the next message brings it back with its context resumed. The message flow drives the lifecycle — not a human's presence.
+- **One identity across runtimes, with one memory.** A peer's `personality` is decoupled from its runtime — the same peer runs on Claude or Codex, switched with a command. By default (set up by `iapeer onboard`) it carries one shared memory (iapeer-memory) keyed to the personality, not the runtime: one personality, one memory, whatever runtime it runs on.
+- **Heterogeneous peers, one protocol.** AI agents, humans (Telegram), and services (timer = cron, watcher = event) are all first-class, addressed the same way over an always-on MCP daemon that exposes exactly one tool, `send_to_peer`.
+
+## Documentation
+
+[`docs/`](https://github.com/agfpd/iapeer/tree/main/docs) — the product side (what it is and how to use it); [`docs/internals/`](https://github.com/agfpd/iapeer/tree/main/docs/internals) — the mechanics from the inside. This repository is the implementation.
+
+## License
+
+Apache-2.0. Platform: macOS / launchd. iapeer is the foundation core of a larger ecosystem; runtime and capability plugins build on top of it.

package/package.json

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

package/src/cli/index.ts

@@ -915,7 +915,7 @@ const USAGE = `usage: iapeer <verb> [args]
   status                                                         host snapshot: version, daemon health, memory slot (<provider> | none)
   install-runtime <runtime> [--package pkg] [--npx]              npx-install a runtime package + deploy its declared peer-set
   update-runtime <runtime> | --all [--force]                     version-gate → re-install + re-provision declared set → restart the runtime's peers
-  init [cwd] [--personality p] [--runtime r] [--description d]   onboard the CURRENT folder as a peer (identity + MCP + doctrine)
+  init [cwd] [--runtime r] [--description d]                     onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)
   create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
   list [--json]                                                  registered peers + per-runtime liveness
   verify [--json] [--fix]                                        profile-standard conformance + index↔local drift (--fix self-heals the index + migrates legacy runtime→default_runtime in local profiles)
@@ -1182,11 +1182,16 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // cwd-DEPENDENT: onboard the CURRENT folder (or positional cwd) as a peer —
         // identity + MCP wiring + doctrine, runtime resolved from the cwd's markers
         // when not explicit. Auto-bootstraps an infra plist unless --no-bootstrap.
+        // A peer's name IS its folder name (normalize(basename(cwd))) — personality ↔ folder
+        // is 1:1, so `--personality` is gone: name the folder, don't pass a separate name.
+        if (flags.personality !== undefined) {
+          errOut("init: --personality was removed — a peer's name is its folder name; rename the folder to set the name\n")
+          return 2
+        }
         const { initPeer } = await import('../init/index.ts')
         const r = await initPeer({
           cwd: positionals[0] ?? process.cwd(),
           runtime: typeof flags.runtime === 'string' ? (flags.runtime as Runtime) : undefined,
-          personality: typeof flags.personality === 'string' ? flags.personality : undefined,
           description: typeof flags.description === 'string' ? flags.description : undefined,
           runtimeBin: typeof flags.bin === 'string' ? flags.bin : undefined,
           bootstrap: flags['no-bootstrap'] === true ? false : undefined,

package/src/daemon/main.ts

@@ -35,6 +35,7 @@ import {
   drainEphemeralQueue,
   enqueueEphemeralTask,
   isEphemeralPeer,
+  addTopic,
   loadLifecycleConfig,
   processEagerRelaunches,
   readTopic,
@@ -42,7 +43,6 @@ import {
   setEphemeralArmed,
   superviseTick,
   wakeOrSpawn,
-  writeTopic,
   type LifecycleConfig,
 } from '../lifecycle/index.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
@@ -135,8 +135,8 @@ export function makeNoteLiveTopic(
 ): (identity: string, topic: string) => void {
   return (identity, topic) => {
     try {
-      if (readTopic(cfg, identity) === topic) return
-      writeTopic(cfg, identity, topic)
+      if (readTopic(cfg, identity) === topic) return // unchanged most-recent → no shift, skip the note
+      addTopic(cfg, identity, topic) // accumulate into the session's topic set (a new live thread)
       appendLifecycleEvent(cfg.eventLogDir, { ev: 'topic-note', identity, topic }, { env })
     } catch {
       /* the marker is a discriminator hint — never fail a delivered message */

package/src/identity/index.ts

@@ -415,6 +415,19 @@ export function ensurePeerProfile(options: EnsurePeerProfileOptions): PeerProfil
     let personality: string
     if (options.personality !== undefined) {
       personality = validatePersonality(options.personality, 'personality')
+      // INVARIANT (personality ↔ folder is 1:1): an explicitly-supplied personality MUST
+      // equal the normalized cwd basename. Otherwise the registry record (personality) and
+      // a manual `cd <cwd>; <runtime>` session (which self-derives identity from the cwd
+      // basename) would disagree. The only ways to reach a mismatch are a runtime manifest
+      // `peers[].path` or `create --path <dir>` whose basename ≠ personality — both are
+      // misconfigurations, surfaced loudly here rather than written as a latent drift.
+      const expected = normalizeNameCandidate(basename(cwd))
+      if (personality !== expected) {
+        throw new IapError(
+          `personality "${personality}" must equal the normalized cwd basename "${expected}" ` +
+            `(personality ↔ folder is 1:1) — name the folder to match, or drop the explicit name. cwd: ${cwd}`,
+        )
+      }
       const collision = peerCollision(personality, cwd, peers)
       if (collision) {
         throw new IapError(

package/src/init/index.ts

@@ -17,6 +17,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { homedir } from 'os'
 import { join } from 'path'
 import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER, IAPEER_DIR, isInfraRuntime, type Runtime } from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
 import {
   ensureLocalIapScaffold,
   pluginStateDir,
@@ -257,11 +258,63 @@ export function ensureDoctrineTemplate(cwd: string): { path: string; created: bo
  * the old inconsistency where a `.codex`-only folder defaulted to claude as primary
  * yet got a codex config — now the primary matches the markers, deterministically.
  */
-export function resolvePrimaryRuntime(cwd: string, explicit?: Runtime): Runtime {
-  if (explicit) return explicit
+/**
+ * Is an AGENTIC runtime installed on this host? Checks (any hit ⇒ installed): env
+ * override (IAPEER_<RT>_BIN), the native installer location (~/.local/bin/claude), the
+ * bare name on PATH, and the runtime's global config dir (~/.claude / ~/.codex — a
+ * runtime that has ever run leaves one). SANDBOX: under IAPEER_TEST_SANDBOX it reports
+ * `true` (never probes the real host) — mirror of the install-side guards; a hermetic
+ * test that wants the real branches injects its own predicate into resolvePrimaryRuntime.
+ */
+export function isRuntimeInstalled(runtime: Runtime, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') return true
+  const override = runtime === 'claude' ? env.IAPEER_CLAUDE_BIN : runtime === 'codex' ? env.IAPEER_CODEX_BIN : undefined
+  if (override?.trim()) return true
+  const home = env.HOME?.trim() || homedir()
+  if (runtime === 'claude' && existsSync(join(home, '.local', 'bin', 'claude'))) return true
+  if (Bun.which(runtime)) return true
+  if (runtime === 'claude' && existsSync(join(home, '.claude'))) return true
+  if (runtime === 'codex' && existsSync(join(home, '.codex'))) return true
+  return false
+}
+
+const AGENTIC_RUNTIMES: Runtime[] = ['claude', 'codex']
+
+/**
+ * Resolve a peer's primary AGENTIC runtime — install-aware:
+ *   1. explicit (`--runtime`) → use it, but VALIDATE it is installed (clear error instead
+ *      of a silent launch failure later on an uninstalled runtime).
+ *   2. else a cwd runtime MARKER (.claude / .codex) → that runtime. The folder's already-
+ *      established config takes PRECEDENCE over install-presence (a folder configured for
+ *      X stays X even if Y is also installed; markers are not re-validated).
+ *   3. else from what is INSTALLED: exactly one → it; none → clear error (don't silently
+ *      default to claude on a host without it); both → claude (deterministic default —
+ *      resolution runs in non-interactive paths, so no prompt; `--runtime` picks codex).
+ * `isInstalled` is injectable for hermetic tests.
+ */
+export function resolvePrimaryRuntime(
+  cwd: string,
+  explicit?: Runtime,
+  isInstalled: (rt: Runtime) => boolean = rt => isRuntimeInstalled(rt),
+): Runtime {
+  if (explicit) {
+    if (!isInstalled(explicit)) {
+      throw new IapError(
+        `runtime "${explicit}" is not installed on this host — install it (Claude Code / Codex CLI) or choose an installed runtime`,
+      )
+    }
+    return explicit
+  }
   if (existsSync(join(cwd, '.claude'))) return 'claude'
   if (existsSync(join(cwd, '.codex'))) return 'codex'
-  return 'claude'
+  const installed = AGENTIC_RUNTIMES.filter(isInstalled)
+  if (installed.length === 1) return installed[0]!
+  if (installed.length === 0) {
+    throw new IapError(
+      `no agentic runtime installed (Claude Code or Codex CLI) — install one, then create/init the peer`,
+    )
+  }
+  return 'claude' // both installed → deterministic default; pass --runtime codex to pick codex
 }
 
 export interface InitPeerOptions {
@@ -319,7 +372,7 @@ export async function initPeer(opts: InitPeerOptions): Promise<InitPeerResult> {
   // Runtime-aware + CONSISTENT: an explicit runtime wins; else the cwd's markers
   // decide the primary (resolvePrimaryRuntime), so the primary always matches the
   // config that gets written (no `.codex`-only-but-primary-claude mismatch).
-  const runtime = resolvePrimaryRuntime(opts.cwd, opts.runtime)
+  const runtime = resolvePrimaryRuntime(opts.cwd, opts.runtime, rt => isRuntimeInstalled(rt, env))
   const provisioned = await provisionPeer({
     cwd: opts.cwd,
     runtime,

package/src/lifecycle/index.ts

@@ -376,27 +376,63 @@ function topicPath(cfg: LifecycleConfig, identity: string): string {
   return join(cfg.stateDir, `${identity}.topic`)
 }
 
-/** Read the stored topic of the current/last session (executor discriminator). '' if none. */
-export function readTopic(cfg: LifecycleConfig, identity: string): string {
+// Per-session TOPIC SET (executor resume discriminator). The `.topic` file holds the
+// topics this session lineage has touched — newline-separated, most-recent LAST, deduped
+// and capped. A peer can carry several threads in ONE session, so resume matches the
+// incoming topic against ANY topic in the set: a later ping on an earlier thread continues
+// that session's context instead of starting fresh and redoing work. The set is RESET on a
+// FRESH wake (new lineage) and ACCUMULATES on the wake topic + every live delivery topic.
+const MAX_SESSION_TOPICS = 16
+
+/** All topics the current session lineage has touched (most-recent last). [] if none. */
+export function readTopics(cfg: LifecycleConfig, identity: string): string[] {
   try {
-    return readFileSync(topicPath(cfg, identity), 'utf8').trim()
+    return readFileSync(topicPath(cfg, identity), 'utf8')
+      .split('\n')
+      .map(t => t.trim())
+      .filter(Boolean)
   } catch {
-    return ''
+    return []
   }
 }
 
-/** Store the session's working topic (raw string, best-effort). Two writers: the
- *  wake (boot topic, wakeOrSpawn) and live deliveries via the noteLiveTopic seam
- *  (makeNoteLiveTopic) — so the marker follows the work, not just the boot. */
-export function writeTopic(cfg: LifecycleConfig, identity: string, topic: string): void {
+/** The session's MOST-RECENT topic (last in the set), or '' — single-value back-compat read. */
+export function readTopic(cfg: LifecycleConfig, identity: string): string {
+  const t = readTopics(cfg, identity)
+  return t.length ? t[t.length - 1]! : ''
+}
+
+/** Is `topic` (non-empty) one of the session lineage's topics? Drives resume-vs-fresh. */
+export function hasTopic(cfg: LifecycleConfig, identity: string, topic: string): boolean {
+  const t = topic.trim()
+  return !!t && readTopics(cfg, identity).includes(t)
+}
+
+/** Add a topic to the session's set (most-recent-last, deduped, capped). Empty → no-op.
+ *  Two callers: the wake (boot topic, wakeOrSpawn) and live deliveries via the noteLiveTopic
+ *  seam (makeNoteLiveTopic) — so the set follows the work, not just the boot. Best-effort. */
+export function addTopic(cfg: LifecycleConfig, identity: string, topic: string): void {
+  const t = topic.trim()
+  if (!t) return
   mkdirSync(cfg.stateDir, { recursive: true, mode: 0o700 })
   try {
-    writeFileSync(topicPath(cfg, identity), topic, { mode: 0o600 })
+    const set = readTopics(cfg, identity).filter(x => x !== t)
+    set.push(t)
+    writeFileSync(topicPath(cfg, identity), set.slice(-MAX_SESSION_TOPICS).join('\n') + '\n', { mode: 0o600 })
   } catch {
     /* best-effort — topic is a discriminator hint, never blocks a wake */
   }
 }
 
+/** Drop the session's topic set — a FRESH wake starts a new lineage with no carried topics. */
+export function resetTopics(cfg: LifecycleConfig, identity: string): void {
+  try {
+    rmSync(topicPath(cfg, identity), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
 /**
  * Purge EVERY identity-keyed lifecycle artifact of `<identity>` from stateDir:
  * the marker files (`.stopped` / `.idle-reaped` / `.deaths` / `.topic` /
@@ -555,10 +591,17 @@ export function resolveWakeMode(
       ? { resume: true, resumeRef: r.ref, cause: 'idle-reaped-human' }
       : { resume: false, cause: 'idle-reaped-human-no-resume' }
   }
-  // executor: a NEW topic (non-empty and differing from the stored one) means new
-  // work → FRESH; same topic, or no incoming topic → continue the work → RESUME.
+  // executor: RESUME is an INTENTIONAL "continue THIS work" signal — it happens ONLY when
+  // the incoming message carries a topic that matches the session's last topic. A DIFFERENT
+  // topic (new work) OR NO topic at all → FRESH. Rationale: a topicless ping after an idle
+  // gap is not a request to resume specific work; defaulting it to resume revived stale
+  // context (e.g. a 3-day-old session). The sender opts INTO continuity by passing the topic.
   const topic = incomingTopic?.trim() ?? ''
-  if (topic && topic !== readTopic(cfg, identity)) return { resume: false, cause: 'idle-reaped-new-topic' }
+  if (!topic) return { resume: false, cause: 'idle-reaped-no-topic' }
+  // RESUME if the incoming topic matches ANY thread this session lineage worked on — not
+  // just the last. Different threads accumulate in one session; a later ping on an earlier
+  // thread continues that context. A topic the session never touched → new work → FRESH.
+  if (!hasTopic(cfg, identity, topic)) return { resume: false, cause: 'idle-reaped-new-topic' }
   const r = resolveResume(cwd)
   return r.ok
     ? { resume: true, resumeRef: r.ref, cause: 'idle-reaped-resume' }
@@ -1053,9 +1096,12 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // reply. ONLY here on the actual launch path, NEVER on the live-session fast path
     // above (a live session may be legitimately armed mid-quiet-window).
     clearEphemeralArmed(cfg, identity)
-    // Establish the session's topic (executor discriminator) and reset the crash-loop
-    // ring — a successful wake means this is NOT a tight crash loop. Best-effort.
-    writeTopic(cfg, identity, args.topic?.trim() ?? '')
+    // Establish/extend the session's topic SET (executor resume discriminator) and reset the
+    // crash-loop ring. A FRESH wake starts a new lineage → drop the old topic set; a RESUME
+    // keeps accumulating. The wake's own topic joins the set (no-op if empty). resolveWakeMode
+    // already read the OLD set above, so mutating here is safe. Best-effort.
+    if (!mode.resume) resetTopics(cfg, identity)
+    addTopic(cfg, identity, args.topic?.trim() ?? '')
     trimDeaths(cfg, identity, cfg.crashLoopWindowSecs, Date.now())
     return { status: 'READY', woke: true, runtime, process_address: identity, taskDelivered: true }
   })