opencode-overclock 0.1.0

package/src/features/usage.ts

@@ -0,0 +1,270 @@
+import { tool } from "@opencode-ai/plugin"
+import type { FeatureModule } from "../types.ts"
+import { ensureStateDir, readJson, writeJson } from "../lib/state.ts"
+
+const z = tool.schema
+
+export interface UsageTokens {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+export interface DayBucket {
+  cost: number
+  tokens: UsageTokens
+  messages: number
+  seen: string[]
+}
+
+export interface UsageState {
+  days: Record<string, DayBucket>
+}
+
+export interface SessionUsage {
+  sessionID: string
+  cost: number
+  tokens: { input: number; output: number }
+}
+
+const RETENTION_DAYS = 60
+
+function zeroTokens(): UsageTokens {
+  return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 }
+}
+
+function emptyBucket(): DayBucket {
+  return { cost: 0, tokens: zeroTokens(), messages: 0, seen: [] }
+}
+
+/** Local YYYY-MM-DD from an epoch-ms timestamp. */
+export function dayKey(ms: number): string {
+  const d = new Date(ms)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, "0")
+  const day = String(d.getDate()).padStart(2, "0")
+  return `${y}-${m}-${day}`
+}
+
+function pruneOldDays(state: UsageState, now: number, retentionDays = RETENTION_DAYS): void {
+  const cutoff = new Date(now)
+  cutoff.setDate(cutoff.getDate() - retentionDays)
+  const cutoffKey = dayKey(cutoff.getTime())
+  for (const day of Object.keys(state.days)) {
+    if (day < cutoffKey) delete state.days[day]
+  }
+}
+
+const fmtCost = (n: number) => `$${n.toFixed(4)}`
+const col = (s: string, n: number) => s.padEnd(n)
+
+export interface UsageTrackerOpts {
+  statePath: string
+  debounceMs?: number
+}
+
+/** Exported for tests: event-consuming core, decoupled from plugin ctx. */
+export interface UsageTracker {
+  load(): Promise<void>
+  onEvent(event: { type: string; properties?: unknown }): void
+  getState(): UsageState
+  getSessionTotals(): SessionUsage[]
+  report(days?: number): string
+  flush(): Promise<void>
+  dispose(): Promise<void>
+}
+
+export function createUsageTracker(opts: UsageTrackerOpts): UsageTracker {
+  const debounceMs = opts.debounceMs ?? 2000
+  let state: UsageState = { days: {} }
+  const sessions = new Map<string, SessionUsage>()
+  let flushTimer: ReturnType<typeof setTimeout> | undefined
+
+  function scheduleFlush(): void {
+    if (flushTimer) clearTimeout(flushTimer)
+    flushTimer = setTimeout(() => {
+      flushTimer = undefined
+      void flush()
+    }, debounceMs)
+  }
+
+  async function flush(): Promise<void> {
+    await writeJson(opts.statePath, state)
+  }
+
+  async function load(): Promise<void> {
+    state = await readJson<UsageState>(opts.statePath, { days: {} })
+    pruneOldDays(state, Date.now())
+  }
+
+  function onEvent(event: { type: string; properties?: unknown }): void {
+    try {
+      if (event.type !== "message.updated") return
+      const info = (event.properties as { info?: unknown } | undefined)?.info as
+        | {
+            id?: string
+            role?: string
+            sessionID?: string
+            time?: { created?: number; completed?: number }
+            cost?: number
+            tokens?: {
+              input?: number
+              output?: number
+              reasoning?: number
+              cache?: { read?: number; write?: number }
+            }
+          }
+        | undefined
+      if (!info || info.role !== "assistant") return
+      if (!info.time?.completed) return
+      if (typeof info.id !== "string" || typeof info.sessionID !== "string") return
+      const created = info.time.created ?? info.time.completed
+      const day = dayKey(created)
+      const bucket = state.days[day] ?? emptyBucket()
+      state.days[day] = bucket
+      if (bucket.seen.includes(info.id)) return
+      bucket.seen.push(info.id)
+
+      const cost = info.cost ?? 0
+      const t = info.tokens ?? {}
+      const input = t.input ?? 0
+      const output = t.output ?? 0
+      const reasoning = t.reasoning ?? 0
+      const cacheRead = t.cache?.read ?? 0
+      const cacheWrite = t.cache?.write ?? 0
+
+      bucket.cost += cost
+      bucket.messages += 1
+      bucket.tokens.input += input
+      bucket.tokens.output += output
+      bucket.tokens.reasoning += reasoning
+      bucket.tokens.cacheRead += cacheRead
+      bucket.tokens.cacheWrite += cacheWrite
+
+      const sess = sessions.get(info.sessionID) ?? {
+        sessionID: info.sessionID,
+        cost: 0,
+        tokens: { input: 0, output: 0 },
+      }
+      sess.cost += cost
+      sess.tokens.input += input
+      sess.tokens.output += output
+      sessions.set(info.sessionID, sess)
+
+      scheduleFlush()
+    } catch (e) {
+      console.warn(`[overclock] usage: event handling failed: ${e}`)
+    }
+  }
+
+  function report(daysCount = 7): string {
+    const lines: string[] = []
+    const base = new Date()
+    base.setHours(0, 0, 0, 0)
+    const dayKeys: string[] = []
+    for (let i = daysCount - 1; i >= 0; i--) {
+      const d = new Date(base)
+      d.setDate(d.getDate() - i)
+      dayKeys.push(dayKey(d.getTime()))
+    }
+
+    lines.push(
+      col("Date", 12) +
+        col("Cost", 10) +
+        col("Input", 9) +
+        col("Output", 9) +
+        col("Reason", 9) +
+        col("CacheR", 9) +
+        col("CacheW", 9) +
+        "Msgs",
+    )
+    for (const day of dayKeys) {
+      const b = state.days[day]
+      const t = b?.tokens ?? zeroTokens()
+      lines.push(
+        col(day, 12) +
+          col(fmtCost(b?.cost ?? 0), 10) +
+          col(String(t.input), 9) +
+          col(String(t.output), 9) +
+          col(String(t.reasoning), 9) +
+          col(String(t.cacheRead), 9) +
+          col(String(t.cacheWrite), 9) +
+          String(b?.messages ?? 0),
+      )
+    }
+
+    lines.push("")
+    lines.push("Today per-session (since plugin start):")
+    if (sessions.size === 0) {
+      lines.push("(none)")
+    } else {
+      lines.push(col("Session", 16) + col("Cost", 10) + col("Input", 9) + "Output")
+      for (const s of sessions.values()) {
+        lines.push(
+          col(s.sessionID, 16) +
+            col(fmtCost(s.cost), 10) +
+            col(String(s.tokens.input), 9) +
+            String(s.tokens.output),
+        )
+      }
+    }
+    return lines.join("\n")
+  }
+
+  return {
+    load,
+    onEvent,
+    getState: () => state,
+    getSessionTotals: () => [...sessions.values()],
+    report,
+    flush,
+    dispose: async () => {
+      if (flushTimer) {
+        clearTimeout(flushTimer)
+        flushTimer = undefined
+      }
+      await flush()
+    },
+  }
+}
+
+/**
+ * Cost/token telemetry from `message.updated` events. Persisted daily buckets +
+ * an in-memory per-session aggregate since plugin start.
+ */
+export const usage: FeatureModule = {
+  name: "usage",
+  defaultEnabled: true,
+  async init(ctx) {
+    const dir = await ensureStateDir(ctx.directory)
+    const tracker = createUsageTracker({ statePath: `${dir}/usage.json` })
+    await tracker.load()
+
+    return {
+      dispose: async () => {
+        await tracker.dispose()
+      },
+      event: async ({ event }) => {
+        try {
+          tracker.onEvent(event)
+        } catch (e) {
+          console.warn(`[overclock] usage: event handling failed: ${e}`)
+        }
+      },
+      tool: {
+        usage_report: tool({
+          description:
+            "Report cost/token usage for the last N days (default 7) plus today's per-session breakdown.",
+          args: {
+            days: z.number().optional().describe("number of days to report, default 7"),
+          },
+          async execute(args) {
+            return tracker.report(args.days ?? 7)
+          },
+        }),
+      },
+    }
+  },
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { features } from "./features/index.ts"
+import { loadConfig } from "./config.ts"
+import { mergeHooks } from "./merge.ts"
+import { missingSurfaces } from "./lib/probe.ts"
+import { toast } from "./lib/inject.ts"
+
+/**
+ * Entry. Load config -> probe surfaces -> init enabled modules -> merge hooks.
+ * Module crash or missing SDK surface (upstream drift) -> skip module, plugin survive.
+ */
+export const Overclock: Plugin = async (ctx) => {
+  const config = await loadConfig(ctx.directory)
+  const parts = []
+  const skipped: string[] = []
+
+  for (const feature of features) {
+    const setting = config.features?.[feature.name] ?? feature.defaultEnabled
+    if (setting === false) continue
+    const missing = missingSurfaces(ctx.client, feature.requires ?? [])
+    if (missing.length) {
+      console.warn(
+        `[overclock] ${feature.name} disabled: client lacks ${missing.join(", ")} (upstream drift?)`,
+      )
+      skipped.push(feature.name)
+      continue
+    }
+    const options = typeof setting === "object" ? setting : {}
+    try {
+      parts.push(await feature.init(ctx, options))
+    } catch (e) {
+      console.warn(`[overclock] feature ${feature.name} failed init: ${e}`)
+    }
+  }
+
+  if (skipped.length)
+    void toast(ctx.client, `overclock: ${skipped.join(", ")} disabled (SDK drift)`, "warning")
+  return mergeHooks(parts)
+}

package/src/lib/busy.ts

@@ -0,0 +1,25 @@
+/**
+ * Session busy tracking via `session.status` (doc-preferred; `session.idle` deprecated).
+ * Unknown/never-firing statuses degrade gracefully: empty set = nothing reported busy.
+ */
+export interface BusyTracker {
+  /** feed bus events */
+  onEvent(event: { type: string; properties?: unknown }): void
+  isBusy(sessionID: string): boolean
+}
+
+export function createBusyTracker(): BusyTracker {
+  const busy = new Set<string>()
+  return {
+    onEvent(event) {
+      const p = (event.properties ?? {}) as { sessionID?: string; status?: { type?: string } }
+      if (!p.sessionID) return
+      if (event.type === "session.status") {
+        p.status?.type === "idle" ? busy.delete(p.sessionID) : busy.add(p.sessionID)
+      } else if (event.type === "session.idle" || event.type === "session.deleted") {
+        busy.delete(p.sessionID)
+      }
+    },
+    isBusy: (id) => busy.has(id),
+  }
+}

package/src/lib/inject.ts

@@ -0,0 +1,56 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+
+type Client = PluginInput["client"]
+type ModelRef = { providerID: string; modelID: string }
+
+/**
+ * Session's active model = model of last assistant message.
+ * Without this, promptAsync falls back to config default model -> injected turns
+ * run on the wrong model (and pile up QUEUED behind a hung default).
+ */
+export async function sessionModel(client: Client, sessionID: string): Promise<ModelRef | undefined> {
+  try {
+    const res = await client.session.messages({ path: { id: sessionID } })
+    const msgs = res.data ?? []
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const info = msgs[i]?.info
+      if (info?.role === "assistant" && info.modelID) {
+        return { providerID: info.providerID, modelID: info.modelID }
+      }
+    }
+  } catch (e) {
+    console.warn(`[overclock] sessionModel lookup failed (${sessionID}): ${e}`)
+  }
+  return undefined
+}
+
+/**
+ * Re-entry: push text into session as user prompt, on the session's own model.
+ * promptAsync = fire-and-forget, server queues if busy. Failure -> warn, never throw.
+ */
+export async function inject(client: Client, sessionID: string, text: string): Promise<boolean> {
+  try {
+    const model = await sessionModel(client, sessionID)
+    await client.session.promptAsync({
+      path: { id: sessionID },
+      body: { parts: [{ type: "text", text }], ...(model ? { model } : {}) },
+    })
+    return true
+  } catch (e) {
+    console.warn(`[overclock] inject failed (session ${sessionID}): ${e}`)
+    return false
+  }
+}
+
+/** TUI toast, best-effort (headless server -> no TUI, swallow). */
+export async function toast(
+  client: Client,
+  message: string,
+  variant: "info" | "success" | "warning" | "error" = "info",
+): Promise<void> {
+  try {
+    await client.tui.showToast({ body: { message, variant } })
+  } catch {
+    // no TUI attached
+  }
+}

package/src/lib/probe.ts

@@ -0,0 +1,15 @@
+/**
+ * Runtime surface probe (doc: "probe for the surfaces we depend on ... instead of
+ * failing silently when upstream moves"). Dot-paths resolved against the SDK client;
+ * leaf must be a function.
+ */
+export function missingSurfaces(client: unknown, paths: string[]): string[] {
+  return paths.filter((path) => {
+    let node: unknown = client
+    for (const key of path.split(".")) {
+      if (node == null || typeof node !== "object") return true
+      node = (node as Record<string, unknown>)[key]
+    }
+    return typeof node !== "function"
+  })
+}

package/src/lib/state.ts

@@ -0,0 +1,27 @@
+import { mkdir } from "node:fs/promises"
+
+/** State root: <project>/.opencode/overclock/[sub]. Creates if missing. */
+export async function ensureStateDir(directory: string, sub?: string): Promise<string> {
+  const dir = `${directory}/.opencode/overclock${sub ? `/${sub}` : ""}`
+  await mkdir(dir, { recursive: true })
+  return dir
+}
+
+export async function readJson<T>(path: string, fallback: T): Promise<T> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) return fallback
+  try {
+    return (await file.json()) as T
+  } catch {
+    return fallback
+  }
+}
+
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await Bun.write(path, JSON.stringify(value, null, 2))
+}
+
+/** POSIX single-quote escape. */
+export function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`
+}

package/src/merge.ts

@@ -0,0 +1,35 @@
+import type { Hooks } from "@opencode-ai/plugin"
+
+/**
+ * Compose many Partial<Hooks> into one Hooks.
+ * - fn hooks: call sequentially, module order. Each sees prior mutations of `output`.
+ * - `tool` map: shallow merge. Name collision -> later module wins, warn.
+ */
+export function mergeHooks(parts: Partial<Hooks>[]): Hooks {
+  const merged: Record<string, unknown> = {}
+  const tools: Record<string, unknown> = {}
+
+  for (const part of parts) {
+    for (const [key, value] of Object.entries(part)) {
+      if (value === undefined) continue
+      if (key === "tool") {
+        for (const [name, def] of Object.entries(value as Record<string, unknown>)) {
+          if (tools[name]) console.warn(`[overclock] tool collision: ${name} (later module wins)`)
+          tools[name] = def
+        }
+        continue
+      }
+      const prev = merged[key] as ((...a: unknown[]) => Promise<void>) | undefined
+      const next = value as (...a: unknown[]) => Promise<void>
+      merged[key] = prev
+        ? async (...args: unknown[]) => {
+            await prev(...args)
+            await next(...args)
+          }
+        : next
+    }
+  }
+
+  if (Object.keys(tools).length) merged.tool = tools
+  return merged as Hooks
+}

package/src/tui.ts

@@ -0,0 +1,227 @@
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+
+const STATE_SUBDIR = ".opencode/overclock"
+
+export interface TuiOptions {
+  notifyIdle?: boolean
+  notifyPermission?: boolean
+  notifyQuestion?: boolean
+  notifyError?: boolean
+}
+
+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>
+}
+
+export interface ScheduleMirrorEntry {
+  id: string
+  spec: string
+  target: string
+}
+
+/** Local YYYY-MM-DD from an epoch-ms timestamp (mirrors usage.ts, kept local to stay decoupled). */
+export function dayKey(ms: number): string {
+  const d = new Date(ms)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, "0")
+  const day = String(d.getDate()).padStart(2, "0")
+  return `${y}-${m}-${day}`
+}
+
+/** Pure: format the /oc-tasks toast summary from a parsed tasks.json mirror. */
+export function formatTasksSummary(entries: TaskMirrorEntry[] | undefined | null): string {
+  if (!entries) return "no data yet"
+  if (!entries.length) return "no tasks"
+  const counts: Record<string, number> = {}
+  for (const e of entries) counts[e.status] = (counts[e.status] ?? 0) + 1
+  const order: TaskMirrorEntry["status"][] = ["running", "exited", "killed"]
+  return order
+    .filter((s) => counts[s])
+    .map((s) => `${counts[s]} ${s}`)
+    .join(", ")
+}
+
+/** Pure: format the /oc-usage toast summary from a parsed usage.json, for a given "now". */
+export function formatUsageSummary(
+  state: UsageStateShape | undefined | null,
+  now: number = Date.now(),
+): string {
+  if (!state) return "no data yet"
+  const bucket = state.days?.[dayKey(now)]
+  if (!bucket) return "no usage today"
+  const tokens = bucket.tokens.input + bucket.tokens.output
+  return `today: $${bucket.cost.toFixed(4)}, ${tokens} tokens, ${bucket.messages} msgs`
+}
+
+/** Pure: format the /oc-schedules toast summary from a parsed schedules.json. */
+export function formatSchedulesSummary(schedules: ScheduleMirrorEntry[] | 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}`)
+  }
+
+  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}`)
+  }
+
+  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}`)
+  }
+
+  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}`)
+  }
+}
+
+export default { id: "overclock-tui", tui } satisfies TuiPluginModule