agent-tempo 1.0.1

package/dist/tui/store.d.ts

@@ -0,0 +1,598 @@
+/**
+ * TUI state management — useReducer + React context.
+ * No external state libraries. All state flows through a single dispatch.
+ *
+ * Supports multi-ensemble navigation: home -> ensemble -> player views.
+ */
+import type { AttachmentPhase, MaestroPlayerInfo, MaestroRelayMessage, HistoryEntry, Message, SentMessage, SessionMetadata, ScheduleEntry, EnsembleChatMessage, EnsembleChatResult } from '../types';
+import type { EnsembleSummary } from '../client';
+/** Conversation-entry shape rendered by `ConversationStream`. */
+export interface ConversationEntry {
+    id: string;
+    from: string;
+    to: string;
+    text: string;
+    timestamp: string;
+    direction: 'in' | 'out';
+    role?: 'maestro-out' | 'maestro-in' | 'conductor-out' | 'conductor-in';
+    thirdParty?: boolean;
+    /**
+     * #357: Mirrors `EnsembleChatMessage.broadcastId`. Threaded through
+     * `toConversationEntry` so the TUI's `ConversationStream.foldByBroadcastId`
+     * can collapse consecutive entries sharing the same id into one row.
+     */
+    broadcastId?: string;
+}
+/**
+ * Project an `EnsembleChatMessage` into a `ConversationEntry`. Shared by
+ * the reducer's incremental path (`APPEND_CHAT_MESSAGE`) and the SSE
+ * snapshot/recovery paths (`src/tui/sse-handler.ts`) so both produce the
+ * same shape.
+ */
+export declare function toConversationEntry(m: EnsembleChatMessage): ConversationEntry;
+/**
+ * TuiView tracks the *navigation hierarchy* (home → ensemble → player).
+ * It determines what data to fetch and what breadcrumb context to show.
+ */
+export type TuiView = 'home' | 'ensemble' | 'player';
+/**
+ * TuiPhase tracks the *application lifecycle* (splash → main → chat/error).
+ * It determines which component renders in the live content area.
+ * A phase can span multiple views (e.g., 'main' shows either home or ensemble view).
+ */
+export type TuiPhase = 'splash' | 'main' | 'chat' | 'recruit' | 'schedule-create' | 'create-ensemble' | 'error';
+export interface StaticItem {
+    id: string;
+    type: 'splash-done' | 'command-output' | 'message' | 'error' | 'info';
+    content: string;
+    timestamp: number;
+    /** Message-specific fields for rich rendering in scrollback. */
+    msgDirection?: 'in' | 'out';
+    msgSender?: string;
+    msgTime?: string;
+    msgThirdParty?: boolean;
+    msgRouteLabel?: string;
+}
+/**
+ * #306: Bottom-pinned ephemeral notifications for errors + warnings.
+ *
+ * Before #306 these rode `commitStatic('error'|'warn', …)` and scrolled out
+ * of view — users missed critical guard errors (e.g. `/destroy conductor`
+ * refusals) because a few lines of other output pushed them above the fold.
+ * Notifications render below the prompt, auto-dismiss on TTL, and can be
+ * dismissed with Esc.
+ */
+export interface NotificationItem {
+    id: number;
+    kind: 'error' | 'warn' | 'info';
+    content: string;
+    timestamp: number;
+    /** Absolute ms epoch when this notification should disappear. */
+    expiresAt: number;
+}
+/** Default TTLs by kind — errors get extra time to read. */
+export declare const NOTIFICATION_TTL_MS: {
+    readonly error: 8000;
+    readonly warn: 5000;
+    readonly info: 5000;
+};
+/** Maximum concurrent notifications; oldest is dropped when exceeded. */
+export declare const NOTIFICATION_CAP = 3;
+export type RecruitStep = 'name' | 'agent' | 'type' | 'workDir' | 'message' | 'host' | 'confirm' | 'done';
+export interface RecruitAnswers {
+    name: string;
+    agent: 'claude' | 'copilot';
+    playerType: string;
+    workDir: string;
+    initialMessage: string;
+    host: string;
+}
+/**
+ * Wizard Pattern:
+ * - Each wizard has a phase (e.g., 'recruit', 'schedule-create', 'create-ensemble')
+ * - State: step name, answers accumulator, error, submitting flag, pre-wizard phase/chatTarget
+ * - Actions: ENTER_*, *_NEXT_STEP, *_PREV_STEP, *_SUBMIT, *_DONE, EXIT_*
+ * - Components: zero-Yoga-node Text renders, manual key handling in App.tsx useInput
+ * - Pre-wizard state (phase, chatTarget) is saved on enter and restored on exit
+ * - Future: normalize to generic WizardState<TStep, TAnswers> (see #96)
+ */
+export interface RecruitState {
+    step: RecruitStep;
+    answers: RecruitAnswers;
+    /** Error from the recruit API call, if any. */
+    error?: string;
+    /** Whether the recruit API call is in progress. */
+    submitting?: boolean;
+    /** Phase before entering the wizard (restored on exit). */
+    preRecruitPhase: TuiPhase;
+    /** Chat target before entering the wizard (restored on exit). */
+    preRecruitChatTarget?: string;
+}
+export declare const RECRUIT_STEPS: RecruitStep[];
+export type ScheduleStep = 'target' | 'message' | 'schedType' | 'timing' | 'timezone' | 'confirm' | 'done';
+export type ScheduleType = 'delay' | 'at' | 'every' | 'cron';
+export interface ScheduleAnswers {
+    target: string;
+    message: string;
+    schedType: ScheduleType;
+    timing: string;
+    timezone: string;
+    name: string;
+}
+export interface ScheduleWizardState {
+    step: ScheduleStep;
+    answers: ScheduleAnswers;
+    error?: string;
+    submitting?: boolean;
+    prePhase: TuiPhase;
+    preChatTarget?: string;
+}
+export declare const SCHEDULE_STEPS: ScheduleStep[];
+export declare const DEFAULT_SCHEDULE_ANSWERS: ScheduleAnswers;
+export declare function defaultRecruitAnswers(defaultAgent?: 'claude' | 'copilot'): RecruitAnswers;
+export type CreateEnsembleStep = 'name' | 'workDir' | 'lineup' | 'confirm' | 'done';
+export interface CreateEnsembleAnswers {
+    name: string;
+    workDir: string;
+    lineup: string;
+}
+export interface CreateEnsembleState {
+    step: CreateEnsembleStep;
+    answers: CreateEnsembleAnswers;
+    error?: string;
+    submitting?: boolean;
+    prePhase: TuiPhase;
+}
+export declare const CREATE_ENSEMBLE_STEPS: CreateEnsembleStep[];
+export declare const DEFAULT_CREATE_ENSEMBLE_ANSWERS: CreateEnsembleAnswers;
+export interface TuiState {
+    phase: TuiPhase;
+    /** Current view in the navigation hierarchy. */
+    view: TuiView;
+    /** Error message when phase === 'error'. */
+    error?: string;
+    /** Splash screen status text. */
+    splashStatus: string;
+    /** Progressive checklist items shown during splash. */
+    splashChecks: Array<{
+        label: string;
+        done: boolean;
+        error?: boolean;
+    }>;
+    /** Whether the splash connection sequence is complete. */
+    splashConnected: boolean;
+    /** Summary info shown in splash after connection. */
+    splashSummary?: {
+        ensemble: string;
+        playerCount: number;
+        conductor?: string;
+        scheduleCount?: number;
+    };
+    /** Known ensembles (null = not yet loaded, [] = loaded but empty). */
+    ensembles: EnsembleSummary[] | null;
+    /** Currently highlighted ensemble index (home view). */
+    selectedEnsembleIndex: number;
+    /** The ensemble currently being viewed (null = home). */
+    activeEnsemble: string | null;
+    /** Players in the active ensemble. */
+    players: MaestroPlayerInfo[];
+    /** True after the first successful player poll. Reset on ensemble switch. */
+    playersLoaded: boolean;
+    /** Messages in the active ensemble (relay messages). */
+    messages: MaestroRelayMessage[];
+    /** Conductor history in the active ensemble. */
+    conductorHistory: HistoryEntry[];
+    /** Active schedules in the ensemble. */
+    schedules: ScheduleEntry[];
+    /** Maestro conversation (null = loading, [] = loaded but empty). */
+    conversation: ConversationEntry[] | null;
+    /** Aggregated ensemble chat feed (from maestroEnsembleChat query). */
+    ensembleChat: EnsembleChatMessage[];
+    /** Whether the active ensemble has a conductor. */
+    hasConductor: boolean;
+    /**
+     * Bug B: Whether the active ensemble's maestro hub is paused. Polled
+     * alongside players/chat. The conductor's session-level `paused` flag
+     * blocks outbox dispatch, so the TUI surfaces this in the status bar
+     * (`paused` segment) so users don't wonder why typed messages aren't
+     * getting a reply. Optimistically toggled by `/pause` and `/play`.
+     */
+    ensemblePaused: boolean;
+    /**
+     * #306 follow-up: Whether at least one session in the active ensemble
+     * has its outbox locked (`held`). Mirrors {@link ensemblePaused} —
+     * polled in the same 2s loop, reset on nav transitions, optimistically
+     * cleared by `/play` and `/go`. Drives the StatusBar `held` segment +
+     * the "Tip: type /go" hint pinned below the input.
+     *
+     * Independent of `ensemblePaused` because `/load_lineup` produces
+     * paused + held simultaneously, and resuming both requires `/play`
+     * AND `/go`. Without surfacing held separately, users got stuck
+     * unpausing an ensemble that still had every player frozen.
+     */
+    ensembleHeld: boolean;
+    /** Currently highlighted player index (ensemble view). */
+    selectedPlayerIndex: number;
+    /** The player currently being inspected (null = not viewing a player). */
+    activePlayer: string | null;
+    /** Player's workflow metadata. */
+    playerMetadata: SessionMetadata | null;
+    /** Player's message history (received + sent). */
+    playerMessages: Array<Message | (SentMessage & {
+        direction: 'sent';
+    })>;
+    /** Scroll offset within the player detail view message list. */
+    playerScrollOffset: number;
+    /** Committed scroll-up history items. */
+    staticItems: StaticItem[];
+    /**
+     * #306: Bottom-pinned ephemeral notifications — errors/warnings that must
+     * stay visible until dismissed rather than scrolling off the top. The
+     * renderer filters expired entries on every tick via a separate state
+     * counter so the auto-dismiss doesn't need a reducer pass.
+     */
+    notifications: NotificationItem[];
+    /**
+     * #306: Monotonic tick counter — bumped every 500ms by a root-level effect
+     * to force re-renders so expired notifications disappear without requiring
+     * a reducer action per expiration. Cheap — a single integer diff.
+     */
+    notificationTick: number;
+    /** Player name when in chat mode (bare text sends message to this target). */
+    chatTarget?: string;
+    /** Locally tracked sent messages (TUI has no workflow to query). */
+    sentMessages: Array<{
+        to: string;
+        text: string;
+        timestamp: string;
+    }>;
+    /** ID of the last message seen (for detecting new arrivals in polling). */
+    lastSeenMessageId?: string;
+    /** Player name pending destroy confirmation (PR-H renamed `/stop` → `/destroy`; field name kept for diff hygiene). */
+    confirmingStop?: string;
+    /** Optional `reason` carried from the `/destroy <player> [reason]` invocation. */
+    confirmingStopReason?: string;
+    /** Ensemble name pending disband confirmation (null = not confirming). */
+    confirmingDisband?: string;
+    /**
+     * Ensemble name pending `/destroy <ensemble>` typed-name confirmation.
+     * Distinct from `confirmingDisband` because the gate is typed-name rather
+     * than y/N.
+     */
+    confirmingEnsembleDestroy?: {
+        ensemble: string;
+        /** Current contents of the typed-confirmation input. */
+        input: string;
+        /** Mismatch error shown beneath the input; cleared on next keystroke. */
+        error?: string;
+        submitting?: boolean;
+    };
+    /** Lineup confirmation state (pending load). */
+    confirmingLineup?: {
+        action: 'load';
+        path: string;
+        summary: string;
+    };
+    /** Recruit wizard state (active when phase === 'recruit'). */
+    recruitState?: RecruitState;
+    /** Schedule creation wizard state (active when phase === 'schedule-create'). */
+    scheduleWizard?: ScheduleWizardState;
+    /** Create ensemble wizard state (active when phase === 'create-ensemble'). */
+    createEnsembleState?: CreateEnsembleState;
+    /**
+     * Home-view modal overlay. `undefined` = no modal. Restore carries the
+     * target ensemble + conductor name + parked player count so the
+     * confirmation body doesn't re-query the backend.
+     */
+    homeModal?: {
+        type: 'new';
+    } | {
+        type: 'lineup';
+    } | {
+        type: 'restore';
+        ensemble: string;
+        playerCount: number;
+        conductor?: string;
+    };
+    /** True while a home-view modal's submit handler is in flight. */
+    homeModalSubmitting?: boolean;
+    /** Error surfaced inside the active home modal (spawn failure, etc.). */
+    homeModalError?: string;
+    /** Status overlay visible (shows player list). */
+    statusOverlay: boolean;
+    /** Generic command overlay (title + pre-formatted content). Shown by data-display commands. */
+    /** Interactive overlay (schedules, gates, stages, worktrees, or generic command). */
+    overlay: {
+        type: string;
+        title: string;
+        items: Array<{
+            id: string;
+            label: string;
+            sublabel?: string;
+        }>;
+        selectedIndex: number;
+        hint: string;
+    } | null;
+    /** Scroll offset within the status overlay. */
+    statusScrollOffset: number;
+    /** Command palette state. */
+    paletteVisible: boolean;
+    paletteIndex: number;
+    /** Interactive picker overlay state. */
+    pickerVisible: boolean;
+    pickerType: 'players' | 'ensembles' | null;
+    pickerIntent: 'navigate' | null;
+    pickerIndex: number;
+    /** Optional status filter for player picker. */
+    pickerStatusFilter: string | null;
+}
+export declare function initialState(ensemble?: string): TuiState;
+export type TuiAction = {
+    type: 'SET_PHASE';
+    phase: TuiPhase;
+    error?: string;
+} | {
+    type: 'SET_SPLASH_STATUS';
+    status: string;
+} | {
+    type: 'SET_SPLASH_CHECKS';
+    checks: Array<{
+        label: string;
+        done: boolean;
+        error?: boolean;
+    }>;
+} | {
+    type: 'SET_SPLASH_CONNECTED';
+    summary?: TuiState['splashSummary'];
+} | {
+    type: 'NAVIGATE_HOME';
+} | {
+    type: 'NAVIGATE_ENSEMBLE';
+    ensemble: string;
+} | {
+    type: 'NAVIGATE_PLAYER';
+    playerId: string;
+} | {
+    type: 'REFRESH_ENSEMBLES';
+    ensembles: EnsembleSummary[];
+} | {
+    type: 'REFRESH_ENSEMBLE_DATA';
+    players: MaestroPlayerInfo[];
+    messages: MaestroRelayMessage[];
+    history: HistoryEntry[];
+    schedules?: ScheduleEntry[];
+} | {
+    type: 'SET_CONVERSATION';
+    conversation: ConversationEntry[];
+} | {
+    type: 'SET_ENSEMBLE_CHAT';
+    chat: EnsembleChatResult;
+}
+/** Append one new chat message — used by `event: chat.appended`. Updates `ensembleChat` and `conversation` together. */
+ | {
+    type: 'APPEND_CHAT_MESSAGE';
+    message: EnsembleChatMessage;
+}
+/**
+ * Insert or update a player by `playerId` — used by `event: player.added`.
+ *
+ * **Invariant**: `player` MUST be a complete `MaestroPlayerInfo` snapshot.
+ * The reducer's `{...existing, ...incoming}` merge will clobber any fields
+ * omitted from `incoming` with `undefined`. For sparse updates (e.g.
+ * `phase`-only), use `PATCH_PLAYER_PHASE` (introduced for #351) — extend
+ * that pattern to other fields rather than passing partial payloads here.
+ */
+ | {
+    type: 'UPSERT_PLAYER';
+    player: MaestroPlayerInfo;
+}
+/**
+ * Patch only the `phase` field of an existing player — used by
+ * `event: player.phase_changed`. The wire payload for that event is
+ * deliberately sparse (only `playerId`, `ensemble`, `phase`, plus a
+ * couple of optional timestamps); routing through `UPSERT_PLAYER`
+ * would force the handler to fill `hostname`/`part`/`isConductor`
+ * with empty defaults, and the reducer's `{...existing, ...incoming}`
+ * spread would then clobber the real values cached from the snapshot.
+ * Phase-only patching keeps the rest of the row intact. See #351.
+ */
+ | {
+    type: 'PATCH_PLAYER_PHASE';
+    playerId: string;
+    phase: AttachmentPhase;
+}
+/** Remove a player by `playerId` — used by `event: player.removed`. */
+ | {
+    type: 'REMOVE_PLAYER';
+    playerId: string;
+}
+/** Replace the schedules slice — used by `event: schedules.changed`. */
+ | {
+    type: 'SET_SCHEDULES';
+    schedules: ScheduleEntry[];
+} | {
+    type: 'REFRESH_PLAYER_DATA';
+    metadata: SessionMetadata | null;
+    messages: Array<Message | (SentMessage & {
+        direction: 'sent';
+    })>;
+} | {
+    type: 'PLAYER_SCROLL_UP';
+} | {
+    type: 'PLAYER_SCROLL_DOWN';
+} | {
+    type: 'COMMIT_STATIC';
+    item: StaticItem;
+} | {
+    type: 'ADD_NOTIFICATION';
+    notification: NotificationItem;
+} | {
+    type: 'DISMISS_NOTIFICATION';
+    id: number;
+} | {
+    type: 'DISMISS_OLDEST_NOTIFICATION';
+} | {
+    type: 'CLEAR_NOTIFICATIONS';
+} | {
+    type: 'NOTIFICATION_TICK';
+} | {
+    type: 'SET_ENSEMBLE_PAUSED';
+    paused: boolean;
+} | {
+    type: 'SET_ENSEMBLE_HELD';
+    held: boolean;
+} | {
+    type: 'APPEND_SENT_MESSAGE';
+    to: string;
+    text: string;
+} | {
+    type: 'HYDRATE_SENT_MESSAGES';
+    messages: Array<{
+        to: string;
+        text: string;
+        timestamp: string;
+    }>;
+} | {
+    type: 'ENTER_CHAT';
+    target: string;
+} | {
+    type: 'EXIT_CHAT';
+} | {
+    type: 'SHOW_PALETTE';
+} | {
+    type: 'HIDE_PALETTE';
+} | {
+    type: 'PALETTE_UP';
+} | {
+    type: 'PALETTE_DOWN';
+    max?: number;
+} | {
+    type: 'PALETTE_SET_INDEX';
+    index: number;
+} | {
+    type: 'SHOW_STATUS';
+} | {
+    type: 'HIDE_STATUS';
+} | {
+    type: 'SHOW_COMMAND_OVERLAY';
+    title: string;
+    content: string;
+} | {
+    type: 'SHOW_OVERLAY';
+    overlay: {
+        type: string;
+        title: string;
+        items: Array<{
+            id: string;
+            label: string;
+            sublabel?: string;
+        }>;
+        hint: string;
+    };
+} | {
+    type: 'HIDE_OVERLAY';
+} | {
+    type: 'OVERLAY_SELECT';
+    direction: 'up' | 'down';
+} | {
+    type: 'STATUS_SCROLL_UP';
+} | {
+    type: 'STATUS_SCROLL_DOWN';
+} | {
+    type: 'SHOW_PICKER';
+    pickerType: 'players' | 'ensembles';
+    intent?: 'navigate';
+    statusFilter?: string;
+} | {
+    type: 'HIDE_PICKER';
+} | {
+    type: 'PICKER_UP';
+} | {
+    type: 'PICKER_DOWN';
+} | {
+    type: 'CONFIRM_STOP';
+    player: string;
+    reason?: string;
+} | {
+    type: 'CANCEL_STOP';
+} | {
+    type: 'CONFIRM_DISBAND';
+    ensemble: string;
+} | {
+    type: 'CANCEL_DISBAND';
+} | {
+    type: 'CONFIRM_ENSEMBLE_DESTROY';
+    ensemble: string;
+} | {
+    type: 'ENSEMBLE_DESTROY_INPUT';
+    input: string;
+} | {
+    type: 'ENSEMBLE_DESTROY_SUBMIT_BUSY';
+} | {
+    type: 'ENSEMBLE_DESTROY_MISMATCH';
+} | {
+    type: 'CANCEL_ENSEMBLE_DESTROY';
+} | {
+    type: 'CONFIRM_LINEUP';
+    action: 'load';
+    path: string;
+    summary: string;
+} | {
+    type: 'CANCEL_LINEUP';
+} | {
+    type: 'ENTER_RECRUIT';
+    answers?: Partial<RecruitAnswers>;
+    defaultAgent?: 'claude' | 'copilot';
+} | {
+    type: 'RECRUIT_NEXT_STEP';
+    answer: Partial<RecruitAnswers>;
+} | {
+    type: 'RECRUIT_PREV_STEP';
+} | {
+    type: 'RECRUIT_SUBMIT';
+} | {
+    type: 'RECRUIT_DONE';
+    error?: string;
+} | {
+    type: 'EXIT_RECRUIT';
+} | {
+    type: 'ENTER_SCHEDULE_WIZARD';
+    answers?: Partial<ScheduleAnswers>;
+} | {
+    type: 'SCHEDULE_NEXT_STEP';
+    answer: Partial<ScheduleAnswers>;
+} | {
+    type: 'SCHEDULE_PREV_STEP';
+} | {
+    type: 'SCHEDULE_SUBMIT';
+} | {
+    type: 'SCHEDULE_DONE';
+    error?: string;
+} | {
+    type: 'EXIT_SCHEDULE_WIZARD';
+} | {
+    type: 'ENTER_CREATE_ENSEMBLE';
+} | {
+    type: 'CREATE_ENSEMBLE_NEXT_STEP';
+    answer: Partial<CreateEnsembleAnswers>;
+} | {
+    type: 'CREATE_ENSEMBLE_PREV_STEP';
+} | {
+    type: 'CREATE_ENSEMBLE_SUBMIT';
+} | {
+    type: 'CREATE_ENSEMBLE_DONE';
+    error?: string;
+    ensemble?: string;
+} | {
+    type: 'EXIT_CREATE_ENSEMBLE';
+} | {
+    type: 'OPEN_HOME_MODAL';
+    modal: NonNullable<TuiState['homeModal']>;
+} | {
+    type: 'CLOSE_HOME_MODAL';
+} | {
+    type: 'SET_HOME_MODAL_STATUS';
+    submitting?: boolean;
+    error?: string;
+};
+export declare function tuiReducer(state: TuiState, action: TuiAction): TuiState;