@agfpd/iapeer 0.2.79 → 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.79",
+  "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

@@ -61,7 +61,7 @@ import {
   validateProfileStandard,
 } from '../identity/profileStandard.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
-import { installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
+import { ensureDaemonStarted, installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
 import { MARKETPLACE_NAME, onboardHost } from '../onboard/index.ts'
 import { readMemoryProvider } from '../status/index.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.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)
@@ -969,6 +969,14 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // reports the would-be actions without touching anything. --infra <csv> ALSO
         // onboards infra runtimes (§6): npx-install each package (auto-resolved) + deploy
         // its declared set. notifier → timer+watcher auto; telegram → operator-add after.
+        // STEP 0 (non-disableable): ensure the router daemon is up. Onboard is the
+        // explicit "set up the host" action, so starting the always-on daemon belongs
+        // here — the operator never types raw `launchctl bootstrap`. Idempotent (no-op
+        // if already loaded). A failure here is a real, host-breaking problem → exit 1.
+        const dstart = await ensureDaemonStarted({ dryRun: flags['dry-run'] === true, env })
+        const dLabel = dstart.state === 'would-start' ? 'would-start (dry-run)' : dstart.state
+        out(`daemon: ${dLabel}${dstart.healthy === false ? ' — UNHEALTHY' : ''}${dstart.detail ? ` — ${dstart.detail}` : ''}\n`)
+        const daemonFailed = dstart.state === 'failed' || dstart.healthy === false
         const r = onboardHost({ dryRun: flags['dry-run'] === true, env })
         for (const m of r.marketplaces) {
           out(`marketplace ${MARKETPLACE_NAME} @ ${m.runtime}: ${m.state}${m.detail ? ` — ${m.detail}` : ''}\n`)
@@ -1038,7 +1046,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
         out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
-        return r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
+        return daemonFailed || r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
       }
       case 'native-memory': {
         // The canonized runtime-memory lever (контракт «Слот памяти» §Native-память):
@@ -1174,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

@@ -23,11 +23,13 @@ import { DAEMON_PLIST_LABEL } from '../core/constants.ts'
 import { IapError } from '../core/errors.ts'
 import { pluginLogsDir } from '../storage/index.ts'
 import {
+  bootstrapDaemon,
   isFoundationOwnedPlist,
   launchAgentsDir,
   renderLaunchdPlist,
 } from '../launch/launchd.ts'
-import type { LaunchdPlistSpec } from '../launch/launchd.ts'
+import type { BootstrapState, LaunchdPlistSpec } from '../launch/launchd.ts'
+import { waitForDaemonHealthy } from '../update/index.ts'
 import {
   drainAllEphemeralQueues,
   drainEphemeralQueue,
@@ -450,6 +452,40 @@ export function installDaemonPlist(opts: InstallDaemonPlistOptions = {}): Instal
   return { path, changed: true }
 }
 
+export interface DaemonStartResult {
+  /** 'would-start' = dryRun report; otherwise the bootstrap outcome. */
+  state: BootstrapState | 'would-start'
+  /** Socket health after a (non-sandbox) bootstrap; undefined when not probed. */
+  healthy?: boolean
+  detail?: string
+}
+
+/**
+ * `iapeer onboard`'s first, non-disableable step: ensure the foundation daemon is up.
+ * Writes the plist if missing (idempotent write-if-changed — defensive when onboard
+ * runs on a host where the plist is absent), idempotently bootstraps it (no-op when
+ * already loaded — NOT a restart), then health-checks the socket. dryRun reports the
+ * intent without touching launchctl. Sandbox-safe: bootstrapDaemon + waitForDaemonHealthy
+ * both short-circuit under IAPEER_TEST_SANDBOX, so this never loads a real job in tests.
+ */
+export async function ensureDaemonStarted(
+  opts: { env?: NodeJS.ProcessEnv; dryRun?: boolean } = {},
+): Promise<DaemonStartResult> {
+  const env = opts.env ?? process.env
+  if (opts.dryRun) {
+    return {
+      state: 'would-start',
+      detail: 'install plist if missing + launchctl bootstrap com.agfpd.iapeer (idempotent) + health-check',
+    }
+  }
+  installDaemonPlist({ env })
+  const b = bootstrapDaemon(env)
+  if (b.state === 'failed') return { state: 'failed', detail: b.detail }
+  if (b.state === 'skipped-sandbox') return { state: 'skipped-sandbox', detail: b.detail }
+  const h = await waitForDaemonHealthy({ env })
+  return { state: b.state, healthy: h.healthy, detail: h.healthy ? undefined : h.detail }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // CLI — launchd-held process / foreground acceptance entrypoint
 // ─────────────────────────────────────────────────────────────────────────────
@@ -463,7 +499,7 @@ if (import.meta.main) {
     const { path: p, changed } = installDaemonPlist()
     process.stdout.write(
       `daemon plist ${changed ? 'written' : 'unchanged'}: ${p}\n` +
-        `NOT loaded. To start it live: launchctl bootstrap gui/$(id -u) ${p}\n`,
+        `NOT loaded. \`iapeer onboard\` starts it (idempotent); or manually: launchctl bootstrap gui/$(id -u) ${p}\n`,
     )
     process.exit(0)
   } else {

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/launch/launchd.ts

@@ -382,6 +382,33 @@ export function cycleDaemon(env: NodeJS.ProcessEnv = process.env): DaemonRestart
   return cycleLaunchdJob(DAEMON_PLIST_LABEL, join(launchAgentsDir(env), `${DAEMON_PLIST_LABEL}.plist`), env)
 }
 
+/**
+ * Ensure the foundation daemon (`com.agfpd.iapeer`) is LOADED in the gui domain — an
+ * IDEMPOTENT `launchctl bootstrap` (no-op when already loaded), NOT a restart. This is
+ * the "start it now" step `iapeer onboard` runs, so an operator never types raw
+ * launchctl. Composed on bootstrapJobCore (undead-job-safe wait-for-gone + backoff).
+ * SANDBOX FAIL-SAFE: under IAPEER_TEST_SANDBOX it never calls launchctl (`bootstrap
+ * gui/<uid>` is host-global regardless of IAPEER_ROOT), consulting BOTH the passed env
+ * and the process env — mirror of launchctlBootstrap's guard.
+ */
+export function bootstrapDaemon(env: NodeJS.ProcessEnv = process.env): BootstrapResult {
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox', label: DAEMON_PLIST_LABEL, detail: 'IAPEER_TEST_SANDBOX=1 — not loading a real launchd job' }
+  }
+  const uid = currentUid()
+  const plistPath = join(launchAgentsDir(env), `${DAEMON_PLIST_LABEL}.plist`)
+  const core = bootstrapJobCore(uid, DAEMON_PLIST_LABEL, plistPath, {
+    run: args => {
+      const r = spawnSync('launchctl', args, { encoding: 'utf8' })
+      return { status: r.status, stderr: r.stderr ?? '' }
+    },
+    sleepMs: ms => spawnSync('sleep', [String(ms / 1000)]),
+  })
+  return core.state === 'failed'
+    ? { state: 'failed', label: DAEMON_PLIST_LABEL, detail: core.detail }
+    : { state: core.state, label: DAEMON_PLIST_LABEL }
+}
+
 /**
  * Restart any launchd job onto the executable(s) currently referenced by its plist:
  * bootout → bootstrap, never kickstart. Used by the daemon update path AND by