@multiclawcli/dashboard 0.8.2 → 0.10.0

package/dist/tui/App.d.ts

@@ -1,5 +1,19 @@
 import type { EventBus, MultiClawConfig } from "@multiclawcli/core";
 import { AgentSessionManager } from "@multiclawcli/core";
+/**
+ * How the console should choose its session on launch.
+ *
+ * Absent means the default: continue the most recent session, or start one when
+ * the workspace has none. `new` always starts fresh. `resume` opens the named
+ * session, or — with no id — the most recent one with the picker already open,
+ * so `multiclaw -r` lands on the list the way `claude -r` does.
+ */
+export type InitialSession = {
+    kind: "new";
+} | {
+    kind: "resume";
+    id?: string;
+};
 export interface AppProps {
     config: MultiClawConfig;
     /**
@@ -11,5 +25,7 @@ export interface AppProps {
     sessions?: AgentSessionManager;
     /** Gives the terminal host an awaitable cleanup barrier, including render failures. */
     onCleanupReady?: (cleanup: () => Promise<void>) => void;
+    /** How to choose the session on launch; defaults to continuing the latest. */
+    initialSession?: InitialSession;
 }
-export declare function App({ config, onTurnStart, sessions: providedSessions, onCleanupReady }: AppProps): import("react").JSX.Element;
+export declare function App({ config, onTurnStart, sessions: providedSessions, onCleanupReady, initialSession, }: AppProps): import("react").JSX.Element;

package/dist/tui/atomic.d.ts

@@ -19,3 +19,13 @@ export declare function writeJsonFile(target: string, json: string): Promise<voi
  * the temporary file behind and the previous — older — file in place.
  */
 export declare function pendingWrite(target: string): Promise<void>;
+/**
+ * Append newline-terminated lines to `target`, serialized per path on the same
+ * chain as {@link writeJsonFile}.
+ *
+ * Unlike the rewrite path this does not go through a temp file: an append is the
+ * cheap O(1) write a JSONL log wants, and a crash mid-append can only tear the
+ * *last* line, which every line-oriented reader here already skips. Sharing the
+ * `writes` chain keeps a `pendingWrite` on the same path able to await it.
+ */
+export declare function appendLines(target: string, lines: readonly string[]): Promise<void>;

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

@@ -1,3 +1,4 @@
+import type { SessionMeta } from "../sessions";
 import { type TurnView } from "../state";
 interface HelpGroup {
     title: string;
@@ -61,4 +62,22 @@ export declare function HistoryOverlay({ turns, selected, width, maxRows, }: {
     /** Rows available in the body. The list is windowed against this. */
     maxRows: number;
 }): import("react").JSX.Element;
+/**
+ * The session picker: every session in the workspace, newest activity first.
+ *
+ * The level above {@link HistoryOverlay}. Where the history list browses the
+ * turns *within* a session, this switches between whole sessions — the thing a
+ * restart, a `/new`, or opening the console again all create. The one the
+ * console is attached to is marked, because "which am I on" is the first
+ * question the list has to answer.
+ */
+export declare function SessionsOverlay({ sessions, selected, currentId, width, maxRows, now, }: {
+    sessions: SessionMeta[];
+    selected: number;
+    currentId: string | undefined;
+    width: number;
+    /** Rows available in the body. The list is windowed against this. */
+    maxRows: number;
+    now: number;
+}): import("react").JSX.Element;
 export {};

package/dist/tui/format.d.ts

@@ -43,6 +43,14 @@ export declare function wrapLine(line: string, width: number): string[];
  * scan a stack of durations only if they share a shape.
  */
 export declare function formatDuration(ms: number): string;
+/**
+ * A coarse "how long ago", for the session list.
+ *
+ * Deliberately low-resolution — the picker wants "which one did I touch last",
+ * not a precise clock. Future timestamps (a clock that moved backwards) read as
+ * "just now" rather than a negative age.
+ */
+export declare function formatAgo(timestamp: number, now: 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. */

package/dist/tui/history.d.ts

@@ -1,14 +1,12 @@
 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";
+/** The finished-turn log a session keeps, one JSON turn per line. */
+export declare const TURNS_FILE = "turns.jsonl";
 /** 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;
+/** Where a session keeps its finished turns. */
+export declare function turnsPath(workDir: string, sessionId: string): string;
 /**
- * Read the workspace's turn history.
+ * Read a session'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
@@ -16,18 +14,21 @@ export declare function historyPath(workDir: string): string;
  *
  * 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.
+ * crashing on startup because a side file got corrupted would be far worse. The
+ * log is line-oriented, so a single torn line (a crash mid-append) is skipped
+ * rather than costing the whole session's history.
  */
-export declare function loadHistory(workDir: string): TurnView[];
+export declare function loadTurns(workDir: string, sessionId: string): TurnView[];
 /**
- * Write the workspace's turn history.
+ * Append finished turns to a session's log, one JSON object per line.
  *
- * 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.
+ * Append-only and serialized per path (see {@link appendLines}): each settled
+ * turn is an O(1) write rather than a rewrite of the whole history, and a crash
+ * mid-append can only tear the last line, which {@link loadTurns} skips. Callers
+ * pass only the turns not yet persisted, tracked by the highest turn number
+ * already written.
  */
-export declare function saveHistory(workDir: string, turns: readonly TurnView[]): Promise<void>;
-export declare function exportPath(workDir: string, turn: number): string;
+export declare function appendTurns(workDir: string, sessionId: string, turns: readonly TurnView[]): Promise<void>;
+export declare function exportPath(workDir: string, sessionId: 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

@@ -1,11 +1,14 @@
 import { type EventBus, type MultiClawConfig } from "@multiclawcli/core";
-export type { AppProps } from "./App";
+import { type InitialSession } from "./App";
+export type { AppProps, InitialSession } 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 | (() => void | Promise<void>);
+    /** How to choose the session on launch; defaults to continuing the latest. */
+    initialSession?: InitialSession;
 }
 /**
  * Render the interactive team console.

package/dist/tui/session.d.ts

@@ -5,10 +5,10 @@ import { type AgentView, type TuiStageInfo, type TuiState, type TurnView } from
  * 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.
+ * instead: which turn was running, what the user had typed but not run, 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. */
@@ -48,29 +48,21 @@ export interface JournalTurn {
 }
 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;
+/** Where a session keeps its journal. */
+export declare function sessionPath(workDir: string, sessionId: string): string;
 /**
- * Read the workspace's session journal.
+ * Read a session's 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.
+ * Never throws, for the same reason `loadTurns` 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;
+export declare function loadJournal(workDir: string, sessionId: string): SessionJournal | undefined;
 /**
  * Write the workspace's session journal.
  *
@@ -78,12 +70,12 @@ export declare function loadJournal(workDir: string): SessionJournal | undefined
  * 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.
+ * An empty journal does not create the file. A session that was opened and quit
+ * without doing anything should not leave a journal 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>;
+export declare function saveJournal(workDir: string, sessionId: string, journal: SessionJournal): Promise<void>;
 /**
  * The journal entry for a turn that is running right now.
  *
@@ -115,20 +107,25 @@ export declare function interruptedTurn(entry: JournalTurn): TurnView;
 export interface RestoredConsole {
     history: TurnView[];
     queue: string[];
-    taskStart: number;
+    /**
+     * Highest turn number already on disk in `turns.jsonl` — the watermark the
+     * console appends past. Excludes a journal-recovered interrupted turn, which
+     * lives only in the journal until the next save writes it to the log.
+     */
+    persistedTurn: 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.
+ * Everything the console should open a session 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.
+ * it: the turns before it still happened. It is skipped when the log already
+ * holds that turn number, because a restored turn is written to the log on the
+ * very next save — a second restart must not add it twice. A journal *behind*
+ * the last recorded turn is stale (the log was written by a later session) and
+ * is dropped for the same reason.
  */
-export declare function restoreConsole(workDir: string): RestoredConsole;
+export declare function restoreConsole(workDir: string, sessionId: string): RestoredConsole;

package/dist/tui/sessions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Sessions: the unit of history and resumption.
+ *
+ * A session is one continuous line of work — a sequence of turns, each fanning
+ * out to the same team of agents. It is what Claude Code / Codex call a session:
+ * an independent, listable, resumable, deletable record. Everything a session
+ * owns lives under its own directory (`turns.jsonl`, `session.json`, exports),
+ * and a small `index.json` holds just the summaries the picker needs so it never
+ * has to open a session to list one.
+ */
+export declare const SESSIONS_DIR = "sessions";
+/** The summary index, read by the picker; one entry per session. */
+export declare const INDEX_FILE = "index.json";
+/** How long a session title may grow before it is truncated for the index. */
+export declare const MAX_TITLE_CHARS = 80;
+export interface SessionMeta {
+    id: string;
+    /** First turn's requirement, truncated. Empty until the session runs a turn. */
+    title: string;
+    createdAt: number;
+    lastActiveAt: number;
+    /** Highest turn number the session has recorded. */
+    turnCount: number;
+}
+export declare function sessionsRoot(workDir: string): string;
+export declare function sessionDir(workDir: string, id: string): string;
+/**
+ * Read the session index, newest-first by last activity.
+ *
+ * Never throws, like `loadTurns`: a missing or corrupt index means "no sessions
+ * the picker can show", which is always a safe place to start from. A single bad
+ * entry is dropped rather than losing the whole list.
+ */
+export declare function listSessions(workDir: string): SessionMeta[];
+/** The most recently active session, or undefined when there is none. */
+export declare function latestSession(workDir: string): SessionMeta | undefined;
+/**
+ * Register a new, empty session and return its metadata.
+ *
+ * The directory is not created here — `appendTurns` and `saveJournal` both
+ * `mkdir` lazily, so a session that is created and never run leaves nothing but
+ * an index entry behind.
+ */
+export declare function createSession(workDir: string): SessionMeta;
+/** Remove a session's directory and its index entry. Idempotent. */
+export declare function deleteSession(workDir: string, id: string): void;
+/** Update a session's summary in the index. `lastActiveAt` defaults to now. */
+export declare function touchSession(workDir: string, id: string, patch: Partial<Pick<SessionMeta, "title" | "turnCount" | "lastActiveAt">>): void;

package/dist/tui/state.d.ts

@@ -210,6 +210,27 @@ export type TuiAction = {
 /** Flip whether tool detail is shown in the stream. */
  | {
     type: "verbose:toggle";
+}
+/**
+ * Start a fresh session in place: empty history, turn counter back to zero,
+ * roster reseeded. Carries the seeded agents and leader ids the same way
+ * `turn:start` does, so no module-level object is shared into live state.
+ */
+ | {
+    type: "session:reset";
+    agents: Record<string, AgentView>;
+    leaderIds: string[];
+}
+/**
+ * Switch to an existing session: like `session:reset`, but seeded with that
+ * session's finished turns so its history is on screen and the turn counter
+ * continues from where it left off.
+ */
+ | {
+    type: "session:load";
+    agents: Record<string, AgentView>;
+    leaderIds: string[];
+    history: TurnView[];
 };
 export declare function stripAnsi(text: string): string;
 /** Append a chunk, keeping only the last {@link MAX_LOG_CHARS} characters. */