opencode-overclock 0.3.0 → 0.4.0

package/src/v2/loader.ts

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview OpenCode V2 Plugin Resolution and Loading
+ *
+ * Provides resolution, dynamic importation, and execution of V2 plugins
+ * on top of a synthetic V2 `PluginContext`.
+ *
+ * Supported plugin formats:
+ *  - Direct instances: `{ id, setup(context) }` or `{ id, effect(context) }`
+ *  - File paths: `./plugins/custom.ts`, `/absolute/path/plugin.js`, `file:///...`
+ *  - Npm packages: bare module specifiers resolved via node/bun module resolution
+ *  - Tuples: `[specifier, pluginOptions]` for supplying per-plugin options
+ */
+
+import { resolve, isAbsolute } from "path"
+import { pathToFileURL, fileURLToPath } from "url"
+import type { Plugin as V2Plugin, PluginOptions } from "@opencode-ai/plugin/v2/promise"
+import type { Disposer, V2ContextHandle } from "./context.ts"
+
+/**
+ * Union of accepted V2 plugin declaration formats:
+ *  - String specifier: file path or package name
+ *  - Tuple: `[specifier, options]`
+ *  - Plugin instance conforming to V2 interface
+ *  - Wrapper object: `{ plugin, options }`
+ */
+export type V2PluginSpec =
+  string | [string, PluginOptions] | V2Plugin | { plugin: V2Plugin; options?: PluginOptions }
+
+/**
+ * Validates whether an unknown value conforms to the OpenCode V2 plugin contract:
+ * requires non-empty string `id`, and either an async `setup` method or an `effect` function.
+ */
+export function isV2Plugin(value: unknown): value is V2Plugin {
+  if (!value || typeof value !== "object") return false
+  const p = value as Record<string, unknown>
+  if (typeof p.id !== "string" || !p.id.trim()) return false
+  return typeof p.setup === "function" || typeof (p as any).effect === "function"
+}
+
+/**
+ * Resolves a file path or URL specifier against the workspace directory.
+ * Preserves bare package names for standard Node/Bun module resolution.
+ */
+export function resolvePluginPath(spec: string, baseDir: string): string {
+  if (spec.startsWith("file://")) return fileURLToPath(spec)
+  if (isAbsolute(spec)) return spec
+  if (spec.startsWith(".")) return resolve(baseDir, spec)
+  return spec
+}
+
+/**
+ * Resolves a V2 plugin specifier into a concrete V2Plugin object and its associated options.
+ * Dynamically imports file paths or npm packages if necessary.
+ */
+export async function resolveV2Plugin(
+  spec: V2PluginSpec,
+  baseDir: string,
+): Promise<{ plugin: V2Plugin; options: PluginOptions } | null> {
+  // Case 1: Already an instantiated V2Plugin object
+  if (isV2Plugin(spec)) {
+    return { plugin: spec, options: {} }
+  }
+
+  // Case 2: Wrapped { plugin, options } object
+  if (
+    typeof spec === "object" &&
+    spec !== null &&
+    "plugin" in spec &&
+    isV2Plugin((spec as any).plugin)
+  ) {
+    return {
+      plugin: (spec as any).plugin,
+      options: (spec as any).options ?? {},
+    }
+  }
+
+  // Case 3: Specifier string or [string, options] tuple
+  let moduleSpec: string
+  let options: PluginOptions = {}
+
+  if (Array.isArray(spec)) {
+    moduleSpec = spec[0]
+    options = spec[1] ?? {}
+  } else if (typeof spec === "string") {
+    moduleSpec = spec
+  } else {
+    return null
+  }
+
+  const resolved = resolvePluginPath(moduleSpec, baseDir)
+  const importTarget = resolved.startsWith("/") ? pathToFileURL(resolved).href : resolved
+
+  try {
+    const mod = await import(importTarget)
+    const candidate = mod?.default ?? mod
+    if (isV2Plugin(candidate)) {
+      return { plugin: candidate, options }
+    }
+    // Check named exports for a V2 plugin definition
+    for (const val of Object.values(mod)) {
+      if (isV2Plugin(val)) {
+        return { plugin: val, options }
+      }
+    }
+    console.warn(
+      `[overclock] v2: module '${moduleSpec}' does not export a valid V2 plugin ({ id, setup/effect })`,
+    )
+    return null
+  } catch (e) {
+    console.warn(`[overclock] v2: failed to import plugin '${moduleSpec}': ${e}`)
+    return null
+  }
+}
+
+/**
+ * Loads and initializes a V2 plugin against the synthetic context.
+ * Creates a scoped context, handles Effect vs Promise lifecycle, and tracks disposers.
+ * Returns the plugin ID if loaded successfully, or null on error.
+ */
+export async function loadV2Plugin(
+  spec: V2PluginSpec,
+  baseDir: string,
+  handle: V2ContextHandle,
+): Promise<string | null> {
+  const resolved = await resolveV2Plugin(spec, baseDir)
+  if (!resolved) return null
+
+  const { plugin, options } = resolved
+  const pluginDisposers = new Set<Disposer>()
+  const scopedCtx = handle.scopedContext(options, pluginDisposers)
+
+  handle.state.activePlugins.set(plugin.id, {
+    plugin,
+    disposers: pluginDisposers,
+  })
+
+  try {
+    if (typeof (plugin as any).effect === "function") {
+      const { runPromise } = await import("effect/Effect")
+      await runPromise((plugin as any).effect(scopedCtx))
+    } else if (typeof plugin.setup === "function") {
+      await plugin.setup(scopedCtx)
+    }
+    return plugin.id
+  } catch (e) {
+    console.warn(`[overclock] v2: plugin '${plugin.id}' failed during setup: ${e}`)
+    await handle.context.plugin.remove(plugin.id)
+    return null
+  }
+}

package/src/buddy/reactions.ts

@@ -1,41 +0,0 @@
-import type { SpriteState } from "./sprites.ts"
-
-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: ["done!", "all set.", "ship it.", "*stretch*"], state: "idle" },
-  error: { lines: ["uh oh.", "*winces*", "yikes."], state: "alarmed" },
-  permission: { lines: ["can we?", "*peeks*", "please?"], state: "curious" },
-  question: { lines: ["your call.", "hmm?", "*head tilt*"], state: "curious" },
-  pet: { lines: ["<3", "*purrs*", "hi!!", "missed you."], 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
-    },
-  }
-}

package/src/buddy/types.ts

@@ -1,30 +0,0 @@
-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
-}
-
-/** Persisted in TUI kv. Rolled once at hatch, then stable for the life of the install. */
-export interface Companion {
-  species: Species
-  rarity: Rarity
-  name: string
-  stats: CompanionStats
-  hatchedAt: number
-}

package/src/config.ts

@@ -1,19 +0,0 @@
-import type { OverclockConfig } from "./types.ts"
-
-const CONFIG_PATHS = [".opencode/overclock.json", "overclock.json"]
-
-/** Load plugin config from project dir. Missing file -> {} (all defaults). */
-export async function loadConfig(directory: string): Promise<OverclockConfig> {
-  for (const rel of CONFIG_PATHS) {
-    const file = Bun.file(`${directory}/${rel}`)
-    if (await file.exists()) {
-      try {
-        return (await file.json()) as OverclockConfig
-      } catch (e) {
-        console.warn(`[overclock] bad config ${rel}: ${e}`)
-        return {}
-      }
-    }
-  }
-  return {}
-}

package/src/features/checkpoints.ts

@@ -1,128 +0,0 @@
-import { tool, type PluginInput } from "@opencode-ai/plugin"
-import type { FeatureModule } from "../types.ts"
-
-const z = tool.schema
-
-type Client = PluginInput["client"]
-
-interface MessagePart {
-  type: string
-  text?: string
-}
-
-interface MessageEntry {
-  info: {
-    id: string
-    role: string
-    time?: { created?: number }
-  }
-  parts: MessagePart[]
-}
-
-const collapse = (s: string) => s.replace(/\s+/g, " ").trim()
-
-/** Exported for tests: revert/unrevert/list core, decoupled from plugin ctx. */
-export interface Checkpoints {
-  list(sessionID: string): Promise<string>
-  revert(sessionID: string, messageID: string): Promise<string>
-  restore(sessionID: string): Promise<string>
-}
-
-export function createCheckpoints(client: Client): Checkpoints {
-  async function list(sessionID: string): Promise<string> {
-    try {
-      const res = await client.session.messages({ path: { id: sessionID } })
-      const msgs = ((res.data ?? []) as MessageEntry[]).filter((m) => m.info.role === "user")
-      if (!msgs.length) return "no checkpoints"
-      return msgs
-        .map((m) => {
-          const time = m.info.time?.created
-            ? new Date(m.info.time.created).toISOString()
-            : "unknown time"
-          const text = m.parts.find((p) => p.type === "text" && typeof p.text === "string")?.text ?? ""
-          const preview = collapse(text).slice(0, 60)
-          return `${m.info.id} ${time} ${preview}`
-        })
-        .join("\n")
-    } catch (e) {
-      console.warn(`[overclock] checkpoints: list failed (session ${sessionID}): ${e}`)
-      return `error listing checkpoints: ${e}`
-    }
-  }
-
-  async function revert(sessionID: string, messageID: string): Promise<string> {
-    try {
-      await client.session.revert({ path: { id: sessionID }, body: { messageID } })
-      return `reverted session ${sessionID} to before message ${messageID}`
-    } catch (e) {
-      console.warn(
-        `[overclock] checkpoints: revert failed (session ${sessionID}, message ${messageID}): ${e}`,
-      )
-      return `error reverting checkpoint: ${e}`
-    }
-  }
-
-  async function restore(sessionID: string): Promise<string> {
-    try {
-      await client.session.unrevert({ path: { id: sessionID } })
-      return `restored session ${sessionID} to latest (undo revert)`
-    } catch (e) {
-      console.warn(`[overclock] checkpoints: restore failed (session ${sessionID}): ${e}`)
-      return `error restoring checkpoint: ${e}`
-    }
-  }
-
-  return { list, revert, restore }
-}
-
-/**
- * Shadow-git revert tools (map doc: "Checkpoints — none gap"). Wraps native
- * session.revert/unrevert around each user message as a revert point.
- */
-export const checkpoints: FeatureModule = {
-  name: "checkpoints",
-  tools: ["checkpoint_list", "checkpoint_revert", "checkpoint_restore"],
-  defaultEnabled: true,
-  requires: ["session.revert", "session.unrevert", "session.messages"],
-  async init(ctx) {
-    const core = createCheckpoints(ctx.client)
-
-    return {
-      tool: {
-        checkpoint_list: tool({
-          description:
-            "List user messages of a session as revert points: messageID, time, first 60 chars. Most recent last.",
-          args: { sessionID: z.string().optional().describe("default: current session") },
-          async execute(args, tctx) {
-            return core.list(args.sessionID ?? tctx.sessionID)
-          },
-        }),
-        checkpoint_revert: tool({
-          description:
-            "Revert session files + conversation back to before the given message (shadow-git, reversible via checkpoint_restore). Requires user permission.",
-          args: {
-            messageID: z.string(),
-            sessionID: z.string().optional().describe("default: current session"),
-          },
-          async execute(args, tctx) {
-            const sessionID = args.sessionID ?? tctx.sessionID
-            await tctx.ask({
-              permission: "checkpoint_revert",
-              patterns: [args.messageID],
-              always: [],
-              metadata: { sessionID, messageID: args.messageID },
-            })
-            return core.revert(sessionID, args.messageID)
-          },
-        }),
-        checkpoint_restore: tool({
-          description: "Undo the most recent checkpoint_revert for a session.",
-          args: { sessionID: z.string().optional().describe("default: current session") },
-          async execute(args, tctx) {
-            return core.restore(args.sessionID ?? tctx.sessionID)
-          },
-        }),
-      },
-    }
-  },
-}

package/src/features/sandbox.ts

@@ -1,104 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import type { FeatureModule } from "../types.ts"
-import { shellQuote } from "../lib/state.ts"
-
-const z = tool.schema
-
-export interface SandboxPolicy {
-  project: string
-  net: boolean
-}
-
-/** Pure: wrap shell cmd in bwrap. / ro, project + /tmp rw, net per policy. */
-export function wrapCommand(cmd: string, policy: SandboxPolicy): string {
-  const args = [
-    "bwrap",
-    "--ro-bind / /",
-    "--dev /dev",
-    "--proc /proc",
-    `--bind ${shellQuote(policy.project)} ${shellQuote(policy.project)}`,
-    "--bind /tmp /tmp",
-    "--die-with-parent",
-  ]
-  if (!policy.net) args.push("--unshare-net")
-  args.push("bash -c", shellQuote(cmd))
-  return args.join(" ")
-}
-
-/** Functional probe: bwrap present AND userns allowed (WSL2/distros vary). */
-export function probeBwrap(): boolean {
-  try {
-    const res = Bun.spawnSync([
-      "bwrap",
-      "--ro-bind",
-      "/",
-      "/",
-      "--dev",
-      "/dev",
-      "--proc",
-      "/proc",
-      "true",
-    ])
-    return res.exitCode === 0
-  } catch {
-    return false
-  }
-}
-
-/**
- * Sandboxed bash via bubblewrap. Rewrites every bash tool call.
- * Off by default. No bwrap -> warn once, passthrough.
- */
-export const sandbox: FeatureModule = {
-  name: "sandbox",
-  tools: ["bash_unsandboxed"],
-  options: { net: "boolean" },
-  defaultEnabled: false,
-  async init(ctx, options) {
-    const policy: SandboxPolicy = {
-      project: ctx.directory,
-      net: options.net !== false,
-    }
-    const available = probeBwrap()
-    if (!available) console.warn("[overclock] sandbox: bwrap unavailable/blocked -> passthrough")
-
-    return {
-      "tool.execute.before": async (input, output) => {
-        if (!available || input.tool !== "bash") return
-        const cmd = (output.args as { command?: string }).command
-        if (typeof cmd !== "string") return
-        output.args.command = wrapCommand(cmd, policy)
-      },
-      tool: {
-        bash_unsandboxed: tool({
-          description:
-            "Run a shell command OUTSIDE the sandbox (full FS write access). Requires user permission. Use only when the sandbox blocks a legitimate operation.",
-          args: {
-            command: z.string(),
-            cwd: z.string().optional(),
-          },
-          async execute(args, tctx) {
-            await tctx.ask({
-              permission: "bash_unsandboxed",
-              patterns: [args.command],
-              always: [],
-              metadata: { command: args.command },
-            })
-            const proc = Bun.spawn(["bash", "-c", args.command], {
-              cwd: args.cwd ?? tctx.directory,
-              stdout: "pipe",
-              stderr: "pipe",
-            })
-            const [out, err, code] = await Promise.all([
-              new Response(proc.stdout).text(),
-              new Response(proc.stderr).text(),
-              proc.exited,
-            ])
-            const text = (out + (err ? `\nstderr:\n${err}` : "")).slice(0, 30_000)
-            return `exit ${code}\n${text}`
-          },
-        }),
-      },
-    }
-  },
-}

package/src/validate.ts

@@ -1,197 +0,0 @@
-import type { ConfigIssue, FeatureModule, OptionType } from "./types.ts"
-import type { ToolPolicy } from "./tools.ts"
-
-export type { ConfigIssue }
-
-/** Levenshtein, capped -- only used to turn a typo into a "did you mean". */
-function distance(a: string, b: string): number {
-  const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
-  const cur = new Array<number>(b.length + 1)
-  for (let i = 1; i <= a.length; i++) {
-    cur[0] = i
-    for (let j = 1; j <= b.length; j++) {
-      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
-    }
-    prev.splice(0, prev.length, ...cur)
-  }
-  return prev[b.length]
-}
-
-/** Closest known name within edit distance 2, else undefined. */
-function nearest(input: string, known: readonly string[]): string | undefined {
-  let best: string | undefined
-  let bestD = 3
-  for (const k of known) {
-    const d = distance(input.toLowerCase(), k.toLowerCase())
-    if (d < bestD) {
-      bestD = d
-      best = k
-    }
-  }
-  return best
-}
-
-function unknownKey(input: string, known: readonly string[], what: string): string {
-  const guess = nearest(input, known)
-  if (guess) return `unknown ${what} "${input}" -- did you mean "${guess}"?`
-  return `unknown ${what} "${input}". Known: ${known.join(", ")}`
-}
-
-function typeOf(v: unknown): OptionType | "null" {
-  if (v === null) return "null"
-  if (Array.isArray(v)) return "array"
-  const t = typeof v
-  if (t === "boolean" || t === "number" || t === "string" || t === "object") return t
-  return "object"
-}
-
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v)
-}
-
-/**
- * Check the `toolNames` remap. A rename that silently does nothing is the worst outcome
- * here: the proxy keeps rejecting the tool and the config looks correct. So an unknown
- * source name is an issue, and two sources aiming at one target is an issue -- the merge
- * would keep only the last.
- */
-function validateToolNames(toolNames: unknown, features: readonly FeatureModule[]): ConfigIssue[] {
-  if (toolNames === undefined) return []
-  if (!isPlainObject(toolNames)) {
-    return [{ path: "toolNames", message: `"toolNames" must be an object, got ${typeOf(toolNames)}` }]
-  }
-
-  const issues: ConfigIssue[] = []
-  const declared = features.flatMap((f) => f.tools ?? [])
-  const targets = new Map<string, string>()
-
-  for (const [from, to] of Object.entries(toolNames)) {
-    if (!declared.includes(from)) {
-      issues.push({ path: `toolNames.${from}`, message: unknownKey(from, declared, "tool") })
-      continue
-    }
-    if (typeof to !== "string" || to.trim() === "") {
-      issues.push({
-        path: `toolNames.${from}`,
-        message: `must be a non-empty string, got ${typeOf(to)}`,
-      })
-      continue
-    }
-    const prior = targets.get(to)
-    if (prior) {
-      issues.push({
-        path: `toolNames.${from}`,
-        message: `"${to}" is already the target of "${prior}" -- only one would survive the merge`,
-      })
-      continue
-    }
-    targets.set(to, from)
-  }
-
-  return issues
-}
-
-/**
- * Check overclock.json against the feature registry.
- *
- * Exists because an unrecognised key is otherwise a silent no-op: `killOnExist: true`
- * reads as "option not set", the feature runs with defaults, and nothing complains.
- * Returns every issue found -- callers warn, never throw. A bad config degrades to
- * defaults rather than taking the plugin down.
- */
-export function validateConfig(config: unknown, features: readonly FeatureModule[]): ConfigIssue[] {
-  const issues: ConfigIssue[] = []
-  if (!isPlainObject(config)) {
-    return [{ path: "", message: `config must be an object, got ${typeOf(config)}` }]
-  }
-
-  const TOP = ["features", "toolNames", "toolAllowlist"]
-  for (const key of Object.keys(config)) {
-    if (!TOP.includes(key)) issues.push({ path: key, message: unknownKey(key, TOP, "top-level key") })
-  }
-
-  issues.push(...validateToolNames(config.toolNames, features))
-
-  const { features: featuresCfg } = config
-  if (featuresCfg === undefined) return issues
-  if (!isPlainObject(featuresCfg)) {
-    issues.push({
-      path: "features",
-      message: `"features" must be an object, got ${typeOf(featuresCfg)}`,
-    })
-    return issues
-  }
-
-  const names = features.map((f) => f.name)
-  for (const [name, setting] of Object.entries(featuresCfg)) {
-    const feature = features.find((f) => f.name === name)
-    if (!feature) {
-      issues.push({ path: `features.${name}`, message: unknownKey(name, names, "feature") })
-      continue
-    }
-    if (typeof setting === "boolean") continue
-    if (!isPlainObject(setting)) {
-      issues.push({
-        path: `features.${name}`,
-        message: `must be true, false, or an options object -- got ${typeOf(setting)}`,
-      })
-      continue
-    }
-
-    const schema = feature.options ?? {}
-    const optionNames = Object.keys(schema)
-    for (const [key, value] of Object.entries(setting)) {
-      const expected = schema[key]
-      if (!expected) {
-        issues.push({
-          path: `features.${name}.${key}`,
-          message: optionNames.length
-            ? unknownKey(key, optionNames, "option")
-            : `"${name}" takes no options, got "${key}"`,
-        })
-        continue
-      }
-      const actual = typeOf(value)
-      if (actual !== expected) {
-        issues.push({
-          path: `features.${name}.${key}`,
-          message: `expected ${expected}, got ${actual}`,
-        })
-      }
-    }
-  }
-
-  return issues
-}
-
-/**
- * One-line inventory of what this plugin just added to the session.
- *
- * Not about context cost -- the full tool surface is only ~800 tokens. It is about
- * capability: installing overclock hands 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 = { rename: {}, withheld: new Set() },
-): 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
-}