@multiclawcli/dashboard 0.4.0 → 0.5.1

package/dist/tui/App.d.ts

@@ -0,0 +1,10 @@
+import type { EventBus, MultiClawConfig } from "@multiclawcli/core";
+export 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;
+}
+export declare function App({ config, onTurnStart }: AppProps): import("react").JSX.Element;

package/dist/tui/commands.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The `/` command palette.
+ *
+ * Slash commands are how every agent CLI in this space exposes operations that
+ * are not worth a keybinding. They also solve the console's hardest input
+ * problem: a bare key cannot be both "type this" and "do that", but a *prefix*
+ * can, because the user has already committed to a mode by typing it.
+ */
+/** When a command may be run. */
+export type Availability = "always" | "running" | "idle";
+export interface CommandSpec {
+    /** Without the leading slash. */
+    name: string;
+    /** Argument hint shown next to the name, e.g. `<agent>`. */
+    args?: string;
+    description: string;
+    availability: Availability;
+    /**
+     * What this command's first argument completes against, if anything.
+     *
+     * Declared as data rather than matched on the name in `App`, so "this command
+     * takes a completer" is one fact in one place: a second such command needs no
+     * edit to the console's key handling.
+     */
+    completes?: "agent";
+}
+export declare const COMMANDS: readonly CommandSpec[];
+export interface ParsedCommand {
+    name: string;
+    args: string[];
+}
+/** Commands that make sense in the current phase. */
+export declare function availableCommands(running: boolean): CommandSpec[];
+/**
+ * Whether a command may run in the current phase.
+ *
+ * `availableCommands` decides what the palette *offers*; this is the same rule
+ * applied to *running*, because typing a command out bypasses the palette
+ * entirely. An unknown name is not "unavailable" — it is let through so the
+ * caller's `default:` branch can report it.
+ */
+export declare function canRun(name: string, running: boolean): boolean;
+/**
+ * Why a command may not run in the current phase, or `undefined` when it may.
+ *
+ * The mirror of {@link canRun}, and the message names the phase the command
+ * *wants* rather than just saying it is unavailable: the two directions mean
+ * different things to the user. A mid-run `/replay` has to read as "wait for the
+ * turn to finish", while an idle `/cancel` has to read as "this only applies to
+ * a running turn" — one string for both would leave the user without the fact
+ * they need to act on. An unknown name has no reason; it is let through so the
+ * caller's `default:` branch can report it.
+ */
+export declare function unavailableReason(name: string, running: boolean): string | undefined;
+/**
+ * Commands matching what has been typed after the slash.
+ *
+ * Name prefixes outrank description hits: someone typing `/ag` wants `/agents`,
+ * not whichever command happens to mention "agent" in its blurb.
+ */
+export declare function matchCommands(query: string, running: boolean): CommandSpec[];
+/** True once the line has committed to command mode. */
+export declare function isCommandLine(text: string): boolean;
+/**
+ * The partial name the palette should filter on, or `undefined` when the
+ * palette should stay closed.
+ *
+ * It closes as soon as a space is typed: at that point the user is writing
+ * arguments, and a list that keeps re-filtering under their cursor is noise.
+ */
+export declare function menuQuery(text: string): string | undefined;
+/** Split a submitted line into a command name and its arguments. */
+export declare function parseCommand(text: string): ParsedCommand | undefined;
+/**
+ * One row of the palette, whether it lists commands or their arguments.
+ *
+ * The label carries the leading slash (commands) or is a bare id (arguments),
+ * so the renderer draws one shape for both panels and never needs to know which
+ * it is showing.
+ */
+export interface PaletteRow {
+    key: string;
+    label: string;
+    description: string;
+}
+/** The palette rows for a command list, in the order given. */
+export declare function paletteRows(commands: readonly CommandSpec[]): PaletteRow[];
+/**
+ * The command whose first argument is being typed, and what has been typed so
+ * far — or `undefined` when no argument completer applies.
+ *
+ * The mirror image of {@link menuQuery}: that one closes the moment a space is
+ * typed, this one opens there. They are mutually exclusive, so the two palettes
+ * can never be open at once.
+ *
+ * Only the first argument is recognised, which is all any current command needs
+ * — a command with two completable arguments would extend this, not the caller.
+ */
+export declare function argQuery(text: string): {
+    command: CommandSpec;
+    partial: string;
+} | undefined;
+/**
+ * Agent ids matching a partial id, case-insensitively, capped at `limit`.
+ *
+ * An empty partial lists the whole roster (up to the cap), so `/focus ` alone is
+ * a way to see who is available rather than an empty panel.
+ */
+export declare function completeAgents(partial: string, ids: readonly string[], limit?: number): string[];
+/**
+ * Turn a typed agent id into the id it names, or the reason it does not.
+ *
+ * An exact id always wins; otherwise a unique prefix resolves, and an ambiguous
+ * prefix reports every candidate so the user can see what to disambiguate
+ * between. `/focus` and `/retry` share this so the two commands accept ids the
+ * same way.
+ */
+export declare function resolveAgentId(input: string, ids: readonly string[]): {
+    id: string;
+} | {
+    error: string;
+};

package/dist/tui/components/chrome.d.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import type { TurnView } from "../state";
+/**
+ * Identity on the left, live context on the right — the same split htop uses.
+ *
+ * Chrome never shrinks. When the column overflows, Yoga squeezes whichever child
+ * it can, and a header that silently disappears is worse than a clipped log.
+ */
+export declare function Header({ name, right }: {
+    name: string;
+    right: string;
+}): import("react").JSX.Element;
+/** A horizontal rule. Cheap separation without spending two rows on a box border. */
+export declare function Rule({ width }: {
+    width: number;
+}): import("react").JSX.Element;
+/**
+ * The rendered width of each cell the rail draws, in rail order.
+ *
+ * The rail wraps, so its height is a function of its content — which means the
+ * row budget has to be able to see this before anything is rendered. Keeping the
+ * measurement next to the component is what stops the two drifting apart: if the
+ * rail changes shape, this is the one other place that needs the same change.
+ */
+export declare function railCellWidths(turn: TurnView): number[];
+/**
+ * The team's shape at a glance: who runs before the pipeline, then each stage in
+ * order.
+ *
+ * The `──▸` connector and the ①②③ markers are borrowed from build tools and CI
+ * UIs, where "this happens, then that" is already read as a left-to-right flow.
+ */
+export declare function PipelineRail({ turn, spinner }: {
+    turn: TurnView;
+    spinner: string;
+}): import("react").JSX.Element | null;
+/**
+ * The footer.
+ *
+ * The right side lists only the keys that do something *right now*, which is how
+ * a console teaches its own keymap without printing a manual.
+ */
+export declare function HintBar({ status, keys }: {
+    status: ReactNode;
+    keys: string;
+}): import("react").JSX.Element;
+/**
+ * Follow-ups typed while the team was still working.
+ *
+ * It sits directly above the prompt because that is where the text was typed, and
+ * the rows are in run order — the first one is what happens next. The overflow
+ * count is spelled out rather than implied, since the whole point of the strip is
+ * that nothing the user typed gets silently dropped.
+ */
+export declare function QueueStrip({ items, max }: {
+    items: string[];
+    max?: number;
+}): import("react").JSX.Element | null;

package/dist/tui/components/overlays.d.ts

@@ -0,0 +1,64 @@
+import { type TurnView } from "../state";
+interface HelpGroup {
+    title: string;
+    rows: Array<[keys: string, description: string]>;
+}
+/**
+ * Grouped the way the user meets them: what the prompt does, then the panes,
+ * then the command layer.
+ *
+ * The command layer lists only keys that are *not* slash commands — `/`, `?`,
+ * `ctrl+c` — plus a single derived line counting the commands. It deliberately
+ * does not enumerate them: the list would drift from `COMMANDS` the moment a
+ * command is added, and it would not fit (see `helpRows`). The `/` palette is
+ * built from `COMMANDS` itself, so it can never drift, and that is where the
+ * enumeration belongs.
+ */
+export declare const HELP_GROUPS: readonly HelpGroup[];
+/** How many turns fit in a body of `maxRows`. Never fewer than one. */
+export declare function historyCapacity(maxRows: number): number;
+/**
+ * The first item to draw, given the one the cursor is on.
+ *
+ * A generic list window — nothing here is specific to history — so the command
+ * palette uses it too. The list can be longer than the body, so without this the
+ * cursor walks off the bottom and `enter` opens a row the user cannot see —
+ * which is exactly when the list is worth opening.
+ */
+export declare function listWindowStart(selected: number, total: number, capacity: number): number;
+/** Rows the help screen occupies, with or without the gaps between groups. */
+export declare function helpRows(compact?: boolean): number;
+/**
+ * The `?` overlay. Replaces the body rather than floating, which keeps it legible.
+ *
+ * `flexShrink={0}` so a body smaller than the content clips it rather than
+ * folding the rows into each other — the body does the clipping, and overlap is
+ * strictly worse than a missing row.
+ *
+ * When even the compact form does not fit, what gets clipped is the bottom, so
+ * the spacing between groups is the first thing to go: on a 24-row terminal the
+ * difference is whether "esc or ? to close" survives.
+ */
+export declare function HelpOverlay({ width, maxRows }: {
+    width: number;
+    maxRows: number;
+}): import("react").JSX.Element;
+/**
+ * The finished turns, newest first.
+ *
+ * Two rows per turn on purpose: the requirement is the thing a reader is
+ * scanning for, and folding it onto the same line as the outcome would truncate
+ * exactly the part that identifies the turn.
+ *
+ * Only turns a newer turn has superseded are listed — the one being run is
+ * already on screen, so listing it would offer to show the user what they are
+ * looking at.
+ */
+export declare function HistoryOverlay({ turns, selected, width, maxRows, }: {
+    turns: TurnView[];
+    selected: number;
+    width: number;
+    /** Rows available in the body. The list is windowed against this. */
+    maxRows: number;
+}): import("react").JSX.Element;
+export {};

package/dist/tui/components/panels.d.ts

@@ -0,0 +1,72 @@
+import type { LeaderMessage } from "@multiclawcli/core";
+import { type TurnView } from "../state";
+/** The roster: one row per agent, with the focused one called out by a caret. */
+export declare function TeamPanel({ turn, width, now, spinner, }: {
+    turn: TurnView;
+    width: number;
+    now: number;
+    spinner: string;
+}): import("react").JSX.Element;
+/**
+ * A one-column vertical rule between the two panes.
+ *
+ * Drawn as a left border rather than a column of `│` characters: the border is
+ * laid out by Yoga and always matches the row's height, whereas a hand-counted
+ * column of glyphs overflows into the footer the moment the two disagree.
+ */
+export declare function Divider(): import("react").JSX.Element;
+/**
+ * The focused agent's output.
+ *
+ * The header carries the three things a reader needs before the text: whose
+ * output this is, what it is running on, and whether the pane is still tailing
+ * or parked. Output itself is rendered at normal brightness — the chrome is what
+ * should recede, not the agent's work.
+ */
+export declare function StreamPanel({ turn, height, width, now, spinner, }: {
+    turn: TurnView;
+    height: number;
+    width: number;
+    now: number;
+    spinner: string;
+}): import("react").JSX.Element;
+/**
+ * A turn the leader answered instead of planning.
+ *
+ * It takes the body for the same reason the welcome screen does: there is no
+ * pipeline to watch, and the words are the entire result. Splitting the space
+ * with two panes that have nothing to say would only shrink the one thing worth
+ * reading. The rail above still names the leader, so the source is not lost.
+ */
+export declare function ReplyPanel({ reply, width }: {
+    reply: LeaderMessage;
+    width: number;
+}): import("react").JSX.Element;
+/**
+ * A turn that stopped with an error, shown in full.
+ *
+ * The status line has one row and truncates, which is the wrong shape for the
+ * errors that matter here: a jiti load failure or an ACP protocol error is
+ * several lines, and squeezing it to one leaves the user nothing to act on. So
+ * the error takes the body, the same way a reply does, and lets Ink wrap it.
+ */
+export declare function ErrorPanel({ message, width }: {
+    message: string;
+    width: number;
+}): import("react").JSX.Element;
+/**
+ * The first screen.
+ *
+ * A console that opens to a blank pane wastes the one moment where the user has
+ * nothing else to read. The roster is already in the config — including the
+ * `description` of what each agent is for — so the welcome screen can say who is
+ * on the team and what each of them does.
+ *
+ * It marks the focused agent with the same `›` caret the team panel uses. Without
+ * it, `tab` looked broken here: the hint bar advertised `tab switch` while the
+ * one roster on screen ignored the focus entirely.
+ */
+export declare function WelcomePanel({ turn, width }: {
+    turn: TurnView;
+    width: number;
+}): import("react").JSX.Element;

package/dist/tui/components/prompt.d.ts

@@ -0,0 +1,36 @@
+import type { PaletteRow } from "../commands";
+/**
+ * The prompt line.
+ *
+ * The terminal's own cursor is hidden while the console owns the screen, so the
+ * caret has to be drawn. It sits *between* the text before and after it rather
+ * than always at the end — that is what makes arrow-key editing legible.
+ *
+ * The caret cell is always exactly one column wide, in both blink phases. That
+ * matters on an empty line: the ghost text starts where the caret is, so a
+ * caret that *added* a cell while visible would shove the placeholder one
+ * column sideways twice a second. Instead the caret is painted *onto* the ghost
+ * text's first character, which is what a real block cursor does.
+ */
+export declare function Prompt({ value, cursor, caretVisible, placeholder, }: {
+    value: string;
+    cursor: number;
+    caretVisible: boolean;
+    placeholder: string;
+}): import("react").JSX.Element;
+/**
+ * The palette, rendered directly above the prompt.
+ *
+ * Keeping it attached to the line being typed — rather than in a floating box —
+ * means the filtered list and the query are always read together, which is how
+ * fzf-style pickers work.
+ *
+ * It takes rows rather than commands so the command list and an argument
+ * completer (see `argQuery`) draw through one path: both reduce to a key, a
+ * label and a description, and the label already carries whatever prefix it
+ * needs.
+ */
+export declare function CommandMenu({ rows, selected }: {
+    rows: PaletteRow[];
+    selected: number;
+}): import("react").JSX.Element;

package/dist/tui/format.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Truncate to `max` columns, ending in an ellipsis when it does not fit.
+ *
+ * Counts code units rather than grapheme clusters, which is what Ink's own
+ * `wrap="truncate-end"` does; matching it keeps hand-truncated and
+ * Ink-truncated strings the same width.
+ */
+export declare function truncate(text: string, max: number): string;
+/**
+ * How many terminal columns a string occupies.
+ *
+ * Deliberately not `text.length`: a CJK character is one code unit and *two*
+ * columns, so counting code units would size a Chinese line at half the pane
+ * and hand it to Ink to cut — the same truncation bug in a new place. Emoji and
+ * combining marks are wrong for the same reason.
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * Break one line of text into the rows a terminal will actually spend on it.
+ *
+ * Word-wrapped, because the stream pane carries an agent's prose as often as it
+ * carries log lines, and breaking mid-word would make the leader's reasoning
+ * harder to read than the truncation this replaced. A word with no space inside
+ * it — a path, a hash, a minified JSON blob — has nowhere to break, so it is
+ * split by width instead.
+ *
+ * Scripts that use wide characters get the rule they actually have: they put no
+ * spaces between words, so a whole Chinese sentence arrives as one "word" and
+ * would be pushed onto the next row whole, leaving the row before it mostly
+ * empty. They may be broken between any two characters instead, so they fill
+ * what is left. Narrow runs — English words, identifiers, numbers — are still
+ * atomic, which is what keeps this a no-op for output that has no CJK in it.
+ *
+ * Every returned row is at most `width` columns, which is what lets the caller
+ * count rows and trust the count.
+ */
+export declare function wrapLine(line: string, width: number): string[];
+/**
+ * Human duration, used for every time column in the console.
+ *
+ * One formatter everywhere is what makes the columns comparable — the eye can
+ * scan a stack of durations only if they share a shape.
+ */
+export declare function formatDuration(ms: number): string;
+/** Stage markers read as an ordered sequence at a glance; past twenty, fall back. */
+export declare function circled(n: number): string;
+/** Pad to a fixed column so sibling rows line up. */
+export declare function padRight(text: string, width: number): string;
+/** Elapsed time of a run that is still in flight, or its total once it has ended. */
+export declare function elapsedSince(startedAt: number | undefined, now: number): number | undefined;
+/**
+ * A compact token count, for a column that must stay narrow.
+ *
+ * `45200 → "45.2k"`, `950 → "950"`, `1_200_000 → "1.2M"`. Below a thousand the
+ * exact number is short enough to show; above it the decimal is what the eye
+ * reads, so the digits past it are dropped.
+ */
+export declare function formatTokens(n: number): string;
+/**
+ * A USD cost, at the precision a session total is read at.
+ *
+ * `0.42 → "$0.42"`, `0 → "$0.00"`, and anything under a cent as `"<$0.01"` rather
+ * than rounding it away to "$0.00" — a real but tiny cost must not read as free.
+ */
+export declare function formatCost(usd: number): string;

package/dist/tui/history.d.ts

@@ -0,0 +1,34 @@
+import { type TurnView } from "./state";
+/** Directory, under a workspace's `.multiclaw/`, that holds console state. */
+export declare const CONSOLE_DIR = "console";
+/** The finished-turn record the console keeps across sessions. */
+export declare const HISTORY_FILE = "history.json";
+/** Where exported turn markdown files are written by default. */
+export declare const EXPORT_DIR = "exports";
+/** Where the console keeps its turn history for a workspace. */
+export declare function historyPath(workDir: string): string;
+/**
+ * Read the workspace's turn history.
+ *
+ * Synchronous on purpose: it runs once, inside the reducer's lazy initialiser,
+ * before the first frame. An async load would race the user's first keystroke
+ * and force a "history is still arriving" state the console does not need.
+ *
+ * Never throws. A missing directory, malformed JSON, or a value of the wrong
+ * shape all mean "no history": the console can always start from empty, and
+ * crashing on startup because a side file got corrupted would be far worse.
+ */
+export declare function loadHistory(workDir: string): TurnView[];
+/**
+ * Write the workspace's turn history.
+ *
+ * Written to a temp file and renamed into place: `rename` is atomic within a
+ * filesystem, so a crash mid-write leaves the *previous* file intact. Writing
+ * `history.json` directly would instead leave half a JSON document, and since
+ * `loadHistory` can only drop a file it cannot parse, that would cost the user
+ * *all* of their history rather than the last write.
+ */
+export declare function saveHistory(workDir: string, turns: readonly TurnView[]): Promise<void>;
+export declare function exportPath(workDir: string, turn: number): string;
+export declare function exportTurn(turn: TurnView, filePath: string): Promise<void>;
+export declare function formatTurnMarkdown(turn: TurnView): string;

package/dist/tui/index.d.ts

@@ -0,0 +1,17 @@
+import type { EventBus, MultiClawConfig } from "@multiclawcli/core";
+export type { AppProps } from "./App";
+export * from "./layout";
+export * from "./state";
+export 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.
+ */
+export declare function startTui(options: TuiOptions): Promise<void>;

package/dist/tui/layout.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+export declare const MIN_COLUMNS = 40;
+export declare const MIN_ROWS = 10;
+/** Below this the roster is dropped so the stream keeps a usable width. */
+export declare const COMPACT_COLUMNS = 72;
+/** The rail costs a row; it only earns one when there is vertical room. */
+export 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.
+ */
+export declare const MAX_RAIL_ROWS = 2;
+/** Enough to see the palette is a list; more would push the stream off screen. */
+export declare const MAX_MENU_ROWS = 7;
+/** Queued follow-ups sit above the prompt; more than a few would crowd the stream. */
+export declare const MAX_QUEUE_ROWS = 3;
+export 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[];
+}
+export 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;
+    /**
+     * Text columns available to the stream pane's *content* — the roster, the
+     * rule between the panes and the stream's own left padding already taken out.
+     *
+     * The stream pre-wraps its output, so it has to know this before Ink lays
+     * anything out; there is no way to measure it back out of Yoga. The arithmetic
+     * is therefore deliberate about erring small: a row wrapped a column early
+     * costs a few characters of width, while a row wrapped a column late would be
+     * cut at the pane edge — the bug this exists to prevent.
+     */
+    streamWidth: 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.
+ */
+export declare function measureRailRows(cells: number[] | undefined, columns: number): number;
+export declare function computeLayout(input: LayoutInput): Layout;