vibeostheog 0.18.15 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +85 -128
  3. package/package.json +4 -5
  4. package/scripts/deploy.mjs +9 -5
  5. package/src/index.js +2163 -781
package/CHANGELOG.md CHANGED
@@ -1,3 +1,27 @@
1
+ ## 0.19.1
2
+ - fix: make README and runtime self-contained
3
+ - test: add 59 integration + e2e tests for cross-module behavior and user workflows
4
+ Merge pull request #49 from DrunkkToys/oc-desktop-live-savings-refresh
5
+ Merge pull request #48 from DrunkkToys/codex/live-savings-refresh
6
+ Invalidate savings cache on state writes
7
+
8
+
9
+ ## 0.19.0
10
+ - feat: quality governance — self-protection, 2h release gate, outcome tracking (#44)
11
+ - fix: chooseEpisodeMode defaults to budget (was always quality) + simplify isApiConnected check
12
+ - fix: stress mitigation directive uses raw stress score, not API-scaled
13
+ - fix: _refreshModel respects project-local opencode.json over bootstrap default slot
14
+ - docs: mark v0.19.0 as alpha milestone release
15
+ Merge pull request #47 from DrunkkToys/codex/status-lock-backend-fix
16
+ Expose status lock and backend state
17
+ Fix stress mitigation and TDD smoke coverage
18
+ Rebuild bundle after telemetry merge
19
+ Add privacy-preserving telemetry capture
20
+ Refresh public README
21
+ Extract runtime surface for easier maintenance
22
+ Fix budget-first mode and stabilize tests
23
+
24
+
1
25
  ## 0.18.15
2
26
  - fix: session records missing started/session_started_at fields (v0.18.12)
3
27
 
package/README.md CHANGED
@@ -1,175 +1,132 @@
1
1
  # vibeOS for OpenCode
2
2
 
3
- 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.
3
+ > **Alpha Release** — This is the first alpha milestone of vibeOS. See [CHANGELOG.md](CHANGELOG.md) for release notes.
4
+ vibeOS is the cost-aware routing layer for OpenCode Desktop. It keeps high-tier models focused on orchestration, pushes implementation work to cheaper tiers, and makes the savings visible in real time through the live footer and dashboard.
4
5
 
5
- 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.
6
6
 
7
- Beyond routing, vibeOS tracks savings from tier-switching, enforces delegation policies, and provides real-time visibility through a live status footer and web dashboard.
7
+ It also adds guardrails: delegation enforcement, flow and TDD controls, pattern learning, stress-aware routing, blackbox decision tracking, reporting, and remote API protection for the core algorithms.
8
8
 
9
- ## Savings Categories
9
+ ## Why Teams Use It
10
10
 
11
- - **Delegation savings** — Estimated cost avoided by routing tasks to cheaper models.
12
- - **Cache savings** — Cost avoided from scratchpad cache hits.
13
-
14
- Both are summed in the live footer and persisted in \`~/.claude/delegation-state.json\` across sessions.
15
-
16
- ## What It Does
17
-
18
- - **Smart delegation** — Blocks direct write/edit on high-tier models and routes work to cheaper subagents
19
- - **Cost tracking** — Tracks estimated savings from delegation events and cache hits, displayed in a live footer
20
- - **trinity commands** — Runtime controls for model switching, enforcement toggles, audits, and diagnostics
21
- - **Flow enforcer** — Validates write/edit patterns against project rules; optionally extracts TODOs/FIXMEs
22
- - **TDD enforcer** — Auto-creates test skeletons for changed source files; strict mode makes TODO tests fail loudly
23
- - **Project guard** — Protects AGENTS.md and README.md in every project with auto-regeneration
24
- - **Pattern learner** — Detects recurring friction and routine patterns per project, surfaces via `trinity patterns`
25
- - **Stress mitigation** — Detects user stress signals, adjusts tier routing, and injects protective prompts
26
- - **Model locking** — Prevents auto-switching when model is changed in the OpenCode GUI (`trinity lock`)
27
- - **Report & audit** — `report-save`, `report-list`, `report-read`, and `research-audit` tools
28
- - **Worker-to-Brain protocol** — Delegates implementation tasks to cheaper subagents, synthesizes results in-chat
29
- - **Web dashboard** — Real-time status, savings, stress gauge, and controls via browser
30
- - **TUI sidebar** — Plugin status and controls via OpenCode sidebar plugin
31
- - **Blackbox decision engine** — Dialogue trajectory tracking with loop prevention, pivot detection, and outcome tracking
11
+ - Routes work to the right model tier without manual babysitting
12
+ - Tracks delegation savings and cache savings separately
13
+ - Shows live status in chat, the footer, and the web dashboard
14
+ - Adds runtime controls for flow, TDD, model locking, and blackbox mode
15
+ - Falls back to local algorithms if the remote API is unavailable
32
16
 
33
17
  ## Install
34
18
 
35
- ### npm (Recommended)
19
+ ### OpenCode plugin
20
+
21
+ 1. Install the package:
36
22
 
37
23
  ```bash
38
- npm install vibeOS
24
+ npm install vibeostheog
39
25
  ```
40
26
 
41
- Register in `~/.config/opencode/opencode.json`:
27
+ 2. Register it in `~/.config/opencode/opencode.json`:
42
28
 
43
29
  ```json
44
- "plugins": [
45
- { "id": "vibeOS", "path": "node_modules/vibeOS/src/index.js" }
46
- ]
30
+ {
31
+ "plugins": [
32
+ { "id": "vibeOS", "path": "node_modules/vibeostheog/src/index.js" }
33
+ ]
34
+ }
47
35
  ```
48
36
 
49
- ### Local Plugin File
50
-
51
- Copy the plugin and lib files to `~/.config/opencode/plugins/`. See the repository for the complete file list.
37
+ ### Local plugin file
52
38
 
53
- Register in `~/.config/opencode/opencode.json`:
39
+ If you keep a local checkout of the plugin, point OpenCode at the built file instead:
54
40
 
55
41
  ```json
56
- "plugins": [
57
- { "id": "vibeOS", "path": "~/.config/opencode/plugins/vibeOS.js" }
58
- ]
59
- ```
60
-
61
- Restart OpenCode Desktop. The plugin auto-creates its configuration on first run.
62
-
63
- ## trinity Commands
64
-
65
- | Command | Description |
66
- |---|---|
67
- | `trinity status` | Show current plugin state |
68
- | `trinity set brain\|medium\|cheap` | Switch model slot |
69
- | `trinity brain\|medium\|cheap` | Shorthand slot switch |
70
- | `trinity enable` / `trinity disable` | Toggle plugin on/off |
71
- | `trinity thinking full\|brief\|off` | Set reasoning depth |
72
- | `trinity enforce on\|off` | Toggle delegation enforcement |
73
- | `trinity lock on\|off` | Toggle model locking |
74
- | `trinity flow on\|off` | Toggle flow enforcer |
75
- | `trinity flow enforce on\|off` | Toggle auto TODO extraction |
76
- | `trinity tdd on\|off` | Toggle test skeleton gen |
77
- | `trinity tdd strict on\|off` | Toggle strict mode |
78
- | `trinity tdd quality on\|off` | Toggle quality mode |
79
- | `trinity blackbox on\|off\|status\|reset` | Decision engine controls |
80
- | `trinity project` | Per-project analytics |
81
- | `trinity patterns` / `trinity patterns clear` | Inspect / clear patterns |
82
- | `trinity guard` | Regenerate project guard files |
83
- | `trinity diagnose` | Run diagnostics |
84
- | `trinity rebuild` | Auto-detect available models |
85
- | `trinity help` | Command reference |
86
-
87
- ## Footer Format
88
-
89
- Typical output footer:
90
-
91
- ```
92
- — [model route] | VibeTheOG: <total> saved <arrow> —
42
+ {
43
+ "plugins": [
44
+ { "id": "vibeOS", "path": "/absolute/path/to/theSaver-oc/src/index.js" }
45
+ ]
46
+ }
93
47
  ```
94
48
 
95
- The footer shows model split, cumulative savings, stress gauge, and trend arrow.
49
+ Restart OpenCode Desktop after changing the config.
96
50
 
97
- ## Web Dashboard
51
+ ## Common Npm Commands
98
52
 
99
53
  ```bash
100
- npm run build:dashboard # Build the SPA
101
- npm run dashboard # Start server on http://127.0.0.1:3333
54
+ npm install
55
+ npm run build
56
+ npm run typecheck
57
+ npm test
58
+ npm run release:patch
102
59
  ```
103
60
 
104
- Displays model split, savings, session history, stress gauge, trinity controls, reports, and blackbox state with SSE push updates every 1.5s.
61
+ `npm run build` compiles `src/index.ts` to `src/index.js` and deploys the built plugin into the OpenCode plugin directory. `npm run typecheck` validates the TypeScript sources without emitting files.
105
62
 
106
- ## Security
63
+ ## Core Controls
107
64
 
108
- The API token (`VIBEOS_API_TOKEN`) acts as a **password** for your vibeOS seat. Treat it with the same care as any credential.
65
+ Use `trinity help` for the full command list. The most common controls are:
109
66
 
110
- - **Token-based seat auth** — Each token is bound to a seat. Suspending a seat immediately revokes all associated tokens.
111
- - **Graceful degradation** — If the token is revoked or the API is unreachable, the plugin falls back to local-only mode with bundled algorithms. No functionality is lost; only remote-optimized routing is disabled.
112
- - **Never commit tokens** — `.env.production` and `PRODUCTION-CREDENTIALS.md` are gitignored. Do not share or hardcode tokens in source files.
113
- - **Token rotation** — Generate a new token and update `VIBEOS_API_TOKEN` if you suspect a leak. Old tokens are invalidated immediately on seat suspension.
114
- - **Local-only mode** — Without an API token, all algorithms run locally. Set `VIBEOS_API_ENABLED=false` to explicitly disable all remote calls.
67
+ - `trinity status` - show current tier, enforcement, savings, stress, and lock state
68
+ - `trinity set brain|medium|cheap` - switch the active tier
69
+ - `trinity brain|medium|cheap` - shorthand tier switch
70
+ - `trinity rebuild` - re-detect available models and repopulate slots
71
+ - `trinity enable` / `trinity disable` - toggle the plugin on or off
72
+ - `trinity mode budget|quality|speed|longrun|auto` - change the optimization mode
73
+ - `trinity thinking full|brief|off` - change reasoning depth
74
+ - `trinity enforce on|off` - control delegation enforcement
75
+ - `trinity lock on|off` - freeze the active model for the session
76
+ - `trinity flow on|off` and `trinity flow enforce on|off` - manage flow checks
77
+ - `trinity tdd on|off`, `trinity tdd strict on|off`, `trinity tdd quality on|off` - manage test skeleton behavior
78
+ - `trinity project` - open project analytics
79
+ - `trinity patterns` / `trinity patterns clear` - inspect or reset learned patterns
80
+ - `trinity diagnose` - run a health check
81
+ - `trinity repair-state preview|apply` - fix state fingerprint collisions
82
+ - `trinity blackbox on|off|status|reset` - control the decision engine
83
+ - `trinity guard` - refresh AGENTS.md and README.md checks
84
+ - `trinity api-token <token>` - update the remote API token
115
85
 
116
- ## Context7 Cost Optimization
86
+ Additional reporting commands:
117
87
 
118
- [context7](https://upstash.com/docs/context7) is an MCP tool that resolves library/framework documentation queries at a fraction of the cost of WebFetch (~$0.06/turn saved).
88
+ - `report-save`
89
+ - `report-list`
90
+ - `report-read`
91
+ - `research-audit`
119
92
 
120
- **Install it once:**
93
+ ## Savings And Footer
121
94
 
122
- ```bash
123
- claude mcp add context7 npx @upstash/context7-mcp
124
- ```
125
-
126
- ### How vibeOS uses context7
95
+ The footer shows:
127
96
 
128
- - **Auto-detection** — At module load, vibeOS scans `~/.claude/settings.json`, `~/.claude.json`, `opencode.json`, and `~/.config/opencode/` for a `context7` reference. No manual config needed.
129
- - **System prompt injection** — When context7 is detected, a cost-policy directive is injected into every system prompt instructing the model to prefer `mcp__context7__resolve-library-id` and `mcp__context7__get-library-docs` over WebFetch/WebSearch for documentation URLs.
130
- - **Urgency levels** — Controlled by the blackbox engine:
131
- - `required` (strict/TDD-strict mode) — context7 is mandatory this turn.
132
- - `preferred` (default) — context7 is encouraged but not forced.
133
- - `optional` (relaxed mode) — context7 is a nice-to-have.
134
- - **Docs nudge** — If context7 is not installed and the model uses WebFetch on a documentation URL (docs.*, readthedocs, MDN, npmjs, pypi, crates.io, pkg.go.dev, etc.), vibeOS logs a one-time install suggestion and tracks the missed savings.
135
- - **Savings tracking** — Every docs URL fetched via WebFetch instead of context7 is recorded as `missed_context7_usd` in `~/.claude/delegation-state.json`. Accumulated misses appear in `trinity project` analytics with an installation suggestion when bypasses exceed 3.
97
+ - the active model split
98
+ - cumulative delegation savings
99
+ - cache savings
100
+ - stress level
101
+ - lock and enforcement tags
136
102
 
137
- ### Force-enable detection
103
+ Savings are persisted in `~/.claude/delegation-state.json`.
138
104
 
139
- ```bash
140
- export CLAUDE_CONTEXT7_AVAILABLE=true
141
- ```
105
+ ## Configuration
142
106
 
143
- Use this when context7 is configured but the auto-scan misses it (unusual paths, remote configs, or runtime-loaded MCP definitions).
144
-
145
- ## Environment Variables
146
-
147
- | Variable | Default | Description |
107
+ | Variable | Default | Purpose |
148
108
  |---|---|---|
149
- | `VIBEOS_API_URL` | `https://api.vibetheog.com` | API server URL |
150
- | `VIBEOS_API_TOKEN` | — | **API token (password). Protect like a credential.** Required for remote mode. If compromised, rotate immediately via seat suspension. |
109
+ | `VIBEOS_API_URL` | `https://api.vibetheog.com` | Remote API server URL |
110
+ | `VIBEOS_API_TOKEN` | none | Token for remote mode |
151
111
  | `VIBEOS_API_ENABLED` | `true` | Set to `false` for local-only mode |
152
- | `CLAUDE_CREDIT_PERCENT` | `100` | Credit percentage override |
153
- | `CLAUDE_CONTEXT7_AVAILABLE` | — | Enable context7 cost optimization |
112
+ | `CLAUDE_CREDIT_PERCENT` | `100` | Credit override |
113
+ | `CLAUDE_CONTEXT7_AVAILABLE` | unset | Enables context7 optimization |
154
114
  | `CLAUDE_SCRATCHPAD_MAX_AGE_SEC` | `86400` | Scratchpad cache lifetime |
155
115
  | `VIBEOS_MCP_PORT` | `3001` | MCP server port |
156
116
 
157
- Without an API token, the plugin runs in local-only mode with all algorithms bundled locally.
158
-
159
- ## Runtime Model Slots
160
-
161
- Tier configuration in `~/.claude/model-tiers.json`:
117
+ Without a token, vibeOS keeps running in local-only mode with bundled algorithms.
162
118
 
163
- | Slot | Purpose |
164
- |---|---|
165
- | `brain` | High-tier model for orchestration |
166
- | `medium` | Mid-tier for moderate tasks |
167
- | `cheap` | Low-tier for delegation subagents |
119
+ ## Troubleshooting
168
120
 
169
- Use `trinity set brain|medium|cheap` or `trinity rebuild` to configure.
121
+ - If the plugin does not appear, confirm the OpenCode config entry, then restart OpenCode Desktop.
122
+ - If the model will not switch, run `trinity rebuild` and then `trinity set brain|medium|cheap`.
123
+ - If writes or edits are blocked, that is usually delegation enforcement working as intended on the brain tier.
124
+ - If the footer is missing, check that the plugin is enabled and that the current OpenCode session is receiving assistant completions.
125
+ - If the remote API is down or the token is invalid, use `trinity api-token <token>` or rely on local-only mode.
126
+ - If the dashboard does not load, rebuild the plugin with `npm run build` and restart OpenCode.
127
+ - If state or config looks inconsistent, run `trinity diagnose` and `trinity guard`.
170
128
 
171
- ## Known Limitations
129
+ ## Notes
172
130
 
173
- - OpenCode runtime behavior can vary by version.
174
- - Some test suite tests may fail due to policy semantic changes rather than actual breakage.
175
- - Savings displayed are estimates, not billing data.
131
+ - `trinity help` is the canonical command reference.
132
+ - The README stays intentionally high level so the command details can follow the code without a rewrite.
package/package.json CHANGED
@@ -1,19 +1,19 @@
1
1
  {
2
2
  "name": "vibeostheog",
3
- "version": "0.18.15",
3
+ "version": "0.19.1",
4
4
  "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.",
5
5
  "scripts": {
6
6
  "release": "node scripts/release.mjs",
7
7
  "release:patch": "node scripts/release.mjs patch --yes",
8
8
  "release:minor": "node scripts/release.mjs minor --yes",
9
9
  "release:major": "node scripts/release.mjs major --yes",
10
- "build": "tsc -p tsconfig.json --noEmit && npx esbuild src/index.ts --bundle --outfile=src/index.js --platform=node --format=esm --target=node22 --external:node:* --external:vibeOScore && node scripts/deploy.mjs",
10
+ "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",
11
11
  "deploy": "node scripts/deploy.mjs",
12
12
  "typecheck": "tsc -p tsconfig.json --noEmit",
13
13
  "checkpoint:validate": "node scripts/checkpoint-validate.mjs",
14
14
  "test:scripts": "node --test scripts/tests/checkpoint-validate.test.mjs",
15
15
  "ts:audit": "node scripts/ts-audit.mjs",
16
- "test": "VIBEOS_MCP_PORT=0 node --test --test-timeout=120000 tests/deep_integration.test.mjs tests/production_regressions.test.mjs tests/release_hardening_tigerteam.test.mjs tests/test_api_migration.neutral.test.mjs tests/test_const_assignment_regression.test.mjs tests/test_delegation_enforcer.test.mjs tests/test_diagnose_cmd.test.mjs tests/test_install_and_recovery.test.mjs tests/test_internals_stress_patterns_offtopic.test.mjs tests/test_saveos_e2e_cleanup.test.mjs tests/test_tdd_enforcer.test.mjs src/tests/*.test.js src/utils/tests/*.test.mjs \"src/vibeOS-lib/tests/!(test_blackbox*).test.mjs\"",
16
+ "test": "VIBEOS_MCP_PORT=0 node --test --test-timeout=240000 tests/deep_integration.test.mjs tests/production_regressions.test.mjs tests/release_hardening_tigerteam.test.mjs tests/test_api_migration.neutral.test.mjs tests/test_const_assignment_regression.test.mjs tests/test_delegation_enforcer.test.mjs tests/test_diagnose_cmd.test.mjs tests/test_install_and_recovery.test.mjs tests/test_internals_stress_patterns_offtopic.test.mjs tests/test_saveos_e2e_cleanup.test.mjs tests/test_tdd_enforcer.test.mjs src/tests/*.test.js src/utils/tests/*.test.mjs \"src/vibeOS-lib/tests/!(test_blackbox*).test.mjs\"",
17
17
  "test:ci": "VIBEOS_MCP_PORT=0 node --test --test-timeout=30000 tests/production_regressions.test.mjs tests/release_hardening_tigerteam.test.mjs tests/test_const_assignment_regression.test.mjs tests/test_diagnose_cmd.test.mjs tests/test_install_and_recovery.test.mjs tests/test_saveos_e2e_cleanup.test.mjs tests/test_tdd_enforcer.test.mjs src/tests/*.test.js src/utils/tests/*.test.mjs \"src/vibeOS-lib/tests/!(test_blackbox*).test.mjs\"",
18
18
  "codex:guard": "bash plugins/vibetheog-codex/scripts/run-guard.sh",
19
19
  "codex:guard:full": "VIBETHEOG_GUARD_FULL=1 bash plugins/vibetheog-codex/scripts/run-guard.sh",
@@ -66,8 +66,7 @@
66
66
  "@types/node": "^22.15.30",
67
67
  "esbuild": "^0.28.0",
68
68
  "express": "^5.2.1",
69
- "typescript": "^5.9.3",
70
- "vibeOScore": "file:../vibeOScore"
69
+ "typescript": "^5.9.3"
71
70
  },
72
71
  "dependencies": {}
73
72
  }
package/scripts/deploy.mjs CHANGED
@@ -70,11 +70,15 @@ try {
70
70
 
71
71
  const envSrc = join(ROOT, ".env.production")
72
72
  if (existsSync(envSrc)) {
73
- const envDest = join(pluginDir, ".env.production")
74
- if (!existsSync(envDest)) {
75
- writeFileSync(envDest, readFileSync(envSrc))
76
- process.stderr.write(`[vibeOS deploy] Copied .env.production to plugin dir\n`)
77
- }
73
+ const envContent = readFileSync(envSrc)
74
+ const pluginEnvDest = join(pluginDir, ".env.production")
75
+ const homeEnvDir = join(homedir(), ".claude")
76
+ const homeEnvDest = join(homeEnvDir, ".env.production")
77
+
78
+ mkdirSync(homeEnvDir, { recursive: true })
79
+ writeFileSync(pluginEnvDest, envContent)
80
+ writeFileSync(homeEnvDest, envContent)
81
+ process.stderr.write(`[vibeOS deploy] Synced .env.production to plugin dir and ~/.claude\n`)
78
82
  }
79
83
 
80
84
  // ── Install nightly pricing sync cron if not already present ──