micode 0.6.0 → 0.7.1

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

@@ -0,0 +1,374 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type {
+  BackgroundTask,
+  BackgroundTaskInput,
+  SessionCreateResponse,
+  SessionStatusResponse,
+  SessionMessagesResponse,
+} from "./types";
+
+const POLL_INTERVAL_MS = 2000;
+const TASK_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+function generateTaskId(): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "bg_";
+  for (let i = 0; i < 8; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+function formatDuration(start: Date, end?: Date): string {
+  const ms = (end || new Date()).getTime() - start.getTime();
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+
+  if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+export class BackgroundTaskManager {
+  private tasks: Map<string, BackgroundTask> = new Map();
+  private notifications: Map<string, BackgroundTask[]> = new Map();
+  private pollingInterval?: ReturnType<typeof setInterval>;
+  private ctx: PluginInput;
+
+  constructor(ctx: PluginInput) {
+    this.ctx = ctx;
+  }
+
+  async launch(input: BackgroundTaskInput): Promise<BackgroundTask> {
+    const taskId = generateTaskId();
+
+    // Create new session for background task
+    const sessionResp = await this.ctx.client.session.create({
+      body: {},
+      query: { directory: this.ctx.directory },
+    });
+
+    const sessionData = sessionResp as SessionCreateResponse;
+    const sessionID = sessionData.data?.id;
+
+    if (!sessionID) {
+      throw new Error("Failed to create background session");
+    }
+
+    const task: BackgroundTask = {
+      id: taskId,
+      sessionID,
+      parentSessionID: input.parentSessionID,
+      parentMessageID: input.parentMessageID,
+      description: input.description,
+      prompt: input.prompt,
+      agent: input.agent,
+      status: "running",
+      startedAt: new Date(),
+      progress: {
+        toolCalls: 0,
+        lastUpdate: new Date(),
+      },
+    };
+
+    this.tasks.set(taskId, task);
+
+    // Fire-and-forget prompt
+    this.ctx.client.session
+      .prompt({
+        path: { id: sessionID },
+        body: {
+          parts: [{ type: "text", text: input.prompt }],
+          agent: input.agent,
+        },
+        query: { directory: this.ctx.directory },
+      })
+      .catch((error) => {
+        console.error(`[background-task] Failed to prompt session ${sessionID}:`, error);
+        task.status = "error";
+        task.error = error instanceof Error ? error.message : String(error);
+        task.completedAt = new Date();
+        this.markForNotification(task);
+      });
+
+    // Start polling if not already
+    this.startPolling();
+
+    return task;
+  }
+
+  async cancel(taskId: string): Promise<boolean> {
+    const task = this.tasks.get(taskId);
+    if (!task || task.status !== "running") {
+      return false;
+    }
+
+    try {
+      // Fire-and-forget abort
+      this.ctx.client.session
+        .abort({
+          path: { id: task.sessionID },
+          query: { directory: this.ctx.directory },
+        })
+        .catch((error) => {
+          console.error(`[background-task] Failed to abort session ${task.sessionID}:`, error);
+        });
+
+      task.status = "cancelled";
+      task.completedAt = new Date();
+      this.markForNotification(task);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async cancelAll(): Promise<number> {
+    let cancelled = 0;
+    for (const task of this.tasks.values()) {
+      if (task.status === "running") {
+        if (await this.cancel(task.id)) {
+          cancelled++;
+        }
+      }
+    }
+    return cancelled;
+  }
+
+  getTask(taskId: string): BackgroundTask | undefined {
+    return this.tasks.get(taskId);
+  }
+
+  getAllTasks(): BackgroundTask[] {
+    return Array.from(this.tasks.values());
+  }
+
+  /**
+   * Poll all running tasks and update their status.
+   * Called by background_list to ensure fresh status.
+   */
+  async refreshTaskStatus(): Promise<void> {
+    const runningTasks = this.getRunningTasks();
+    if (runningTasks.length === 0) return;
+
+    try {
+      // Get all session statuses in one call
+      const resp = await this.ctx.client.session.status({
+        query: { directory: this.ctx.directory },
+      });
+
+      const statusResp = resp as SessionStatusResponse;
+      const statusMap = statusResp.data || {};
+
+      for (const task of runningTasks) {
+        const sessionStatus = statusMap[task.sessionID];
+        const statusType = sessionStatus?.type;
+
+        if (statusType === "idle") {
+          task.status = "completed";
+          task.completedAt = new Date();
+          await this.getTaskResult(task.id);
+        }
+        // Store last known session status for debugging
+        (task as BackgroundTask & { _sessionStatus?: string })._sessionStatus = statusType;
+      }
+    } catch (error) {
+      console.error("[background-task] Failed to refresh task status:", error);
+      // Don't mark all tasks as error - they may still be running
+    }
+  }
+
+  getRunningTasks(): BackgroundTask[] {
+    return this.getAllTasks().filter((t) => t.status === "running");
+  }
+
+  async getTaskResult(taskId: string): Promise<string | undefined> {
+    const task = this.tasks.get(taskId);
+    if (!task || task.status === "running") {
+      return undefined;
+    }
+
+    if (task.result) {
+      return task.result;
+    }
+
+    // Fetch result from session messages
+    try {
+      const resp = await this.ctx.client.session.messages({
+        path: { id: task.sessionID },
+        query: { directory: this.ctx.directory },
+      });
+
+      const messagesResp = resp as SessionMessagesResponse;
+      const messages = messagesResp.data || [];
+      const lastAssistant = [...messages].reverse().find((m) => m.info?.role === "assistant");
+
+      if (lastAssistant) {
+        const textParts = lastAssistant.parts?.filter((p) => p.type === "text") || [];
+        task.result = textParts.map((p) => p.text || "").join("\n");
+        return task.result;
+      }
+    } catch (error) {
+      console.error(`[background-task] Failed to fetch result for task ${taskId}:`, error);
+    }
+
+    return undefined;
+  }
+
+  formatTaskStatus(task: BackgroundTask): string {
+    const duration = formatDuration(task.startedAt, task.completedAt);
+    const status = task.status.toUpperCase();
+
+    let output = `## Task: ${task.description}\n\n`;
+    output += `| Field | Value |\n|-------|-------|\n`;
+    output += `| ID | ${task.id} |\n`;
+    output += `| Status | ${status} |\n`;
+    output += `| Agent | ${task.agent} |\n`;
+    output += `| Duration | ${duration} |\n`;
+
+    if (task.progress) {
+      output += `| Tool Calls | ${task.progress.toolCalls} |\n`;
+      if (task.progress.lastTool) {
+        output += `| Last Tool | ${task.progress.lastTool} |\n`;
+      }
+    }
+
+    if (task.error) {
+      output += `\n### Error\n${task.error}\n`;
+    }
+
+    return output;
+  }
+
+  private startPolling(): void {
+    if (this.pollingInterval) return;
+
+    this.pollingInterval = setInterval(() => {
+      this.pollRunningTasks();
+    }, POLL_INTERVAL_MS);
+  }
+
+  private stopPolling(): void {
+    if (this.pollingInterval) {
+      clearInterval(this.pollingInterval);
+      this.pollingInterval = undefined;
+    }
+  }
+
+  private cleanupOldTasks(): void {
+    const now = Date.now();
+    for (const [taskId, task] of this.tasks) {
+      // Only cleanup completed/cancelled/error tasks
+      if (task.status === "running") continue;
+
+      const completedAt = task.completedAt?.getTime() || 0;
+      if (now - completedAt > TASK_TTL_MS) {
+        this.tasks.delete(taskId);
+      }
+    }
+  }
+
+  private async pollRunningTasks(): Promise<void> {
+    // Cleanup old completed tasks to prevent memory leak
+    this.cleanupOldTasks();
+
+    const runningTasks = this.getRunningTasks();
+
+    if (runningTasks.length === 0) {
+      this.stopPolling();
+      return;
+    }
+
+    try {
+      // Get all session statuses in one call
+      const resp = await this.ctx.client.session.status({
+        query: { directory: this.ctx.directory },
+      });
+
+      const statusResp = resp as SessionStatusResponse;
+      const statusMap = statusResp.data || {};
+
+      for (const task of runningTasks) {
+        const sessionStatus = statusMap[task.sessionID];
+        const statusType = sessionStatus?.type;
+
+        console.log(`[background-task] Poll ${task.id}: session=${task.sessionID} status=${statusType}`);
+
+        if (statusType === "idle") {
+          // Task completed
+          task.status = "completed";
+          task.completedAt = new Date();
+          await this.getTaskResult(task.id); // Cache the result
+          this.markForNotification(task);
+
+          await this.ctx.client.tui
+            .showToast({
+              body: {
+                title: "Background Task Complete",
+                message: task.description,
+                variant: "success",
+                duration: 5000,
+              },
+            })
+            .catch((error) => {
+              console.error(`[background-task] Failed to show toast for task ${task.id}:`, error);
+            });
+        }
+      }
+    } catch (error) {
+      console.error("[background-task] Failed to poll tasks:", error);
+      // Don't mark tasks as error - they may still be running, just can't check
+    }
+  }
+
+  private markForNotification(task: BackgroundTask): void {
+    const existing = this.notifications.get(task.parentSessionID) || [];
+    existing.push(task);
+    this.notifications.set(task.parentSessionID, existing);
+  }
+
+  getPendingNotifications(parentSessionID: string): BackgroundTask[] {
+    const notifications = this.notifications.get(parentSessionID) || [];
+    this.notifications.delete(parentSessionID);
+    return notifications;
+  }
+
+  handleEvent(event: { type: string; properties?: unknown }): void {
+    const props = event.properties as Record<string, unknown> | undefined;
+
+    // Track tool usage for progress
+    if (event.type === "message.part.updated") {
+      const info = props?.info as Record<string, unknown> | undefined;
+      const sessionID = info?.sessionID as string | undefined;
+      const partType = info?.type as string | undefined;
+
+      if (sessionID && partType === "tool_use") {
+        for (const task of this.tasks.values()) {
+          if (task.sessionID === sessionID && task.status === "running") {
+            if (!task.progress) {
+              task.progress = { toolCalls: 0, lastUpdate: new Date() };
+            }
+            task.progress.toolCalls++;
+            task.progress.lastTool = (info?.name as string) || undefined;
+            task.progress.lastUpdate = new Date();
+            break;
+          }
+        }
+      }
+    }
+
+    // Cleanup on session delete
+    if (event.type === "session.deleted") {
+      const sessionInfo = props?.info as { id?: string } | undefined;
+      if (sessionInfo?.id) {
+        for (const task of this.tasks.values()) {
+          if (task.sessionID === sessionInfo.id && task.status === "running") {
+            task.status = "cancelled";
+            task.completedAt = new Date();
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,145 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import type { BackgroundTaskManager } from "./manager";
+
+export function createBackgroundTaskTools(manager: BackgroundTaskManager) {
+  const background_task = tool({
+    description: `Launch a task to run in the background using a subagent.
+The task runs independently while you continue working.
+Use background_output to check progress or get results when complete.
+Useful for: parallel research, concurrent implementation, async reviews.`,
+    args: {
+      description: tool.schema.string().describe("Short description of the task (shown in status)"),
+      prompt: tool.schema.string().describe("Full prompt/instructions for the background agent"),
+      agent: tool.schema.string().describe("Agent to use (e.g., 'codebase-analyzer', 'implementer')"),
+    },
+    execute: async (args, ctx) => {
+      try {
+        const task = await manager.launch({
+          description: args.description,
+          prompt: args.prompt,
+          agent: args.agent,
+          parentSessionID: ctx.sessionID,
+          parentMessageID: ctx.messageID || "",
+        });
+
+        return `## Background Task Launched
+
+| Field | Value |
+|-------|-------|
+| Task ID | ${task.id} |
+| Agent | ${args.agent} |
+| Status | RUNNING |
+
+Use \`background_output\` with task_id="${task.id}" to check progress or get results.`;
+      } catch (error) {
+        return `Failed to launch background task: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    },
+  });
+
+  const background_output = tool({
+    description: `Get status or results from a background task.
+Returns immediately with current status. Use background_list to poll for completion.`,
+    args: {
+      task_id: tool.schema.string().describe("ID of the task to check (e.g., 'bg_abc12345')"),
+    },
+    execute: async (args) => {
+      const { task_id } = args;
+
+      const task = manager.getTask(task_id);
+      if (!task) {
+        return `Task not found: ${task_id}`;
+      }
+
+      // Format status
+      let output = manager.formatTaskStatus(task);
+
+      // Include result if completed
+      if (task.status === "completed") {
+        const result = await manager.getTaskResult(task_id);
+        if (result) {
+          output += `\n### Result\n${result}\n`;
+        }
+      }
+
+      return output;
+    },
+  });
+
+  const background_cancel = tool({
+    description: `Cancel a running background task or all tasks.`,
+    args: {
+      task_id: tool.schema.string().optional().describe("ID of the task to cancel (omit to cancel all)"),
+      all: tool.schema.boolean().optional().describe("Cancel all running tasks (default: false)"),
+    },
+    execute: async (args) => {
+      const { task_id, all = false } = args;
+
+      if (all) {
+        const cancelled = await manager.cancelAll();
+        return `Cancelled ${cancelled} running task(s).`;
+      }
+
+      if (!task_id) {
+        return "Provide task_id or set all=true to cancel tasks.";
+      }
+
+      const success = await manager.cancel(task_id);
+      if (success) {
+        return `Task ${task_id} cancelled.`;
+      }
+
+      return `Could not cancel task ${task_id}. It may already be completed or not exist.`;
+    },
+  });
+
+  const background_list = tool({
+    description: `List all background tasks and their status.`,
+    args: {},
+    execute: async () => {
+      // Refresh status of running tasks before returning
+      await manager.refreshTaskStatus();
+      const tasks = manager.getAllTasks();
+
+      if (tasks.length === 0) {
+        return "No background tasks.";
+      }
+
+      const completed = tasks.filter((t) => t.status === "completed").length;
+      const errored = tasks.filter((t) => t.status === "error").length;
+      const running = tasks.filter((t) => t.status === "running").length;
+      const total = tasks.length;
+      const allDone = running === 0;
+
+      let output = "## Background Tasks\n\n";
+      output += `**Status: ${completed + errored}/${total} done${allDone ? " ✓ ALL COMPLETE" : ` (${running} still running)`}**\n\n`;
+      output += "| ID | Description | Agent | Status | Duration | Session |\n";
+      output += "|----|-------------|-------|--------|----------|---------|";
+
+      for (const task of tasks) {
+        const duration = task.completedAt
+          ? `${Math.round((task.completedAt.getTime() - task.startedAt.getTime()) / 1000)}s`
+          : `${Math.round((Date.now() - task.startedAt.getTime()) / 1000)}s`;
+
+        // Show session status for debugging
+        const sessionStatus = (task as { _sessionStatus?: string })._sessionStatus || "?";
+        const statusDisplay = task.status === "running" ? `${task.status} (${sessionStatus})` : task.status;
+
+        output += `| ${task.id} | ${task.description} | ${task.agent} | ${statusDisplay} | ${duration} | ${task.sessionID} |\n`;
+      }
+
+      if (allDone) {
+        output += "\n**→ All tasks complete. Proceed to collect results with background_output.**";
+      }
+
+      return output;
+    },
+  });
+
+  return {
+    background_task,
+    background_output,
+    background_cancel,
+    background_list,
+  };
+}

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";
+  },
+});