opencode-async-agent 1.0.0

package/AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md — opencode-async-agent
+
+## What This Is
+
+OpenCode plugin providing async background delegation. TypeScript source in `src/plugin/`, bundled via esbuild to `dist/async-agent.js`. No test framework. No linter configured.
+
+## Build
+
+```bash
+# Install deps
+npm install
+
+# Build
+npm run build
+
+# Verify build worked
+ls -la dist/async-agent.js
+```
+
+## Project Structure
+
+```
+src/plugin/
+  plugin.ts    — Entry point. Registers tools, hooks, slash commands, events
+  manager.ts   — DelegationManager class. Core state machine for delegations
+  tools.ts     — Tool factories (delegate, read, list, cancel, resume)
+  types.ts     — All interfaces and type definitions
+  rules.ts     — System prompt injection + compaction context
+  utils.ts     — Logger, toast, formatDuration helpers
+dist/
+  async-agent.js  — Bundled output (committed)
+```
+
+## Code Style
+
+### TypeScript
+- Strict types, no `any` except when casting OpenCode client for optional APIs
+- Use `type` imports: `import type { Foo } from "./types"`
+- Tabs for indentation, no semicolons (except rare cases)
+- Double quotes for strings
+- Interfaces over type aliases for object shapes
+
+### Naming
+- PascalCase: classes (`DelegationManager`), interfaces (`Delegation`, `DelegateInput`)
+- camelCase: functions (`createDelegate`), variables, methods
+- UPPER_SNAKE: constants (`MAX_RUN_TIME_MS`, `DELEGATION_RULES`)
+- Slash command names: kebab-case strings (`"delegation"`)
+
+### Imports
+- Group order: external packages → local types → local modules
+- Always use relative paths (`"./types"`, `"./manager"`)
+- External deps are `@opencode-ai/plugin` and `@opencode-ai/sdk` only
+
+### Functions
+- Tool creators follow factory pattern: `createXxx(manager) → tool({...})`
+- Tools return `string` (success message or error text), never throw to caller
+- Prefix user-facing errors with `❌`
+- Manager methods are `async` and return typed results
+
+### Error Handling
+- Tools: try/catch → return error string (never throw)
+- Async fire-and-forget: `.catch(() => {})` on non-critical promises (logging, toasts)
+- Manager notifications: catch and log, never crash the plugin
+- SDK calls that might fail: wrap in try/catch, ignore or log
+
+### Plugin Hooks Pattern
+- `config` hook → register slash commands via `input.command[name] = { template, description }`
+- `command.execute.before` hook → handle slash command, throw Error to signal "handled"
+- `event` hook → listen for `session.idle`, `session.deleted` etc.
+- `experimental.chat.system.transform` → inject into system prompt
+- `experimental.session.compacting` → inject context during compaction
+
+### State Management
+- All state in `DelegationManager.delegations: Map<string, Delegation>`
+- In-memory only, no persistence to disk
+- Delegation ID = OpenCode session ID (same value)
+- Status flow: `running` → `completed` | `error` | `cancelled` | `timeout`
+
+## Key Patterns
+
+### Adding a new tool
+1. Define args interface in `tools.ts`
+2. Create factory function `createXxx(manager)` returning `tool({...})`
+3. Register in `plugin.ts` under the `tool:` object
+4. Add any needed manager methods in `manager.ts`
+5. Rebuild
+
+### Adding a new slash command
+1. Define command name constant in `plugin.ts`
+2. Register in `config` hook: `input.command[name] = { template, description }`
+3. Handle in `command.execute.before` hook, throw Error when handled
+4. Send output via `client.session.prompt({ path: { id: sessionID }, body: { noReply: true, parts: [...] } })`
+
+### Tool execute signature
+```typescript
+async execute(args: ArgsType, toolCtx: ToolContext): Promise<string>
+```
+- `toolCtx.sessionID` — current chat session
+- `toolCtx.messageID` — current message
+- `toolCtx.agent` — current agent name
+- Always guard: `if (!toolCtx?.sessionID) return "❌ ..."`
+
+## External Dependencies
+
+- `@opencode-ai/plugin` — tool() factory, ToolContext, Plugin type (external, not bundled)
+- `@opencode-ai/sdk` — OpenCode client types, Event, Message, Part (external, not bundled)
+- `esbuild` — build tool (devDependency)
+
+## No Tests
+
+No test framework is configured. Validate changes by building and running in OpenCode.
+
+## Common Gotchas
+
+- `dist/` is committed — always rebuild after changes
+- `@opencode-ai/*` packages are marked external in esbuild — they're provided by the OpenCode runtime
+- Delegation ID and session ID are the same value (kept as two fields for clarity)
+- `noReply: true` on prompts means "show to user but don't trigger AI response"
+- Throwing in `command.execute.before` signals the command was handled by this plugin

package/README.md

@@ -0,0 +1,151 @@
+# OpenCode Async Agent Plugin
+
+Async background delegation for OpenCode — run multiple AI agents in parallel.
+
+
+## Features
+
+- **Parallel Execution** — Delegate tasks to background agents while you continue working
+- **Multiple Agents** — Use explore, researcher, or any custom agent
+- **Model Override** — Specify which model runs each task (e.g., `minimax/MiniMax-M2.5`)
+- **Session Persistence** — Resume cancelled tasks without losing context
+- **Slash Commands** — `/delegation` to list all delegation status and metadata
+- **System Prompt Injection** — Your `~/.config/opencode/async-agent.md` config is automatically loaded
+
+## Installation
+
+### Manual Setup (Current)
+
+1. **Clone and build:**
+   ```bash
+   git clone https://github.com/aptdnfapt/opencode-async-agent
+   cd opencode-async-agent
+   npm install
+   npm run build
+   ```
+
+2. **Copy to OpenCode plugins:**
+   ```bash
+   mkdir -p ~/.config/opencode/plugin
+   cp dist/async-agent.js ~/.config/opencode/plugin/
+   ```
+
+3. **Restart OpenCode** — the plugin auto-registers on startup
+
+### NPM Package (Coming Soon)
+
+```bash
+npm install -g oc-async-agent
+```
+
+## Usage
+
+The plugin adds these tools to your OpenCode agent:
+
+| Tool | Description |
+|------|-------------|
+| `delegate(prompt, agent)` | Start a background task |
+| `delegate(prompt, agent, model)` | Start with specific model |
+| `delegation_read(id)` | Get completed result |
+| `delegation_list()` | List active/completed tasks |
+| `delegation_cancel(id\|all)` | Cancel running task(s) |
+| `delegation_resume(id, prompt?)` | Resume cancelled task |
+
+### Slash Commands
+
+**`/delegation`** — List all active and completed delegations for the current session, including:
+- Delegation ID (with `opencode -s {id}` command to open session)
+- Status (running/completed/error/cancelled)
+- Agent used
+- Duration
+- Start time
+- Title/description
+
+## Configuration
+
+### Step 1: Find Model Names
+
+First, run this command to see available models and get the full `provider/model` string:
+
+```bash
+opencode models | grep <model-name>
+```
+
+For example:
+```bash
+opencode models | grep minimax
+# Output: minimax/MiniMax-M2.5
+#         minimax/MiniMax-M2.1
+```
+
+### Step 2: Configure Models
+
+**Recommended:** Create `~/.config/opencode/async-agent.md`:
+
+```markdown
+# Async Agent Model Configuration
+
+## Recommended Models
+
+### Fast
+- `minimax/MiniMax-M2.5`
+
+### Good Understanding
+- `synthetic/hf:moonshotai/Kimi-K2.5`
+
+## Notes
+Format: `provider/model` — pass to `delegate()` via the `model` parameter.
+```
+
+This file is automatically injected into your agent's system prompt, so it knows which models to use when you ask it to delegate tasks.
+
+**Alternative:** Create subagent markdown files with hardcoded models. Learn more at [Agents Documentation](https://opencode.ai/docs/agents/#markdown)
+
+## How I Use It
+
+My workflow with async agent goes like this:
+
+1. **Use Claude Opus 4.5 as my main planner** — I tell Opus what I want to build, including tech stack, key libraries, APIs, etc.
+
+2. **Identify knowledge gaps** — When I don't know much about a specific component or tech choice
+
+3. **Launch parallel research** — I tell Opus: "Send 15 minimax agents to research this part"
+   
+   Opus then makes multiple `delegate()` tool calls with:
+   ```
+   delegate(prompt="Research React patterns for large apps", agent="explore", model="minimax/MiniMax-M2.5")
+   ```
+   - Each delegation is a separate session owned by the main session
+   - Agents perform research using web search, zread/zai for GitHub, grep.app for code examples, MCP tools, or cloned OSS codebases
+
+4. **Continue planning while research runs** — Opus keeps working with me on the plan while the async agents investigate in the background
+
+5. **Check live progress** — To see what a delegation is doing in real-time:
+   - Press `Ctrl+X` then `←` / `→` to navigate sessions
+   - Child sessions appear under parent (owned by main agent)
+   - You can watch the agent work live
+
+6. **Get notified + read results** — When research completes, `<system-reminder>` fires to notify Opus, Opus reads the results internally with `delegation_read(id)`, then explains the findings to me
+
+The parallelism is key — 15 agents researching different aspects simultaneously means comprehensive information in the time it would take to do one sequential query.
+
+**Note:** I've also tried using async agent for parallel feature implementation but haven't found good success with that.
+
+
+## Project Structure
+
+```
+src/plugin/
+  plugin.ts    — Entry point, tool registration
+  manager.ts   — Delegation state machine
+  tools.ts     — Tool factories
+  types.ts     — Type definitions
+  rules.ts     — System prompt injection
+  utils.ts     — Helpers
+dist/
+  async-agent.js  — Bundled output
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "opencode-async-agent",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "esbuild src/plugin/plugin.ts --bundle --format=esm --platform=node --outfile=dist/async-agent.js --external:@opencode-ai/plugin --external:@opencode-ai/sdk"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3"
+  }
+}