@haywoodmarx/agent-pager 0.1.0

package/dist/src/tui/model.d.ts

@@ -0,0 +1,414 @@
+import { type OperatorAgentHealth } from "../operator/agent-projection.js";
+import { type OperatorCommandEnvelope, type OperatorCommandResult, type OperatorCursor, type OperatorDiagnostic, type OperatorSnapshot, type OperatorTraffic } from "../operator/protocol.js";
+import type { AgentId } from "../broker/protocol.js";
+/** A renderer-neutral terminal pane. */
+export type TuiPane = "tree" | "agent_log" | "message_log";
+/** A local selection without granting broker authority. */
+export type TuiSelection = {
+    kind: "workspace";
+    repositoryId: string;
+} | {
+    kind: "archived";
+    repositoryId: string;
+} | {
+    kind: "agent";
+    agentId: AgentId;
+} | {
+    kind: "hidden";
+} | null;
+/** A local overlay. */
+export type TuiOverlay = {
+    kind: "none";
+} | {
+    kind: "agent_identity";
+    agentId: AgentId;
+} | {
+    kind: "full_message";
+    messageId: string;
+} | {
+    kind: "context_menu";
+    target: "agent";
+    agentId: AgentId;
+} | {
+    kind: "context_menu";
+    target: "message";
+    messageId: string;
+} | {
+    kind: "context_menu";
+    target: "workspace";
+    repositoryId: string;
+} | {
+    kind: "archive_confirm";
+    agentId: AgentId;
+} | {
+    kind: "expire_confirm";
+    messageId: string;
+} | {
+    kind: "actions";
+} | {
+    kind: "action_run";
+    actionId: string;
+} | {
+    kind: "help";
+} | {
+    kind: "log";
+};
+/** Local operator state kept outside authoritative broker facts. */
+export type TuiOperatorViewState = {
+    focus: TuiPane;
+    selection: TuiSelection;
+    /** Traffic row the agent log has selected; the message log reads its delivery through it. */
+    trafficId: string | null;
+    collapsedRepositories: ReadonlySet<string>;
+    /** Repositories the operator put out of sight, shown only in the hidden section. */
+    hiddenRepositories: ReadonlySet<string>;
+    /** Whether the hidden section is open; it starts closed and keeps the operator's choice while the section is absent. */
+    hiddenExpanded: boolean;
+    /**
+     * What the operator asked of each archive section they have touched.
+     *
+     * One entry per repository, so a section cannot be recorded as both opened and closed. A section with
+     * no entry takes the default its workspace implies, and an entry is kept only where the operator's
+     * choice departed from that default when they made it.
+     */
+    archivedSections: ReadonlyMap<string, "open" | "closed">;
+    followAgentLog: boolean;
+    /** Columns the operator dragged the tree pane to, or null while it keeps its default width. */
+    treeColumns: number | null;
+    /** Columns the operator dragged the message-log pane to, or null while it keeps its default. */
+    messageLogColumns: number | null;
+    overlay: TuiOverlay;
+    overlayReturnFocus: TuiPane;
+    contextActionIndex: number;
+    actionIndex: number;
+};
+/** Complete renderer-neutral state exposed by the controller. */
+export type TuiOperatorModelState = {
+    snapshot: OperatorSnapshot | null;
+    view: TuiOperatorViewState;
+    unreadMessageIds: ReadonlySet<string>;
+    healthByAgentId: ReadonlyMap<string, OperatorAgentHealth>;
+    connection: "cold" | "healthy" | "recovering" | "incompatible" | "disposed";
+    diagnostics: readonly OperatorDiagnostic[];
+    run: TuiLocalRun | null;
+};
+/** Fetches a complete snapshot without choosing a transport; the model validates the result. */
+export interface TuiSnapshotPort {
+    fetch(): TuiRequest<unknown>;
+}
+/** Opens an ordered event stream after a cursor. */
+export interface TuiStreamPort {
+    open(cursor: OperatorCursor | null, receive: (observation: TuiStreamObservation) => void, unavailable: () => void): () => void;
+}
+/**
+ * One transport observation delivered through the model-owned stream generation.
+ *
+ * A snapshot arrives already validated; an event payload is validated by the model.
+ */
+export type TuiStreamObservation = {
+    readonly type: "event";
+    readonly event: unknown;
+} | {
+    readonly type: "snapshot";
+    readonly snapshot: OperatorSnapshot;
+    readonly replacement: boolean;
+} | {
+    readonly type: "resync";
+} | {
+    readonly type: "incompatible";
+} | {
+    readonly type: "diagnostic";
+    readonly diagnostic: OperatorDiagnostic;
+} | {
+    readonly type: "live";
+} | {
+    readonly type: "resync_pending";
+} | {
+    readonly type: "resync_progress";
+};
+/** Resets the transport client, so the `fetch` or `open` that follows it connects. */
+export interface TuiReconnectPort {
+    reconnect(): void;
+}
+/** Submits an operator command without making it a local fact. */
+export interface TuiCommandPort {
+    execute(command: OperatorCommandEnvelope): TuiRequest<OperatorCommandResult>;
+}
+/** Cancellable work owned by the long-lived TUI model. */
+export type TuiRequest<Value> = {
+    promise: Promise<Value>;
+    cancel(): void;
+};
+/** Reports what one local command run has produced so far. */
+export type TuiLocalRun = {
+    /** Identity of this attempt, so a repeat is not mistaken for a continuation of the one before it. */
+    readonly id: number;
+    /** Command line shown to the operator, exactly as it was executed. */
+    readonly command: string;
+    /**
+     * Raw terminal bytes the command has written, oldest first. Whole chunks are dropped from the front
+     * once the total passes `TUI_RUN_OUTPUT_BYTE_LIMIT`, but the newest chunk is always kept.
+     *
+     * Kept unparsed because the child drives a terminal rather than printing lines: only an emulator can
+     * say what the screen now holds. Replaying the whole sequence reconstructs that screen, so a view
+     * that mounts late is not left blank.
+     */
+    readonly chunks: readonly Uint8Array[];
+    /**
+     * Count of chunks ever received, including those since dropped.
+     *
+     * A consumer writing chunks somewhere incrementally cannot use an index into `chunks`, which shifts
+     * under it as the buffer drops its oldest. This only ever grows.
+     */
+    readonly received: number;
+    /** Reports whether output was dropped because the buffer filled. */
+    readonly truncated: boolean;
+    /** Reports where the run has got to, and what it ended with once it has ended. */
+    readonly outcome: TuiLocalRunOutcome;
+};
+/** Where one local command run has got to. */
+export type TuiLocalRunOutcome = {
+    readonly kind: "running";
+} | {
+    readonly kind: "exited";
+    readonly code: number;
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+} | {
+    readonly kind: "cancelled";
+};
+/** Bytes a run's replay buffer keeps before it drops its oldest chunks. */
+export declare const TUI_RUN_OUTPUT_BYTE_LIMIT: number;
+/**
+ * Runs one local command on the operator's machine and reports its output as it arrives.
+ *
+ * Separate from `TuiCommandPort`, which submits an operator command to the broker. This one leaves
+ * the process entirely.
+ */
+export interface TuiLocalCommandPort {
+    /**
+     * Start one command attached to a terminal, reporting its bytes and the status it ends with.
+     *
+     * The exit is reported only once the child's terminal has reached end of file, so it can arrive
+     * after the child itself has exited. Output still unread when the session is stopped is discarded.
+     * @param command - Executable to run.
+     * @param args - Arguments passed to the executable.
+     * @param size - Terminal dimensions the child lays its output out for.
+     * @param observe - Receives each output chunk, then exactly one terminal outcome.
+     * @returns - Handle for writing to the child, or null when it never started.
+     */
+    run(command: string, args: readonly string[], size: TuiLocalRunSize, observe: (event: {
+        type: "output";
+        bytes: Uint8Array;
+    } | {
+        type: "exit";
+        code: number;
+    } | {
+        type: "failed";
+        reason: string;
+    }) => void): TuiLocalCommandSession | null;
+}
+/** Dimensions a child is told its terminal has, so its output fits where the operator will read it. */
+export type TuiLocalRunSize = {
+    /** Columns the child lays out to. */
+    readonly columns: number;
+    /** Rows the child lays out to. */
+    readonly rows: number;
+};
+/** Writes to a running child's terminal. */
+export interface TuiLocalCommandSession {
+    /**
+     * Send operator input to the child, already encoded for a terminal.
+     * @param bytes - Sequence the child reads from its standard input.
+     */
+    write(bytes: Uint8Array): void;
+    /**
+     * Tell the child its terminal has a new size, so it lays its output out again.
+     * @param columns - Columns the child now has.
+     * @param rows - Rows the child now has.
+     */
+    resize(columns: number, rows: number): void;
+    /**
+     * End the child and release its terminal.
+     *
+     * The operator can leave while a child is still writing, and a child of a terminal nobody reads
+     * would hold its process and its file descriptor for as long as it chose to run.
+     */
+    stop(): void;
+}
+/** Schedules controller-owned recovery work after a caller-chosen delay. */
+export interface TuiSchedulerPort {
+    schedule(callback: () => void, delayMs: number): () => void;
+}
+/** Releases composition-owned resources exactly once. */
+export interface TuiDisposalPort {
+    dispose(): void;
+}
+/** Explicit dependencies selected by the TUI composition root. */
+export type TuiOperatorModelDependencies = {
+    snapshot: TuiSnapshotPort;
+    stream: TuiStreamPort;
+    reconnect: TuiReconnectPort;
+    command: TuiCommandPort;
+    localCommand?: TuiLocalCommandPort;
+    scheduler: TuiSchedulerPort;
+    disposal: TuiDisposalPort;
+    layout?: TuiLayoutPort;
+    /** Current time in epoch milliseconds, for client diagnostics and the replacement wait's time limit. */
+    now: () => number;
+};
+/** Pane widths one operator dragged, in the terminal cells each pane occupies. */
+export type TuiPaneLayout = {
+    /** Columns the tree pane was dragged to, or null while it holds its default. */
+    treeColumns: number | null;
+    /** Columns the message-log pane was dragged to, or null while it holds its default. */
+    messageLogColumns: number | null;
+};
+/** Carries dragged pane widths between runs of the terminal surface. */
+export interface TuiLayoutPort {
+    /**
+     * Read the layout a previous run stored.
+     * @returns The stored layout, or null when none was stored or it could not be read.
+     */
+    read(): TuiPaneLayout | null;
+    /**
+     * Store a layout for later runs. A failure to store is not reported: losing a pane width is not
+     * worth interrupting an operator over.
+     * @param layout - Widths to store.
+     */
+    write(layout: TuiPaneLayout): void;
+}
+/**
+ * Renderer-independent authoritative-state controller.
+ *
+ * Data flows broker → model → view. The model holds the authoritative facts and one map derived from
+ * them, `healthByAgentId`; every other derivation is computed at read time, in `presentation.ts` or
+ * beside the component that reads it, and never stored here. A view renders immutable state read
+ * through `useSyncExternalStore` and calls model intents, but a key or pointer handler reads
+ * `model.state` instead of the state its component last rendered: a reduction carries a whole view, so
+ * one built from a rendered snapshot overwrites what another handler decided since.
+ *
+ * Transport, local process, and scheduling reach the model as injected ports, so a component never
+ * opens a socket. The clipboard and the command-id and issue-time ports are the shell's, not the
+ * model's: they reach components as props, and components call them directly. Diagnostics go through
+ * this model's log, not `console.*` from a component; the runtime reports an abnormal exit's cause
+ * once the terminal is restored.
+ */
+export declare class TuiOperatorModel {
+    #private;
+    private readonly dependencies;
+    /**
+     * Construct a controller from explicit IO and lifecycle collaborators.
+     * @param dependencies - Injected transport, command, scheduling, and disposal ports.
+     */
+    constructor(dependencies: TuiOperatorModelDependencies);
+    /**
+     * Read the current immutable model state.
+     * @returns Current broker facts and local view state.
+     */
+    get state(): TuiOperatorModelState;
+    /**
+     * Observe state transitions.
+     * @param listener - Listener invoked after each state change.
+     * @returns Removal callback.
+     */
+    subscribe(listener: (state: TuiOperatorModelState) => void): () => void;
+    /**
+     * Hydrate authoritative facts and begin ordered reduction.
+     * @returns Completion after the initial snapshot is installed.
+     */
+    start(): Promise<void>;
+    /**
+     * Submit a command without locally changing broker facts.
+     * @param command - Versioned operator command.
+     * @returns Broker admission result.
+     */
+    execute(command: OperatorCommandEnvelope): Promise<OperatorCommandResult>;
+    /**
+     * Start one local command and record its output as it arrives.
+     *
+     * Ignored while a run is already in progress, so a repeated key cannot start a second child.
+     * @param command - Executable to run.
+     * @param args - Arguments passed to the executable.
+     * @param size - Terminal dimensions the child lays its output out for.
+     */
+    startLocalRun(command: string, args: readonly string[], size: TuiLocalRunSize): void;
+    /**
+     * Send operator input to the running child.
+     *
+     * Ignored unless a child is running, so a key pressed as the run ends cannot reach a dead process.
+     * @param bytes - Sequence already encoded for the child's terminal.
+     */
+    writeToLocalRun(bytes: Uint8Array): void;
+    /**
+     * Tell the running child its terminal has been resized.
+     *
+     * Ignored unless a child is running, for the same reason input is.
+     * @param columns - Columns the child now has.
+     * @param rows - Rows the child now has.
+     */
+    resizeLocalRun(columns: number, rows: number): void;
+    /**
+     * Discard a finished run, leaving a run still in progress alone.
+     */
+    clearLocalRun(): void;
+    /**
+     * End the running child and report the run as abandoned.
+     *
+     * The outcome is recorded here rather than awaited from the port, because the operator asked to stop
+     * waiting: a child that ignores the signal would otherwise keep them in the overlay it is stuck in.
+     * Whatever that child reports afterwards is dropped, because the run is no longer running.
+     */
+    cancelLocalRun(): void;
+    /**
+     * Set one side pane's dragged width.
+     *
+     * Storing is deliberately not done here: this runs once per cell of pointer travel, and the store
+     * is a blocking write.
+     *
+     * The pane on the far side is pinned to the width it currently renders at. Left as a preference the
+     * layout has not yet honoured, it would be re-clamped against the new request and shift under a
+     * pointer that never touched it.
+     * @param pane - Which side pane the operator dragged.
+     * @param columns - Cells the dragged pane should occupy, before any clamping the layout applies.
+     * @param oppositeColumns - Cells the pane on the far side of the agent log currently renders at.
+     */
+    resizePane(pane: "tree" | "message_log", columns: number, oppositeColumns: number): void;
+    /** Store the pane widths the operator has finished dragging, for later runs to adopt. */
+    commitPaneLayout(): void;
+    /**
+     * Update local view state only.
+     * @param update - Pure local view transformation.
+     */
+    updateView(update: (view: TuiOperatorViewState) => TuiOperatorViewState): void;
+    /**
+     * Select one traffic row, marking an accepted delivery read by the act of showing it.
+     * @param entry - Traffic row the operator moved onto.
+     */
+    viewTraffic(entry: OperatorTraffic): void;
+    /** Dispose stream, recovery work, listeners, and composition resources once. */
+    dispose(): void;
+    /**
+     * Record a condition this client observed, stamped from the model's own clock.
+     * @param severity - Attention the condition asks for.
+     * @param scope - Subsystem the condition arose in.
+     * @param summary - Content-free description, in the words the diagnostics log shows.
+     */
+    reportDiagnostic(severity: OperatorDiagnostic["severity"], scope: string, summary: string): void;
+    /**
+     * Install a complete transport snapshot through the same authoritative replacement path.
+     * @param snapshot - Validated operator snapshot, held by the model from here on.
+     * @param replacement - Whether the snapshot answers a resync, so unread identities that survived the gap are kept.
+     */
+    observeSnapshot(snapshot: OperatorSnapshot, replacement: boolean): void;
+    /**
+     * Apply one transport event using normal ordered reduction.
+     * @param event - Untrusted event envelope from the operator stream, validated here before it is applied.
+     */
+    observeEvent(event: unknown): void;
+    /** Start bounded recovery after an explicit transport resync. */
+    observeResync(): void;
+    /** End stream application after an incompatible transport observation. */
+    observeIncompatible(): void;
+}