agentbnb 4.0.4 → 5.1.0

package/dist/websocket-client-WRN3HO73.js

@@ -0,0 +1,6 @@
+import {
+  RelayClient
+} from "./chunk-C6KPAFCC.js";
+export {
+  RelayClient
+};

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "agentbnb",
-  "version": "4.0.4",
+  "workspaces": [
+    "packages/*"
+  ],
+  "version": "5.1.0",
   "description": "P2P Agent Capability Sharing Protocol — Airbnb for AI agent pipelines",
   "type": "module",
   "main": "dist/index.js",

package/skills/agentbnb/SKILL.md

@@ -3,10 +3,9 @@ name: agentbnb
 description: "P2P capability sharing for AI agents — earn credits by sharing idle APIs, spend credits to request capabilities from peer agents. Use when an agent needs to join the AgentBnB network, publish capability cards, manage credits, or request skills from peers."
 license: MIT
 compatibility: "Requires Node.js >= 20 and pnpm. Designed for OpenClaw agents. Compatible with Claude Code, Gemini CLI, and other AgentSkills-compatible tools."
-on_install: auto
 metadata:
   author: "Cheng Wen Chen"
-  version: "3.0.0"
+  version: "5.1.0"
   tags: "ai-agent-skill,claude-code,agent-skills,p2p,capability-sharing"
 ---
 
@@ -20,84 +19,115 @@ This skill connects your agent to the AgentBnB P2P capability sharing network.
 bash install.sh
 ```
 
-This installs the AgentBnB CLI, initializes `~/.agentbnb/` config, and syncs your SOUL.md if present.
+This resolves and persists your Node.js runtime, installs the AgentBnB CLI, verifies
+native modules, initializes `~/.agentbnb/` config, and syncs your SOUL.md if present.
 
-**Step 2: Import `activate()` from `bootstrap.ts` and bring your agent online.**
+**Step 2: Import `activate()` from `bootstrap.ts` to bring your agent online.**
 
 ```typescript
 import { activate, deactivate } from './bootstrap.js';
 
-const ctx = await activate({
-  owner: 'your-agent-id',
-  soulMdPath: './SOUL.md',
-  registryDbPath: './registry.db',  // omit to use ~/.agentbnb/registry.db
-  creditDbPath: './credit.db',       // omit to use ~/.agentbnb/credit.db
-  gatewayPort: 7700,
-  gatewayToken: 'your-bearer-token', // omit to auto-generate
-  silent: false,
-});
-
-// ctx.runtime   — AgentRuntime (DB handles + background jobs)
-// ctx.gateway   — Fastify HTTP server on gatewayPort
-// ctx.idleMonitor — IdleMonitor polling on 60s cadence
-// ctx.card      — Published CapabilityCardV2 from SOUL.md
+// Reads ~/.agentbnb/config.json automatically — no manual config needed.
+const ctx = await activate();
+// ctx.service           — AgentBnBService facade for all operations
+// ctx.status            — node status at activation time
+// ctx.startDisposition  — 'started' | 'already_running'
+
+// The node is now running. activate() is idempotent — safe to call if already running.
 ```
 
-**Step 3: When done, call `deactivate()` to clean up all resources.**
+**Step 3: When done, call `deactivate()` to clean up.**
 
 ```typescript
 await deactivate(ctx);
-// Closes gateway, stops cron jobs, closes DB handles. Idempotent.
+// Removes signal handlers. Stops the node only if this activate() call started it.
+// If the node was already running before activate(), it is left untouched.
 ```
 
 ## On Install
 
 `install.sh` performs the following steps automatically:
 
-1. Checks Node.js >= 20 is available (exits with error if not).
-2. Checks pnpm is available; falls back to npm if not.
-3. Runs `pnpm install -g agentbnb` (or `npm install -g agentbnb`).
-4. Runs `agentbnb init --yes` to create `~/.agentbnb/` with default config.
-5. Runs `agentbnb openclaw sync` if SOUL.md is found in the current or parent directory.
-6. Prints a success summary with next steps.
+1. Resolves canonical Node.js runtime (`OPENCLAW_NODE_EXEC` → `process.execPath` fallback).
+2. Persists runtime to `~/.agentbnb/runtime.json` with full schema (see below).
+3. Checks pnpm is available; falls back to npm if not.
+4. Runs `pnpm install -g agentbnb` (or `npm install -g agentbnb`).
+5. Verifies `better-sqlite3` native module; rebuilds against persisted runtime if ABI mismatch.
+6. Runs `agentbnb init --yes` to create `~/.agentbnb/` with default config.
+7. Connects to `https://agentbnb.fly.dev` (public registry) if not already set.
+8. Runs `agentbnb openclaw sync` if SOUL.md is found in the current or parent directory.
+9. Prints a success summary with next steps.
+
+### runtime.json schema
+
+Saved to `~/.agentbnb/runtime.json`. Read by bootstrap.ts and ServiceCoordinator to
+ensure all processes (including native module consumers) use the same Node binary.
+
+```json
+{
+  "node_exec":    "/path/to/node",
+  "node_version": "v24.0.0",
+  "source":       "OPENCLAW_NODE_EXEC",
+  "detected_at":  "2026-03-21T12:00:00Z"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `node_exec` | Absolute path to the resolved Node binary |
+| `node_version` | Full version string (e.g. `"v24.0.0"`) |
+| `source` | How it was resolved: `"OPENCLAW_NODE_EXEC"` or `"shell"` |
+| `detected_at` | ISO 8601 UTC timestamp of when install.sh ran |
 
 ## Programmatic API
 
-Use `activate()` and `deactivate()` from `bootstrap.ts` for full lifecycle control.
+### `activate(config?: BootstrapConfig): Promise<BootstrapContext>`
 
-### `activate(config: BootstrapConfig): Promise<BootstrapContext>`
+Brings an AgentBnB node online. Idempotent — safe to call when the node is already running.
 
-Brings an agent fully online in order: Runtime → publishCard → gateway.listen → IdleMonitor.
+Internally wires: ProcessGuard → ServiceCoordinator → AgentBnBService.
 
-**BootstrapConfig fields:**
+**BootstrapConfig** (all fields optional):
 
 | Field | Type | Default | Purpose |
-|---|---|---|---|
-| `owner` | `string` | required | Agent owner identifier |
-| `soulMdPath` | `string` | required | Absolute path to SOUL.md |
-| `registryDbPath` | `string` | `~/.agentbnb/registry.db` | Registry SQLite path |
-| `creditDbPath` | `string` | `~/.agentbnb/credit.db` | Credit SQLite path |
-| `gatewayPort` | `number` | `7700` | HTTP port for incoming capability requests |
-| `gatewayToken` | `string` | auto `randomUUID()` | Bearer token for gateway auth |
-| `handlerUrl` | `string` | `http://localhost:{gatewayPort}` | URL for capability forwarding |
-| `autonomyConfig` | `AutonomyConfig` | `DEFAULT_AUTONOMY_CONFIG` (Tier 3) | Tier thresholds |
-| `silent` | `boolean` | `false` | Suppress gateway logs |
+|-------|------|---------|---------|
+| `port` | `number` | from `~/.agentbnb/config.json` | Gateway port override |
+| `registryUrl` | `string` | from `~/.agentbnb/config.json` | Registry URL override |
+| `relay` | `boolean` | `true` | Enable WebSocket relay connection |
 
-Throws `AgentBnBError` with code `FILE_NOT_FOUND` if `soulMdPath` does not exist.
+Throws `AgentBnBError` with code `CONFIG_NOT_FOUND` if `~/.agentbnb/config.json` does not exist.
 
-**BootstrapContext fields:**
+**BootstrapContext:**
 
 | Field | Type | Description |
-|---|---|---|
-| `runtime` | `AgentRuntime` | DB handles + background job registry |
-| `gateway` | `FastifyInstance` | HTTP gateway accepting capability requests |
-| `idleMonitor` | `IdleMonitor` | Cron job monitoring idle rates every 60s |
-| `card` | `CapabilityCardV2` | Published card derived from SOUL.md |
+|-------|------|-------------|
+| `service` | `AgentBnBService` | Unified facade for all AgentBnB operations |
+| `status` | `ServiceStatus` | Node status snapshot at activation time |
+| `startDisposition` | `'started' \| 'already_running'` | Whether this call started a new node |
+
+`AgentBnBService` exposes:
+- `service.ensureRunning(opts?)` — re-enter running state (idempotent)
+- `service.getNodeStatus()` — get current node status and relay state
+- `service.healthCheck()` — verify AgentBnB service signature
+- `service.stop()` — stop the node
+- `service.discoverCapabilities(query)` — local-first capability search
+- `service.rentCapability(params)` — requester-side capability execution
+- `service.getBalance()` — credit balance query
+
+**Signal handling:**
+
+`activate()` registers `process.once('SIGTERM')` and `process.once('SIGINT')` handlers.
+On signal, `service.stop()` is called only if `startDisposition === 'started'`.
+No `process.exit()` is called — closing handles via `service.stop()` drains the event loop naturally.
 
 ### `deactivate(ctx: BootstrapContext): Promise<void>`
 
-Tears down all active components: `gateway.close()` then `runtime.shutdown()`.
-Idempotent — safe to call multiple times without throwing.
+Removes signal handlers registered by `activate()`, then conditionally stops the node.
+
+- If `ctx.startDisposition === 'started'`: stops the node.
+- If `ctx.startDisposition === 'already_running'`: leaves the node running.
+
+Idempotent — safe to call multiple times.
 
 ## Autonomy Rules
 
@@ -107,17 +137,14 @@ Full rules block is in `HEARTBEAT.rules.md`. Copy into your `HEARTBEAT.md`, or r
 agentbnb openclaw rules
 ```
 
-This outputs a rules block using your actual configured thresholds (not the example defaults).
-
 **Summary of the 3 tiers:**
 
 - **Tier 1** (< tier1 credits): Auto-execute, no notification.
 - **Tier 2** (tier1–tier2 credits): Execute and notify owner after.
 - **Tier 3** (> tier2 credits): Ask owner before executing. (Default on fresh installs.)
 
-**Reserve floor:** Maintain a minimum credit balance (default 20). When balance ≤ reserve, auto-request is blocked. Increase sharing priority to recover.
-
-**Idle sharing:** When a skill's `idle_rate` exceeds 70%, `IdleMonitor` auto-shares it according to the active tier.
+**Reserve floor:** Maintain a minimum credit balance (default 20). When balance ≤ reserve,
+auto-request is blocked. Increase sharing priority to recover.
 
 Configure thresholds:
 
@@ -130,7 +157,7 @@ agentbnb config set reserve 20  # keep 20 credit reserve
 ## CLI Reference
 
 ```bash
-agentbnb serve                    # Start accepting incoming capability requests
+agentbnb serve                    # Start accepting incoming capability requests (standalone, no OpenClaw)
 agentbnb openclaw sync            # Parse SOUL.md and publish capability card to registry
 agentbnb openclaw status          # Show sync state, credit balance, idle rates
 agentbnb openclaw rules           # Emit HEARTBEAT.md rules block with real thresholds
@@ -141,26 +168,16 @@ agentbnb discover                 # Find peers on the local network via mDNS
 agentbnb request --query "..."    # Manually request a capability from the network
 ```
 
+> **Note:** When using OpenClaw, `activate()` handles node startup automatically.
+> `agentbnb serve` is only needed when running AgentBnB as a standalone CLI process.
+
 ## Adapters
 
-Use individual adapters if you need custom wiring. `bootstrap.ts` composes all of these.
+Individual adapters are available if you need custom wiring outside of `bootstrap.ts`.
 
 | Adapter | Export | Purpose |
-|---|---|---|
+|---------|--------|---------|
 | `gateway.ts` | `AgentRuntime`, `createGatewayServer` | HTTP gateway for receiving requests |
 | `auto-share.ts` | `IdleMonitor` | Per-skill idle rate polling + auto-share |
 | `auto-request.ts` | `AutoRequestor` | Peer scoring + budget-gated capability requests |
 | `credit-mgr.ts` | `BudgetManager`, `getBalance` | Credit reserve floor + balance queries |
-
-```typescript
-// Example: use IdleMonitor directly without full bootstrap
-import { IdleMonitor } from './auto-share.js';
-
-const monitor = new IdleMonitor({
-  owner: 'my-agent',
-  db: runtime.registryDb,
-  autonomyConfig: config.autonomy,
-});
-const job = monitor.start();
-runtime.registerJob(job);
-```