@agfpd/iapeer 0.2.80 → 0.2.81

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.81",
   "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/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,