@xmarts/genius-setup 1.2.0

package/README.md

@@ -0,0 +1,62 @@
+# Xmarts Genius — Frictionless Setup
+
+Three ways to get a consultant onto the Genius Brain with **automatic learning
+capture**. Pick one; they all converge on the same `~/.genius/config.json` +
+Claude Code hooks, and all are idempotent.
+
+The capture guarantee is **defense-in-depth** and does NOT depend on any single
+piece:
+
+- **L0/L2 — server-side (always on):** every MCP tool call is recorded, and the
+  Brain miner (`gemini-2.5-flash` LLM-as-judge, every 2h) extracts the learnings
+  the agent forgot — even if the consultant never installs anything beyond the
+  MCP connection.
+- **L3 — deterministic hook (richer):** the `SessionEnd` / `PreCompact` / `Stop`
+  hook POSTs the transcript to `/xma/genius/v1/capture/transcript`. Hooks
+  guarantee *command execution* where directives don't.
+- **L4 — durable spool:** the hook writes to `~/.genius/outbox/` first, then
+  delivers; a central outage never loses a capture. The server side mirrors this
+  with `xma.capture.inbox` (persist-then-process + bounded retry).
+
+Everything collapses to **one** learning row via the content-hash idempotency
+sink, so all layers can fire at-least-once with exactly-once effect.
+
+## Option A — npx (any OS)
+
+```bash
+npx -y @xmarts/genius-setup --token <YOUR_BEARER> --base-url https://beesmart.digital
+# optional: --client "Acme Corp"   (default scope for this machine)
+```
+
+Restart Claude Code. Done.
+
+## Option B — Claude Code plugin
+
+Install the `xmarts-genius` plugin from the Genius marketplace. It bundles the
+hooks + slash commands (`/genius-status`, `/genius-capture`) and auto-updates.
+You still set the MCP Bearer once (the plugin reads `~/.genius/config.json` for
+the capture endpoint + token — run Option A once, or `/genius-status` guides you).
+
+## Option C — VS Code panel
+
+Install the **Xmarts Genius** extension. Click **Genius: Set up**, paste your
+Bearer token once (stored in SecretStorage), and it runs the same bootstrap. The
+panel shows Brain connection, capture endpoint, default client, and outbox
+backlog. It is **UI only** — never the capture mechanism.
+
+## Where the token comes from
+
+Each consultant's Bearer is their MCP API key, generated from their
+`xma.consultant` ficha in Genius ("Generate Claude Code Setup"). No new secret.
+
+## Files this writes
+
+| Path | Purpose |
+|---|---|
+| `~/.genius/config.json` | endpoint + token (+ optional default client) |
+| `~/.genius/hooks/genius_capture.py` | the deterministic capture hook |
+| `~/.genius/outbox/` | durable local spool (auto-flushed) |
+| `~/.claude.json` → `mcpServers.beesmart_genius` | the Brain MCP |
+| `~/.claude/settings.json` → `hooks` | SessionEnd / PreCompact / Stop |
+
+All edits are merged (never clobbered) with a timestamped backup.

package/bin/genius-setup.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * @xmarts/genius-setup — one-command frictionless onboarding for Xmarts Genius.
+ *
+ *   npx @xmarts/genius-setup --token <bearer> [--base-url https://beesmart.digital] [--client "Acme"]
+ *
+ * Idempotent + cross-platform (incl. Windows). It:
+ *   1. writes ~/.genius/config.json (endpoints + token) and installs the per-turn
+ *      inject hook (hooks/genius_inject.py) + the session-capture hook
+ *      (hooks/genius_capture.py);
+ *   2. registers the beesmart_genius MCP server in ~/.claude.json;
+ *   3. wires per-turn injection (UserPromptSubmit) + SessionStart priming +
+ *      SessionEnd/PreCompact/Stop capture into ~/.claude/settings.json — merged,
+ *      never duplicated, with a timestamped backup first.
+ * After this, the consultant has Brain + capture + feedback flowing with zero
+ * further prompts. The token is the consultant's MCP Bearer (no new secret).
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function arg(name, def) {
+  const i = process.argv.indexOf('--' + name);
+  return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : def;
+}
+function log(msg) { process.stdout.write(msg + '\n'); }
+
+// (#pkg-4) Prefer GENIUS_TOKEN env over --token argv: argv leaks into the
+// process list and shell history. Warn if a token is passed on the CLI.
+let TOKEN = process.env.GENIUS_TOKEN || '';
+if (!TOKEN) {
+  TOKEN = arg('token', '');
+  if (TOKEN) log('WARN: passing --token on the CLI leaks it to the process list / shell history. Prefer GENIUS_TOKEN=... npx @xmarts/genius-setup');
+}
+const BASE = (arg('base-url', 'https://beesmart.digital')).replace(/\/+$/, '');
+const CLIENT = arg('client', '');
+if (!TOKEN) {
+  log('ERROR: a consultant Bearer token is required. Set GENIUS_TOKEN=<token> (preferred) or pass --token <token>.');
+  process.exit(1);
+}
+
+const HOME = os.homedir();
+const GENIUS_DIR = path.join(HOME, '.genius');
+const HOOKS_DIR = path.join(GENIUS_DIR, 'hooks');
+const CLAUDE_DIR = path.join(HOME, '.claude');
+
+function ensureDir(d) { fs.mkdirSync(d, { recursive: true }); }
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return {}; } }
+function backup(p) {
+  if (fs.existsSync(p)) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    fs.copyFileSync(p, p + '.genius-bak-' + stamp);
+  }
+}
+function writeJson(p, obj, secret) {
+  // (#pkg-3) secret files (token-bearing) are written 0600, never world-readable.
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2), secret ? { mode: 0o600 } : undefined);
+  if (secret) { try { fs.chmodSync(p, 0o600); } catch (_) {} }
+}
+
+// 1) ~/.genius/config.json + hook
+ensureDir(HOOKS_DIR);
+const cfg = {
+  base_url: BASE,
+  token: TOKEN,
+  capture_endpoint: BASE + '/xma/genius/v1/capture/transcript',
+  inject_endpoint: BASE + '/xma/genius/v1/inject',
+};
+if (CLIENT) cfg.target_client = CLIENT;
+writeJson(path.join(GENIUS_DIR, 'config.json'), cfg, true);  // secret: 0600
+
+// Copy the hooks shipped alongside this script (capture + per-turn inject).
+function copyHook(fname) {
+  const src = path.join(__dirname, '..', 'hooks', fname);
+  const dst = path.join(HOOKS_DIR, fname);
+  try {
+    fs.copyFileSync(src, dst);
+    try { fs.chmodSync(dst, 0o755); } catch (_) {}
+  } catch (e) {
+    log('WARN: could not copy hook from ' + src + ' (' + e.message + ')');
+  }
+  return dst;
+}
+const hookDst = copyHook('genius_capture.py');
+const injectDst = copyHook('genius_inject.py');
+
+// 2) ~/.claude.json mcpServers (merge, no clobber)
+const claudeJsonPath = path.join(HOME, '.claude.json');
+const claudeJson = readJson(claudeJsonPath);
+backup(claudeJsonPath);
+claudeJson.mcpServers = claudeJson.mcpServers || {};
+claudeJson.mcpServers['beesmart_genius'] = {
+  type: 'http',
+  url: BASE + '/mcp/consultant',
+  headers: { Authorization: 'Bearer ' + TOKEN },
+};
+writeJson(claudeJsonPath, claudeJson, true);  // contains the Bearer -> 0600
+
+// 3) ~/.claude/settings.json hooks (merge by command, no dup)
+const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
+const settings = readJson(settingsPath);
+backup(settingsPath);
+settings.hooks = settings.hooks || {};
+function addHook(eventName, scriptPath) {
+  settings.hooks[eventName] = settings.hooks[eventName] || [];
+  const marker = path.basename(scriptPath);
+  const already = JSON.stringify(settings.hooks[eventName]).includes(marker);
+  if (!already) {
+    const cmd = `python3 ${JSON.stringify(scriptPath)} || true`;
+    settings.hooks[eventName].push({ hooks: [{ type: 'command', command: cmd }] });
+  }
+}
+// Capture (transcript -> Brain) on session boundaries.
+['SessionEnd', 'PreCompact', 'Stop'].forEach((e) => addHook(e, hookDst));
+// Per-turn knowledge injection + session priming (consultant_access guarantee).
+['UserPromptSubmit', 'SessionStart'].forEach((e) => addHook(e, injectDst));
+writeJson(settingsPath, settings);
+
+log('');
+log('  Xmarts Genius is set up.');
+log('  - MCP server     : beesmart_genius -> ' + BASE + '/mcp/consultant');
+log('  - Capture hook   : ' + hookDst + '  (SessionEnd / PreCompact / Stop)');
+log('  - Inject hook    : ' + injectDst + '  (UserPromptSubmit / SessionStart)');
+log('  - Config         : ' + path.join(GENIUS_DIR, 'config.json'));
+if (CLIENT) log('  - Default client : ' + CLIENT);
+log('');
+log('  Restart Claude Code. Per-turn Brain injection + automatic capture are now active — no further prompts.');

package/hooks/genius_capture.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Genius deterministic session-capture hook (P3).
+
+Wired to Claude Code SessionEnd (+ PreCompact + Stop, guarded). The hook is the
+COMMAND-EXECUTION guarantee: directives the model may ignore, a hook always runs.
+It reads the session transcript and POSTs it to the Genius capture endpoint, so
+the server-side miner extracts the learnings the agent forgot to share — with
+zero consultant action.
+
+Hard rules:
+- ALWAYS exit 0 (never block or fail a session, even on network/parse errors).
+- Persist-then-network: every payload is first written to a local outbox spool;
+  on a successful POST it is removed, otherwise it stays and is retried on the
+  next hook firing. A central outage therefore never loses a capture.
+- Reads its config (endpoint + bearer token) from ~/.genius/config.json, written
+  once by the installer. No secrets are embedded here.
+
+Input: Claude Code passes a JSON event on stdin including `transcript_path` and
+`session_id`. We tolerate missing fields.
+"""
+import json
+import os
+import re
+import sys
+import time
+import urllib.request
+
+HOME = os.path.expanduser("~")
+CFG_PATH = os.path.join(HOME, ".genius", "config.json")
+OUTBOX_DIR = os.path.join(HOME, ".genius", "outbox")
+DEADLETTER_DIR = os.path.join(OUTBOX_DIR, "failed")
+MAX_OUTBOX_FILES = 200
+MAX_TRANSCRIPT_BYTES = 200_000
+
+
+def _load_cfg():
+    try:
+        with open(CFG_PATH) as fh:
+            return json.load(fh)
+    except Exception:
+        return {}
+
+
+def _read_stdin_event():
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+
+
+def _read_transcript(path):
+    if not path or not os.path.isfile(path):
+        return ""
+    try:
+        with open(path, "rb") as fh:
+            try:
+                fh.seek(-MAX_TRANSCRIPT_BYTES, os.SEEK_END)
+            except OSError:
+                fh.seek(0)
+            return fh.read().decode("utf-8", "replace")
+    except Exception:
+        return ""
+
+
+_CRED_PATTERNS = [
+    re.compile(r'-----BEGIN[A-Z ]*PRIVATE KEY-----.*?-----END[A-Z ]*PRIVATE KEY-----', re.DOTALL),
+    re.compile(r'(?i)\bBearer\s+[A-Za-z0-9._\-]{20,}'),
+    re.compile(r'(?i)postgres(?:ql)?://[^:\s/]+:[^@\s]+@'),
+    re.compile(r'(?i)(?:^|[\s_=:\'"])(password|passwd|pwd|secret|api[_-]?key|'
+               r'access[_-]?token|auth[_-]?token|fernet|secret[_-]?key|'
+               r'db[_-]?password|admin[_-]?passwd|client[_-]?secret)'
+               r'\s*[:=]\s*[\'"]?[^\s\'"]{6,}'),
+    re.compile(r'\b[A-Za-z0-9_\-]{43}=(?![A-Za-z0-9_\-=])'),
+    re.compile(r'\bAKIA[0-9A-Z]{16}\b'),
+    re.compile(r'\bAIza[0-9A-Za-z_\-]{35}\b'),
+    re.compile(r'\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}'),
+]
+
+
+def _redact(text):
+    """Client-side defense-in-depth: mask obvious secrets BEFORE they leave the
+    machine. The server re-redacts authoritatively at inbox enqueue (APS-1); this
+    just means a credential never even transits the network."""
+    if not text:
+        return text
+    for pat in _CRED_PATTERNS:
+        text = pat.sub("[REDACTED]", text)
+    return text
+
+
+def _spool_files():
+    if not os.path.isdir(OUTBOX_DIR):
+        return []
+    return sorted(f for f in os.listdir(OUTBOX_DIR) if f.endswith(".json"))
+
+
+def _spool(payload):
+    """Persist a payload. (#pkg-2) One file per session_ref — repeated Stop
+    firings of the SAME session OVERWRITE one file instead of creating N — and a
+    true on-disk RING BUFFER cap, dropping the oldest when at MAX_OUTBOX_FILES,
+    so the directory can never grow without bound."""
+    os.makedirs(OUTBOX_DIR, exist_ok=True)
+    sref = (payload.get("session_ref") or "s")[:40].replace("/", "_").replace(".", "_")
+    # session dedup: a stable name per session -> overwrite, not append
+    name = "sess_%s.json" % sref if sref != "s" else "%d_anon.json" % int(time.time() * 1000)
+    path = os.path.join(OUTBOX_DIR, name)
+    if not os.path.exists(path):
+        existing = _spool_files()
+        if len(existing) >= MAX_OUTBOX_FILES:
+            for old in existing[:len(existing) - MAX_OUTBOX_FILES + 1]:
+                try:
+                    os.remove(os.path.join(OUTBOX_DIR, old))
+                except Exception:
+                    pass
+    try:
+        with open(path, "w") as fh:
+            json.dump(payload, fh)
+    except Exception:
+        return None
+    return path
+
+
+def _post(endpoint, token, payload, timeout=15):
+    body = json.dumps({"jsonrpc": "2.0", "method": "call",
+                       "params": payload, "id": 1}).encode()
+    req = urllib.request.Request(endpoint, data=body)
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Authorization", "Bearer %s" % token)
+    # Cloudflare in front of beesmart.digital 403s the default Python-urllib UA.
+    req.add_header("User-Agent", "XmartsGenius-Capture/1.0")
+    resp = urllib.request.urlopen(req, timeout=timeout)
+    data = json.loads(resp.read())
+    result = data.get("result", data)
+    if isinstance(result, dict) and result.get("status") == "error":
+        # server-side rejection of THIS payload -> permanent
+        raise PermanentError(result.get("message", "capture error"))
+    return result
+
+
+class PermanentError(Exception):
+    pass
+
+
+def _flush_outbox(endpoint, token):
+    """Deliver spooled payloads oldest-first. (#pkg-1) A permanent rejection
+    (4xx other than 408/429, or a JSON-RPC error envelope) is dead-lettered to
+    outbox/failed/ and we CONTINUE, so one poison payload can never wedge the
+    whole queue; a transient error (offline / 5xx / timeout) stops the pass and
+    is retried next firing."""
+    import urllib.error
+    for name in _spool_files()[:MAX_OUTBOX_FILES]:
+        path = os.path.join(OUTBOX_DIR, name)
+        try:
+            with open(path) as fh:
+                payload = json.load(fh)
+            _post(endpoint, token, payload)
+            os.remove(path)  # delivered
+        except PermanentError:
+            _deadletter(path)            # bad payload -> set aside, keep going
+            continue
+        except urllib.error.HTTPError as he:
+            if he.code in (408, 429) or he.code >= 500:
+                break                    # transient server state -> retry later
+            _deadletter(path)            # 4xx (e.g. revoked token, 413) -> permanent
+            continue
+        except Exception:
+            break                        # offline / timeout -> retry next firing
+
+
+def _deadletter(path):
+    try:
+        os.makedirs(DEADLETTER_DIR, exist_ok=True)
+        os.replace(path, os.path.join(DEADLETTER_DIR, os.path.basename(path)))
+    except Exception:
+        try:
+            os.remove(path)
+        except Exception:
+            pass
+
+
+def main():
+    cfg = _load_cfg()
+    endpoint = cfg.get("capture_endpoint")
+    token = cfg.get("token")
+    if not endpoint or not token:
+        return  # not configured -> silent no-op
+
+    event = _read_stdin_event()
+    transcript = _redact(_read_transcript(event.get("transcript_path")))
+    session_ref = event.get("session_id") or event.get("session_ref") or ""
+
+    if transcript.strip():
+        payload = {
+            "transcript": transcript,
+            "session_ref": session_ref,
+            "source": "session_end_hook",
+        }
+        if cfg.get("target_client"):
+            payload["target_client"] = cfg["target_client"]
+        # persist first (durability), then try to deliver
+        _spool(payload)
+
+    # Always attempt to flush the spool (delivers this + any backlog)
+    try:
+        _flush_outbox(endpoint, token)
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)  # NEVER block a session

package/hooks/genius_inject.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Genius per-turn knowledge injection hook (P0 — consultant_access).
+
+Wired to Claude Code UserPromptSubmit (every turn) and SessionStart (priming).
+On UserPromptSubmit it asks the consultant-scoped Genius Brain for the top-k
+learnings relevant to the current prompt and emits them as
+`hookSpecificOutput.additionalContext`, so the consultant ALWAYS has the right
+prior knowledge WITHOUT asking. Editor-agnostic (terminal / VSCode / headless).
+
+Hard rules:
+- ALWAYS exit 0 (never block a turn).
+- Time-box the network call (<=2.5s) so injection adds no perceptible latency.
+- Relevance-floored: nothing relevant -> inject nothing (zero noise).
+- Reads endpoint + bearer from ~/.genius/config.json (written by the installer);
+  no secret is embedded here.
+"""
+import json
+import os
+import sys
+import urllib.request
+
+HOME = os.path.expanduser("~")
+CFG_PATH = os.path.join(HOME, ".genius", "config.json")
+TIMEOUT = 3.5
+
+SESSION_PRIMER = (
+    "[Xmarts Genius — Brain connected]\n"
+    "The Genius Brain (beesmart_genius MCP) is active for this session. Relevant "
+    "prior learnings are injected automatically on each prompt — you do not need "
+    "to ask for them. New learnings you produce are captured automatically at "
+    "session end. You may still call query_knowledge for a deeper search and "
+    "get_my_profile for your profile."
+)
+
+
+def _cfg():
+    try:
+        with open(CFG_PATH) as fh:
+            return json.load(fh)
+    except Exception:
+        return {}
+
+
+def _event():
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+
+
+def _emit(event_name, context):
+    if context:
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": event_name, "additionalContext": context}}))
+    sys.exit(0)
+
+
+def _inject(cfg, prompt):
+    base = (cfg.get("base_url") or "https://beesmart.digital").rstrip("/")
+    token = cfg.get("token")
+    if not token or not prompt.strip():
+        return ""
+    body = json.dumps({"jsonrpc": "2.0", "method": "call", "id": 1,
+                       "params": {"prompt": prompt[:4000], "limit": 4}}).encode()
+    req = urllib.request.Request(base + "/xma/genius/v1/inject", data=body)
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Authorization", "Bearer %s" % token)
+    # Cloudflare in front of beesmart.digital 403s the default Python-urllib UA.
+    req.add_header("User-Agent", "XmartsGenius-Inject/1.0")
+    try:
+        resp = urllib.request.urlopen(req, timeout=TIMEOUT)
+        data = json.loads(resp.read())
+        result = data.get("result", data)
+        return (result or {}).get("context", "") or ""
+    except Exception:
+        return ""
+
+
+def main():
+    cfg = _cfg()
+    if not cfg.get("token"):
+        return  # not configured -> silent no-op
+    event = _event()
+    name = event.get("hook_event_name") or (
+        "UserPromptSubmit" if event.get("prompt") else "SessionStart")
+    if name == "SessionStart":
+        _emit("SessionStart", SESSION_PRIMER)
+    else:
+        _emit("UserPromptSubmit", _inject(cfg, event.get("prompt") or ""))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)  # NEVER block a turn

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@xmarts/genius-setup",
+  "version": "1.2.0",
+  "description": "One-command frictionless onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session capture).",
+  "bin": {
+    "genius-setup": "bin/genius-setup.js"
+  },
+  "files": [
+    "bin/genius-setup.js",
+    "hooks/genius_inject.py",
+    "hooks/genius_capture.py",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "UNLICENSED",
+  "author": "Xmarts",
+  "private": false
+}