opencode-overclock 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # opencode-overclock
 
-Power-ups for [opencode](https://opencode.ai): background tasks, cron-style scheduling,
-sandboxed bash, quality-gate hooks, cost telemetry, checkpoints — and an ASCII pet.
+The modular workflow suite and power-ups for [opencode](https://opencode.ai): background
+tasks, cron-style scheduling, quality-gate hooks, cost telemetry — and an ASCII companion.
 
 Everything is a separate module you can turn off individually, so you can take one feature and
 ignore the rest. When opencode ships a native equivalent, the matching module goes away.
@@ -13,18 +13,18 @@ opencode plugin -g opencode-overclock    # every project
 
 ## What you get
 
-| Module        | What it does                                                                                                                                          | Tools it adds                                              |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `tasks`       | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt. | `task_run` `task_status` `task_output` `task_kill`         |
-| `sched`       | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                   | `schedule_create` `schedule_list` `schedule_delete`        |
-| `guard`       | Your own quality gates: run a command after the agent edits files, and feed failures back to it once the session goes idle.                           | —                                                          |
-| `usage`       | Per-day and per-session cost and token totals, collected from the event bus.                                                                          | `usage_report`                                             |
-| `checkpoints` | Rewind a session to any earlier message, files included, on top of opencode's own snapshots. Reverting asks for permission first.                     | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` |
-| `sandbox`     | Wrap every bash call in bwrap: read-only `/`, writable project and `/tmp`, network off by default. Off unless you enable it.                          | `bash_unsandboxed` (escape hatch)                          |
-| `buddy`       | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                            | —                                                          |
+| Module      | What it does                                                                                                                                                  | Tools it adds                                       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `tasks`     | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt.         | `task_run` `task_status` `task_output` `task_kill`  |
+| `sched`     | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                           | `schedule_create` `schedule_list` `schedule_delete` |
+| `guard`     | Your own quality gates: run a command after the agent edits files, and feed failures back to it once the session goes idle. Built-in recipes & edit recovery. | —                                                   |
+| `recovery`  | Automatically heal provider errors (missing tool results, thinking block sequencing, context limit) and auto-resume sessions.                                 | —                                                   |
+| `truncator` | Context-protecting smart output truncation for high-volume tools (`task_output`, `bash`, `grep`, `glob`, `webfetch`) preserving header & tail diagnostics.    | —                                                   |
+| `usage`     | Per-day and per-session cost and token totals, collected from the event bus (accessible via TUI `/oc-usage`).                                                 | —                                                   |
+| `buddy`     | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                                    | —                                                   |
 
 On top of the tools, the TUI side adds desktop notifications when a turn finishes or the agent
-needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules` and `/oc-buddy`.
+needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules`, `/oc-buddy` (pet), `/oc-buddy-switch` (choose species), and `/oc-buddy-cycle` (next species).
 
 **Please read this before installing:** overclock gives the agent the ability to run shell
 commands in the background (`task_run`) and to schedule recurring prompts (`schedule_create`).
@@ -54,142 +54,239 @@ a plugin's `dispose` hook, without which this plugin's timers and watchers are n
 
 ## Configuration
 
-Everything is optional. With no config file you get every module except `sandbox`, and `guard`
-sits inert until you give it hooks — so the one thing worth configuring on day one is a quality
-gate. A reasonable `.opencode/overclock.json` to start from:
+Everything is optional. With no options configured, overclock runs with sensible defaults: background
+tasks, cron-style scheduling, quality gates, usage telemetry, and the buddy are active immediately.
 
-```json
+Configure options directly in your project or global `opencode.json`:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "tasks": { "killOnExit": true },
+        "guard": { "auto": true },
+      },
+    ],
+  ],
+}
+```
+
+To turn an individual feature off:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "buddy": false,
+      },
+    ],
+  ],
+}
+```
+
+| Module           | Options                                                                                                          |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `tasks`          | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num · `tmux` bool    |
+| `sched`          | `skipIfBusy` bool                                                                                                |
+| `guard`          | `hooks` array · `recipes` array (`["tsc", "eslint", "cargo", "ruff", "go"]`) · `auto` bool · `editRecovery` bool |
+| `recovery`       | `maxAttempts` num · `cooldownMs` num · `autoResume` bool                                                         |
+| `truncator`      | `maxChars` num · `tools` array · `headLines` num · `tailLines` num                                               |
+| `usage`, `buddy` | —                                                                                                                |
+
+### Quality gates (`guard`)
+
+Quality gates let you define automated feedback loops. Whenever the agent modifies code with `edit`
+or `write`, the guard runs your project's verification command in the background. If the command fails,
+the error output is automatically fed back into the session once the agent finishes its turn, prompting
+it to self-correct.
+
+Because verification commands vary by language and repository, configure hooks in your project's
+local `opencode.json`:
+
+#### Stack recipes
+
+##### TypeScript / JavaScript
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "typecheck",
+        "tools": ["edit", "write"],
+        "pathFilter": "src/**/*.ts",
+        "run": "npm run typecheck",
+      },
+    ],
+  },
+}
+```
+
+##### Python (Ruff / Pytest)
+
+```jsonc
 {
-  "features": {
-    "guard": {
-      "hooks": [
-        {
-          "name": "typecheck",
-          "tools": ["edit", "write"],
-          "run": "npm run typecheck",
-          "pathFilter": "src/**/*.ts"
-        }
-      ]
-    },
-    "tasks": { "killOnExit": true }
-  }
+  "guard": {
+    "hooks": [
+      {
+        "name": "lint",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.py",
+        "run": "ruff check .",
+      },
+    ],
+  },
 }
 ```
 
-That gives you a typecheck after every edit (reported back to the agent when the session goes
-idle), background tasks that don't outlive the session, plus scheduling, telemetry, checkpoints
-and the buddy on their defaults. Swap `run` for whatever your project uses.
+##### Rust (Cargo)
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "cargo-check",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.rs",
+        "run": "cargo check",
+      },
+    ],
+  },
+}
+```
 
-Each entry is `true`, `false`, or an object of options (which also means "on"). To turn
-something off:
+##### Go
 
-```json
-{ "features": { "buddy": false } }
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "go-test",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.go",
+        "run": "go test ./...",
+      },
+    ],
+  },
+}
 ```
 
-| Module                          | Options                                                                                         |
-| ------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `tasks`                         | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num |
-| `sched`                         | `skipIfBusy` bool                                                                               |
-| `sandbox`                       | `net` bool                                                                                      |
-| `guard`                         | `hooks` array                                                                                   |
-| `usage`, `checkpoints`, `buddy` | —                                                                                               |
+##### Generic / Make
 
-Typos are reported at startup with a "did you mean", because a misspelled key like
-`killOnExist` would otherwise read as "not set" and quietly run the default. A bad config never
-takes the plugin down; the affected setting falls back to its default.
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "check",
+        "tools": ["edit", "write"],
+        "run": "make check",
+      },
+    ],
+  },
+}
+```
 
-### Quality gate options (`guard`)
+#### Hook options
 
-Each hook runs a command after the agent uses one of the tools it watches, and reports failures
-back to the agent. `name`, `tools` and `run` are required. Also available: `pathFilter` (glob), `mode` (`inject`,
-the default, waits for the session to be idle before reporting; `append` reports immediately),
-`debounceMs` (2000), `timeoutMs` (60000), `onSuccess` (`silent` or `notify`), and `maxDeferMs`
-(300000, how long `inject` waits for an idle session before reporting anyway).
+| Field        | Default     | Description                                                                   |
+| ------------ | ----------- | ----------------------------------------------------------------------------- |
+| `name`       | _required_  | Identifier displayed in failure reports                                       |
+| `tools`      | _required_  | Tools to trigger on, e.g. `["edit", "write"]`                                 |
+| `run`        | _required_  | Shell command to execute (receives `$GUARD_TOOL` and `$GUARD_FILE` in env)    |
+| `pathFilter` | `undefined` | Optional glob pattern to limit triggers to relevant files (e.g. `**/*.py`)    |
+| `mode`       | `"inject"`  | `"inject"` waits for the session to go idle; `"append"` reports immediately   |
+| `debounceMs` | `2000`      | Debounce duration for rapid successive edits                                  |
+| `timeoutMs`  | `60000`     | Execution timeout before killing the command                                  |
+| `maxDeferMs` | `300000`    | Maximum time `"inject"` will wait for an idle session before reporting anyway |
+| `onSuccess`  | `"silent"`  | `"silent"` or `"notify"`                                                      |
 
-### Restricting tool names
+### Restricting and remapping tool names
 
 If your setup only accepts certain tool names, list them in `toolAllowlist`. Any tool whose
-name isn't permitted is withheld from the model rather than offered and refused, since a single
-unrecognised name can fail an entire request.
+name isn't permitted is withheld from the model rather than offered and refused:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "toolAllowlist": ["task_run", "task_status", "schedule_create"],
+      },
+    ],
+  ],
+}
+```
 
-```json
+`toolNames` maps this plugin's tools onto custom names you want the model to see:
+
+```jsonc
 {
-  "toolAllowlist": ["TaskCreate", "TaskList", "TaskOutput", "TaskStop", "MyExtraTool"],
-  "toolNames": { "task_run": "TaskCreate", "task_status": "TaskList" }
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "toolNames": { "task_run": "run_background_task" },
+      },
+    ],
+  ],
 }
 ```
 
-`toolNames` maps this plugin's tools onto names you allow. Keys are declared names (the table
-under [What you get](#what-you-get)); values are what the model sees.
-
-Startup tells you exactly where you stand: what was renamed, what was withheld and which of
-your allowed names are still free to use for it, and any name that collides with an opencode
-built-in (`bash`, `task`, …) or differs from one only by capitalisation — the first replaces
-that built-in, the second reads as a duplicate to anything matching case-insensitively.
-Descriptions mentioning a renamed tool are rewritten too, so the agent never gets instructions
-naming a tool it wasn't given. Permission ids keep their declared names, so existing permission
-config still applies.
-
-#### Named lists
-
-`toolAllowlist` entries can also name a bundled list, which expands to every name it permits.
-Mix and match freely — `["claude-code", "MyExtraTool"]` is a bundled list plus one of your own.
-
-`claude-code` is the tool set Claude Code registers. opencode's ids are snake_case and Claude
-Code's are PascalCase, so the two vocabularies don't overlap and these names are free to use.
-A bundled list also supplies default names for tools where it contains the same operation:
-
-| Module  | Declared          | Sent as      |
-| ------- | ----------------- | ------------ |
-| `tasks` | `task_run`        | `TaskCreate` |
-| `tasks` | `task_status`     | `TaskList`   |
-| `tasks` | `task_output`     | `TaskOutput` |
-| `tasks` | `task_kill`       | `TaskStop`   |
-| `sched` | `schedule_create` | `CronCreate` |
-| `sched` | `schedule_list`   | `CronList`   |
-| `sched` | `schedule_delete` | `CronDelete` |
-
-That's the whole table, and it stops there on purpose. Nothing in the `claude-code` set means
-"revert a session checkpoint" or "report token spend", so `checkpoints`, `usage` and
-`bash_unsandboxed` get no default name: handing them an unrelated one would tell the model the
-wrong thing about what they do. They're withheld until you choose a name yourself, and startup
-says which names are free:
-
-```json
+### Running OpenCode V2 plugins on OpenCode V1
+
+OpenCode V1 distributions cannot natively load V2 plugins (which export `{ id, setup }` or `{ id, effect }` instead of a server function). Overclock provides an embedded V2 host engine that runs V2 plugins side-by-side with V1 tools:
+
+```jsonc
 {
-  "toolAllowlist": "claude-code",
-  "toolNames": { "usage_report": "StructuredOutput" }
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "plugins": ["./plugins/custom-agent.ts", ["opencode-plugin-review", { "strict": true }]],
+      },
+    ],
+  ],
 }
 ```
 
-`toolNames` overrides any row above too, if a different name reads better for you. The table is
-checked against the source by a test, so the two can't drift apart.
+Overclock synthesizes a spec-compliant `PluginContext`, adapting V2 domain transforms (`agent`, `command`, `catalog`, `reference`, `skill`, `aisdk`) to live V1 config and chat hooks while keeping all V1 power tools active.
+
+Startup tells you what was renamed, what was withheld, and warns on collisions with opencode
+built-in tools. Descriptions mentioning a renamed tool are rewritten automatically.
 
 ## Notes on the TUI surface
 
 The TUI plugin sends a desktop notification (with sound) when a turn completes or the agent
 needs permission, asks a question, or errors — each individually switchable through plugin
-options. Its slash commands read the state files under `.opencode/overclock/`, so they work
+options (`notifyIdle`, `notifyPermission`, `notifyQuestion`, `notifyError`, `buddy` in `tui.json`).
+Its slash commands read the state files under `.opencode/overclock/`, so they work
 without going through the model.
 
 The buddy hatches once per install with a random species, rarity and name, persists in the
 TUI's key-value store, hides itself below 100 columns, and needs `@opentui/solid` resolvable at
 runtime. If it isn't, the buddy quietly sits out and the rest of the TUI plugin still loads.
+Switch buddy on demand via `/oc-buddy-switch` (opens an interactive species picker or rolls a fresh companion)
+or `/oc-buddy-cycle` (advances directly to the next species in rotation).
 
 ## Contributing
 
 ```
 src/
-  index.ts          entry: load config, init modules, merge hooks
+  index.ts          entry: init enabled modules, merge hooks, hybrid V1/V2 export
   tui.ts            TUI plugin (notifications + slash commands), separate export
-  types.ts          FeatureModule contract
-  config.ts         config loader
-  merge.ts          hook composition (many modules, same hook -> sequential)
-  tools.ts          gateway tool policy: alias presets, allowlists, rename/withhold
-  validate.ts       overclock.json checks + startup summary
-  lib/              state dir + json, session inject + toast
-  features/         one file per module + registry
+  core/             types, lifecycle/hook merging, tool policy, capability summary, bridge
+  platform/         host adapters: process (exec/tmux), session (busy/inject/notify), storage (state/store), probe
+  buddy/            ASCII companion state, sprites, and TUI slot integration
+  v2/               embedded V2 plugin host, synthetic context, and dynamic loader
+  features/         feature modules (tasks, sched, guard, recovery, truncator, usage, buddy)
 test/               bun test
 ```
 
@@ -197,8 +294,6 @@ Adding a feature:
 
 1. Write `src/features/<name>.ts` exporting a `FeatureModule`.
 2. Register it in `src/features/index.ts`.
-3. If it adds tools, add each one to the `claude-code` table in `src/tools.ts`. A test fails
-   otherwise, since an unmapped tool is invisible behind a whitelisting gateway.
 
 Background reading:
 [docs/opencode-plugin-surface.md](docs/opencode-plugin-surface.md) maps opencode's
@@ -243,7 +338,7 @@ somewhere else.
 ### Headless end-to-end
 
 ```sh
-timeout 90 opencode run -m anthropic/claude-sonnet-5 "Use task_run to run 'echo hi' ..." < /dev/null
+timeout 90 opencode run -m <provider>/<model> "Use task_run to run 'echo hi' ..." < /dev/null
 ```
 
 - `< /dev/null` is required; an open stdin hangs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-overclock",
-  "version": "0.3.0",
-  "description": "Power-ups for opencode: background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Modular, toggleable.",
+  "version": "0.4.0",
+  "description": "Power-ups for opencode: background tasks, cron scheduling, quality-gate hooks, usage telemetry, and companion. Modular, toggleable.",
   "type": "module",
   "repository": {
     "type": "git",

package/src/bridge.ts

@@ -0,0 +1 @@
+export { createHybridPlugin, type HybridPlugin, type HybridPluginDefinition } from "./core/bridge.ts"

package/src/buddy/companion.ts

@@ -1,4 +1,74 @@
-import { SPECIES, type Companion, type CompanionStats, type Rarity } from "./types.ts"
+import type { SpriteState } from "./sprites.ts"
+
+export const SPECIES = [
+  "cat",
+  "dog",
+  "bunny",
+  "owl",
+  "bat",
+  "penguin",
+  "duck",
+  "ghost",
+  "slime",
+] as const
+export type Species = (typeof SPECIES)[number]
+
+export type Rarity = "common" | "uncommon" | "rare" | "legendary"
+
+export interface CompanionStats {
+  patience: number
+  chaos: number
+  wisdom: number
+  snark: number
+}
+
+export interface Companion {
+  species: Species
+  rarity: Rarity
+  name: string
+  stats: CompanionStats
+  hatchedAt: number
+}
+
+export type ReactionKind = "done" | "error" | "permission" | "question" | "pet"
+
+/** Speech-bubble line + which face the sprite pulls while it shows. */
+export interface Reaction {
+  text: string
+  state: SpriteState
+}
+
+// Lines render into the sprite's 12-col effect row -- keep every line <= 12 chars.
+const POOLS: Record<ReactionKind, { lines: string[]; state: SpriteState }> = {
+  done: { lines: ["cooked", "ate that", "big W", "say less", "we ball"], state: "idle" },
+  error: { lines: ["bruh", "ur cooked", "skill issue", "aint no way", "big L"], state: "alarmed" },
+  permission: { lines: ["let me cook", "valid?", "we good?", "bet?", "vibe check"], state: "curious" },
+  question: { lines: ["wym?", "the move?", "u tell me", "spill", "hbu?"], state: "curious" },
+  pet: { lines: ["pookie!", "w rizz", "ur valid", "slay", "ily"], state: "pet" },
+}
+
+/** Pure: pick a random line for a reaction kind. */
+export function pickReaction(kind: ReactionKind, rng: () => number = Math.random): Reaction {
+  const pool = POOLS[kind]
+  return { text: pool.lines[Math.floor(rng() * pool.lines.length)]!, state: pool.state }
+}
+
+export interface ReactionGate {
+  /** True + arms the cooldown if enough time has passed since the last fire. */
+  tryFire(now?: number): boolean
+}
+
+/** Debounce for event-driven reactions -- keeps a busy session from spamming the bubble. */
+export function createReactionGate(cooldownMs = 8000): ReactionGate {
+  let last = -Infinity
+  return {
+    tryFire(now: number = Date.now()): boolean {
+      if (now - last < cooldownMs) return false
+      last = now
+      return true
+    },
+  }
+}
 
 const RARITY_WEIGHTS: { rarity: Rarity; weight: number }[] = [
   { rarity: "common", weight: 60 },
@@ -55,16 +125,45 @@ function rollStat(rng: () => number): number {
 }
 
 /**
- * Companions persist in TUI kv and outlive the sprite sheet, so an install that
- * hatched a species we have since retired would look it up and find no art. Move
- * it onto a species we still draw, keeping the identity that isn't the drawing:
- * same name, rarity, stats and hatch date. Returns undefined when nothing to do.
+ * Move companion onto an active species if its hatched species was retired.
  */
 export function migrateSpecies(c: Companion, rng: () => number = Math.random): Companion | undefined {
   if ((SPECIES as readonly string[]).includes(c.species)) return undefined
   return { ...c, species: pick(rng, SPECIES) }
 }
 
+/** Short character descriptions for each species based on their idle fidget. */
+export const SPECIES_DESCRIPTIONS: Record<Species, string> = {
+  cat: "tail flick",
+  dog: "ear perk",
+  bunny: "ear wiggle",
+  owl: "feather ruffle",
+  bat: "wing beat",
+  penguin: "waddle",
+  duck: "ripples",
+  ghost: "float",
+  slime: "squash",
+}
+
+/** Pure: formatted description for dialog options. */
+export function speciesDescription(species: Species, isCurrent = false): string {
+  const desc = SPECIES_DESCRIPTIONS[species] ?? species
+  return isCurrent ? `${desc} (current)` : desc
+}
+
+/** Move companion to a new species, preserving name, stats, and hatchedAt. */
+export function switchSpecies(c: Companion, species: Species): Companion {
+  if (!(SPECIES as readonly string[]).includes(species)) return c
+  return { ...c, species }
+}
+
+/** Pure: get the next species in the SPECIES rotation. */
+export function cycleSpecies(current: Species): Species {
+  const idx = SPECIES.indexOf(current)
+  if (idx === -1) return SPECIES[0]
+  return SPECIES[(idx + 1) % SPECIES.length]!
+}
+
 /** One-line card for the /oc-buddy toast. */
 export function describeCompanion(c: Companion): string {
   const s = c.stats

package/src/buddy/sprites.ts

@@ -1,4 +1,4 @@
-import type { Species } from "./types.ts"
+import type { Species } from "./companion.ts"
 
 /**
  * Every frame is padded to exactly SPRITE_WIDTH columns so animation never
@@ -35,8 +35,8 @@ interface SpeciesArt {
   /**
    * Which of the two poses a tick shows. Per-species on purpose: alternating
    * every tick reads as a strobe, and it makes every species move alike. A cat
-   * flicks its tail rarely, a dog wags nonstop, a dragon's wingbeat is slow and
-   * held at the top, a ghost never quite lands.
+   * flicks its tail rarely, a dog wags nonstop, a bat's wingbeat flutters rapidly,
+   * a ghost never quite lands.
    */
   beat: (t: number) => 0 | 1
 }
@@ -148,7 +148,7 @@ export function withBubble(frame: string, bubble: string | undefined): string {
 /** Pure: render one frame. `tick` drives idle fidget + blink; other states are static. */
 export function spriteFrame(species: Species, state: SpriteState, tick: number): string {
   const art = ART[species]
-  const t = ((tick % 1000) + 1000) % 1000
+  const t = Math.max(0, tick)
   const body = art.idle[art.beat(t)]!
   const rest = art.idle[0]!