opencode-agent-progress 0.1.0

package/DESIGN.md

@@ -0,0 +1,55 @@
+# OpenCode Agent Progress Design System
+
+## 0. Research Log
+
+- Embedded reference: OpenCode native sidebar and OMO 4.19 progress sections define the layout contract.
+- Runtime reference: `opencode-metrics` proves node-level render invalidation works on OpenTUI 0.4.x.
+- Skipped Lazyweb and image drafts: this is a terminal-native compatibility surface with a concrete host reference.
+
+## 1. Atmosphere & Identity
+
+A quiet operational instrument that looks native to OpenCode. Its signature is immediate state clarity: the main session and every subordinate activity change in place without decorative motion or separate branding.
+
+## 2. Color
+
+All colors come from `TuiThemeCurrent`. Primary text uses `text`, metadata uses `textMuted`, active work uses `accent`, retries use `warning`, failures use `error`, and completed work uses `success`. The plugin never declares raw color values.
+
+## 3. Typography
+
+The host terminal owns font family, size, line height, and character width. Labels are concise English identifiers because terminal alignment and log scanning are the primary use cases. Status text stays on one line and truncates before it can resize the sidebar.
+
+## 4. Spacing & Layout
+
+OpenTUI character cells are the base unit. Sections use one-cell vertical separation, one-cell inner padding when bordered, and full available sidebar width. The layout is a single vertical stack with no nested cards.
+
+## 5. Components
+
+### Progress Section
+
+- **Structure**: title followed by compact status rows.
+- **Variants**: main session, agents, jobs, and ULW loop.
+- **States**: idle, busy, retry, running, completed, error, cancelled, stale, and empty.
+- **Accessibility**: status is always expressed in text, never color alone.
+- **Motion**: none; content changes in place.
+- **Layout**: full-width terminal stack with bounded labels.
+
+### Status Row
+
+- **Structure**: left label and right status/value.
+- **Variants**: neutral, active, success, warning, and error.
+- **States**: visible or omitted; no disabled interaction state.
+- **Accessibility**: stable text labels and theme-provided contrast.
+- **Motion**: none.
+- **Layout**: one terminal row with deterministic width.
+
+## 6. Motion & Interaction
+
+Updates are immediate and non-animated. The plugin does not add controls in its first release; state changes are informational and must never steal keyboard focus.
+
+## 7. Depth & Surface
+
+The strategy is borders-only, inherited from the host theme. Each major section may use one native single-line border; rows never become separate cards.
+
+## 8. Accessibility Constraints & Accepted Debt
+
+All state meaning must survive monochrome terminals. Labels are bounded to prevent clipping. Accepted debt for `0.1.0`: narrow terminals below the host sidebar minimum are governed by OpenCode itself rather than a plugin-specific responsive mode.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mingjian Shao
+
+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,105 @@
+# opencode-agent-progress
+
+Live OpenCode sidebar progress for the main session, OMO agents, background jobs, and ULW loops.
+
+The plugin exists to keep progress visible when host-level redraws lag behind state updates. It reads
+OpenCode session state directly, consumes the OMO v1 mirror, and updates mounted OpenTUI nodes without
+requiring the user to leave and re-enter a session.
+
+## Requirements
+
+- OpenCode `1.18.3` (verified; other releases require the validation described below)
+- `@opencode-ai/plugin` `1.17.x`
+- OpenTUI `0.3.4` through `0.4.x`
+- OMO `4.19.x` for agents, jobs, and ULW mirror data
+
+The main-session section works without OMO. When no compatible mirror exists, the sidebar reports
+`waiting`, `invalid`, or `stale` instead of rendering untrusted data.
+
+## Local installation
+
+Install and validate the project:
+
+```bash
+pnpm install
+pnpm check
+```
+
+Add the local TUI plugin to `~/.config/opencode/tui.json`. Keep the OMO entry so it remains installed,
+but deactivate only its TUI module to avoid duplicate sidebar sections:
+
+```json
+{
+  "plugin": [
+    "oh-my-openagent@latest",
+    "file:///absolute/path/to/opencode-agent-progress/src/tui.tsx"
+  ],
+  "plugin_enabled": {
+    "oh-my-openagent:tui": false
+  }
+}
+```
+
+Do not set OMO's `tui.sidebar.enabled` to `false`. That setting also stops the server-side mirror writer,
+so agent, job, and ULW state would no longer reach this plugin.
+
+Leave `oh-my-openagent@latest` enabled in `opencode.json` so OMO orchestration and mirror generation keep
+running. Restart the OpenCode TUI after changing plugin configuration, then open the sidebar with the
+configured `sidebar_toggle` binding. The default is `<leader>b`.
+
+## Displayed state
+
+- **Main**: session title, status, active agent, and model.
+- **Agents**: active OMO agent names and states.
+- **Jobs**: bounded job labels, status, and tool-call count.
+- **ULW**: goals, checks, queue, and active goal.
+- **OMO**: mirror health when live OMO state is unavailable.
+
+Status is always expressed as text. Theme colors add emphasis but never carry meaning alone.
+
+## Runtime design
+
+OpenCode events trigger immediate reads for connection, session, message, and todo updates. A one-second
+poll is retained for OMO's file mirror and as a reconnect fallback. Identical views are deduplicated.
+
+The sidebar uses fixed OpenTUI row slots and updates `TextRenderable` nodes directly. Each changed node
+requests its own render; the plugin does not call the host's global `api.renderer.requestRender()`.
+Mounted nodes own controller cleanup, so event subscriptions and timers are released when the sidebar is
+destroyed or replaced.
+
+OMO mirror compatibility is intentionally strict:
+
+- SHA-1 project hash and canonical path matching follow OMO's mirror-path contract.
+- Zod parses schema version `1` at the file boundary.
+- Mirrors older than six seconds are marked stale.
+- Unknown schemas fail closed as `invalid`.
+
+## Development
+
+```bash
+bun test
+bun run typecheck
+bun run lint
+bun run build
+```
+
+`bunfig.toml` preloads the official OpenTUI Solid transform. Source TSX remains the package entry because
+OpenCode's TUI plugin loader compiles it in the host runtime.
+
+## Verified matrix
+
+| Surface | Version | Result |
+|---|---:|---|
+| OpenCode | `1.18.3` | Local file plugin loaded from isolated `tui.json` |
+| `@opencode-ai/plugin` | `1.17.16` | Typecheck and runtime slot registration passed |
+| OpenTUI | `0.4.3` | In-memory renderer and real TUI passed |
+| OMO mirror | schema `1` | Missing-to-live refresh passed without session re-entry |
+
+The isolated real-TUI check used a 120-column terminal. The plugin region measured 37 of 40 available
+columns, with no overflow and aligned borders.
+
+## Compatibility policy
+
+Host and OpenTUI upgrades must pass `pnpm check` plus an isolated real-TUI run before the supported range
+is widened. A new OMO mirror schema requires a new parser branch and fixtures; it must not be accepted by
+loosening the current schema.

package/dist/tui.d.ts

@@ -0,0 +1,11 @@
+import { TuiPlugin } from '@opencode-ai/plugin/tui';
+
+/** @jsxImportSource @opentui/solid */
+/** @jsxRuntime automatic */
+
+declare const plugin: {
+    id: string;
+    tui: TuiPlugin;
+};
+
+export { plugin as default };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "opencode-agent-progress",
+  "version": "0.1.0",
+  "description": "Live OpenCode TUI progress for the main session, subagents, jobs, and OMO loops",
+  "type": "module",
+  "main": "./src/tui.tsx",
+  "types": "./dist/tui.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/tui.tsx",
+      "types": "./dist/tui.d.ts"
+    }
+  },
+  "oc-plugin": [
+    "tui"
+  ],
+  "files": [
+    "dist/tui.d.ts",
+    "src",
+    "DESIGN.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "bun test",
+    "check": "bun run lint && bun run typecheck && bun run test && bun run build",
+    "prepublishOnly": "bun run check"
+  },
+  "dependencies": {
+    "solid-js": "1.9.12",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.17.0 <2",
+    "@opentui/core": ">=0.3.4 <0.5.0",
+    "@opentui/solid": ">=0.3.4 <0.5.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.4",
+    "@opencode-ai/plugin": "1.17.16",
+    "@opentui/core": "0.4.3",
+    "@opentui/solid": "0.4.3",
+    "@types/bun": "1.3.14",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "packageManager": "pnpm@11.13.1",
+  "license": "MIT"
+}

package/src/controller.ts

@@ -0,0 +1,71 @@
+import type { MainSessionView } from "./main-session"
+import type { MirrorFileResult } from "./mirror-file"
+import { type ProgressEventBus, registerRefreshEvents } from "./refresh-events"
+
+export type ProgressView = {
+  readonly main: MainSessionView
+  readonly mirror: MirrorFileResult
+}
+
+export interface ProgressSource {
+  read(): ProgressView
+}
+
+export interface ProgressClock {
+  every(intervalMs: number, task: () => void): () => void
+}
+
+export type ProgressControllerOptions = {
+  readonly source: ProgressSource
+  readonly eventBus: ProgressEventBus
+  readonly clock: ProgressClock
+  readonly intervalMs: number
+}
+
+export interface ProgressController {
+  get(): ProgressView
+  refresh(): void
+  subscribe(listener: (view: ProgressView) => void): () => void
+  dispose(): void
+}
+
+function progressViewKey(view: ProgressView): string {
+  return JSON.stringify(view)
+}
+
+export function createProgressController(options: ProgressControllerOptions): ProgressController {
+  let current = options.source.read()
+  let currentKey = progressViewKey(current)
+  let disposed = false
+  const listeners = new Set<(view: ProgressView) => void>()
+
+  const refresh = () => {
+    if (disposed) return
+    const next = options.source.read()
+    const nextKey = progressViewKey(next)
+    if (nextKey === currentKey) return
+
+    current = next
+    currentKey = nextKey
+    for (const listener of listeners) listener(current)
+  }
+
+  const disposeEvents = registerRefreshEvents(options.eventBus, refresh)
+  const disposeClock = options.clock.every(options.intervalMs, refresh)
+
+  return {
+    get: () => current,
+    refresh,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      disposeEvents()
+      disposeClock()
+      listeners.clear()
+    },
+  }
+}

package/src/main-session.ts

@@ -0,0 +1,36 @@
+export type SessionStatus = "idle" | "busy" | "retry"
+
+export type SessionRecord = {
+  readonly id: string
+  readonly title: string
+  readonly agent?: string
+  readonly model?: {
+    readonly id: string
+    readonly providerID: string
+  }
+}
+
+export interface MainSessionReader {
+  getSession(sessionID: string): SessionRecord | undefined
+  getStatus(sessionID: string): SessionStatus | undefined
+}
+
+export type MainSessionView = {
+  readonly sessionID: string
+  readonly title: string
+  readonly agent: string
+  readonly model: string
+  readonly status: SessionStatus
+}
+
+export function readMainSession(reader: MainSessionReader, sessionID: string): MainSessionView {
+  const session = reader.getSession(sessionID)
+  const model = session?.model
+  return {
+    sessionID,
+    title: session?.title ?? "Untitled",
+    agent: session?.agent ?? "main",
+    model: model ? `${model.providerID}/${model.id}` : "unknown",
+    status: reader.getStatus(sessionID) ?? "idle",
+  }
+}

package/src/mirror-file.ts

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto"
+import { readFileSync, realpathSync } from "node:fs"
+import { join, resolve } from "node:path"
+import type { OmoMirrorSnapshot } from "./mirror"
+import { parseOmoMirror } from "./mirror"
+
+export type MirrorFileResult =
+  | { readonly kind: "ready"; readonly snapshot: OmoMirrorSnapshot; readonly stale: boolean }
+  | { readonly kind: "missing" }
+  | { readonly kind: "invalid" }
+
+export type MirrorFileOptions = {
+  readonly projectDirectory: string
+  readonly dataHome: string
+  readonly now: () => number
+  readonly staleAfterMs: number
+}
+
+function canonicalProjectDirectory(projectDirectory: string): string {
+  try {
+    return realpathSync.native(projectDirectory)
+  } catch (error) {
+    if (error instanceof Error) return resolve(projectDirectory)
+    throw error
+  }
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (!(error instanceof Error) || !("code" in error)) return undefined
+  return typeof error.code === "string" ? error.code : undefined
+}
+
+export function omoMirrorFilePath(projectDirectory: string, dataHome: string): string {
+  const canonicalDirectory = canonicalProjectDirectory(projectDirectory)
+  const projectHash = createHash("sha1").update(canonicalDirectory).digest("hex").slice(0, 16)
+  return join(
+    dataHome,
+    "opencode",
+    "storage",
+    "oh-my-openagent",
+    "tui-state",
+    `${projectHash}.json`,
+  )
+}
+
+export function readOmoMirrorFile(options: MirrorFileOptions): MirrorFileResult {
+  const projectDirectory = canonicalProjectDirectory(options.projectDirectory)
+  const path = omoMirrorFilePath(projectDirectory, options.dataHome)
+  let raw: string
+  try {
+    raw = readFileSync(path, "utf8")
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return { kind: "missing" }
+    throw error
+  }
+
+  const parsed = parseOmoMirror(raw, projectDirectory)
+  if (parsed.kind === "invalid") return parsed
+  return {
+    kind: "ready",
+    snapshot: parsed.snapshot,
+    stale: options.now() - parsed.snapshot.updatedAt > options.staleAfterMs,
+  }
+}

package/src/mirror.ts

@@ -0,0 +1,105 @@
+import { z } from "zod"
+
+export type AgentStatus = "busy" | "idle" | "error" | "running" | "retry"
+export type JobStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt"
+
+export type AgentRow = {
+  readonly name: string
+  readonly status: AgentStatus
+}
+
+export type JobRow = {
+  readonly title: string
+  readonly status: JobStatus
+  readonly toolCalls: number | null
+  readonly lastTool: string | null
+}
+
+export type LoopProgress = {
+  readonly goalsDone: number
+  readonly goalsTotal: number
+  readonly pass: number
+  readonly fail: number
+  readonly pending: number
+  readonly blocked: number
+  readonly activeGoal: string | null
+}
+
+export type OmoMirrorSnapshot = {
+  readonly projectDir: string
+  readonly updatedAt: number
+  readonly activeAgents: readonly AgentRow[]
+  readonly jobBoard: readonly JobRow[]
+  readonly loop: LoopProgress | null
+}
+
+export type MirrorParseResult =
+  | { readonly kind: "valid"; readonly snapshot: OmoMirrorSnapshot }
+  | { readonly kind: "invalid" }
+
+const AgentRowSchema = z.object({
+  name: z.string(),
+  status: z.enum(["busy", "idle", "error", "running", "retry"]),
+})
+
+const JobRowSchema = z.object({
+  title: z.string(),
+  status: z.enum(["pending", "running", "completed", "error", "cancelled", "interrupt"]),
+  toolCalls: z.number().int().nonnegative().nullable(),
+  lastTool: z.string().nullable(),
+})
+
+const LoopSchema = z.object({
+  kind: z.literal("live"),
+  goalsDone: z.number().int().nonnegative(),
+  goalsTotal: z.number().int().nonnegative(),
+  pass: z.number().int().nonnegative(),
+  fail: z.number().int().nonnegative(),
+  pending: z.number().int().nonnegative(),
+  blocked: z.number().int().nonnegative(),
+  activeGoal: z.string().nullable(),
+})
+
+const OmoMirrorSchema = z.object({
+  version: z.literal(1),
+  projectDir: z.string(),
+  updatedAt: z.number().int().nonnegative(),
+  activeAgents: z.array(AgentRowSchema),
+  jobBoard: z.array(JobRowSchema),
+  loop: LoopSchema.nullable(),
+})
+
+export function parseOmoMirror(raw: string, expectedProjectDir: string): MirrorParseResult {
+  let input: unknown
+  try {
+    input = JSON.parse(raw)
+  } catch (error) {
+    if (error instanceof SyntaxError) return { kind: "invalid" }
+    throw error
+  }
+
+  const parsed = OmoMirrorSchema.safeParse(input)
+  if (!parsed.success || parsed.data.projectDir !== expectedProjectDir) return { kind: "invalid" }
+
+  const { loop } = parsed.data
+  return {
+    kind: "valid",
+    snapshot: {
+      projectDir: parsed.data.projectDir,
+      updatedAt: parsed.data.updatedAt,
+      activeAgents: parsed.data.activeAgents,
+      jobBoard: parsed.data.jobBoard,
+      loop: loop
+        ? {
+            goalsDone: loop.goalsDone,
+            goalsTotal: loop.goalsTotal,
+            pass: loop.pass,
+            fail: loop.fail,
+            pending: loop.pending,
+            blocked: loop.blocked,
+            activeGoal: loop.activeGoal,
+          }
+        : null,
+    },
+  }
+}

package/src/presentation.ts

@@ -0,0 +1,137 @@
+import type { ProgressView } from "./controller"
+import type { SessionStatus } from "./main-session"
+import type { AgentStatus, JobStatus, LoopProgress, OmoMirrorSnapshot } from "./mirror"
+
+export type ProgressTone = "neutral" | "active" | "success" | "warning" | "error"
+
+export type StatusRow = {
+  readonly label: string
+  readonly value: string
+  readonly tone: ProgressTone
+}
+
+export type ProgressSection = {
+  readonly title: string
+  readonly rows: readonly StatusRow[]
+}
+
+const MAIN_TONES = {
+  idle: "neutral",
+  busy: "active",
+  retry: "warning",
+} as const satisfies Record<SessionStatus, ProgressTone>
+
+const AGENT_TONES = {
+  idle: "neutral",
+  busy: "active",
+  running: "active",
+  retry: "warning",
+  error: "error",
+} as const satisfies Record<AgentStatus, ProgressTone>
+
+const JOB_TONES = {
+  pending: "warning",
+  running: "active",
+  completed: "success",
+  error: "error",
+  cancelled: "neutral",
+  interrupt: "warning",
+} as const satisfies Record<JobStatus, ProgressTone>
+
+function truncate(value: string, maximumLength: number): string {
+  return value.length <= maximumLength ? value : `${value.slice(0, maximumLength - 3)}...`
+}
+
+function mainSection(view: ProgressView): ProgressSection {
+  return {
+    title: "Main",
+    rows: [
+      {
+        label: truncate(view.main.title, 24),
+        value: view.main.status,
+        tone: MAIN_TONES[view.main.status],
+      },
+      { label: "agent", value: truncate(view.main.agent, 28), tone: "neutral" },
+      { label: "model", value: truncate(view.main.model, 28), tone: "neutral" },
+    ],
+  }
+}
+
+function agentSection(snapshot: OmoMirrorSnapshot): ProgressSection {
+  const rows: readonly StatusRow[] =
+    snapshot.activeAgents.length === 0
+      ? [{ label: "agents", value: "none", tone: "neutral" }]
+      : snapshot.activeAgents.map((agent) => ({
+          label: truncate(agent.name, 24),
+          value: agent.status,
+          tone: AGENT_TONES[agent.status],
+        }))
+  return { title: "Agents", rows }
+}
+
+function jobSection(snapshot: OmoMirrorSnapshot): ProgressSection {
+  const rows: readonly StatusRow[] =
+    snapshot.jobBoard.length === 0
+      ? [{ label: "jobs", value: "none", tone: "neutral" }]
+      : snapshot.jobBoard.map((job) => {
+          const calls = job.toolCalls === null ? "" : ` · ${job.toolCalls}`
+          return {
+            label: truncate(job.title, 16),
+            value: `${job.status}${calls}`,
+            tone: JOB_TONES[job.status],
+          }
+        })
+  return { title: "Jobs", rows }
+}
+
+function loopRows(loop: LoopProgress): readonly StatusRow[] {
+  const goalsTone: ProgressTone = loop.goalsDone === loop.goalsTotal ? "success" : "active"
+  const checksTone: ProgressTone = loop.fail > 0 ? "error" : loop.pass > 0 ? "success" : "neutral"
+  const queueTone: ProgressTone =
+    loop.blocked > 0 ? "error" : loop.pending > 0 ? "warning" : "neutral"
+  const rows: StatusRow[] = [
+    { label: "goals", value: `${loop.goalsDone}/${loop.goalsTotal}`, tone: goalsTone },
+    { label: "checks", value: `${loop.pass} pass · ${loop.fail} fail`, tone: checksTone },
+    { label: "queue", value: `${loop.pending} pending · ${loop.blocked} blocked`, tone: queueTone },
+  ]
+  if (loop.activeGoal !== null) {
+    rows.push({ label: "active", value: truncate(loop.activeGoal, 28), tone: "active" })
+  }
+  return rows
+}
+
+function loopSection(snapshot: OmoMirrorSnapshot): ProgressSection {
+  return {
+    title: "ULW",
+    rows:
+      snapshot.loop === null
+        ? [{ label: "loop", value: "inactive", tone: "neutral" }]
+        : loopRows(snapshot.loop),
+  }
+}
+
+export function buildProgressSections(view: ProgressView): readonly ProgressSection[] {
+  const main = mainSection(view)
+  switch (view.mirror.kind) {
+    case "missing":
+      return [
+        main,
+        { title: "OMO", rows: [{ label: "mirror", value: "waiting", tone: "neutral" }] },
+      ]
+    case "invalid":
+      return [main, { title: "OMO", rows: [{ label: "mirror", value: "invalid", tone: "error" }] }]
+    case "ready":
+      if (view.mirror.stale) {
+        return [
+          main,
+          { title: "OMO", rows: [{ label: "mirror", value: "stale", tone: "warning" }] },
+        ]
+      }
+      return [
+        main,
+        agentSection(view.mirror.snapshot),
+        jobSection(view.mirror.snapshot),
+        loopSection(view.mirror.snapshot),
+      ]
+  }
+}

package/src/refresh-events.ts

@@ -0,0 +1,20 @@
+export const REFRESH_EVENT_TYPES = [
+  "server.connected",
+  "session.status",
+  "session.updated",
+  "message.updated",
+  "todo.updated",
+] as const
+
+export type RefreshEventType = (typeof REFRESH_EVENT_TYPES)[number]
+
+export interface ProgressEventBus {
+  on(type: RefreshEventType, handler: () => void): () => void
+}
+
+export function registerRefreshEvents(eventBus: ProgressEventBus, refresh: () => void): () => void {
+  const disposers = REFRESH_EVENT_TYPES.map((type) => eventBus.on(type, refresh))
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,82 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
+import {
+  createProgressController,
+  type ProgressClock,
+  type ProgressController,
+  type ProgressSource,
+} from "./controller"
+import {
+  type MainSessionReader,
+  readMainSession,
+  type SessionRecord,
+  type SessionStatus,
+} from "./main-session"
+import { readOmoMirrorFile } from "./mirror-file"
+import type { ProgressEventBus } from "./refresh-events"
+
+const POLL_INTERVAL_MS = 1_000
+const MIRROR_STALE_MS = 6_000
+
+const SYSTEM_CLOCK: ProgressClock = {
+  every(intervalMs, task) {
+    const timer = setInterval(task, intervalMs)
+    return () => clearInterval(timer)
+  },
+}
+
+export interface HostSessionAccess {
+  get(sessionID: string): SessionRecord | undefined
+  status(sessionID: string): { readonly type: SessionStatus } | undefined
+}
+
+export function createHostSessionReader(session: HostSessionAccess): MainSessionReader {
+  return {
+    getSession: (sessionID) => session.get(sessionID),
+    getStatus: (sessionID) => session.status(sessionID)?.type,
+  }
+}
+
+export function createTuiProgressController(
+  api: Pick<TuiPluginApi, "state" | "event">,
+  sessionID: string,
+): ProgressController {
+  const sessionReader = createHostSessionReader(api.state.session)
+  const { XDG_DATA_HOME: configuredDataHome } = process.env
+  const dataHome = configuredDataHome ?? join(homedir(), ".local", "share")
+  const source: ProgressSource = {
+    read: () => ({
+      main: readMainSession(sessionReader, sessionID),
+      mirror: readOmoMirrorFile({
+        projectDirectory: api.state.path.directory,
+        dataHome,
+        now: Date.now,
+        staleAfterMs: MIRROR_STALE_MS,
+      }),
+    }),
+  }
+  const eventBus: ProgressEventBus = {
+    on(type, handler) {
+      switch (type) {
+        case "server.connected":
+          return api.event.on("server.connected", handler)
+        case "session.status":
+          return api.event.on("session.status", handler)
+        case "session.updated":
+          return api.event.on("session.updated", handler)
+        case "message.updated":
+          return api.event.on("message.updated", handler)
+        case "todo.updated":
+          return api.event.on("todo.updated", handler)
+      }
+    },
+  }
+
+  return createProgressController({
+    source,
+    eventBus,
+    clock: SYSTEM_CLOCK,
+    intervalMs: POLL_INTERVAL_MS,
+  })
+}

package/src/sidebar.tsx

@@ -0,0 +1,74 @@
+import type { TuiThemeCurrent } from "@opencode-ai/plugin/tui"
+import { type BoxRenderable, RenderableEvents } from "@opentui/core"
+import type { JSX } from "@opentui/solid"
+import type { ProgressController } from "./controller"
+import { buildProgressSections, type ProgressSection } from "./presentation"
+import { StatusSection } from "./status-section"
+
+export type ProgressPalette = Pick<
+  TuiThemeCurrent,
+  "text" | "textMuted" | "accent" | "success" | "warning" | "error" | "borderSubtle"
+>
+
+export type ProgressSidebarProps = {
+  readonly controller: ProgressController
+  readonly palette: ProgressPalette
+}
+
+const SECTION_SLOTS = [
+  { title: "Main", maximumRows: 3 },
+  { title: "Agents", maximumRows: 12 },
+  { title: "Jobs", maximumRows: 12 },
+  { title: "ULW", maximumRows: 4 },
+  { title: "OMO", maximumRows: 1 },
+] as const
+
+function indexSections(sections: readonly ProgressSection[]): ReadonlyMap<string, ProgressSection> {
+  return new Map(sections.map((section) => [section.title, section]))
+}
+
+export function ProgressSidebar(props: ProgressSidebarProps): JSX.Element {
+  let sections = indexSections(buildProgressSections(props.controller.get()))
+  let root: BoxRenderable | undefined
+  let disposed = false
+  const syncs = new Set<() => void>()
+
+  const syncAll = () => {
+    for (const sync of syncs) sync()
+    root?.requestRender()
+  }
+  const registerSync = (sync: () => void) => {
+    syncs.add(sync)
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    unsubscribe()
+    syncs.clear()
+    props.controller.dispose()
+  }
+  const attachRoot = (node: BoxRenderable) => {
+    root = node
+    node.once(RenderableEvents.DESTROYED, cleanup)
+    syncAll()
+    queueMicrotask(syncAll)
+  }
+  const unsubscribe = props.controller.subscribe((next) => {
+    sections = indexSections(buildProgressSections(next))
+    syncAll()
+    queueMicrotask(syncAll)
+  })
+
+  return (
+    <box ref={attachRoot} flexDirection="column" gap={1} width="100%">
+      {SECTION_SLOTS.map((slot) => (
+        <StatusSection
+          maximumRows={slot.maximumRows}
+          palette={props.palette}
+          section={() => sections.get(slot.title)}
+          registerSync={registerSync}
+        />
+      ))}
+    </box>
+  )
+}

package/src/status-section.tsx

@@ -0,0 +1,104 @@
+import type { BoxRenderable, TextRenderable } from "@opentui/core"
+import type { JSX } from "@opentui/solid"
+import type { ProgressSection, ProgressTone } from "./presentation"
+import type { ProgressPalette } from "./sidebar"
+
+type RowNodes = {
+  box?: BoxRenderable
+  label?: TextRenderable
+  value?: TextRenderable
+}
+
+export type StatusSectionProps = {
+  readonly maximumRows: number
+  readonly palette: ProgressPalette
+  readonly section: () => ProgressSection | undefined
+  readonly registerSync: (sync: () => void) => void
+}
+
+function toneColor(tone: ProgressTone, palette: ProgressPalette): ProgressPalette["text"] {
+  const colors = {
+    neutral: palette.textMuted,
+    active: palette.accent,
+    success: palette.success,
+    warning: palette.warning,
+    error: palette.error,
+  } as const satisfies Record<ProgressTone, ProgressPalette["text"]>
+  return colors[tone]
+}
+
+export function StatusSection(props: StatusSectionProps): JSX.Element {
+  let sectionNode: BoxRenderable | undefined
+  let titleNode: TextRenderable | undefined
+  const rows: RowNodes[] = Array.from({ length: props.maximumRows }, () => ({}))
+
+  const sync = () => {
+    const section = props.section()
+    if (sectionNode) sectionNode.visible = section !== undefined
+    if (titleNode) titleNode.content = section?.title ?? ""
+
+    for (const [index, nodes] of rows.entries()) {
+      const row = section?.rows[index]
+      if (nodes.box) nodes.box.visible = row !== undefined
+      if (nodes.label) nodes.label.content = row?.label ?? ""
+      if (nodes.value) {
+        nodes.value.content = row?.value ?? ""
+        nodes.value.fg = row ? toneColor(row.tone, props.palette) : props.palette.textMuted
+        nodes.value.requestRender()
+      }
+    }
+    sectionNode?.requestRender()
+  }
+
+  const attachSection = (node: BoxRenderable) => {
+    sectionNode = node
+    sync()
+  }
+  const attachTitle = (node: TextRenderable) => {
+    titleNode = node
+    sync()
+  }
+  const attachRow = (index: number) => (node: BoxRenderable) => {
+    const nodes = rows[index]
+    if (nodes) nodes.box = node
+    sync()
+  }
+  const attachLabel = (index: number) => (node: TextRenderable) => {
+    const nodes = rows[index]
+    if (nodes) nodes.label = node
+    sync()
+  }
+  const attachValue = (index: number) => (node: TextRenderable) => {
+    const nodes = rows[index]
+    if (nodes) nodes.value = node
+    sync()
+  }
+
+  props.registerSync(sync)
+
+  return (
+    <box
+      ref={attachSection}
+      borderStyle="single"
+      borderColor={props.palette.borderSubtle}
+      flexDirection="column"
+      padding={1}
+      visible={false}
+      width="100%"
+    >
+      <text ref={attachTitle} fg={props.palette.text} content="" />
+      {rows.map((_, index) => (
+        <box
+          ref={attachRow(index)}
+          flexDirection="row"
+          justifyContent="space-between"
+          visible={false}
+          width="100%"
+        >
+          <text ref={attachLabel(index)} fg={props.palette.textMuted} content="" />
+          <text ref={attachValue(index)} fg={props.palette.textMuted} content="" />
+        </box>
+      ))}
+    </box>
+  )
+}

package/src/tui.tsx

@@ -0,0 +1,28 @@
+/** @jsxImportSource @opentui/solid */
+/** @jsxRuntime automatic */
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { createTuiProgressController } from "./runtime"
+import { ProgressSidebar } from "./sidebar"
+
+const tui: TuiPlugin = async (api) => {
+  api.slots.register({
+    order: 900,
+    slots: {
+      sidebar_content(context, props) {
+        return (
+          <ProgressSidebar
+            controller={createTuiProgressController(api, props.session_id)}
+            palette={context.theme.current}
+          />
+        )
+      },
+    },
+  })
+}
+
+const plugin = {
+  id: "opencode-agent-progress",
+  tui,
+} satisfies TuiPluginModule
+
+export default plugin