@multiclawcli/dashboard 0.5.0 → 0.6.0

package/dist/tui/App.d.ts

@@ -1,10 +1,15 @@
 import type { EventBus, MultiClawConfig } from "@multiclawcli/core";
+import { AgentSessionManager } 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;
+    onTurnStart?: (eventBus: EventBus, logDir: string) => void | (() => void | Promise<void>);
+    /** Caller-owned resources; startTui also closes them on render failures. */
+    sessions?: AgentSessionManager;
+    /** Gives the terminal host an awaitable cleanup barrier, including render failures. */
+    onCleanupReady?: (cleanup: () => Promise<void>) => void;
 }
-export declare function App({ config, onTurnStart }: AppProps): import("react").JSX.Element;
+export declare function App({ config, onTurnStart, sessions: providedSessions, onCleanupReady }: AppProps): import("react").JSX.Element;

package/dist/tui/atomic.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Write JSON to `target` atomically, serialized per path.
+ *
+ * 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
+ * the target directly would instead leave half a JSON document, and since every
+ * reader here can only drop a file it cannot parse, that would cost the user
+ * *all* of their state rather than the last write.
+ *
+ * The returned promise rejects on failure; the serialization chain swallows it
+ * so one failed write cannot poison the next.
+ */
+export declare function writeJsonFile(target: string, json: string): Promise<void>;
+/**
+ * The last write queued for `target`, or a resolved promise when there is none.
+ *
+ * Lets a shutdown wait for state that is already on its way to disk. Without it
+ * the process can exit between the `writeFile` and the `rename`, which leaves
+ * the temporary file behind and the previous — older — file in place.
+ */
+export declare function pendingWrite(target: string): Promise<void>;

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

@@ -1,3 +1,4 @@
+import type { RuntimePermissionRequest, RuntimeQuestionRequest } from "@multiclawcli/core";
 import { type TurnView } from "../state";
 interface HelpGroup {
     title: string;
@@ -43,6 +44,22 @@ export declare function HelpOverlay({ width, maxRows }: {
     width: number;
     maxRows: number;
 }): import("react").JSX.Element;
+export declare function PermissionOverlay({ request, shortId, queued, width, maxRows, }: {
+    request: RuntimePermissionRequest;
+    shortId: string;
+    queued: number;
+    width: number;
+    maxRows: number;
+}): import("react").JSX.Element;
+export declare function questionLines(request: RuntimeQuestionRequest, width: number): string[];
+export declare function QuestionOverlay({ request, shortId, queued, width, maxRows, offset, }: {
+    request: RuntimeQuestionRequest;
+    shortId: string;
+    queued: number;
+    width: number;
+    maxRows: number;
+    offset: number;
+}): import("react").JSX.Element;
 /**
  * The finished turns, newest first.
  *

package/dist/tui/format.d.ts

@@ -1,3 +1,4 @@
+import type { SupplementReport } from "@multiclawcli/core";
 /**
  * Truncate to `max` columns, ending in an ellipsis when it does not fit.
  *
@@ -63,3 +64,21 @@ export declare function formatTokens(n: number): string;
  * than rounding it away to "$0.00" — a real but tiny cost must not read as free.
  */
 export declare function formatCost(usd: number): string;
+/**
+ * What to tell the user after a mid-turn message.
+ *
+ * Reports are per agent and each carries its own reason, so the sentence names
+ * agents rather than summarising an outcome: "steered architect · leader was
+ * between turns" tells the user what happened to whom, while "steering failed"
+ * tells them nothing they can act on.
+ *
+ * `error` and `idle` must never be collapsed: the first is a delivery that went
+ * wrong, the second is a message that arrived at the wrong moment. Calling the
+ * first the second would tell the user to simply wait when they should be
+ * looking at a failure.
+ *
+ * When nothing was delivered the caller queues the text, so the sentence says
+ * so — otherwise the user is left believing their message is inside the turn
+ * they are watching.
+ */
+export declare function describeSteering(reports: readonly SupplementReport[]): string;

package/dist/tui/history.d.ts

@@ -22,11 +22,10 @@ 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.
+ * Atomic and serialized per path (see {@link writeJsonFile}), because a crash
+ * mid-write must leave the previous history readable rather than half a
+ * document: `loadHistory` can only drop a file it cannot parse, so a torn write
+ * would cost the user *all* of their history rather than the last one.
  */
 export declare function saveHistory(workDir: string, turns: readonly TurnView[]): Promise<void>;
 export declare function exportPath(workDir: string, turn: number): string;

package/dist/tui/index.d.ts

@@ -1,11 +1,11 @@
-import type { EventBus, MultiClawConfig } from "@multiclawcli/core";
+import { type EventBus, type 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;
+    onTurnStart?: (eventBus: EventBus, logDir: string) => void | (() => void | Promise<void>);
 }
 /**
  * Render the interactive team console.

package/dist/tui/session.d.ts

@@ -0,0 +1,134 @@
+import { type AgentView, type TuiStageInfo, type TuiState, type TurnView } from "./state";
+/**
+ * The session journal: what a restart needs to pick the console back up.
+ *
+ * Live agent sessions are child processes, and a pending approval is an RPC in
+ * flight to one of them — neither survives the process that owns them. So this
+ * file deliberately does not try to *continue* a turn. It records the boundary
+ * instead: which turn was running, what the user had typed but not run, where
+ * the current task began, and how many decisions were waiting. A restart can
+ * then say what happened, show the interrupted turn as a turn, and hand the
+ * queued input back — without pretending a dead agent is still working.
+ */
+export declare const SESSION_FILE = "session.json";
+/** Bumped when the on-disk shape changes in a way an older console cannot read. */
+export declare const SESSION_VERSION = 1;
+/**
+ * How much of each agent's log the journal keeps.
+ *
+ * The live buffer holds `MAX_LOG_CHARS` per agent and a turn can have a dozen
+ * agents, so journaling it whole would rewrite a multi-hundred-kilobyte file
+ * every few seconds. The tail is what answers "what was it doing when it died",
+ * and it is the only part worth the write.
+ */
+export declare const MAX_JOURNAL_LOG_CHARS = 1200;
+/** The turn that was in flight when the journal was last written. */
+export interface JournalTurn {
+    turn: number;
+    requirement: string;
+    startedAt?: number;
+    effectiveRequirement?: string;
+    reason?: string;
+    warning?: string;
+    /**
+     * Wall clock of this write — the last moment the console was known to be
+     * alive. The restored turn ends here, so its duration reads as "how long it
+     * ran", not "how long ago it was".
+     */
+    savedAt: number;
+    leaderIds: string[];
+    focusId?: string;
+    stages: TuiStageInfo[];
+    agents: Record<string, AgentView>;
+    /** Decisions the agents were waiting on. A restart cannot answer them. */
+    pending?: {
+        permissions: number;
+        questions: number;
+    };
+}
+export interface SessionJournal {
+    version: number;
+    /**
+     * Turn number the current task began at.
+     *
+     * `/task` closes the previous task's context, and that boundary has to outlive
+     * the process: without it a restart would hand the leader every turn ever run
+     * in the workspace, including the ones the user explicitly closed.
+     */
+    taskStart?: number;
+    /** Follow-ups typed but never run, in the order they were typed. */
+    queue?: string[];
+    inFlight?: JournalTurn;
+}
+/** Where the console keeps its session journal for a workspace. */
+export declare function sessionPath(workDir: string): string;
+/**
+ * Read the workspace's session journal.
+ *
+ * Never throws, for the same reason `loadHistory` does not: a corrupted side
+ * file means "no journal", and a console that refuses to start over it would be
+ * far worse than one that starts with an empty past. A journal written by a
+ * newer console (unknown `version`) is ignored rather than guessed at.
+ */
+export declare function loadJournal(workDir: string): SessionJournal | undefined;
+/**
+ * Write the workspace's session journal.
+ *
+ * Atomic and serialized per path (see {@link writeJsonFile}): the whole point is
+ * to survive a process that dies mid-write, so the write itself must never be
+ * the thing that leaves a torn file behind.
+ *
+ * An empty journal does not create the file. A console that was opened and quit
+ * without doing anything should not leave `.multiclaw/console/` behind — but an
+ * *existing* journal is still rewritten when it empties, because "nothing is in
+ * flight" is exactly what the next start needs to read.
+ */
+export declare function saveJournal(workDir: string, journal: SessionJournal): Promise<void>;
+/**
+ * The journal entry for a turn that is running right now.
+ *
+ * A pure projection of what the panes are showing, so the journal can never
+ * describe a turn the console is not actually running. Logs are trimmed; every
+ * other field is small enough to keep whole.
+ */
+export declare function journalTurn(state: TuiState, pending: {
+    permissions: number;
+    questions: number;
+}): JournalTurn;
+/**
+ * Rebuild an interrupted turn as a browsable record.
+ *
+ * Two deliberate rewrites, both because the record must not claim work that is
+ * not happening:
+ *
+ * - An agent that never reported back becomes `cancelled`. Leaving it `running`
+ *   would animate a spinner and a growing clock for a process that died with
+ *   the console.
+ * - Stage outcomes are dropped so they are re-derived from those statuses. A
+ *   stage that had finished before the crash keeps its success, and one that was
+ *   mid-flight reads as cancelled instead of frozen at `running` for ever.
+ *
+ * The turn itself is `complete` — nothing will be added to it — with
+ * `interrupted` set so every surface can say *how* it ended.
+ */
+export declare function interruptedTurn(entry: JournalTurn): TurnView;
+export interface RestoredConsole {
+    history: TurnView[];
+    queue: string[];
+    taskStart: number;
+    /** The last turn ended by asking the user something, so the console reopens ready for it. */
+    awaitingAnswer: boolean;
+    /** One line for the notice bar, when the previous session left work behind. */
+    notice?: string;
+}
+/**
+ * Everything the console should open with, read once at startup.
+ *
+ * The interrupted turn is appended to the restored history rather than replacing
+ * it: the turns before it still happened. It is skipped when history already
+ * holds that turn number, because a restored turn is written back to
+ * `history.json` on the very next save — a second restart must not add it twice.
+ * A journal *behind* the last recorded turn is stale (the history was written by
+ * a later session) and is dropped for the same reason.
+ */
+export declare function restoreConsole(workDir: string): RestoredConsole;

package/dist/tui/state.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDefinition, AgentOutput, AgentStatus, LeaderMessage, MultiClawConfig, MultiClawEvent, StageInfo, TurnRecord } from "@multiclawcli/core";
+import type { AcceptanceResult, AgentDefinition, AgentOutput, AgentStatus, LeaderMessage, MultiClawConfig, MultiClawEvent, StageInfo, TurnRecord } from "@multiclawcli/core";
 /**
  * Per-agent log buffer cap, in characters.
  *
@@ -41,6 +41,11 @@ export interface AgentView {
     logs: string;
 }
 export type TuiPhase = "idle" | "running" | "complete";
+export interface TuiStageInfo extends StageInfo {
+    /** Frozen when this stage finishes, independent of later runs of its agents. */
+    outcome?: AgentStatus;
+    memberStatuses?: Record<string, AgentStatus>;
+}
 /**
  * One turn, as the panes need to see it.
  *
@@ -52,12 +57,14 @@ export type TuiPhase = "idle" | "running" | "complete";
 export interface TurnView {
     turn: number;
     requirement?: string;
+    effectiveRequirement?: string;
+    cancelled?: boolean;
     phase: TuiPhase;
     /** Wall clock at which the turn started. */
     startedAt?: number;
     /** Wall clock at which the turn finished. */
     endedAt?: number;
-    stages: StageInfo[];
+    stages: TuiStageInfo[];
     agents: Record<string, AgentView>;
     /**
      * Agents that run *before* the pipeline exists (the leader), so the pipeline
@@ -82,6 +89,19 @@ export interface TurnView {
      */
     scroll: number;
     success?: boolean;
+    /**
+     * Set on a turn that was recovered from a journal after the console died
+     * mid-run.
+     *
+     * Such a turn is `complete` — it is over, and its record is final — but it
+     * did not *finish*, so it must not be reported as a success or a failure.
+     * `cancelled` is deliberately not reused: that means the user stopped the
+     * run, while this one was stopped by the process going away, and the console
+     * has to be able to tell the two apart when the user asks "what happened to
+     * turn 3".
+     */
+    interrupted?: boolean;
+    acceptance?: AcceptanceResult;
     totalDuration?: number;
     /**
      * Sum of the per-agent costs the runtime reported, in USD. Absent when none
@@ -166,6 +186,18 @@ export type TuiAction = {
  | {
     type: "stream:clear";
 }
+/**
+ * Append a console marker to one agent's stream — what the user did, not what
+ * the agent said.
+ *
+ * Always the live turn: a mid-turn message can only reach what is running
+ * now, so there is no past turn for it to belong to.
+ */
+ | {
+    type: "stream:note";
+    agentId: string;
+    text: string;
+}
 /** Open a finished turn for reading, by its turn number. */
  | {
     type: "view:open";
@@ -244,6 +276,12 @@ export declare function recordedTurns(state: TuiState): TurnView[];
  * 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.
+ *
+ * An *interrupted* turn is carried even though it has no reply. A cancelled one
+ * is not: the user chose to abandon it. An interrupted turn was abandoned by
+ * the process, so its requirement is unfinished business — and it is the only
+ * thing that makes a follow-up like "carry on with that" readable after a
+ * restart.
  */
 export declare function conversationTurns(state: TuiState): TurnRecord[];
 export declare function tuiReducer(state: TuiState, action: TuiAction): TuiState;
@@ -257,7 +295,7 @@ export declare function tuiReducer(state: TuiState, action: TuiAction): TuiState
  * 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;
+export declare function stageStatus(stage: TuiStageInfo, 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;