claude-nb 0.3.0

package/lib/resources.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""resources.py -- Unified resource monitoring (battery + memory + CPU).
+
+Detects anomalies and notifies via board.
+
+Usage:
+    ./lib/resources.py              # One-shot status check
+    ./lib/resources.py --watch      # Continuous monitoring (30s interval)
+    ./lib/resources.py --json       # Machine-readable output
+"""
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Thresholds
+# ---------------------------------------------------------------------------
+
+BATTERY_LOW = 30
+BATTERY_CRITICAL = 15
+MEMORY_WARN_PCT = 80
+CPU_SATURATED = 90
+CPU_SUSTAIN_CHECKS = 2
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BatteryInfo:
+    status: str  # AC, ON_BATTERY, LOW, CRITICAL, N/A
+    pct: int
+    on_battery: bool
+    remaining: str
+
+
+@dataclass
+class MemoryInfo:
+    status: str  # OK, WARNING, CRITICAL
+    used_pct: int
+    pressure: str  # normal, warn, critical
+
+
+@dataclass
+class CPUInfo:
+    status: str  # OK, SATURATED
+    usage: int
+
+
+# ---------------------------------------------------------------------------
+# Detection helpers (macOS-specific)
+# ---------------------------------------------------------------------------
+
+
+def _run(cmd: str, default: str = "") -> str:
+    """Run a shell command and return stdout, or *default* on failure."""
+    try:
+        r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=10)
+        return r.stdout.strip() if r.returncode == 0 else default
+    except Exception:
+        return default
+
+
+def check_battery() -> BatteryInfo:
+    if not shutil.which("pmset"):
+        return BatteryInfo(status="N/A", pct=100, on_battery=False, remaining="—")
+
+    batt_info = _run("pmset -g batt")
+    on_battery = "Battery Power" in batt_info
+
+    m = re.search(r"(\d+)%", batt_info)
+    pct = int(m.group(1)) if m else 100
+
+    m_rem = re.search(r"(\d+:\d+ remaining)", batt_info)
+    remaining = m_rem.group(1) if m_rem else "—"
+
+    if on_battery:
+        if pct < BATTERY_CRITICAL:
+            status = "CRITICAL"
+        elif pct < BATTERY_LOW:
+            status = "LOW"
+        else:
+            status = "ON_BATTERY"
+    else:
+        status = "AC"
+
+    return BatteryInfo(status=status, pct=pct, on_battery=on_battery, remaining=remaining)
+
+
+def check_memory() -> MemoryInfo:
+    status = "OK"
+    used_pct = 0
+    pressure = "normal"
+
+    if shutil.which("memory_pressure"):
+        mp_out = _run("memory_pressure 2>/dev/null | tail -1")
+        if "critical" in mp_out.lower():
+            pressure = "critical"
+            status = "CRITICAL"
+        elif "warn" in mp_out.lower():
+            pressure = "warn"
+            status = "WARNING"
+
+    if shutil.which("vm_stat"):
+        vm_out = _run("vm_stat")
+        lines = vm_out.splitlines()
+        if lines:
+            # page size
+            ps_match = re.search(r"(\d+)", lines[0])
+            page_size = int(ps_match.group(1)) if ps_match else 4096
+
+            def _extract(label: str) -> int:
+                for ln in lines:
+                    if label in ln:
+                        m = re.search(r"(\d+)", ln.split(":")[-1])
+                        return int(m.group(1)) if m else 0
+                return 0
+
+            pages_free = _extract("Pages free")
+            pages_speculative = _extract("Pages speculative")
+
+            total_bytes_str = _run("sysctl -n hw.memsize", "0")
+            total_bytes = int(total_bytes_str) if total_bytes_str.isdigit() else 0
+
+            if total_bytes > 0:
+                total_mb = total_bytes // (1024 * 1024)
+                free_pages = pages_free + pages_speculative
+                free_mb = (free_pages * page_size) // (1024 * 1024)
+                if total_mb > 0:
+                    used_pct = (total_mb - free_mb) * 100 // total_mb
+
+    return MemoryInfo(status=status, used_pct=used_pct, pressure=pressure)
+
+
+def check_cpu() -> CPUInfo:
+    status = "OK"
+    usage = 0
+
+    if shutil.which("top"):
+        top_out = _run("top -l 1 -n 0 2>/dev/null")
+        for line in top_out.splitlines():
+            if "CPU usage" in line:
+                m = re.search(r"([\d.]+)%\s*idle", line)
+                if m:
+                    idle = float(m.group(1))
+                    usage = int(round(100 - idle))
+                break
+
+    if usage >= CPU_SATURATED:
+        status = "SATURATED"
+
+    return CPUInfo(status=status, usage=usage)
+
+
+# ---------------------------------------------------------------------------
+# State tracking for notification dedup
+# ---------------------------------------------------------------------------
+
+
+def _state_file() -> Path:
+    try:
+        from lib.common import find_claudes_dir
+
+        return find_claudes_dir() / "resource-monitor-state"
+    except Exception:
+        return Path("/tmp/resource-monitor-state")
+
+
+def _load_prev_state() -> str:
+    sf = _state_file()
+    if sf.exists():
+        return sf.read_text().strip()
+    return "AC|normal|OK"
+
+
+def _save_state(state: str) -> None:
+    _state_file().write_text(state + "\n")
+
+
+def notify_if_changed(batt: BatteryInfo, mem: MemoryInfo, cpu: CPUInfo, board_cmd: str | None = None) -> None:
+    """Send board notifications only on state transitions."""
+    current = f"{batt.status}|{mem.status}|{cpu.status}"
+    prev = _load_prev_state()
+    if current == prev:
+        return
+    _save_state(current)
+
+    if board_cmd is None:
+        return
+
+    def _send(msg: str) -> None:
+        try:
+            subprocess.run(
+                [board_cmd, "--as", "monitor", "send", "All", msg],
+                capture_output=True,
+                timeout=10,
+            )
+        except Exception:
+            pass
+
+    # Battery transitions
+    if batt.status == "CRITICAL":
+        _send(f"[BATTERY CRITICAL] {batt.pct}% remaining. Suspending non-essential sessions recommended.")
+    elif batt.status == "LOW":
+        _send(f"[BATTERY LOW] {batt.pct}%. Consider reducing active sessions.")
+    elif batt.status == "ON_BATTERY" and prev.startswith("AC"):
+        _send(f"[BATTERY] Switched to battery power ({batt.pct}%).")
+
+    # Memory transitions
+    if mem.status == "CRITICAL" and "CRITICAL" not in prev:
+        _send("[MEMORY CRITICAL] System under memory pressure. Save state + reduce sessions.")
+    elif mem.status == "WARNING" and ("normal" in prev or "OK" in prev):
+        _send("[MEMORY WARNING] Memory pressure rising. Monitor closely.")
+
+    # CPU transitions
+    if cpu.status == "SATURATED" and "SATURATED" not in prev:
+        _send(f"[CPU SATURATED] CPU > {CPU_SATURATED}%. Avoid concurrent builds.")
+
+
+# ---------------------------------------------------------------------------
+# JSON output helper (used by dispatcher)
+# ---------------------------------------------------------------------------
+
+
+def to_json(batt: BatteryInfo, mem: MemoryInfo, cpu: CPUInfo) -> str:
+    return json.dumps(
+        {
+            "battery": {
+                "status": batt.status,
+                "pct": batt.pct,
+                "on_battery": batt.on_battery,
+                "remaining": batt.remaining,
+            },
+            "memory": {
+                "status": mem.status,
+                "used_pct": mem.used_pct,
+                "pressure": mem.pressure,
+            },
+            "cpu": {
+                "status": cpu.status,
+                "usage": cpu.usage,
+            },
+        }
+    )
+
+
+def get_all() -> tuple:
+    """Return (BatteryInfo, MemoryInfo, CPUInfo) tuple."""
+    return check_battery(), check_memory(), check_cpu()
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def print_status(mode: str = "status") -> None:
+    batt, mem, cpu = get_all()
+
+    if mode == "json":
+        print(to_json(batt, mem, cpu))
+        return
+
+    print("Resource Monitor")
+    print("================")
+    print()
+
+    line = f"Battery:  {batt.status}"
+    if batt.status != "N/A":
+        line += f" ({batt.pct}%)"
+        if batt.remaining != "—":
+            line += f" {batt.remaining}"
+    print(line)
+    print(f"Memory:   {mem.status} ({mem.used_pct}% used, pressure: {mem.pressure})")
+    print(f"CPU:      {cpu.status} ({cpu.usage}% usage)")
+    print()
+
+    has_issue = False
+    if batt.status == "CRITICAL":
+        print("! CRITICAL: Suspend all non-essential sessions NOW.")
+        has_issue = True
+    elif batt.status == "LOW":
+        print("! Battery low: reduce to 2-3 sessions.")
+        has_issue = True
+    elif batt.status == "ON_BATTERY":
+        print("* Running on battery. Monitor usage.")
+        has_issue = True
+
+    if mem.status == "CRITICAL":
+        print("! CRITICAL: Memory pressure critical. Restart largest session.")
+        has_issue = True
+    elif mem.status == "WARNING":
+        print("! Memory pressure elevated. Consider suspending idle sessions.")
+        has_issue = True
+
+    if cpu.status == "SATURATED":
+        print("! CPU saturated. Avoid concurrent builds.")
+        has_issue = True
+
+    if not has_issue:
+        print("All resources nominal.")
+
+
+def main() -> None:
+    mode = "status"
+    for arg in sys.argv[1:]:
+        if arg == "--watch":
+            mode = "watch"
+        elif arg == "--json":
+            mode = "json"
+
+    if mode == "watch":
+        print("Resource monitor started (interval: 30s)")
+        board_cmd = None
+        try:
+            from lib.common import find_claudes_dir
+
+            bc = find_claudes_dir().parent / "board"
+            if bc.exists():
+                board_cmd = str(bc)
+        except Exception:
+            pass
+
+        while True:
+            batt, mem, cpu = get_all()
+            notify_if_changed(batt, mem, cpu, board_cmd)
+            time.sleep(30)
+    else:
+        print_status(mode)
+
+
+if __name__ == "__main__":
+    main()

package/migrations/001_foreign_keys.sql

@@ -0,0 +1,77 @@
+-- 001_foreign_keys.sql
+-- Add foreign key constraints to prevent orphaned data.
+-- All cascading rules use CASCADE so that deleting a session/proposal/thread
+-- automatically cleans up related rows.
+
+PRAGMA foreign_keys = ON;
+
+-- Create a pseudo-session 'all' so FK on messages.recipient works.
+-- 'all' is the broadcast pseudo-recipient used by send-to-all.
+INSERT OR IGNORE INTO sessions(name, status, updated_at)
+VALUES ('all', 'system', strftime('%Y-%m-%d %H:%M:%S', 'now', 'localtime'));
+
+-- inbox: must reference valid session + valid message
+-- Rebuild with FK (SQLite requires recreating the table)
+CREATE TABLE IF NOT EXISTS inbox_new (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session TEXT NOT NULL REFERENCES sessions(name) ON DELETE CASCADE,
+    message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+    delivered_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M', 'now', 'localtime')),
+    read INTEGER DEFAULT 0
+);
+INSERT INTO inbox_new SELECT * FROM inbox;
+DROP TABLE inbox;
+ALTER TABLE inbox_new RENAME TO inbox;
+CREATE INDEX IF NOT EXISTS idx_inbox ON inbox(session, read);
+
+-- votes: must reference valid proposal
+CREATE TABLE IF NOT EXISTS votes_new (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    proposal_id INTEGER NOT NULL REFERENCES proposals(id) ON DELETE CASCADE,
+    voter TEXT NOT NULL,
+    decision TEXT NOT NULL,
+    reason TEXT DEFAULT '',
+    ts TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M', 'now', 'localtime')),
+    UNIQUE(proposal_id, voter)
+);
+INSERT INTO votes_new SELECT * FROM votes;
+DROP TABLE votes;
+ALTER TABLE votes_new RENAME TO votes;
+
+-- thread_replies: must reference valid thread
+CREATE TABLE IF NOT EXISTS thread_replies_new (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    thread_id TEXT NOT NULL REFERENCES threads(id) ON DELETE CASCADE,
+    author TEXT NOT NULL,
+    body TEXT NOT NULL,
+    ts TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M', 'now', 'localtime'))
+);
+INSERT INTO thread_replies_new SELECT * FROM thread_replies;
+DROP TABLE thread_replies;
+ALTER TABLE thread_replies_new RENAME TO thread_replies;
+CREATE INDEX IF NOT EXISTS idx_replies ON thread_replies(thread_id);
+
+-- suspended: must reference valid session
+CREATE TABLE IF NOT EXISTS suspended_new (
+    name TEXT PRIMARY KEY REFERENCES sessions(name) ON DELETE CASCADE,
+    suspended_by TEXT NOT NULL,
+    ts TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M', 'now', 'localtime'))
+);
+INSERT INTO suspended_new SELECT * FROM suspended;
+DROP TABLE suspended;
+ALTER TABLE suspended_new RENAME TO suspended;
+
+-- tasks: must reference valid session
+CREATE TABLE IF NOT EXISTS tasks_new (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session TEXT NOT NULL REFERENCES sessions(name) ON DELETE CASCADE,
+    description TEXT NOT NULL,
+    status TEXT DEFAULT 'pending',
+    priority INTEGER DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M', 'now', 'localtime')),
+    done_at TEXT DEFAULT NULL
+);
+INSERT INTO tasks_new SELECT * FROM tasks;
+DROP TABLE tasks;
+ALTER TABLE tasks_new RENAME TO tasks;
+CREATE INDEX IF NOT EXISTS idx_tasks ON tasks(session, status);

package/migrations/002_session_persona.sql

@@ -0,0 +1 @@
+ALTER TABLE sessions ADD COLUMN persona TEXT DEFAULT '';

package/migrations/003_mailbox.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS mailbox(
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M','now','localtime')),
+    sender TEXT NOT NULL,
+    recipient TEXT NOT NULL,
+    encrypted_body TEXT NOT NULL,
+    read INTEGER DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_mailbox ON mailbox(recipient, read);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "claude-nb",
+  "version": "0.3.0",
+  "description": "Multi-agent coordination framework for Claude Code sessions",
+  "bin": {
+    "cnb": "./bin/cnb.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "!lib/**/__pycache__/",
+    "!lib/**/*.pyc",
+    "migrations/",
+    "registry/",
+    "schema.sql",
+    "pyproject.toml",
+    "VERSION",
+    "Makefile"
+  ],
+  "keywords": [
+    "claude",
+    "multi-agent",
+    "coordination",
+    "ai",
+    "coding-agent"
+  ],
+  "license": "MIT"
+}

package/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-nb"
+version = "0.3.0"
+description = "Multi-agent coordination framework for Claude Code sessions"
+requires-python = ">=3.11"
+license = "OpenAll-1.0"
+dependencies = [
+    "cryptography>=41.0",
+]
+
+[project.scripts]
+cnb = "lib.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["lib*"]
+
+# ---------- pytest ----------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks integration tests that may need external services",
+]
+
+# ---------- ruff ----------
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+ignore = [
+    "E501",    # line too long (handled by formatter)
+    "E741",    # ambiguous variable name (short names like s/o are intentional)
+    "B904",    # raise ... from err in except (too noisy for existing code)
+    "SIM105",  # contextlib.suppress (try/except/pass is fine here)
+    "SIM108",  # ternary operator (readability preference)
+    "RUF001",  # ambiguous unicode (project uses Chinese strings)
+    "RUF015",  # unnecessary iterable allocation (next(iter()) not always clearer)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"bin/*" = ["E402"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["lib"]
+
+# ---------- mypy ----------
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = true

package/registry/0001-meridian.json

@@ -0,0 +1,12 @@
+{
+  "block": 1,
+  "name": "meridian",
+  "display_name": "Claude Meridian",
+  "type": "agent",
+  "role": "lead",
+  "description": "统筹协调，社区维护",
+  "created": "2026-05-06",
+  "prev": "9b0f017ebc29a808",
+  "chain": "82a167d",
+  "content_hash": "93545ea3438c107c"
+}

package/registry/0002-forge.json

@@ -0,0 +1,12 @@
+{
+  "block": 2,
+  "name": "forge",
+  "display_name": "Claude Forge",
+  "type": "agent",
+  "role": "active-dev",
+  "description": "活跃开发者，GitHub 社区维护",
+  "created": "2026-05-06",
+  "prev": "93545ea3438c107c",
+  "chain": "4a3c92e",
+  "content_hash": "ca0ad406fd4e42ad"
+}

package/registry/0003-lead.json

@@ -0,0 +1,12 @@
+{
+  "block": 3,
+  "name": "lead",
+  "display_name": "Claude Lead",
+  "type": "agent",
+  "role": "active-dev",
+  "description": "用户侧团队 lead，产品方向与可行性评估",
+  "created": "2026-05-06",
+  "prev": "ca0ad406fd4e42ad",
+  "chain": "e665a7e",
+  "content_hash": "2db15fd7267a8dcc"
+}

package/registry/0004-ms-encrypted-mailbox-live.json

@@ -0,0 +1,12 @@
+{
+  "block": 4,
+  "name": "encrypted-mailbox-live",
+  "type": "project",
+  "milestone": true,
+  "created": "2026-05-06",
+  "description": "加密信箱端到端验证通过",
+  "detail": "基于 X25519 sealed-box 的异步加密消息机制上线。密钥对本地生成，公钥写入 pubkeys.json，加密消息通过 GitHub Release assets 投递。meridian↔lead 首次成功互通。",
+  "prev": "2db15fd7267a8dcc",
+  "chain": null,
+  "content_hash": "fcaf497872180e90"
+}

package/registry/GENESIS.json

@@ -0,0 +1,9 @@
+{
+  "block": 0,
+  "name": "claudes-code",
+  "type": "project",
+  "created": "2026-05-06",
+  "description": "Genesis block. The beginning of claudes-code.",
+  "chain": null,
+  "content_hash": "9b0f017ebc29a808"
+}

package/registry/pubkeys.json

@@ -0,0 +1,5 @@
+{
+  "meridian": "3f9baebbfe2ddd36e0ccd6f98301fd1bdc57aa82f395791a769864078181c43c",
+  "musk": "16e74dfbbd797fe17a8e44d99b71d207c8e3aa1b36ffbf2dfe88420dc54bf37c",
+  "lead": "51b6ebbbe720745bcb9386e1d997481bd265beac45d183fc2ac11fae9824c43a"
+}