opencode-peak-scheduler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# opencode-peak-scheduler
+
+OpenCode plugin that automatically switches the DeepSeek model OpenCode uses
+based on Beijing **peak-pricing windows**: during peak hours a cheaper/faster
+model is selected, off-peak the full model is restored.
+
+Built and verified against the **anomalyco/opencode fork (~1.18.x)** — the
+plugin API and the session-model lever were confirmed against that source (see
+`spike/README.md`).
+
+## Schedule (Asia/Shanghai, UTC+8)
+
+| Window   | Model                         | When                                       |
+| -------- | ----------------------------- | ------------------------------------------ |
+| Peak     | `deepseek/deepseek-v4-flash`  | Mon–Fri 09:00–12:00 and 14:00–18:00        |
+| Off-peak | `deepseek/deepseek-v4-pro`    | Everything else + weekends (Sat & Sun)     |
+
+Half-open intervals `[start, end)`. Weekday means Monday–Friday in the
+**Asia/Shanghai** calendar, regardless of the host machine's timezone.
+
+## How it works
+
+Two parts cooperate:
+
+### Provider-level routing — the real lever
+
+The `deepseek` provider in `opencode.json` is repointed from
+`@ai-sdk/openai-compatible` to this package. `createSchedulerProvider`
+(exported from the package entry) **wraps** the openai-compatible provider and
+adds one pseudo-model, `auto`, which becomes the default model:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "deepseek/auto",
+  "provider": {
+    "deepseek": {
+      "npm": "file:///home/mukminov/src/opencode-peak-scheduler",
+      "name": "DeepSeek",
+      "options": {
+        "baseURL": "https://api.deepseek.com",
+        "apiKey": "…",
+        "scheduler": {
+          "peakModel": "deepseek-v4-flash",
+          "offModel": "deepseek-v4-pro",
+          "timezone": "Asia/Shanghai",
+          "autoID": "auto"
+        }
+      },
+      "models": {
+        "deepseek-v4-pro": { "name": "DeepSeek-V4-Pro" },
+        "deepseek-v4-flash": { "name": "deepseek-v4-flash" },
+        "auto": {
+          "name": "Auto (peak-aware)",
+          "limit": { "context": 1048576, "output": 393216 }
+        }
+      }
+    }
+  }
+}
+```
+
+When opencode requests `deepseek/auto`, the factory returns a
+`TimeRoutedLanguageModel`: on every `doGenerate`/`doStream` it runs the pure
+`resolveModel(date)` scheduler against the Beijing window and delegates to the
+real inner model for that moment. Any other model id (e.g.
+`deepseek/deepseek-v4-pro`) passes straight through untouched.
+
+The `npm` value must be a `file:///` URL (three slashes: `file://` +
+absolute path). The fork's `resolveSDK` only takes its direct-import branch
+for specs starting with `file://`; anything else (e.g. `file:/…` with one
+slash) is treated as an npm package and goes through `Npm.add` → cross-process
+flock + arborist reify into a shared cache directory. That path is slow and
+fragile (shared mutable state across every opencode instance using the same
+config) and fails with `Failed to initialize provider: deepseek` when the
+reify/entrypoint resolution hiccups. The `file:///` form imports the package
+directory directly and skips all of that.
+
+### TUI plugin — informational only
+
+The TUI plugin (`tui.ts`) keeps watching the clock and switching the session
+**row** model (`POST /api/session/:id/model`) at peak↔off-peak transitions.
+That switch is **informational**: the TUI always sends its own model in the
+message body and `input.model` is authoritative for the whole turn, so actual
+call routing happens in the provider (`auto`), not in the row. The row switch
+only steers model-less turns, and the plugin surfaces window transitions as a
+toast plus the switch's own chat line, adds palette entries, and shows a live
+"Model" block at the top of the right sidebar (window + resolved model).
+A palette entry **Peak Scheduler: Toggle Mode** switches between the two global
+modes. **Auto** keeps the session on `auto` (window-routed, approximate cost).
+**Manual** stops all switching so you can pick the real model yourself (accurate
+cost); picking any non-`auto` model in the TUI auto-pauses switching, and
+picking `auto` (or the toggle) resumes it. The sidebar `Model` block shows the
+mode badge plus the window and resolved model (or a hint in manual mode).
+
+In **auto** mode the sidebar `Model` block also shows a `Cost:` line — an
+estimate the plugin computes itself (opencode prices the `auto` model at $0).
+It prices the session's token deltas with the resolved model's `cost`, applying
+a 2× peak multiplier during peak hours (DeepSeek bills off-peak at half the peak
+rate). Configure the **off-peak** per-1M-token prices on the model entries in
+`opencode.json` (see the live table at
+`https://api-docs.deepseek.com/quick_start/pricing/`):
+
+    "deepseek-v4-pro":  { "cost": { "input": 0.66, "output": 1.98, "cache": { "read": 0.022, "write": 0 } } },
+    "deepseek-v4-flash": { "cost": { "input": 0.22, "output": 0.66, "cache": { "read": 0.007, "write": 0 } } }
+
+`input` is the cache-miss price, `cache.read` the cache-hit price, and
+`cache.write` is 0 (DeepSeek doesn't charge for cache writes). DeepSeek's peak
+hours (`01:00–04:00` and `06:00–10:00` UTC) are exactly the plugin's peak
+windows, so during peak the plugin routes to `deepseek-v4-flash` at 2× and
+off-peak to `deepseek-v4-pro` at 1×. The estimate is accurate to the 30s check
+interval; in manual mode opencode prices the real model itself, so the plugin
+hides the line.
+
+### Cost — disclaimer
+
+**The `Cost:` line is an estimate, not your bill.** opencode prices a turn from
+the model id in the request; under `auto` that id has no `cost`, so opencode's
+own `Context` block always shows `$0.00` in auto mode. The plugin works around
+this by computing its own estimate from the session's token deltas and the
+resolved model's `cost` (with the 2× peak multiplier). This is a workaround
+with known gaps:
+
+- It is **per-session** and sampled every 30s — tokens at peak↔off-peak and
+  auto↔manual boundaries may be attributed to the neighbouring window.
+- On the first observation of a session (e.g. right after a restart) its
+  existing tokens are priced at the **current** window's model, so the estimate
+  is approximate for sessions that span multiple windows.
+- It assumes a **flat 2×** peak multiplier and `cache.write = 0`; if DeepSeek
+  changes its pricing or cache-billing model, the estimate drifts.
+- It is **not authoritative** — your actual spend is what DeepSeek bills
+  (`platform.deepseek.com`). For exact per-turn cost, switch to **manual** mode:
+  there opencode prices the real model with its `cost` directly.
+
+### Balance
+
+The sidebar also shows a `Balance:` line — the account's current DeepSeek
+balance, fetched via `GET /user/balance` (see
+`https://api-docs.deepseek.com/api/get-user-balance`) using the provider's
+`apiKey`. The balance is **account-wide** (one balance for both
+`deepseek-v4-pro` and `deepseek-v4-flash`), refreshed on startup and then every
+5 minutes. The line is hidden when no API key is configured or the request
+fails.
+
+### Cache
+
+With the `file:///` npm spec the provider package is imported directly from
+the source directory — no npm snapshot is taken, and rebuilds are picked up by
+restarting OpenCode. If you ever use a package-style spec instead, OpenCode
+snapshots the provider into its npm cache (`Npm.add`) at startup and does
+**not** refresh it on rebuild; in that case clear the snapshot before
+restarting:
+
+```bash
+rm -rf "$HOME/.cache/opencode/packages/file:/home/mukminov/src/opencode-peak-scheduler"
+```
+
+## Install
+
+1. `bun run build`
+2. Point the `deepseek` provider at the package and add the `auto` model +
+   top-level `model` key (snippet above).
+3. Register the TUI plugin in the **TUI config** (`tui.json`), not in
+   `opencode.json`. The fork's TUI plugin host loads plugins from
+   `TuiConfig.pluginOrigins()`, which only reads the `plugin` array out of
+   `tui.json` files — the `plugin` array in `opencode.json` feeds the server
+   process only, so a TUI plugin declared there is never loaded (no toasts, no
+   palette commands):
+
+```jsonc
+// ~/.config/opencode/tui.json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    ["/home/mukminov/src/opencode-peak-scheduler", { "peakModel": "deepseek-v4-flash" }],
+    "/home/mukminov/src/opencode-git-footer"
+  ]
+}
+```
+
+The custom sidebar footer (path + git branch + dirty indicator) lives in a
+separate package, `opencode-git-footer`; this package only ships the
+peak/off-peak routing and its TUI status UI.
+
+4. Restart OpenCode (the `file:///` import is resolved once at startup).
+
+## Options
+
+Two config surfaces, both validated with zod (unknown keys rejected).
+
+Plugin options (`plugin` tuple):
+
+| Key               | Type     | Default                  | Meaning                                  |
+| ----------------- | -------- | ------------------------ | ---------------------------------------- |
+| `providerID`      | `string` | `"deepseek"`             | Provider part of the target model        |
+| `peakModel`       | `string` | `"deepseek-v4-flash"`    | Model used during peak hours             |
+| `offModel`        | `string` | `"deepseek-v4-pro"`      | Model used off-peak                      |
+| `timezone`        | `string` | `"Asia/Shanghai"`        | IANA timezone the schedule runs in       |
+| `autoID`          | `string` | `"auto"`                 | Pseudo-model id routed by the window     |
+| `checkIntervalMs` | `number` | `30000`                  | How often the period is re-checked       |
+
+Provider `scheduler` options (inside `provider.deepseek.options.scheduler`):
+
+| Key         | Type     | Default               | Meaning                              |
+| ----------- | -------- | --------------------- | ------------------------------------ |
+| `peakModel` | `string` | `"deepseek-v4-flash"` | Model used during peak hours         |
+| `offModel`  | `string` | `"deepseek-v4-pro"`   | Model used off-peak                  |
+| `timezone`  | `string` | `"Asia/Shanghai"`     | IANA timezone the schedule runs in   |
+| `autoID`    | `string` | `"auto"`              | Pseudo-model id routed by the window |
+
+An invalid `timezone` falls back to `Asia/Shanghai` with a warning.
+
+## Commands
+
+| Palette entry              | What it shows                            |
+| -------------------------- | ---------------------------------------- |
+| **Peak Scheduler: Status** | Current window, resolved model, session  |
+| **Peak Scheduler: Window Now** | Model that applies right now         |
+
+Notes:
+
+- These are **command-palette** entries (`api.command.register`), not `/peak`
+  slash commands. The fork has no server hook that answers a slash command
+  without an LLM turn (`command.execute.before` only mutates the prompt parts
+  and still calls the model), so a cheap status UI lives in the palette.
+- Peak/off transitions surface as a toast, and the session-row switch itself
+  also shows a "Model switched" line in the chat.
+
+## Limitations (honest)
+
+- **Explicit model choices are always respected.** Picking a concrete model
+  (e.g. `deepseek-v4-flash` during off-peak) bypasses the scheduler entirely —
+  only `auto` is routed by the window, and `input.model` wins per turn.
+- **The provider package must be reachable at that exact `file:///` path.** The
+  import is resolved at startup; moving or deleting the source directory while
+  OpenCode is running does not affect the loaded copy, and a fresh start will
+  fail with `Failed to initialize provider: deepseek` until the path exists
+  again.
+- **Interactive turns are not rewritten.** When you type a message, the TUI
+  sends your selected model in the message body and it is authoritative for that
+  whole turn. The plugin changes the **session row model**, which steers
+  *subsequent model-less turns* (autonomous/agentic subflows, compactions,
+  summaries) — never an already-in-flight or already-typed message.
+- **Sessions with an explicit model are respected.** A session that was created
+  with a provider other than `providerID`, or that already carries an explicit
+  model, is left untouched (the plugin cannot tell intent; it only acts on
+  model-less sessions and on transitions).
+- **Requires a running TUI** for the informational row switches, toasts, and
+  status UI. A headless `opencode run`/`serve` without the TUI still gets
+  provider-level routing for `auto`, but no session-row switching or status UI.
+- **Per-model `options` are not applied to `auto`-routed calls.** OpenCode
+  computes provider options from the `auto` model entry (which has none), so
+  `options` on the `deepseek-v4-pro`/`deepseek-v4-flash` entries (e.g.
+  `reasoningEffort`) are bypassed for calls routed via `auto`. Put shared
+  options at provider level (`provider.deepseek.options`) or on the `auto`
+  entry instead.
+- **Cost under `auto` is a plugin-computed estimate.** opencode prices a turn
+  from the model id in the request, so under `auto` its own `$0.00` is expected.
+  The plugin's `Cost:` line estimates it from the resolved model's `cost` and
+  the 2× peak multiplier (accurate to the 30s tick). Manual mode uses the real
+  model, so opencode's own pricing is exact there.
+
+## Development
+
+```bash
+bun install
+bun run verify   # bun test && tsc --noEmit
+bun run build    # bun build index.ts tui.ts + .d.ts into dist/
+```
+
+Layout: `src/scheduler.ts` (pure period resolution),
+`src/provider/` (`createSchedulerProvider` wrapper + `TimeRoutedLanguageModel`),
+`src/engine.ts` (transition logic — fully unit-tested), `src/switch-model.ts`
+(V2 switch call), `src/tui-plugin.ts` (TUI glue), `tui.ts` (TUI module entry),
+`index.ts` (exports `createSchedulerProvider`).
+
+After a rebuild, clear the provider package cache (see above) before
+re-verifying live routing.
+
+## Donate
+
+If this plugin saves you money, you can say thanks:
+
+| QR | Address |
+| --- | --- |
+| ![BNB Smart Chain](assets/bsc.png) | **BNB Smart Chain (BEP-20):** `0x1Df93A331CF8D5bE9d382B6d55fe227D6489B2a2` |
+| ![Tron](assets/tron.png) | **Tron (TRC-20):** `TDfatR9JWqcfx5VuTMHDLQP3BN6f8Ynk5r` |
+
+## License
+
+MIT — see `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { PluginModule } from "@opencode-ai/plugin";
+import { createSchedulerProvider } from "./src/provider/scheduler-provider";
+export { createSchedulerProvider };
+declare const plugin: PluginModule;
+export default plugin;