@north-light/api 0.3.580 → 0.3.588

package/dist/clients/attach/render/chat-view.d.ts

@@ -0,0 +1,409 @@
+import { Container, Loader, type Component, type TUI } from '@earendil-works/pi-tui';
+import { type AgentSessionEvent } from '@earendil-works/pi-coding-agent';
+import type { BrokerSnapshot } from '../../../core/runtime/broker-protocol.js';
+import { type AttachPalette } from '../config.js';
+import { type ToolGroupSummary } from '../../../shared/tool-groups.js';
+import { type TurnReply } from '../../../shared/turn-replies.js';
+import { type ViewportSource } from './measured-container.js';
+import type { CondensedHistoryMode } from '../../../types.js';
+export type ToolDisplayToggle = {
+    kind: 'summaries';
+    shown: boolean;
+} | {
+    kind: 'output';
+    expanded: boolean;
+};
+export type CopyBlockKind = 'user' | 'assistant' | 'tool' | 'condensed';
+/** One copyable unit, bound to the exact top-level component the viewport addresses. */
+export interface CopyBlock {
+    block: Component;
+    kind: CopyBlockKind;
+    text: string;
+}
+export interface ChatViewOptions {
+    /** Working dir used by `ToolExecutionComponent` for path/diff display. Defaults
+     *  to the viewer's cwd; T7 may pass the node's working dir for nicer paths. */
+    cwd?: string;
+    /** Render inline images in tool output (terminal-dependent). Default true. */
+    showImages?: boolean;
+    /** Inline image width in cells. Default 60 (pi's default). */
+    imageWidthCells?: number;
+    /** Collapse the assistant thinking block. Default false. */
+    hideThinking?: boolean;
+    /** Label shown for a hidden thinking block. Default "Thinking...". */
+    hiddenThinkingLabel?: string;
+    /** Start tool output expanded. Default false. */
+    toolOutputExpanded?: boolean;
+    /** Sink for footer/header-only events ChatView does not itself render
+     *  (queue_update, session_info_changed, thinking_level_changed). The attach
+     *  command wires a footer here; absent → these events are no-ops. */
+    onFooterEvent?: (event: AgentSessionEvent) => void;
+    /** Theme palette for the activity spinner / dim status / error lines. Absent →
+     *  the module defaults (faint + ANSI red) are used. */
+    palette?: AttachPalette;
+    /** Viewer-owned fixed activity slot. When supplied, activity stays outside
+     *  the scrolling transcript and this callback swaps its sole loader. */
+    onActivityChange?: (loader: Loader | undefined) => void;
+    /** Trailing refresh-yield cycles rendered at full fidelity; older cycles are
+     *  condensed to lightweight, reflowing content (see condensed-history.ts).
+     *  Absent → the user's `live_cycles` config setting, itself defaulting to 2. */
+    liveCycles?: number;
+    /** Which messages of a condensed cycle survive into the condensed region.
+     *  Absent → the user's `condensed_history` config setting, itself defaulting
+     *  to `none` (cycle dividers only). */
+    condensedHistory?: CondensedHistoryMode;
+    /** Render an inline page sent by THIS node as a durable transcript block,
+     *  anchored after the `human send` that raised it. Local attach only: a remote
+     *  viewer cannot read the ticket directory the block renders from. */
+    inlinePageBlocks?: boolean;
+    /** How the person opens their inbox on this surface, resolved lazily because
+     *  bindings are resolved after ChatView is constructed. */
+    pageOpenHint?: () => string;
+    /** How the person hands a still-running bash command to the background on this
+     *  surface, resolved lazily for the same reason. Null when this viewer cannot
+     *  invoke the handoff at all, which suppresses the row. */
+    backgroundBashHint?: () => string | null;
+    /** Pre-colored banner lines pinned as the FIRST child of the chat container,
+     *  above history (the crouton wordmark). Sits at the very top of the transcript
+     *  and scrolls up into scrollback as the chat grows. Absent → no banner. */
+    banner?: ReadonlyArray<string>;
+}
+export declare class ChatView {
+    private readonly tui;
+    /** The chat scroll area handed in by the attach command. */
+    private readonly container;
+    /** Settled history is cached independently from the live status area so picker
+     *  navigation does not re-render a long conversation on every key repeat. */
+    private readonly historyContainer;
+    /** Standalone ChatViews render activity inline; the attach viewer supplies
+     *  `onActivityChange`, so its transcript excludes this container. */
+    private readonly statusContainer;
+    /** Optional banner, above history and status in the viewport's flat source. */
+    private readonly bannerContainer;
+    private readonly transcript;
+    /** Where `append()` puts a component. Normally `historyContainer`; retargeted to
+     *  a nested container while condensed history is being built, so the same
+     *  message-rendering path serves both regions. */
+    private appendTarget;
+    /** Inline page blocks placed in this transcript, by page id — one block per
+     *  page, so a `--replace` revision refreshes the block already on screen. */
+    private readonly pageBlocks;
+    /** The person's inbox answers in the live region, each with its leading
+     *  spacer. Summary mode hides them with the settled pages they answer. */
+    private readonly inboxAnswers;
+    private readonly inlinePageBlocks;
+    private readonly pageOpenHint;
+    private readonly backgroundBashHint;
+    /** Trailing cycles kept at full fidelity (config `live_cycles`). */
+    private readonly liveCycles;
+    /** Messages kept from a condensed cycle (config `condensed_history`). */
+    private readonly condensedHistory;
+    private readonly cwd;
+    private readonly showImages;
+    private readonly imageWidthCells;
+    private hideThinking;
+    private readonly hiddenThinkingLabel;
+    /** Ctrl+O: pi's two-state tool-output expansion. */
+    private toolOutputExpanded;
+    /** The view setting (Alt+C → z → f): fold every SETTLED tool call to its single
+     *  call line. Independent of `toolOutputExpanded` — it survives an expand/collapse
+     *  and only ever applies to tool calls that are done. */
+    private foldSettledTools;
+    /** Summary mode only changes Ctrl+O when both persistent settings are on. */
+    private readonly summarizeToolCalls;
+    private readonly detailedToolRecaps;
+    private showGroupSummaries;
+    /** Groups exist only while building/rendering the full-fidelity live region. */
+    private readonly groups;
+    private openGroup;
+    /** Consolidated replies (`consolidate_replies`), read once per attach. */
+    private readonly consolidateReplies;
+    /** `/show-working`: expand every turn's working. Viewer-local, not persisted. */
+    private showWorking;
+    private readonly turnReplies;
+    private readonly turns;
+    private openReplyTurn;
+    /** The turn the live region opens in when it begins mid-turn (the condensed
+     * region held its person's message), else the pre-message `start` turn. */
+    private carriedTurn;
+    /** >0 while appending components that never join a turn (the person's
+     * message, turn chrome, errors, condensed history). */
+    private outsideTurns;
+    /** Components the turn fold currently hides. */
+    private turnHidden;
+    private readonly groupSummaries;
+    /** Node id → display name for every node spawned in this transcript, so a
+     *  later group's finish notice can name the child rather than its id. */
+    private readonly nodeRoster;
+    private streamingWasGroupMember;
+    private readonly onFooterEvent;
+    /** Viewer hook that places activity in its fixed slot, when available. */
+    private readonly onActivityChange;
+    /** Theme-derived colorizers for the activity/status area. */
+    private readonly spinnerStyle;
+    private readonly dimStyle;
+    private readonly errorStyle;
+    /** Palette shared with recap rows that render outside pi tool callbacks. */
+    private readonly recapPalette;
+    /** Bold accent for the expanded crtr-context label. */
+    private readonly labelStyle;
+    /** Viewer-local Markdown projection, handed to pi's message components so
+     *  THEY apply it at render time with the exact content width. The viewer keeps
+     *  no projected copy: the components hold canonical source, and each
+     *  transformer reads live viewer state on every call. Diagrams apply only to
+     *  assistant-authored Markdown. */
+    private readonly markdownTransformers;
+    /** The assistant message component currently being streamed (between
+     *  message_start and message_end for an assistant turn). */
+    private streamingComponent;
+    /** The separator immediately after the live assistant component. It becomes
+     *  visible when that response has visible prose or thinking and folded tools. */
+    private streamingToolSeparator;
+    /** Content classes for each separator, so Ctrl+T can add/remove thinking gaps
+     * without rebuilding the transcript. */
+    private readonly foldedToolSeparatorContents;
+    /** Tool-call id → its execution component, for the duration of the call. */
+    private readonly pendingTools;
+    /** The `!` bash component currently streaming (between bash_start and bash_end). */
+    private bashComponent;
+    /** The single active activity loader (working/compaction/retry), if any. */
+    private activityLoader;
+    /** The shared broker transcript state; this renderer projects it into pi TUI
+     *  components while retaining terminal-only folding and virtualization. */
+    private projection;
+    /** Broker-selected normal label for this turn; compaction/retry temporarily
+     *  replace it and restore it when the run remains active. */
+    private workingActivity;
+    private runActive;
+    /** True while applySnapshot is mid-build; live broker frames defer instead of
+     *  mutating the partially-rebuilt view. */
+    private applyingSnapshot;
+    /** Bumped on every applySnapshot. A build suspended at a yield compares this
+     *  after resuming and abandons itself when a newer welcome has bumped it, so
+     *  the newest welcome wins and stale state never overwrites the live view. */
+    private snapshotGeneration;
+    /** Live frames captured during an in-flight build (bound closures that re-run
+     *  the original entry point), replayed in order when the build completes and
+     *  dropped when a newer welcome supersedes the build. */
+    private readonly deferredFrames;
+    /** Text of the most recent assistant message, kept current from the welcome
+     *  snapshot AND the live event stream so `/copy` (getLastAssistantText) works
+     *  whether the message arrived before or after attach. */
+    private lastAssistantText;
+    /** Existing file paths found anywhere in the rendered transcript, newest first. */
+    private readonly transcriptFilePaths;
+    /** `[[ref]]` document references from the transcript, newest first. */
+    private readonly transcriptDocRefs;
+    /** Canonical copyable transcript blocks, in their rendered visual order. */
+    private readonly copyBlockRecords;
+    private readonly copyIndex;
+    /** Registrations made while building condensed history are collapsed onto its
+     * outer container once that container becomes a top-level viewport block. */
+    private readonly condensedCopyBlocks;
+    constructor(tui: TUI, container: Container, opts?: ChatViewOptions);
+    /** The transcript as one flat ordered block list for the viewport. */
+    transcriptSource(): ViewportSource;
+    /** Render the full message history from a `welcome` snapshot. Ports pi's
+     *  `renderSessionContext` (interactive-mode.js:2553): assistant messages spawn
+     *  tool-execution components matched to their toolResult messages; everything
+     *  else routes through `addMessageToChat`. The TUI's differential renderer +
+     *  reflow-on-resize is automatic — no scrollback reconstruction needed. */
+    applySnapshot(snapshot: BrokerSnapshot): Promise<void>;
+    /**
+     * Build the condensed form of the already-finished cycles as a nested component
+     * container, or return undefined when nothing survives condensation.
+     *
+     * Reuses `addMessageToChat` by retargeting `append()` at the nested container, so
+     * condensed history uses the same renderer as live history with tool traffic
+     * filtered out. The outer history cache keeps stable-width frames cheap, while
+     * preserving the components lets pane-width changes reflow their content. The
+     * build yields on the live cadence and abandons itself when a newer welcome
+     * supersedes this generation.
+     */
+    private buildCondensedBlock;
+    /** Consolidated replies in condensed history: each finished turn renders as
+     * the person's message, its reply, then any cycle dividers it spanned. A turn
+     * still open at the end continues into the live region, so it is carried there
+     * instead of rendered. Returns false when a newer welcome superseded the build. */
+    private buildCondensedTurns;
+    /** Defer a live broker frame when a snapshot build is in flight. Returns true
+     *  (and enqueues the replay closure) while building so the caller returns
+     *  without mutating the half-rebuilt view; false when the caller may proceed.
+     *  This is the single-writer gate every live-frame entry point passes through. */
+    private deferIfBuilding;
+    /** Replay deferred live frames in wire order. The gate is already open, so each
+     *  closure re-enters its entry point and dispatches immediately. */
+    private replayDeferredFrames;
+    /** Apply the broker's random choice for a newly received user message. */
+    setWorkingActivity(activity: string): void;
+    /** Clear live turn state after the broker reports completion or the viewer observes dormancy. */
+    settleRun(): void;
+    /** Stop any spinning activity loader. A one-shot `crtr surface attach` process lets its
+     *  timers die with the process, but if T7 reuses a ChatView across reconnects in
+     *  one process it should call this on detach to avoid a leaked interval. */
+    dispose(): void;
+    /** Ctrl+O prefers summaries when the user enabled both folding and summary
+     * generation. */
+    toggleToolsExpanded(): ToolDisplayToggle;
+    /** The `fold finished tool calls` view setting (`/fold-tools`, Alt+C → z → f).
+     *  Returns the new state so the caller can surface a notice. */
+    toggleFoldSettledTools(): boolean;
+    /** Push both display settings onto every rendered component. A tool call still in
+     *  flight is never hidden or minimized. Only a settled group with a broker-known
+     *  summary collapses; incomplete/failed generation leaves its folded call lines. */
+    private applyToolDisplay;
+    /** Summary mode hides the back-and-forth with the person: every settled
+     *  inline page and every answer they gave from their inbox. A page still
+     *  awaiting an answer stays on screen. */
+    private hidesInboxExchange;
+    private applyInboxExchangeDisplay;
+    /** `/show-working` (Alt+C → z → w): expand or fold the working behind every
+     *  consolidated reply. Returns the new state, or null when the
+     *  `consolidate_replies` experiment is off for this attach. */
+    toggleShowWorking(): boolean | null;
+    /** A broker rewrite landed for one turn. Stored first: it may precede the
+     *  turn's events, and snapshot rebuilds defer it through the writer gate. */
+    applyTurnReply(key: string, reply: TurnReply): void;
+    /** Every turn member the fold hides right now. The live turn keeps what is
+     *  still in motion — the streaming message and in-flight tools — visible
+     *  below its working row. */
+    private turnFoldedComponents;
+    private beginTurn;
+    /** Whether an append in progress lands in the live region of a consolidating view. */
+    private consolidatingHere;
+    private currentTurn;
+    /** A settled assistant message with prose becomes part of its turn's reply. */
+    private recordTurnProse;
+    /** Re-render one turn's reply from its prose and the broker's latest rewrite. */
+    private refreshTurn;
+    private refreshWorkingRow;
+    private replyMessage;
+    /** Ctrl+T / app.thinking.toggle — flip thinking-block visibility and apply it to
+     *  every assistant message (the in-flight streaming bubble is itself a child of
+     *  the container, so the loop covers it too). Returns the new HIDDEN state. */
+    toggleThinking(): boolean;
+    handleEvent(event: AgentSessionEvent): void;
+    bashStart(command: string, excludeFromContext?: boolean): void;
+    bashOutput(chunk: string): void;
+    bashEnd(result: {
+        exitCode: number | undefined;
+        cancelled: boolean;
+        truncated: boolean;
+        fullOutputPath?: string;
+    }): void;
+    private addMessageToChat;
+    private appendUserMessage;
+    /** Render an assistant reply plus its initially-hidden boundary separator.
+     *  A turn that ended on its own abort is rendered as the interrupt it is,
+     *  matching the live seam above, so re-reading the transcript later never
+     *  turns a healthy interrupt into a red `Error:` line. */
+    private appendAssistantMessage;
+    /** Add a separator in transcript order now; it renders only after a following
+     * tool settles in the folded view. */
+    private appendAssistantSeparator;
+    private appendAssistantPart;
+    private appendUserPart;
+    /** An answer the person typed in their inbox renders exactly like a message
+     * they typed here, and closes the run around it the same way. */
+    private appendHumanAnswer;
+    private appendHumanAnswerParts;
+    private trackInboxAnswer;
+    /** Only the full-fidelity trailing region gets summary groups. Condensed
+     * history intentionally drops tool traffic, so grouping there would create
+     * phantom summary rows and cross the live/condensed boundary. */
+    private isLiveGroupRegion;
+    private ensureGroup;
+    private closeOpenGroup;
+    private appendGroupMember;
+    private removeGroupMember;
+    /** Add one tool as a group member, moving the assistant's boundary separator
+     * behind the new summary row without changing the separator's identity. */
+    private appendToolComponent;
+    private noteGroupTool;
+    private settleGroupTool;
+    /** An assistant starts as a non-boundary while its text is empty. Visible prose
+     * or a terminal failure turns it into a boundary without recreating either
+     * pi-owned component (their direct-child cache identities remain intact). */
+    private promoteStreamingAssistantToBoundary;
+    private seedToolGroupSummaries;
+    /** Broker frames can arrive before or after their group's events, and snapshot
+     * rebuilding defers them through the single-writer gate, so this stores first
+     * and applies to every currently-rendered matching group. */
+    applyToolGroupSummary(key: string, summary: ToolGroupSummary): void;
+    private applyGroupDisplay;
+    /** Make each separator visible only if its immediately-following tool call is
+     * actually folded; in-flight calls remain flush with their live output. */
+    private updateFoldedToolSeparators;
+    /** Track whether an assistant response contains prose or thinking, then make
+     * its separator eligible only for content the current Ctrl+T setting shows. */
+    private setAssistantSeparatorContent;
+    /** Tool component with native viewer renderers for crouter-owned tool output. */
+    private makeToolComponent;
+    /** Append conversation content above the independent live status area — or into
+     *  the nested container while condensed history is under construction. */
+    private append;
+    /** Number of rendered conversation components in the container currently being
+     *  appended to (live history or the nested condensed region). */
+    private chatChildCount;
+    /** Clear all chat content. */
+    private resetChat;
+    /** Place the transcript block for an inline page a `human send` just raised.
+     *  The block is a plain history child, NOT a tool-group member: collapsing the
+     *  tool group folds the command away and leaves the page itself on screen, the
+     *  way assistant prose stays. Condensed history is skipped deliberately — old
+     *  cycles keep only prose and cycle seams. */
+    private maybeAppendPageBlock;
+    private loadPageBlock;
+    /** Re-measure the tool calls still in flight. A silent long-running command
+     *  emits no tool-execution update, so nothing else would evict its cached
+     *  lines and its backgrounding hint would never appear. Driven by the
+     *  viewer's existing low-rate chrome poll, and cheap because it touches only
+     *  in-flight tools — usually one, never the transcript. */
+    refreshInFlightTools(): void;
+    /** Re-read every placed page through the daemon. Driven by the viewer's
+     *  ticket-activity watcher, so an answer, a cancellation, or a `--replace`
+     *  revision lands on the block already anchored in the transcript. */
+    refreshPageBlocks(): Promise<void>;
+    private makeLoader;
+    /** Let a self-updating history child invalidate only its own cached lines. */
+    private componentTui;
+    /** Complete and release the live bash component before ChatView gives up ownership. */
+    private settleBashComponent;
+    /** Swap the single active activity indicator (working/compaction/retry). */
+    private setActivity;
+    private showStatus;
+    /** Append an error to the transcript. pi's own error events land here, and so
+     *  do the broker's `error` frames: their text is the engine's own and is
+     *  routinely multi-line (pi's login help is three lines), which the one-row
+     *  status notice cannot show. */
+    showError(message: string): void;
+    private crtrOutputTheme;
+    /** Extract the tool-call content items from an assistant message. */
+    private assistantToolCalls;
+    /** Existing file paths from the rendered transcript, newest first. */
+    getTranscriptFilePathsNewestFirst(): string[];
+    /** `[[ref]]` document references from the transcript, newest first, deduped. */
+    getTranscriptDocRefsNewestFirst(): string[];
+    /** Re-run every Markdown transform: a document link's rendered target changed. */
+    refreshMarkdown(): void;
+    /** The text of the most recent assistant message, for `/copy`. Undefined when
+     *  no assistant message has been seen (or it had no text content). */
+    getLastAssistantText(): string | undefined;
+    /** Copyable source text for a transcript block, if it has any. */
+    blockText(block: Component): string | undefined;
+    /** The canonical ordered copy record, oldest → newest. */
+    copyBlocks(): readonly CopyBlock[];
+    /** Newest tool call's result text (`/copy-tool`). */
+    getLastToolOutputText(): string | undefined;
+    /** Every copyable block's text, oldest → newest, joined by blank lines. */
+    getTranscriptPlainText(): string;
+    private registerCopyBlock;
+    private unregisterCopyBlock;
+    private appendCondensedBlock;
+    /** Flatten arbitrary tool result payloads into the visible text copy target. */
+    private toolResultText;
+    private pushTranscriptText;
+    private pushTranscriptValue;
+    /** Concatenate the text blocks of a user message (string or content array). */
+    private userMessageText;
+}