opencode-async-agent 1.0.0 → 1.0.1

package/src/plugin/plugin.ts

@@ -1,200 +0,0 @@
-/**
- * async-agent
- * Unified delegation system for OpenCode
- *
- * Based on oh-my-opencode by @code-yeongyu (MIT License)
- * https://github.com/code-yeongyu/oh-my-opencode
- */
-
-import type { Plugin } from "@opencode-ai/plugin"
-import type { Event } from "@opencode-ai/sdk"
-import type { OpencodeClient } from "./types"
-import { createLogger } from "./utils"
-import { DelegationManager } from "./manager"
-import {
-	createDelegate,
-	createDelegationRead,
-	createDelegationList,
-	createDelegationCancel,
-	createDelegationResume,
-} from "./tools"
-import { DELEGATION_RULES, formatDelegationContext, readBgAgentsConfig } from "./rules"
-
-// Slash command name — user types /delegation in chat
-const delegationCommand = "delegation"
-
-export const AsyncAgentPlugin: Plugin = async (ctx) => {
-	const { client } = ctx
-
-	const log = createLogger(client as OpencodeClient)
-	const manager = new DelegationManager(client as OpencodeClient, log)
-
-	await manager.debugLog("AsyncAgentPlugin initialized")
-
-	return {
-		// Handle /delegation slash command execution
-		"command.execute.before": async (input: { command: string; sessionID: string }) => {
-			if (input.command !== delegationCommand) return
-
-			const typedClient = client as OpencodeClient
-
-			// Query child sessions of current session from OpenCode API (survives reboots)
-			let childSessions: any[] = []
-			try {
-				const result = await typedClient.session.children({
-					path: { id: input.sessionID },
-				})
-				childSessions = (result.data ?? []) as any[]
-			} catch {
-				// Fallback to in-memory only if API fails
-			}
-
-			// Filter for delegation sessions — created with title "Delegation: <agent>"
-			const delegationSessions = childSessions.filter(
-				(s: any) => s.title?.startsWith("Delegation:"),
-			)
-
-			// Get in-memory state for extra metadata (status, duration, agent)
-			const inMemory = manager.listAllDelegations()
-			const inMemoryMap = new Map(inMemory.map((d) => [d.id, d]))
-
-			let message: string
-			if (delegationSessions.length === 0 && inMemory.length === 0) {
-				message = "No delegations found for this session."
-			} else {
-				const lines: string[] = []
-				const seen = new Set<string>()
-				const entries: {
-					id: string
-					title: string
-					agent: string
-					status: string
-					duration: string
-					started: string
-				}[] = []
-
-				// Persisted child sessions from API — survive reboots
-				for (const s of delegationSessions) {
-					seen.add(s.id)
-					const mem = inMemoryMap.get(s.id)
-					// Extract agent name from title "Delegation: <agent>"
-					const agent = mem?.agent ?? s.title?.replace("Delegation: ", "") ?? "unknown"
-					const status = mem?.status?.toUpperCase() ?? "PERSISTED"
-					const duration = mem?.duration ?? "—"
-					// time.created is already in ms — do NOT multiply by 1000
-					const created = s.time?.created
-						? new Date(s.time.created).toISOString()
-						: mem?.startedAt?.toISOString() ?? "—"
-
-					entries.push({
-						id: s.id,
-						title: mem?.title ?? s.title ?? "—",
-						agent,
-						status,
-						duration,
-						started: created,
-					})
-				}
-
-				// In-memory delegations not in API yet (just launched, or API miss)
-				for (const d of inMemory) {
-					if (seen.has(d.id)) continue
-					// Only include delegations belonging to this parent session
-					entries.push({
-						id: d.id,
-						title: d.title ?? d.description?.slice(0, 60) ?? "—",
-						agent: d.agent ?? "unknown",
-						status: d.status?.toUpperCase() ?? "UNKNOWN",
-						duration: d.duration ?? "—",
-						started: d.startedAt?.toISOString() ?? "—",
-					})
-				}
-
-				lines.push(`## Delegations (${entries.length})\n`)
-
-				for (const e of entries) {
-					lines.push(`**[${e.id}]** ${e.title}`)
-					lines.push(`  Status: ${e.status} | Agent: ${e.agent} | Duration: ${e.duration}`)
-					lines.push(`  Started: ${e.started}`)
-					lines.push(`  \`opencode -s ${e.id}\``)
-					lines.push("")
-				}
-
-				message = lines.join("\n")
-			}
-
-			// Send output to the user's session
-			await typedClient.session.prompt({
-				path: { id: input.sessionID },
-				body: {
-					noReply: true,
-					parts: [{ type: "text", text: message }],
-				},
-			})
-
-			throw new Error("Command handled by async-agent plugin")
-		},
-
-		tool: {
-			delegate: createDelegate(manager),
-			delegation_read: createDelegationRead(manager),
-			delegation_list: createDelegationList(manager),
-			delegation_cancel: createDelegationCancel(manager),
-			delegation_resume: createDelegationResume(manager),
-		},
-
-		// Register /delegation slash command
-		config: async (input: any) => {
-			if (!input.command) input.command = {}
-			input.command[delegationCommand] = {
-				template: "Show all background delegation sessions with their status, IDs, agents, and metadata.",
-				description: "List all background delegations",
-			}
-		},
-
-		// Inject delegation rules + async-agent.md config into system prompt
-		"experimental.chat.system.transform": async (
-			_input: { sessionID?: string; model: any },
-			output: { system: string[] },
-		): Promise<void> => {
-			output.system.push(DELEGATION_RULES)
-
-			// Read user's model config from ~/.config/opencode/async-agent.md
-			const bgConfig = await readBgAgentsConfig()
-			if (bgConfig.trim()) {
-				output.system.push(`<async-agent-config>\n${bgConfig}\n</async-agent-config>`)
-			}
-		},
-
-		// Inject active delegation context during session compaction
-		"experimental.session.compacting": async (
-			_input: { sessionID: string },
-			output: { context: string[] },
-		): Promise<void> => {
-			const running = manager.getRunningDelegations().map((d) => ({
-				id: d.id,
-				agent: d.agent,
-				status: d.status,
-				startedAt: d.startedAt,
-			}))
-
-			// Only inject if there are active delegations
-			if (running.length > 0) {
-				output.context.push(formatDelegationContext(running, []))
-			}
-		},
-
-		event: async (input: { event: Event }): Promise<void> => {
-			const { event } = input
-			if (event.type === "session.idle") {
-				const sessionID = (event.properties as any)?.sessionID
-				const delegation = manager.findBySession(sessionID)
-				if (delegation) {
-					await manager.handleSessionIdle(sessionID)
-				}
-			}
-		},
-	}
-}
-
-export default AsyncAgentPlugin

package/src/plugin/rules.ts

@@ -1,115 +0,0 @@
-// System prompt rules injected to teach the agent how to use delegation tools
-export const DELEGATION_RULES = `<system-reminder>
-<delegation-system>
-
-## Async Delegation
-
-You have tools for parallel background work:
-- \`delegate(prompt, agent)\` - Launch task, returns ID immediately
-- \`delegate(prompt, agent, model)\` - Launch task with specific model override
-- \`delegation_read(id)\` - Retrieve completed result
-- \`delegation_list()\` - List delegations (use sparingly)
-- \`delegation_cancel(id|all)\` - Cancel running task(s)
-- \`delegation_resume(id, prompt?)\` - Continue cancelled task (same session)
-
-## How It Works
-
-1. Call \`delegate()\` - Get task ID immediately, continue working
-2. Receive \`<system-reminder>\` notification when complete
-3. Call \`delegation_read(id)\` to get the actual result
-
-## Model Override
-
-The \`delegate\` tool accepts an optional \`model\` parameter in "provider/model" format.
-Example: \`delegate(prompt, agent, model="minimax/MiniMax-M2.5")\`
-If not specified, the agent's default model is used.
-
-## Critical Constraints
-
-**NEVER poll \`delegation_list\` to check completion.**
-You WILL be notified via \`<system-reminder>\`. Polling wastes tokens.
-
-**NEVER wait idle.** Always have productive work while delegations run.
-
-**Cancelled tasks can be resumed** with \`delegation_resume()\` - same session, full context.
-
-</delegation-system>
-</system-reminder>`
-
-// Read user's async-agent(s).md config file — contains model preferences for delegation
-// Tries both async-agents.md and async-agent.md, returns first found or empty string
-export async function readBgAgentsConfig(): Promise<string> {
-	const { homedir } = await import("os")
-	const { readFile } = await import("fs/promises")
-	const { join } = await import("path")
-
-	const configDir = join(homedir(), ".config", "opencode")
-	for (const name of ["async-agents.md", "async-agent.md"]) {
-		try {
-			return await readFile(join(configDir, name), "utf-8")
-		} catch {}
-	}
-	return ""
-}
-
-// Context injected during compaction so the agent remembers active delegations
-interface DelegationForContext {
-	id: string
-	agent?: string
-	title?: string
-	description?: string
-	status: string
-	startedAt?: Date
-	duration?: string
-}
-
-export function formatDelegationContext(
-	running: DelegationForContext[],
-	completed: DelegationForContext[],
-): string {
-	const sections: string[] = ["<delegation-context>"]
-
-	if (running.length > 0) {
-		sections.push("## Running Delegations")
-		sections.push("")
-		for (const d of running) {
-			sections.push(`### \`${d.id}\`${d.agent ? ` (${d.agent})` : ""}`)
-			if (d.startedAt) {
-				sections.push(`**Started:** ${d.startedAt.toISOString()}`)
-			}
-			sections.push("")
-		}
-		sections.push("> **Note:** You WILL be notified via \`<system-reminder>\` when delegations complete.",
-		)
-		sections.push("> Do NOT poll \`delegation_list\` - continue productive work.")
-		sections.push("")
-	}
-
-	if (completed.length > 0) {
-		sections.push("## Recent Completed Delegations")
-		sections.push("")
-		for (const d of completed) {
-			const statusEmoji =
-				d.status === "completed"
-					? "✅"
-					: d.status === "error"
-						? "❌"
-						: d.status === "timeout"
-							? "⏱️"
-							: "🚫"
-			sections.push(`### ${statusEmoji} \`${d.id}\``)
-			sections.push(`**Status:** ${d.status}`)
-			if (d.duration) sections.push(`**Duration:** ${d.duration}`)
-			sections.push("")
-		}
-		sections.push("> Use \`delegation_list()\` to see all delegations.")
-		sections.push("")
-	}
-
-	sections.push("## Retrieval")
-	sections.push('Use \`delegation_read("id")\` to access results.')
-	sections.push("Use \`delegation_read(id, mode=\"full\")\` for full conversation.")
-	sections.push("</delegation-context>")
-
-	return sections.join("\n")
-}

package/src/plugin/tools.ts

@@ -1,230 +0,0 @@
-import { type ToolContext, tool } from "@opencode-ai/plugin"
-import type { ReadDelegationArgs } from "./types"
-import type { DelegationManager } from "./manager"
-
-// ---- Arg interfaces ----
-
-interface DelegateArgs {
-	prompt: string
-	agent: string
-	model?: string
-}
-
-interface CancelArgs {
-	id?: string
-	all?: boolean
-}
-
-interface ResumeArgs {
-	id: string
-	prompt?: string
-}
-
-// ---- Tool creators ----
-
-export function createDelegate(manager: DelegationManager): ReturnType<typeof tool> {
-	return tool({
-		description: `Delegate a task to an agent. Returns immediately with the session ID.
-
-Use this for:
-- Research tasks (will be auto-saved)
-- Parallel work that can run in background
-- Any task where you want persistent, retrievable output
-
-On completion, a notification will arrive with the session ID, status, duration.
-Use \`delegation_read\` with the session ID to retrieve the result.`,
-		args: {
-			prompt: tool.schema
-				.string()
-				.describe("The full detailed prompt for the agent. Must be in English."),
-			agent: tool.schema
-				.string()
-				.describe(
-					'Agent to delegate to: "explore" (codebase search), "researcher" (external research), etc.',
-				),
-			model: tool.schema
-				.string()
-				.optional()
-				.describe(
-					'Override model for this delegation. Format: "provider/model" (e.g. "minimax/MiniMax-M2.5"). If not set, uses the agent default.',
-				),
-		},
-		async execute(args: DelegateArgs, toolCtx: ToolContext): Promise<string> {
-			if (!toolCtx?.sessionID) {
-				return "❌ delegate requires sessionID. This is a system error."
-			}
-			if (!toolCtx?.messageID) {
-				return "❌ delegate requires messageID. This is a system error."
-			}
-
-			// Block sub-agents from using delegation
-			if (manager.findBySession(toolCtx.sessionID)) {
-				return "❌ Sub-agents cannot delegate tasks. Only the main agent can use delegation tools."
-			}
-
-			try {
-				const delegation = await manager.delegate({
-					parentSessionID: toolCtx.sessionID,
-					parentMessageID: toolCtx.messageID,
-					parentAgent: toolCtx.agent,
-					prompt: args.prompt,
-					agent: args.agent,
-					model: args.model,
-				})
-
-				const pendingCount = manager.getPendingCount(toolCtx.sessionID)
-
-				let response = `Delegation started: ${delegation.id}\nAgent: ${args.agent}`
-				if (pendingCount > 1) {
-					response += `\n\n${pendingCount} delegations now active.`
-				}
-				response += `\n\nYou WILL be notified via <system-reminder> when complete. Do NOT poll delegation_list().`
-
-				return response
-			} catch (error) {
-				return `❌ Delegation failed:\n\n${error instanceof Error ? error.message : "Unknown error"}`
-			}
-		},
-	})
-}
-
-export function createDelegationRead(manager: DelegationManager): ReturnType<typeof tool> {
-	return tool({
-		description: `Read the output of a delegation by its ID.
-
-Modes:
-- simple (default): Returns just the final result
-- full: Returns all messages in the session with timestamps
-
-Use filters to get specific parts of the conversation.`,
-		args: {
-			id: tool.schema.string().describe("The delegation session ID"),
-			mode: tool.schema
-				.enum(["simple", "full"])
-				.optional()
-				.describe("Output mode: 'simple' for result only, 'full' for all messages"),
-			include_thinking: tool.schema
-				.boolean()
-				.optional()
-				.describe("Include thinking/reasoning blocks in full mode"),
-			include_tools: tool.schema
-				.boolean()
-				.optional()
-				.describe("Include tool results in full mode"),
-			since_message_id: tool.schema
-				.string()
-				.optional()
-				.describe("Return only messages after this message ID (full mode only)"),
-			limit: tool.schema
-				.number()
-				.optional()
-				.describe("Max messages to return, capped at 100 (full mode only)"),
-		},
-		async execute(args: ReadDelegationArgs, toolCtx: ToolContext): Promise<string> {
-			if (!toolCtx?.sessionID) {
-				return "❌ delegation_read requires sessionID. This is a system error."
-			}
-
-			try {
-				return await manager.readDelegation(args)
-			} catch (error) {
-				return `❌ Error reading delegation: ${error instanceof Error ? error.message : "Unknown error"}`
-			}
-		},
-	})
-}
-
-export function createDelegationList(manager: DelegationManager): ReturnType<typeof tool> {
-	return tool({
-		description: `List all delegations for the current session.
-Shows running, completed, cancelled, and error tasks with metadata.`,
-		args: {},
-		async execute(_args: Record<string, never>, toolCtx: ToolContext): Promise<string> {
-			if (!toolCtx?.sessionID) {
-				return "❌ delegation_list requires sessionID. This is a system error."
-			}
-
-			const delegations = await manager.listDelegations(toolCtx.sessionID)
-
-			if (delegations.length === 0) {
-				return "No delegations found for this session."
-			}
-
-			const lines = delegations.map((d) => {
-				const titlePart = d.title ? ` | ${d.title}` : ""
-				const durationPart = d.duration ? ` (${d.duration})` : ""
-				const descPart = d.description ? `\n  → ${d.description.slice(0, 100)}${d.description.length > 100 ? "..." : ""}` : ""
-				return `- **${d.id}**${titlePart} [${d.status}]${durationPart}${descPart}`
-			})
-
-			return `## Delegations\n\n${lines.join("\n")}`
-		},
-	})
-}
-
-export function createDelegationCancel(manager: DelegationManager): ReturnType<typeof tool> {
-	return tool({
-		description: `Cancel a running delegation by ID, or cancel all running delegations.
-
-Cancelled tasks can be resumed later with delegation_resume().`,
-		args: {
-			id: tool.schema.string().optional().describe("Task ID to cancel"),
-			all: tool.schema.boolean().optional().describe("Cancel ALL running delegations"),
-		},
-		async execute(args: CancelArgs, toolCtx: ToolContext): Promise<string> {
-			if (!toolCtx?.sessionID) {
-				return "❌ delegation_cancel requires sessionID. This is a system error."
-			}
-
-			try {
-				if (args.all) {
-					const cancelled = await manager.cancelAll(toolCtx.sessionID)
-					if (cancelled.length === 0) {
-						return "No running delegations to cancel."
-					}
-					return `Cancelled ${cancelled.length} delegation(s):\n${cancelled.map(id => `- ${id}`).join("\n")}`
-				}
-
-				if (!args.id) {
-					return "❌ Must provide either 'id' or 'all=true'"
-				}
-
-				const success = await manager.cancel(args.id)
-				if (!success) {
-					return `❌ Could not cancel "${args.id}". Task may not exist or is not running.`
-				}
-
-				return `✅ Cancelled delegation: ${args.id}\n\nYou can resume it later with delegation_resume(id="${args.id}")`
-			} catch (error) {
-				return `❌ Error cancelling: ${error instanceof Error ? error.message : "Unknown error"}`
-			}
-		},
-	})
-}
-
-export function createDelegationResume(manager: DelegationManager): ReturnType<typeof tool> {
-	return tool({
-		description: `Resume a cancelled or errored delegation by sending a new prompt to the same session.
-
-The agent will have access to the previous conversation context.`,
-		args: {
-			id: tool.schema.string().describe("Task ID to resume"),
-			prompt: tool.schema
-				.string()
-				.optional()
-				.describe("Optional prompt to send (default: 'Continue from where you left off.')"),
-		},
-		async execute(args: ResumeArgs, toolCtx: ToolContext): Promise<string> {
-			if (!toolCtx?.sessionID) {
-				return "❌ delegation_resume requires sessionID. This is a system error."
-			}
-
-			try {
-				const delegation = await manager.resume(args.id, args.prompt)
-				return `✅ Resumed delegation: ${delegation.id}\nAgent: ${delegation.agent}\nStatus: ${delegation.status}`
-			} catch (error) {
-				return `❌ Error resuming: ${error instanceof Error ? error.message : "Unknown error"}`
-			}
-		},
-	})
-}

package/src/plugin/types.ts

@@ -1,80 +0,0 @@
-import type { Message, Part } from "@opencode-ai/sdk"
-import type { createOpencodeClient } from "@opencode-ai/sdk"
-
-// OpenCode client instance type
-export type OpencodeClient = ReturnType<typeof createOpencodeClient>
-
-// Logger returned by createLogger
-export type Logger = {
-	debug: (msg: string) => void
-	info: (msg: string) => void
-	warn: (msg: string) => void
-	error: (msg: string) => void
-}
-
-// 15 minute max run time per delegation
-export const MAX_RUN_TIME_MS = 15 * 60 * 1000
-
-export interface SessionMessageItem {
-	info: Message
-	parts: Part[]
-}
-
-export interface AssistantSessionMessageItem {
-	info: Message & { role: "assistant" }
-	parts: Part[]
-}
-
-export interface DelegationProgress {
-	toolCalls: number
-	lastUpdate: Date
-	lastMessage?: string
-	lastMessageAt?: Date
-}
-
-export interface Delegation {
-	id: string // OpenCode session ID (same as sessionID — used for delegation_read, opencode -s, etc.)
-	sessionID: string // Same as id — kept for clarity in API calls
-	parentSessionID: string
-	parentMessageID: string
-	parentAgent: string
-	prompt: string
-	agent: string
-	model?: string // Full "provider/model" string (e.g. "minimax/MiniMax-M2.5")
-	status: "running" | "completed" | "error" | "cancelled" | "timeout"
-	startedAt: Date
-	completedAt?: Date
-	duration?: string
-	progress: DelegationProgress
-	error?: string
-	title?: string
-	description?: string
-}
-
-export interface DelegateInput {
-	parentSessionID: string
-	parentMessageID: string
-	parentAgent: string
-	prompt: string
-	agent: string
-	model?: string // Full "provider/model" string — split via parseModel() before passing to session.prompt()
-}
-
-export interface DelegationListItem {
-	id: string
-	status: string
-	title?: string
-	description?: string
-	agent?: string
-	duration?: string
-	startedAt?: Date
-}
-
-export interface ReadDelegationArgs {
-	id: string
-	mode?: "simple" | "full"
-	include_thinking?: boolean
-	include_tools?: boolean
-	since_message_id?: string
-	limit?: number
-}

package/src/plugin/utils.ts

@@ -1,51 +0,0 @@
-import type { OpencodeClient, Logger } from "./types"
-
-// Structured logger → OpenCode log API
-// Catches errors silently to avoid disrupting tool execution
-export function createLogger(client: OpencodeClient): Logger {
-	const log = (level: "debug" | "info" | "warn" | "error", message: string) =>
-		client.app.log({ body: { service: "async-agent", level, message } }).catch(() => {})
-	return {
-		debug: (msg: string) => log("debug", msg),
-		info: (msg: string) => log("info", msg),
-		warn: (msg: string) => log("warn", msg),
-		error: (msg: string) => log("error", msg),
-	}
-}
-
-// Shows toast in OpenCode TUI (top-right notification)
-// Casts client to any + optional chaining = graceful no-op if unavailable
-export function showToast(
-	client: OpencodeClient,
-	title: string,
-	message: string,
-	variant: "info" | "success" | "error" = "info",
-	duration = 3000,
-) {
-	const tuiClient = client as any
-	if (!tuiClient.tui?.showToast) return
-	tuiClient.tui.showToast({
-		body: { title, message, variant, duration },
-	}).catch(() => {})
-}
-
-// Format ms duration into human-readable string (e.g. "2m 30s")
-export function formatDuration(startedAt: Date, completedAt?: Date): string {
-	const end = completedAt || new Date()
-	const diffMs = end.getTime() - startedAt.getTime()
-	const diffSec = Math.floor(diffMs / 1000)
-
-	if (diffSec < 60) {
-		return `${diffSec}s`
-	}
-
-	const diffMin = Math.floor(diffSec / 60)
-	if (diffMin < 60) {
-		const secs = diffSec % 60
-		return secs > 0 ? `${diffMin}m ${secs}s` : `${diffMin}m`
-	}
-
-	const diffHour = Math.floor(diffMin / 60)
-	const mins = diffMin % 60
-	return mins > 0 ? `${diffHour}h ${mins}m` : `${diffHour}h`
-}