opencode-overclock 0.2.2 → 0.4.0

package/src/lib/ui.ts

@@ -0,0 +1,208 @@
+import type { TuiPluginApi, TuiSlotContext } from "@opencode-ai/plugin/tui"
+import { missingSurfaces } from "./probe.ts"
+import type { Store } from "./state.ts"
+
+/** Raw `@opentui/solid` node factory. Returns a JSX.Element the host can render. */
+type JsxFactory = (type: string, props?: Record<string, unknown> | null) => unknown
+
+type SlotRender = (ctx: TuiSlotContext) => unknown
+
+export interface UiCommand {
+  /** command palette entry */
+  title: string
+  /** slash name, without the leading "/" */
+  slash?: string
+  /** optional slash aliases */
+  aliases?: string[]
+  /** unique command id; defaults to `overclock.<slash ?? title>` */
+  id?: string
+  run(dialog?: unknown): void | Promise<void>
+}
+
+export interface UiNotify {
+  message: string
+  title?: string
+  /** built-in sound name; only played when the terminal is blurred */
+  sound?: "default" | "question" | "permission" | "error" | "done" | "subagent_done"
+}
+
+/**
+ * Thin, failure-tolerant facade over `TuiPluginApi`.
+ *
+ * Two things it buys us. First, *uniform degradation*: every host call is a place the TUI API can
+ * drift out from under us, and a throw inside plugin setup takes down every later registration in
+ * the same function. Each method here is individually guarded and warns with a consistent label,
+ * so one broken surface costs exactly one feature. Second, *disposal by construction*: the host
+ * hands back an unsubscribe from `event.on`, an id from `slots.register` (where cleanup is host-managed), and
+ * nothing from `setInterval` -- contracts that call sites previously tracked
+ * by hand. Listeners and intervals registered through the facade are wired to `lifecycle.onDispose` here.
+ */
+export interface Ui {
+  /** escape hatch for surfaces the facade does not wrap yet */
+  readonly api: TuiPluginApi
+  /** project directory; the root every `Store` path is resolved against */
+  readonly directory: string
+  /** subscribe to a host event, auto-disposed. Returns the unsubscribe for early removal. */
+  readonly on: TuiPluginApi["event"]["on"]
+  /** register a palette/slash command, auto-disposed */
+  command(cmd: UiCommand): void
+  /** desktop notification + sound, fired only when the terminal is blurred */
+  notify(input: UiNotify): void
+  toast(message: string, variant?: "info" | "success" | "warning" | "error"): void
+  /** setInterval, cleared on dispose */
+  every(ms: number, fn: () => void): void
+  /** read a store defined in `platform/storage/store.ts` (or re-exported via `mirror.ts`) */
+  read<T>(store: Store<T>): Promise<T>
+  /** as `read`, but `undefined` when the server half has never written the file */
+  readOptional<T>(store: Store<T>): Promise<T | undefined>
+  /** true when every dot-path resolves to a function on the host api */
+  has(...paths: string[]): boolean
+  /**
+   * Load the host's JSX runtime, enabling `node()`. Separate from `createUi` because
+   * `@opentui/solid` is an optional peer and slot rendering is synchronous: a feature that draws
+   * must await this up front, and one that does not should not pay for the import.
+   */
+  enableJsx(): Promise<void>
+  /** create a renderable node. Throws unless `enableJsx()` resolved first. */
+  node(type: string, props: Record<string, unknown>): unknown
+  /** mount slot renderers. The host owns slot cleanup, so there is nothing to dispose. */
+  slots(map: Record<string, SlotRender>): void
+}
+
+function warn(label: string, e: unknown): void {
+  console.warn(`[overclock-tui] ${label} failed: ${e}`)
+}
+
+/** Run `fn`, swallowing and reporting any throw. Returns undefined on failure. */
+function guard<T>(label: string, fn: () => T): T | undefined {
+  try {
+    return fn()
+  } catch (e) {
+    warn(label, e)
+    return undefined
+  }
+}
+
+export function createUi(api: TuiPluginApi): Ui {
+  const directory = api.state.path.directory
+  let jsx: JsxFactory | undefined
+
+  /** Best-effort disposer registration -- `lifecycle` itself is a surface that can be missing. */
+  const onDispose = (fn: () => void): void => {
+    try {
+      api.lifecycle.onDispose(async () => fn())
+    } catch (e) {
+      warn("lifecycle registration", e)
+    }
+  }
+
+  const noop = () => {}
+
+  // Cast: the host's `on` is generic over the event union, and reproducing that generic on an
+  // ordinary function expression is not expressible without naming `Event`, which
+  // `@opencode-ai/plugin/tui` does not re-export. The cast keeps full narrowing for callers.
+  const on = ((type: string, handler: (event: never) => void) => {
+    const unsub = guard(`subscribe ${type}`, () =>
+      (api.event.on as (t: string, h: (event: never) => void) => () => void)(type, handler),
+    )
+    if (!unsub) return noop
+    onDispose(unsub)
+    return unsub
+  }) as TuiPluginApi["event"]["on"]
+
+  return {
+    api,
+    directory,
+    on,
+
+    command(cmd) {
+      const id = cmd.id ?? `overclock.${cmd.slash ?? cmd.title}`
+      // `api.command` is deprecated upstream in favour of `keymap.registerLayer({commands,
+      // bindings})`, and optional on the api type. Isolated here so that migration is a change
+      // to this one method rather than to every feature that registers a command.
+      const unregister = guard(`command ${id}`, () =>
+        api.command?.register(() => [
+          {
+            title: cmd.title,
+            value: id,
+            ...(cmd.slash
+              ? {
+                  slash: {
+                    name: cmd.slash,
+                    ...(cmd.aliases ? { aliases: cmd.aliases } : {}),
+                  },
+                }
+              : {}),
+            onSelect: async (dialog) => {
+              try {
+                await cmd.run(dialog)
+              } catch (e) {
+                warn(`command ${id}`, e)
+              }
+            },
+          },
+        ]),
+      )
+      if (unregister) onDispose(unregister)
+    },
+
+    notify(input) {
+      guard("notify", () =>
+        api.attention.notify({
+          title: input.title ?? "opencode",
+          message: input.message,
+          notification: { when: "blurred" },
+          ...(input.sound ? { sound: { name: input.sound, when: "blurred" as const } } : {}),
+        }),
+      )
+    },
+
+    toast(message, variant) {
+      guard("toast", () => api.ui.toast({ message, ...(variant ? { variant } : {}) }))
+    },
+
+    every(ms, fn) {
+      const timer = setInterval(() => {
+        try {
+          fn()
+        } catch (e) {
+          warn("interval", e)
+        }
+      }, ms)
+      onDispose(() => clearInterval(timer))
+    },
+
+    read(store) {
+      return store.read(directory)
+    },
+
+    readOptional(store) {
+      return store.readMaybe(directory)
+    },
+
+    has(...paths) {
+      return missingSurfaces(api, paths).length === 0
+    },
+
+    async enableJsx() {
+      // The host must map this specifier to *its own* solid instance. If it does not, the import
+      // throws here -- at the caller's await, where it can degrade to "no drawing" -- rather than
+      // from inside a slot render where nothing can catch it.
+      const mod = (await import("@opentui/solid/jsx-runtime")) as unknown as { jsx: JsxFactory }
+      jsx = mod.jsx
+    },
+
+    node(type, props) {
+      if (!jsx) throw new Error("ui.node() requires await ui.enableJsx()")
+      return jsx(type, props)
+    },
+
+    slots(map) {
+      guard("slot registration", () =>
+        api.slots.register({
+          slots: map as unknown as Parameters<TuiPluginApi["slots"]["register"]>[0]["slots"],
+        }),
+      )
+    },
+  }
+}

package/src/merge.ts

@@ -1,35 +1,2 @@
-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
-}
+export { mergeHooks } from "./core/lifecycle.ts"
+export { applyToolPolicy, EMPTY_POLICY, renameInText, type ToolPolicy } from "./core/policy.ts"

package/src/platform/probe.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 by default.
+ */
+export function missingSurfaces(
+  client: unknown,
+  paths: string[],
+  requiredType: "function" | "object" | "defined" = "function",
+): string[] {
+  return paths.filter((path) => {
+    let node: unknown = client
+    for (const key of path.split(".")) {
+      if (node == null || typeof node !== "object") return true
+      try {
+        node = (node as Record<string, unknown>)[key]
+      } catch {
+        return true
+      }
+    }
+    if (requiredType === "function") return typeof node !== "function"
+    if (requiredType === "object") return node === null || typeof node !== "object"
+    return node === undefined
+  })
+}

package/src/platform/process/exec.ts

@@ -0,0 +1,76 @@
+/**
+ * POSIX single-quote escape for safe shell argument interpolation.
+ */
+export function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`
+}
+
+export const NON_INTERACTIVE_ENV: Record<string, string> = {
+  GIT_PAGER: "cat",
+  PAGER: "cat",
+  GIT_EDITOR: "true",
+  CI: "true",
+  DEBIAN_FRONTEND: "noninteractive",
+  TERM: "dumb",
+}
+
+export interface ExecBashOptions {
+  cwd?: string
+  env?: Record<string, string | undefined>
+  timeoutMs?: number
+  onSpawn?: (proc: Bun.Subprocess) => void
+}
+
+export interface ExecBashResult {
+  code: number | null
+  stdout: string
+  stderr: string
+  combined: string
+}
+
+/**
+ * Run a command via `bash -c`, capturing stdout, stderr, and exit code.
+ * Ensures non-interactive environment variables with correct precedence and
+ * process termination escalation.
+ */
+export async function execBash(command: string, options: ExecBashOptions = {}): Promise<ExecBashResult> {
+  const mergedEnv: Record<string, string | undefined> = {
+    ...process.env,
+    ...NON_INTERACTIVE_ENV,
+    ...options.env,
+  }
+
+  const proc = Bun.spawn(["bash", "-c", command], {
+    cwd: options.cwd,
+    env: mergedEnv,
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  options.onSpawn?.(proc)
+
+  let killEscalationTimer: ReturnType<typeof setTimeout> | undefined
+  const killTimer = options.timeoutMs
+    ? setTimeout(() => {
+        try {
+          proc.kill("SIGTERM")
+        } catch {}
+        killEscalationTimer = setTimeout(() => {
+          try {
+            proc.kill("SIGKILL")
+          } catch {}
+        }, 2000)
+        killEscalationTimer.unref?.()
+      }, options.timeoutMs)
+    : undefined
+
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+
+  if (killTimer) clearTimeout(killTimer)
+  if (killEscalationTimer) clearTimeout(killEscalationTimer)
+
+  return { code, stdout, stderr, combined: stdout + stderr }
+}

package/src/platform/process/tmux.ts

@@ -0,0 +1,60 @@
+export interface TmuxPane {
+  paneId: string
+  close: () => Promise<void>
+}
+
+/** Check if current process is running inside a tmux session. */
+export function isInsideTmux(): boolean {
+  return Boolean(process.env.TMUX)
+}
+
+/**
+ * Spawns a background tmux split pane tailing the task log file.
+ * Uses `-d` to avoid stealing terminal focus.
+ * Uses positional parameters to prevent shell injection via title formatting.
+ */
+export async function spawnTaskPane(logPath: string, title?: string): Promise<TmuxPane | null> {
+  if (!isInsideTmux()) return null
+  try {
+    const args = title
+      ? [
+          "tmux",
+          "split-window",
+          "-d",
+          "-P",
+          "-F",
+          "#{pane_id}",
+          "bash",
+          "-c",
+          'printf "=== [%s] ===\\n" "$1" && exec tail -f "$2"',
+          "_",
+          title,
+          logPath,
+        ]
+      : ["tmux", "split-window", "-d", "-P", "-F", "#{pane_id}", "tail", "-f", logPath]
+
+    const proc = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" })
+    const [stdout, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+    if (code !== 0) return null
+
+    const paneId = stdout.trim()
+    if (!paneId.startsWith("%")) return null
+
+    return {
+      paneId,
+      close: async () => {
+        try {
+          const killProc = Bun.spawn(["tmux", "kill-pane", "-t", paneId], {
+            stdout: "ignore",
+            stderr: "ignore",
+          })
+          await killProc.exited
+        } catch {
+          // Pane might have been manually closed by user
+        }
+      },
+    }
+  } catch {
+    return null
+  }
+}

package/src/platform/session/busy.ts

@@ -0,0 +1,33 @@
+import type { BusyTracker } from "../../core/types.ts"
+
+export type { BusyTracker } from "../../core/types.ts"
+
+/**
+ * Session busy tracking via `session.status` (doc-preferred; `session.idle` deprecated).
+ * Resilient to aborts, errors, and deletions so sessions do not deadlock in busy state.
+ */
+export function createBusyTracker(): BusyTracker {
+  const busy = new Set<string>()
+  return {
+    onEvent(event: unknown) {
+      if (!event || typeof event !== "object") return
+      const ev = event as { type?: unknown; properties?: unknown }
+      if (typeof ev.type !== "string") return
+
+      const p = (ev.properties ?? {}) as { sessionID?: string; status?: { type?: string } }
+      if (!p.sessionID) return
+
+      if (ev.type === "session.status") {
+        p.status?.type === "idle" ? busy.delete(p.sessionID) : busy.add(p.sessionID)
+      } else if (
+        ev.type === "session.idle" ||
+        ev.type === "session.deleted" ||
+        ev.type === "session.error" ||
+        ev.type === "session.aborted"
+      ) {
+        busy.delete(p.sessionID)
+      }
+    },
+    isBusy: (id) => (id ? busy.has(id) : false),
+  }
+}

package/src/platform/session/inject.ts

@@ -0,0 +1,82 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import { toast } from "./notify.ts"
+
+export { toast, type ToastVariant } from "./notify.ts"
+
+type Client = PluginInput["client"]
+export type ModelRef = { providerID: string; modelID: string }
+export type SessionContext = {
+  model?: ModelRef
+  agent?: string
+}
+
+export interface InjectOptions {
+  noReply?: boolean
+}
+
+/**
+ * Session's active context = model of last assistant message and most recent agent name.
+ * Without model, promptAsync falls back to config default model -> injected turns
+ * run on the wrong model (and pile up QUEUED behind a hung default).
+ * Preserving agent ensures turns continue under the active persona.
+ */
+export async function sessionContext(client: Client, sessionID: string): Promise<SessionContext> {
+  try {
+    const res = await client.session.messages({ path: { id: sessionID } })
+    const msgs = res.data ?? []
+    let model: ModelRef | undefined
+    let agent: string | undefined
+
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const info = msgs[i]?.info as
+        { role?: string; modelID?: string; providerID?: string; agent?: string } | undefined
+      if (!model && info?.role === "assistant" && info.modelID && info.providerID) {
+        model = { providerID: info.providerID, modelID: info.modelID }
+      }
+      if (!agent && info?.agent) {
+        agent = info.agent
+      }
+      if (model && agent) break
+    }
+    return { model, agent }
+  } catch (e) {
+    console.warn(`[overclock] sessionContext lookup failed (${sessionID}): ${e}`)
+    return {}
+  }
+}
+
+/**
+ * Session's active model = model of last assistant message.
+ */
+export async function sessionModel(client: Client, sessionID: string): Promise<ModelRef | undefined> {
+  const ctx = await sessionContext(client, sessionID)
+  return ctx.model
+}
+
+/**
+ * Re-entry: push text into session as user prompt, on the session's own model and agent.
+ * promptAsync = fire-and-forget, server queues if busy. Failure -> warn, never throw.
+ */
+export async function inject(
+  client: Client,
+  sessionID: string,
+  text: string,
+  options?: InjectOptions,
+): Promise<boolean> {
+  try {
+    const ctx = await sessionContext(client, sessionID)
+    await client.session.promptAsync({
+      path: { id: sessionID },
+      body: {
+        parts: [{ type: "text", text }],
+        ...(ctx.model ? { model: ctx.model } : {}),
+        ...(ctx.agent ? { agent: ctx.agent } : {}),
+        ...(options?.noReply ? { noReply: true } : {}),
+      },
+    })
+    return true
+  } catch (e) {
+    console.warn(`[overclock] inject failed (session ${sessionID}): ${e}`)
+    return false
+  }
+}

package/src/platform/session/notify.ts

@@ -0,0 +1,20 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+
+type Client = PluginInput["client"]
+
+export type ToastVariant = "info" | "success" | "warning" | "error"
+
+/**
+ * TUI toast notification, best-effort (swallows errors in headless/no-TUI environments).
+ */
+export async function toast(
+  client: Client,
+  message: string,
+  variant: ToastVariant = "info",
+): Promise<void> {
+  try {
+    await client.tui.showToast({ body: { message, variant } })
+  } catch {
+    // no TUI attached or client lacks tui surface
+  }
+}

package/src/platform/storage/state.ts

@@ -0,0 +1,77 @@
+import { mkdir } from "node:fs/promises"
+import { shellQuote } from "../process/exec.ts"
+
+export { shellQuote }
+
+/** State root: <project>/.opencode/overclock/[sub]. Pure -- creates nothing. */
+export function stateDir(directory: string, sub?: string): string {
+  return `${directory}/.opencode/overclock${sub ? `/${sub}` : ""}`
+}
+
+/** State root: <project>/.opencode/overclock/[sub]. Creates if missing. */
+export async function ensureStateDir(directory: string, sub?: string): Promise<string> {
+  const dir = stateDir(directory, sub)
+  await mkdir(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * True once per project, then never again. Marker lives beside the other state, so
+ * deleting .opencode/overclock/ re-arms the first-run notice.
+ */
+export async function firstRun(directory: string): Promise<boolean> {
+  const dir = await ensureStateDir(directory)
+  const marker = Bun.file(`${dir}/.installed`)
+  if (await marker.exists()) return false
+  await Bun.write(marker, new Date().toISOString())
+  return true
+}
+
+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
+  }
+}
+
+/**
+ * Serializes the value formatted with 2 spaces and writes to the destination path.
+ */
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await Bun.write(path, JSON.stringify(value, null, 2))
+}
+
+/** A typed state file accessor. */
+export interface Store<T> {
+  readonly file: string
+  path(directory: string): string
+  read(directory: string): Promise<T>
+  readMaybe(directory: string): Promise<T | undefined>
+  write(directory: string, value: T): Promise<void>
+}
+
+/** Factory for typed state file stores. */
+export function defineStore<T>(file: string, fallback: () => T): Store<T> {
+  const path = (directory: string) => `${stateDir(directory)}/${file}`
+  return {
+    file,
+    path,
+    read: (directory) => readJson<T>(path(directory), fallback()),
+    readMaybe: async (directory) => {
+      const target = path(directory)
+      try {
+        if (!(await Bun.file(target).exists())) return undefined
+      } catch {
+        return undefined
+      }
+      return readJson<T>(target, fallback())
+    },
+    write: async (directory, value) => {
+      await ensureStateDir(directory)
+      await writeJson(path(directory), value)
+    },
+  }
+}

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"