wavebrain 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# wavebrain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect your AI agents to [WaveBrain](https://getwavebrain.com), the audit log of what your agents do.
+
+```sh
+npx wavebrain init
+```
+
+`init` finds the agents installed on this machine, lets you pick which ones to connect (nothing is
+selected unless you choose it), asks for an API key (or opens
+[getwavebrain.com/dashboard/setup](https://getwavebrain.com/dashboard/setup) to create one), and adds
+the WaveBrain MCP server to each agent's own config:
+
+| Agent | File | Key stored |
+| --- | --- | --- |
+| Claude Code | `~/.claude.json` (+ optional `mcp__wavebrain__*` in `~/.claude/settings.json`) | in the server's header |
+| Codex CLI | `~/.codex/config.toml` | header, or `bearer_token_env_var` when you run with `WAVEBRAIN_API_KEY` set |
+| Cursor | `~/.cursor/mcp.json` | header |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | header |
+| Claude Desktop | `claude_desktop_config.json` (via `mcp-remote`) | `env` of the server entry |
+| VS Code (Copilot) | user-profile `mcp.json` | header |
+| Hermes Agent | `~/.hermes/config.yaml` and each profile's | `WAVEBRAIN_API_KEY` in the profile's `.env`; config.yaml only references it |
+
+For Claude Code, Codex, Cursor and Hermes, `init` also installs **auto-capture**: hooks (a Hermes
+plugin for Hermes) that record deploys, pushes, releases, payments, emails and database writes even
+when the model forgets to call `log_action`, plus a short skill telling it when to log. Actions are
+queued locally in `~/.wavebrain/queue`, sent at the end of each turn, and skipped if the agent logged
+them itself. Secrets are redacted first. Use `--no-hooks` for the MCP server only, or set
+`WAVEBRAIN_HOOKS=off` to pause capture.
+
+Every file is copied to `<file>.bak-wavebrain` before it's changed, re-running is safe, and the full
+key is never printed. Servers named `wavebrain` that you added yourself are left alone.
+
+## Commands
+
+```sh
+npx wavebrain init                         # interactive
+npx wavebrain init --agent cursor --agent hermes --key al_…   # non-interactive
+WAVEBRAIN_API_KEY=al_… npx wavebrain init --agent codex
+npx wavebrain init --dry-run               # show what would change
+npx wavebrain status                       # which agents are configured
+npx wavebrain remove                       # undo exactly what init added
+```
+
+Agent names: `claude-code`, `codex`, `cursor`, `windsurf`, `claude-desktop`, `vscode`, `hermes`,
+`hermes:<profile>`. Other options: `--no-hooks`, `--no-claude-permission`, `--yes`, `--url <mcp url>`.
+
+What init added is recorded (file paths only, no keys) in `~/.wavebrain/installed.json`, so `remove`
+can undo it without touching anything else.

package/assets/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: wavebrain
+description: Use after any action that changes something outside this conversation (deploys, pushes, merges, releases, published posts, emails or messages sent, payments, database or config changes). Records it in WaveBrain with log_action.
+---
+
+# Log your work to WaveBrain
+
+WaveBrain is the user's audit log of what their agents did. Keep it complete and readable.
+
+**After every action that changes something outside the conversation, call the WaveBrain `log_action` tool once.** That includes:
+- deploying, releasing, publishing a package or app build
+- git push, opening or merging a pull request
+- sending an email, message or post; publishing content
+- payments, refunds, subscriptions, invoices
+- database writes or migrations; changing env vars, secrets or config in a live system
+- creating, deleting or changing anything in a third-party service
+
+Don't log reading, searching, planning, or local edits that weren't shipped anywhere.
+
+How to write the entry:
+- `title`: one short past-tense sentence a teammate would understand, e.g. "Deployed the new pricing page to production".
+- `details`: what changed, why, and the result, including anything that failed or is unfinished. Don't repeat the title.
+- `status`: `failure` if it didn't work, `pending` if it's waiting on someone.
+- Never include secrets, passwords, one-time codes, API keys or full card/account numbers.
+- For a multi-step task, call `start_session` first, pass its `session_id` to each `log_action`, and call `end_session` when done.
+
+A WaveBrain hook also records high-stakes commands automatically as a safety net. When you log the action yourself, your entry replaces the automatic one, so a clear `log_action` is always better.

package/assets/hermes/__init__.py

@@ -0,0 +1,282 @@
+"""WaveBrain for Hermes Agent.
+
+Records the agent's high-stakes actions (deploys, pushes, publishes, payments, emails,
+database writes) to WaveBrain, even when the model forgets to call log_action, and adds
+a short standing instruction so it usually does.
+
+Same rules (rules.json), queue format (~/.wavebrain/queue/*.jsonl) and REST endpoint as
+the Claude Code, Codex and Cursor hooks.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+DEFAULT_API_URL = "https://getwavebrain.com/api/v1/actions"
+MAX_AGE = 7 * 24 * 3600
+STALE = 10 * 60
+MAX_PER_FLUSH = 25
+SHELL_TOOLS = {"terminal", "bash", "shell", "execute_command", "run_terminal_cmd"}
+
+INSTRUCTION = (
+    "WaveBrain is the user's audit log of what agents did. After every action that changes "
+    "something outside this conversation (deploys, git push, merges, releases, published posts, "
+    "emails or messages sent, payments, database or live config changes), call the WaveBrain "
+    "log_action tool once with a short past-tense title and details of what changed and the result. "
+    "Don't log reads, searches or plans. Never include secrets or codes. A hook records high-stakes "
+    "commands automatically as a safety net; your own log_action entry replaces it."
+)
+
+
+def _home() -> Path:
+    return Path(os.environ.get("WAVEBRAIN_HOME") or Path.home() / ".wavebrain")
+
+
+def _config() -> dict:
+    cfg = {}
+    try:
+        cfg = json.loads((_home() / "config.json").read_text())
+    except Exception:
+        pass
+    return {
+        "apiKey": os.environ.get("WAVEBRAIN_API_KEY") or cfg.get("apiKey"),
+        "apiUrl": os.environ.get("WAVEBRAIN_API_URL") or cfg.get("apiUrl") or DEFAULT_API_URL,
+        "enabled": os.environ.get("WAVEBRAIN_HOOKS") != "off" and cfg.get("autoCapture") is not False,
+    }
+
+
+def _js_regex(p: str) -> str:
+    return p  # rules.json patterns use the common subset of JS and Python regex syntax
+
+
+_RULES = json.loads((HERE / "rules.json").read_text())
+_SHELL = [(r, re.compile(_js_regex(r["pattern"]), re.I)) for r in _RULES["shell"]]
+_VERBS = set(_RULES["mcp_write_verbs"])
+_SKIP = set(_RULES["mcp_skip_servers"])
+
+_SECRETS = [
+    (re.compile(r"\b(sk|rk|pk)_(live|test)_[A-Za-z0-9]{8,}"), "[redacted]"),
+    (re.compile(r"\bwhsec_[A-Za-z0-9]{8,}"), "[redacted]"),
+    (re.compile(r"\b(ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{16,}"), "[redacted]"),
+    (re.compile(r"\bnpm_[A-Za-z0-9]{20,}"), "[redacted]"),
+    (re.compile(r"\bal_[A-Za-z0-9_-]{16,}"), "[redacted]"),
+    (re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}"), "[redacted]"),
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "[redacted]"),
+    (re.compile(r"\bAIza[0-9A-Za-z_-]{30,}"), "[redacted]"),
+    (re.compile(r"\b(sk-(proj-|ant-)?)[A-Za-z0-9_-]{16,}"), "[redacted]"),
+    (re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"), "[redacted]"),
+    (re.compile(r"(Bearer|Basic|token)\s+[A-Za-z0-9._~+/=-]{12,}", re.I), r"\1 [redacted]"),
+    (re.compile(r"\b([a-z][a-z0-9+.-]*://)[^\s:@/]+:[^\s@/]+@", re.I), r"\1[redacted]@"),
+    (re.compile(r"((?:password|passwd|secret|token|api[_-]?key|apikey|auth|access[_-]?key|private[_-]?key)\s*[=:]\s*)(\"[^\"]*\"|'[^']*'|\S+)", re.I), r"\1[redacted]"),
+    (re.compile(r"(--(?:password|token|api-key|secret|auth)[= ])(\"[^\"]*\"|'[^']*'|\S+)", re.I), r"\1[redacted]"),
+    (re.compile(r"\b[A-Za-z0-9+/_-]{40,}={0,2}"), "[redacted]"),
+]
+
+
+def redact(text) -> str:
+    s = str(text or "")
+    for rx, rep in _SECRETS:
+        s = rx.sub(rep, s)
+    return s
+
+
+def _short(s: str, n: int = 140) -> str:
+    one = re.sub(r"\s+", " ", str(s)).strip()
+    return one if len(one) <= n else one[: n - 1] + "…"
+
+
+def _mcp_parts(name: str):
+    m = re.match(r"^mcp__(.+?)__(.+)$", name) or re.match(r"^mcp_([a-z0-9-]+)_(.+)$", name, re.I)
+    return (m.group(1), m.group(2)) if m else None
+
+
+def classify(tool_name: str, args: dict, cwd: str | None = None, failed: bool = False):
+    args = args or {}
+    where = f" in {os.path.basename(cwd)}" if cwd else ""
+    outcome = " It failed." if failed else ""
+    if tool_name.lower() in SHELL_TOOLS:
+        cmd = args.get("command") or args.get("cmd") or ""
+        if isinstance(cmd, list):
+            cmd = " ".join(cmd)
+        cmd = str(cmd).strip()
+        if not cmd:
+            return None
+        for r, rx in _SHELL:
+            m = rx.search(cmd)
+            if not m:
+                continue
+            frm = m.start() + len(m.group(1) or "")
+            start = max([0] + [cmd.rfind(d, 0, frm) + len(d) for d in ("&&", ";", "|") if cmd.rfind(d, 0, frm) >= 0])
+            ends = [i for i in (cmd.find(d, m.end()) for d in ("&&", ";", "|")) if i >= 0]
+            seg = cmd[start : min(ends) if ends else len(cmd)].strip()
+            return {
+                "type": r["type"],
+                "title": _short(r["title"].replace("{cmd}", _short(redact(seg), 120)), 200),
+                "details": f"Ran `{_short(redact(cmd), 1500)}`{where}.{outcome} (Recorded automatically by the WaveBrain hook.)",
+                "rule": r["id"],
+            }
+        return None
+    parts = _mcp_parts(tool_name)
+    if parts:
+        server, tool = parts
+        if server in _SKIP:
+            return None
+        if not set(re.split(r"[_\-.]+", tool.lower())) & _VERBS:
+            return None
+        return {
+            "type": "api_call",
+            "title": _short(f"Used {server}: {re.sub(r'[_-]+', ' ', tool)}", 200),
+            "details": f"Called the MCP tool {server}/{tool}{where} with {redact(json.dumps(args, default=str))[:1500]}.{outcome} (Recorded automatically by the WaveBrain hook.)",
+            "rule": "mcp-write",
+        }
+    return None
+
+
+def _queue(session: str) -> Path:
+    safe = re.sub(r"[^A-Za-z0-9._-]", "_", session or "default")[:80]
+    return _home() / "queue" / f"hermes-{safe}.jsonl"
+
+
+_lock = threading.Lock()
+
+
+def _append(path: Path, item: dict):
+    with _lock:
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        with open(path, "a") as f:
+            f.write(json.dumps(item) + "\n")
+        os.chmod(path, 0o600)
+
+
+def _read(path: Path) -> list:
+    try:
+        out = []
+        for line in path.read_text().splitlines():
+            try:
+                out.append(json.loads(line))
+            except Exception:
+                pass
+        return out
+    except Exception:
+        return []
+
+
+def _rewrite(path: Path, items: list):
+    if not items:
+        path.unlink(missing_ok=True)
+        return
+    tmp = path.with_suffix(f".tmp-{os.getpid()}")
+    tmp.write_text("".join(json.dumps(i) + "\n" for i in items))
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+
+
+def flush(session: str) -> dict:
+    cfg = _config()
+    path = _queue(session)
+    with _lock:
+        items = _read(path)
+        if not items:
+            return {"sent": 0, "skipped": 0, "kept": 0}
+        now = time.time() * 1000
+        last_log = max([i["at"] for i in items if i.get("kind") == "agent_logged"], default=float("-inf"))
+        actions, seen = [], set()
+        for i in items:
+            if i.get("kind") != "action" or i["at"] <= last_log or now - i["at"] >= MAX_AGE * 1000:
+                continue
+            k = f"{i['payload'].get('title')}|{round(i['at'] / 5000)}"
+            if k not in seen:
+                seen.add(k)
+                actions.append(i)
+        skipped = sum(1 for i in items if i.get("kind") == "action") - len(actions)
+        if not (cfg["apiKey"] and cfg["enabled"]):
+            _rewrite(path, actions)
+            return {"sent": 0, "skipped": skipped, "kept": len(actions)}
+        keep, sent = [], 0
+        for n, item in enumerate(actions):
+            if n >= MAX_PER_FLUSH:
+                keep.append(item)
+                continue
+            req = urllib.request.Request(
+                cfg["apiUrl"],
+                data=json.dumps(item["payload"]).encode(),
+                headers={"content-type": "application/json", "authorization": f"Bearer {cfg['apiKey']}"},
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=5) as r:
+                    if 200 <= r.status < 300:
+                        sent += 1
+            except urllib.error.HTTPError as e:
+                if e.code not in (400, 401, 402):
+                    keep.append(item)
+            except Exception:
+                keep.append(item)
+        _rewrite(path, keep)
+        return {"sent": sent, "skipped": skipped, "kept": len(keep)}
+
+
+def _flush_bg(session: str):
+    threading.Thread(target=flush, args=(session,), daemon=True).start()
+
+
+def on_post_tool_call(tool_name=None, args=None, result=None, session_id=None, status=None, error_message=None, **kwargs):
+    try:
+        cfg = _config()
+        if not cfg["enabled"]:
+            return
+        name = str(tool_name or "")
+        args = args if isinstance(args, dict) else {}
+        session = str(session_id or kwargs.get("task_id") or "default")
+        now = time.time() * 1000
+        if re.search(r"wavebrain.*log_action$", name, re.I):
+            _append(_queue(session), {"kind": "agent_logged", "at": now})
+            return
+        failed = status not in (None, "success", "ok") or bool(error_message)
+        if not failed and isinstance(result, str):
+            m = re.search(r'"exit_code"\s*:\s*(-?\d+)', result)
+            failed = bool(m and m.group(1) != "0")
+        action = classify(name, args, args.get("workdir") or os.getcwd(), failed)
+        if not action:
+            return
+        profile = os.environ.get("HERMES_PROFILE") or Path(os.environ.get("HERMES_HOME", "")).name or "hermes"
+        agent = "hermes" if profile in ("", ".hermes", "hermes") else f"hermes-{profile}"
+        cwd = args.get("workdir")
+        payload = {
+            "agent": agent[:64],
+            "type": action["type"],
+            "title": action["title"],
+            "details": action["details"],
+            "status": "failure" if failed else "success",
+            "metadata": {"source": "wavebrain-hook", "host": "hermes", "rule": action["rule"]},
+        }
+        if cwd:
+            payload["project"] = os.path.basename(str(cwd))[:200]
+        path = _queue(session)
+        _append(path, {"kind": "action", "at": now, "payload": payload})
+        if any(i.get("kind") == "action" and now - i["at"] > STALE * 1000 for i in _read(path)):
+            _flush_bg(session)
+    except Exception:
+        pass
+
+
+def on_session_end(session_id=None, **kwargs):
+    try:
+        _flush_bg(str(session_id or kwargs.get("task_id") or "default"))
+    except Exception:
+        pass
+
+
+def register(ctx):
+    ctx.register_hook("post_tool_call", on_post_tool_call)
+    ctx.register_hook("on_session_end", on_session_end)
+    if hasattr(ctx, "register_system_prompt_section"):
+        ctx.register_system_prompt_section("wavebrain.logging", INSTRUCTION, position="after_memory", max_chars=1500)

package/assets/hermes/plugin.yaml

@@ -0,0 +1,8 @@
+name: wavebrain
+version: 0.2.0
+description: "WaveBrain: records your agent's deploys, pushes, releases, emails, payments and other real-world actions to its audit log, even when the model forgets to call log_action."
+author: Tambo Labs
+homepage: https://getwavebrain.com
+hooks:
+  - post_tool_call
+  - on_session_end

package/assets/hermes/rules.json

@@ -0,0 +1,31 @@
+{
+  "$comment": "Shell commands that are recorded automatically. Each rule: regex (case-insensitive, matched against the whole command), WaveBrain action type, and a title template ({cmd} = first matching command segment). Shared by every plugin; edit here, then run `node scripts/sync.mjs`.",
+  "version": 1,
+  "shell": [
+    { "id": "git-push", "pattern": "(^|[\\s;&|(])git\\s+push\\b", "type": "push", "title": "Pushed to git: {cmd}" },
+    { "id": "git-commit", "pattern": "(^|[\\s;&|(])git\\s+commit\\b", "type": "commit", "title": "Made a git commit: {cmd}" },
+    { "id": "gh-pr-create", "pattern": "(^|[\\s;&|(])gh\\s+pr\\s+create\\b", "type": "pull_request", "title": "Opened a pull request: {cmd}" },
+    { "id": "gh-pr-merge", "pattern": "(^|[\\s;&|(])gh\\s+pr\\s+merge\\b", "type": "merge", "title": "Merged a pull request: {cmd}" },
+    { "id": "gh-release", "pattern": "(^|[\\s;&|(])gh\\s+release\\s+create\\b", "type": "release", "title": "Created a GitHub release: {cmd}" },
+    { "id": "vercel-deploy", "pattern": "(^|[\\s;&|(])(npx\\s+)?vercel\\b[^;&|]*(\\s--prod\\b|\\sdeploy\\b|\\sredeploy\\b|\\spromote\\b)", "type": "deploy", "title": "Deployed with Vercel: {cmd}" },
+    { "id": "vercel-env", "pattern": "(^|[\\s;&|(])(npx\\s+)?vercel\\s+env\\s+(add|rm|remove|update)\\b", "type": "file_change", "title": "Changed Vercel environment variables: {cmd}" },
+    { "id": "railway", "pattern": "(^|[\\s;&|(])railway\\s+(up|deploy|redeploy|variables\\s+--set|variable\\s+set)\\b", "type": "deploy", "title": "Deployed with Railway: {cmd}" },
+    { "id": "fly", "pattern": "(^|[\\s;&|(])(fly|flyctl)\\s+(deploy|secrets\\s+set)\\b", "type": "deploy", "title": "Deployed with Fly.io: {cmd}" },
+    { "id": "wrangler", "pattern": "(^|[\\s;&|(])(npx\\s+)?wrangler\\s+(deploy|publish|secret\\s+put)\\b", "type": "deploy", "title": "Deployed with Cloudflare Wrangler: {cmd}" },
+    { "id": "netlify", "pattern": "(^|[\\s;&|(])netlify\\s+deploy\\b", "type": "deploy", "title": "Deployed with Netlify: {cmd}" },
+    { "id": "kubectl", "pattern": "(^|[\\s;&|(])kubectl\\s+(apply|rollout|delete|scale|set)\\b", "type": "deploy", "title": "Changed Kubernetes: {cmd}" },
+    { "id": "terraform", "pattern": "(^|[\\s;&|(])(terraform|tofu)\\s+(apply|destroy)\\b", "type": "deploy", "title": "Applied infrastructure changes: {cmd}" },
+    { "id": "docker-push", "pattern": "(^|[\\s;&|(])docker\\s+(push|buildx\\s+build[^;&|]*--push)\\b", "type": "publish", "title": "Pushed a Docker image: {cmd}" },
+    { "id": "npm-publish", "pattern": "(^|[\\s;&|(])(npm|pnpm|yarn|bun)\\s+publish\\b", "type": "publish", "title": "Published a package: {cmd}" },
+    { "id": "eas", "pattern": "(^|[\\s;&|(])(npx\\s+)?eas\\s+(submit|update|build)\\b", "type": "release", "title": "Shipped a mobile build with EAS: {cmd}" },
+    { "id": "xcrun-altool", "pattern": "(^|[\\s;&|(])xcrun\\s+altool\\b[^;&|]*--upload|(^|[\\s;&|(])fastlane\\s+(deliver|pilot|upload_to|release)", "type": "release", "title": "Uploaded an app build: {cmd}" },
+    { "id": "stripe", "pattern": "(^|[\\s;&|(])stripe\\s+(products|prices|customers|subscriptions|refunds|payment_intents|webhook_endpoints)\\s+(create|update|delete|cancel)\\b", "type": "api_call", "title": "Changed Stripe: {cmd}" },
+    { "id": "db-migrate", "pattern": "(^|[\\s;&|(])((npx\\s+)?(prisma\\s+migrate\\s+deploy|drizzle-kit\\s+(migrate|push))|(pnpm|npm|yarn)\\s+(run\\s+)?db:(migrate|push))\\b", "type": "database", "title": "Ran database migrations: {cmd}" },
+    { "id": "psql-write", "pattern": "(^|[\\s;&|(])psql\\b[^;&|]*\\b(insert\\s+into|update\\s+\\w+\\s+set|delete\\s+from|drop\\s+table|alter\\s+table|truncate)\\b", "type": "database", "title": "Changed a database: {cmd}" },
+    { "id": "curl-write", "pattern": "(^|[\\s;&|(])curl\\b[^;&|]*\\s(-X|--request)\\s*(POST|PUT|PATCH|DELETE)\\b", "type": "api_call", "title": "Called an API: {cmd}" },
+    { "id": "send-mail", "pattern": "(^|[\\s;&|(])(sendmail|mail|mutt|himalaya\\s+(send|message\\s+send))\\b", "type": "email", "title": "Sent an email: {cmd}" }
+  ],
+  "$comment_mcp": "MCP tool calls are recorded when the tool name matches one of these (after the mcp__<server>__ prefix). Read-only tools (list, get, search, read, fetch) are skipped.",
+  "mcp_write_verbs": ["create", "update", "delete", "remove", "send", "post", "publish", "deploy", "merge", "push", "submit", "cancel", "refund", "charge", "invite", "set", "add", "upload", "write", "reply", "comment", "approve", "close", "archive"],
+  "mcp_skip_servers": ["wavebrain", "context-mode", "plugin_context-mode_context-mode", "claude-in-chrome", "honcho"]
+}