opencode-overclock 0.3.0 → 0.4.0

package/src/platform/storage/store.ts

@@ -0,0 +1,61 @@
+import { defineStore } from "./state.ts"
+
+// ---------------------------------------------------------------- tasks
+
+export interface TaskMirrorEntry {
+  id: string
+  description: string
+  status: "running" | "exited" | "killed"
+  exitCode: number | null
+  startedAt: number
+}
+
+export const taskStore = defineStore<TaskMirrorEntry[]>("tasks.json", () => [])
+
+// ---------------------------------------------------------------- usage
+
+export interface UsageTokens {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+export interface DayBucket {
+  cost: number
+  tokens: UsageTokens
+  messages: number
+  /** message ids already counted, so a replayed event cannot double-bill */
+  seen: string[]
+}
+
+export interface UsageState {
+  days: Record<string, DayBucket>
+}
+
+/** What the TUI needs off a day bucket. `seen` is write-side bookkeeping. */
+export type DayBucketView = Omit<DayBucket, "seen">
+
+export interface UsageStateView {
+  days?: Record<string, DayBucketView | undefined>
+}
+
+export const usageStore = defineStore<UsageState>("usage.json", () => ({ days: {} }))
+
+// ---------------------------------------------------------------- schedules
+
+export interface ScheduleEntry {
+  id: string
+  spec: string
+  prompt: string
+  target: "current" | "new-session"
+  /** creator; also the inject target when target=current */
+  sessionID: string
+  createdAt: string
+}
+
+/** The TUI lists schedules; it has no business reading the prompt or the session id. */
+export type ScheduleEntryView = Pick<ScheduleEntry, "id" | "spec">
+
+export const scheduleStore = defineStore<ScheduleEntry[]>("schedules.json", () => [])

package/src/summary.ts

@@ -0,0 +1 @@
+export { summarise } from "./core/summary.ts"

package/src/tools.ts

@@ -1,244 +1,8 @@
-import type { ConfigIssue, FeatureModule, OverclockConfig } 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. Drift in this
- * list only makes the warning less complete, never wrong.
- */
-export const HOST_TOOL_IDS: readonly string[] = [
-  "apply_patch",
-  "bash",
-  "edit",
-  "glob",
-  "grep",
-  "invalid",
-  "question",
-  "read",
-  "skill",
-  "task",
-  "todowrite",
-  "webfetch",
-  "websearch",
-  "write",
-]
-
-export interface KnownAllowlist {
-  /** every name the list permits */
-  names: readonly string[]
-  /**
-   * declared tool name -> the name from this list it is offered under. Only for names that
-   * mean the same operation; nothing is invented, so this table stays short.
-   */
-  aliases: Readonly<Record<string, string>>
-  /**
-   * Tools with no honest alias in this list, and why. Recorded rather than left blank so the
-   * absence is a decision someone made, not an oversight -- a test requires every tool to be
-   * in `aliases` or here, and the reason is shown when such a tool gets withheld.
-   */
-  unaliased: Readonly<Record<string, string>>
-}
-
-/**
- * Named allowlists, usable anywhere a tool name is accepted in `toolAllowlist`.
- *
- * `claude-code` is Claude Code's registered tool set. opencode's own ids are snake_case and
- * disjoint from it, so every name here is free for this plugin to use.
- *
- * `aliases` only covers tools where a name in the list denotes the same operation, so nothing
- * here is a guess: background tasks and cron already exist in this vocabulary. Anything else is
- * listed in `unaliased` with the reason, because picking an unrelated name on a user's behalf
- * would mislead the model about what the tool does. Map those yourself with `toolNames`.
- *
- * Adding a tool: give it an alias or an `unaliased` reason in the same commit. A test fails
- * otherwise, so the decision surfaces in CI rather than as a rejected request mid-session.
- */
-export const KNOWN_ALLOWLISTS: Readonly<Record<string, KnownAllowlist>> = {
-  "claude-code": {
-    names: [
-      "Read",
-      "Write",
-      "Edit",
-      "MultiEdit",
-      "NotebookEdit",
-      "Glob",
-      "Grep",
-      "Bash",
-      "Agent",
-      "Task",
-      "Workflow",
-      "TodoWrite",
-      "TaskCreate",
-      "TaskGet",
-      "TaskList",
-      "TaskUpdate",
-      "TaskStop",
-      "TaskOutput",
-      "TeamCreate",
-      "TeamDelete",
-      "SendMessage",
-      "EnterPlanMode",
-      "ExitPlanMode",
-      "EnterWorktree",
-      "ExitWorktree",
-      "ListMcpResourcesTool",
-      "WaitForMcpServers",
-      "ToolSearch",
-      "Skill",
-      "CronCreate",
-      "CronDelete",
-      "CronList",
-      "ScheduleWakeup",
-      "AskUserQuestion",
-      "StructuredOutput",
-      "ValidationResult",
-      "ReportFindings",
-      "LSP",
-    ],
-    aliases: {
-      task_run: "TaskCreate",
-      task_status: "TaskList",
-      task_output: "TaskOutput",
-      task_kill: "TaskStop",
-      schedule_create: "CronCreate",
-      schedule_list: "CronList",
-      schedule_delete: "CronDelete",
-    },
-    unaliased: {
-      bash_unsandboxed: "the only fitting name is `Bash`, which is also an opencode built-in",
-      checkpoint_list: "no name in this list denotes session checkpoints",
-      checkpoint_revert: "no name in this list denotes session checkpoints",
-      checkpoint_restore: "no name in this list denotes session checkpoints",
-      usage_report: "no name in this list denotes cost/token telemetry",
-    },
-  },
-}
-
-export interface ToolPolicy {
-  /** declared name -> model-visible name */
-  rename: Record<string, string>
-  /** declared names withheld from the model entirely (no allowed name to use) */
-  withheld: Set<string>
-}
-
-export const EMPTY_POLICY: ToolPolicy = { rename: {}, withheld: new Set() }
-
-/** Entries like "claude-code" name a bundled list; a literal tool id would not look like this. */
-function looksLikeListName(entry: string): boolean {
-  return /^[a-z0-9]+(-[a-z0-9]+)+$/.test(entry)
-}
-
-/**
- * Expand `toolAllowlist` into the names it permits plus the aliases any named list brings.
- * Entries are either a known list name or a literal tool name, so extending a bundled list is
- * `["claude-code", "MyExtraTool"]` -- no separate key, no re-listing what the bundle covers.
- */
-export function resolveAllowlist(value: unknown): {
-  names?: string[]
-  aliases: Record<string, string>
-  /** declared tool -> why no bundled list offered a name for it */
-  unaliased: Record<string, string>
-  issues: ConfigIssue[]
-} {
-  const aliases: Record<string, string> = {}
-  const unaliased: Record<string, string> = {}
-  if (value === undefined) return { aliases, unaliased, issues: [] }
-
-  const entries = typeof value === "string" ? [value] : value
-  if (!Array.isArray(entries) || !entries.every((v) => typeof v === "string")) {
-    return {
-      aliases,
-      unaliased,
-      issues: [
-        {
-          path: "toolAllowlist",
-          message: `must be a name or an array of names (a known list is ${Object.keys(KNOWN_ALLOWLISTS).join(", ")}), got ${Array.isArray(value) ? "array with non-strings" : typeof value}`,
-        },
-      ],
-    }
-  }
-
-  const names: string[] = []
-  const issues: ConfigIssue[] = []
-  for (const entry of entries as string[]) {
-    const known = KNOWN_ALLOWLISTS[entry]
-    if (known) {
-      names.push(...known.names)
-      Object.assign(aliases, known.aliases)
-      Object.assign(unaliased, known.unaliased)
-      continue
-    }
-    // A typo'd list name would otherwise pass as a literal tool name, withhold everything, and
-    // suggest the typo itself as a free name. Cheap to catch, confusing to debug.
-    if (looksLikeListName(entry)) {
-      issues.push({
-        path: "toolAllowlist",
-        message: `"${entry}" looks like a known list but is not one (known: ${Object.keys(KNOWN_ALLOWLISTS).join(", ")}) -- treating it as a literal tool name`,
-      })
-    }
-    names.push(entry)
-  }
-  return { names, aliases, unaliased, issues }
-}
-
-/**
- * Fold the allowlist's aliases + explicit renames into one policy, and report what a human
- * needs to act on. Every check here exists because the failure it catches is otherwise
- * invisible until a request comes back rejected:
- * - a tool with no permitted name is withheld, and the still-free names are listed so picking
- *   one is a single config line;
- * - a name that collides with a host built-in (or its case-twin) is called out, since that
- *   replaces the built-in or reads as a duplicate.
- */
-export function resolveToolPolicy(
-  config: Pick<OverclockConfig, "toolNames" | "toolAllowlist">,
-  features: readonly FeatureModule[],
-): { policy: ToolPolicy; issues: ConfigIssue[] } {
-  const { names: allowlist, aliases, unaliased, issues } = resolveAllowlist(config.toolAllowlist)
-
-  // Explicit names win: a bundled list is a starting point, not a straitjacket.
-  const rename: Record<string, string> = { ...aliases, ...(config.toolNames ?? {}) }
-
-  const final = new Map<string, string>() // declared -> model-visible
-  for (const name of features.flatMap((f) => f.tools ?? [])) {
-    final.set(name, rename[name] ?? name)
-  }
-
-  for (const [name, visible] of final) {
-    const twin = HOST_TOOL_IDS.find((id) => id.toLowerCase() === visible.toLowerCase())
-    if (!twin) continue
-    issues.push({
-      path: `tool "${name}"`,
-      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`,
-    })
-  }
-
-  const withheld = new Set<string>()
-  if (allowlist) {
-    const allowed = new Set(allowlist)
-    const taken = new Set([...final.values()].filter((v) => allowed.has(v)))
-    const builtin = new Set(HOST_TOOL_IDS.map((id) => id.toLowerCase()))
-    // Suggesting a name that would immediately earn a built-in collision warning is worse than
-    // suggesting nothing, so case-twins of opencode's own ids are not offered.
-    const free = allowlist.filter((n) => !taken.has(n) && !builtin.has(n.toLowerCase()))
-    for (const [name, visible] of final) {
-      if (allowed.has(visible)) continue
-      withheld.add(name)
-      const why = unaliased[name] ? ` (${unaliased[name]})` : ""
-      issues.push({
-        path: `tool "${name}"`,
-        message:
-          `"${visible}" is not in toolAllowlist${why} -- withheld from the model. ` +
-          `Pick a name for it via toolNames (free: ${free.slice(0, 4).join(", ") || "none left"}), ` +
-          `or add one to toolAllowlist`,
-      })
-    }
-  }
-
-  return { policy: { rename, withheld }, issues }
-}
+export {
+  applyToolPolicy,
+  EMPTY_POLICY,
+  HOST_TOOL_IDS,
+  renameInText,
+  resolveToolPolicy,
+  type ToolPolicy,
+} from "./core/policy.ts"

package/src/tui.ts

@@ -1,7 +1,14 @@
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { registerBuddy } from "./buddy/tui.ts"
-
-const STATE_SUBDIR = ".opencode/overclock"
+import { createUi } from "./lib/ui.ts"
+import {
+  scheduleStore,
+  taskStore,
+  usageStore,
+  type ScheduleEntryView,
+  type TaskMirrorEntry,
+  type UsageStateView,
+} from "./lib/mirror.ts"
 
 export interface TuiOptions {
   notifyIdle?: boolean
@@ -11,44 +18,16 @@ export interface TuiOptions {
   buddy?: boolean
 }
 
-/**
- * The buddy toggles from the same overclock.json as the server features, so one
- * config file governs both surfaces. `features.buddy: false` disables; missing
- * file or unreadable config = default on.
- */
-export async function buddyEnabledInConfig(directory: string): Promise<boolean> {
-  try {
-    const file = Bun.file(`${directory}/.opencode/overclock.json`)
-    if (!(await file.exists())) return true
-    const config = (await file.json()) as { features?: Record<string, unknown> }
-    return config.features?.["buddy"] !== false
-  } catch {
-    return true
-  }
-}
-
-export interface TaskMirrorEntry {
-  id: string
-  description: string
-  status: "running" | "exited" | "killed"
-  exitCode: number | null
-  startedAt: number
-}
-
-export interface UsageDayBucket {
-  cost: number
-  tokens: { input: number; output: number; reasoning: number; cacheRead: number; cacheWrite: number }
-  messages: number
-}
-
-export interface UsageStateShape {
-  days: Record<string, UsageDayBucket>
-}
+/** Read views the summary formatters accept. Re-exported for tests and downstream typing. */
+export type { TaskMirrorEntry, ScheduleEntryView, UsageStateView }
 
-export interface ScheduleMirrorEntry {
-  id: string
-  spec: string
-  target: string
+/** Check if buddy feature is enabled via plugin options. */
+export function isBuddyEnabled(options?: TuiOptions): boolean {
+  if (!options) return true
+  if (options.buddy === false) return false
+  const features = (options as { features?: Record<string, unknown> }).features
+  if (features?.buddy === false) return false
+  return true
 }
 
 /** Local YYYY-MM-DD from an epoch-ms timestamp (mirrors usage.ts, kept local to stay decoupled). */
@@ -75,7 +54,7 @@ export function formatTasksSummary(entries: TaskMirrorEntry[] | undefined | null
 
 /** Pure: format the /oc-usage toast summary from a parsed usage.json, for a given "now". */
 export function formatUsageSummary(
-  state: UsageStateShape | undefined | null,
+  state: UsageStateView | undefined | null,
   now: number = Date.now(),
 ): string {
   if (!state) return "no data yet"
@@ -86,169 +65,61 @@ export function formatUsageSummary(
 }
 
 /** Pure: format the /oc-schedules toast summary from a parsed schedules.json. */
-export function formatSchedulesSummary(schedules: ScheduleMirrorEntry[] | undefined | null): string {
+export function formatSchedulesSummary(schedules: ScheduleEntryView[] | undefined | null): string {
   if (!schedules) return "no data yet"
   if (!schedules.length) return "no schedules"
   const list = schedules.map((s) => `${s.id} (${s.spec})`).join(", ")
   return `${schedules.length} schedule${schedules.length === 1 ? "" : "s"}: ${list}`
 }
 
-async function readState<T>(directory: string, file: string): Promise<T | undefined> {
-  try {
-    const f = Bun.file(`${directory}/${STATE_SUBDIR}/${file}`)
-    if (!(await f.exists())) return undefined
-    return (await f.json()) as T
-  } catch {
-    return undefined
-  }
-}
-
 const tui: TuiPlugin = async (api, options) => {
   const opts = (options ?? {}) as TuiOptions
-  const notifyIdle = opts.notifyIdle !== false
-  const notifyPermission = opts.notifyPermission !== false
-  const notifyQuestion = opts.notifyQuestion !== false
-  const notifyError = opts.notifyError !== false
-
-  const unsubs: Array<() => void> = []
-
-  try {
-    if (notifyIdle) {
-      unsubs.push(
-        api.event.on("session.status", (event) => {
-          if (event.properties.status.type !== "idle") return
-          void api.attention.notify({
-            title: "opencode",
-            message: "turn complete",
-            sound: { name: "done", when: "blurred" },
-            notification: { when: "blurred" },
-          })
-        }),
-      )
-    }
-  } catch (e) {
-    console.warn(`[overclock-tui] session.status subscription failed: ${e}`)
-  }
-
-  try {
-    if (notifyPermission) {
-      unsubs.push(
-        api.event.on("permission.asked", () => {
-          void api.attention.notify({
-            title: "opencode",
-            message: "needs permission",
-            sound: { name: "permission", when: "blurred" },
-            notification: { when: "blurred" },
-          })
-        }),
-      )
-    }
-  } catch (e) {
-    console.warn(`[overclock-tui] permission.asked subscription failed: ${e}`)
-  }
-
-  try {
-    if (notifyQuestion) {
-      unsubs.push(
-        api.event.on("question.asked", () => {
-          void api.attention.notify({
-            title: "opencode",
-            message: "asking a question",
-            sound: { name: "question", when: "blurred" },
-            notification: { when: "blurred" },
-          })
-        }),
-      )
-    }
-  } catch (e) {
-    console.warn(`[overclock-tui] question.asked subscription failed: ${e}`)
-  }
-
-  try {
-    if (notifyError) {
-      unsubs.push(
-        api.event.on("session.error", () => {
-          void api.attention.notify({
-            title: "opencode",
-            message: "session error",
-            sound: { name: "error", when: "blurred" },
-            notification: { when: "blurred" },
-          })
-        }),
-      )
-    }
-  } catch (e) {
-    console.warn(`[overclock-tui] session.error subscription failed: ${e}`)
-  }
-
-  try {
-    for (const unsub of unsubs) api.lifecycle.onDispose(async () => unsub())
-  } catch (e) {
-    console.warn(`[overclock-tui] lifecycle registration failed: ${e}`)
+  const ui = createUi(api)
+
+  if (opts.notifyIdle !== false) {
+    ui.on("session.status", (event) => {
+      if (event.properties?.status?.type === "idle") {
+        ui.notify({ message: "turn complete", sound: "done" })
+      }
+    })
   }
 
-  try {
-    const unregister = api.command?.register(() => [
-      {
-        title: "Overclock: Tasks",
-        value: "overclock.tasks",
-        slash: { name: "oc-tasks" },
-        onSelect: async () => {
-          const entries = await readState<TaskMirrorEntry[]>(api.state.path.directory, "tasks.json")
-          api.ui.toast({ message: formatTasksSummary(entries) })
-        },
-      },
-    ])
-    if (unregister) api.lifecycle.onDispose(async () => unregister())
-  } catch (e) {
-    console.warn(`[overclock-tui] /oc-tasks command registration failed: ${e}`)
+  if (opts.notifyPermission !== false) {
+    ui.on("permission.asked", () => ui.notify({ message: "needs permission", sound: "permission" }))
   }
 
-  try {
-    const unregister = api.command?.register(() => [
-      {
-        title: "Overclock: Usage",
-        value: "overclock.usage",
-        slash: { name: "oc-usage" },
-        onSelect: async () => {
-          const state = await readState<UsageStateShape>(api.state.path.directory, "usage.json")
-          api.ui.toast({ message: formatUsageSummary(state) })
-        },
-      },
-    ])
-    if (unregister) api.lifecycle.onDispose(async () => unregister())
-  } catch (e) {
-    console.warn(`[overclock-tui] /oc-usage command registration failed: ${e}`)
+  if (opts.notifyQuestion !== false) {
+    ui.on("question.asked", () => ui.notify({ message: "asking a question", sound: "question" }))
   }
 
-  try {
-    const unregister = api.command?.register(() => [
-      {
-        title: "Overclock: Schedules",
-        value: "overclock.schedules",
-        slash: { name: "oc-schedules" },
-        onSelect: async () => {
-          const schedules = await readState<ScheduleMirrorEntry[]>(
-            api.state.path.directory,
-            "schedules.json",
-          )
-          api.ui.toast({ message: formatSchedulesSummary(schedules) })
-        },
-      },
-    ])
-    if (unregister) api.lifecycle.onDispose(async () => unregister())
-  } catch (e) {
-    console.warn(`[overclock-tui] /oc-schedules command registration failed: ${e}`)
+  if (opts.notifyError !== false) {
+    ui.on("session.error", () => ui.notify({ message: "session error", sound: "error" }))
   }
 
-  // ASCII pet beside the prompt. Anything here failing (missing @opentui/solid,
-  // slot API drift) must degrade to "no buddy", never take the notifications down.
-  try {
-    if (opts.buddy !== false && (await buddyEnabledInConfig(api.state.path.directory))) {
-      await registerBuddy(api)
+  ui.command({
+    title: "Overclock: Tasks",
+    slash: "oc-tasks",
+    run: async () => ui.toast(formatTasksSummary(await ui.readOptional(taskStore))),
+  })
+
+  ui.command({
+    title: "Overclock: Usage",
+    slash: "oc-usage",
+    run: async () => ui.toast(formatUsageSummary(await ui.readOptional(usageStore))),
+  })
+
+  ui.command({
+    title: "Overclock: Schedules",
+    slash: "oc-schedules",
+    run: async () => ui.toast(formatSchedulesSummary(await ui.readOptional(scheduleStore))),
+  })
+
+  if (isBuddyEnabled(opts)) {
+    try {
+      await registerBuddy(ui)
+    } catch (e) {
+      console.warn(`[overclock-tui] buddy disabled: ${e}`)
     }
-  } catch (e) {
-    console.warn(`[overclock-tui] buddy disabled: ${e}`)
   }
 }
 

package/src/types.ts

@@ -1,73 +1 @@
-import type { Hooks, PluginInput } from "@opencode-ai/plugin"
-import type { BusyTracker } from "./lib/busy.ts"
-
-/**
- * Singletons built once by the entry and handed to every module.
- * Derived from the event bus, so they must have exactly one subscription -- a per-module
- * copy would be N subscriptions maintaining N identical copies of the same state.
- */
-export interface SharedDeps {
-  /** live per-session busy/idle state; the entry owns the subscription that feeds it */
-  busy: BusyTracker
-  /**
-   * Declared tool name -> the name the model was actually offered (see `toolNames` config).
-   * Needed wherever a module names one of its own tools in text the model reads: under a
-   * remap the declared name is not a tool the model has.
-   */
-  toolName(declared: string): string
-}
-
-/** Per-feature config from .opencode/overclock.json. `false` = off, object = options. */
-export type FeatureConfig = boolean | Record<string, unknown>
-
-/** A problem found in overclock.json. Lives here so config consumers need not import validate. */
-export interface ConfigIssue {
-  /** dotted location in overclock.json, e.g. "features.tasks.killOnExit" */
-  path: string
-  message: string
-}
-
-/** Option value kinds a module declares, so a typo in overclock.json can be caught. */
-export type OptionType = "boolean" | "number" | "string" | "array" | "object"
-
-export interface OverclockConfig {
-  features?: Record<string, FeatureConfig>
-  /**
-   * Model-visible tool ids: declared name -> replacement. The key of the `tool` hook map is
-   * literally the name sent to the provider, so this is the whole remap. Exists for hosts
-   * behind a proxy that whitelists tool names and rejects unknown ones.
-   *
-   * A replacement that collides with a built-in tool *overrides* that built-in in the final
-   * tool map -- borrow a name you do not mind losing. Permission ids are deliberately not
-   * remapped: they key the user's opencode permission config, not the wire format.
-   */
-  toolNames?: Record<string, string>
-  /**
-   * The only tool names the model may be offered. Entries are literal names or the name of a
-   * bundled list (see KNOWN_ALLOWLISTS), so extending one is `["claude-code", "MyExtraTool"]`.
-   * A bundled list also supplies default aliases for this plugin's tools; `toolNames` overrides
-   * those per tool.
-   *
-   * Any tool whose final name is not permitted is withheld from the model rather than offered
-   * and rejected -- a single unrecognised name can fail a whole request, so a loud gap at
-   * startup beats a session that cannot reach the provider.
-   */
-  toolAllowlist?: string[] | string
-}
-
-/**
- * One feature = one module.
- * init returns partial Hooks. Same hook from many modules -> composed in registry order.
- */
-export interface FeatureModule {
-  name: string
-  /** on by default? */
-  defaultEnabled: boolean
-  /** SDK client surfaces (dot-paths) the module needs. Missing -> module skipped + warn. */
-  requires?: string[]
-  /** Tool names registered. Declared, not derived -- feeds the first-run summary. */
-  tools?: string[]
-  /** Accepted option keys -> expected type. Anything else in config is a typo. */
-  options?: Record<string, OptionType>
-  init(ctx: PluginInput, options: Record<string, unknown>, shared: SharedDeps): Promise<Partial<Hooks>>
-}
+export * from "./core/types.ts"