@multiclawcli/dashboard 0.3.2 → 0.5.0

package/dist/tui/state.d.ts

@@ -0,0 +1,292 @@
+import type { AgentDefinition, AgentOutput, AgentStatus, LeaderMessage, MultiClawConfig, MultiClawEvent, StageInfo, TurnRecord } from "@multiclawcli/core";
+/**
+ * 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.
+ */
+export declare const MAX_LOG_CHARS = 8000;
+export 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;
+    /** Context-window usage the runtime reported, when it reported any. */
+    usage?: AgentOutput["usage"];
+    /** USD cost the runtime reported, when the provider priced itself. */
+    costUsd?: number;
+    /**
+     * Session the agent ran under, when the runtime reported one. Carried so
+     * `/retry` can ask the agent to continue where it left off instead of
+     * re-exploring from scratch.
+     */
+    sessionId?: string;
+    logs: string;
+}
+export 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.
+ */
+export 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 rows 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.
+     *
+     * Counted in *terminal rows*, not log lines: a log line can wrap over
+     * several rows, and the window has to add up to the pane's height.
+     */
+    scroll: number;
+    success?: boolean;
+    totalDuration?: number;
+    /**
+     * Sum of the per-agent costs the runtime reported, in USD. Absent when none
+     * was reported — "no data" is not the same as "free", so the console must not
+     * print a cost that was never measured.
+     */
+    totalCostUsd?: number;
+    /** Short explanation the leader gave for choosing the current pipeline. */
+    reason?: string;
+    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. */
+export declare const MAX_HISTORY = 20;
+export 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;
+    /**
+     * Whether tool detail is shown in the stream.
+     *
+     * Console state, not turn state: it belongs here rather than on `TurnView` so
+     * `snapshot()` never writes it into a history record, and toggling it applies
+     * to whichever turn is on screen.
+     */
+    verbose: boolean;
+}
+export declare const initialState: TuiState;
+export 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, in terminal rows. `viewport` is needed to clamp
+ * at the tail, and `width` because how many rows a log line spends depends on
+ * the pane's width — a line that wraps to three rows scrolls three rows.
+ */
+ | {
+    type: "stream:scroll";
+    delta: number;
+    viewport: number;
+    width: number;
+}
+/** Jump the focused stream to the newest wrapped row containing `query`. */
+ | {
+    type: "stream:search";
+    query: string;
+    viewport: number;
+    width: number;
+}
+/** Return the focused stream to the tail and re-arm live follow. */
+ | {
+    type: "stream:latest";
+}
+/** 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";
+}
+/** Flip whether tool detail is shown in the stream. */
+ | {
+    type: "verbose:toggle";
+};
+export declare function stripAnsi(text: string): string;
+/** Append a chunk, keeping only the last {@link MAX_LOG_CHARS} characters. */
+export declare function appendLog(previous: string, chunk: string): string;
+/** Every agent that takes part in a run, in declaration order: leader first. */
+export declare function plannedAgents(config: MultiClawConfig): AgentDefinition[];
+export 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.
+ */
+export declare function seedAgents(config: MultiClawConfig): Record<string, AgentView>;
+/**
+ * Build the console's opening state, optionally seeded with turns from disk.
+ *
+ * `history` is the second parameter rather than part of `config` because it is
+ * *session* state, not configuration: two runs of the same config start from the
+ * same config but different pasts.
+ *
+ * The turn counter continues from the last restored turn (`history`'s last
+ * entry) so numbering stays monotonic across sessions. If it restarted at zero,
+ * `/replay 3` would be ambiguous the moment a second session began — two turns
+ * would share the number three.
+ *
+ * The parameter is optional and defaults to `[]`, so every existing caller keeps
+ * the exact behaviour it had before history existed (turn 0, empty history). This
+ * module is re-exported wholesale by `src/tui/index.ts`, so widening the
+ * signature any other way would be a breaking change to the public API.
+ */
+export declare function createInitialState(config: MultiClawConfig, history?: TurnView[]): TuiState;
+export declare function reduceEvent(state: TuiState, event: MultiClawEvent): TuiState;
+/**
+ * The turns worth keeping: those already in `history`, plus the turn on screen
+ * once it has ended.
+ *
+ * The live turn joins the set only when its `phase` is `complete`. While it is
+ * still `running` it is half a turn — the requirement is known but the outcome
+ * is not — and a record captured mid-flight would be written to disk as a turn
+ * that never finishes. The two places that persist turns (the on-disk history
+ * and the leader's conversation context) must agree on which turns exist, so
+ * they both derive from here rather than each rebuilding the set.
+ *
+ * `snapshot` is module-private, which is why this helper lives in `state.ts`
+ * rather than beside the file-writing code in `history.ts`.
+ */
+export declare function recordedTurns(state: TuiState): TurnView[];
+/**
+ * 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: the recorded turns *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.
+ */
+export declare function conversationTurns(state: TuiState): TurnRecord[];
+export declare function tuiReducer(state: TuiState, action: TuiAction): TuiState;
+/**
+ * Roll a stage's member statuses up into one status for the pipeline bar.
+ *
+ * Ordering is by severity: a failure anywhere outranks a run in flight, which
+ * outranks a uniform outcome. `cancelled` is a settled outcome like `success`
+ * and `skipped`, so a stage of cancelled members reads as `cancelled` rather
+ * than falling through to `pending` — a stopped stage is not one that has yet
+ * to start, and reporting it as `pending` would be the same lie B2-6 fixed one
+ * level down.
+ */
+export declare function stageStatus(stage: StageInfo, agents: Record<string, AgentView>): AgentStatus;
+/** How many agents have finished, out of how many the turn will run. */
+export 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.
+ */
+export declare function agentElapsed(agent: AgentView, now: number): number | undefined;
+/** The turn's time, live while running and frozen once the orchestrator reports back. */
+export declare function turnElapsed(turn: TurnView, now: number): number | undefined;
+export interface LogWindow {
+    /** The wrapped rows that fit, oldest first. */
+    rows: string[];
+    /** How many rows 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.
+ *
+ * Wrapped first, then windowed, and both steps are needed: the pane is a fixed
+ * number of *rows*, while the buffer is a string of *lines*, and one line can
+ * spend several rows. Slicing lines would hand the pane more rows than it has
+ * and push the newest output out of sight.
+ *
+ * Clamping here as well as in the reducer keeps the window correct even when
+ * the pane is resized between two scroll actions.
+ */
+export declare function visibleLog(turn: TurnView, viewport: number, width: number): LogWindow;

package/dist/tui/theme.d.ts

@@ -0,0 +1,66 @@
+import type { AgentStatus } from "@multiclawcli/core";
+/**
+ * Semantic colours, in one place.
+ *
+ * Only the sixteen named ANSI colours are used. Every terminal theme remaps
+ * those to something legible against its own background; a hard-coded hex would
+ * look right on the author's machine and wrong on everyone else's.
+ */
+export declare const COLOR: {
+    readonly accent: "cyan";
+    readonly ok: "green";
+    readonly warn: "yellow";
+    readonly error: "red";
+    readonly muted: "gray";
+};
+export interface StatusStyle {
+    glyph: string;
+    color: string;
+    dim?: boolean;
+    /** Word used in prose contexts (stream header, help). */
+    label: string;
+}
+/**
+ * Status is always a glyph *and* a colour.
+ *
+ * Colour alone would be invisible to a colour-blind user and would vanish the
+ * moment the output is copied into a log or an issue.
+ */
+export declare const STATUS: Record<AgentStatus, StatusStyle>;
+/** Braille spinner frames, cycled in place of the static running glyph. */
+export declare const SPINNER: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export declare const GLYPH: {
+    /** Marks the console itself in the header and the welcome screen. */
+    readonly brand: "◆";
+    /** The leader runs before the pipeline exists, so it gets its own mark. */
+    readonly leader: "◆";
+    readonly agent: "◇";
+    /** Points at the focused row in the team list. */
+    readonly caret: "›";
+    /** Pipeline flow between stages. */
+    readonly connector: "──▸";
+    /** The stream is tailing; new output appears as it arrives. */
+    readonly live: "▼";
+    /** The stream is parked while the user reads back. */
+    readonly paused: "⏸";
+    /**
+     * A follow-up waiting for the team to finish.
+     *
+     * Latin-1 on purpose: it renders as exactly one cell in every terminal, which
+     * a pictograph like ⏳ does not.
+     */
+    readonly queued: "»";
+    /** The leader is asking for a decision rather than reporting one. */
+    readonly ask: "?";
+    /** A mid-turn warning that rides alongside the outcome rather than hiding it. */
+    readonly warn: "⚠";
+    /**
+     * A pasted line break, drawn in the one-line prompt.
+     *
+     * MUST be exactly one column wide. `Prompt` maps `\n` to this glyph 1:1 — one
+     * character in, one character out — so its caret index stays valid; a glyph
+     * that rendered as two columns would push the caret off by one for every
+     * newline before it. If a terminal disagrees, this single glyph is the fix.
+     */
+    readonly newline: "↵";
+};