@opencode-cockpit/subagents 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codestz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @opencode-cockpit/subagents
+
+**See what your subagents are doing, while they do it — and reuse them.** When the main agent hands
+work to a subagent, you get one line in the chat and nothing else. This puts every subagent in the
+sidebar with what it is doing right now, opens its whole run in a pane — thinking, every tool call as
+OpenCode draws its own, the answer — lets you message it, stop it or move it to the background, and
+has the main agent continue the subagent that did the work instead of starting from nothing.
+
+Part of [opencode-cockpit](https://github.com/Codestz/opencode-cockpit). Install it on its own, or
+through the bundle. Works on OpenCode 1.18+ and 2.0.15+.
+
+```sh
+opencode plugin @opencode-cockpit/subagents@0.7.0 --global --force     # OpenCode 1
+opencode plugin add @opencode-cockpit/subagents@0.7.0                   # OpenCode 2
+```
+
+## What it does
+
+**In the sidebar**, a Subagents block: each subagent in this conversation, its type and task, and
+under it what it is doing now — `grep "session" src/auth/**`, `thinking`, `waiting for permission`,
+`done · 2 rounds`, `cancelled` — with how many calls and how long on the right. A subagent that
+launched its own has them indented under it.
+
+**Click one** — or `ctrl+x w`, or `/subagents` — and its run opens in a pane on the right, half the
+window or all of it: its model and who launched it, the task, then the run. A shell command or a file
+change is a box with its output (ten lines, sixty open, all with `a`); reads and searches are one quiet
+line each; thinking folds; the answer is drawn as markdown.
+
+| Key | |
+| --- | --- |
+| `j` `k` | Move the cursor through the run's items |
+| `enter` · a click | Open or fold the item under it |
+| `e` | Open, or fold, every call |
+| `a` | A call's whole output — open shows its first 60 lines, whole up to 2,000 |
+| `t` | Show or hide thinking — shown by default, and remembered |
+| `m` | Write it a message, at the foot of the pane (pasting works) |
+| `x` | Stop it (press twice) — or, once it has finished, remove it from the list |
+| `X` | Remove every finished subagent from the list |
+| `b` | Move it to the background, so the main agent carries on (OpenCode's own `ctrl+b`) |
+| `i` | Details: model, what it is denied, calls by tool, tokens, cost |
+| `w` | Half the window, or all of it (remembered) |
+| `[` `]` | Another subagent of this conversation |
+| `d` `u` · `g` `G` | Page down · up · to the start · follow the run |
+| `esc` `q` | Back to the conversation |
+
+**Follow-ups keep their context.** The main agent is asked to continue the subagent that did the work
+(`task_id` on OpenCode 1, `sessionID` on 2) rather than launch a new one, and has a `subagents_list`
+tool: each subagent's id, task, state and last answer — saying when one was cancelled, or ended on a
+progress note rather than an answer. Each round shows in the pane under a "Round N" rule.
+
+**Message it.** A subagent that is still working picks your message up in its current run and answers
+it in its report, so the main agent sees it too. A finished one wakes up and answers you, and Cockpit
+adds the exchange to the main conversation without starting a turn there, so the main agent knows it
+next time. A message it finished without reading comes back to the field.
+
+**Stop and remove.** `x` twice stops a working subagent — and first tells the main agent you stopped
+it on purpose, so it reports the stop instead of launching the subagent again. `x` on a finished one
+removes it from the list, `X` removes every finished one; the sessions stay in OpenCode.
+
+**Background subagents.** The main agent is asked to launch independent subagents with
+`background: true` when its tool offers it, so the conversation keeps going. OpenCode 2 offers it
+always; **OpenCode 1 only when started with `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`** — a
+plugin cannot set that for you. `b` moves one already running in the foreground, the same way.
+
+```sh
+export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true   # in ~/.zshrc, then start OpenCode
+```
+
+## Settings
+
+In the bundle's entry (`"subagents": { … }`) or this package's own:
+
+| Setting | Default | |
+| --- | --- | --- |
+| `sidebarRows` | `6` | Subagents shown before the rest fold into a count — working ones first |
+| `hideFinishedAfter` | unset | Minutes a finished subagent stays in the sidebar; unset keeps it for the conversation |
+| `sidebarOrder` | `150` | Where the block sits in the sidebar; lower draws first |
+| `keybinds` | `{ "cockpit.subagents.open": "<leader>w" }` | The key that opens the latest one |
+| `guidance` | `true` | Tell the main agent about background subagents and follow-ups (agent side) |
+
+## See it without OpenCode
+
+```sh
+bunx @opencode-cockpit/subagents preview
+```
+
+Draws the sidebar block and the pane from a sample run, in your terminal.
+
+## Troubleshooting
+
+```sh
+npx opencode-cockpit@latest doctor
+```
+
+checks OpenCode, its config, Cockpit's logs and the daemon, and prints the fix for anything wrong —
+on OpenCode 1 and 2, and when Cockpit will not load at all ([what it checks](https://codestz.github.io/opencode-cockpit/help/doctor/)).
+
+Everything Cockpit does inside OpenCode goes to one file — which OpenCode loaded which bay, and every
+error with its stack:
+
+```sh
+tail -50 ~/.cache/opencode-cockpit/cockpit.log
+```
+
+`COCKPIT_DEBUG=1 opencode` adds the detail. [Troubleshooting](https://codestz.github.io/opencode-cockpit/help/troubleshooting/) covers
+the failures people hit and what to attach to an issue; [OpenCode 1 and 2](https://codestz.github.io/opencode-cockpit/start/opencode-versions/)
+covers what differs between the two.

package/dist/agent/plugin.js

@@ -0,0 +1,134 @@
+import { tool } from "@opencode-ai/plugin";
+import { claimFeature, duplicateFeatureMessage } from "@opencode-cockpit/client";
+import { dualServer } from "@opencode-cockpit/client/server";
+import { createV1Translator } from "../core/adapt/v1.js";
+import { createV2Translator } from "../core/adapt/v2.js";
+import { applyAll, emptyModel, subagentsOf } from "../core/model/model.js";
+import { subagentReport } from "../core/view/report.js";
+
+/**
+ * What the agent is told about subagents, once per request.
+ *
+ * Measured on both OpenCodes (docs/opencode/agents.md): a subagent launched in the background lets the
+ * conversation carry on, and the main agent is told when it finishes. OpenCode 2 offers it on its
+ * `subagent` tool; OpenCode 1 only with `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`, which a
+ * plugin cannot set — so the guidance says "if your tool offers it", and never promises it.
+ *
+ * Continuing a subagent was measured too: given its id, the same subagent picks up with everything it
+ * already read, and answers in seconds. Main agents rarely do it on their own — the id scrolls away —
+ * so the guidance asks for it, and `subagents_list` hands the ids back.
+ */
+export const GUIDANCE = `## Subagents (opencode-cockpit)
+When you delegate independent work to a subagent, launch it with background: true if your task or subagent tool offers that option, so this conversation continues while it works; you are notified when it finishes. Work on something else meanwhile, or tell the user what you launched.
+When the user asks for a fix or follow-up on work a subagent already did, continue that same subagent (task_id or sessionID) rather than launching a new one — it keeps its context. subagents_list gives each subagent's id, task and last answer.
+The user can watch each subagent and message it directly; when they do, a note in this conversation tells you what they asked and what it answered.`;
+const LIST = `List the subagents of this conversation: each one's id, agent, task, state and last answer.
+
+Use it before following up on work a subagent did, to continue that same subagent by its id instead of starting a new one — it keeps everything it already read and tried.`;
+export const SUBAGENTS_PACKAGE = "@opencode-cockpit/subagents";
+/**
+ * What the agent side keeps of each run: enough to list it — not what calls printed, nor thinking, so
+ * a long session does not hold every file its subagents read.
+ */
+export function slim(changes) {
+  const out = [];
+  for (const change of changes) {
+    if (change.type === "thinking") continue;
+    if (change.type === "tool") {
+      const {
+        output: _output,
+        input: _input,
+        ...rest
+      } = change;
+      out.push(rest);
+    } else out.push(change);
+  }
+  return out;
+}
+
+/**
+ * The conversation's subagents: what the events said, and on OpenCode 1 any from before we started —
+ * with their history, read once. Listed bare, those read "working now · 0 calls" to the main agent,
+ * which then waits on work long finished, or does it again.
+ */
+async function nodesFor(host, model, history, sessionID) {
+  const listed = (await host.session.children?.(sessionID).catch(() => [])) ?? [];
+  const missing = listed.filter(child => (model.sessions.get(child.id)?.entries.length ?? 0) === 0);
+  for (const child of missing) {
+    const at = child.time?.updated ?? Date.now();
+    const messages = (await host.session.messages?.(child.id).catch(() => [])) ?? [];
+    applyAll(model, [{
+      type: "session",
+      id: child.id,
+      parentID: sessionID,
+      ...(child.title ? {
+        title: child.title
+      } : {}),
+      at
+    }, ...slim(history(messages)), {
+      type: "status",
+      id: child.id,
+      status: "idle",
+      at
+    }]);
+  }
+  return subagentsOf(model, sessionID);
+}
+
+/** The agent side as a factory, so the `opencode-cockpit` bundle can include it. */
+export function createSubagentsServer({
+  source = SUBAGENTS_PACKAGE
+} = {}) {
+  return async (host, rawOptions) => {
+    const claim = claimFeature(host.scope, "subagents", source);
+    if (!claim.active) {
+      host.log.warn(duplicateFeatureMessage("Subagents", claim.owner, source));
+      return {};
+    }
+    const log = host.log.child("subagents");
+    const options = rawOptions ?? {};
+    const model = emptyModel();
+    const v1 = host.version === 1 ? createV1Translator() : undefined;
+    const translate = v1 ?? createV2Translator();
+    const history = messages => v1?.history(messages) ?? [];
+    const list = tool({
+      description: LIST,
+      args: {},
+      async execute(_args, context) {
+        const nodes = await nodesFor(host, model, history, context.sessionID);
+        log.debug("list", {
+          sessionID: context.sessionID,
+          count: nodes.length
+        });
+        return subagentReport({
+          nodes,
+          now: Date.now(),
+          version: host.version
+        });
+      }
+    });
+    return {
+      ...(options.guidance === false ? {} : {
+        system: async () => [GUIDANCE]
+      }),
+      tools: {
+        subagents_list: list
+      },
+      event: event => {
+        try {
+          const changes = slim(translate.event(event));
+          if (changes.length > 0) applyAll(model, changes);
+        } catch (error) {
+          log.warn("event failed", {
+            error
+          });
+        }
+      },
+      sessionDeleted: async sessionID => {
+        model.sessions.delete(sessionID);
+      },
+      dispose: () => claim.release()
+    };
+  };
+}
+export default dualServer("opencode-cockpit.subagents", createSubagentsServer());

package/dist/cli/preview.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env bun
+/**
+ * The see-it loop: the sidebar block and the full screen, drawn in this terminal from a recorded run,
+ * with no OpenCode running. The same rows OpenCode draws — only the colours come from a fixed
+ * palette (OpenCode's default theme) instead of the user's.
+ *
+ *   bunx @opencode-cockpit/subagents preview            a sample run, mid-flight
+ *   bunx @opencode-cockpit/subagents preview --width 34 the sidebar at another width
+ */
+import { applyAll, emptyModel, subagentsOf } from "../core/model/model.js";
+import { SAMPLE_NOW, SAMPLE_ROOT, sample } from "../core/sample.js";
+import { screenRows } from "../core/view/screen.js";
+import { sidebarLines } from "../core/view/sidebar.js";
+
+/** OpenCode's default theme, measured (docs/opencode/v2.md). */
+const HEX = {
+  text: "#eeeeee",
+  muted: "#808080",
+  accent: "#9d7cd8",
+  info: "#56b6c2",
+  tool: "#fab283",
+  success: "#7fd88f",
+  error: "#e06c75",
+  warning: "#f5a742",
+  border: "#484848"
+};
+const FILL = {
+  band: "#141414",
+  block: "#1e1e1e",
+  card: "#1e1e1e",
+  selected: "#141414"
+};
+const rgb = hex => [1, 3, 5].map(i => Number.parseInt(hex.slice(i, i + 2), 16)).join(";");
+const color = process.stdout.isTTY && !process.env.NO_COLOR;
+function paint(row) {
+  if (!color) return row.map(run => run.text).join("");
+  return row.map(run => {
+    const codes = [`38;2;${rgb(HEX[run.tone ?? "text"])}`];
+    if (run.fill && run.fill !== "none") codes.push(`48;2;${rgb(FILL[run.fill])}`);
+    if (run.bold) codes.push("1");
+    if (run.faint) codes.push("2");
+    return `\x1b[${codes.join(";")}m${run.text}\x1b[0m`;
+  }).join("");
+}
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write("Usage: subagents preview [--width <sidebar columns>]\n");
+  process.exit(0);
+}
+const at = args.indexOf("--width");
+const sidebarWidth = at >= 0 ? Number(args[at + 1]) || 36 : 36;
+const columns = Math.max(60, Math.min(process.stdout.columns || 100, 140));
+const model = applyAll(emptyModel(), sample());
+const nodes = subagentsOf(model, SAMPLE_ROOT);
+const out = ["", "Sidebar", ""];
+for (const line of sidebarLines({
+  nodes,
+  width: sidebarWidth,
+  now: SAMPLE_NOW,
+  frame: 2
+})) out.push(paint(line.row));
+const first = nodes[0]?.session;
+if (first) {
+  const base = {
+    session: first,
+    nodes,
+    launcher: "build",
+    width: columns,
+    height: 30,
+    now: SAMPLE_NOW,
+    frame: 2,
+    open: new Set(),
+    closed: new Set(),
+    thinking: false,
+    details: false
+  };
+  out.push("", "The pane — the first subagent", "");
+  const folded = screenRows(base);
+  for (const row of folded.rows) out.push(paint(row));
+  /** The same, with the cursor on the first call and that call open. */
+  const call = folded.keys.find(key => key.startsWith("tool:"));
+  if (call) {
+    out.push("", "A call, selected and open", "");
+    const opened = screenRows({
+      ...base,
+      selected: call,
+      open: new Set([call]),
+      top: 0
+    });
+    for (const row of opened.rows) out.push(paint(row));
+  }
+  out.push("", "Details", "");
+  for (const row of screenRows({
+    ...base,
+    details: true,
+    height: 20
+  }).rows) out.push(paint(row));
+}
+process.stdout.write(`${out.join("\n")}\n\n`);