opencode-overclock 0.3.0 → 0.4.0

package/src/core/types.ts

@@ -0,0 +1,164 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin"
+import type { PluginContext, Plugin as V2Plugin, PluginOptions } from "@opencode-ai/plugin/v2/promise"
+
+/**
+ * Tracks live session busy/idle state derived from the host event bus.
+ */
+export interface BusyTracker {
+  onEvent(event: unknown): void
+  isBusy(sessionID?: string): boolean
+}
+
+/**
+ * Singletons built once by the entry and handed to every module.
+ * `busy` is derived from the event bus and requires 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
+}
+
+/** A problem found in plugin configuration. */
+export interface ConfigIssue {
+  path: string
+  message: string
+}
+
+/** Policy for renaming tools and withholding tools not permitted by allowlists. */
+export interface ToolPolicy {
+  /** declared name -> model-visible name */
+  readonly rename: Record<string, string>
+  /** declared names withheld from the model entirely (not in allowlist) */
+  readonly withheld: Set<string>
+}
+
+export const EMPTY_POLICY: ToolPolicy = { rename: {}, withheld: new Set() }
+
+export interface TasksOptions {
+  killOnExit?: boolean
+  stallDetection?: boolean
+  stallThresholdMs?: number
+  stallCheckIntervalMs?: number
+  tmux?: boolean
+  [key: string]: unknown
+}
+
+export interface SchedOptions {
+  skipIfBusy?: boolean
+  [key: string]: unknown
+}
+
+export interface GuardHookConfig {
+  name: string
+  tools?: string[]
+  pathFilter?: string
+  run: string
+  mode?: "inject" | "append"
+  debounceMs?: number
+  timeoutMs?: number
+  onSuccess?: "silent" | "notify"
+  maxDeferMs?: number
+  [key: string]: unknown
+}
+
+export interface GuardOptions {
+  hooks?: GuardHookConfig[]
+  recipes?: string[]
+  auto?: boolean
+  editRecovery?: boolean
+  [key: string]: unknown
+}
+
+export interface RecoveryOptions {
+  autoResume?: boolean
+  maxAttempts?: number
+  cooldownMs?: number
+  [key: string]: unknown
+}
+
+export interface TruncatorOptions {
+  tools?: string[]
+  headLines?: number
+  tailLines?: number
+  maxChars?: number
+  [key: string]: unknown
+}
+
+/**
+ * Accepted formats for declaring V2 plugins:
+ * file path, npm package, tuple with options, or plugin object.
+ */
+export type V2PluginSpec =
+  string | [string, PluginOptions] | V2Plugin | { plugin: V2Plugin; options?: PluginOptions }
+
+/**
+ * Plugin options passed directly from opencode.json:
+ * { "plugin": [ ["opencode-overclock", { "guard": { ... } }] ] }
+ */
+export interface OverclockOptions {
+  tasks?: boolean | TasksOptions
+  sched?: boolean | SchedOptions
+  guard?: boolean | GuardOptions
+  usage?: boolean | { debounceMs?: number }
+  buddy?: boolean
+  recovery?: boolean | RecoveryOptions
+  truncator?: boolean | TruncatorOptions
+  /** Legacy or grouped feature options: { features: { guard: ... } } */
+  features?: Record<string, boolean | Record<string, unknown>>
+  /** Model-visible tool ids: declared name -> replacement */
+  toolNames?: Record<string, string>
+  /** Whitelist of tool names the model may be offered */
+  toolAllowlist?: string[] | string
+  /**
+   * V2 plugins to host and run alongside V1:
+   * file paths (e.g. "./plugins/custom.ts"), npm specifiers, plugin objects, or [spec, options] tuples.
+   */
+  plugins?: V2PluginSpec[]
+  [key: string]: unknown
+}
+
+/**
+ * One feature = one module.
+ * Can participate in V1 hook composition (`init`), V2 domain transforms (`setup`), or both.
+ */
+export interface FeatureModule {
+  name: string
+  /** on by default? */
+  defaultEnabled: boolean
+  /** SDK client surfaces (dot-paths) the module needs in V1. Missing -> module skipped + warn. */
+  requires?: string[]
+  /** Tool names registered. Declared, not derived -- feeds the first-run summary. */
+  tools?: string[]
+  /** V1 initialization: returns partial Hooks composed in registry order. */
+  init(ctx: PluginInput, options: Record<string, unknown>, shared: SharedDeps): Promise<Partial<Hooks>>
+  /** V2 setup: receives V2 PluginContext to register domain transforms. */
+  setup?(context: PluginContext, options: Record<string, unknown>): Promise<void> | void
+}
+
+/**
+ * Definition structure for a dual-target plugin (V1 hooks + V2 setup).
+ */
+export interface HybridPluginDefinition<TOptions = Record<string, unknown>> {
+  readonly id: string
+  /** V1 lifecycle: tools, execution interception, event bus hooks */
+  readonly server?: (input: PluginInput, options?: TOptions) => Promise<Partial<Hooks>>
+  /** V2 lifecycle: domain transforms (agents, commands, catalog, aisdk) */
+  readonly setup?: (context: PluginContext, options?: TOptions) => Promise<void> | void
+}
+
+/**
+ * Plugin instance callable directly in V1 while presenting V2 interface object.
+ */
+export interface HybridPlugin<TOptions = Record<string, unknown>> extends V2Plugin {
+  (input: PluginInput, options?: TOptions): Promise<Hooks>
+  readonly id: string
+  readonly server: (input: PluginInput, options?: TOptions) => Promise<Hooks>
+  readonly setup: (context: PluginContext) => Promise<void>
+}

package/src/features/buddy.ts

@@ -3,8 +3,7 @@ import type { FeatureModule } from "../types.ts"
 /**
  * Buddy is a TUI-surface feature (src/buddy/, wired in src/tui.ts): an ASCII pet
  * beside the prompt. This server module registers no hooks or tools -- it exists
- * so `features.buddy` validates in overclock.json (one config file toggles both
- * surfaces) and the first-run summary mentions it.
+ * so buddy appears in the first-run capability summary.
  */
 export const buddy: FeatureModule = {
   name: "buddy",

package/src/features/guard.ts

@@ -1,10 +1,12 @@
 import type { FeatureModule } from "../types.ts"
 import { inject, toast } from "../lib/inject.ts"
+import { execBash } from "../lib/exec.ts"
 
 export interface GuardHook {
   name: string
   tools: string[]
   pathFilter?: string
+  glob?: Bun.Glob
   run: string
   mode: "inject" | "append"
   debounceMs: number
@@ -14,6 +16,102 @@ export interface GuardHook {
   maxDeferMs: number
 }
 
+export const EDIT_ERROR_PATTERNS = [
+  "oldstring and newstring must be different",
+  "oldstring not found",
+  "found multiple matches for oldstring",
+]
+
+export const EDIT_RECOVERY_HINT =
+  "\n\n[edit recovery hint]\nThe edit failed due to a content mismatch. Use the `read` tool to inspect the latest file state around the target lines before retrying the edit."
+
+export function checkEditFailure(tool: string, outputText: string): string | null {
+  if (tool.toLowerCase() !== "edit") return null
+  const lower = outputText.toLowerCase()
+  if (EDIT_ERROR_PATTERNS.some((p) => lower.includes(p))) {
+    return EDIT_RECOVERY_HINT
+  }
+  return null
+}
+
+export const GUARD_RECIPES: Record<string, Omit<GuardHook, "glob">> = {
+  tsc: {
+    name: "tsc",
+    tools: ["edit", "write"],
+    pathFilter: "**/*.{ts,tsx}",
+    run: "bun x tsc --noEmit || npx tsc --noEmit",
+    mode: "inject",
+    debounceMs: 2000,
+    timeoutMs: 60000,
+    onSuccess: "silent",
+    maxDeferMs: 300000,
+  },
+  eslint: {
+    name: "eslint",
+    tools: ["edit", "write"],
+    pathFilter: "**/*.{js,jsx,ts,tsx}",
+    run: "bun x eslint . || npx eslint .",
+    mode: "inject",
+    debounceMs: 2000,
+    timeoutMs: 60000,
+    onSuccess: "silent",
+    maxDeferMs: 300000,
+  },
+  ruff: {
+    name: "ruff",
+    tools: ["edit", "write"],
+    pathFilter: "**/*.py",
+    run: "ruff check .",
+    mode: "inject",
+    debounceMs: 2000,
+    timeoutMs: 60000,
+    onSuccess: "silent",
+    maxDeferMs: 300000,
+  },
+  cargo: {
+    name: "cargo",
+    tools: ["edit", "write"],
+    pathFilter: "**/*.rs",
+    run: "cargo check",
+    mode: "inject",
+    debounceMs: 2000,
+    timeoutMs: 60000,
+    onSuccess: "silent",
+    maxDeferMs: 300000,
+  },
+  go: {
+    name: "go",
+    tools: ["edit", "write"],
+    pathFilter: "**/*.go",
+    run: "go test ./...",
+    mode: "inject",
+    debounceMs: 2000,
+    timeoutMs: 60000,
+    onSuccess: "silent",
+    maxDeferMs: 300000,
+  },
+}
+
+export async function detectRecipes(directory: string): Promise<GuardHook[]> {
+  const detected: GuardHook[] = []
+  if (await Bun.file(`${directory}/tsconfig.json`).exists()) {
+    detected.push({ ...GUARD_RECIPES.tsc, glob: new Bun.Glob("**/*.{ts,tsx}") })
+  }
+  if (await Bun.file(`${directory}/Cargo.toml`).exists()) {
+    detected.push({ ...GUARD_RECIPES.cargo, glob: new Bun.Glob("**/*.rs") })
+  }
+  if (
+    (await Bun.file(`${directory}/pyproject.toml`).exists()) ||
+    (await Bun.file(`${directory}/ruff.toml`).exists())
+  ) {
+    detected.push({ ...GUARD_RECIPES.ruff, glob: new Bun.Glob("**/*.py") })
+  }
+  if (await Bun.file(`${directory}/go.mod`).exists()) {
+    detected.push({ ...GUARD_RECIPES.go, glob: new Bun.Glob("**/*.go") })
+  }
+  return detected
+}
+
 /** options.hooks -> validated GuardHook[]. Invalid entries -> console.warn, skipped, never throw. */
 export function parseHooks(raw: unknown): GuardHook[] {
   if (!Array.isArray(raw)) return []
@@ -26,10 +124,12 @@ export function parseHooks(raw: unknown): GuardHook[] {
       console.warn(`[overclock] guard: skipping invalid hook config: ${JSON.stringify(entry)}`)
       continue
     }
+    const pathFilter = typeof e.pathFilter === "string" ? e.pathFilter : undefined
     hooks.push({
       name: e.name,
       tools: e.tools as string[],
-      pathFilter: typeof e.pathFilter === "string" ? e.pathFilter : undefined,
+      pathFilter,
+      glob: pathFilter ? new Bun.Glob(pathFilter) : undefined,
       run: e.run,
       mode: e.mode === "append" ? "append" : "inject",
       debounceMs: typeof e.debounceMs === "number" ? e.debounceMs : 2000,
@@ -41,12 +141,22 @@ export function parseHooks(raw: unknown): GuardHook[] {
   return hooks
 }
 
-/** tools: exact match. pathFilter set + no filePath -> no match. */
-export function matchHook(hook: GuardHook, toolName: string, filePath: string | undefined): boolean {
-  if (!hook.tools.includes(toolName)) return false
+/** tools: exact match or mapped name. pathFilter set + no filePath -> no match. */
+export function matchHook(
+  hook: GuardHook,
+  toolName: string,
+  filePath: string | undefined,
+  resolveTool?: (name: string) => string,
+): boolean {
+  const matches = hook.tools.some((t) => {
+    if (t === toolName) return true
+    if (resolveTool && resolveTool(t) === toolName) return true
+    return false
+  })
+  if (!matches) return false
   if (!hook.pathFilter) return true
   if (typeof filePath !== "string") return false
-  return new Bun.Glob(hook.pathFilter).match(filePath)
+  return (hook.glob ?? new Bun.Glob(hook.pathFilter)).match(filePath)
 }
 
 /** `[guard "<name>" failed (exit <code>)]` + last 40 lines of combined stdout+stderr. */
@@ -69,16 +179,7 @@ async function runCommand(
   env: Record<string, string | undefined>,
   register?: (proc: Bun.Subprocess) => void,
 ): Promise<{ code: number | null; combined: string }> {
-  const proc = Bun.spawn(["bash", "-c", hook.run], { cwd, env, stdout: "pipe", stderr: "pipe" })
-  register?.(proc)
-  const killTimer = setTimeout(() => proc.kill("SIGTERM"), hook.timeoutMs)
-  const [out, err, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ])
-  clearTimeout(killTimer)
-  return { code, combined: out + err }
+  return execBash(hook.run, { cwd, env, timeoutMs: hook.timeoutMs, onSpawn: register })
 }
 
 interface HookState {
@@ -200,7 +301,17 @@ export function createGuardRunner(deps: GuardRunnerDeps): GuardRunner {
   function dispose(): void {
     for (const s of states.values()) {
       if (s.timer) clearTimeout(s.timer)
-      for (const p of s.procs) p.kill("SIGTERM")
+      for (const p of s.procs) {
+        try {
+          p.kill("SIGTERM")
+          const hard = setTimeout(() => {
+            try {
+              p.kill("SIGKILL")
+            } catch {}
+          }, 1000)
+          hard.unref?.()
+        } catch {}
+      }
     }
   }
 
@@ -218,7 +329,6 @@ export function createGuardRunner(deps: GuardRunnerDeps): GuardRunner {
 export const guard: FeatureModule = {
   name: "guard",
   tools: [],
-  options: { hooks: "array" },
   defaultEnabled: true,
   requires: ["session.promptAsync", "session.messages"],
   async init(ctx, options, shared) {
@@ -226,29 +336,57 @@ export const guard: FeatureModule = {
       console.warn(`[overclock] guard: options.hooks must be an array, got ${typeof options.hooks}`)
     }
     const hooks = parseHooks(options.hooks)
-    if (hooks.length === 0) return {}
+    if (Array.isArray(options.recipes)) {
+      for (const r of options.recipes) {
+        if (typeof r === "string" && GUARD_RECIPES[r]) {
+          const recipe = GUARD_RECIPES[r]
+          hooks.push({
+            ...recipe,
+            glob: recipe.pathFilter ? new Bun.Glob(recipe.pathFilter) : undefined,
+          })
+        }
+      }
+    }
+    if (options.auto === true) {
+      const autoHooks = await detectRecipes(ctx.directory)
+      hooks.push(...autoHooks)
+    }
 
-    const runner = createGuardRunner({
-      cwd: ctx.directory,
-      onInject: async (sessionID, payload) => {
-        await inject(ctx.client, sessionID, payload)
-      },
-      onNotify: async (hookName) => {
-        await toast(ctx.client, `guard "${hookName}" passed`, "success")
-      },
-      isBusy: (sessionID) => shared.busy.isBusy(sessionID),
-    })
+    const editRecovery =
+      options.editRecovery === true || (hooks.length > 0 && options.editRecovery !== false)
+    if (hooks.length === 0 && !editRecovery) return {}
+
+    const runner =
+      hooks.length > 0
+        ? createGuardRunner({
+            cwd: ctx.directory,
+            onInject: async (sessionID, payload) => {
+              await inject(ctx.client, sessionID, payload)
+            },
+            onNotify: async (hookName) => {
+              await toast(ctx.client, `guard "${hookName}" passed`, "success")
+            },
+            isBusy: (sessionID) => shared.busy.isBusy(sessionID),
+          })
+        : undefined
 
     return {
       dispose: async () => {
-        runner.dispose()
+        runner?.dispose()
       },
       "tool.execute.after": async (input, output) => {
+        if (editRecovery && typeof output.output === "string") {
+          const hint = checkEditFailure(input.tool, output.output)
+          if (hint) output.output += hint
+        }
+
+        if (!runner || hooks.length === 0) return
+
         const args = input.args as Record<string, unknown> | undefined
         const filePath = typeof args?.filePath === "string" ? args.filePath : undefined
 
         for (const hook of hooks) {
-          if (!matchHook(hook, input.tool, filePath)) continue
+          if (!matchHook(hook, input.tool, filePath, shared?.toolName)) continue
           if (hook.mode === "append") {
             const payload = await runner.runAppend(hook, input.tool, filePath)
             if (payload && typeof output.output === "string") output.output += payload

package/src/features/index.ts

@@ -1,11 +1,13 @@
 import type { FeatureModule } from "../types.ts"
 import { tasks } from "./tasks.ts"
 import { sched } from "./sched.ts"
-import { sandbox } from "./sandbox.ts"
 import { guard } from "./guard.ts"
 import { usage } from "./usage.ts"
-import { checkpoints } from "./checkpoints.ts"
 import { buddy } from "./buddy.ts"
+import { truncator } from "./truncator.ts"
+import { recovery } from "./recovery.ts"
 
-/** Registry, ordered. Order = hook composition order. */
-export const features: FeatureModule[] = [tasks, sched, sandbox, guard, usage, checkpoints, buddy]
+/**
+ * Registry, ordered. Order = hook composition order.
+ */
+export const features: FeatureModule[] = [tasks, sched, guard, usage, buddy, truncator, recovery]

package/src/features/recovery.ts

@@ -0,0 +1,143 @@
+import type { FeatureModule } from "../types.ts"
+import { inject, toast } from "../lib/inject.ts"
+
+export interface RecoveryOptions {
+  maxAttempts?: number
+  cooldownMs?: number
+  autoResume?: boolean
+}
+
+export interface ErrorClassification {
+  recoverable: boolean
+  reason?:
+    | "tool_result_missing"
+    | "thinking_order"
+    | "thinking_disabled"
+    | "context_limit"
+    | "rate_limit"
+    | "transient"
+  message?: string
+}
+
+const ERROR_PATTERNS: Array<{ regex: RegExp; reason: ErrorClassification["reason"] }> = [
+  {
+    regex: /tool_use.*(?:without|missing).*tool_result|tool_result.*missing/i,
+    reason: "tool_result_missing",
+  },
+  { regex: /thinking.*(?:must precede|preceded by|order)/i, reason: "thinking_order" },
+  { regex: /thinking.*(?:not allowed|disabled|unsupported)/i, reason: "thinking_disabled" },
+  {
+    regex: /prompt is too long|context.*(?:limit|window).*exceeded|maximum context length/i,
+    reason: "context_limit",
+  },
+  { regex: /rate[ _-]?limit|too many requests|overloaded/i, reason: "rate_limit" },
+  { regex: /socket hang up|ECONNRESET|ETIMEDOUT|network error/i, reason: "transient" },
+]
+
+/** Classify error into known recoverable provider failure modes. */
+export function classifyError(error: unknown): ErrorClassification {
+  if (!error) return { recoverable: false }
+
+  const errorString =
+    typeof error === "string"
+      ? error
+      : error instanceof Error
+        ? `${error.name}: ${error.message}`
+        : JSON.stringify(error)
+
+  for (const { regex, reason } of ERROR_PATTERNS) {
+    if (regex.test(errorString)) {
+      return { recoverable: true, reason, message: errorString }
+    }
+  }
+
+  return { recoverable: false, message: errorString }
+}
+
+export interface RecoveryTracker {
+  canAttempt(sessionID: string): boolean
+  recordAttempt(sessionID: string): void
+  reset(sessionID: string): void
+}
+
+/** Rate-limits recovery attempts per session. */
+export function createRecoveryTracker(maxAttempts = 3, cooldownMs = 60_000): RecoveryTracker {
+  const attempts = new Map<string, number[]>()
+
+  return {
+    canAttempt(sessionID: string): boolean {
+      const now = Date.now()
+      const list = (attempts.get(sessionID) ?? []).filter((t) => now - t < cooldownMs)
+      attempts.set(sessionID, list)
+      return list.length < maxAttempts
+    },
+    recordAttempt(sessionID: string): void {
+      const now = Date.now()
+      const list = (attempts.get(sessionID) ?? []).filter((t) => now - t < cooldownMs)
+      list.push(now)
+      attempts.set(sessionID, list)
+    },
+    reset(sessionID: string): void {
+      attempts.delete(sessionID)
+    },
+  }
+}
+
+/**
+ * Recovery module: automatically detects and recovers from transient provider errors,
+ * protocol sequencing glitches, and context window issues during autonomous sessions.
+ */
+export const recovery: FeatureModule = {
+  name: "recovery",
+  tools: [],
+  defaultEnabled: true,
+  requires: ["session.promptAsync", "session.messages"],
+  async init(ctx, options) {
+    const maxAttempts = typeof options.maxAttempts === "number" ? options.maxAttempts : 3
+    const cooldownMs = typeof options.cooldownMs === "number" ? options.cooldownMs : 60_000
+    const autoResume = options.autoResume !== false
+    const tracker = createRecoveryTracker(maxAttempts, cooldownMs)
+
+    return {
+      event: async ({ event }) => {
+        if (event.type === "session.deleted") {
+          const props = event.properties as { info?: { id?: string } } | undefined
+          if (props?.info?.id) tracker.reset(props.info.id)
+          return
+        }
+
+        if (event.type !== "session.error") return
+
+        const props = event.properties as { sessionID?: string; error?: unknown } | undefined
+        const sessionID = props?.sessionID
+        if (!sessionID || !props?.error) return
+
+        const classified = classifyError(props.error)
+        if (!classified.recoverable) return
+
+        if (!tracker.canAttempt(sessionID)) {
+          console.warn(
+            `[overclock] recovery: exceeded max attempts (${maxAttempts}) for session ${sessionID}`,
+          )
+          await toast(ctx.client, `recovery failed: too many consecutive errors in session`, "error")
+          return
+        }
+
+        tracker.recordAttempt(sessionID)
+        console.warn(
+          `[overclock] recovery: session ${sessionID} error (${classified.reason}), attempting auto-resume`,
+        )
+        await toast(ctx.client, `recovering session from ${classified.reason}...`, "warning")
+
+        if (autoResume) {
+          const resumeText =
+            classified.reason === "context_limit"
+              ? "[session recovered: context limit reached; summarize recent progress and continue with minimal output]"
+              : `[session recovered from ${classified.reason} - please continue with your previous task]`
+
+          await inject(ctx.client, sessionID, resumeText)
+        }
+      },
+    }
+  },
+}