@xmarts/genius-setup 1.2.0 → 1.4.0

package/CLAUDE_PROTOCOL.md

@@ -0,0 +1,36 @@
+# Xmarts Genius — Protocolo de Consultor
+
+> Esta sección la instala/actualiza automáticamente `@xmarts/genius-setup`. No la edites a mano.
+
+## Cómo funciona (cero fricción)
+
+El Brain de Genius está conectado vía el MCP **`beesmart_genius`** y dos hooks de Claude Code:
+- **Inyección por turno** (UserPromptSubmit/SessionStart): en cada turno recibes automáticamente los
+  learnings, playbooks y patrones relevantes — no tienes que pedirlos.
+- **Captura automática** (SessionEnd/PreCompact/Stop): tus hallazgos y tu sesión se capturan solos al
+  final; no tienes que documentar manualmente.
+- **Auto-actualización**: el paquete se refresca solo en segundo plano (1×/día). Cuando agregamos tools,
+  skills o features, las recibes en tus turnos **sin hacer nada**.
+
+## Reglas Obligatorias (siempre activas)
+
+1. **ANTES de cada tarea**: usa `query_knowledge` (o `ask_brain`) para buscar conocimiento existente.
+2. **AL descubrir algo nuevo**: captura con `capture_learning` — título claro + resolución detallada.
+3. **AL resolver un error**: documenta error → fix (el Brain auto-detecta el par).
+4. **SIEMPRE usa `target_client`** para operar en un cliente (p.ej. `target_client="GEA Ecuador"`).
+5. **NUNCA te conectes directo al Odoo del cliente** — todo fluye por el MCP `beesmart_genius`.
+6. Tu tiempo se sugiere solo a partir de tu actividad; confírmalo cuando puedas en **My Week**
+   (`/mcp/webapp/my-week`). Solo el tiempo que confirmas cuenta como horas reales.
+
+## Tools (servidas dinámicamente por `beesmart_genius`)
+
+| Tool | Cuándo usar |
+|------|-------------|
+| `query_knowledge` | Antes de cada tarea — busca en el Brain |
+| `capture_learning` | Al descubrir algo nuevo |
+| `get_my_profile` | Ver tu perfil de consultor |
+| `search_read` / `execute_orm` + `target_client` | Consultar/operar data de cualquier cliente vía gateway |
+| `list_models` / `get_model_schema` + `target_client` | Inspeccionar esquema de un cliente |
+
+> La lista completa de tools (y skills como prompts) la sirve el MCP en tiempo real; al agregar nuevas,
+> aparecen automáticamente en tu sesión sin reconfigurar nada.

package/bin/genius-setup.js

@@ -118,12 +118,38 @@ function addHook(eventName, scriptPath) {
 ['UserPromptSubmit', 'SessionStart'].forEach((e) => addHook(e, injectDst));
 writeJson(settingsPath, settings);
 
+// 4) ~/.claude/CLAUDE.md — install/refresh the Genius Protocol between auto-managed
+//    markers (idempotent; never clobbers the consultant's surrounding content).
+const BEGIN = '<!-- XMARTS-GENIUS-PROTOCOL:BEGIN (auto-managed by @xmarts/genius-setup) -->';
+const END = '<!-- XMARTS-GENIUS-PROTOCOL:END -->';
+try {
+  ensureDir(CLAUDE_DIR);
+  const claudeMdPath = path.join(CLAUDE_DIR, 'CLAUDE.md');
+  let existing = '';
+  try { existing = fs.readFileSync(claudeMdPath, 'utf8'); } catch (_) {}
+  const proto = fs.readFileSync(path.join(__dirname, '..', 'CLAUDE_PROTOCOL.md'), 'utf8').trim();
+  const block = BEGIN + '\n' + proto + '\n' + END;
+  let out;
+  if (existing.includes(BEGIN) && existing.includes(END)) {
+    out = existing.slice(0, existing.indexOf(BEGIN)) + block +
+          existing.slice(existing.indexOf(END) + END.length);
+  } else {
+    out = (existing ? existing.replace(/\s+$/, '') + '\n\n' : '') + block + '\n';
+  }
+  fs.writeFileSync(claudeMdPath, out);
+} catch (e) {
+  log('WARN: could not write CLAUDE.md protocol (' + e.message + ')');
+}
+
 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'));
+log('  - Protocol       : ' + path.join(CLAUDE_DIR, 'CLAUDE.md') + '  (auto-managed)');
 if (CLIENT) log('  - Default client : ' + CLIENT);
 log('');
-log('  Restart Claude Code. Per-turn Brain injection + automatic capture are now active — no further prompts.');
+log('  Restart Claude Code. Per-turn Brain injection + automatic capture + the Genius');
+log('  protocol are now active. The package SELF-UPDATES daily in the background, so new');
+log('  tools, skills and features arrive automatically — you never have to run this again.');

package/hooks/genius_capture.py

@@ -18,6 +18,7 @@ Hard rules:
 Input: Claude Code passes a JSON event on stdin including `transcript_path` and
 `session_id`. We tolerate missing fields.
 """
+import datetime as _dt
 import json
 import os
 import re
@@ -63,6 +64,75 @@ def _read_transcript(path):
         return ""
 
 
+_SESSION_GAP_SECONDS = 30 * 60     # idle gap that splits work into blocks
+_METRIC_MAX_LINES = 40000
+
+
+def _parse_ts(s):
+    try:
+        return _dt.datetime.fromisoformat(str(s).replace("Z", "+00:00"))
+    except Exception:
+        return None
+
+
+def _session_metrics(path):
+    """Derive honest session timing from the transcript JSONL: gap-clustered
+    ACTIVE minutes (idle gaps removed), start/end, and tool-event count. This is
+    the human-work signal the server turns into hours — computed locally so no
+    transcript content is needed to know the TIME spent."""
+    if not path or not os.path.isfile(path):
+        return None
+    times, tool_events = [], 0
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            for i, line in enumerate(fh):
+                if i >= _METRIC_MAX_LINES:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                t = _parse_ts(obj.get("timestamp")) if obj.get("timestamp") else None
+                if t:
+                    times.append(t)
+                msg = obj.get("message") or {}
+                content = msg.get("content") if isinstance(msg, dict) else None
+                if isinstance(content, list):
+                    for blk in content:
+                        if isinstance(blk, dict) and blk.get("type") == "tool_use":
+                            tool_events += 1
+    except Exception:
+        return None
+    if not times:
+        return None
+    times.sort()
+    active = 0.0
+    start = prev = times[0]
+    blocks = []
+    for t in times[1:]:
+        if (t - prev).total_seconds() > _SESSION_GAP_SECONDS:
+            blocks.append((start, prev))
+            start = t
+        prev = t
+    blocks.append((start, prev))
+    for a, b in blocks:
+        active += max((b - a).total_seconds(), 60.0)   # >=1 min per block
+
+    def _fmt(d):
+        if d.tzinfo:
+            d = d.astimezone(_dt.timezone.utc).replace(tzinfo=None)
+        return d.strftime("%Y-%m-%d %H:%M:%S")
+    return {
+        "started_at": _fmt(times[0]),
+        "ended_at": _fmt(times[-1]),
+        "active_minutes": round(active / 60.0, 2),
+        "tool_events": tool_events,
+    }
+
+
 _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,}'),
@@ -95,15 +165,16 @@ def _spool_files():
     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
+def _spool(payload, prefix="sess"):
+    """Persist a payload. (#pkg-2) One file per (prefix, session_ref) — repeated
     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."""
+    so the directory can never grow without bound. The prefix keeps the transcript
+    payload ('sess') and the session-metadata payload ('meta') as distinct files."""
     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)
+    # session dedup: a stable name per (prefix, session) -> overwrite, not append
+    name = "%s_%s.json" % (prefix, 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()
@@ -122,6 +193,7 @@ def _spool(payload):
 
 
 def _post(endpoint, token, payload, timeout=15):
+    payload = {k: v for k, v in payload.items() if k != "_endpoint"}
     body = json.dumps({"jsonrpc": "2.0", "method": "call",
                        "params": payload, "id": 1}).encode()
     req = urllib.request.Request(endpoint, data=body)
@@ -154,7 +226,7 @@ def _flush_outbox(endpoint, token):
         try:
             with open(path) as fh:
                 payload = json.load(fh)
-            _post(endpoint, token, payload)
+            _post(payload.get("_endpoint") or endpoint, token, payload)
             os.remove(path)  # delivered
         except PermanentError:
             _deadletter(path)            # bad payload -> set aside, keep going
@@ -186,20 +258,58 @@ def main():
     if not endpoint or not token:
         return  # not configured -> silent no-op
 
+    # Derive the metadata-only session endpoint (no content) from the configured
+    # capture endpoint or base_url.
+    session_endpoint = cfg.get("session_endpoint")
+    if not session_endpoint:
+        if "/capture/transcript" in endpoint:
+            session_endpoint = endpoint.replace("/capture/transcript", "/capture/session")
+        elif cfg.get("base_url"):
+            session_endpoint = cfg["base_url"].rstrip("/") + "/xma/genius/v1/capture/session"
+
     event = _read_stdin_event()
-    transcript = _redact(_read_transcript(event.get("transcript_path")))
+    tpath = event.get("transcript_path")
+    transcript = _redact(_read_transcript(tpath))
     session_ref = event.get("session_id") or event.get("session_ref") or ""
 
-    if transcript.strip():
+    # Off-platform / sensitive work keeps CONTENT out of the Brain entirely — only
+    # the TIME (session metadata) is sent. Inferred from an explicit pii_safe flag
+    # or a topic set with no Genius client (e.g. Ateneai insurance/medical work).
+    offplatform = bool(cfg.get("pii_safe")) or (
+        bool(cfg.get("topic")) and not cfg.get("target_client"))
+
+    if transcript.strip() and not offplatform:
         payload = {
             "transcript": transcript,
             "session_ref": session_ref,
             "source": "session_end_hook",
+            "_endpoint": endpoint,
         }
         if cfg.get("target_client"):
             payload["target_client"] = cfg["target_client"]
         # persist first (durability), then try to deliver
-        _spool(payload)
+        _spool(payload, prefix="sess")
+
+    # Claude-session TIME metadata (no content) -> /capture/session. This is the
+    # honest human-work signal; it also covers off-platform sessions (no client).
+    if session_endpoint and session_ref:
+        metrics = _session_metrics(tpath)
+        if metrics and metrics.get("active_minutes", 0) > 0:
+            meta = {
+                "session_ref": session_ref,
+                "source": "transcript_hook",
+                "is_offplatform": offplatform,
+                "_endpoint": session_endpoint,
+            }
+            meta.update(metrics)
+            if cfg.get("target_client"):
+                meta["target_client"] = cfg["target_client"]
+            ws = cfg.get("workspace") or event.get("cwd")
+            if ws:
+                meta["workspace"] = ws
+            if cfg.get("topic"):
+                meta["topic"] = cfg["topic"]
+            _spool(meta, prefix="meta")
 
     # Always attempt to flush the spool (delivers this + any backlog)
     try:

package/hooks/genius_inject.py

@@ -22,6 +22,8 @@ import urllib.request
 HOME = os.path.expanduser("~")
 CFG_PATH = os.path.join(HOME, ".genius", "config.json")
 TIMEOUT = 3.5
+SELF_UPDATE_TTL = 86400  # at most once/day
+SELF_UPDATE_STAMP = os.path.join(HOME, ".genius", ".last_selfupdate")
 
 SESSION_PRIMER = (
     "[Xmarts Genius — Brain connected]\n"
@@ -77,10 +79,53 @@ def _inject(cfg, prompt):
         return ""
 
 
+def _maybe_self_update(cfg):
+    """Keep the consultant on the LATEST Genius package with ZERO action: at most
+    once/day, silently re-run the installer in the background. New hooks, MCP
+    tools, settings and the CLAUDE.md protocol then flow automatically — the
+    consultant never re-onboards. Detached + fully guarded; never blocks a turn.
+    """
+    import time
+    import subprocess
+    try:
+        token = cfg.get("token")
+        if not token:
+            return
+        if os.path.exists(SELF_UPDATE_STAMP) and (
+                time.time() - os.path.getmtime(SELF_UPDATE_STAMP)) < SELF_UPDATE_TTL:
+            return
+        # Stamp FIRST so a failing/slow npx never causes a retry storm.
+        try:
+            os.makedirs(os.path.dirname(SELF_UPDATE_STAMP), exist_ok=True)
+            with open(SELF_UPDATE_STAMP, "w") as fh:
+                fh.write(str(int(time.time())))
+        except Exception:
+            return
+        env = dict(os.environ)
+        env["GENIUS_TOKEN"] = token
+        base = cfg.get("base_url")
+        devnull = open(os.devnull, "w")
+        if os.name == "nt":
+            cmd = "npx -y @xmarts/genius-setup@latest"
+            if base:
+                cmd += ' --base-url "%s"' % base
+            subprocess.Popen(cmd, shell=True, env=env, stdout=devnull, stderr=devnull,
+                             stdin=subprocess.DEVNULL, creationflags=0x00000008)  # DETACHED_PROCESS
+        else:
+            args = ["npx", "-y", "@xmarts/genius-setup@latest"]
+            if base:
+                args += ["--base-url", base]
+            subprocess.Popen(args, env=env, stdout=devnull, stderr=devnull,
+                             stdin=subprocess.DEVNULL, start_new_session=True)
+    except Exception:
+        pass
+
+
 def main():
     cfg = _cfg()
     if not cfg.get("token"):
         return  # not configured -> silent no-op
+    _maybe_self_update(cfg)   # background, daily, zero-action upgrades
     event = _event()
     name = event.get("hook_event_name") or (
         "UserPromptSubmit" if event.get("prompt") else "SessionStart")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xmarts/genius-setup",
-  "version": "1.2.0",
-  "description": "One-command frictionless onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session capture).",
+  "version": "1.4.0",
+  "description": "One-command, self-updating onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session/time capture + CLAUDE.md protocol). Installs once; self-updates daily so new tools/skills/features arrive with zero action.",
   "bin": {
     "genius-setup": "bin/genius-setup.js"
   },
@@ -9,6 +9,7 @@
     "bin/genius-setup.js",
     "hooks/genius_inject.py",
     "hooks/genius_capture.py",
+    "CLAUDE_PROTOCOL.md",
     "README.md"
   ],
   "engines": {