@danielbdev/opencode-agents 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel
+
+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

@@ -1,3 +1,80 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @danielbdev/opencode-agents
+
+An [OpenCode](https://opencode.ai) V2 plugin that shows the status of your **subagents** in the session
+sidebar, below the MCP block.
+
+## Install
+
+```sh
+opencode plugin add @danielbdev/opencode-agents
+```
+
+Requires OpenCode V2.
+
+## What it shows
+
+```
+Agents
+2 running · 4 done · 1 failed
+explore · 42s
+general · 3m
+verify · failed · 3m
+```
+
+Succeeded subagents are counted but not listed, so the section stays short. Running ones come first,
+then the failed ones.
+
+Colour comes from the theme's semantic feedback slots — succeeded green, running yellow, failed or
+interrupted red — and the count line takes the worst state present, so a failure colours the whole
+section at a glance. Nothing here names a colour: it resolves through `theme.text.feedback[kind].base`,
+so the semaphore follows whatever theme you run.
+
+## How it works
+
+TUI-only: subagent data is already in the TUI's data layer, so this package ships **no server half, no
+credential handling and no RPC**. It reads the session family of the session it renders in.
+
+The state comes from fields that are queryable, not inferred from events:
+
+| Field | Meaning |
+| ----- | ------- |
+| `parentID` | marks a record as a subagent |
+| `agent` | the agent name |
+| `outcome` | `succeeded`, `failed` or `interrupted` |
+| `time.created` / `time.idle` | elapsed time |
+| `data.session.status(id)` | adds the liveness bit: `idle` or `running` |
+
+## Security
+
+This plugin **reads no credentials and makes no network requests**. It has no server half, so there is
+nothing to authenticate and nothing to send anywhere.
+
+What it does read is the host's session records for the session it renders in: the agent name, the outcome
+and the timing of each subagent. That is the feature — a status section cannot work without reading
+status. Nothing is written back, nothing is persisted, and the data never leaves the TUI process.
+
+Like every package in this repository it ships its sources unminified, with no build step and no
+install-time script, and each release carries a provenance attestation.
+
+## Development
+
+```sh
+npm install
+npm test        # node --test, no build step (Node 24 type stripping)
+npm run typecheck
+```
+
+`src/core/agents.ts` holds the state mapping, the counts and the formatters with no host dependency, so
+all of it runs under plain `node --test`.
+
+This package lives in a monorepo of atomic plugins: each package does one thing and installs alone.
+
+## Releasing
+
+Same flow as every package in this repository: bump, commit, tag `<directory>@<version>`, push the tag,
+and GitHub Actions publishes it over OIDC. See the repository README of the sibling package for the
+exact commands.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,47 @@
-{
-  "name": "@danielbdev/opencode-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@danielbdev/opencode-agents",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenCode V2 plugin that shows subagent status in the session sidebar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielbdev/opencode-plugins.git",
+    "directory": "packages/agents"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-agents",
+    "subagents",
+    "sidebar"
+  ],
+  "exports": {
+    "./tui": "./src/tui.tsx"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.4"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@opencode/client": "^2.0.4",
+    "@opencode/theme": "^2.0.4",
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/core/agents.test.ts

@@ -0,0 +1,204 @@
+import { test } from "node:test"
+import assert from "node:assert/strict"
+
+import {
+  feedbackOf,
+  formatAgentLine,
+  formatCounts,
+  formatElapsed,
+  stateOf,
+  summarize,
+  summaryFeedback,
+  type SessionLike,
+} from "./agents.ts"
+
+const NOW = 1_800_000_000_000
+
+function subagent(overrides: Partial<SessionLike> & { id: string }): SessionLike {
+  return { parentID: "ses_root", agent: "explore", time: { created: NOW - 42_000 }, ...overrides }
+}
+
+test("stateOf reads the queryable outcome before anything else", () => {
+  assert.equal(stateOf({ id: "a", outcome: "succeeded" }, false), "succeeded")
+  assert.equal(stateOf({ id: "a", outcome: "failed" }, false), "failed")
+  assert.equal(stateOf({ id: "a", outcome: "interrupted" }, false), "interrupted")
+  assert.equal(stateOf({ id: "a", outcome: "succeeded" }, true), "succeeded")
+})
+
+test("stateOf falls back to liveness when there is no outcome yet", () => {
+  assert.equal(stateOf({ id: "a" }, true), "running")
+  assert.equal(stateOf({ id: "a" }, false), "idle")
+})
+
+test("summarize counts only subagents and ignores the root session", () => {
+  const summary = summarize(
+    [
+      { id: "ses_root", agent: "gentle-orchestrator" },
+      subagent({ id: "s1", outcome: "succeeded" }),
+      subagent({ id: "s2", outcome: "failed" }),
+    ],
+    new Set(),
+    NOW,
+  )
+
+  assert.equal(summary.total, 2)
+  assert.equal(summary.succeeded, 1)
+  assert.equal(summary.failed, 1)
+  assert.equal(summary.running, 0)
+  assert.equal(summary.done, 1)
+})
+
+test("summarize separates done from failed and counts running separately", () => {
+  const summary = summarize(
+    [
+      subagent({ id: "s1", outcome: "succeeded" }),
+      subagent({ id: "s2", outcome: "succeeded" }),
+      subagent({ id: "s3", outcome: "interrupted" }),
+      subagent({ id: "s4" }),
+      subagent({ id: "s5" }),
+    ],
+    new Set(["s4", "s5"]),
+    NOW,
+  )
+
+  assert.equal(summary.total, 5)
+  assert.equal(summary.succeeded, 2)
+  assert.equal(summary.failed, 1)
+  assert.equal(summary.running, 2)
+  assert.equal(summary.done, 2)
+})
+
+test("summarize lists running first, then failed, and never lists succeeded ones", () => {
+  const summary = summarize(
+    [
+      subagent({ id: "ok", outcome: "succeeded" }),
+      subagent({ id: "boom", outcome: "failed", agent: "verify" }),
+      subagent({ id: "busy", agent: "general" }),
+    ],
+    new Set(["busy"]),
+    NOW,
+  )
+
+  assert.deepEqual(
+    summary.entries.map((entry) => [entry.id, entry.state]),
+    [
+      ["busy", "running"],
+      ["boom", "failed"],
+    ],
+  )
+  assert.equal(summary.entries[0]?.name, "general")
+})
+
+test("summarize measures a running subagent against now and a finished one against its end", () => {
+  const summary = summarize(
+    [
+      subagent({ id: "busy", time: { created: NOW - 90_000 } }),
+      subagent({ id: "done", outcome: "succeeded", time: { created: NOW - 500_000, idle: NOW - 440_000 } }),
+      subagent({ id: "no-idle", outcome: "failed", time: { created: NOW - 30_000, updated: NOW - 10_000 } }),
+    ],
+    new Set(["busy"]),
+    NOW,
+  )
+
+  const byId = new Map(summary.entries.map((entry) => [entry.id, entry]))
+  assert.equal(byId.get("busy")?.elapsedMs, 90_000)
+  assert.equal(byId.get("no-idle")?.elapsedMs, 20_000)
+})
+
+test("summarize names an unnamed subagent and survives a missing time block", () => {
+  const summary = summarize([subagent({ id: "s1", agent: undefined, time: undefined })], new Set(), NOW)
+
+  assert.equal(summary.entries.length, 0)
+  assert.equal(summary.total, 1)
+
+  const named = summarize(
+    [subagent({ id: "s2", agent: undefined, outcome: "failed" })],
+    new Set(),
+    NOW,
+  )
+  assert.equal(named.entries[0]?.name, "subagent")
+})
+
+test("formatElapsed renders seconds, minutes and hours", () => {
+  assert.equal(formatElapsed(0), "0s")
+  assert.equal(formatElapsed(42_000), "42s")
+  assert.equal(formatElapsed(59_999), "59s")
+  assert.equal(formatElapsed(60_000), "1m")
+  assert.equal(formatElapsed(192_000), "3m")
+  assert.equal(formatElapsed(3_900_000), "1h 5m")
+})
+
+test("formatCounts omits a zero failed bucket and has an explicit empty state", () => {
+  const busy = summarize(
+    [subagent({ id: "a" }), subagent({ id: "b", outcome: "succeeded" })],
+    new Set(["a"]),
+    NOW,
+  )
+  assert.equal(formatCounts(busy), "1 running · 1 done")
+
+  const broken = summarize(
+    [subagent({ id: "a", outcome: "failed" }), subagent({ id: "b", outcome: "succeeded" })],
+    new Set(),
+    NOW,
+  )
+  assert.equal(formatCounts(broken), "0 running · 1 done · 1 failed")
+
+  const empty = summarize([{ id: "ses_root" }], new Set(), NOW)
+  assert.equal(formatCounts(empty), "no subagents yet")
+})
+
+test("formatAgentLine pairs the name with the elapsed time", () => {
+  assert.equal(
+    formatAgentLine({ id: "a", name: "explore", state: "running", elapsedMs: 42_000 }),
+    "explore · 42s",
+  )
+  assert.equal(
+    formatAgentLine({ id: "b", name: "verify", state: "failed", elapsedMs: 192_000 }),
+    "verify · failed · 3m",
+  )
+})
+
+test("feedbackOf maps every state onto a theme feedback kind", () => {
+  assert.equal(feedbackOf("running"), "warning")
+  assert.equal(feedbackOf("succeeded"), "success")
+  assert.equal(feedbackOf("failed"), "error")
+  assert.equal(feedbackOf("interrupted"), "error")
+  assert.equal(feedbackOf("idle"), "info")
+})
+
+test("a failed subagent keeps its final duration even while liveness still reports running", () => {
+  const summary = summarize(
+    [
+      subagent({
+        id: "boom",
+        outcome: "failed",
+        time: { created: NOW - 60_000, updated: NOW - 20_000 },
+      }),
+    ],
+    // Liveness lags: the outcome is already recorded but the status bit still says running.
+    new Set(["boom"]),
+    NOW,
+  )
+
+  assert.equal(summary.entries[0]?.state, "failed")
+  assert.equal(summary.entries[0]?.elapsedMs, 40_000)
+})
+
+test("summaryFeedback reports the worst state present", () => {
+  const allGood = summarize([subagent({ id: "a", outcome: "succeeded" })], new Set(), NOW)
+  assert.equal(summaryFeedback(allGood), "success")
+
+  const busy = summarize([subagent({ id: "a" }), subagent({ id: "b", outcome: "succeeded" })], new Set(["a"]), NOW)
+  assert.equal(summaryFeedback(busy), "warning")
+
+  const broken = summarize([subagent({ id: "a" }), subagent({ id: "b", outcome: "failed" })], new Set(["a"]), NOW)
+  assert.equal(summaryFeedback(broken), "error")
+
+  const empty = summarize([], new Set(), NOW)
+  assert.equal(summaryFeedback(empty), "info")
+
+  // Finished without a recorded outcome is still a green section: nothing is
+  // running and nothing failed.
+  const idleOnly = summarize([subagent({ id: "a" })], new Set(), NOW)
+  assert.equal(summaryFeedback(idleOnly), "success")
+})

package/src/core/agents.ts

@@ -0,0 +1,168 @@
+/**
+ * Pure model for the subagent section.
+ *
+ * Everything here is host-free on purpose: the TUI plugin feeds it the session
+ * records it already has, so the whole state mapping, the counts and the
+ * formatters run under plain `node --test`.
+ *
+ * The fields come from `SessionInfo` in `@opencode/client`, verified rather
+ * than assumed:
+ *
+ *   parentID?: string                                    // marks a subagent
+ *   agent?: string                                       // the agent name
+ *   outcome?: "succeeded" | "failed" | "interrupted"     // queryable state
+ *   time: { created, updated, idle? }
+ *
+ * Liveness is not part of the record: `data.session.status(id)` reports it, so
+ * the caller passes the running ids in.
+ */
+
+export type AgentState = "running" | "succeeded" | "failed" | "interrupted" | "idle"
+
+/** The theme's semantic colour slots, so the view never names a colour. */
+export type FeedbackKind = "success" | "warning" | "error" | "info"
+
+/** The slice of a session record this module needs. */
+export interface SessionLike {
+  readonly id: string
+  readonly parentID?: string
+  readonly agent?: string
+  readonly outcome?: "succeeded" | "failed" | "interrupted"
+  readonly time?: {
+    readonly created?: number
+    readonly updated?: number
+    readonly idle?: number
+  }
+}
+
+export interface AgentEntry {
+  readonly id: string
+  readonly name: string
+  readonly state: AgentState
+  readonly elapsedMs: number
+}
+
+export interface AgentSummary {
+  /** Only the subagents worth a line: running first, then the failed ones. */
+  readonly entries: readonly AgentEntry[]
+  readonly running: number
+  readonly succeeded: number
+  /** Failed and interrupted together: both stopped for a reason. */
+  readonly failed: number
+  /** Finished without failing: succeeded or simply no longer running. */
+  readonly done: number
+  readonly total: number
+}
+
+const UNNAMED = "subagent"
+
+/** A recorded outcome wins over liveness; liveness only covers the gap before one exists. */
+export function stateOf(session: SessionLike, running: boolean): AgentState {
+  if (session.outcome === "succeeded") return "succeeded"
+  if (session.outcome === "failed") return "failed"
+  if (session.outcome === "interrupted") return "interrupted"
+  return running ? "running" : "idle"
+}
+
+function elapsedOf(session: SessionLike, running: boolean, now: number): number {
+  const created = session.time?.created
+  if (created === undefined) return 0
+
+  // A running subagent is measured against now; a finished one against when it
+  // stopped, falling back to its last update when no idle stamp exists.
+  const end = running ? now : (session.time?.idle ?? session.time?.updated ?? now)
+  return Math.max(0, end - created)
+}
+
+function isSubagent(session: SessionLike): boolean {
+  return session.parentID !== undefined
+}
+
+function isFailure(state: AgentState): boolean {
+  return state === "failed" || state === "interrupted"
+}
+
+/** Subagents only: the root session is the session itself, not a child. */
+export function summarize(
+  sessions: readonly SessionLike[],
+  runningIds: ReadonlySet<string>,
+  now: number,
+): AgentSummary {
+  const entries: AgentEntry[] = []
+  let running = 0
+  let succeeded = 0
+  let failed = 0
+  let done = 0
+
+  const listed: AgentEntry[] = []
+
+  for (const session of sessions) {
+    if (!isSubagent(session)) continue
+
+    const isRunning = runningIds.has(session.id)
+    const state = stateOf(session, isRunning)
+
+    if (state === "running") running += 1
+    if (state === "succeeded") succeeded += 1
+    if (isFailure(state)) failed += 1
+    if (state === "succeeded" || state === "idle") done += 1
+
+    if (state === "running" || isFailure(state)) {
+      listed.push({
+        id: session.id,
+        name: session.agent ?? UNNAMED,
+        state,
+        // Measured against the state actually shown, not the raw liveness bit: a
+        // recorded outcome wins over liveness in `stateOf`, so keying the clock
+        // off liveness would let a failed entry's duration keep growing.
+        elapsedMs: elapsedOf(session, state === "running", now),
+      })
+    }
+  }
+
+  entries.push(
+    ...listed.filter((entry) => entry.state === "running"),
+    ...listed.filter((entry) => isFailure(entry.state)),
+  )
+
+  return { entries, running, succeeded, failed, done, total: running + done + failed }
+}
+
+export function formatElapsed(ms: number): string {
+  if (ms < 60_000) return `${Math.floor(ms / 1000)}s`
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m`
+
+  const hours = Math.floor(ms / 3_600_000)
+  const minutes = Math.floor((ms % 3_600_000) / 60_000)
+  return `${hours}h ${minutes}m`
+}
+
+export function formatCounts(summary: AgentSummary): string {
+  if (summary.total === 0) return "no subagents yet"
+
+  const parts = [`${summary.running} running`, `${summary.done} done`]
+  if (summary.failed > 0) parts.push(`${summary.failed} failed`)
+  return parts.join(" · ")
+}
+
+export function formatAgentLine(entry: AgentEntry): string {
+  const elapsed = formatElapsed(entry.elapsedMs)
+  return entry.state === "running"
+    ? `${entry.name} · ${elapsed}`
+    : `${entry.name} · ${entry.state} · ${elapsed}`
+}
+
+export function feedbackOf(state: AgentState): FeedbackKind {
+  if (state === "failed" || state === "interrupted") return "error"
+  if (state === "running") return "warning"
+  if (state === "succeeded") return "success"
+  return "info"
+}
+
+/** The count line takes the worst state present, so a failure colours the whole section. */
+export function summaryFeedback(summary: AgentSummary): FeedbackKind {
+  if (summary.failed > 0) return "error"
+  if (summary.running > 0) return "warning"
+  if (summary.done > 0) return "success"
+  return "info"
+}

package/src/tui.tsx

@@ -0,0 +1,95 @@
+/** @jsxImportSource @opentui/solid */
+import { Plugin } from "@opencode/plugin/tui"
+import { createMemo, createSignal, onCleanup } from "solid-js"
+
+import {
+  feedbackOf,
+  formatAgentLine,
+  formatCounts,
+  summarize,
+  summaryFeedback,
+  type FeedbackKind,
+  type SessionLike,
+} from "./core/agents.ts"
+
+/** Elapsed times move on their own; a running subagent needs no event to age. */
+const ELAPSED_TICK_MS = 10_000
+
+const EMPTY = summarize([], new Set(), Date.now())
+
+/**
+ * Colours come from the theme's semantic feedback slots
+ * (`FeedbackKind = error | warning | success | info`), so the semaphore follows
+ * whatever theme is active instead of naming a colour here.
+ */
+function feedbackColor(context: Plugin.Context, kind: FeedbackKind): string {
+  const feedback = (
+    context.theme as unknown as
+      | { text?: { feedback?: Record<string, { base?: unknown } | undefined> } }
+      | undefined
+  )?.text?.feedback
+
+  return (feedback?.[kind]?.base ?? "white") as string
+}
+
+function titleColor(context: Plugin.Context): string {
+  const text = (context.theme as unknown as { text?: Record<string, unknown> } | undefined)?.text
+  return (text?.["base"] ?? "white") as string
+}
+
+/**
+ * TUI-only plugin.
+ *
+ * Subagent data is already in the TUI's data layer, so there is no server half,
+ * no credential and no RPC: the section reads the session family of the session
+ * it renders in.
+ */
+export default Plugin.define({
+  id: "opencode-agents.tui",
+  setup(context) {
+    const AgentsSection = (props: { sessionID: string }) => {
+      const [tick, setTick] = createSignal(0)
+
+      const timer = setInterval(() => setTick((value) => value + 1), ELAPSED_TICK_MS)
+      onCleanup(() => clearInterval(timer))
+
+      const stopEvents = context.data.listen(({ details }) => {
+        if (details.type.startsWith("session.")) setTick((value) => value + 1)
+      })
+      onCleanup(() => stopEvents())
+
+      const summary = createMemo(() => {
+        tick()
+
+        const root = props.sessionID
+        if (!root) return EMPTY
+
+        const ids = context.data.session.family(root)
+        const sessions = ids
+          .map((id) => context.data.session.get(id))
+          .filter((session): session is NonNullable<typeof session> => session !== undefined)
+
+        const running = new Set(ids.filter((id) => context.data.session.status(id) === "running"))
+
+        return summarize(sessions as readonly SessionLike[], running, Date.now())
+      })
+
+      return (
+        <box flexDirection="column">
+          <text fg={titleColor(context)}>Agents</text>
+          <text fg={feedbackColor(context, summaryFeedback(summary()))}>{formatCounts(summary())}</text>
+          {summary().entries.map((entry) => (
+            <text fg={feedbackColor(context, feedbackOf(entry.state))}>{formatAgentLine(entry)}</text>
+          ))}
+        </box>
+      )
+    }
+
+    const stopSlot = context.ui.slot({
+      append: "sidebar.content",
+      render: (input) => <AgentsSection sessionID={input.sessionID} />,
+    })
+
+    return () => stopSlot()
+  },
+})