leopold-driver 0.1.1 → 0.1.3

package/README.md

@@ -58,14 +58,26 @@ npm run build
 
 ## Usage
 
-From any project that already has a `.leopold/` brief (written by `/leopold-brief`),
-and with Claude Code logged in:
+This package is the whole of Leopold from npm — it bundles the harness (skills, hooks,
+installer, extensions) so the CLI runs everything **without cloning the repo or `make`**.
+The binary is exposed as both `leopold-driver` and `leopold`.
 
 ```bash
-node /path/to/leopold/packages/driver/dist/index.js          # run
-node /path/to/leopold/packages/driver/dist/index.js --dry-run # load brief, show the plan, do nothing
+npm i -g leopold-driver
+
+leopold install              # copy skills + hooks into ~/.claude (also: --with-gstack)
+leopold menu                 # toolchain manager (serena / gstack / ovmem)
+leopold watch [--port N]     # live dashboard at http://127.0.0.1:4179  (needs Python 3)
+leopold serena install       # manage an extension directly (also: gstack, ovmem)
+leopold doctor               # run every extension's doctor
+leopold update               # reinstall from this package
+leopold run [--dry-run]      # conduct the .leopold run (the SDK driver below)
 ```
 
+`watch` reads the current project's `.leopold/` and shows run status, cost meters, the
+event feed, decisions, and a Stop button. `run` needs a `.leopold/` brief (from
+`/leopold-brief`) and your Claude Code login.
+
 ### Environment
 
 | Var | Default | Purpose |
@@ -83,7 +95,9 @@ in-session engine.
 ## Status and known limits
 
 Alpha. Verified: compiles against `@anthropic-ai/claude-agent-sdk`, the CLI and
-dry-run work, the status parser and git guard are tested. Not yet built: a
+dry-run work, and the status parser + `canUseTool` guard have unit tests
+(`make driver-test` / `npm test`) covering the same bypass attempts as the bash
+guard's red-team suite. Not yet built: a
 watchdog for a worker that ends a turn without emitting a status block (today the
 worker is strongly instructed to always emit one), parallel multi-worker waves,
 and the live dashboard. See the repo roadmap.

package/assets/VERSION

@@ -0,0 +1 @@
+0.4.4

package/assets/extensions/README.md

@@ -0,0 +1,52 @@
+# Leopold extension registry
+
+The toolchain manager (`scripts/leopold-menu.sh`, or `make menu`) is data-driven: it
+discovers everything under this directory and drives each one through a uniform contract.
+This is the generalization of the one-off gstack prompt that used to live in `install.sh`.
+
+## Layout
+
+```
+extensions/
+  <name>/
+    extension.json   # metadata the menu renders
+    manage.sh        # the actions the menu calls
+    README.md        # optional, per-extension docs
+```
+
+## extension.json
+
+```json
+{
+  "name": "gstack",
+  "title": "gstack",
+  "summary": "One-line description shown in the menu.",
+  "homepage": "https://...",
+  "license": "MIT",
+  "order": 20
+}
+```
+
+`order` controls position in the menu (lower first). Convention: Leopold core 10,
+the toolchain it conducts 20, companion capabilities 30+.
+
+## manage.sh contract
+
+`manage.sh <action>` where action is one of:
+
+| action  | must do | exit code |
+|---------|---------|-----------|
+| `detect`  | nothing visible; just probe | `0` if installed, non-zero if not |
+| `status`  | print one short line (e.g. version/health) | `0` |
+| `install` | install the component | `0` on success |
+| `update`  | update to latest | `0` on success |
+| `remove`  | uninstall (be reversible / safe where possible) | `0` on success |
+| `doctor`  | print diagnostics (what's wired, what's missing) | `0` |
+
+Rules:
+- Keep it idempotent. `install` run twice must not break anything.
+- Never touch the user's git. Never print secrets.
+- `detect` is the single source of truth for "installed?" — keep it cheap (no network).
+- Resolve the Claude home as `${CLAUDE_HOME:-$HOME/.claude}`.
+
+Adding a component is just dropping a new folder here with these two files.

package/assets/extensions/gstack/extension.json

@@ -0,0 +1,8 @@
+{
+  "name": "gstack",
+  "title": "gstack",
+  "summary": "Garry Tan's planning + QA skill suite that Leopold conducts (/spec, /autoplan, /plan-*-review).",
+  "homepage": "https://github.com/garrytan/gstack",
+  "license": "MIT",
+  "order": 20
+}

package/assets/extensions/gstack/manage.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# gstack extension - install/manage the gstack skill suite that Leopold conducts.
+# gstack is a separate MIT project by Garry Tan: https://github.com/garrytan/gstack
+set -euo pipefail
+
+CLAUDE="${CLAUDE_HOME:-$HOME/.claude}"
+SKILLS="$CLAUDE/skills"
+GSTACK_DIR="$SKILLS/gstack"
+REPO="https://github.com/garrytan/gstack.git"
+
+case "${1:-}" in
+  detect)
+    # installed if the clone exists, or if its skills are already present
+    [ -d "$GSTACK_DIR" ] || ls "$SKILLS" 2>/dev/null | grep -q '^spec$'
+    ;;
+
+  status)
+    if [ -d "$GSTACK_DIR/.git" ]; then
+      echo "$(cd "$GSTACK_DIR" && git rev-parse --short HEAD 2>/dev/null || echo present)"
+    else
+      echo "present"
+    fi
+    ;;
+
+  install)
+    if [ -d "$GSTACK_DIR" ]; then
+      echo "gstack already installed at $GSTACK_DIR"
+      exit 0
+    fi
+    command -v bun >/dev/null 2>&1 || echo "note: gstack needs Bun v1.0+ (https://bun.sh); its setup will guide you."
+    echo "-> cloning gstack into $GSTACK_DIR (shows progress; a few seconds)"
+    mkdir -p "$SKILLS"
+    git clone --progress --single-branch --depth 1 "$REPO" "$GSTACK_DIR"
+    echo "-> running gstack setup"
+    ( cd "$GSTACK_DIR" && ./setup )
+    echo "gstack installed."
+    ;;
+
+  update)
+    if [ ! -d "$GSTACK_DIR/.git" ]; then
+      echo "gstack not installed as a git clone; nothing to update. Run install."
+      exit 0
+    fi
+    echo "-> pulling gstack"
+    ( cd "$GSTACK_DIR" && git pull --ff-only -q && ./setup )
+    echo "gstack updated."
+    ;;
+
+  remove)
+    if [ -d "$GSTACK_DIR" ]; then
+      rm -rf "${GSTACK_DIR:?}"
+      echo "removed $GSTACK_DIR"
+    else
+      echo "gstack not present."
+    fi
+    ;;
+
+  doctor)
+    echo "dir:  $([ -d "$GSTACK_DIR" ] && echo "$GSTACK_DIR" || echo "missing")"
+    echo "bun:  $(command -v bun >/dev/null 2>&1 && bun --version 2>/dev/null || echo "not found (needed for setup)")"
+    echo "spec skill: $([ -d "$SKILLS/spec" ] && echo present || echo missing)"
+    ;;
+
+  *)
+    echo "usage: manage.sh {detect|status|install|update|remove|doctor}" >&2
+    exit 2
+    ;;
+esac

package/assets/extensions/leopold/extension.json

@@ -0,0 +1,8 @@
+{
+  "name": "leopold",
+  "title": "Leopold",
+  "summary": "The autonomous orchestration harness itself (skills + Stop/PreToolUse hooks).",
+  "homepage": "https://github.com/Jonhvmp/leopold",
+  "license": "MIT",
+  "order": 10
+}

package/assets/extensions/leopold/manage.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Leopold core extension - manage the harness install (skills + hooks).
+# install/update delegate to the canonical scripts so there is one source of truth.
+set -euo pipefail
+
+CLAUDE="${CLAUDE_HOME:-$HOME/.claude}"
+LEO_HOME="$CLAUDE/leopold"
+SKILLS="$CLAUDE/skills"
+
+# Resolve this extension's own location to reach sibling scripts / VERSION,
+# whether running from a clone (repo/extensions/leopold) or an install
+# (~/.claude/leopold/extensions/leopold).
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../.." && pwd)"   # repo root, or ~/.claude/leopold
+
+case "${1:-}" in
+  detect)
+    [ -d "$LEO_HOME/hooks" ] && [ -d "$SKILLS/leopold-run" ]
+    ;;
+
+  status)
+    if [ -f "$ROOT/VERSION" ]; then echo "v$(cat "$ROOT/VERSION" 2>/dev/null | tr -d '[:space:]')"; else echo "installed"; fi
+    ;;
+
+  install|update)
+    if [ -x "$ROOT/install.sh" ]; then
+      bash "$ROOT/install.sh"
+    elif [ -x "$LEO_HOME/scripts/leopold-update.sh" ]; then
+      bash "$LEO_HOME/scripts/leopold-update.sh"
+    else
+      echo "no installer found (expected $ROOT/install.sh or $LEO_HOME/scripts/leopold-update.sh)"
+      exit 1
+    fi
+    ;;
+
+  remove)
+    echo "Removing Leopold core also removes this menu. Doing it by hand keeps you in control:"
+    echo "  rm -rf $LEO_HOME"
+    echo "  rm -rf $SKILLS/leopold-*"
+    echo "  then remove the Stop + PreToolUse hooks from $CLAUDE/settings.json"
+    echo "  (a backup was written to settings.json.leopold.bak at install time)"
+    ;;
+
+  doctor)
+    if [ -x "$LEO_HOME/scripts/leopold-doctor.sh" ]; then
+      bash "$LEO_HOME/scripts/leopold-doctor.sh"
+    elif [ -x "$ROOT/scripts/leopold-doctor.sh" ]; then
+      bash "$ROOT/scripts/leopold-doctor.sh"
+    else
+      echo "skills:   $([ -d "$SKILLS/leopold-run" ] && echo ok || echo missing)"
+      echo "hooks:    $([ -d "$LEO_HOME/hooks" ] && echo ok || echo missing)"
+    fi
+    ;;
+
+  *)
+    echo "usage: manage.sh {detect|status|install|update|remove|doctor}" >&2
+    exit 2
+    ;;
+esac

package/assets/extensions/ovmem/README.md

@@ -0,0 +1,101 @@
+# ovmem extension
+
+**ovmem** gives Claude Code autonomous, self-managing long-term memory: it wires
+[OpenViking](https://github.com/volcengine/OpenViking) (a hierarchical context DB) to
+Claude Code through 4 native hooks, so any session stays optimized without destructive
+`/compact` or `/clear`. Distillation, dedup and reconsolidation happen server-side; a
+weekly hotness prune keeps the store from accumulating.
+
+The installer is a **provider + model picker**. It runs `detect / status / install /
+update / remove / doctor` like every extension; `install` walks you through:
+
+```
+Provider:  1) openai   2) bedrock
+chat model:   gpt-4o-mini  $0.15 in / $0.60 out per 1M · ctx 128k · cheap default
+              ...
+embed model:  text-embedding-3-small  $0.02 per 1M · 1536d · default
+              ...
+```
+
+Prices and the model lineup live in [`models.json`](models.json) — the single source the
+picker reads (USD per 1M tokens, approximate, sourced from the LiteLLM price map). For
+ovmem the real cost is **cents**: extraction only runs at PreCompact / SessionEnd.
+
+## Providers
+
+### OpenAI
+
+One API key (needs the **embedding** and **`model.request`/chat** scopes). The installer
+validates the key against both before saving it to `~/.openviking/ov.conf` (`chmod 600`).
+
+- chat: `gpt-4o-mini` (default) · `gpt-4.1-mini` · `gpt-4o`
+- embed: `text-embedding-3-small` (1536d, default) · `text-embedding-3-large` (3072d)
+
+### AWS Bedrock
+
+Routed through OpenViking's LiteLLM backends. Auth is a **Bedrock API key (bearer token)**
+plus a **region** — that is all the user passes. The installer:
+
+- adds `boto3` to the OpenViking tool venv (`uv tool install --with boto3 …`),
+- writes the bearer token + region into the server's launch env (`openviking-start`, `chmod 700`),
+- sets `vlm.provider` / `embedding.dense.provider` to `litellm` with `bedrock/…` model ids.
+
+- chat: `nova-lite` (cheapest) · `claude-3-5-haiku` · `claude-3-5-sonnet` · `claude-sonnet-4-5`
+- embed: `titan-embed-v2` (1024d) · `cohere-embed-v3` (1024d) · `titan-embed-v1` (1536d)
+
+> The chat model ids use the `us.` cross-region inference profile. The model must be
+> **enabled in your AWS account** (Bedrock → Model access). The installer's round-trip
+> step surfaces a clear error if access/region/token is wrong. The Bedrock path is
+> implemented against OpenViking's verified config shape but has not been run against a
+> live AWS account in CI — treat it as beta.
+
+## Switching providers / reconfiguring
+
+Run `install` (or `update`) from the toolchain menu again — it is also the reconfigure
+path. It detects the current setup, **offers to reuse the existing credential**, defaults
+every prompt to your current choice, and:
+
+- **Chat-only change** (or new model, same embedding) → just rewrites `ov.conf` and
+  restarts. Your memories are untouched.
+- **Embedding change** (e.g. OpenAI → Bedrock, where the dimension goes 1536 → 1024) →
+  the vector index is **rebuilt**: it backs up and drops the index, lets the server
+  recreate it at the new dimension, then re-embeds every memory (`content/reindex`). Your
+  memory **content is preserved** — only the index is rebuilt. If the rebuild fails, the
+  previous index **and** config are restored automatically.
+
+Server restarts are lock-aware (one OpenViking process per data dir — a kill+restart race
+on the data-dir lock is exactly what breaks otherwise).
+
+## Notes that bite
+
+- **The embedding model sets the vector dimension** (1536 / 3072 / 1024), baked into the
+  vectordb. Changing it is handled by the reindex above, but it re-embeds the whole store
+  (cents + a few seconds), so don't flip it casually.
+- **`vlm.max_tokens`**: 16384 for OpenAI gpt-4o-mini (its cap), 8192 for Bedrock.
+- **`output_language_override: "en"`** pins memory + summaries to English.
+
+## Headless / CI install
+
+No terminal? Set the choices via env (the picker reads `/dev/tty` interactively, or these
+when there is none):
+
+```bash
+OVMEM_PROVIDER=openai  OVMEM_CHAT_MODEL=gpt-4o-mini  OVMEM_EMBED_MODEL=text-embedding-3-small \
+  OPENAI_API_KEY=sk-... bash install.sh
+# or
+OVMEM_PROVIDER=bedrock OVMEM_CHAT_MODEL=claude-3-5-haiku OVMEM_EMBED_MODEL=titan-embed-v2 \
+  AWS_BEARER_TOKEN_BEDROCK=... AWS_REGION=us-east-1 bash install.sh
+```
+
+## Runtime model (reference)
+
+4 hooks → OpenViking REST:
+- **SessionStart** — bootstrap the server + rehydrate (session summary + long-term memory)
+- **UserPromptSubmit** — recall: inject memory relevant to the prompt (token-budgeted)
+- **PreCompact** — flush the transcript delta + commit *before* compaction destroys it
+- **SessionEnd** — flush + commit, then the weekly hotness prune (`ovmem-cleanup.py`)
+
+Dedup and obsolescence are handled natively by OpenViking on commit. Cold-memory
+accumulation is pruned by `ovmem-cleanup.py` (hotness = frequency × recency decay).
+Everything is local: the server binds `127.0.0.1` only. The lone outbound call is to the
+chosen provider (OpenAI or Bedrock, with the user's own credential) for embeddings/extraction.

package/assets/extensions/ovmem/extension.json

@@ -0,0 +1,8 @@
+{
+  "name": "ovmem",
+  "title": "ovmem",
+  "summary": "Autonomous RAG long-term memory (OpenViking + 4 hooks). Provider + model picker (OpenAI / AWS Bedrock) with prices.",
+  "homepage": "https://github.com/Jonhvmp/leopold",
+  "license": "MIT",
+  "order": 30
+}