vibeostheog 0.13.22

package/README.md

@@ -0,0 +1,286 @@
+# vibeOS for OpenCode
+
+Cost-aware delegation and policy plugin for OpenCode Desktop.
+
+vibeOS helps keep expensive model usage under control by enforcing delegation behavior, tracking savings, and exposing runtime controls through the `trinity` tool.
+
+## Version
+
+Current package version: `0.11.0`
+
+## 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 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.
+
+## 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.
+
+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)
+
+## Install
+
+### npm (Recommended)
+
+Published to npm as `vibeOS`:
+
+```bash
+npm install vibeOS
+```
+
+Then register in `~/.config/opencode/opencode.json`:
+```json
+"plugins": [
+  { "id": "vibeOS", "path": "node_modules/vibeOS/src/index.js" }
+]
+```
+
+### 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
+```
+
+Then register the plugin in `~/.config/opencode/opencode.json`:
+
+```json
+"plugins": [
+  { "id": "vibeOS", "path": "~/.config/opencode/plugins/vibeOS.js" }
+]
+```
+
+Restart OpenCode Desktop. The plugin auto-creates `~/.claude/model-tiers.json` on first run.
+
+## Web Dashboard
+
+Open `http://127.0.0.1:3333` in your browser after starting the server.
+
+```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
+```
+
+Features: model split, savings, sessions, stress gauge, trinity controls, reports, blackbox state. SSE push updates every 1.5s.
+
+## Build
+
+- `npm run build`
+- `npm run build:dashboard` (build the web dashboard SPA)
+
+`npm run build` compiles TypeScript source-of-truth modules and syncs generated JS artifacts used by runtime.
+
+## CI/CD
+
+GitHub Actions workflows are in `.github/workflows/`:
+
+- **CI** (`.github/workflows/ci.yml`): Runs on every push/PR to `main`/`master`. Executes typecheck, syntax check, test suite, TypeScript audit, and build validation.
+
+- **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.
+
+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.
+
+## 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.

package/model-tiers.sample.json

@@ -0,0 +1,69 @@
+{
+  "$schema_version": 1,
+  "_comment": "Single source of truth for VibeTheOG model classification. Both the bash hook and JS plugin load this file. Tier IDs (high/mid/budget) are stable — display labels are user-facing.",
+  "trinity": {
+    "_comment": "Per-slot models for both runtimes. `oc` writes to the OpenCode config. `cc` writes to the CC config. Adjust to match your available models.",
+    "brain": {
+      "oc": "provider/high-tier-model",
+      "cc": "brain"
+    },
+    "medium": {
+      "oc": "provider/mid-tier-model",
+      "cc": "medium"
+    },
+    "cheap": {
+      "oc": "provider/budget-tier-model",
+      "cc": "budget"
+    }
+  },
+  "selection": {
+    "_comment": "Used by `trinity auto`: pick `brain` slot when credit ≥ threshold, else `fallback` slot. Dropping to mid slot at low credit is more reliable than burning what's left on flaky brain calls. `enabled` toggles all VibeTheOG logic. `active_slot` records the last slot set by `trinity`.",
+    "credit_threshold_percent": 30,
+    "brain": "brain",
+    "fallback": "medium",
+    "enabled": true,
+    "active_slot": "brain",
+    "delegation_enforce": true,
+    "tdd_strict": true
+  },
+  "tiers": {
+    "high": {
+      "label": "brain",
+      "icon": "🧠",
+      "regex": "opus|gemini-.*-pro|deepseek.*v4.*pro|deepseek.*r1|gpt-5|mistral.*large|qwen.*max|grok-3|command.*r.*plus|(^|[^a-z])o[134]($|[^a-z])",
+      "behavior": "warn on Edit/Write/Bash with savings estimate; ledger; context7 nudge; scratchpad observe"
+    },
+    "mid": {
+      "label": "medium",
+      "icon": "⚙",
+      "regex": "claude.*sonnet|sonnet|deepseek.*v4.*flash|deepseek.*v[23]|deepseek.*coder|gemini-.*-flash|gpt-4o(?!-mini)|gpt-4(?!o)|llama|mixtral|mistral(?!.*large)|qwen.*plus|grok-2|command.*r(?!.*plus)|o[134]-mini",
+      "behavior": "silent; ledger only"
+    },
+    "budget": {
+      "label": "cheap",
+      "icon": "⚡",
+      "regex": ".*",
+      "behavior": "fully silent; pass-through"
+    }
+  },
+  "pricing": {
+    "high": {
+      "input": 15.00,
+      "output": 75.00,
+      "cache_read": 1.50,
+      "cache_write": 18.75
+    },
+    "mid": {
+      "input": 3.00,
+      "output": 15.00,
+      "cache_read": 0.30,
+      "cache_write": 3.75
+    },
+    "budget": {
+      "input": 0.80,
+      "output": 4.00,
+      "cache_read": 0.08,
+      "cache_write": 1.00
+    }
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "vibeostheog",
+  "version": "0.13.22",
+  "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",
+    "release:patch": "node scripts/release.mjs patch --yes",
+    "release:minor": "node scripts/release.mjs minor --yes",
+    "release:major": "node scripts/release.mjs major --yes",
+    "build": "tsc -p tsconfig.json --noEmit && npx esbuild src/index.ts --bundle --outfile=src/index.js --platform=node --format=esm --target=node22 --external:node:* && node scripts/deploy.mjs",
+    "deploy": "node scripts/deploy.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "checkpoint:validate": "node scripts/checkpoint-validate.mjs",
+    "test:scripts": "node --test scripts/tests/checkpoint-validate.test.mjs",
+    "ts:audit": "node scripts/ts-audit.mjs",
+    "test": "VIBEOS_MCP_PORT=0 node --test tests/*.test.mjs src/tests/*.test.js src/utils/tests/*.test.mjs src/vibeOS-lib/tests/*.test.mjs",
+    "codex:guard": "bash plugins/vibetheog-codex/scripts/run-guard.sh",
+    "codex:guard:full": "VIBETHEOG_GUARD_FULL=1 bash plugins/vibetheog-codex/scripts/run-guard.sh",
+    "codex:hook:precommit": "bash plugins/vibetheog-codex/hooks/pre-commit.sh",
+    "codex:hook:summary": "bash plugins/vibetheog-codex/hooks/post-command-summary.sh",
+    "precommit": "node scripts/pre-commit.mjs",
+    "audit-state": "node scripts/audit-state.mjs",
+    "migrate-ledger": "node scripts/migrate-ledger.mjs",
+    "build:dashboard": "cd src/dashboard && npm install && npm run build",
+    "dev:dashboard": "cd src/dashboard && npm run dev",
+    "dashboard": "node scripts/dashboard-server.mjs",
+    "test:e2e": "node --test tests/dashboard-buttons.e2e.test.mjs",
+    "test:dashboard": "node --test tests/test_dashboard.test.mjs"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "cost",
+    "delegation",
+    "model-routing",
+    "trinity"
+  ],
+  "author": "vibeOS",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "files": [
+    "src/index.js",
+    "model-tiers.sample.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DrunkkToys/vibeOS.git"
+  },
+  "homepage": "https://github.com/DrunkkToys/vibeOS#readme",
+  "bugs": {
+    "url": "https://github.com/DrunkkToys/vibeOS/issues"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.15.30",
+    "esbuild": "^0.28.0",
+    "express": "^5.2.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "solid-js": "^1.9.13"
+  }
+}