micode 0.7.0 → 0.7.1

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

@@ -0,0 +1,68 @@
+export interface BackgroundTask {
+  id: string;
+  sessionID: string;
+  parentSessionID: string;
+  parentMessageID: string;
+  description: string;
+  prompt: string;
+  agent: string;
+  status: "running" | "completed" | "error" | "cancelled";
+  startedAt: Date;
+  completedAt?: Date;
+  result?: string;
+  error?: string;
+  progress?: {
+    toolCalls: number;
+    lastTool?: string;
+    lastUpdate: Date;
+  };
+}
+
+export interface BackgroundTaskInput {
+  description: string;
+  prompt: string;
+  agent: string;
+  parentSessionID: string;
+  parentMessageID: string;
+}
+
+// API Response Types - SDK wraps responses in { data: T } format
+export interface SessionCreateResponse {
+  data?: {
+    id?: string;
+  };
+}
+
+// SessionStatus from OpenCode SDK - status is a discriminated union with 'type' field
+export type SessionStatus =
+  | { type: "idle" }
+  | { type: "retry"; attempt: number; message: string; next: number }
+  | { type: "busy" };
+
+// session.status() returns { data: map of sessionID -> SessionStatus }
+export interface SessionStatusResponse {
+  data?: {
+    [sessionID: string]: SessionStatus;
+  };
+}
+
+export interface MessagePart {
+  type: string;
+  text?: string;
+}
+
+export interface MessageInfo {
+  role?: "user" | "assistant";
+  sessionID?: string;
+  type?: string;
+  name?: string;
+}
+
+export interface SessionMessage {
+  info?: MessageInfo;
+  parts?: MessagePart[];
+}
+
+export interface SessionMessagesResponse {
+  data?: SessionMessage[];
+}

package/src/tools/btca/index.ts

@@ -0,0 +1,82 @@
+import { spawn, which } from "bun";
+import { tool } from "@opencode-ai/plugin/tool";
+
+/**
+ * Check if btca CLI is available on the system.
+ * Returns installation instructions if not found.
+ */
+export async function checkBtcaAvailable(): Promise<{ available: boolean; message?: string }> {
+  const btcaPath = which("btca");
+  if (btcaPath) {
+    return { available: true };
+  }
+  return {
+    available: false,
+    message:
+      "btca CLI not found. Library source code search will not work.\n" +
+      "Install from: https://github.com/davis7dotsh/better-context\n" +
+      "  bun add -g btca",
+  };
+}
+
+const BTCA_TIMEOUT_MS = 120000; // 2 minutes for long clones
+
+async function runBtca(args: string[]): Promise<{ output: string; error?: string }> {
+  try {
+    const proc = spawn(["btca", ...args], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    // Create timeout promise
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        proc.kill();
+        reject(new Error("btca command timed out after 2 minutes"));
+      }, BTCA_TIMEOUT_MS);
+    });
+
+    // Race between process completion and timeout
+    const [stdout, stderr, exitCode] = await Promise.race([
+      Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]),
+      timeoutPromise,
+    ]);
+
+    if (exitCode !== 0) {
+      const errorMsg = stderr.trim() || `Exit code ${exitCode}`;
+      return { output: "", error: errorMsg };
+    }
+
+    return { output: stdout.trim() };
+  } catch (e) {
+    const err = e as Error;
+    if (err.message?.includes("ENOENT")) {
+      return {
+        output: "",
+        error:
+          "btca CLI not found. Install from: https://github.com/davis7dotsh/better-context\n" + "  bun add -g btca",
+      };
+    }
+    return { output: "", error: err.message };
+  }
+}
+
+export const btca_ask = tool({
+  description:
+    "Ask questions about library/framework source code using btca. " +
+    "Clones repos locally and searches source code to answer questions. " +
+    "Use for understanding library internals, finding implementation details, or debugging.",
+  args: {
+    tech: tool.schema.string().describe("Resource name configured in btca (e.g., 'react', 'express')"),
+    question: tool.schema.string().describe("Question to ask about the library source code"),
+  },
+  execute: async (args) => {
+    const result = await runBtca(["ask", "-t", args.tech, "-q", args.question]);
+
+    if (result.error) {
+      return `Error: ${result.error}`;
+    }
+
+    return result.output || "No answer found";
+  },
+});

package/src/tools/look-at.ts

@@ -0,0 +1,210 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { readFileSync, statSync } from "node:fs";
+import { extname, basename } from "node:path";
+
+// File size threshold for triggering extraction (100KB)
+const LARGE_FILE_THRESHOLD = 100 * 1024;
+
+// Max lines to return without extraction
+const MAX_LINES_WITHOUT_EXTRACT = 200;
+
+// Supported file types for smart extraction
+const EXTRACTABLE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".md",
+  ".json",
+  ".yaml",
+  ".yml",
+];
+
+function extractStructure(content: string, ext: string): string {
+  const lines = content.split("\n");
+
+  switch (ext) {
+    case ".ts":
+    case ".tsx":
+    case ".js":
+    case ".jsx":
+      return extractTypeScriptStructure(lines);
+    case ".py":
+      return extractPythonStructure(lines);
+    case ".go":
+      return extractGoStructure(lines);
+    case ".md":
+      return extractMarkdownStructure(lines);
+    case ".json":
+      return extractJsonStructure(content);
+    case ".yaml":
+    case ".yml":
+      return extractYamlStructure(lines);
+    default:
+      return extractGenericStructure(lines);
+  }
+}
+
+function extractTypeScriptStructure(lines: string[]): string {
+  const output: string[] = ["## Structure\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Capture exports, classes, interfaces, types, functions
+    if (
+      trimmed.startsWith("export ") ||
+      trimmed.startsWith("class ") ||
+      trimmed.startsWith("interface ") ||
+      trimmed.startsWith("type ") ||
+      trimmed.startsWith("function ") ||
+      trimmed.startsWith("const ") ||
+      trimmed.startsWith("async function ")
+    ) {
+      // Get the signature (first line only for multi-line)
+      const signature = trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
+      output.push(`Line ${i + 1}: ${signature}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractPythonStructure(lines: string[]): string {
+  const output: string[] = ["## Structure\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Capture classes, functions, decorators
+    if (
+      trimmed.startsWith("class ") ||
+      trimmed.startsWith("def ") ||
+      trimmed.startsWith("async def ") ||
+      trimmed.startsWith("@")
+    ) {
+      const signature = trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
+      output.push(`Line ${i + 1}: ${signature}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractGoStructure(lines: string[]): string {
+  const output: string[] = ["## Structure\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Capture types, functions, methods
+    if (trimmed.startsWith("type ") || trimmed.startsWith("func ") || trimmed.startsWith("package ")) {
+      const signature = trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
+      output.push(`Line ${i + 1}: ${signature}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractMarkdownStructure(lines: string[]): string {
+  const output: string[] = ["## Outline\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Capture headings
+    if (line.startsWith("#")) {
+      output.push(`Line ${i + 1}: ${line}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractJsonStructure(content: string): string {
+  try {
+    const obj = JSON.parse(content);
+    const keys = Object.keys(obj);
+    return `## Top-level keys (${keys.length})\n\n${keys.slice(0, 50).join(", ")}${keys.length > 50 ? "..." : ""}`;
+  } catch {
+    return "## Invalid JSON";
+  }
+}
+
+function extractYamlStructure(lines: string[]): string {
+  const output: string[] = ["## Top-level keys\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Top-level keys (no indentation)
+    if (line.match(/^[a-zA-Z_][a-zA-Z0-9_]*:/)) {
+      output.push(`Line ${i + 1}: ${line}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractGenericStructure(lines: string[]): string {
+  // For unknown files, just show first/last lines and line count
+  const total = lines.length;
+  const preview = lines.slice(0, 10).join("\n");
+  const tail = lines.slice(-5).join("\n");
+
+  return `## File Preview (${total} lines)\n\n### First 10 lines:\n${preview}\n\n### Last 5 lines:\n${tail}`;
+}
+
+export const look_at = tool({
+  description: `Extract key information from a file to save context tokens.
+For large files, returns structure/outline instead of full content.
+Use when you need to understand a file without loading all content.
+Ideal for: large files, getting file structure, quick overview.`,
+  args: {
+    filePath: tool.schema.string().describe("Path to the file"),
+    extract: tool.schema
+      .string()
+      .optional()
+      .describe("What to extract: 'structure', 'imports', 'exports', 'all' (default: auto)"),
+  },
+  execute: async (args) => {
+    try {
+      const stats = statSync(args.filePath);
+      const ext = extname(args.filePath).toLowerCase();
+      const name = basename(args.filePath);
+
+      // Read file
+      const content = readFileSync(args.filePath, "utf-8");
+      const lines = content.split("\n");
+
+      // For small files, return full content
+      if (stats.size < LARGE_FILE_THRESHOLD && lines.length <= MAX_LINES_WITHOUT_EXTRACT) {
+        return `## ${name} (${lines.length} lines)\n\n${content}`;
+      }
+
+      // For large files, extract structure
+      let output = `## ${name}\n`;
+      output += `**Size**: ${Math.round(stats.size / 1024)}KB | **Lines**: ${lines.length}\n\n`;
+
+      if (EXTRACTABLE_EXTENSIONS.includes(ext)) {
+        output += extractStructure(content, ext);
+      } else {
+        output += extractGenericStructure(lines);
+      }
+
+      output += `\n\n---\n*Use Read tool with line offset/limit for specific sections*`;
+
+      return output;
+    } catch (e) {
+      return `Error: ${e instanceof Error ? e.message : String(e)}`;
+    }
+  },
+});

package/src/tools/pty/buffer.ts

@@ -0,0 +1,49 @@
+// src/tools/pty/buffer.ts
+import type { SearchMatch } from "./types";
+
+const parsed = parseInt(process.env.PTY_MAX_BUFFER_LINES || "50000", 10);
+const DEFAULT_MAX_LINES = isNaN(parsed) ? 50000 : parsed;
+
+export class RingBuffer {
+  private lines: string[] = [];
+  private maxLines: number;
+
+  constructor(maxLines: number = DEFAULT_MAX_LINES) {
+    this.maxLines = maxLines;
+  }
+
+  append(data: string): void {
+    const newLines = data.split("\n");
+    for (const line of newLines) {
+      this.lines.push(line);
+      if (this.lines.length > this.maxLines) {
+        this.lines.shift();
+      }
+    }
+  }
+
+  read(offset: number = 0, limit?: number): string[] {
+    const start = Math.max(0, offset);
+    const end = limit !== undefined ? start + limit : this.lines.length;
+    return this.lines.slice(start, end);
+  }
+
+  search(pattern: RegExp): SearchMatch[] {
+    const matches: SearchMatch[] = [];
+    for (let i = 0; i < this.lines.length; i++) {
+      const line = this.lines[i];
+      if (line !== undefined && pattern.test(line)) {
+        matches.push({ lineNumber: i + 1, text: line });
+      }
+    }
+    return matches;
+  }
+
+  get length(): number {
+    return this.lines.length;
+  }
+
+  clear(): void {
+    this.lines = [];
+  }
+}

package/src/tools/pty/index.ts

@@ -0,0 +1,34 @@
+// src/tools/pty/index.ts
+export { PTYManager } from "./manager";
+export { RingBuffer } from "./buffer";
+export { createPtySpawnTool } from "./tools/spawn";
+export { createPtyWriteTool } from "./tools/write";
+export { createPtyReadTool } from "./tools/read";
+export { createPtyListTool } from "./tools/list";
+export { createPtyKillTool } from "./tools/kill";
+export type {
+  PTYSession,
+  PTYSessionInfo,
+  PTYStatus,
+  SpawnOptions,
+  ReadResult,
+  SearchMatch,
+  SearchResult,
+} from "./types";
+
+import type { PTYManager } from "./manager";
+import { createPtySpawnTool } from "./tools/spawn";
+import { createPtyWriteTool } from "./tools/write";
+import { createPtyReadTool } from "./tools/read";
+import { createPtyListTool } from "./tools/list";
+import { createPtyKillTool } from "./tools/kill";
+
+export function createPtyTools(manager: PTYManager) {
+  return {
+    pty_spawn: createPtySpawnTool(manager),
+    pty_write: createPtyWriteTool(manager),
+    pty_read: createPtyReadTool(manager),
+    pty_list: createPtyListTool(manager),
+    pty_kill: createPtyKillTool(manager),
+  };
+}

package/src/tools/pty/manager.ts

@@ -0,0 +1,159 @@
+// src/tools/pty/manager.ts
+import { spawn, type IPty } from "bun-pty";
+import { RingBuffer } from "./buffer";
+import type { PTYSession, PTYSessionInfo, SpawnOptions, ReadResult, SearchResult } from "./types";
+
+function generateId(): string {
+  const hex = Array.from(crypto.getRandomValues(new Uint8Array(4)))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `pty_${hex}`;
+}
+
+export class PTYManager {
+  private sessions: Map<string, PTYSession> = new Map();
+
+  spawn(opts: SpawnOptions): PTYSessionInfo {
+    const id = generateId();
+    const args = opts.args ?? [];
+    const workdir = opts.workdir ?? process.cwd();
+    const env = { ...process.env, ...opts.env } as Record<string, string>;
+    const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
+
+    const ptyProcess: IPty = spawn(opts.command, args, {
+      name: "xterm-256color",
+      cols: 120,
+      rows: 40,
+      cwd: workdir,
+      env,
+    });
+
+    const buffer = new RingBuffer();
+    const session: PTYSession = {
+      id,
+      title,
+      command: opts.command,
+      args,
+      workdir,
+      env: opts.env,
+      status: "running",
+      pid: ptyProcess.pid,
+      createdAt: new Date(),
+      parentSessionId: opts.parentSessionId,
+      buffer,
+      process: ptyProcess,
+    };
+
+    this.sessions.set(id, session);
+
+    ptyProcess.onData((data: string) => {
+      buffer.append(data);
+    });
+
+    ptyProcess.onExit(({ exitCode }: { exitCode: number }) => {
+      if (session.status === "running") {
+        session.status = "exited";
+        session.exitCode = exitCode;
+      }
+    });
+
+    return this.toInfo(session);
+  }
+
+  write(id: string, data: string): boolean {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status !== "running") {
+      return false;
+    }
+    session.process.write(data);
+    return true;
+  }
+
+  read(id: string, offset: number = 0, limit?: number): ReadResult | null {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const lines = session.buffer.read(offset, limit);
+    const totalLines = session.buffer.length;
+    const hasMore = offset + lines.length < totalLines;
+    return { lines, totalLines, offset, hasMore };
+  }
+
+  search(id: string, pattern: RegExp, offset: number = 0, limit?: number): SearchResult | null {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const allMatches = session.buffer.search(pattern);
+    const totalMatches = allMatches.length;
+    const totalLines = session.buffer.length;
+    const paginatedMatches = limit !== undefined ? allMatches.slice(offset, offset + limit) : allMatches.slice(offset);
+    const hasMore = offset + paginatedMatches.length < totalMatches;
+    return { matches: paginatedMatches, totalMatches, totalLines, offset, hasMore };
+  }
+
+  list(): PTYSessionInfo[] {
+    return Array.from(this.sessions.values()).map((s) => this.toInfo(s));
+  }
+
+  get(id: string): PTYSessionInfo | null {
+    const session = this.sessions.get(id);
+    return session ? this.toInfo(session) : null;
+  }
+
+  kill(id: string, cleanup: boolean = false): boolean {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+
+    if (session.status === "running") {
+      try {
+        session.process.kill();
+      } catch {
+        // Process may already be dead
+      }
+      session.status = "killed";
+    }
+
+    if (cleanup) {
+      session.buffer.clear();
+      this.sessions.delete(id);
+    }
+
+    return true;
+  }
+
+  cleanupBySession(parentSessionId: string): void {
+    for (const [id, session] of this.sessions) {
+      if (session.parentSessionId === parentSessionId) {
+        this.kill(id, true);
+      }
+    }
+  }
+
+  cleanupAll(): void {
+    for (const id of this.sessions.keys()) {
+      this.kill(id, true);
+    }
+  }
+
+  private toInfo(session: PTYSession): PTYSessionInfo {
+    return {
+      id: session.id,
+      title: session.title,
+      command: session.command,
+      args: session.args,
+      workdir: session.workdir,
+      status: session.status,
+      exitCode: session.exitCode,
+      pid: session.pid,
+      createdAt: session.createdAt,
+      lineCount: session.buffer.length,
+    };
+  }
+}

package/src/tools/pty/tools/kill.ts

@@ -0,0 +1,68 @@
+// src/tools/pty/tools/kill.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Terminates a PTY session and optionally cleans up its buffer.
+
+Use this tool to:
+- Stop a running process (sends SIGTERM)
+- Clean up an exited session to free memory
+- Remove a session from the list
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`cleanup\`: If true, removes the session and frees the buffer (default: false)
+
+Behavior:
+- If the session is running, it will be killed (status becomes "killed")
+- If cleanup=false (default), the session remains in the list with its output buffer intact
+- If cleanup=true, the session is removed entirely and the buffer is freed
+- Keeping sessions without cleanup allows you to compare logs between runs
+
+Tips:
+- Use cleanup=false if you might want to read the output later
+- Use cleanup=true when you're done with the session entirely
+- To send Ctrl+C instead of killing, use pty_write with data="\\x03"
+
+Examples:
+- Kill but keep logs: cleanup=false (or omit)
+- Kill and remove: cleanup=true`;
+
+export function createPtyKillTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      cleanup: tool.schema
+        .boolean()
+        .optional()
+        .describe("If true, removes the session and frees the buffer (default: false)"),
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+
+      const wasRunning = session.status === "running";
+      const cleanup = args.cleanup ?? false;
+      const success = manager.kill(args.id, cleanup);
+
+      if (!success) {
+        throw new Error(`Failed to kill PTY session '${args.id}'.`);
+      }
+
+      const action = wasRunning ? "Killed" : "Cleaned up";
+      const cleanupNote = cleanup ? " (session removed)" : " (session retained for log access)";
+
+      return [
+        `<pty_killed>`,
+        `${action}: ${args.id}${cleanupNote}`,
+        `Title: ${session.title}`,
+        `Command: ${session.command} ${session.args.join(" ")}`,
+        `Final line count: ${session.lineCount}`,
+        `</pty_killed>`,
+      ].join("\n");
+    },
+  });
+}