opencode-agent-teams 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# opencode-agent-teams
+
+Plugin for [OpenCode](https://opencode.ai) that brings parallel agent execution, background tasks, and team coordination to your sessions. Define teams of agents, run tasks in parallel respecting dependencies, and fire off background work without blocking your main session.
+
+No more waiting for one agent to finish before starting the next.
+
+## Tools
+
+### `team_create`
+
+Define a reusable team plan with multiple tasks, each with a prompt, optional agent type, and optional dependencies.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plan_id` | `string` | Unique name for the plan |
+| `tasks` | `array` | Tasks with `id`, `prompt`, `agent` (optional), `depends_on` (optional) |
+
+### `team_run`
+
+Execute a team plan. Tasks within the same dependency level run in parallel. The agent waits for all tasks to complete and returns a summary.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plan_id` | `string` | Plan to execute |
+
+### `team_status`
+
+Check status of running or finished teams.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plan_id` | `string` (optional) | Omit to list all teams and background tasks |
+
+### `background`
+
+Fire-and-forget a single agent in the background. Returns immediately with a task ID. Optionally injects the result into your session when done.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `prompt` | `string` | Instructions for the background agent |
+| `agent` | `string` (optional) | Agent type: `general`, `explore`, `build`. Defaults to `general`. |
+| `notify` | `boolean` (optional) | Inject result into current session when done. Default: `true`. |
+
+## How it works
+
+Under the hood, the plugin uses the OpenCode SDK to create child sessions and send prompts programmatically:
+
+1. `team_create` stores a plan with a DAG of task dependencies
+2. `team_run` topologically sorts the tasks, runs each dependency level in parallel via `Promise.all`
+3. Each task gets its own child session via `client.session.create` with `parentID` set to the current session
+4. Tasks run via `client.session.prompt` (blocking) or `client.session.promptAsync` (background)
+5. `team_status` reads session state from the OpenCode server
+6. Background tasks poll for completion and inject results back into the parent session
+
+## Install
+
+```json
+{
+  "plugin": ["opencode-agent-teams"]
+}
+```
+
+Restart OpenCode.
+
+## Examples
+
+### Parallel research team
+
+```
+team_create plan_id="research-feature" tasks=[
+  {id:"api", prompt:"Research the API endpoints needed for user auth", agent:"explore"},
+  {id:"db", prompt:"Research database schema for user auth", agent:"explore"},
+  {id:"summary", prompt:"Synthesize the API and DB findings into a plan", agent:"general", depends_on:["api","db"]}
+]
+team_run plan_id="research-feature"
+```
+
+### Background code review
+
+```
+background prompt="Review all changed files in this project for security issues" agent="explore"
+team_status
+```
+
+## Mantenido por
+
+**Maycol B.T** ([@SoyMaycol](https://github.com/SoyMaycol))
+
+```
+Email:  soymaycol.cn@gmail.com
+Web:    https://soymaycol.icu
+GitHub: https://github.com/SoyMaycol
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,446 @@
+import { tool } from "@opencode-ai/plugin";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const TEAMS_DIR = join(homedir(), ".config", "opencode", "teams");
+function ensureDir() {
+    if (!existsSync(TEAMS_DIR))
+        mkdirSync(TEAMS_DIR, { recursive: true });
+}
+function planPath(id) {
+    return join(TEAMS_DIR, `plan-${id}.json`);
+}
+function runPath(id) {
+    return join(TEAMS_DIR, `run-${id}.json`);
+}
+function bgPath(id) {
+    return join(TEAMS_DIR, `bg-${id}.json`);
+}
+function savePlan(plan) {
+    ensureDir();
+    writeFileSync(planPath(plan.id), JSON.stringify(plan, null, 2));
+}
+function saveRun(run) {
+    ensureDir();
+    writeFileSync(runPath(run.planID), JSON.stringify(run, null, 2));
+}
+function saveBg(task) {
+    ensureDir();
+    writeFileSync(bgPath(task.id), JSON.stringify(task, null, 2));
+}
+function loadPlan(id) {
+    const p = planPath(id);
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, "utf-8"));
+}
+function loadRun(planID) {
+    const p = runPath(planID);
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, "utf-8"));
+}
+function loadBg(id) {
+    const p = bgPath(id);
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, "utf-8"));
+}
+function listPlans() {
+    ensureDir();
+    const files = readFileSync(TEAMS_DIR, "utf-8")
+        ? readdirSync(TEAMS_DIR).filter((f) => f.startsWith("plan-"))
+        : [];
+    return files.map((f) => JSON.parse(readFileSync(join(TEAMS_DIR, f), "utf-8")));
+}
+function listRuns() {
+    ensureDir();
+    const files = readFileSync(TEAMS_DIR, "utf-8")
+        ? readdirSync(TEAMS_DIR).filter((f) => f.startsWith("run-"))
+        : [];
+    return files.map((f) => JSON.parse(readFileSync(join(TEAMS_DIR, f), "utf-8")));
+}
+function listBg() {
+    ensureDir();
+    const files = readFileSync(TEAMS_DIR, "utf-8")
+        ? readdirSync(TEAMS_DIR).filter((f) => f.startsWith("bg-"))
+        : [];
+    return files.map((f) => JSON.parse(readFileSync(join(TEAMS_DIR, f), "utf-8")));
+}
+function topologicalSort(tasks) {
+    const taskMap = new Map(tasks.map((t) => [t.id, t]));
+    const inDegree = new Map();
+    const children = new Map();
+    for (const t of tasks) {
+        if (!inDegree.has(t.id))
+            inDegree.set(t.id, 0);
+        if (!children.has(t.id))
+            children.set(t.id, []);
+        for (const dep of t.depends_on) {
+            if (!children.has(dep))
+                children.set(dep, []);
+            children.get(dep).push(t.id);
+            inDegree.set(t.id, (inDegree.get(t.id) || 0) + 1);
+        }
+    }
+    const levels = [];
+    let queue = tasks.filter((t) => (inDegree.get(t.id) || 0) === 0);
+    while (queue.length > 0) {
+        levels.push(queue);
+        const next = [];
+        for (const t of queue) {
+            for (const child of children.get(t.id) || []) {
+                const deg = (inDegree.get(child) || 1) - 1;
+                inDegree.set(child, deg);
+                if (deg === 0 && taskMap.has(child)) {
+                    next.push(taskMap.get(child));
+                }
+            }
+        }
+        queue = next;
+    }
+    return levels;
+}
+const plugin = async (ctx) => {
+    return {
+        tool: {
+            team_create: tool({
+                description: "Define a team of agents with multiple tasks and optional dependencies. " +
+                    "Each task has an id, a prompt, an optional agent type, and an optional list of task IDs it depends on. " +
+                    "Use this before team_run to create reusable team plans.",
+                args: {
+                    plan_id: tool.schema
+                        .string()
+                        .describe("Unique name for this team plan, e.g. 'refactor-auth'"),
+                    tasks: tool.schema
+                        .array(tool.schema.object({
+                        id: tool.schema
+                            .string()
+                            .describe("Unique task ID within this plan"),
+                        prompt: tool.schema
+                            .string()
+                            .describe("The prompt/instructions for this agent"),
+                        agent: tool.schema
+                            .string()
+                            .optional()
+                            .describe("Agent type to use (e.g. 'general', 'explore', 'build'). Defaults to 'general'"),
+                        depends_on: tool.schema
+                            .array(tool.schema.string())
+                            .optional()
+                            .describe("Task IDs that must complete before this one starts"),
+                    }))
+                        .describe("Array of tasks the team will execute"),
+                },
+                async execute(args) {
+                    const tasks = (args.tasks || []).map((t) => ({
+                        id: t.id,
+                        prompt: t.prompt,
+                        agent: t.agent || "general",
+                        depends_on: t.depends_on || [],
+                    }));
+                    if (tasks.length === 0)
+                        return "No tasks provided.";
+                    const ids = new Set(tasks.map((t) => t.id));
+                    if (ids.size !== tasks.length)
+                        return "Duplicate task IDs found.";
+                    for (const t of tasks) {
+                        for (const d of t.depends_on) {
+                            if (!ids.has(d))
+                                return `Task "${t.id}" depends on "${d}" which does not exist.`;
+                        }
+                    }
+                    const plan = {
+                        id: args.plan_id,
+                        tasks,
+                        created: Date.now(),
+                    };
+                    savePlan(plan);
+                    const levels = topologicalSort(tasks);
+                    const summary = levels
+                        .map((level, i) => `  Level ${i + 1}: ${level.map((t) => t.id).join(", ")}`)
+                        .join("\n");
+                    return [
+                        `Team plan "${args.plan_id}" created with ${tasks.length} tasks across ${levels.length} execution levels.`,
+                        "",
+                        summary,
+                        "",
+                        `Run it with: team_run plan_id="${args.plan_id}"`,
+                    ].join("\n");
+                },
+            }),
+            team_run: tool({
+                description: "Execute a team plan. Tasks run in parallel within each dependency level. " +
+                    "The agent waits for all tasks to complete and returns a summary of results. " +
+                    "Use team_status to check progress of longer running teams.",
+                args: {
+                    plan_id: tool.schema
+                        .string()
+                        .describe("The plan ID to execute (created with team_create)"),
+                },
+                async execute(args, context) {
+                    const plan = loadPlan(args.plan_id);
+                    if (!plan)
+                        return `Plan "${args.plan_id}" not found. Create it first with team_create.`;
+                    const run = {
+                        planID: plan.id,
+                        tasks: plan.tasks.map((t) => ({
+                            id: t.id,
+                            sessionID: "",
+                            status: "pending",
+                        })),
+                        started: Date.now(),
+                    };
+                    saveRun(run);
+                    const taskMap = new Map(plan.tasks.map((t) => [t.id, t]));
+                    const runMap = new Map(run.tasks.map((t) => [t.id, t]));
+                    const levels = topologicalSort(plan.tasks);
+                    for (const level of levels) {
+                        const promises = level.map(async (taskDef) => {
+                            const runEntry = runMap.get(taskDef.id);
+                            runEntry.status = "running";
+                            saveRun(run);
+                            try {
+                                const { data: session, error: createErr } = await ctx.client.session.create({
+                                    body: {
+                                        parentID: context.sessionID,
+                                        title: `[team] ${plan.id}/${taskDef.id}`,
+                                    },
+                                });
+                                if (createErr || !session) {
+                                    runEntry.status = "failed";
+                                    runEntry.error = String(createErr || "session creation failed");
+                                    saveRun(run);
+                                    return;
+                                }
+                                runEntry.sessionID = session.id;
+                                saveRun(run);
+                                const { data: result, error: promptErr } = await ctx.client.session.prompt({
+                                    path: { id: session.id },
+                                    body: {
+                                        agent: taskDef.agent || "general",
+                                        parts: [{ type: "text", text: taskDef.prompt }],
+                                    },
+                                });
+                                if (promptErr || !result) {
+                                    runEntry.status = "failed";
+                                    runEntry.error = String(promptErr || "prompt failed");
+                                }
+                                else {
+                                    runEntry.status = "done";
+                                }
+                            }
+                            catch (e) {
+                                runEntry.status = "failed";
+                                runEntry.error = e?.message || String(e);
+                            }
+                            saveRun(run);
+                        });
+                        await Promise.all(promises);
+                    }
+                    const finalRun = loadRun(plan.id);
+                    if (!finalRun)
+                        return "Run data lost.";
+                    const lines = [
+                        `Team "${plan.id}" finished. ${finalRun.tasks.filter((t) => t.status === "done").length}/${finalRun.tasks.length} tasks succeeded.`,
+                        "",
+                    ];
+                    for (const t of finalRun.tasks) {
+                        const icon = t.status === "done" ? "✓" : t.status === "failed" ? "✗" : "○";
+                        const session = t.sessionID ? ` (session: ${t.sessionID})` : "";
+                        lines.push(`  ${icon} ${t.id} — ${t.status}${session}`);
+                        if (t.error)
+                            lines.push(`      error: ${t.error}`);
+                    }
+                    lines.push("");
+                    lines.push("Use team_status to get detailed results from individual sessions.");
+                    return lines.join("\n");
+                },
+            }),
+            team_status: tool({
+                description: "Check the execution status of a team plan. Shows each task's status, session ID, and any errors. " +
+                    "Omit plan_id to list all tracked teams and background tasks.",
+                args: {
+                    plan_id: tool.schema
+                        .string()
+                        .optional()
+                        .describe("Specific plan ID to check, or omit to list all"),
+                },
+                async execute(_args) {
+                    if (_args.plan_id) {
+                        const run = loadRun(_args.plan_id);
+                        if (!run)
+                            return `No execution data for plan "${_args.plan_id}".`;
+                        const lines = [
+                            `Plan: ${run.planID}`,
+                            `Started: ${new Date(run.started).toISOString()}`,
+                            "",
+                        ];
+                        for (const t of run.tasks) {
+                            const icon = t.status === "done"
+                                ? "✓"
+                                : t.status === "failed"
+                                    ? "✗"
+                                    : t.status === "running"
+                                        ? "◌"
+                                        : "○";
+                            lines.push(`  ${icon} ${t.id} — ${t.status}`);
+                            if (t.sessionID)
+                                lines.push(`      session: ${t.sessionID}`);
+                            if (t.error)
+                                lines.push(`      error: ${t.error}`);
+                        }
+                        return lines.join("\n");
+                    }
+                    const allRuns = listRuns();
+                    const bgTasks = listBg();
+                    const sections = ["**Team runs:**"];
+                    if (allRuns.length === 0) {
+                        sections.push("  No team runs yet.");
+                    }
+                    else {
+                        for (const r of allRuns) {
+                            const done = r.tasks.filter((t) => t.status === "done").length;
+                            const failed = r.tasks.filter((t) => t.status === "failed").length;
+                            const running = r.tasks.filter((t) => t.status === "running").length;
+                            sections.push(`  • ${r.planID}: ${done}✓ ${failed > 0 ? failed + "✗ " : ""}${running > 0 ? running + "◌ " : ""}(${r.tasks.length} tasks)`);
+                        }
+                    }
+                    sections.push("", "**Background tasks:**");
+                    if (bgTasks.length === 0) {
+                        sections.push("  No background tasks.");
+                    }
+                    else {
+                        for (const b of bgTasks) {
+                            const icon = b.status === "done"
+                                ? "✓"
+                                : b.status === "failed"
+                                    ? "✗"
+                                    : "◌";
+                            sections.push(`  ${icon} ${b.id} — ${b.status} [${b.agent || "general"}]`);
+                        }
+                    }
+                    return sections.join("\n");
+                },
+            }),
+            background: tool({
+                description: "Launch a fire-and-forget agent in the background. " +
+                    "Returns immediately with a task ID so you can check status later. " +
+                    "Useful for long-running tasks like code reviews, tests, research, or documentation generation.",
+                args: {
+                    prompt: tool.schema
+                        .string()
+                        .describe("The prompt/instructions for the background agent"),
+                    agent: tool.schema
+                        .string()
+                        .optional()
+                        .describe("Agent type (e.g. 'general', 'explore', 'build'). Defaults to 'general'"),
+                    notify: tool.schema
+                        .boolean()
+                        .optional()
+                        .describe("When true, the result will be injected into the current session when done. Default: true"),
+                },
+                async execute(args, context) {
+                    const taskID = `bg-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+                    try {
+                        const { data: session, error: createErr } = await ctx.client.session.create({
+                            body: {
+                                parentID: context.sessionID,
+                                title: `[bg] ${taskID}`,
+                            },
+                        });
+                        if (createErr || !session) {
+                            return `Failed to create background session: ${String(createErr || "unknown")}`;
+                        }
+                        const bgTask = {
+                            id: taskID,
+                            prompt: args.prompt,
+                            agent: args.agent || "general",
+                            sessionID: session.id,
+                            status: "running",
+                            started: Date.now(),
+                        };
+                        saveBg(bgTask);
+                        const { error: promptErr } = await ctx.client.session.promptAsync({
+                            path: { id: session.id },
+                            body: {
+                                agent: args.agent || "general",
+                                parts: [{ type: "text", text: args.prompt }],
+                            },
+                        });
+                        if (promptErr) {
+                            bgTask.status = "failed";
+                            saveBg(bgTask);
+                            return `Background task started but promptAsync failed: ${promptErr}`;
+                        }
+                        // Poll for completion
+                        (async () => {
+                            let attempts = 0;
+                            const maxAttempts = 600;
+                            while (attempts < maxAttempts) {
+                                await sleep(2000);
+                                attempts++;
+                                try {
+                                    const { data: statuses } = await ctx.client.session.status();
+                                    const s = statuses?.[session.id];
+                                    if (!s || s.type === "idle") {
+                                        // Session finished
+                                        const { data: msgs } = await ctx.client.session.messages({
+                                            path: { id: session.id },
+                                            query: { limit: 1 },
+                                        });
+                                        bgTask.status = "done";
+                                        saveBg(bgTask);
+                                        // If notify is false, skip injection
+                                        if (args.notify !== false && msgs?.length) {
+                                            const last = msgs[msgs.length - 1];
+                                            const text = last.parts
+                                                .filter((p) => p.type === "text")
+                                                .map((p) => p.text)
+                                                .join("\n");
+                                            await ctx.client.session.promptAsync({
+                                                path: { id: context.sessionID },
+                                                body: {
+                                                    parts: [
+                                                        {
+                                                            type: "text",
+                                                            text: `[Background task "${taskID}" completed]\n\n${text}`,
+                                                            synthetic: true,
+                                                        },
+                                                    ],
+                                                    noReply: true,
+                                                },
+                                            });
+                                        }
+                                        return;
+                                    }
+                                }
+                                catch {
+                                    // keep polling
+                                }
+                            }
+                            bgTask.status = "failed";
+                            bgTask.error = "timed out";
+                            saveBg(bgTask);
+                        })();
+                        return [
+                            `Background task launched.`,
+                            `  Task ID: ${taskID}`,
+                            `  Agent: ${args.agent || "general"}`,
+                            `  Session: ${session.id}`,
+                            "",
+                            `Check status with: team_status`,
+                            `Or: team_status plan_id="${taskID}"`,
+                        ].join("\n");
+                    }
+                    catch (e) {
+                        return `Failed to launch background task: ${e?.message || String(e)}`;
+                    }
+                },
+            }),
+        },
+    };
+};
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export default plugin;

package/package.json

@@ -0,0 +1,51 @@
+{
+"name": "opencode-agent-teams",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for parallel agent execution, background tasks, and team coordination. Create teams of agents that work together, run tasks in parallel respecting dependencies, and fire off background work without blocking.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "teams",
+    "agents",
+    "parallel",
+    "background",
+    "orchestration"
+  ],
+  "author": {
+    "name": "Maycol B.T",
+    "email": "soymaycol.cn@gmail.com",
+    "url": "https://github.com/SoyMaycol"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SoyMaycol/opencode-teams"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0",
+    "@opencode-ai/sdk": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.4.6",
+    "@opencode-ai/sdk": "latest",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}