vibeostheog 0.15.22 → 0.15.34

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.15.23
+- feat: add trinity api-token command to inject VIBEOS_API_TOKEN
+
+
 ## 0.15.22
 - chore: update flash pricing, add fallback indicator to footer
 

package/README.md

@@ -1,225 +1,45 @@
 # vibeOS for OpenCode
 
-Cost-aware delegation and policy plugin for OpenCode Desktop.
+VIBE is a smart model router for OpenCode Desktop. It automatically selects and switches between brain, medium, and cheap model tiers based on the task at hand — expensive models handle orchestration while cost-effective models execute implementation work. No manual slot-picking needed.
 
-vibeOS helps keep expensive model usage under control by enforcing delegation behavior, tracking savings, and exposing runtime controls through the `trinity` tool.
+The core is the VIBE autoswitcher: a decision engine that routes each request to the right tier based on context, enforcement policy, and session state. You stay in control via the `trinity` tool set, but the default workflow is zero-config.
 
-## Version
+Beyond routing, vibeOS tracks savings from tier-switching, enforces delegation policies, and provides real-time visibility through a live status footer and web dashboard.
 
-Current package version: `0.14.1`
+## Savings Categories
 
-## What It Does
-
-- Tracks estimated savings from delegation warnings and enforcement events.
-- Tracks cache savings as a separate persisted category when scratchpad cache hits are observed.
-- Adds a live footer to assistant outputs with model split, cumulative savings, and trend arrow.
-- Provides `trinity` runtime controls for slot switching, enforcement toggles, audits, and diagnostics.
-- Adds per-session model locking: prevents the plugin from auto-switching models when the user changes the model in the OpenCode GUI (`trinity lock on|off`).
-- Adds optional flow checks and TDD skeleton enforcement.
-- Adds project guard: ensures AGENTS.md and README.md exist and stay protected in every project.
-- Adds report and research-audit tooling.
-- Learns recurring struggle and routine patterns per project, with `trinity patterns` inspection and `trinity patterns clear`.
-- Stress mitigation pipeline: detects user stress signals, shows live stress gauge in footer, injects protective system prompts, and upgrades Task tier when user is stressed.
-- vibeOS MCP server with HTTP API for extended tool capabilities (trinity, reports, session metrics, diagnostics).
-- TUI dashboard sidebar plugin for real-time plugin status and controls.
-- **Web dashboard** — SolidJS SPA served via standalone server (`npm run dashboard`) or embedded in the MCP server. Real-time SSE push updates at `http://127.0.0.1:3333`.
-- Worker-to-Brain (WBP) protocol synthesizes delegated task output directly in assistant chat.
-- **Remote API protection**: Core algorithms run on a self-hosted API server (`api.vibetheog.com`) with token-based authentication. Non-paying seats can be deactivated, immediately revoking all API tokens and falling back to local degraded mode.
-
-## Remote API Protection
-
-vibeOS protects its core algorithms by serving them from a self-hosted API server rather than bundling them entirely in the plugin:
-
-| Algorithm | Endpoint | Description |
-|---|---|---|---|
-| Delegation enforcement | `POST /api/v1/delegate/check` | Model cost calculation, block/warn routing |
-| Model tier routing | `POST /api/v1/route/model` | Tier classification, stress-aware routing |
-| Stress scoring | `POST /api/v1/stress/score` | NLP stress signal detection |
-| Blackbox engine | `POST /api/v1/blackbox/analyze` | Dialogue trajectory, loop detection, pivot/switch, outcome tracking |
-| Blackbox calibration | `POST /api/v1/blackbox/calibrate` | Auto-tune thresholds from session outcomes |
-| Blackbox calibration state | `GET /api/v1/blackbox/calibration` | Read calibrated weights per project |
-| Blackbox outcome | `POST /api/v1/blackbox/outcome` | Record session satisfaction outcome |
-| Blackbox project sessions | `GET /api/v1/blackbox/project-sessions` | List cross-session history per project |
-| TDD skeleton gen | `POST /api/v1/tdd/skeleton` | Multi-language test generation |
-| Pattern learner | `POST /api/v1/patterns/observe` | Friction/routine detection |
-| Model pricing | `POST /api/v1/pricing/fetch` | Dynamic OpenRouter pricing cache |
-| Context compression | `POST /api/v1/compress/context` | Bullet-point extraction |
-
-### Environment Variables
-
-```
-VIBEOS_API_URL=https://api.vibetheog.com   # API server URL (default: https://api.vibetheog.com)
-VIBEOS_API_TOKEN=vos_...                    # Your API token (required for remote mode)
-VIBEOS_API_ENABLED=true                     # Set to "false" to use local-only mode
-CLAUDE_CREDIT_PERCENT=150                   # Override credit percentage (default: 100)
-CLAUDE_CONTEXT7_AVAILABLE=true              # Set to enable context7 cost optimization
-CLAUDE_SCRATCHPAD_MAX_AGE_SEC=86400         # Scratchpad cache lifetime in seconds
-VIBEOS_MCP_PORT=3001                        # MCP server port (default: 3001)
-```
-
-When `VIBEOS_API_TOKEN` is not set or `VIBEOS_API_ENABLED=false`, the plugin runs in local-only mode with all algorithms bundled. When a valid token is provided, core algorithms are offloaded to the remote API.
-
-### Seat & Token Management
-
-The API server manages licenses via seats:
-
-- **Create a seat + token** (WordPress integration):  
-  `POST /admin/seats` with `{ "name": "...", "email": "...", "with_token": "label" }`
-
-- **Suspend a seat** (non-paying customer):  
-  `PATCH /admin/seats/:id` with `{ "status": "suspended" }`  
-  This immediately revokes all API tokens for that seat. The plugin falls back to local degraded mode.
-
-- **Reactivate a seat**:  
-  `PATCH /admin/seats/:id` with `{ "status": "active" }`
-
-## Runtime Model Slots
-
-Slots are configured in `~/.claude/model-tiers.json`:
-
-- `brain`
-- `medium`
-- `cheap`
-
-On startup, the plugin detects the active model/slot from `model-tiers.json`. No automatic slot switching occurs; use `trinity set <slot>` or `trinity rebuild` to change slots.
-
-## Savings Categories (Persisted)
-
-State file: `~/.claude/delegation-state.json`
-
-- Delegation savings:
-  - `sessions[...].warns[].est_savings_usd`
-  - aggregated into footer totals
-- Cache savings:
-  - `sessions[...].cache_savings_usd`
-  - `lifetime.cache_savings_usd`
-  - optional `sessions[...].cache_hits[]` audit entries
-- Context7 missed-savings tracker:
-  - `lifetime.missed_context7_usd`
-
-## Footer Format
-
-Typical output footer:
-
-`— [model route] | VibeTheOG: <total> saved <arrow> —`
-
-Example (with savings):
-
-`— [🧠 deepseek-v4-flash → ⚙ deepseek-chat] | VibeTheOG: 0.01 saved → —`
-
-Example (no savings yet, tier label only):
-
-`— [⚙ Mid] —`
-
-## `trinity` Tool Commands
-
-Main commands:
-
-- `trinity status`
-- `trinity set brain|medium|cheap`
-- `trinity brain|medium|cheap`
-- `trinity enable` / `trinity disable`
-- `trinity thinking full|brief|off`
-- `trinity enforce` / `trinity enforce on|off`
-- `trinity lock on|off` / `trinity lock`
-- `trinity flow on|off` / `trinity flow enforce on|off` / `trinity flow`
-- `trinity tdd on|off` / `trinity tdd strict on|off` / `trinity tdd quality on|off` / `trinity tdd`
-- `trinity project`
-- `trinity patterns`
-- `trinity patterns clear`
-- `trinity patterns suggest`
-- `trinity repair-state`
-- `trinity guard`
-- `trinity diagnose`
-- `trinity rebuild`
-- `trinity help`
-
-## Optional Enforcement Modules
+- **Delegation savings** — Estimated cost avoided by routing tasks to cheaper models.
+- **Cache savings** — Cost avoided from scratchpad cache hits.
 
-- Delegation enforcement:
-  - Blocks direct `write`/`edit`/`notebookedit` on high-tier brain when enabled.
-  - Adds user-visible enforcement notes.
-- Flow enforcer:
-  - Rule checks for write/edit patterns.
-  - Optional TODO/FIXME extraction queue when flow enforcement is enabled.
-- TDD enforcer:
-  - Auto-creates skeleton tests for changed source files when enabled.
-  - Strict mode is ON by default: TODO tests fail loudly until implemented.
-- Project Guard:
-  - On session init, checks if AGENTS.md and README.md exist in the project root.
-  - Auto-creates AGENTS.md with protective rules (LLM must ask before modifying code).
-  - Auto-creates README.md with tech stack auto-detection and feature stubs.
-  - Flow rules warn/flag on write/edit to these protected files.
-  - System prompt injects directive to maintain both files.
-  - `trinity guard` command regenerates both files on demand.
+Both are summed in the live footer and persisted in \`~/.claude/delegation-state.json\` across sessions.
 
-## Reports and Audit Tools
-
-- `research-audit`
-- `report-save`
-- `report-list`
-- `report-read`
-
-These use `~/.claude/reports` and project memory in `~/.claude/project-states.json`.
-
-## Pattern Learning
-
-- Detects repeated friction signals and recurring successful routines from session behavior.
-- Stores per-project pattern memory in `~/.claude/project-states.json`.
-- Promotes patterns after repeated confirmation across sessions and surfaces them via `trinity patterns`.
-
-## Blackbox Decision Engine
-
-The blackbox tracks dialogue trajectory per-session and per-project, providing real-time decision state insights:
-
-**Enabled by default.**
-
-- **Resolution tracking**: Classifies each session into one of 7 sub-regimes (INIT, DIVERGENT, EXPLORING, REFINING, CONVERGING, CLOSED, LOOPING) based on entropy trends, action consistency, feature contradiction, and embedding drift.
-- **Real feature extraction**: Derives 11 features from each user message — message length, word count, question ratio, code blocks, urgency signals, sentiment, complexity, repetition, and instruction density.
-- **Loop prevention**: Detects when the conversation is going in circles and injects escalating system prompt interventions (gentle → suggestive → assertive → escalated) to break the loop.
-- **PIVOT/SWITCH detection**: Recognizes when the user changes context outside the current project scope and injects scope-confirmation directives.
-- **Outcome tracking**: Detects satisfaction signals from assistant responses (positive: "thanks/that works/perfect"; negative: "broken/still failing/wrong") and records them for calibration.
-- **Cross-session continuity**: State persists per project fingerprint in `~/.claude/blackbox-state.json` and remotely in SQLite, allowing resolution state to carry across terminal restarts.
-- **Online calibration**: The API server aggregates session outcomes and auto-tunes loop detection, momentum, and closure thresholds per project via `POST /api/v1/blackbox/calibrate`.
-
-Commands:
-- `trinity blackbox on` — Enable the decision engine
-- `trinity blackbox off` — Disable the decision engine
-- `trinity blackbox status` — View current resolution, sub-regime, momentum, loop state, and project history
-- `trinity blackbox reset` — Clear the resolution tracker for the current session
-
-
-The blackbox injects a decision directive into system prompts showing current resolution state, intent volatility, and continuity. When looping or pivoting is detected, stronger intervention directives are injected to guide the model.
-
-### Session Workflow Phases
-
-The meta-controller maps detected sub-regimes to optimization modes, which are the authority over all plugin settings. Each turn, `syncControlSettings()` writes the mode's control vector to `model-tiers.json`, auto-toggling enforcement, flow, TDD, and thinking level:
-
-| Regime | Mode | Enforce | Flow | TDD | Tier | Think |
-|---|---|---|---|---|---|---|
-| INIT | budget | relaxed | audit | lazy | cheap | off |
-| EXPLORING / DIVERGENT | budget | relaxed | audit | lazy | cheap | off |
-| REFINING | budget | relaxed | audit | lazy | cheap | off |
-| CONVERGING / CLOSED | quality | strict | strict | quality | brain | full |
-| LOOPING | speed | relaxed | audit | lazy | medium | off |
-
-**Stress override**: When user stress exceeds 1.5, any regime escalates to `quality` mode — enforcement tightens, brain tier activates. Settings are re-synced every turn; mode is the sole authority. Manual `trinity enforce on/off` still works until the next turn re-evaluates.
+## What It Does
 
-When the blackbox is disabled, a lightweight `classifyTurnSimple()` fallback inspects user message patterns:
-- Q&A patterns (`"how"`, `"what"`, `"explain"`) → EXPLORING (relaxed)
-- Implementation patterns (`"write"`, `"fix"`, `"implement"`) → REFINING (normal)
+- **Smart delegation** — Blocks direct write/edit on high-tier models and routes work to cheaper subagents
+- **Cost tracking** — Tracks estimated savings from delegation events and cache hits, displayed in a live footer
+- **trinity commands** — Runtime controls for model switching, enforcement toggles, audits, and diagnostics
+- **Flow enforcer** — Validates write/edit patterns against project rules; optionally extracts TODOs/FIXMEs
+- **TDD enforcer** — Auto-creates test skeletons for changed source files; strict mode makes TODO tests fail loudly
+- **Project guard** — Protects AGENTS.md and README.md in every project with auto-regeneration
+- **Pattern learner** — Detects recurring friction and routine patterns per project, surfaces via `trinity patterns`
+- **Stress mitigation** — Detects user stress signals, adjusts tier routing, and injects protective prompts
+- **Model locking** — Prevents auto-switching when model is changed in the OpenCode GUI (`trinity lock`)
+- **Report & audit** — `report-save`, `report-list`, `report-read`, and `research-audit` tools
+- **Worker-to-Brain protocol** — Delegates implementation tasks to cheaper subagents, synthesizes results in-chat
+- **Web dashboard** — Real-time status, savings, stress gauge, and controls via browser
+- **TUI sidebar** — Plugin status and controls via OpenCode sidebar plugin
+- **Blackbox decision engine** — Dialogue trajectory tracking with loop prevention, pivot detection, and outcome tracking
 
 ## Install
 
 ### npm (Recommended)
 
-Published to npm as `vibeOS`:
-
 ```bash
 npm install vibeOS
 ```
 
-Then register in `~/.config/opencode/opencode.json`:
+Register in `~/.config/opencode/opencode.json`:
+
 ```json
 "plugins": [
   { "id": "vibeOS", "path": "node_modules/vibeOS/src/index.js" }
@@ -228,19 +48,9 @@ Then register in `~/.config/opencode/opencode.json`:
 
 ### Local Plugin File
 
-For OpenCode Desktop local plugin usage, copy these files to `~/.config/opencode/plugins/`:
-
-```
-cp src/index.js                    ~/.config/opencode/plugins/vibeOS.js
-cp src/vibeOS-lib/flow-enforcer.js ~/.config/opencode/plugins/vibeOS-lib/flow-enforcer.js
-cp src/vibeOS-lib/session-metrics.js ~/.config/opencode/plugins/vibeOS-lib/session-metrics.js
-cp src/vibeOS-lib/flow-rules.json  ~/.config/opencode/plugins/vibeOS-lib/flow-rules.json
-cp src/utils/cost-formatter.js     ~/.config/opencode/plugins/vibeOS-lib/cost-formatter.js
-cp src/utils/math.js               ~/.config/opencode/plugins/vibeOS-lib/math.js
-cp src/utils/timer.js              ~/.config/opencode/plugins/vibeOS-lib/timer.js
-```
+Copy the plugin and lib files to `~/.config/opencode/plugins/`. See the repository for the complete file list.
 
-Then register the plugin in `~/.config/opencode/opencode.json`:
+Register in `~/.config/opencode/opencode.json`:
 
 ```json
 "plugins": [
@@ -248,39 +58,79 @@ Then register the plugin in `~/.config/opencode/opencode.json`:
 ]
 ```
 
-Restart OpenCode Desktop. The plugin auto-creates `~/.claude/model-tiers.json` on first run.
+Restart OpenCode Desktop. The plugin auto-creates its configuration on first run.
+
+## trinity Commands
+
+| Command | Description |
+|---|---|
+| `trinity status` | Show current plugin state |
+| `trinity set brain\|medium\|cheap` | Switch model slot |
+| `trinity brain\|medium\|cheap` | Shorthand slot switch |
+| `trinity enable` / `trinity disable` | Toggle plugin on/off |
+| `trinity thinking full\|brief\|off` | Set reasoning depth |
+| `trinity enforce on\|off` | Toggle delegation enforcement |
+| `trinity lock on\|off` | Toggle model locking |
+| `trinity flow on\|off` | Toggle flow enforcer |
+| `trinity flow enforce on\|off` | Toggle auto TODO extraction |
+| `trinity tdd on\|off` | Toggle test skeleton gen |
+| `trinity tdd strict on\|off` | Toggle strict mode |
+| `trinity tdd quality on\|off` | Toggle quality mode |
+| `trinity blackbox on\|off\|status\|reset` | Decision engine controls |
+| `trinity project` | Per-project analytics |
+| `trinity patterns` / `trinity patterns clear` | Inspect / clear patterns |
+| `trinity guard` | Regenerate project guard files |
+| `trinity diagnose` | Run diagnostics |
+| `trinity rebuild` | Auto-detect available models |
+| `trinity help` | Command reference |
 
-## Web Dashboard
+## Footer Format
+
+Typical output footer:
+
+```
+— [model route] | VibeTheOG: <total> saved <arrow> —
+```
 
-Open `http://127.0.0.1:3333` in your browser after starting the server.
+The footer shows model split, cumulative savings, stress gauge, and trend arrow.
+
+## Web Dashboard
 
 ```bash
-npm run build:dashboard   # Build the SPA (one-time)
-npm run dashboard         # Start standalone server on :3333
-npm run dev:dashboard     # Vite dev server on :5173 with hot-reload
+npm run build:dashboard   # Build the SPA
+npm run dashboard         # Start server on http://127.0.0.1:3333
 ```
 
-Features: model split, savings, sessions, stress gauge, trinity controls, reports, blackbox state. SSE push updates every 1.5s.
+Displays model split, savings, session history, stress gauge, trinity controls, reports, and blackbox state with SSE push updates every 1.5s.
 
-## Build
+## Environment Variables
 
-- `npm run build`
-- `npm run build:dashboard` (build the web dashboard SPA)
+| Variable | Default | Description |
+|---|---|---|
+| `VIBEOS_API_URL` | `https://api.vibetheog.com` | API server URL |
+| `VIBEOS_API_TOKEN` | — | API token (required for remote mode) |
+| `VIBEOS_API_ENABLED` | `true` | Set to `false` for local-only mode |
+| `CLAUDE_CREDIT_PERCENT` | `100` | Credit percentage override |
+| `CLAUDE_CONTEXT7_AVAILABLE` | — | Enable context7 cost optimization |
+| `CLAUDE_SCRATCHPAD_MAX_AGE_SEC` | `86400` | Scratchpad cache lifetime |
+| `VIBEOS_MCP_PORT` | `3001` | MCP server port |
 
-`npm run build` compiles TypeScript source-of-truth modules and syncs generated JS artifacts used by runtime.
+Without an API token, the plugin runs in local-only mode with all algorithms bundled locally.
 
-## CI/CD
-
-GitHub Actions workflows are in `.github/workflows/`:
+## Runtime Model Slots
 
-- **CI** (`.github/workflows/ci.yml`): Runs on every push/PR to `main`/`master`. Executes typecheck, syntax check, test suite, TypeScript audit, and build validation.
+Tier configuration in `~/.claude/model-tiers.json`:
 
-- **Release** (`.github/workflows/release.yml`): Manual trigger via GitHub Actions UI (`workflow_dispatch`). Prompts for version bump type (patch/minor/major), then runs tests, builds, and executes `scripts/release.mjs --yes --ci` which bumps version, updates changelog, commits/tags/pushes, creates a GitHub Release, and publishes to npm.
+| Slot | Purpose |
+|---|---|
+| `brain` | High-tier model for orchestration |
+| `medium` | Mid-tier for moderate tasks |
+| `cheap` | Low-tier for delegation subagents |
 
-Before using the release workflow, add an `NPM_TOKEN` secret to the repository with an npm automation token that has publish permissions for the `vibeOS` package.
+Use `trinity set brain|medium|cheap` or `trinity rebuild` to configure.
 
 ## Known Limitations
 
-- OpenCode runtime behavior can vary by version for per-task model override handling.
-- Some legacy tests in this repo are older than current enforcement defaults and may fail due to changed policy semantics rather than runtime breakage.
-- Savings are estimates, not billing data.
+- OpenCode runtime behavior can vary by version.
+- Some test suite tests may fail due to policy semantic changes rather than actual breakage.
+- Savings displayed are estimates, not billing data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeostheog",
-  "version": "0.15.22",
+  "version": "0.15.34",
   "description": "Cost-aware delegation enforcer for OpenCode. Tracks model usage, routes Task subagents to cheaper tiers, surfaces cumulative savings in chat. Includes research audit, reporting framework, project memory, progressive scratchpad decadence, and trinity CLI for brain/medium/cheap slot switching.",
   "scripts": {
     "release": "node scripts/release.mjs",