opencode-agent-dock 0.1.0 → 1.0.0

package/README.md

@@ -1,102 +1,98 @@
 # opencode-agent-dock
 
-> Status: **skeleton / work-in-progress**. Architecture and wiring are in place;
-> the verify-items below remain before it renders live subagents correctly.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-green.svg)](https://opencode.ai)
+[![npm version](https://img.shields.io/npm/v/opencode-agent-dock.svg)](https://www.npmjs.com/package/opencode-agent-dock)
+[![GitHub repo](https://img.shields.io/badge/repo-arttttt%2Fopencode--agent--dock-181717?logo=github)](https://github.com/arttttt/opencode-agent-dock)
 
-An [OpenCode](https://opencode.ai) **TUI plugin** that adds a **Claude-Code-style
-bottom panel** grouping the current session's **subagents** — with select,
-switch, and open-session. Not in the right sidebar: rendered in the `app_bottom`
-slot, which sits below the active route in the session view.
+An [OpenCode](https://opencode.ai) **TUI plugin** that adds a **Claude-Code-style bottom panel** of your running **subagents** — visible at a glance under the prompt, with inline keyboard navigation to browse them collapsed and open any one.
+
+Subagents normally only surface inline in the chat, and the chat scrolls away from where they were spawned. `opencode-agent-dock` keeps the active session's subagents pinned to the bottom of the screen, each with its status, elapsed time and token spend.
+
+## How it works
 
 ```
-▸ ● general-purpose  Verify error-tile reactivity and guards   3m 25s
-  ○ explore          Audit round-3 test quality                 45s
-  ✓ librarian        Lookup JWT docs
+active session route
+  ↓
+resolve current session
+  ├─ parent session → client.session.children() → keep the RUNNING ones
+  └─ subagent session → pin the one currently in focus (panel stays up)
+  ↓
+app_bottom slot renders the roster:  ● title  elapsed · tokens
+  ↓
+navigation: keymap.intercept catches ↑/↓/Enter BEFORE the prompt textarea
+            (the same mechanism opencode uses for copy-on-select), so while the
+            dock is focused the prompt is "locked" and arrows move the cursor
 ```
 
-## Why
+## Features
 
-Subagents only surface inside the chat, and the chat scrolls away from where
-they were spawned. The existing opencode subagent plugins put their list in the
-**right sidebar** and are heavy. This plugin targets the **bottom** (like Claude
-Code's agent panel) and stays as a single lean plugin.
+- **Persistent bottom panel** — running subagents stay visible under the prompt (Claude-Code-style: plain rows, no panel chrome).
+- **Per-subagent telemetry** — status glyph, elapsed time and total token usage on every row.
+- **Inline keyboard navigation** — browse the list collapsed, `Enter` opens the selected subagent's session.
+- **Stays visible inside a subagent** — the focused subagent is highlighted; native `←/→` between siblings updates it live.
+- **Self-cleaning** — finished/cancelled subagents drop out of the panel automatically; it hides when there are none.
+- **Escape stays native** — `Esc` is never hijacked, so it still cancels subagents.
 
 ## Install
 
-TUI plugins are configured in `tui.json`. Add the plugin, then restart OpenCode:
+This is a **TUI plugin**, so it is configured in `tui.json` (not `opencode.json`):
 
 ```jsonc
-// ~/.config/opencode/tui.json
+// ~/.config/opencode/tui.json  (user)  or  .opencode/tui.json  (project)
 {
+  "$schema": "https://opencode.ai/tui.json",
   "plugin": ["opencode-agent-dock"]
 }
 ```
 
-Local development:
-
-```jsonc
-{
-  "plugin": [["file:///absolute/path/to/opencode-agent-dock/src/index.tsx"]]
-}
-```
+Restart OpenCode after adding it.
 
 ## Keybindings
 
 | Key | Action |
 | --- | --- |
-| `alt+a` | Focus the dock |
-| `k` / `j` | Previous / next subagent |
-| `enter` | Open the selected subagent's session |
-| `esc` | Leave the dock |
+| `ctrl+x` `v`  — or `/subagents` | Focus the dock (toggle) |
+| `↑` / `↓` | Previous / next subagent |
+| `Enter` | Open the selected subagent's session |
+| `↑` from the first row, or `ctrl+x` `v` again | Leave the dock |
+| `Esc` | _(native)_ cancel subagents |
+
+The toggle key (`<leader>v`) can be remapped in `tui.json` under the `agent-dock.toggle` command if you prefer a different one.
+
+> Why a toggle and not bare `↓`? In the parent session the prompt textarea captures arrow keys, and a plugin cannot blur the host prompt. `keymap.intercept` runs before the textarea, so once the dock is focused the arrows are ours. `↓` itself is also the prompt's history key, which made it an unreliable trigger.
 
 ## Architecture
 
-Clean Architecture, by analogy with
-[`opencode-auto-vision`](https://github.com/arttttt/opencode-auto-vision):
-dependencies point inward, the domain is pure, and the only thing that knows
-about the opencode SDK / TUI API is the composition root + adapters.
+Clean Architecture — dependencies point inward, the domain is pure, and the only place that knows about the opencode SDK / TUI API is the composition root + adapters.
 
 ```
 src/
-  domain.ts                              pure: Subagent, selection math, formatting
-  ports.ts                               SubagentStore, SessionNavigator, Logger
-  sdk.ts                                 SDK Session/SessionStatus -> domain Subagent
-  constants.ts                           plugin id, slot name, keybinds, limits
+  domain.ts                       pure: Subagent, selection math, formatting (unit-tested)
+  ports.ts                        SubagentStore, Logger contracts
+  sdk.ts                          SDK Session/SessionStatus -> domain Subagent
+  constants.ts                    plugin id, slot name, limits
   adapters/
-    opencode-subagent-store.ts           SubagentStore via client.session.children + events
-    opencode-navigator.ts                SessionNavigator via route.navigate
-    opencode-logger.ts                   Logger via client.app.log
+    opencode-subagent-store.ts    SubagentStore via client.session.children + events
+    opencode-logger.ts            Logger via client.app.log
   view/
-    Dock.tsx                             Solid render into the app_bottom slot
-  index.tsx                              composition root + tui entry ({ id, tui })
+    Dock.tsx                      Solid render into the app_bottom slot
+  index.tsx                       composition root: slot + inline nav (intercept)
 ```
 
-### Data flow
-
-`api.route.current` resolves the active parent session →
-`client.session.children({ sessionID })` returns its child sessions → each is
-projected to a domain `Subagent` and status is read from
-`api.state.session.status(id)` → `Dock` renders rows in `app_bottom`.
-Selection is owned by the root; `enter` calls `route.navigate("session", …)`.
-
-## Verify before release
-
-- [ ] `client.session.children` response shape (`result.data`) and namespace.
-- [ ] `Session.time.created` field name for elapsed-time origin.
-- [ ] `app_bottom` slot `SolidPlugin` shape from `@opentui/solid` (cast today).
-- [ ] Focus handling: pushing `agent-dock` mode reliably captures `j/k/enter`.
-- [ ] Map terminal subagent states to `done` vs `error` (status `undefined` is
-      treated as `done` for now).
-
 ## Develop
 
 ```sh
 npm install
+npm test        # vitest — domain unit tests
 npm run typecheck
 ```
 
-OpenCode runs on Bun and loads `.ts`/`.tsx` natively, so there is no build step
-for local file-plugin use.
+OpenCode runs on Bun and loads `.ts`/`.tsx` natively, so there is no build step for local file-plugin use:
+
+```jsonc
+{ "plugin": [["file:///absolute/path/to/opencode-agent-dock/src/index.tsx"]] }
+```
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-agent-dock",
-  "version": "0.1.0",
-  "description": "OpenCode TUI plugin — a Claude-Code-style bottom panel that groups the current session's subagents, with select / switch / open-session.",
+  "version": "1.0.0",
+  "description": "OpenCode TUI plugin — a Claude-Code-style bottom panel of running subagents with inline keyboard navigation.",
   "type": "module",
   "exports": {
     "./tui": {
@@ -14,6 +14,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "format:check": "prettier --check \"src/**/*.{ts,tsx}\""
@@ -37,30 +38,24 @@
   "bugs": {
     "url": "https://github.com/arttttt/opencode-agent-dock/issues"
   },
-  "dependencies": {
-    "@opencode-ai/plugin": "^1.18.4",
-    "@opencode-ai/sdk": "^1.18.4"
-  },
   "peerDependencies": {
-    "@opentui/core": ">=0.4.5",
-    "@opentui/keymap": ">=0.4.5",
+    "@opencode-ai/plugin": ">=1.18.0",
+    "@opencode-ai/sdk": ">=1.18.0",
     "@opentui/solid": ">=0.4.5"
   },
   "peerDependenciesMeta": {
-    "@opentui/core": { "optional": true },
-    "@opentui/keymap": { "optional": true },
     "@opentui/solid": { "optional": true }
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.18.4",
     "@opencode-ai/sdk": "^1.18.4",
     "@opentui/core": ">=0.4.5",
-    "@opentui/keymap": ">=0.4.5",
     "@opentui/solid": ">=0.4.5",
     "@types/bun": "latest",
     "prettier": "^3.8.1",
     "solid-js": "^1.9.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
   },
   "engines": {
     "opencode": "^1.18.0"

package/src/domain.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from "vitest";
+import {
+  sortSubagents,
+  clampSelection,
+  formatElapsed,
+  formatTokens,
+  truncate,
+  isTerminal,
+  toRow,
+  type Subagent,
+} from "./domain.js";
+import { statusFromSessionStatus } from "./sdk.js";
+
+const sub = (overrides: Partial<Subagent> = {}): Subagent => ({
+  id: "ses_1",
+  title: "Analyze architecture",
+  status: "running",
+  startedAt: 0,
+  ...overrides,
+});
+
+describe("sortSubagents", () => {
+  it("orders running before idle before terminal states", () => {
+    const list = [
+      sub({ id: "done", status: "done", startedAt: 1 }),
+      sub({ id: "idle", status: "idle", startedAt: 2 }),
+      sub({ id: "run", status: "running", startedAt: 3 }),
+    ];
+    expect(sortSubagents(list).map((s) => s.id)).toEqual(["run", "idle", "done"]);
+  });
+
+  it("falls back to newest-first within the same status", () => {
+    const list = [
+      sub({ id: "old", status: "running", startedAt: 10 }),
+      sub({ id: "new", status: "running", startedAt: 90 }),
+    ];
+    expect(sortSubagents(list).map((s) => s.id)).toEqual(["new", "old"]);
+  });
+
+  it("does not mutate the input", () => {
+    const list = [sub({ id: "a" }), sub({ id: "b" })];
+    const snapshot = list.map((s) => s.id);
+    sortSubagents(list);
+    expect(list.map((s) => s.id)).toEqual(snapshot);
+  });
+});
+
+describe("clampSelection", () => {
+  it("returns 0 for an empty list", () => {
+    expect(clampSelection(5, 0)).toBe(0);
+  });
+  it("clamps below 0 to 0", () => {
+    expect(clampSelection(-3, 4)).toBe(0);
+  });
+  it("clamps overflow to the last index", () => {
+    expect(clampSelection(99, 4)).toBe(3);
+  });
+  it("passes through in-range values", () => {
+    expect(clampSelection(2, 4)).toBe(2);
+  });
+});
+
+describe("formatElapsed", () => {
+  it("formats seconds under a minute", () => {
+    expect(formatElapsed(0, 59_000)).toBe("59s");
+  });
+  it("formats minutes with zero-padded seconds", () => {
+    expect(formatElapsed(0, 125_000)).toBe("2m 05s");
+  });
+  it("formats hours with zero-padded minutes", () => {
+    expect(formatElapsed(0, 3_725_000)).toBe("1h 02m");
+  });
+  it("never goes negative", () => {
+    expect(formatElapsed(10_000, 0)).toBe("0s");
+  });
+});
+
+describe("formatTokens", () => {
+  it("returns empty for undefined / non-positive", () => {
+    expect(formatTokens(undefined)).toBe("");
+    expect(formatTokens(0)).toBe("");
+  });
+  it("renders raw numbers under 1000", () => {
+    expect(formatTokens(500)).toBe("500");
+    expect(formatTokens(999)).toBe("999");
+  });
+  it("renders thousands with a k suffix", () => {
+    expect(formatTokens(1500)).toBe("1.5k");
+    expect(formatTokens(85_400)).toBe("85.4k");
+  });
+});
+
+describe("truncate", () => {
+  it("trims and returns short text as-is", () => {
+    expect(truncate("  hi  ", 10)).toBe("hi");
+  });
+  it("truncates with an ellipsis when too long", () => {
+    expect(truncate("hello world", 5)).toBe("hell…");
+  });
+  it("handles exact length without truncation", () => {
+    expect(truncate("hello", 5)).toBe("hello");
+  });
+});
+
+describe("isTerminal", () => {
+  it("treats done and error as terminal", () => {
+    expect(isTerminal("done")).toBe(true);
+    expect(isTerminal("error")).toBe(true);
+  });
+  it("treats running and idle as non-terminal", () => {
+    expect(isTerminal("running")).toBe(false);
+    expect(isTerminal("idle")).toBe(false);
+  });
+});
+
+describe("toRow", () => {
+  it("maps status to a glyph", () => {
+    expect(toRow(sub({ status: "running" }), 0, 48).glyph).toBe("●");
+    expect(toRow(sub({ status: "done" }), 0, 48).glyph).toBe("✓");
+  });
+  it("shows elapsed + tokens in meta for a running subagent", () => {
+    const row = toRow(sub({ status: "running", startedAt: 0, tokens: 1500 }), 30_000, 48);
+    expect(row.meta).toBe("30s · 1.5k");
+  });
+  it("drops elapsed for terminal states", () => {
+    const row = toRow(sub({ status: "done", tokens: 500 }), 30_000, 48);
+    expect(row.meta).toBe("500");
+  });
+  it("falls back to the id when the title is empty", () => {
+    expect(toRow(sub({ title: "", id: "ses_x" }), 0, 48).label).toBe("ses_x");
+  });
+});
+
+describe("statusFromSessionStatus", () => {
+  it("maps busy and retry to running", () => {
+    expect(statusFromSessionStatus({ type: "busy" })).toBe("running");
+    expect(statusFromSessionStatus({ type: "retry", attempt: 1, message: "x", next: 1 })).toBe("running");
+  });
+  it("maps idle to idle", () => {
+    expect(statusFromSessionStatus({ type: "idle" })).toBe("idle");
+  });
+  it("maps undefined to done", () => {
+    expect(statusFromSessionStatus(undefined)).toBe("done");
+  });
+});

package/src/index.tsx

@@ -80,25 +80,24 @@ const tui: TuiPlugin = async (api) => {
   // Inline navigation: intercept arrows/enter while the dock is focused.
   api.keymap.intercept(
     "key",
-    ({ event }) => {
+    ({ event }: { event: InterceptEvent }) => {
       if (!focused()) return;
-      const ev = event as InterceptEvent;
       const rows = store.snapshot();
       if (rows.length === 0) {
         exitDock();
         return;
       }
-      switch (ev.name) {
+      switch (event.name) {
         case "up":
           if (selection() <= 0) exitDock();
           else setSelection((current) => current - 1);
-          ev.preventDefault();
-          ev.stopPropagation();
+          event.preventDefault();
+          event.stopPropagation();
           break;
         case "down":
           setSelection((current) => clampSelection(current + 1, rows.length));
-          ev.preventDefault();
-          ev.stopPropagation();
+          event.preventDefault();
+          event.stopPropagation();
           break;
         case "return": {
           const target = rows[clampSelection(selection(), rows.length)];
@@ -106,8 +105,8 @@ const tui: TuiPlugin = async (api) => {
             exitDock();
             api.route.navigate("session", { sessionID: target.id });
           }
-          ev.preventDefault();
-          ev.stopPropagation();
+          event.preventDefault();
+          event.stopPropagation();
           break;
         }
       }