@hiai-gg/hiai-opencode 0.1.0

package/src/tools/ast-grep/index.ts

@@ -0,0 +1,5 @@
+export { createAstGrepTools } from "./tools"
+export { ensureAstGrepBinary, getCachedBinaryPath, getCacheDir } from "./downloader"
+export { getAstGrepPath, isCliAvailable, ensureCliAvailable, startBackgroundInit } from "./cli"
+export { checkEnvironment, formatEnvironmentCheck } from "./constants"
+export type { EnvironmentCheckResult } from "./constants"

package/src/tools/ast-grep/language-support.ts

@@ -0,0 +1,63 @@
+// CLI supported languages (25 total)
+export const CLI_LANGUAGES = [
+	"bash",
+	"c",
+	"cpp",
+	"csharp",
+	"css",
+	"elixir",
+	"go",
+	"haskell",
+	"html",
+	"java",
+	"javascript",
+	"json",
+	"kotlin",
+	"lua",
+	"nix",
+	"php",
+	"python",
+	"ruby",
+	"rust",
+	"scala",
+	"solidity",
+	"swift",
+	"typescript",
+	"tsx",
+	"yaml",
+] as const
+
+// NAPI supported languages (5 total - native bindings)
+export const NAPI_LANGUAGES = ["html", "javascript", "tsx", "css", "typescript"] as const
+
+export const DEFAULT_TIMEOUT_MS = 300_000
+export const DEFAULT_MAX_OUTPUT_BYTES = 1 * 1024 * 1024
+export const DEFAULT_MAX_MATCHES = 500
+
+export const LANG_EXTENSIONS: Record<string, string[]> = {
+	bash: [".bash", ".sh", ".zsh", ".bats"],
+	c: [".c", ".h"],
+	cpp: [".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".h"],
+	csharp: [".cs"],
+	css: [".css"],
+	elixir: [".ex", ".exs"],
+	go: [".go"],
+	haskell: [".hs", ".lhs"],
+	html: [".html", ".htm"],
+	java: [".java"],
+	javascript: [".js", ".jsx", ".mjs", ".cjs"],
+	json: [".json"],
+	kotlin: [".kt", ".kts"],
+	lua: [".lua"],
+	nix: [".nix"],
+	php: [".php"],
+	python: [".py", ".pyi"],
+	ruby: [".rb", ".rake"],
+	rust: [".rs"],
+	scala: [".scala", ".sc"],
+	solidity: [".sol"],
+	swift: [".swift"],
+	typescript: [".ts", ".cts", ".mts"],
+	tsx: [".tsx"],
+	yaml: [".yml", ".yaml"],
+}

package/src/tools/ast-grep/process-output-timeout.ts

@@ -0,0 +1,28 @@
+type SpawnedProcess = {
+	stdout: ReadableStream | null
+	stderr: ReadableStream | null
+	exited: Promise<number>
+	kill: () => void
+}
+
+export async function collectProcessOutputWithTimeout(
+	process: SpawnedProcess,
+	timeoutMs: number
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const timeoutPromise = new Promise<never>((_, reject) => {
+		const timeoutId = setTimeout(() => {
+			process.kill()
+			reject(new Error(`Search timeout after ${timeoutMs}ms`))
+		}, timeoutMs)
+		process.exited.then(() => clearTimeout(timeoutId))
+	})
+
+	const stdoutPromise = process.stdout ? new Response(process.stdout).text() : Promise.resolve("")
+	const stderrPromise = process.stderr ? new Response(process.stderr).text() : Promise.resolve("")
+
+	const stdout = await Promise.race([stdoutPromise, timeoutPromise])
+	const stderr = await stderrPromise
+	const exitCode = await process.exited
+
+	return { stdout, stderr, exitCode }
+}

package/src/tools/ast-grep/result-formatter.ts

@@ -0,0 +1,102 @@
+import type { AnalyzeResult, SgResult } from "./types"
+
+export function formatSearchResult(result: SgResult): string {
+  if (result.error) {
+    return `Error: ${result.error}`
+  }
+
+  if (result.matches.length === 0) {
+    return "No matches found"
+  }
+
+  const lines: string[] = []
+
+  if (result.truncated) {
+    const reason = result.truncatedReason === "max_matches"
+      ? `showing first ${result.matches.length} of ${result.totalMatches}`
+      : result.truncatedReason === "max_output_bytes"
+      ? "output exceeded 1MB limit"
+      : "search timed out"
+    lines.push(`[TRUNCATED] Results truncated (${reason})\n`)
+  }
+
+  lines.push(`Found ${result.matches.length} match(es)${result.truncated ? ` (truncated from ${result.totalMatches})` : ""}:\n`)
+
+  for (const match of result.matches) {
+    const loc = `${match.file}:${match.range.start.line + 1}:${match.range.start.column + 1}`
+    lines.push(`${loc}`)
+    lines.push(`  ${match.lines.trim()}`)
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+export function formatReplaceResult(result: SgResult, isDryRun: boolean): string {
+  if (result.error) {
+    return `Error: ${result.error}`
+  }
+
+  if (result.matches.length === 0) {
+    return "No matches found to replace"
+  }
+
+  const prefix = isDryRun ? "[DRY RUN] " : ""
+  const lines: string[] = []
+
+  if (result.truncated) {
+    const reason = result.truncatedReason === "max_matches"
+      ? `showing first ${result.matches.length} of ${result.totalMatches}`
+      : result.truncatedReason === "max_output_bytes"
+      ? "output exceeded 1MB limit"
+      : "search timed out"
+    lines.push(`[TRUNCATED] Results truncated (${reason})\n`)
+  }
+
+  lines.push(`${prefix}${result.matches.length} replacement(s):\n`)
+
+  for (const match of result.matches) {
+    const loc = `${match.file}:${match.range.start.line + 1}:${match.range.start.column + 1}`
+    lines.push(`${loc}`)
+    lines.push(`  ${match.text}`)
+    lines.push("")
+  }
+
+  if (isDryRun) {
+    lines.push("Use dryRun=false to apply changes")
+  }
+
+  return lines.join("\n")
+}
+
+export function formatAnalyzeResult(results: AnalyzeResult[], extractedMetaVars: boolean): string {
+  if (results.length === 0) {
+    return "No matches found"
+  }
+
+  const lines: string[] = [`Found ${results.length} match(es):\n`]
+
+  for (const result of results) {
+    const loc = `L${result.range.start.line + 1}:${result.range.start.column + 1}`
+    lines.push(`[${loc}] (${result.kind})`)
+    lines.push(`  ${result.text}`)
+
+    if (extractedMetaVars && result.metaVariables.length > 0) {
+      lines.push("  Meta-variables:")
+      for (const mv of result.metaVariables) {
+        lines.push(`    $${mv.name} = "${mv.text}" (${mv.kind})`)
+      }
+    }
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+export function formatTransformResult(_original: string, transformed: string, editCount: number): string {
+  if (editCount === 0) {
+    return "No matches found to transform"
+  }
+
+  return `Transformed (${editCount} edit(s)):\n\`\`\`\n${transformed}\n\`\`\``
+}

package/src/tools/ast-grep/sg-cli-path.ts

@@ -0,0 +1,102 @@
+import { createRequire } from "module"
+import { dirname, join } from "path"
+import { existsSync, statSync } from "fs"
+
+import { getCachedBinaryPath } from "./downloader"
+
+type Platform = "darwin" | "linux" | "win32" | "unsupported"
+
+function isValidBinary(filePath: string): boolean {
+	try {
+		return statSync(filePath).size > 10000
+	} catch {
+		return false
+	}
+}
+
+function getPlatformPackageName(): string | null {
+	const platform = process.platform as Platform
+	const arch = process.arch
+
+	const platformMap: Record<string, string> = {
+		"darwin-arm64": "@ast-grep/cli-darwin-arm64",
+		"darwin-x64": "@ast-grep/cli-darwin-x64",
+		"linux-arm64": "@ast-grep/cli-linux-arm64-gnu",
+		"linux-x64": "@ast-grep/cli-linux-x64-gnu",
+		"win32-x64": "@ast-grep/cli-win32-x64-msvc",
+		"win32-arm64": "@ast-grep/cli-win32-arm64-msvc",
+		"win32-ia32": "@ast-grep/cli-win32-ia32-msvc",
+	}
+
+	return platformMap[`${platform}-${arch}`] ?? null
+}
+
+export function findSgCliPathSync(): string | null {
+	const binaryName = process.platform === "win32" ? "sg.exe" : "sg"
+
+	const cachedPath = getCachedBinaryPath()
+	if (cachedPath && isValidBinary(cachedPath)) {
+		return cachedPath
+	}
+
+	try {
+		const require = createRequire(import.meta.url)
+		const cliPackageJsonPath = require.resolve("@ast-grep/cli/package.json")
+		const cliDirectory = dirname(cliPackageJsonPath)
+		const sgPath = join(cliDirectory, binaryName)
+
+		if (existsSync(sgPath) && isValidBinary(sgPath)) {
+			return sgPath
+		}
+	} catch {
+		// @ast-grep/cli not installed
+	}
+
+	const platformPackage = getPlatformPackageName()
+	if (platformPackage) {
+		try {
+			const require = createRequire(import.meta.url)
+			const packageJsonPath = require.resolve(`${platformPackage}/package.json`)
+			const packageDirectory = dirname(packageJsonPath)
+			const astGrepBinaryName = process.platform === "win32" ? "ast-grep.exe" : "ast-grep"
+			const binaryPath = join(packageDirectory, astGrepBinaryName)
+
+			if (existsSync(binaryPath) && isValidBinary(binaryPath)) {
+				return binaryPath
+			}
+		} catch {
+			// Platform-specific package not installed
+		}
+	}
+
+	if (process.platform === "darwin") {
+		const homebrewPaths = ["/opt/homebrew/bin/sg", "/usr/local/bin/sg"]
+		for (const path of homebrewPaths) {
+			if (existsSync(path) && isValidBinary(path)) {
+				return path
+			}
+		}
+	}
+
+	return null
+}
+
+let resolvedCliPath: string | null = null
+
+export function getSgCliPath(): string | null {
+	if (resolvedCliPath !== null) {
+		return resolvedCliPath
+	}
+
+	const syncPath = findSgCliPathSync()
+	if (syncPath) {
+		resolvedCliPath = syncPath
+		return syncPath
+	}
+
+	return null
+}
+
+export function setSgCliPath(path: string): void {
+	resolvedCliPath = path
+}

package/src/tools/ast-grep/sg-compact-json-output.ts

@@ -0,0 +1,54 @@
+import { DEFAULT_MAX_MATCHES, DEFAULT_MAX_OUTPUT_BYTES } from "./constants"
+import type { CliMatch, SgResult } from "./types"
+
+export function createSgResultFromStdout(stdout: string): SgResult {
+	if (!stdout.trim()) {
+		return { matches: [], totalMatches: 0, truncated: false }
+	}
+
+	const outputTruncated = stdout.length >= DEFAULT_MAX_OUTPUT_BYTES
+	const outputToProcess = outputTruncated ? stdout.substring(0, DEFAULT_MAX_OUTPUT_BYTES) : stdout
+
+	let matches: CliMatch[] = []
+	try {
+		matches = JSON.parse(outputToProcess) as CliMatch[]
+	} catch {
+		if (outputTruncated) {
+			try {
+				const lastValidIndex = outputToProcess.lastIndexOf("}")
+				if (lastValidIndex > 0) {
+					const bracketIndex = outputToProcess.lastIndexOf("},", lastValidIndex)
+					if (bracketIndex > 0) {
+						const truncatedJson = outputToProcess.substring(0, bracketIndex + 1) + "]"
+						matches = JSON.parse(truncatedJson) as CliMatch[]
+					}
+				}
+			} catch {
+				return {
+					matches: [],
+					totalMatches: 0,
+					truncated: true,
+					truncatedReason: "max_output_bytes",
+					error: "Output too large and could not be parsed",
+				}
+			}
+		} else {
+			return { matches: [], totalMatches: 0, truncated: false }
+		}
+	}
+
+	const totalMatches = matches.length
+	const matchesTruncated = totalMatches > DEFAULT_MAX_MATCHES
+	const finalMatches = matchesTruncated ? matches.slice(0, DEFAULT_MAX_MATCHES) : matches
+
+	return {
+		matches: finalMatches,
+		totalMatches,
+		truncated: outputTruncated || matchesTruncated,
+		truncatedReason: outputTruncated
+			? "max_output_bytes"
+			: matchesTruncated
+				? "max_matches"
+				: undefined,
+	}
+}

package/src/tools/ast-grep/tools.ts

@@ -0,0 +1,117 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"
+import { CLI_LANGUAGES } from "./constants"
+import { runSg } from "./cli"
+import { formatSearchResult, formatReplaceResult } from "./result-formatter"
+import type { CliLanguage } from "./types"
+
+async function showOutputToUser(context: unknown, output: string): Promise<void> {
+  const ctx = context as {
+    metadata?: (input: { metadata: { output: string } }) => void | Promise<void>
+  }
+  await ctx.metadata?.({ metadata: { output } })
+}
+
+function getEmptyResultHint(pattern: string, lang: CliLanguage): string | null {
+  const src = pattern.trim()
+
+  if (lang === "python") {
+    if (src.startsWith("class ") && src.endsWith(":")) {
+      const withoutColon = src.slice(0, -1)
+      return `Hint: Remove trailing colon. Try: "${withoutColon}"`
+    }
+    if ((src.startsWith("def ") || src.startsWith("async def ")) && src.endsWith(":")) {
+      const withoutColon = src.slice(0, -1)
+      return `Hint: Remove trailing colon. Try: "${withoutColon}"`
+    }
+  }
+
+  if (["javascript", "typescript", "tsx"].includes(lang)) {
+    if (/^(export\s+)?(async\s+)?function\s+\$[A-Z_]+\s*$/i.test(src)) {
+      return `Hint: Function patterns need params and body. Try "function $NAME($$$) { $$$ }"`
+    }
+  }
+
+  return null
+}
+
+export function createAstGrepTools(ctx: PluginInput): Record<string, ToolDefinition> {
+  const ast_grep_search: ToolDefinition = tool({
+    description:
+      "Search code patterns across filesystem using AST-aware matching. Supports 25 languages. " +
+      "Use meta-variables: $VAR (single node), $$$ (multiple nodes). " +
+      "IMPORTANT: Patterns must be complete AST nodes (valid code). " +
+      "For functions, include params and body: 'export async function $NAME($$$) { $$$ }' not 'export async function $NAME'. " +
+      "Examples: 'console.log($MSG)', 'def $FUNC($$$):', 'async function $NAME($$$)'",
+    args: {
+      pattern: tool.schema.string().describe("AST pattern with meta-variables ($VAR, $$$). Must be complete AST node."),
+      lang: tool.schema.enum(CLI_LANGUAGES).describe("Target language"),
+      paths: tool.schema.array(tool.schema.string()).optional().describe("Paths to search (default: ['.'])"),
+      globs: tool.schema.array(tool.schema.string()).optional().describe("Include/exclude globs (prefix ! to exclude)"),
+      context: tool.schema.number().optional().describe("Context lines around match"),
+    },
+    execute: async (args, context) => {
+      try {
+        const result = await runSg({
+          pattern: args.pattern,
+          lang: args.lang as CliLanguage,
+          paths: args.paths ?? [ctx.directory],
+          globs: args.globs,
+          context: args.context,
+        })
+
+        let output = formatSearchResult(result)
+
+        if (result.matches.length === 0 && !result.error) {
+          const hint = getEmptyResultHint(args.pattern, args.lang as CliLanguage)
+          if (hint) {
+            output += `\n\n${hint}`
+          }
+        }
+
+        await showOutputToUser(context, output)
+        return output
+      } catch (e) {
+        const output = `Error: ${e instanceof Error ? e.message : String(e)}`
+        await showOutputToUser(context, output)
+        return output
+      }
+    },
+  })
+
+  const ast_grep_replace: ToolDefinition = tool({
+    description:
+      "Replace code patterns across filesystem with AST-aware rewriting. " +
+      "Dry-run by default. Use meta-variables in rewrite to preserve matched content. " +
+      "Example: pattern='console.log($MSG)' rewrite='logger.info($MSG)'",
+    args: {
+      pattern: tool.schema.string().describe("AST pattern to match"),
+      rewrite: tool.schema.string().describe("Replacement pattern (can use $VAR from pattern)"),
+      lang: tool.schema.enum(CLI_LANGUAGES).describe("Target language"),
+      paths: tool.schema.array(tool.schema.string()).optional().describe("Paths to search"),
+      globs: tool.schema.array(tool.schema.string()).optional().describe("Include/exclude globs"),
+      dryRun: tool.schema.boolean().optional().describe("Preview changes without applying (default: true)"),
+    },
+    execute: async (args, context) => {
+      try {
+        const result = await runSg({
+          pattern: args.pattern,
+          rewrite: args.rewrite,
+          lang: args.lang as CliLanguage,
+          paths: args.paths ?? [ctx.directory],
+          globs: args.globs,
+          updateAll: args.dryRun === false,
+        })
+        const output = formatReplaceResult(result, args.dryRun !== false)
+        await showOutputToUser(context, output)
+        return output
+      } catch (e) {
+        const output = `Error: ${e instanceof Error ? e.message : String(e)}`
+        await showOutputToUser(context, output)
+        return output
+      }
+    },
+  })
+
+  return { ast_grep_search, ast_grep_replace }
+}

package/src/tools/ast-grep/types.ts

@@ -0,0 +1,61 @@
+import type { CLI_LANGUAGES, NAPI_LANGUAGES } from "./constants"
+
+export type CliLanguage = (typeof CLI_LANGUAGES)[number]
+export type NapiLanguage = (typeof NAPI_LANGUAGES)[number]
+
+export interface Position {
+  line: number
+  column: number
+}
+
+export interface Range {
+  start: Position
+  end: Position
+}
+
+export interface CliMatch {
+  text: string
+  range: {
+    byteOffset: { start: number; end: number }
+    start: Position
+    end: Position
+  }
+  file: string
+  lines: string
+  charCount: { leading: number; trailing: number }
+  language: string
+}
+
+export interface SearchMatch {
+  file: string
+  text: string
+  range: Range
+  lines: string
+}
+
+export interface MetaVariable {
+  name: string
+  text: string
+  kind: string
+}
+
+export interface AnalyzeResult {
+  text: string
+  range: Range
+  kind: string
+  metaVariables: MetaVariable[]
+}
+
+export interface TransformResult {
+  original: string
+  transformed: string
+  editCount: number
+}
+
+export interface SgResult {
+  matches: CliMatch[]
+  totalMatches: number
+  truncated: boolean
+  truncatedReason?: "max_matches" | "max_output_bytes" | "timeout"
+  error?: string
+}

package/src/tools/background-task/AGENTS.md

@@ -0,0 +1,53 @@
+# src/tools/background-task/ — Background Task Tool Wrappers
+
+**Generated:** 2026-04-11
+
+## OVERVIEW
+
+18 files. Tool-layer wrappers for `background_output` and `background_cancel`. Does NOT implement the background execution engine — that lives in `src/features/background-agent/`. This directory provides the LLM-facing tool interface.
+
+## THREE TOOLS
+
+| Tool | Factory | Purpose |
+|------|---------|---------|
+| `background_output` | `createBackgroundOutput` | Get results from a running/completed background task |
+| `background_cancel` | `createBackgroundCancel` | Cancel running task(s) |
+| `createBackgroundTask` | internal | Shared factory used by both |
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `create-background-output.ts` | `background_output` tool: fetch task results by task_id |
+| `create-background-cancel.ts` | `background_cancel` tool: cancel by taskId or all=true |
+| `create-background-task.ts` | Shared tool factory with common params |
+| `clients.ts` | Client interfaces for background output and cancel |
+| `session-messages.ts` | Fetch session messages from OpenCode |
+| `full-session-format.ts` | Format full session output (messages, thinking blocks) |
+| `task-result-format.ts` | Format task result for LLM consumption |
+| `task-status-format.ts` | Format task status (running/completed/error) |
+| `message-dir.ts` | Temp directory for message exchange |
+| `truncate-text.ts` | Truncate large output to fit context |
+| `time-format.ts` | Human-readable duration formatting |
+| `delay.ts` | Polling delay utility |
+| `types.ts` | `BackgroundTaskOptions`, result/status types |
+| `constants.ts` | Timeout defaults, polling intervals |
+
+## BACKGROUND OUTPUT MODES
+
+```
+background_output(task_id, block=false)  → check current status/result
+background_output(task_id, block=true)   → wait until complete (timeout default: 120s)
+background_output(task_id, full_session=true) → return full session transcript
+background_output(task_id, message_limit=N) → last N messages only
+background_output(task_id, include_thinking=true) → include thinking blocks
+```
+
+## RELATIONSHIP TO BACKGROUND ENGINE
+
+```
+tools/background-task/  ← LLM tool interface
+features/background-agent/  ← execution engine (BackgroundManager)
+```
+
+`createBackgroundOutput` queries `BackgroundManager.getTask(task_id)` — it does not manage task state.

package/src/tools/background-task/clients.ts

@@ -0,0 +1,32 @@
+import type { BackgroundManager } from "../../features/background-agent"
+
+export type BackgroundOutputMessage = {
+  id?: string
+  info?: { role?: string; time?: string | { created?: number }; agent?: string }
+  parts?: Array<{
+    type?: string
+    text?: string
+    thinking?: string
+    content?: string | Array<{ type: string; text?: string }>
+    output?: string
+    name?: string
+  }>
+}
+
+export type BackgroundOutputMessagesResult =
+  | { data?: BackgroundOutputMessage[]; error?: unknown }
+  | BackgroundOutputMessage[]
+
+export type BackgroundOutputClient = {
+  session: {
+    messages: (args: { path: { id: string } }) => Promise<BackgroundOutputMessagesResult>
+  }
+}
+
+export type BackgroundCancelClient = {
+  session: {
+    abort: (args: { path: { id: string } }) => Promise<unknown>
+  }
+}
+
+export type BackgroundOutputManager = Pick<BackgroundManager, "getTask">

package/src/tools/background-task/constants.ts

@@ -0,0 +1,9 @@
+export const BACKGROUND_TASK_DESCRIPTION = `Run agent task in background. Returns task_id immediately; notifies on completion.
+
+Use \`background_output\` to get results. Prompts MUST be in English.`
+
+export const BACKGROUND_OUTPUT_DESCRIPTION = `Get output from background task. Use full_session=true to fetch session messages with filters. System notifies on completion, so block=true rarely needed. - Timeout values are in milliseconds (ms), NOT seconds.
+
+IMPORTANT: ONLY call this tool AFTER receiving a <system-reminder> notification for the task. Do NOT call immediately after launching a background task - wait for the notification first.`
+
+export const BACKGROUND_CANCEL_DESCRIPTION = `Cancel running background task(s). Use all=true to cancel ALL before final answer.`