@opencode-cockpit/subagents 0.7.0

package/types/core/model/changes.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What a subagent did, in one vocabulary for both OpenCodes.
+ *
+ * OpenCode 1 says it as `message.part.updated` / `message.part.delta` / `session.status`; OpenCode 2
+ * as `session.tool.called` / `session.reasoning.delta` / `session.execution.started`. The two
+ * adapters in `tui/data/` translate each into these changes, and everything after them — the model,
+ * the rows — is written once. Shapes measured from real runs (test/fixtures, docs/opencode/agents.md).
+ *
+ * `id` is always the session the change is about; a subagent *is* a session with a parent.
+ */
+export type ToolState = "pending" | "running" | "completed" | "failed";
+export type Change = 
+/** A session exists, or learned something about itself. Only fields present are applied. */
+{
+    type: "session";
+    id: string;
+    parentID?: string;
+    agent?: string;
+    title?: string;
+    /** The model it runs on, as the host names it: `space-bunny-free`. */
+    model?: string;
+    /** Launched in the background: the main agent carried on without waiting for it. */
+    background?: boolean;
+    /** Permissions its agent's rules deny it outright (OpenCode 1 says; OpenCode 2 does not). */
+    denied?: string[];
+    at: number;
+}
+/** It finished one step — one model turn, with the calls it made. */
+ | {
+    type: "step";
+    id: string;
+    at: number;
+}
+/** Whether it is working. `waiting` is a permission or a question it is held on. */
+ | {
+    type: "status";
+    id: string;
+    status: "busy" | "idle" | "failed" | "waiting";
+    error?: string;
+    at: number;
+}
+/** Something said *to* it: the first is the task it was given, the rest are messages. */
+ | {
+    type: "prompt";
+    id: string;
+    key: string;
+    text: string;
+    at: number;
+}
+/** Its thinking, whole (`text`) or as it streams (`delta`). `key` names one block of it. */
+ | {
+    type: "thinking";
+    id: string;
+    key: string;
+    text?: string;
+    delta?: string;
+    done?: boolean;
+    at: number;
+}
+/** What it is writing back, the same way. */
+ | {
+    type: "reply";
+    id: string;
+    key: string;
+    text?: string;
+    delta?: string;
+    done?: boolean;
+    at: number;
+}
+/** A tool call, as it moves from pending to done. `call` names it; later changes fill it in. */
+ | {
+    type: "tool";
+    id: string;
+    call: string;
+    name?: string;
+    state?: ToolState;
+    input?: Record<string, unknown>;
+    /** What it returned — or, while running, what it has printed so far. */
+    output?: string;
+    error?: string;
+    /** When the call itself started and ended, when the host says; otherwise when we heard. */
+    started?: number;
+    ended?: number;
+    /** Its result in a few words, when the host gives the number: `9 matches`, `exit 1`. */
+    summary?: string;
+    at: number;
+}
+/** Running totals for the session, as the host keeps them. */
+ | {
+    type: "usage";
+    id: string;
+    tokens?: number;
+    cost?: number;
+    at: number;
+};
+/** OpenCode 2 starts every subagent's task with this line; the task is what follows it. */
+export declare const SUBAGENT_PREAMBLE = "You are a subagent spawned by another session.";
+export declare function taskText(text: string): string;

package/types/core/model/model.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Subagents, built from changes. Pure: no OpenCode, no terminal — a test feeds it the changes a real
+ * run produced and checks what came out.
+ *
+ * Every session is kept, the conversation you are in included: a subagent is only "a subagent" in
+ * relation to the session it hangs under, and `subagentsOf` walks that from whichever conversation is
+ * on screen.
+ */
+import type { Change, ToolState } from "./changes.ts";
+export type Status = "starting" | "running" | "waiting" | "done" | "failed";
+export type Entry = {
+    kind: "prompt";
+    key: string;
+    text: string;
+    at: number;
+    first: boolean;
+} | {
+    kind: "thinking";
+    key: string;
+    text: string;
+    done: boolean;
+    at: number;
+} | {
+    kind: "reply";
+    key: string;
+    text: string;
+    done: boolean;
+    at: number;
+} | {
+    kind: "tool";
+    call: string;
+    name: string;
+    state: ToolState;
+    input: Record<string, unknown>;
+    output: string;
+    error?: string;
+    summary?: string;
+    at: number;
+    ended?: number;
+};
+export interface Session {
+    id: string;
+    parentID?: string;
+    agent: string;
+    title: string;
+    /** The task it was given — its first prompt. */
+    task?: string;
+    status: Status;
+    /** When the current status began: how long it has been waiting, say. */
+    since: number;
+    error?: string;
+    started: number;
+    /** When it last went idle or failed; cleared when it works again. */
+    ended?: number;
+    entries: Entry[];
+    tokens: number;
+    cost: number;
+    model?: string;
+    background?: boolean;
+    denied: string[];
+    steps: number;
+    /** When anything was last heard about it: a run gone quiet this long is asked about. */
+    seen: number;
+}
+export interface Model {
+    sessions: Map<string, Session>;
+}
+export declare const emptyModel: () => Model;
+/** Applies one change in place. Unknown sessions are created, so order never loses anything. */
+export declare function apply(model: Model, change: Change): void;
+export declare function applyAll(model: Model, changes: Iterable<Change>): Model;
+export interface Node {
+    session: Session;
+    /** 0 for a subagent of the conversation on screen, 1 for one it launched, … */
+    depth: number;
+}
+/** The subagents under `root`, depth first, oldest first at each level. */
+export declare function subagentsOf(model: Model, root: string): Node[];
+/** The conversation a session belongs to: up its parents to the one with none. */
+export declare function rootOf(model: Model, id: string): string;
+/** What a tool call is *about*, in a few words: the file, the pattern, the command. */
+export declare function toolTarget(name: string, input: Record<string, unknown>): string;
+export interface Activity {
+    kind: "starting" | "tool" | "thinking" | "writing" | "waiting" | "done" | "failed";
+    /** The tool's name, for `tool`. */
+    tool?: string;
+    text: string;
+    /** When the current thing started, for its elapsed time. */
+    since: number;
+}
+/** What a subagent is doing right now — the line under its name in the sidebar. */
+export declare function activityOf(s: Session): Activity;
+/** Counts for the block's heading. */
+export declare function countsOf(nodes: readonly Node[]): {
+    total: number;
+    running: number;
+    done: number;
+    failed: number;
+};

package/types/core/sample.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A run caught mid-flight, for the preview: build has launched three subagents — one searching, one
+ * held on a permission, one finished. Fixed times, so the preview draws the same thing every time.
+ */
+import type { Change } from "./model/changes.ts";
+export declare const SAMPLE_ROOT = "ses_build";
+export declare const SAMPLE_NOW = 1790000060000;
+export declare function sample(): Change[];

package/types/core/view/markdown.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A subagent's answer as rows: the markdown it writes, drawn rather than shown as source.
+ *
+ * Only what agents actually write: headings, **bold**, `code`, lists, quotes and fenced code. Inline
+ * styles survive wrapping — a line is cut into styled words first, then the words are laid out —
+ * so a path in `code` that crosses the edge keeps its colour on both lines.
+ */
+import { type Row, type Run } from "./rows.ts";
+type Style = Omit<Run, "text">;
+/** `**bold**` and `` `code` `` in one line, as styled pieces. */
+export declare function inline(text: string, base: Style): Run[];
+/**
+ * Styled pieces onto lines of `width`, word by word. `first` leads the first line and `rest` every
+ * line after it — a bullet, then the indent that lines up under the words.
+ */
+export declare function flow(pieces: readonly Run[], width: number, first: Run[], rest: Run[]): Row[];
+export interface MarkdownOptions {
+    /** Columns of margin on the left of every row. */
+    indent: number;
+}
+export declare function markdownRows(text: string, width: number, { indent }: MarkdownOptions): Row[];
+export {};

package/types/core/view/report.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The main agent's view of its subagents: what `subagents_list` answers.
+ *
+ * Written for a model, not a person — plain lines, every id in full, and the one thing it needs to do
+ * with them said once: continue a subagent by its id rather than start a new one, so the follow-up
+ * keeps everything that subagent already read and tried. Pure, like everything in `core/`.
+ */
+import type { Node } from "../model/model.ts";
+export interface ReportInput {
+    nodes: readonly Node[];
+    now: number;
+    /** Which OpenCode: the id goes in `task_id` on 1 and `sessionID` on 2. */
+    version: 1 | 2;
+}
+export declare function subagentReport({ nodes, now, version }: ReportInput): string;

package/types/core/view/rows.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Rows of styled runs — the one drawing of every Subagents surface, pure so a test can measure it.
+ *
+ * Tones name a meaning, never a colour; `tui/render.ts` is the only place that knows what a tone
+ * looks like, so the preview CLI and OpenCode draw the same rows (docs/building/terminal-ui.md).
+ */
+export type Tone = "text" | "muted" | "accent" | "info" | "tool" | "success" | "error" | "warning" | "border";
+/**
+ * What sits behind a run: the header band, a block (code, the input), a card (the task, your
+ * messages), or the item under the cursor.
+ */
+export type Fill = "none" | "band" | "block" | "card" | "selected";
+export interface Run {
+    text: string;
+    tone?: Tone;
+    fill?: Fill;
+    bold?: boolean;
+    /** The terminal's DIM: thinking, and what is not the point. */
+    faint?: boolean;
+}
+export type Row = Run[];
+export declare const rowText: (row: Row) => string;
+/** Columns a string takes. Wide characters (CJK, most emoji) take two. */
+export declare function widthOf(text: string, limit?: number): number;
+/** `text` in at most `width` columns, ending in `…` when cut. */
+export declare function cut(text: string, width: number): string;
+/**
+ * A row exactly `width` columns wide: runs cut where they overflow, and padded — in the last run's
+ * fill — where they fall short, so a band reaches both edges. Every row every surface draws goes
+ * through here; the grid test holds it to it.
+ */
+export declare function fit(row: Row, width: number): Row;
+/** Left and right parts on one row, the right part flush against the edge; the left gives way. */
+export declare function spread(left: Row, right: Row, width: number): Row;
+/** Words onto lines of at most `width` columns; newlines in the text are kept; a long word breaks. */
+export declare function wrap(text: string, width: number): string[];
+/** A duration in the fewest characters that still reads: `4s`, `51s`, `2m04s`, `1h12m`. */
+export declare function elapsed(ms: number): string;
+/** `1.2k`, `24k`, `1.1M` — tokens in a narrow column. */
+export declare function compact(n: number): string;
+/** A spinner frame, from a clock that ticks on every paint. */
+export declare const SPINNER: string[];
+export declare const spin: (frame: number) => string;

package/types/core/view/screen.d.ts

@@ -0,0 +1,101 @@
+/**
+ * One subagent, in the pane: its run as a timeline you can move through and open.
+ *
+ *   ▌⠙ EXPLORE  Scan architecture opportunities                          running 3m32s
+ *     space-bunny-free · background · launched by build · 108 calls · 14 steps · 2.2M tok
+ *     ‹ 2/3 ›  general Review diff   explore Scan arch…   general Verify
+ *
+ *     ▎ Task from build
+ *     ▎ Inspect the codebase architecture and docs; identify one or two…
+ *
+ *     ◇ Thinking  Need inspect sizes to identify. Glob source…
+ *     › read   docs/building/a-new-bay.md
+ *     ⌄ grep   "loadConfig" *.ts                                   9 matches · 1.4s
+ *       │ pattern  loadConfig
+ *       │ include  *.ts
+ *       │ ─
+ *       │ packages/shell/src/core/config.ts:80: export function loadConfig(
+ *
+ *     ## Findings …                                   (the answer, as markdown)
+ *
+ * Every item — a call, a block of thinking, a message you sent — is selectable (`j`/`k`) and opens
+ * or folds (`enter`, a click). Every row is exactly `width`; there are exactly `height` rows; only
+ * the body scrolls. Pure, like everything in `core/`.
+ */
+import { type Entry, type Node, type Session } from "../model/model.ts";
+import { type Row } from "./rows.ts";
+export interface ScreenInput {
+    session: Session;
+    /** Every subagent of the conversation, for "2/3" and the switcher. */
+    nodes: readonly Node[];
+    /** The agent that launched it: "Task from build". */
+    launcher?: string;
+    width: number;
+    height: number;
+    now: number;
+    frame: number;
+    /** First body row shown; undefined follows the run as it grows. */
+    top?: number;
+    /** The item under the cursor. */
+    selected?: string;
+    /** Whether a message to the subagent was yours — the rest came from the main agent continuing it. */
+    yours?: (entry: Extract<Entry, {
+        kind: "prompt";
+    }>) => boolean;
+    /** Calls whose output is shown whole rather than its first lines (`a`). */
+    whole?: ReadonlySet<string>;
+    /** The cursor just moved: bring the selected item into view. Scrolling does not. */
+    reveal?: boolean;
+    /** Items opened by hand; running calls are open unless folded by hand (`closed`). */
+    open: ReadonlySet<string>;
+    closed: ReadonlySet<string>;
+    /** Every thinking block open, not just the ones opened by hand. */
+    thinking: boolean;
+    /** The details view in place of the timeline. */
+    details: boolean;
+    /** A message being typed at the bottom of the pane. */
+    input?: {
+        draft: string;
+        busy: boolean;
+    };
+    /** A line under the keys: what just happened. */
+    notice?: string;
+    /** What each item drew last time, kept by the caller between paints (`createScreenCache`). */
+    cache?: ScreenCache;
+}
+/**
+ * Each item's rows from the paint before, and what they were drawn from. A paint redraws only the
+ * items that changed — a scroll, a spinner tick or a new call no longer lays out every call, every
+ * block of thinking and the whole answer again (32 ms a paint on a 200-call run, measured).
+ */
+export interface ScreenCache {
+    items: Map<string, {
+        sig: string;
+        lines: Line[];
+    }>;
+}
+export declare const createScreenCache: () => ScreenCache;
+export interface Screen {
+    rows: Row[];
+    /** The item each row belongs to, for a click. */
+    items: (string | undefined)[];
+    /** Selectable items, in order, for `j`/`k`. */
+    keys: string[];
+    /** Items drawn open, so a toggle knows which way to go. */
+    opened: string[];
+    /** The first body row shown, resolved. */
+    top: number;
+    /** The furthest the body can scroll. */
+    most: number;
+    /** Where the body starts on screen, for mapping a click. */
+    bodyAt: number;
+}
+/** A body row, and the item it belongs to. */
+export interface Line {
+    row: Row;
+    item?: string;
+}
+export declare const itemKey: (entry: Entry) => string;
+export declare function screenRows(input: ScreenInput): Screen;
+/** For tests and the preview: the columns a row takes. */
+export declare const rowWidth: (row: Row) => number;

package/types/core/view/sidebar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The sidebar block: a heading with counts, then two lines per subagent — who it is, and what it is
+ * doing now. Every line of a subagent carries its id, so a click on either opens it.
+ *
+ * The sidebar is a narrow column shared with Context, Shells and the statusline; rows are exactly
+ * its width, and a subagent's lines stay two however long its task or target is.
+ *
+ *   Subagents                   2 running
+ *   ⠙ explore Map the auth flow
+ *     └ grep "session"  9 calls · 51s
+ *   ● general Update README
+ *     └ done            3 calls · 28s
+ */
+import { type Node } from "../model/model.ts";
+import { type Row } from "./rows.ts";
+export interface SidebarLine {
+    row: Row;
+    /** The subagent a click on this line opens. */
+    id?: string;
+}
+export interface SidebarInput {
+    nodes: readonly Node[];
+    width: number;
+    now: number;
+    /** The spinner's clock. */
+    frame: number;
+    /** Subagents shown before the rest fold into a count; the sidebar is shared. */
+    limit?: number;
+}
+export declare function sidebarLines(input: SidebarInput): SidebarLine[];

package/types/server.d.ts

@@ -0,0 +1,2 @@
+/** Published entry point: `@opencode-cockpit/subagents/server`. */
+export { createSubagentsServer, default, GUIDANCE, SUBAGENTS_PACKAGE, type SubagentsServerOptions, } from "./agent/plugin.ts";

package/types/tui/index.d.ts

@@ -0,0 +1,26 @@
+/** @jsxImportSource @opentui/solid */
+import { type Host } from "@opencode-cockpit/client/host";
+export interface SubagentsTuiOptions {
+    /** Subagents shown in the sidebar before the rest fold into a count. */
+    sidebarRows?: number;
+    /**
+     * Minutes a finished subagent stays in the sidebar; unset keeps it for the conversation. It is only
+     * out of the sidebar — `/subagents` and the pane's `[` `]` still reach it, and it comes back if it
+     * works again.
+     */
+    hideFinishedAfter?: number;
+    /** Where the block sits among sidebar blocks; lower draws first (Shell 150, statusline 200). */
+    sidebarOrder?: number;
+    keybinds?: Record<string, string>;
+}
+/** Subagents' TUI half as a factory, so the `opencode-cockpit` bundle can include it. */
+export declare function createSubagentsTui({ source }?: {
+    source?: string;
+}): (api: Host, rawOptions?: unknown) => Promise<void>;
+/** One entry for both OpenCodes: v1 calls `tui`, v2 calls `setup` (docs/opencode/v2.md). */
+declare const _default: {
+    id: string;
+    tui: (api: import("@opencode-ai/plugin/tui").TuiPluginApi, options?: unknown) => Promise<void>;
+    setup: (ctx: import("@opencode-cockpit/client/host").V2Context) => Promise<() => void>;
+};
+export default _default;

package/types/tui/render.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The only place that knows what a tone looks like: every colour from the user's OpenCode theme,
+ * through the host (so OpenCode 2's tokens arrive under the same names — client/host `themeFromV2`).
+ *
+ * Nothing of OpenTUI is imported at runtime: it is the host's, not installed beside a published
+ * plugin (docs/opencode/v2.md). `StyledText` and the colour class are borrowed from objects the host
+ * made, as Shell's and Review's pools do.
+ */
+import type { Theme } from "@opencode-cockpit/client/host";
+import type { RGBA, TextRenderable } from "@opentui/core";
+import type { Fill, Row, Run, Tone } from "../core/view/rows.ts";
+export declare function toneColour(theme: Theme, tone: Tone | undefined): RGBA;
+export declare function fillColour(theme: Theme, fill: Fill | undefined): RGBA | undefined;
+/** Bold is bold; faint is the muted colour in italics — the terminal's DIM draws too dark to read. */
+export declare const attributesOf: (run: Run) => number;
+/**
+ * A surface colour certain to paint. A theme may leave its backgrounds transparent (OpenCode's
+ * "system" theme), and a full-window surface painted with one lets the conversation show through —
+ * the 0.6 fix, carried over from Shell and Review.
+ */
+export declare function solidSurface(theme: Theme): RGBA;
+export interface RowPool {
+    draw: (rows: readonly Row[], theme: Theme) => void;
+    clear: () => void;
+}
+/** Rows onto a pool of lines — Shell's pool: only lines that changed are touched. */
+export declare function createRowPool(lines: readonly TextRenderable[]): RowPool;

package/types/tui/source.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where subagents come from: the host's live events, and the stored runs of subagents that existed
+ * before this plugin did. The only file that reaches past `Host` into a specific OpenCode — through
+ * `api.v1` / `api.v2`, as Status's snapshot does — and every shape it reads was measured on 1.18.32
+ * and 2.0.15 (docs/opencode/agents.md). Everything it learns becomes `Change`s for the model.
+ */
+import type { Host } from "@opencode-cockpit/client/host";
+import type { Log } from "@opencode-cockpit/client/log";
+import type { Change } from "../core/model/changes.ts";
+export interface Source {
+    /** Loads what exists under a conversation: its subagents, theirs, and their runs so far. */
+    load: (root: string) => Promise<void>;
+    /**
+     * Says something to a subagent; a busy one picks it up mid-run. `agent` is the subagent's own: sent
+     * without one, OpenCode 1 answered as its default `build` agent — other tools, other permissions.
+     */
+    send: (id: string, text: string, busy: boolean, agent: string) => Promise<void>;
+    /**
+     * Stops a subagent's run. Measured: on OpenCode 1 its task fails as "aborted" and the main agent
+     * carries on; on OpenCode 2 it is interrupted, and the main agent may start it again.
+     */
+    stop: (id: string) => Promise<void>;
+    /**
+     * Moves the subagents a conversation is blocked on into the background, so it carries on — what
+     * OpenCode's own `ctrl+b` does. Measured: OpenCode 2 always; OpenCode 1 only when started with
+     * OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true, and it says `false` otherwise. Resolves to
+     * whether it happened.
+     */
+    background: (parentID: string) => Promise<boolean>;
+    /**
+     * Tells a conversation something, as its user. Used before a stop: told nothing, the main agent
+     * read the stopped subagent as failed and launched it again.
+     */
+    note: (sessionID: string, text: string, busy: boolean, agent?: string) => Promise<void>;
+    /**
+     * Adds something to a conversation without starting a turn: the main agent reads it next time it
+     * is asked. Measured: OpenCode 1 `noReply` (drawn as your message), OpenCode 2 a synthetic message
+     * with `resume: false` (drawn as one line) — neither answered, both recalled it on the next turn.
+     */
+    quiet: (sessionID: string, text: string, agent?: string) => Promise<void>;
+    /** What the host says about a session now, for a run that went quiet; nothing when it does not know. */
+    check: (id: string) => Change[];
+    dispose: () => void;
+}
+export declare function createSource(api: Host, log: Log, emit: (changes: Change[]) => void): Source;

package/types/tui/view/overlay.d.ts

@@ -0,0 +1,30 @@
+/** @jsxImportSource @opentui/solid */
+import type { Host } from "@opencode-cockpit/client/host";
+import type { BoxRenderable, TextRenderable } from "@opentui/core";
+import type { JSX } from "solid-js";
+/** Enough lines for any terminal: a slot's tree is read once, so the pool cannot grow later. */
+export declare const MAX_LINES = 300;
+export interface OverlayProps {
+    api: Host;
+    onReady: (parts: {
+        backdrop: BoxRenderable;
+        panel: BoxRenderable;
+        lines: TextRenderable[];
+    }) => void;
+    /** A click landed outside the pane. */
+    onDismiss: () => void;
+    /** A click landed on the pane, at this row of it. */
+    onClick: (y: number) => void;
+    /** The wheel turned over the pane: negative is up. */
+    onScroll: (delta: number) => void;
+}
+/**
+ * The pane's surface — Review's shape: a full-window, transparent backdrop that catches clicks off
+ * the pane, and the pane inside it, right-aligned, half the window or all of it.
+ *
+ * **Nothing here is reactive.** The host reads a slot's children once (docs/opencode/gotchas.md), so
+ * the component hands its boxes up and the plugin assigns to them. Anchored bottom-right, because an
+ * absolute box is placed against the `app_bottom` container at the foot of the window. Only props a
+ * box actually uses: an unused one (`titleColor`) blanked Review's pane on OpenCode 2.
+ */
+export declare function Overlay(props: OverlayProps): JSX.Element;

package/types/tui/view/sidebar.d.ts

@@ -0,0 +1,22 @@
+/** @jsxImportSource @opentui/solid */
+import type { Host } from "@opencode-cockpit/client/host";
+import type { BoxRenderable } from "@opentui/core";
+import { type JSX } from "solid-js";
+import type { SidebarLine } from "../../core/view/sidebar.ts";
+export interface SidebarProps {
+    api: Host;
+    /** The block's lines, from `core/view/sidebar.ts`; a signal, so `<For>` redraws them. */
+    lines: () => readonly SidebarLine[];
+    onOpen: (id: string) => void;
+    /** The block's own box, so its rows can be drawn at the width the sidebar really gives it. */
+    onReady?: (box: BoxRenderable) => void;
+}
+/**
+ * The Subagents block: the rows `core/view/sidebar.ts` produced, one `<text>` per row.
+ *
+ * Shell's and Status's sidebar pattern, proven live on both OpenCodes: a signal read by `<For>`
+ * redraws, where anything decided once in a slot's tree never would (docs/opencode/gotchas.md).
+ * Every line of a subagent opens it; mouse-up, not mouse-down, because the host acts on the release
+ * that follows (as Shell's sidebar found).
+ */
+export declare function SidebarBlock(props: SidebarProps): JSX.Element;