opencode-overclock 0.3.0 → 0.5.0

package/src/buddy/tui.ts

@@ -1,8 +1,21 @@
-import type { TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui"
-import { rollCompanion, describeCompanion, migrateSpecies } from "./companion.ts"
-import type { Companion, Rarity } from "./types.ts"
+import type { TuiThemeCurrent } from "@opencode-ai/plugin/tui"
+import type { Ui } from "../lib/ui.ts"
+import {
+  rollCompanion,
+  describeCompanion,
+  migrateSpecies,
+  pickReaction,
+  createReactionGate,
+  cycleSpecies,
+  switchSpecies,
+  speciesDescription,
+  SPECIES,
+  type Companion,
+  type Rarity,
+  type ReactionKind,
+  type Species,
+} from "./companion.ts"
 import { spriteFrame, withBubble, spriteHeight, SPRITE_WIDTH, type SpriteState } from "./sprites.ts"
-import { pickReaction, createReactionGate, type ReactionKind } from "./reactions.ts"
 
 const KV_KEY = "buddy.companion"
 /** Below this terminal width the buddy hides rather than crowd the prompt. */
@@ -20,6 +33,8 @@ const SLEEP_AFTER_MS = 120_000
 interface SpriteNode {
   content: string
   visible: boolean
+  height?: number | string
+  fg?: unknown
   destroyed?: boolean
 }
 
@@ -38,20 +53,17 @@ function rarityColor(rarity: Rarity, theme: TuiThemeCurrent): unknown {
 
 /**
  * Hatch (or load) the companion and mount it in the prompt-right slots.
- * Dynamic import of @opentui/solid: if the host doesn't map the specifier to its
- * own instance, this throws and the caller degrades to "no buddy" -- it must
- * never take the rest of the TUI plugin down.
+ * `enableJsx` throws when the host does not map @opentui/solid to its own instance;
+ * the caller degrades to "no buddy" and the rest of the TUI plugin is unaffected.
  */
-export async function registerBuddy(api: TuiPluginApi): Promise<void> {
-  const { jsx } = (await import("@opentui/solid/jsx-runtime")) as unknown as {
-    jsx: (type: string, props?: Record<string, unknown> | null) => unknown
-  }
+export async function registerBuddy(ui: Ui): Promise<void> {
+  await ui.enableJsx()
 
-  let companion = api.kv.get<Companion | undefined>(KV_KEY, undefined)
+  let companion = ui.api.kv?.get<Companion | undefined>(KV_KEY, undefined)
   if (!companion) {
     companion = rollCompanion()
-    api.kv.set(KV_KEY, companion)
-    api.ui.toast({ message: `a buddy hatched: ${describeCompanion(companion)}` })
+    ui.api.kv?.set(KV_KEY, companion)
+    ui.toast(`a buddy hatched: ${describeCompanion(companion)}`)
   } else {
     // A companion persisted under a species we have since retired has no art:
     // every lookup into ART would throw from inside the slot render, where the
@@ -60,11 +72,11 @@ export async function registerBuddy(api: TuiPluginApi): Promise<void> {
     const migrated = migrateSpecies(companion)
     if (migrated) {
       companion = migrated
-      api.kv.set(KV_KEY, migrated)
-      api.ui.toast({ message: `${migrated.name} is a ${migrated.species} now` })
+      ui.api.kv?.set(KV_KEY, migrated)
+      ui.toast(`${migrated.name} is a ${migrated.species} now`)
     }
   }
-  const hatched: Companion = companion
+  let active: Companion = companion
 
   // One ticker drives every mounted node (home + session slots).
   const nodes = new Set<SpriteNode>()
@@ -82,9 +94,9 @@ export async function registerBuddy(api: TuiPluginApi): Promise<void> {
 
   function paint(): void {
     const now = Date.now()
-    const frame = spriteFrame(hatched.species, currentState(now), tick)
+    const frame = spriteFrame(active.species, currentState(now), tick)
     const text = withBubble(frame, now < bubbleUntil ? bubble : undefined)
-    const wide = api.renderer.width >= MIN_COLS
+    const wide = (ui.api.renderer?.width ?? 120) >= MIN_COLS
     for (const node of [...nodes]) {
       try {
         if (node.destroyed) {
@@ -108,29 +120,116 @@ export async function registerBuddy(api: TuiPluginApi): Promise<void> {
     paint()
   }
 
-  const timer = setInterval(() => {
+  function setCompanion(next: Companion, toastMessage?: string): void {
+    active = next
+    ui.api.kv?.set(KV_KEY, next)
+    const currentTheme = ui.api.theme?.current
+    for (const node of [...nodes]) {
+      try {
+        if (node.destroyed) {
+          nodes.delete(node)
+          continue
+        }
+        if (currentTheme) {
+          node.fg = rarityColor(active.rarity, currentTheme)
+        }
+        node.height = spriteHeight(active.species)
+      } catch {
+        nodes.delete(node)
+      }
+    }
+    react("pet")
+    ui.toast(toastMessage ?? describeCompanion(active))
+  }
+
+  function openSwitchDialog(dialog?: unknown): void {
+    const stack = (dialog ?? ui.api.ui?.dialog) as
+      { replace(render: () => unknown, onClose?: () => void): void; clear(): void } | undefined
+    const DialogSelect = ui.api.ui?.DialogSelect
+
+    if (!stack || typeof stack.replace !== "function" || !DialogSelect) {
+      const next = cycleSpecies(active.species)
+      setCompanion(
+        switchSpecies(active, next),
+        `switched to ${next}: ${describeCompanion(switchSpecies(active, next))}`,
+      )
+      return
+    }
+
+    let closed = false
+    const selectBuddy = (speciesOrRandom: string) => {
+      if (closed) return
+      closed = true
+      try {
+        stack.clear()
+      } catch {
+        // ignore
+      }
+      if (speciesOrRandom === "random") {
+        const fresh = rollCompanion()
+        setCompanion(fresh, `a new buddy hatched: ${describeCompanion(fresh)}`)
+      } else if ((SPECIES as readonly string[]).includes(speciesOrRandom)) {
+        const nextSpecies = speciesOrRandom as Species
+        setCompanion(
+          switchSpecies(active, nextSpecies),
+          `switched to ${nextSpecies}: ${describeCompanion(switchSpecies(active, nextSpecies))}`,
+        )
+      }
+    }
+
+    const options = [
+      ...SPECIES.map((species) => ({
+        title: species,
+        value: species,
+        description: speciesDescription(species, species === active.species),
+        onSelect: () => selectBuddy(species),
+      })),
+      {
+        title: "random roll",
+        value: "random",
+        description: "hatch a brand new companion with new stats & rarity",
+        onSelect: () => selectBuddy("random"),
+      },
+    ]
+
+    try {
+      stack.replace(() =>
+        ui.node(DialogSelect as any, {
+          title: "Switch Buddy",
+          placeholder: "Select a species...",
+          current: active.species,
+          options,
+          onSelect: (opt: { value: string }) => selectBuddy(opt.value),
+        }),
+      )
+    } catch {
+      const next = cycleSpecies(active.species)
+      setCompanion(
+        switchSpecies(active, next),
+        `switched to ${next}: ${describeCompanion(switchSpecies(active, next))}`,
+      )
+    }
+  }
+
+  ui.every(TICK_MS, () => {
     tick++
     paint()
-  }, TICK_MS)
-  api.lifecycle.onDispose(async () => clearInterval(timer))
+  })
 
   const gate = createReactionGate()
-  const unsubs = [
-    api.event.on("session.status", (event) => {
-      lastActivity = Date.now()
-      if (event.properties.status.type === "idle" && gate.tryFire()) react("done")
-    }),
-    api.event.on("session.error", () => {
-      if (gate.tryFire()) react("error")
-    }),
-    api.event.on("permission.asked", () => {
-      if (gate.tryFire()) react("permission")
-    }),
-    api.event.on("question.asked", () => {
-      if (gate.tryFire()) react("question")
-    }),
-  ]
-  for (const unsub of unsubs) api.lifecycle.onDispose(async () => unsub())
+  ui.on("session.status", (event) => {
+    lastActivity = Date.now()
+    if (event.properties?.status?.type === "idle" && gate.tryFire()) react("done")
+  })
+  ui.on("session.error", () => {
+    if (gate.tryFire()) react("error")
+  })
+  ui.on("permission.asked", () => {
+    if (gate.tryFire()) react("permission")
+  })
+  ui.on("question.asked", () => {
+    if (gate.tryFire()) react("question")
+  })
 
   // The host renders the slot inside a one-line flex row next to the agent/model
   // text (prompt/index.tsx: justifyContent="space-between"). An in-flow sprite
@@ -139,44 +238,55 @@ export async function registerBuddy(api: TuiPluginApi): Promise<void> {
   // parent's edges, and bottom/right pin the creature's last row onto the
   // agent/model line while it grows upward over the (usually empty) input area.
   const renderSprite = (theme: TuiThemeCurrent) =>
-    jsx("text", {
+    ui.node("text", {
       position: "absolute",
       bottom: 0,
       right: 0,
       width: SPRITE_WIDTH,
-      height: spriteHeight(hatched.species),
-      content: spriteFrame(hatched.species, "idle", tick),
-      fg: rarityColor(hatched.rarity, theme),
+      height: spriteHeight(active.species),
+      content: spriteFrame(active.species, "idle", tick),
+      fg: rarityColor(active.rarity, theme),
       selectable: false,
-      visible: api.renderer.width >= MIN_COLS,
+      visible: (ui.api.renderer?.width ?? 120) >= MIN_COLS,
       ref: (node: SpriteNode | undefined) => {
         if (node) nodes.add(node)
       },
     })
 
-  // register returns the assigned plugin id, not a disposer -- the host owns
-  // slot cleanup when the TUI plugin deactivates.
-  api.slots.register({
-    slots: {
-      home_prompt_right: (ctx) => renderSprite(ctx.theme.current),
-      session_prompt_right: (ctx) => renderSprite(ctx.theme.current),
+  ui.slots({
+    home_prompt_right: (ctx) => renderSprite(ctx.theme.current),
+    session_prompt_right: (ctx) => renderSprite(ctx.theme.current),
+  })
+
+  ui.command({
+    title: "Overclock: Pet buddy",
+    slash: "oc-buddy",
+    aliases: ["buddy"],
+    run: () => {
+      react("pet")
+      ui.toast(describeCompanion(active))
     },
   })
 
-  try {
-    const uncommand = api.command?.register(() => [
-      {
-        title: "Overclock: Pet buddy",
-        value: "overclock.buddy",
-        slash: { name: "oc-buddy" },
-        onSelect: async () => {
-          react("pet")
-          api.ui.toast({ message: describeCompanion(hatched) })
-        },
-      },
-    ])
-    if (uncommand) api.lifecycle.onDispose(async () => uncommand())
-  } catch (e) {
-    console.warn(`[overclock-tui] /oc-buddy command registration failed: ${e}`)
-  }
+  ui.command({
+    title: "Overclock: Switch buddy",
+    slash: "oc-buddy-switch",
+    aliases: ["buddy-switch"],
+    run: (dialog) => {
+      openSwitchDialog(dialog)
+    },
+  })
+
+  ui.command({
+    title: "Overclock: Cycle buddy",
+    slash: "oc-buddy-cycle",
+    aliases: ["buddy-cycle"],
+    run: () => {
+      const next = cycleSpecies(active.species)
+      setCompanion(
+        switchSpecies(active, next),
+        `switched to ${next}: ${describeCompanion(switchSpecies(active, next))}`,
+      )
+    },
+  })
 }

package/src/core/bridge.ts

@@ -0,0 +1,34 @@
+import type { Hooks, Plugin as V1Plugin } from "@opencode-ai/plugin"
+import type { PluginContext as V2Context } from "@opencode-ai/plugin/v2/promise"
+import type { HybridPlugin, HybridPluginDefinition } from "./types.ts"
+
+export type { HybridPlugin, HybridPluginDefinition } from "./types.ts"
+
+/**
+ * Creates a plugin export that satisfies both OpenCode V1 and V2 host lifecycles.
+ *
+ * - On a V1 host, it can be called directly as a function `(input, options)` or read via `{ id, server }`.
+ * - On a V2 host, it presents `{ id, setup(context) }` conforming to the V2 plugin specification.
+ */
+export function createHybridPlugin<TOptions = Record<string, unknown>>(
+  definition: HybridPluginDefinition<TOptions>,
+): HybridPlugin<TOptions> {
+  const v1Runner: V1Plugin = async (input, options) => {
+    if (!definition.server) return {}
+    return (await definition.server(input, options as TOptions)) as Hooks
+  }
+
+  const v2Runner = async (context: V2Context): Promise<void> => {
+    if (!definition.setup) return
+    const options = (context.options ?? {}) as TOptions
+    await definition.setup(context, options)
+  }
+
+  const hybrid = Object.assign(v1Runner, {
+    id: definition.id,
+    server: v1Runner,
+    setup: v2Runner,
+  }) as HybridPlugin<TOptions>
+
+  return hybrid
+}

package/src/core/lifecycle.ts

@@ -0,0 +1,67 @@
+import type { Hooks } from "@opencode-ai/plugin"
+import { applyToolPolicy, EMPTY_POLICY, type ToolPolicy } from "./policy.ts"
+
+/**
+ * Compose many Partial<Hooks> into one unified Hooks object.
+ * - fn hooks: sequential composition in array order.
+ * - tool definitions: merged and filtered/remapped via policy.
+ * - dispose: fault-tolerant sequential cleanup guaranteeing every disposer executes.
+ */
+export function mergeHooks(parts: Partial<Hooks>[], policy: ToolPolicy = EMPTY_POLICY): Hooks {
+  const merged: Record<string, unknown> = {}
+  const rawTools: Record<string, unknown> = {}
+
+  for (const part of parts) {
+    for (const [key, value] of Object.entries(part)) {
+      if (value === undefined) continue
+      if (key === "tool") {
+        const toolsObj = value as Record<string, unknown>
+        for (const [toolName, toolDef] of Object.entries(toolsObj)) {
+          if (rawTools[toolName] !== undefined) {
+            console.warn(`[overclock] tool collision: ${toolName} (later module wins)`)
+          }
+          rawTools[toolName] = toolDef
+        }
+        continue
+      }
+      const prev = merged[key] as ((...a: unknown[]) => Promise<unknown>) | undefined
+      const next = value as (...a: unknown[]) => Promise<unknown>
+      merged[key] = prev
+        ? async (...args: unknown[]) => {
+            if (key === "dispose") {
+              await Promise.resolve(prev(...args)).catch((e) =>
+                console.warn(`[overclock] dispose error: ${e}`),
+              )
+              await Promise.resolve(next(...args)).catch((e) =>
+                console.warn(`[overclock] dispose error: ${e}`),
+              )
+              return
+            }
+            if (key === "event") {
+              try {
+                await prev(...args)
+              } catch (e) {
+                console.warn(`[overclock] event error: ${e}`)
+              }
+              try {
+                await next(...args)
+              } catch (e) {
+                console.warn(`[overclock] event error: ${e}`)
+              }
+              return
+            }
+            const prevRes = await prev(...args)
+            const nextRes = await next(...args)
+            return nextRes !== undefined ? nextRes : prevRes
+          }
+        : next
+    }
+  }
+
+  const processedTools = applyToolPolicy(rawTools, policy)
+  if (Object.keys(processedTools).length > 0) {
+    merged.tool = processedTools
+  }
+
+  return merged as Hooks
+}

package/src/core/policy.ts

@@ -0,0 +1,128 @@
+import type { ConfigIssue, FeatureModule, OverclockOptions, ToolPolicy } from "./types.ts"
+export { EMPTY_POLICY, type ToolPolicy } from "./types.ts"
+
+/**
+ * Tool ids opencode registers itself (observed on 1.18.4 via `/experimental/tool/ids`).
+ *
+ * Only used to warn: a tool registered under one of these *replaces* the built-in in the final
+ * tool map, and a name that differs only by case (`Task` vs `task`) is worse still -- the host
+ * offers both, and a consumer that matches case-insensitively sees a duplicate.
+ */
+export const HOST_TOOL_IDS: readonly string[] = [
+  "apply_patch",
+  "bash",
+  "edit",
+  "glob",
+  "grep",
+  "invalid",
+  "question",
+  "read",
+  "skill",
+  "task",
+  "todowrite",
+  "webfetch",
+  "websearch",
+  "write",
+]
+
+/**
+ * Resolve tool rename and allowlist policies.
+ *
+ * - Remaps tool names according to `config.toolNames`.
+ * - Withholds any tool not in `config.toolAllowlist` (if configured).
+ * - Emits warnings on collisions with host built-in tool names.
+ */
+export function resolveToolPolicy(
+  config: Pick<OverclockOptions, "toolNames" | "toolAllowlist">,
+  features: readonly FeatureModule[],
+): { policy: ToolPolicy; issues: ConfigIssue[] } {
+  const issues: ConfigIssue[] = []
+  const rename: Record<string, string> = { ...(config.toolNames ?? {}) }
+  const withheld = new Set<string>()
+
+  let allowedSet: Set<string> | undefined
+  if (config.toolAllowlist !== undefined) {
+    if (typeof config.toolAllowlist === "string") {
+      allowedSet = new Set([config.toolAllowlist])
+    } else if (
+      Array.isArray(config.toolAllowlist) &&
+      config.toolAllowlist.every((s) => typeof s === "string")
+    ) {
+      allowedSet = new Set(config.toolAllowlist)
+    } else {
+      issues.push({
+        path: "toolAllowlist",
+        message: `must be a string or array of strings, got ${Array.isArray(config.toolAllowlist) ? "array with non-strings" : typeof config.toolAllowlist}`,
+      })
+    }
+  }
+
+  const allTools = features.flatMap((f) => f.tools ?? [])
+  for (const declared of allTools) {
+    const visible = rename[declared] ?? declared
+
+    // Check collisions with host built-ins
+    const twin = HOST_TOOL_IDS.find((id) => id.toLowerCase() === visible.toLowerCase())
+    if (twin) {
+      issues.push({
+        path: `tool "${declared}"`,
+        message:
+          twin === visible
+            ? `"${visible}" is an opencode built-in -- registering it replaces that built-in`
+            : `"${visible}" differs from opencode's built-in "${twin}" only by case; anything matching case-insensitively sees one name twice`,
+      })
+    }
+
+    // Check allowlist
+    if (allowedSet && !allowedSet.has(visible)) {
+      withheld.add(declared)
+      issues.push({
+        path: `tool "${declared}"`,
+        message: `"${visible}" is not in toolAllowlist -- withheld from the model. Add it to toolAllowlist or remap via toolNames`,
+      })
+    }
+  }
+
+  return { policy: { rename, withheld }, issues }
+}
+
+/**
+ * Rewrite declared tool names appearing inside a description in a single regex pass.
+ * Word-anchored so a name that is a substring of a longer identifier is not clobbered,
+ * and single-pass so chained mappings (A -> B, B -> C) do not cascade.
+ */
+export function renameInText(text: string, rename: Record<string, string>): string {
+  const activeEntries = Object.entries(rename).filter(([from, to]) => from !== to)
+  if (activeEntries.length === 0) return text
+
+  const pattern = new RegExp(
+    `\\b(${activeEntries.map(([k]) => k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`,
+    "g",
+  )
+  return text.replace(pattern, (match) => rename[match] ?? match)
+}
+
+/**
+ * Filter withheld tools and apply renames and description updates to tool definitions.
+ */
+export function applyToolPolicy(
+  tools: Record<string, unknown>,
+  policy: ToolPolicy = { rename: {}, withheld: new Set() },
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  const { rename, withheld } = policy
+  const hasRenames = Object.keys(rename).length > 0
+
+  for (const [declared, def] of Object.entries(tools)) {
+    if (withheld.has(declared)) continue
+    const name = rename[declared] ?? declared
+    if (result[name]) console.warn(`[overclock] tool collision: ${name} (later module wins)`)
+
+    const d = def as { description?: unknown }
+    result[name] =
+      hasRenames && typeof d?.description === "string"
+        ? { ...d, description: renameInText(d.description, rename) }
+        : def
+  }
+  return result
+}

package/src/core/summary.ts

@@ -0,0 +1,33 @@
+import type { FeatureModule, ToolPolicy } from "./types.ts"
+import { EMPTY_POLICY } from "./policy.ts"
+
+/**
+ * One-line inventory of what this plugin just added to the session.
+ *
+ * Reports capability: installing overclock grants the agent background shell execution and
+ * recurring scheduling, and that should not be something a user discovers by accident.
+ */
+export function summarise(
+  enabled: readonly FeatureModule[],
+  skipped: readonly string[],
+  policy: ToolPolicy = EMPTY_POLICY,
+): string {
+  const { rename, withheld } = policy
+  const offered = enabled.flatMap((f) => (f.tools ?? []).filter((t) => !withheld.has(t)))
+  // Report the name the model is actually offered, not the declared one -- under a remap the
+  // declared name appears nowhere on the wire, so listing it would misdescribe the session.
+  const parts = enabled.map((f) => {
+    const names = (f.tools ?? []).filter((t) => !withheld.has(t)).map((t) => rename[t] ?? t)
+    return `${f.name}${names.length ? ` (${names.join(", ")})` : ""}`
+  })
+  const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`
+  let line = `${plural(enabled.length, "module")}, ${plural(offered.length, "tool")}: ${parts.join(" · ")}`
+  const applied = offered.filter((t) => rename[t] && rename[t] !== t).map((t) => `${t}->${rename[t]}`)
+  if (applied.length) line += ` | renamed: ${applied.join(", ")}`
+  // Withheld tools are the one case where the session is quietly less capable than the config
+  // implies, so they are named here rather than left to the issue log alone.
+  const held = enabled.flatMap((f) => (f.tools ?? []).filter((t) => withheld.has(t)))
+  if (held.length) line += ` | withheld: ${held.join(", ")}`
+  if (skipped.length) line += ` | skipped: ${skipped.join(", ")}`
+  return line
+}