@thelioo/opencode-balancer 0.1.8 → 0.2.1

package/INSTALL.txt

@@ -1,17 +1,18 @@
 opencode-balancer installation guide for AI agents
 
 Goal
-Install @thelioo/opencode-balancer as an opencode npm plugin without removing or rewriting the user's existing opencode configuration.
+Install @thelioo/opencode-balancer as both an opencode server plugin and an opencode TUI plugin without removing or rewriting the user's existing opencode configuration.
 
 What this plugin does
-opencode-balancer lets opencode users save multiple authenticated accounts per provider, switch active accounts from the Balancer TUI sidebar/dashboard, and automatically retry with another saved account when the active account is rate-limited.
+opencode-balancer lets opencode users save multiple authenticated accounts per provider, manage them from a TUI dashboard, choose provider/model priority, and automatically retry with another healthy account when the active account is rate-limited.
 
 Important rules
-- Do not run npm install for this plugin. opencode installs npm plugins automatically with Bun at startup.
-- Preserve existing opencode config, plugins, comments, formatting, providers, agents, MCP servers, and permissions whenever possible.
+- Do not run npm install, bun install, or other package install commands for this plugin during user setup. opencode installs npm plugins automatically with Bun at startup.
+- Preserve existing opencode config, TUI config, plugins, comments, formatting, providers, agents, MCP servers, and permissions whenever possible.
 - Use the singular key "plugin", not "plugins".
 - Add the plugin only if it is not already present.
-- Prefer @thelioo/opencode-balancer@latest for user installs.
+- Prefer @thelioo/opencode-balancer (without @latest) for user installs.
+- Keep config changes minimal and do not remove unrelated user settings.
 
 Steps
 1. Locate the user's opencode config.
@@ -25,43 +26,70 @@ Steps
    - If the config is JSONC, keep JSONC syntax valid.
    - If the config is JSON, keep JSON syntax valid.
 
-3. Add this plugin entry:
-   @thelioo/opencode-balancer@latest
+3. Add this plugin entry to the opencode config plugin array:
+   @thelioo/opencode-balancer
 
-4. Save the config.
+4. Locate the user's opencode TUI config.
+   - Prefer ~/.config/opencode/tui.jsonc if it exists.
+   - Otherwise use ~/.config/opencode/tui.json if it exists.
+   - If neither exists, create ~/.config/opencode/tui.json with a minimal JSON object.
 
-5. Show the user the final plugin array.
+5. Ensure the TUI config has a top-level plugin array.
+   - If plugin already exists and is an array, keep all existing entries.
+   - If plugin is missing, create it.
+   - If the config is JSONC, keep JSONC syntax valid.
+   - If the config is JSON, keep JSON syntax valid.
+
+6. Add this plugin entry to the TUI config plugin array:
+   @thelioo/opencode-balancer
+
+7. Save both configs.
 
-6. Tell the user to restart opencode.
+8. Show the user both final plugin arrays.
+
+9. Tell the user to restart opencode.
 
 Expected config shape
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@thelioo/opencode-balancer@latest"]
+  "plugin": ["@thelioo/opencode-balancer"]
+}
+
+Expected TUI config shape
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@thelioo/opencode-balancer"]
 }
 
 After restart
-1. Tell the user to run opencode's native connect flow:
-   /connect <provider>
+1. Tell the user to open the Balancer dashboard using one of these options:
+   - Press Ctrl+B.
+   - Run /balancer.
+   - Open "Open Balancer Dashboard" from the opencode command palette.
+   - Use the Balancer button in the sidebar if visible.
+
+2. Tell the user to choose "New account" in the dashboard, or press C, to start opencode's native provider connection flow.
 
-2. Tell the user to use the Balancer TUI modal/sidebar to save the detected pending connection with an alias.
+3. Tell the user to complete the provider connection in opencode. The plugin detects the changed provider credentials and saves them from the TUI workflow automatically. If the credentials match an existing saved account, the saved account is refreshed instead of duplicated.
 
-3. If the Balancer dashboard is not visible, tell the user to open it from the opencode command palette.
+4. Tell the user to open the priority matrix from the dashboard header, or press P, to configure automatic balancing:
+   - Press B to turn automatic balancing on or off.
+   - Press Enter on a provider to choose its model.
+   - Use Shift+Up and Shift+Down to reorder provider priority.
+   - Press Space to enable or disable a provider.
 
-4. Remind the user to restart opencode after any later config changes.
+5. Remind the user to restart opencode after any later config changes.
 
 Security note
 The plugin stores saved provider credentials locally in balancer.sqlite under the opencode config directory, usually ~/.config/opencode/balancer.sqlite or OPENCODE_CONFIG_DIR/balancer.sqlite. Keep this file private and never commit, paste, or share it.
 
-Fallback commands
-/balancer commands are compatibility and troubleshooting fallbacks. Alias creation is handled by the TUI pending-connection flow.
-/balancer help
-/balancer list
-/balancer status
-/balancer use <provider> <alias>
-/balancer active <provider>
+TUI-only workflow
+/balancer opens the Balancer dashboard in the TUI. Account management, provider/model priority, supported usage snapshots, and balancing settings are handled from the TUI only.
 
 Verification
-- Confirm the opencode config contains @thelioo/opencode-balancer@latest in the plugin array.
+- Confirm the opencode config contains @thelioo/opencode-balancer in the plugin array.
+- Confirm the opencode TUI config contains @thelioo/opencode-balancer in the plugin array.
 - Confirm no existing plugin entries were removed.
-- Remind the user that opencode must be restarted before the plugin UI and fallback commands become available.
+- Confirm the user restarted opencode after the config change.
+- Confirm the Balancer dashboard opens with Ctrl+B, /balancer, or the command palette.
+- Confirm at least one account can be connected from the dashboard before helping configure balancing.

package/README.md

@@ -2,32 +2,33 @@
 
 # opencode-balancer
 
-_Use multiple accounts per opencode provider and switch automatically when one hits a rate limit._
+_Use multiple accounts and provider/model priorities in opencode, then fail over automatically when one account hits a limit._
 
 [![npm version](https://img.shields.io/npm/v/@thelioo/opencode-balancer?style=flat-square)](https://www.npmjs.com/package/@thelioo/opencode-balancer)
 [![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![opencode plugin](https://img.shields.io/badge/opencode-plugin-111?style=flat-square)](https://opencode.ai/docs/plugins)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
 
-[Features](#features) | [Installation](#installation) | [Usage](#usage) | [Fallback Commands](#fallback-commands) | [Troubleshooting](#troubleshooting)
+[Features](#features) | [Installation](#installation) | [Usage](#usage) | [Troubleshooting](#troubleshooting)
 
 </div>
 
-`opencode-balancer` is an [opencode](https://opencode.ai/) plugin that lets you save multiple authenticated accounts for the same provider, give each one a friendly alias, and keep working when the active account becomes rate-limited.
+`opencode-balancer` is an [opencode](https://opencode.ai/) server and TUI plugin that lets you keep several authenticated accounts, choose which provider/model should be used first, and keep working when the current account becomes rate-limited.
 
-It works with opencode's existing auth flow: connect a provider, save the detected credentials from the Balancer TUI, then let the plugin inject the active account credentials into future model requests.
+It integrates with opencode's native provider connection flow. Use the plugin dashboard to connect accounts, inspect usage, switch active accounts, configure provider priority, and enable or disable automatic balancing.
 
 > [!NOTE]
 > This plugin manages credentials already configured through opencode. It does not create accounts, bypass provider limits, or modify provider-side quotas.
 
 ## Features
 
-- **Multiple accounts per provider**: Save aliases like `work`, `personal`, or `backup` for the same provider.
-- **Automatic failover**: Switches to another saved account on retryable rate-limit/server responses.
-- **TUI-first account management**: Save aliases, switch accounts, and inspect pending connections from the Balancer sidebar/dashboard.
-- **OAuth-friendly setup**: Uses opencode's native `/connect` flow, then prompts you to save the detected credentials in the TUI.
-- **Agent tool support**: Exposes a `balancer_command` tool so opencode agents can manage accounts when asked.
-- **Local credential store**: Saves account credentials and status data under your opencode config directory.
+- **Multiple accounts per provider**: Save and activate separate accounts for the same provider.
+- **Automatic failover**: Retries with another healthy account after retryable responses such as `429`, `500`, `502`, `503`, `504`, or `529`.
+- **Provider priority matrix**: Choose one model per provider, reorder failover priority, and disable providers from the balancer.
+- **TUI dashboard**: Open a control center from the command palette, `/balancer`, `Ctrl+B`, or the sidebar.
+- **Native connect flow**: Start opencode's provider connection from the dashboard and save the detected account automatically.
+- **Usage snapshots**: Shows per-account usage when the provider exposes supported usage data.
+- **Local credential store**: Saves accounts, usage snapshots, events, and priority settings under your opencode config directory.
 
 ## Installation
 
@@ -44,68 +45,94 @@ Or read the local guide: [INSTALL.txt](INSTALL.txt).
 
 ### Option B: Manual Setup
 
-Add the plugin to your opencode config:
+Add the plugin to your opencode config so the server hooks can run:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@thelioo/opencode-balancer@latest"]
+  "plugin": ["@thelioo/opencode-balancer"]
 }
 ```
 
-Then restart opencode.
+Then add the same plugin to your opencode TUI config so the dashboard can load:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@thelioo/opencode-balancer"]
+}
+```
+
+Use the package name without an explicit `@latest` tag so opencode can refresh to newer published versions on restart.
+
+Then restart opencode. The same package provides both the server hooks and the TUI dashboard.
 
 > [!TIP]
-> No manual `npm install` is required. opencode automatically installs npm plugins with Bun at startup and caches them locally.
+> No manual `npm install` is required. opencode installs npm plugins automatically with Bun at startup and caches them locally.
 
 ## Usage
 
-### Save Your First Account
+### Open The Dashboard
 
-Connect a provider with opencode's native flow:
+Open the Balancer dashboard with any of these entry points:
 
-```text
-/connect anthropic
-```
+- Press `Ctrl+B`.
+- Run `/balancer` from opencode to open the dashboard.
+- Open **Open Balancer Dashboard** from the command palette.
+- Click the Balancer dashboard button in the sidebar.
 
-After the connection is detected, use the Balancer TUI modal or sidebar to save it with an alias such as `work`.
+The dashboard is the primary workflow for account management. It works on compact and full terminal layouts.
 
-### Add Another Account
+### Connect An Account
 
-Connect the same provider with a different account, then save the new pending connection from the Balancer TUI:
+In the dashboard, choose **New account** or press `C`. The plugin opens opencode's native provider connection flow.
 
-```text
-/connect anthropic
-```
+After the provider auth changes, `opencode-balancer` detects the new credentials and saves them as an account. If the credentials match an existing saved account, the saved account is refreshed instead of duplicated.
 
 ### Manage Accounts
 
-Use the Balancer sidebar or dashboard to switch accounts, view usage, and review pending connections. If the dashboard is not visible, open it from opencode's command palette.
+Use the dashboard and sidebar to:
+
+- Activate an account for a provider.
+- Rename an account.
+- Remove an account after confirmation.
+- View supported usage snapshots when the provider exposes compatible usage data.
 
-When the active account receives a retryable response such as `429`, `500`, `502`, `503`, `504`, or `529`, the plugin marks it as temporarily rate-limited and retries with another available account for the same provider.
+Aliases are normalized to lowercase and may contain letters, numbers, dots, hyphens, and underscores.
 
-## Fallback Commands
+### Configure Automatic Balancing
 
-`opencode-balancer` is TUI-first. `/balancer` commands are compatibility and troubleshooting fallbacks, not the primary account management workflow. Alias creation is intentionally handled by the TUI pending-connection flow.
+Open the priority matrix from the dashboard header or press `P`.
 
-| Command | Description |
-| --- | --- |
-| `/balancer help` | Show fallback commands. |
-| `/balancer list` | List saved accounts as `provider/alias`. |
-| `/balancer status` | Show saved and pending counts. |
-| `/balancer use <provider> <alias>` | Switch the active account for a provider. |
-| `/balancer active <provider>` | Show the active account for a provider. |
+In the priority matrix you can:
 
-Aliases are normalized to lowercase and may contain letters, numbers, dots, hyphens, and underscores.
+- Press `B` to enable or disable automatic balancing.
+- Pick the model used for each provider with `Enter`.
+- Reorder providers with `Shift+Up` and `Shift+Down`.
+- Enable or disable individual providers with `Space`.
+
+When balancing is on, the priority matrix decides the provider/model for each message. The plugin selects the first enabled provider with a configured model and a healthy saved account. When a retryable error is returned, the current account is temporarily marked as rate-limited and another healthy account for that provider is used when available.
+
+When balancing is off, opencode keeps its native provider/model selection. The plugin only applies the selected saved account when needed.
+
+## TUI Entry Points
+
+`opencode-balancer` is managed from the TUI. Use one of these entry points to open the dashboard:
+
+- `Ctrl+B`
+- `/balancer`
+- **Open Balancer Dashboard** in the command palette
+- The Balancer sidebar button
 
 ## How It Works
 
-`opencode-balancer` hooks into opencode's plugin lifecycle and request flow:
+`opencode-balancer` combines server hooks with a TUI module:
 
-1. It watches opencode auth changes and records detected provider credentials as pending connections.
-2. The Balancer TUI saves pending connections under provider-specific aliases.
-3. Before model requests, the plugin selects the active account for the request provider.
-4. If the provider returns a retryable rate-limit or server response, the plugin marks the account as temporarily unavailable and retries with another saved account.
+1. The TUI dashboard opens opencode's native connect flow and stores changed provider credentials as saved accounts.
+2. The dashboard stores selected accounts, per-provider models, balancing state, usage snapshots, and priority order in a local SQLite database.
+3. Before a chat request, server hooks choose the active account and, when balancing is enabled, the provider/model from the priority matrix.
+4. A fetch patch injects the selected account credentials into the provider request.
+5. Retryable provider responses mark the account as temporarily rate-limited and trigger a retry with another healthy account when balancing is enabled.
 
 Saved account data is written to:
 
@@ -121,12 +148,29 @@ If `OPENCODE_CONFIG_DIR` is set, the plugin uses that directory instead.
 ## Local Development
 
 ```bash
-npm install
-npm run check
-npm run build
+bun install
+bun run check
+bun run build
+bun test
+```
+
+Releases use Changesets:
+
+```bash
+bun run changeset
+bun run version
+bun run release
+```
+
+To test a local checkout with opencode, point your opencode config to the package directory:
+
+```json
+{
+  "plugin": ["file:///absolute/path/to/opencode-balancer"]
+}
 ```
 
-To test a local checkout with opencode, point your config to the package directory:
+And add the same local path to your TUI config:
 
 ```json
 {
@@ -138,11 +182,11 @@ To test a local checkout with opencode, point your config to the package directo
 
 | Problem | What to try |
 | --- | --- |
-| Plugin does not load | Confirm `plugin` is singular, restart opencode, and check that the package name is `@thelioo/opencode-balancer@latest`. |
-| `/balancer` is unavailable | Restart opencode after editing the config. |
-| No connection detected | Run `/connect <provider>` first, then save the pending connection from the Balancer TUI modal/sidebar. |
-| Account is not switching | Open the Balancer sidebar/dashboard and confirm there is another saved account for the same provider. |
-| Need command-line fallback | Run `/balancer help` for compatibility commands. |
+| Plugin does not load | Confirm `plugin` is singular in opencode config, restart opencode, and check that the package name is `@thelioo/opencode-balancer`. |
+| Dashboard does not open | Confirm `tui.json` also contains the plugin, restart opencode, then try `Ctrl+B`, `/balancer`, or the command palette. |
+| Account was not saved | Use **New account** from the Balancer dashboard and complete opencode's native provider connection flow. |
+| Provider is skipped | Open the priority matrix and confirm the provider is enabled and has a model selected. |
+| Account is not switching | Confirm there is another non-disabled saved account for the same provider and automatic balancing is on. |
 
 ## Resources