@multiclawcli/dashboard 0.3.1 → 0.4.0

package/README.md

@@ -3,9 +3,73 @@
 [![npm](https://img.shields.io/npm/v/@multiclawcli/dashboard)](https://www.npmjs.com/package/@multiclawcli/dashboard)
 [![GitHub](https://img.shields.io/badge/GitHub-shipengqi%2Fmulticlaw-blue?logo=github)](https://github.com/shipengqi/multiclaw)
 
-Real-time dashboard for [multiclaw](https://github.com/shipengqi/multiclaw) — the multi-agent orchestration CLI.
+Interactive terminal console for [multiclaw](https://github.com/shipengqi/multiclaw) — the multi-agent
+orchestration CLI.
 
-This package provides the web UI and WebSocket server used internally by the `multiclaw` CLI. It is not intended for direct use; install [`multiclaw`](https://www.npmjs.com/package/multiclaw) instead.
+This package provides the Ink-based TUI used internally by the `multiclaw` CLI when it is run with
+no subcommand. It is not intended for direct use; install
+[`multiclaw`](https://www.npmjs.com/package/multiclaw) instead.
+
+## What it exports
+
+| Export | Purpose |
+|--------|---------|
+| `./tui` → `startTui({ config, onTurnStart })` | Render the console and drive the turn loop |
+| `./tui` → `tuiReducer`, `reduceEvent`, `initialState`, `appendLog`, `stripAnsi` | Pure state machine |
+| `./tui` → `TurnView`, `TuiState`, `MAX_HISTORY` | The turn/console split that history is built on |
+| `./tui` → `computeLayout` | Terminal geometry: which regions fit at a given size |
+
+`reduceEvent` is a pure `(state, event) => state` function over core's `MultiClawEvent`, and
+`computeLayout` is pure arithmetic over `(columns, rows, …)`. Both the state layer and the responsive
+rules are therefore testable without a terminal.
+
+## One turn, and the console around it
+
+`TuiState` is split in two, and the split is what makes history possible:
+
+| Type | Holds |
+|------|-------|
+| `TurnView` | Everything that describes *a turn*: agents, stages, focus, scroll, phase, reply |
+| `TuiState extends TurnView` | The above, for the live turn, plus `name`, `history` and `view` |
+
+A finished turn is just a `TurnView` kept in `history`, and every pane takes a `TurnView` — so a past
+turn renders through exactly the same components as the live one. `view` is a *detached* copy of the
+turn being read: `mapShown` routes `tab`, scroll and `/clear` to `view` when one is open, so browsing
+cannot move the focus out from under a run in progress, and cannot rewrite history either.
+
+## Source layout
+
+| Path | Holds |
+|------|-------|
+| `src/tui/state.ts` | The reducer, the roster seed, the log window, the live clocks, the turn history |
+| `src/tui/layout.ts` | Row budget and breakpoints |
+| `src/tui/format.ts` | Duration, truncation and padding helpers |
+| `src/tui/commands.ts` | The `/` command palette model |
+| `src/tui/theme.ts` | Colour, glyph and spinner tokens |
+| `src/tui/components/` | Ink components, grouped by role |
+| `src/tui/App.tsx` | Keymap and wiring |
+
+Coverage is scoped to the four decision-carrying modules (`state`, `layout`, `format`, `commands`).
+The Ink components are render glue, so they are covered by frame assertions in `components.test.tsx`
+and `App.test.tsx` rather than by line counts.
+
+## Notes
+
+- The console requires a TTY. Without one, `startTui` throws and the CLI points at `multiclaw run`.
+- Rendering happens on the alternate screen buffer, which is always restored on exit.
+- Per-agent log buffers are capped (tail window) so a long-running agent cannot exhaust memory.
+- The prompt holds focus at all times, so only `?` and `/` are reserved as bare keys, and only while
+  the line is empty *and* the console is idle. Everything else is a named key or an ordinary
+  character. Mid-run `?` therefore types a literal `?`, because that is what the user is doing.
+- The prompt stays live while a turn runs. Submitting queues the text, and the queue starts as the
+  next turn once the console is idle — `App.tsx` holds it in a small array, `QueueStrip` renders it,
+  and `computeLayout` charges its rows to the body.
+- Every turn runs against the same `workDir`. Only the logs are per-run
+  (`.multiclaw/runs/run-<stamp>/logs/`), which is what lets a follow-up build on the last turn.
+- The hint bar only lists keys that do something *right now*. A turn that ended in a reply takes the
+  body, so there is no roster to switch between and `tab` is left out rather than promised.
+- The package name is historical: it previously shipped a React web dashboard. Renaming it would
+  invalidate the npm trusted-publisher configuration, so the name stays.
 
 ## Documentation
 

package/dist/tui.d.ts

@@ -0,0 +1,299 @@
+import { MultiClawConfig, EventBus, AgentStatus, MultiClawEvent, StageInfo, LeaderMessage, TurnRecord, AgentDefinition } from '@multiclawcli/core';
+
+interface AppProps {
+    config: MultiClawConfig;
+    /**
+     * Called once per turn, after that turn's orchestrator exists. The CLI uses it
+     * to attach a file log writer without the TUI depending on the CLI package.
+     */
+    onTurnStart?: (eventBus: EventBus, logDir: string) => void;
+}
+
+/**
+ * Terminal geometry.
+ *
+ * Kept pure and separate from the components because responsive rules are the
+ * part of a TUI that is easiest to get subtly wrong and hardest to eyeball. Every
+ * row the console spends is budgeted here, so the arithmetic is testable rather
+ * than buried in JSX.
+ */
+declare const MIN_COLUMNS = 40;
+declare const MIN_ROWS = 10;
+/** Below this the roster is dropped so the stream keeps a usable width. */
+declare const COMPACT_COLUMNS = 72;
+/** The rail costs a row; it only earns one when there is vertical room. */
+declare const RAIL_MIN_ROWS = 16;
+/**
+ * The most rows the pipeline rail is ever allowed to occupy.
+ *
+ * The rail wraps, so its height depends on how many agents the turn has and how
+ * wide the terminal is. Without a cap it could eat the whole screen; with one,
+ * the budget stays honest and anything past it is clipped rather than silently
+ * swallowed by the body.
+ */
+declare const MAX_RAIL_ROWS = 2;
+/** Enough to see the palette is a list; more would push the stream off screen. */
+declare const MAX_MENU_ROWS = 7;
+/** Queued follow-ups sit above the prompt; more than a few would crowd the stream. */
+declare const MAX_QUEUE_ROWS = 3;
+interface LayoutInput {
+    columns: number;
+    rows: number;
+    /** Zero means no turn has run yet, which swaps the body for the welcome screen. */
+    turn: number;
+    /** A modal owns the body — help or the history list. */
+    overlay: boolean;
+    /** Rows the command palette is asking for. */
+    menuRows: number;
+    /** Rows the queued follow-ups are asking for. */
+    queueRows?: number;
+    /** Whether a command result is waiting to be shown. */
+    notice: boolean;
+    /** A past turn is open for reading, which costs a banner row. */
+    viewing?: boolean;
+    /** Whether there is a leader or any stage to draw. */
+    hasRail: boolean;
+    /**
+     * Rendered widths of the rail's cells, widest first is not required — order
+     * is what the rail draws. Needed because the rail wraps: its height is a
+     * function of the content, so a flat "one row" charge under-budgets it.
+     */
+    railCells?: number[];
+}
+interface Layout {
+    columns: number;
+    rows: number;
+    compact: boolean;
+    showTeam: boolean;
+    showRail: boolean;
+    /** How many rows the rail will actually occupy once it wraps. */
+    railRows: number;
+    welcome: boolean;
+    bodyHeight: number;
+    logViewport: number;
+    teamWidth: number;
+    menuRows: number;
+    queueRows: number;
+}
+/**
+ * How many rows the rail occupies given the widths of the cells it draws.
+ *
+ * Approximate on purpose: Yoga's own wrapping depends on margins and on how the
+ * terminal renders wide glyphs, and chasing exactness here is not worth it. The
+ * number is capped and the rail is clipped, so an under-count costs the last
+ * chip rather than collapsing the layout.
+ */
+declare function measureRailRows(cells: number[] | undefined, columns: number): number;
+declare function computeLayout(input: LayoutInput): Layout;
+
+/**
+ * Per-agent log buffer cap, in characters.
+ *
+ * The previous web store appended output forever (`logs: a.logs + chunk`). A
+ * chatty agent running for hours would grow that string without bound. The TUI
+ * renders a tail window, so only the tail is worth keeping.
+ */
+declare const MAX_LOG_CHARS = 8000;
+interface AgentView {
+    id: string;
+    name: string;
+    icon?: string;
+    model?: string;
+    /** Static role, from the config. Always available, even before turn one. */
+    description?: string;
+    /** Per-turn title assigned by the leader's task plan; absent until it plans. */
+    taskTitle?: string;
+    status: AgentStatus;
+    /** Wall clock at which the agent started, so its timer can tick while it runs. */
+    startedAt?: number;
+    /** Final duration, present once the agent has finished. */
+    duration?: number;
+    attempts?: number;
+    /** In-flight retry counter, present only while the agent is between attempts. */
+    retry?: {
+        attempt: number;
+        max: number;
+    };
+    error?: string;
+    logs: string;
+}
+type TuiPhase = "idle" | "running" | "complete";
+/**
+ * One turn, as the panes need to see it.
+ *
+ * Everything that describes *a turn* lives here, and everything that describes
+ * *the console* lives on {@link TuiState}. The split is what makes history
+ * possible: a finished turn is just a `TurnView` kept around, and the panes take
+ * a `TurnView` so they can render one without knowing which it is.
+ */
+interface TurnView {
+    turn: number;
+    requirement?: string;
+    phase: TuiPhase;
+    /** Wall clock at which the turn started. */
+    startedAt?: number;
+    /** Wall clock at which the turn finished. */
+    endedAt?: number;
+    stages: StageInfo[];
+    agents: Record<string, AgentView>;
+    /**
+     * Agents that run *before* the pipeline exists (the leader), so the pipeline
+     * bar can label them without guessing. Derived from the config, not from
+     * "every agent that is not in a stage" — a configured agent that has not been
+     * scheduled yet is not a leader.
+     */
+    leaderIds: string[];
+    focusId?: string;
+    /**
+     * While true the focus pane follows whichever agent starts next. Cycling the
+     * focus by hand clears it, so the user's choice is not yanked away.
+     */
+    autoFollow: boolean;
+    /**
+     * How many lines the stream is scrolled back from the tail. Zero means the
+     * stream is live. Kept as an offset rather than an absolute index so new
+     * output arriving underneath does not shift what the user is reading.
+     */
+    scroll: number;
+    success?: boolean;
+    totalDuration?: number;
+    warning?: string;
+    /**
+     * Set when the turn ended in words rather than a pipeline: the leader answered
+     * or asked a question, so no agent ran. Distinct from `success`, because both
+     * a finished pipeline and a one-line answer are successful turns — and the
+     * console has to be able to say which one happened.
+     */
+    reply?: LeaderMessage;
+}
+/** How many finished turns the console keeps around to browse. */
+declare const MAX_HISTORY = 20;
+interface TuiState extends TurnView {
+    name: string;
+    /** Finished turns, oldest first. The live turn is `state` itself. */
+    history: TurnView[];
+    /**
+     * A finished turn opened for reading.
+     *
+     * Kept as a detached copy so scrolling and tabbing through it cannot disturb
+     * the turn that is actually running. While it is set the panes render it, and
+     * `focusId` / `scroll` edits land on it rather than on the live turn.
+     */
+    view?: TurnView;
+}
+declare const initialState: TuiState;
+type TuiAction = {
+    type: "turn:start";
+    requirement: string;
+    agents: Record<string, AgentView>;
+    leaderIds: string[];
+    startedAt: number;
+} | {
+    type: "event";
+    event: MultiClawEvent;
+} | {
+    type: "focus:cycle";
+    delta: number;
+} | {
+    type: "focus:set";
+    agentId: string;
+}
+/** Scroll the focused stream. `viewport` is needed to clamp at the tail. */
+ | {
+    type: "stream:scroll";
+    delta: number;
+    viewport: number;
+}
+/** Drop the focused agent's buffered output without touching its status. */
+ | {
+    type: "stream:clear";
+}
+/** Open a finished turn for reading, by its turn number. */
+ | {
+    type: "view:open";
+    turn: number;
+}
+/** Go back to the live turn. */
+ | {
+    type: "view:close";
+};
+declare function stripAnsi(text: string): string;
+/** Append a chunk, keeping only the last {@link MAX_LOG_CHARS} characters. */
+declare function appendLog(previous: string, chunk: string): string;
+/** Every agent that takes part in a run, in declaration order: leader first. */
+declare function plannedAgents(config: MultiClawConfig): AgentDefinition[];
+declare function leaderAgentIds(config: MultiClawConfig): string[];
+/**
+ * Build the roster shown before (and between) runs.
+ *
+ * The orchestrator only reveals the team through `orchestration:start`, which it
+ * emits *after* the leader has already run — so a console that learned its
+ * agents purely from events would show an empty list until the first turn was
+ * well under way. Seeding from the config makes the idle screen show the team
+ * you are about to run, and gives every turn a known baseline to reset to.
+ */
+declare function seedAgents(config: MultiClawConfig): Record<string, AgentView>;
+declare function createInitialState(config: MultiClawConfig): TuiState;
+declare function reduceEvent(state: TuiState, event: MultiClawEvent): TuiState;
+/**
+ * The turns behind this one, as dialogue the leader can read back.
+ *
+ * Core has no notion of a session — an orchestrator is built per turn — so the
+ * console is what carries earlier turns into the next run. Without them a bare
+ * answer arrives at the leader as a requirement with nothing to answer: turn one
+ * asks "which database?", turn two's requirement is the word "Postgres".
+ *
+ * Derived rather than tracked separately: `history` plus the turn on screen
+ * *are* the finished turns, and a second copy is one more thing that could
+ * disagree with what the panes show.
+ *
+ * Only turns that ended are carried, which makes the call site's timing
+ * irrelevant: whether this is read before or after `turn:start` moves the turn
+ * on screen into `history`, the set is the same.
+ */
+declare function conversationTurns(state: TuiState): TurnRecord[];
+declare function tuiReducer(state: TuiState, action: TuiAction): TuiState;
+/** Roll a stage's member statuses up into one status for the pipeline bar. */
+declare function stageStatus(stage: StageInfo, agents: Record<string, AgentView>): AgentStatus;
+/** How many agents have finished, out of how many the turn will run. */
+declare function progress(turn: TurnView): {
+    done: number;
+    total: number;
+};
+/**
+ * An agent's time: the live clock while it runs, the recorded duration once it
+ * has stopped. Returning the *same* number after completion is what stops the
+ * column from jittering when a stage ends.
+ */
+declare function agentElapsed(agent: AgentView, now: number): number | undefined;
+/** The turn's time, live while running and frozen once the orchestrator reports back. */
+declare function turnElapsed(turn: TurnView, now: number): number | undefined;
+interface LogWindow {
+    lines: string[];
+    /** How many lines sit below the window. Zero means the stream is live. */
+    scrolledBack: number;
+    following: boolean;
+}
+/**
+ * The slice of the focused agent's output that fits the pane.
+ *
+ * Clamping here as well as in the reducer keeps the window correct even when
+ * the pane is resized between two scroll actions.
+ */
+declare function visibleLog(turn: TurnView, viewport: number): LogWindow;
+
+interface TuiOptions {
+    config: MultiClawConfig;
+    /** Attach per-turn reporters (e.g. a file log writer) here. */
+    onTurnStart?: (eventBus: EventBus, logDir: string) => void;
+}
+/**
+ * Render the interactive team console.
+ *
+ * Runs on the alternate screen buffer so the app owns the viewport and the
+ * user's scrollback survives. The buffer is always restored — including when
+ * rendering throws — otherwise the terminal is left unusable.
+ */
+declare function startTui(options: TuiOptions): Promise<void>;
+
+export { type AgentView, type AppProps, COMPACT_COLUMNS, type Layout, type LayoutInput, type LogWindow, MAX_HISTORY, MAX_LOG_CHARS, MAX_MENU_ROWS, MAX_QUEUE_ROWS, MAX_RAIL_ROWS, MIN_COLUMNS, MIN_ROWS, RAIL_MIN_ROWS, type TuiAction, type TuiOptions, type TuiPhase, type TuiState, type TurnView, agentElapsed, appendLog, computeLayout, conversationTurns, createInitialState, initialState, leaderAgentIds, measureRailRows, plannedAgents, progress, reduceEvent, seedAgents, stageStatus, startTui, stripAnsi, tuiReducer, turnElapsed, visibleLog };