@haywoodmarx/agent-pager 0.1.0

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

@@ -0,0 +1,350 @@
+import { type AgentId } from "../broker/protocol.js";
+import type { OperatorAcceptedDelivery, OperatorAgent, OperatorCommand, OperatorCommandResult, OperatorDiagnostic, OperatorJsonValue, OperatorTraffic } from "../operator/protocol.js";
+import type { TuiOperatorModelState } from "./model.js";
+import type { TuiTheme, TuiThemeColor } from "./theme.js";
+/** Column widths of the agent-log list when a workspace scopes the traffic. */
+export declare const WORKSPACE_TRAFFIC_COLUMNS: Readonly<{
+    state: 3;
+    time: 6;
+    from: 15;
+    arrow: 3;
+    to: 14;
+    type: number;
+}>;
+/**
+ * Column widths of the agent-log list when a single agent scopes the traffic.
+ *
+ * One peer stands where the workspace list shows two, so it takes half of what those two endpoints
+ * occupy there; the arrow between them belongs to neither and is excluded before halving.
+ */
+export declare const AGENT_TRAFFIC_COLUMNS: Readonly<{
+    state: 3;
+    time: 6;
+    direction: 6;
+    peer: number;
+    type: number;
+}>;
+/** Label gutter shared by the message-log metadata and lifecycle sections. */
+export declare const MESSAGE_LABEL_GUTTER = 11;
+/** Label gutter used by the agent identity modal. */
+export declare const IDENTITY_LABEL_GUTTER = 14;
+/** Rows the message-log body block never falls below while the pane can afford them. */
+export declare const MINIMUM_MESSAGE_BODY_ROWS = 3;
+/**
+ * Size the message-log body block from the pane rather than the message.
+ *
+ * The block is fixed for any one pane height so the panel cannot jump as the operator moves through
+ * the list, and it scales with the pane's height.
+ * @param contentRows - Rows the message-log pane gives its content, excluding header, footer, and rules.
+ * @returns Rows reserved for the subject and clipped body.
+ */
+export declare function selectMessageBodyRows(contentRows: number): number;
+/**
+ * Marks the selected row in the gutter cell that sits outside its fill.
+ *
+ * The marker is not part of the highlight, so it keeps one shape whether or not the row is filled.
+ */
+export declare const SELECTION_GUTTER_GLYPH = "\u2503";
+/** Default column count of the agent tree pane, including its own padding; see {@link sidePaneWidths} for its draggable range. */
+export declare const AGENT_TREE_COLUMNS = 52;
+/** Default column count of the message log pane, including its own padding; see {@link sidePaneWidths} for its draggable range. */
+export declare const MESSAGE_LOG_COLUMNS = 42;
+/** Narrowest the agent tree may be dragged before its own content stops being legible. */
+export declare const MINIMUM_TREE_COLUMNS = 29;
+/** Narrowest the message log may be dragged before its own content stops being legible. */
+export declare const MINIMUM_MESSAGE_LOG_COLUMNS = 41;
+/** Columns the agent log keeps for itself, bounding how far either side pane may be dragged open. */
+export declare const MINIMUM_AGENT_LOG_COLUMNS = 55;
+/** Cells the window border and the two rules between panes take before any pane is drawn. */
+export declare const PANE_DECORATION_COLUMNS = 4;
+/** Drag state and available room for {@link sidePaneWidths}. */
+export type SidePaneWidthsRequest = {
+    /** Columns the operator dragged the tree pane to, or null for its default. */
+    tree: number | null;
+    /** Default width of the tree pane. */
+    treeFallback: number;
+    /** Columns the operator dragged the message-log pane to, or null for its default. */
+    messageLog: number | null;
+    /** Default width of the message-log pane. */
+    messageLogFallback: number;
+    /** Columns the three panes share, excluding the two rules between them. */
+    available: number;
+};
+/**
+ * Resolve both side panes' widths against the operator's drags and the room actually available.
+ *
+ * Each pane holds the width it was dragged to while the room allows, so widening one does not move
+ * the other. They yield only together: when the two of them plus the agent log's own minimum exceed
+ * the room, they give up the shortfall in proportion to how far each holds above its floor. A null
+ * request is a pane the operator has never dragged, which holds its default.
+ * @param request - Both panes' drag state, their fallbacks, and the room available to them.
+ * @returns Columns each side pane occupies; the agent log takes what is left.
+ */
+export declare function sidePaneWidths({ tree, treeFallback, messageLog, messageLogFallback, available, }: SidePaneWidthsRequest): {
+    readonly tree: number;
+    readonly messageLog: number;
+};
+/**
+ * Terminal width below which the operator surface becomes a single-pane stack.
+ *
+ * The three panes cannot all be shown below the sum of the widths each needs to stay legible, so that
+ * sum plus the decoration between and around them is exactly where the surface stops trying.
+ */
+export declare const PORTRAIT_BREAKPOINT_COLUMNS: number;
+/**
+ * Decide how wide a traffic row's type column should render.
+ *
+ * The type column outranks the subject as a row narrows: a type is a whole word, while a subject
+ * clipped to its first few characters is worth less than the category beside it. The subject
+ * therefore absorbs the loss down to nothing, and only a row too narrow for the type column itself
+ * clips that.
+ * @param fixedColumnsWithoutType - The row's other fixed columns for its scope, excluding type.
+ * @param maxWidth - The type column's width when there is room to show it in full.
+ * @param rowWidth - Character cells available to the whole row, subject included.
+ * @returns `maxWidth`, or what remains of the row when even that does not fit.
+ */
+export declare function trafficTypeColumnWidth(fixedColumnsWithoutType: number, maxWidth: number, rowWidth: number): number;
+/** Rows the diagnostics log always occupies beneath the panes, however many entries it holds. */
+export declare const COLLAPSED_LOG_ROWS = 3;
+/**
+ * Render one diagnostic as a single log row.
+ * @param diagnostic - Content-free condition recorded by the broker or the client.
+ * @param width - Character cells available to the row.
+ * @returns The row text, clipped to the width.
+ */
+export declare function formatDiagnostic(diagnostic: OperatorDiagnostic, width: number): string;
+/**
+ * Word one operator command's outcome for the diagnostics log.
+ *
+ * An answer is admission, not the resulting state change, so an accepted command is worded as
+ * accepted. A command that got no answer at all is worded as unknown, because the broker may have
+ * applied it.
+ * @param state - Current projection, which names the agent a command targeted.
+ * @param command - Command the operator submitted.
+ * @param result - The broker's admission answer, or null when none came back.
+ * @returns Severity and content-free summary for the log row.
+ */
+export declare function describeCommandOutcome(state: TuiOperatorModelState, command: OperatorCommand, result: OperatorCommandResult | null): Pick<OperatorDiagnostic, "severity" | "summary">;
+/**
+ * Select the colour role one diagnostic severity carries.
+ * @param severity - Attention the condition asks for.
+ * @param theme - Semantic palette in use.
+ * @returns The colour the row is drawn in.
+ */
+export declare function diagnosticColor(severity: OperatorDiagnostic["severity"], theme: Readonly<TuiTheme>): string;
+/**
+ * Render a wall-clock time without seconds for list columns.
+ * @param at - Epoch milliseconds recorded by the broker.
+ * @returns Local `HH:MM` rendering.
+ */
+export declare function formatClock(at: number): string;
+/**
+ * Render a wall-clock time with seconds for lifecycle rows.
+ * @param at - Epoch milliseconds recorded by the broker.
+ * @returns Local `HH:MM:SS` rendering.
+ */
+export declare function formatClockSeconds(at: number): string;
+/**
+ * Fit a value into a fixed column count, marking loss with an ellipsis.
+ * @param value - Text to place in the column.
+ * @param width - Character cells available to the column.
+ * @returns Text no wider than the column.
+ */
+export declare function truncateCells(value: string, width: number): string;
+/** Cells a pane bar leaves unused at its two edges. */
+export declare const PANE_BAR_INSET_COLUMNS = 2;
+/**
+ * Fit the leading text of a pane bar so the trailing text keeps its place beside it.
+ *
+ * A bar row is one cell high, so text wider than the room it is given wraps and the row shows only its
+ * first line, cut at a hyphen with no ellipsis. This shortens the leading text before that happens.
+ * @param leading - Text at the bar's left edge, given whatever the trailing text leaves.
+ * @param barWidth - Cells the whole bar occupies, including its inset.
+ * @param trailing - Text at the bar's right edge, kept whole; empty when the bar has none.
+ * @returns The leading text, ending in an ellipsis when it was shortened.
+ */
+export declare function fitBarLeading(leading: string, barWidth: number, trailing?: string): string;
+/**
+ * Left-align a value in a fixed column.
+ * @param value - Text to place in the column.
+ * @param width - Character cells available to the column.
+ * @returns Truncated text padded to the column width.
+ */
+export declare function padCells(value: string, width: number): string;
+/**
+ * Left-align a value in a fixed column, reserving its final cell so the next column cannot abut.
+ * @param value - Text to place in the column.
+ * @param width - Character cells available to the column, including the reserved separator.
+ * @returns Text truncated one cell short of the column and padded to its full width.
+ */
+export declare function padCellsBeforeColumn(value: string, width: number): string;
+/**
+ * Right-align a value in a fixed column.
+ * @param value - Text to place in the column.
+ * @param width - Character cells available to the column.
+ * @returns Truncated text padded to the column width.
+ */
+export declare function padCellsEnd(value: string, width: number): string;
+/**
+ * Assign one stable palette slot to an agent identity.
+ * @param agentId - Durable broker agent identity.
+ * @param theme - Semantic palette in use.
+ * @returns The agent's colour, stable everywhere its handle appears.
+ */
+export declare function agentColor(agentId: string, theme: Readonly<TuiTheme>): TuiThemeColor;
+/**
+ * Render the handle an operator reads for an agent identity.
+ * @param state - Current projection and view state.
+ * @param agentId - Durable broker agent identity.
+ * @returns The routable handle, or the raw identity when the agent is not projected.
+ */
+export declare function agentHandle(state: TuiOperatorModelState, agentId: string): string;
+/**
+ * Render one alias as the handle an operator reads.
+ *
+ * The projection delivers aliases without their at-sign, and this adds the one; a leading at-sign
+ * already present is kept rather than doubled.
+ * @param alias - Projected agent alias.
+ * @returns The alias with exactly one leading at-sign.
+ */
+export declare function agentHandleText(alias: string): string;
+/**
+ * Render one agent as the full address that reaches it from any workspace.
+ * @param state - Current operator model state supplying the projected agents.
+ * @param agentId - Durable agent identity to name.
+ * @returns The handle followed by an at-sign and the agent's workspace name.
+ */
+export declare function agentAddress(state: TuiOperatorModelState, agentId: string): string;
+/**
+ * Name the implementation and worktree detail shown beside an agent handle.
+ * @param agent - Projected agent.
+ * @returns Secondary detail text, without the handle.
+ */
+export declare function agentDetail(agent: OperatorAgent): string;
+/**
+ * Select the glyph carried by a delivery state in the tree and traffic lists.
+ * @param state - Durable delivery state.
+ * @returns The one-cell state glyph.
+ */
+export declare function deliveryGlyph(state: OperatorAcceptedDelivery["state"]): string;
+/**
+ * Select the colour carried by a delivery state.
+ * @param state - Durable delivery state, or null for an observation that established none.
+ * @param theme - Semantic palette in use.
+ * @returns The state colour, or secondary text for a stateless observation.
+ */
+export declare function deliveryColor(state: OperatorAcceptedDelivery["state"] | null, theme: Readonly<TuiTheme>): string;
+/**
+ * Read the headline an operator scans a traffic row by.
+ * @param entry - Traffic row from the authoritative projection.
+ * @returns The durable subject for a delivery, and nothing for an audit, which carries no subject.
+ */
+export declare function trafficSubject(entry: OperatorTraffic): string;
+/**
+ * Read the type of a traffic row, apart from its subject.
+ * @param entry - Traffic row from the authoritative projection.
+ * @returns The sender-supplied type of a delivery, or the control word for an audit.
+ */
+export declare function trafficType(entry: OperatorTraffic): string;
+/**
+ * Render a retained message body as the sentence an operator reads, not its wire JSON.
+ *
+ * A bare string body renders as itself. A peer sending a `{ type, detail }` envelope falls back to
+ * its `detail`. Every other shape the broker's opaque body admits — an array, an object
+ * with no string `detail` — has no defined readable subset, so it falls back to the full body rather
+ * than inventing a partial rendering. Exact wire-byte access does not depend on this: the raw-copy
+ * action reads the body's own retained representation, untouched by this function.
+ * @param content - Retained message body content.
+ * @returns Text for the message-log pane and full-message overlay.
+ */
+export declare function messageBodyDisplayText(content: OperatorJsonValue): string;
+/** Heading the agent log presents, carrying an agent identity only where the scope is one agent. */
+export type TuiAgentLogScope = {
+    readonly kind: "agent";
+    readonly title: string;
+    readonly detail: string;
+    readonly agentId: AgentId;
+} | {
+    readonly kind: "workspace";
+    readonly title: string;
+    readonly detail: string;
+};
+/**
+ * Describe the scope heading the agent log presents for the current tree selection.
+ * @param state - Current projection and view state.
+ * @returns Heading title, its trailing detail, and the scope kind, with the agent's identity when one agent scopes the log.
+ */
+export declare function agentLogScope(state: TuiOperatorModelState): TuiAgentLogScope;
+/**
+ * Count the agents the operator is being asked to keep an eye on.
+ *
+ * Archived identities are excluded: they are kept for their history and their conversations may
+ * return, but they are not part of what is running now. So are the agents of a hidden workspace,
+ * which the operator has said they do not want to see.
+ * @param state - Current authoritative projection.
+ * @returns - Number of agents that are neither archived nor in a hidden workspace.
+ */
+export declare function activeAgentCount(state: TuiOperatorModelState): number;
+/**
+ * Report the broker indicator and its colour role.
+ * @param connection - Current transport condition held by the model.
+ * @param theme - Semantic palette in use.
+ * @returns Indicator glyph and colour.
+ */
+export declare function brokerIndicator(connection: TuiOperatorModelState["connection"], theme: Readonly<TuiTheme>): {
+    readonly glyph: string;
+    readonly color: string;
+};
+/**
+ * Move a menu selection one entry, wrapping at both ends.
+ * @param index - Current selection.
+ * @param direction - Requested movement.
+ * @param count - Number of entries to move within.
+ * @returns - Next selection, zero for a menu with no entries.
+ */
+export declare function stepWrappingIndex(index: number, direction: "up" | "down", count: number): number;
+/**
+ * Select traffic that belongs to the local tree selection without treating audits as deliveries.
+ * @param state - Current projection and view state.
+ * @returns Traffic rows in projection order, empty where the selection scopes none.
+ */
+export declare function selectTuiTraffic(state: TuiOperatorModelState): readonly OperatorTraffic[];
+/**
+ * Read the traffic row the agent log has selected.
+ * @param state - Current projection and view state.
+ * @returns The selected row, or undefined when nothing is selected or it has left the projection.
+ */
+export declare function selectedTraffic(state: TuiOperatorModelState): OperatorTraffic | undefined;
+/**
+ * Read the accepted delivery the message log presents.
+ * @param state - Current projection and view state.
+ * @returns The selected delivery, or undefined when the selected row is not one.
+ */
+export declare function selectedMessage(state: TuiOperatorModelState): OperatorAcceptedDelivery | undefined;
+/**
+ * Find one accepted delivery by its durable message identity.
+ * @param state - Current projection and view state.
+ * @param messageId - Durable message the caller holds an identity for.
+ * @returns The delivery, or undefined when the projection no longer carries it.
+ */
+export declare function findTuiMessage(state: TuiOperatorModelState, messageId: string): OperatorAcceptedDelivery | undefined;
+/**
+ * Report whether one traffic row involves a single agent.
+ * @param entry - Traffic row from the authoritative projection.
+ * @param agentId - Durable broker agent identity.
+ * @returns Whether the row belongs to the agent's filtered log.
+ */
+export declare function trafficTouchesAgent(entry: OperatorTraffic, agentId: string): boolean;
+/**
+ * Report whether one traffic row involves any agent of a workspace.
+ * @param entry - Traffic row from the authoritative projection.
+ * @param agentIds - Durable identities grouped under one operator repository.
+ * @returns Whether the row belongs to the workspace log.
+ */
+export declare function trafficTouchesAny(entry: OperatorTraffic, agentIds: ReadonlySet<string>): boolean;
+/**
+ * Read the time a traffic row is ordered and listed by.
+ * @param entry - Traffic row from the authoritative projection.
+ * @returns Epoch milliseconds shown in the time column.
+ */
+export declare function trafficTime(entry: OperatorTraffic): number;