@haywoodmarx/agent-pager 0.1.0

package/dist/src/tui/presentation.js

@@ -0,0 +1,541 @@
+import { MESSAGE_TYPE_LIMIT_CHARACTERS } from "../broker/protocol.js";
+import { isOperatorAgentArchived } from "../operator/agent-projection.js";
+/** Column width the type column occupies when there is room to show it in full. */
+const TRAFFIC_TYPE_COLUMN_WIDTH = MESSAGE_TYPE_LIMIT_CHARACTERS + 1;
+/** Column widths of the agent-log list when a workspace scopes the traffic. */
+export const WORKSPACE_TRAFFIC_COLUMNS = Object.freeze({
+    state: 3,
+    time: 6,
+    from: 15,
+    arrow: 3,
+    to: 14,
+    type: TRAFFIC_TYPE_COLUMN_WIDTH,
+});
+/**
+ * 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 const AGENT_TRAFFIC_COLUMNS = Object.freeze({
+    state: 3,
+    time: 6,
+    direction: 6,
+    peer: Math.floor((WORKSPACE_TRAFFIC_COLUMNS.from + WORKSPACE_TRAFFIC_COLUMNS.to) / 2),
+    type: TRAFFIC_TYPE_COLUMN_WIDTH,
+});
+/** Label gutter shared by the message-log metadata and lifecycle sections. */
+export const MESSAGE_LABEL_GUTTER = 11;
+/** Label gutter used by the agent identity modal. */
+export const IDENTITY_LABEL_GUTTER = 14;
+/** Share of the message-log pane the body block occupies, whatever the message holds. */
+const MESSAGE_BODY_SHARE = 0.4;
+/** Rows the message-log body block never falls below while the pane can afford them. */
+export const MINIMUM_MESSAGE_BODY_ROWS = 3;
+/** Rows the lifecycle section keeps: its label, its blank row, and one observation. */
+const MINIMUM_LIFECYCLE_ROWS = 3;
+/** Rows the message-log metadata block and its closing rule always occupy. */
+const MESSAGE_METADATA_ROWS = 4;
+/**
+ * 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 function selectMessageBodyRows(contentRows) {
+    const available = contentRows - MESSAGE_METADATA_ROWS - 1;
+    if (available <= MINIMUM_MESSAGE_BODY_ROWS)
+        return Math.max(1, available);
+    const share = Math.round(contentRows * MESSAGE_BODY_SHARE);
+    return Math.min(Math.max(share, MINIMUM_MESSAGE_BODY_ROWS), available - MINIMUM_LIFECYCLE_ROWS);
+}
+/**
+ * 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 const SELECTION_GUTTER_GLYPH = "┃";
+/** Default column count of the agent tree pane, including its own padding; see {@link sidePaneWidths} for its draggable range. */
+export 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 const MESSAGE_LOG_COLUMNS = 42;
+/** Narrowest the agent tree may be dragged before its own content stops being legible. */
+export const MINIMUM_TREE_COLUMNS = 29;
+/** Narrowest the message log may be dragged before its own content stops being legible. */
+export const MINIMUM_MESSAGE_LOG_COLUMNS = 41;
+/** Columns the agent log keeps for itself, bounding how far either side pane may be dragged open. */
+export const MINIMUM_AGENT_LOG_COLUMNS = 55;
+/** Cells the window border and the two rules between panes take before any pane is drawn. */
+export const PANE_DECORATION_COLUMNS = 4;
+/**
+ * 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 function sidePaneWidths({ tree, treeFallback, messageLog, messageLogFallback, available, }) {
+    const wanted = {
+        tree: Math.max(MINIMUM_TREE_COLUMNS, tree ?? treeFallback),
+        messageLog: Math.max(MINIMUM_MESSAGE_LOG_COLUMNS, messageLog ?? messageLogFallback),
+    };
+    const overflow = wanted.tree + wanted.messageLog + MINIMUM_AGENT_LOG_COLUMNS - available;
+    const slack = {
+        tree: wanted.tree - MINIMUM_TREE_COLUMNS,
+        messageLog: wanted.messageLog - MINIMUM_MESSAGE_LOG_COLUMNS,
+    };
+    const total = slack.tree + slack.messageLog;
+    if (overflow <= 0 || total <= 0)
+        return wanted;
+    const take = Math.min(overflow, total);
+    const fromTree = Math.min(slack.tree, Math.max(take - slack.messageLog, Math.round((take * slack.tree) / total)));
+    return { tree: wanted.tree - fromTree, messageLog: wanted.messageLog - (take - fromTree) };
+}
+/**
+ * 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 const PORTRAIT_BREAKPOINT_COLUMNS = MINIMUM_TREE_COLUMNS + MINIMUM_AGENT_LOG_COLUMNS + MINIMUM_MESSAGE_LOG_COLUMNS + PANE_DECORATION_COLUMNS;
+/**
+ * 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 function trafficTypeColumnWidth(fixedColumnsWithoutType, maxWidth, rowWidth) {
+    return Math.max(0, Math.min(maxWidth, rowWidth - fixedColumnsWithoutType));
+}
+/** Rows the diagnostics log always occupies beneath the panes, however many entries it holds. */
+export 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 function formatDiagnostic(diagnostic, width) {
+    return truncateCells(`${formatClockSeconds(diagnostic.at)}  ${diagnostic.scope} — ${diagnostic.summary}`, width);
+}
+/**
+ * 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 function describeCommandOutcome(state, command, result) {
+    const verb = { ping_agent: "ping", archive_agent: "archive", expire_message: "expire" }[command.type];
+    if (result === null)
+        return { severity: "error", summary: `${verb} outcome unknown: no answer came back from the broker` };
+    if (result.status === "rejected")
+        return { severity: "warning", summary: `${verb} refused: ${result.reason}` };
+    const target = command.type === "expire_message" ? command.messageId : agentHandle(state, command.targetAgentId);
+    return { severity: "info", summary: `${verb} accepted for ${target}` };
+}
+/**
+ * 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 function diagnosticColor(severity, theme) {
+    switch (severity) {
+        case "error":
+            return theme.states.failed;
+        case "warning":
+            return theme.states.inProgress;
+        case "info":
+            return theme.structure.rulesAndLabels;
+    }
+}
+/**
+ * Render a wall-clock time without seconds for list columns.
+ * @param at - Epoch milliseconds recorded by the broker.
+ * @returns Local `HH:MM` rendering.
+ */
+export function formatClock(at) {
+    const value = new Date(at);
+    return `${pad2(value.getHours())}:${pad2(value.getMinutes())}`;
+}
+/**
+ * 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 function formatClockSeconds(at) {
+    const value = new Date(at);
+    return `${pad2(value.getHours())}:${pad2(value.getMinutes())}:${pad2(value.getSeconds())}`;
+}
+/**
+ * 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 function truncateCells(value, width) {
+    if (width <= 0)
+        return "";
+    return Array.from(value).length > width
+        ? `${Array.from(value)
+            .slice(0, Math.max(0, width - 1))
+            .join("")}…`
+        : value;
+}
+/** Cells a pane bar leaves unused at its two edges. */
+export 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 function fitBarLeading(leading, barWidth, trailing = "") {
+    const gap = trailing === "" ? 0 : Array.from(trailing).length + 1;
+    return truncateCells(leading, barWidth - PANE_BAR_INSET_COLUMNS - gap);
+}
+/**
+ * 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 function padCells(value, width) {
+    const fitted = truncateCells(value, width);
+    return fitted + " ".repeat(Math.max(0, width - Array.from(fitted).length));
+}
+/**
+ * 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 function padCellsBeforeColumn(value, width) {
+    return padCells(truncateCells(value, Math.max(0, width - 1)), width);
+}
+/**
+ * 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 function padCellsEnd(value, width) {
+    const fitted = truncateCells(value, width);
+    return " ".repeat(Math.max(0, width - Array.from(fitted).length)) + fitted;
+}
+/**
+ * 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 function agentColor(agentId, theme) {
+    let hash = 0;
+    for (const character of agentId)
+        hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
+    return theme.agents[hash % theme.agents.length] ?? theme.structure.bodyText;
+}
+/**
+ * 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 function agentHandle(state, agentId) {
+    const agent = state.snapshot?.agents.find((entry) => entry.id === agentId);
+    return agent ? agentHandleText(agent.alias) : agentId;
+}
+/**
+ * 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 function agentHandleText(alias) {
+    return alias.startsWith("@") ? alias : `@${alias}`;
+}
+/**
+ * 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 function agentAddress(state, agentId) {
+    const agent = state.snapshot?.agents.find((entry) => entry.id === agentId);
+    return agent ? `${agentHandleText(agent.alias)}@${agent.workspace}` : agentId;
+}
+/**
+ * Name the implementation and worktree detail shown beside an agent handle.
+ * @param agent - Projected agent.
+ * @returns Secondary detail text, without the handle.
+ */
+export function agentDetail(agent) {
+    const implementation = agent.implementation.available
+        ? agent.implementation.displayName
+        : (agent.implementation.id ?? "unavailable");
+    return agent.repository.worktree.kind === "worktree"
+        ? `${implementation} ⑂ ${agent.repository.worktree.path}`
+        : implementation;
+}
+/**
+ * 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 function deliveryGlyph(state) {
+    switch (state) {
+        case "queued":
+        case "claimed":
+            return "◐";
+        case "acknowledged":
+            return "●";
+        case "expired":
+            return "⊖";
+        case "dead_lettered":
+        case "failed":
+            return "✕";
+    }
+}
+/**
+ * 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 function deliveryColor(state, theme) {
+    switch (state) {
+        case "acknowledged":
+            return theme.states.complete;
+        case "queued":
+        case "claimed":
+            return theme.states.inProgress;
+        case "failed":
+        case "dead_lettered":
+            return theme.states.failed;
+        case "expired":
+            return theme.states.expired;
+        case null:
+            return theme.structure.rulesAndLabels;
+    }
+}
+/**
+ * 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 function trafficSubject(entry) {
+    switch (entry.kind) {
+        case "ping_audit":
+            return "";
+        case "accepted_delivery":
+            return entry.subject;
+    }
+}
+/**
+ * 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 function trafficType(entry) {
+    return entry.kind === "accepted_delivery" ? entry.type : "ping";
+}
+/**
+ * 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 function messageBodyDisplayText(content) {
+    if (typeof content === "string")
+        return content;
+    if (content !== null && typeof content === "object" && !Array.isArray(content) && typeof content.detail === "string")
+        return content.detail;
+    return JSON.stringify(content);
+}
+/**
+ * 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 function agentLogScope(state) {
+    const count = selectTuiTraffic(state).length;
+    const selection = state.view.selection;
+    if (selection?.kind === "agent") {
+        const agent = state.snapshot?.agents.find((entry) => entry.id === selection.agentId);
+        const repository = state.snapshot?.repositories.find((entry) => entry.id === agent?.repository.repositoryId);
+        const workspace = repository ? repository.name : "unknown workspace";
+        return {
+            kind: "agent",
+            title: agent
+                ? `${agentHandle(state, selection.agentId)} · ${agentDetail(agent)}`
+                : agentHandle(state, selection.agentId),
+            detail: `${workspace} · ${String(count)} msgs`,
+            agentId: selection.agentId,
+        };
+    }
+    const repository = selection === null || selection.kind === "hidden"
+        ? undefined
+        : state.snapshot?.repositories.find((entry) => entry.id === selection.repositoryId);
+    return { kind: "workspace", title: repository ? repository.name : "messages", detail: `${String(count)} msgs` };
+}
+/**
+ * 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 function activeAgentCount(state) {
+    return (state.snapshot?.agents ?? []).filter((agent) => !isOperatorAgentArchived(agent) && !state.view.hiddenRepositories.has(agent.repository.repositoryId)).length;
+}
+/**
+ * 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 function brokerIndicator(connection, theme) {
+    switch (connection) {
+        case "healthy":
+            return { glyph: "●", color: theme.states.complete };
+        case "recovering":
+            return { glyph: "◐", color: theme.states.inProgress };
+        case "incompatible":
+            return { glyph: "✕", color: theme.states.failed };
+        case "cold":
+        case "disposed":
+            return { glyph: "○", color: theme.structure.rulesAndLabels };
+    }
+}
+/**
+ * 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 function stepWrappingIndex(index, direction, count) {
+    if (count < 1)
+        return 0;
+    return (index + (direction === "up" ? count - 1 : 1)) % count;
+}
+/**
+ * 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 function selectTuiTraffic(state) {
+    const traffic = state.snapshot?.traffic ?? [];
+    const selection = state.view.selection;
+    // Traffic is read through a selection. Without one there is nothing in scope, rather than
+    // everything: an unscoped list belongs to no workspace and answers no question the operator asked.
+    if (!selection || selection.kind === "hidden")
+        return [];
+    if (selection.kind === "agent")
+        return traffic.filter((entry) => trafficTouchesAgent(entry, selection.agentId));
+    const agentIds = new Set((state.snapshot?.agents ?? [])
+        .filter((agent) => agent.repository.repositoryId === selection.repositoryId)
+        .map((agent) => agent.id));
+    return traffic.filter((entry) => trafficTouchesAny(entry, agentIds));
+}
+/**
+ * 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 function selectedTraffic(state) {
+    const trafficId = state.view.trafficId;
+    return trafficId === null ? undefined : state.snapshot?.traffic.find((entry) => entry.trafficId === trafficId);
+}
+/**
+ * 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 function selectedMessage(state) {
+    const entry = selectedTraffic(state);
+    return entry?.kind === "accepted_delivery" ? entry : 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 function findTuiMessage(state, messageId) {
+    const entry = state.snapshot?.traffic.find((traffic) => traffic.kind === "accepted_delivery" && traffic.messageId === messageId);
+    return entry?.kind === "accepted_delivery" ? entry : 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 function trafficTouchesAgent(entry, agentId) {
+    switch (entry.kind) {
+        case "accepted_delivery":
+            return entry.fromAgentId === agentId || entry.toAgentId === agentId;
+        case "ping_audit":
+            return entry.targetAgentId === agentId;
+    }
+}
+/**
+ * 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 function trafficTouchesAny(entry, agentIds) {
+    switch (entry.kind) {
+        case "accepted_delivery":
+            return agentIds.has(entry.fromAgentId) || agentIds.has(entry.toAgentId);
+        case "ping_audit":
+            return agentIds.has(entry.targetAgentId);
+    }
+}
+/**
+ * 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 function trafficTime(entry) {
+    switch (entry.kind) {
+        case "accepted_delivery":
+            return entry.acceptedAt;
+        case "ping_audit":
+            return entry.acceptedAt;
+    }
+}
+function pad2(value) {
+    return String(value).padStart(2, "0");
+}

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

@@ -0,0 +1,79 @@
+import { type OperatorTuiProps } from "./app.js";
+import { startOpenTuiFactory, type OpenTuiRuntimeOptions } from "./composition.js";
+import { type TuiLayoutPort, type TuiLocalCommandPort, type TuiSchedulerPort } from "./model.js";
+import type { TuiTheme } from "./theme.js";
+export type { TuiHostRegistration } from "./actions.js";
+/** Canonical semantic palette selected by the production terminal command. */
+export declare const DEFAULT_OPERATOR_TUI_THEME: Readonly<TuiTheme>;
+/**
+ * Start the production terminal surface from explicitly composed client and presentation ports.
+ * @param options - Model, presentation ports, and optional renderer configuration.
+ * @param start - Starts the renderer, supplying the shutdown action to the factory that builds the root element; the OpenTUI starter by default.
+ * @returns Running renderer lifecycle whose caller owns the final shutdown request.
+ */
+export declare function startOperatorTui(options: Omit<OperatorTuiProps, "onShutdown"> & {
+    readonly runtime?: OpenTuiRuntimeOptions;
+}, start?: typeof startOpenTuiFactory): Promise<import("./runtime.ts").TuiRuntime<import("@opentui/core").CliRenderer>>;
+/** Options for {@link createOperatorTuiClient}. */
+export type CreateOperatorTuiClientOptions = {
+    /** Operator endpoint the broker published; no connection opens until the model starts. */
+    operatorUrl: string;
+    /** Palette every view receives; the dimmed backdrop for overlays is derived from it. */
+    theme: Readonly<TuiTheme>;
+    /** Copies raw text where the terminal cannot; the operating system's commands unless injected. */
+    clipboard?: TuiNativeClipboardPort;
+    /** Runs operator actions on this machine; a pseudo-terminal spawn unless injected. */
+    localCommand?: TuiLocalCommandPort;
+    /** Carries dragged pane widths between runs, or undefined to keep them for this run only. */
+    layout?: TuiLayoutPort;
+};
+/**
+ * Build the production model and retained-body adapter from the published operator state endpoint.
+ * @param options - Endpoint, palette, and optional clipboard, local-command, and layout ports.
+ * @returns The shell's model, palette, body reader, copy fallback and command port, without its shutdown action or action catalogue.
+ */
+export declare function createOperatorTuiClient({ operatorUrl, theme, clipboard, localCommand, layout, }: CreateOperatorTuiClientOptions): Omit<OperatorTuiProps, "onShutdown" | "actions">;
+/**
+ * Keep dragged pane widths in a file beside the operator's other local state.
+ *
+ * Every failure resolves to "no stored layout": the file is a convenience, and an operator locked out
+ * of the surface because a width could not be parsed would be worse off than one whose panes reset.
+ * @param storeDirectory - Directory the operator's local state lives in.
+ * @returns - Port reading and writing that directory's layout file.
+ */
+export declare function fileBackedTuiLayout(storeDirectory: string): TuiLayoutPort;
+/** Copies raw message content through a native mechanism when OSC52 is unavailable. */
+export interface TuiNativeClipboardPort {
+    /**
+     * Attempts one local clipboard write without reporting message content.
+     * @param rawCopy - Exact content to copy.
+     * @returns Whether the platform reported success.
+     */
+    copy(rawCopy: string): boolean;
+}
+/**
+ * Run a local command attached to a pseudo-terminal, streaming its raw bytes to the model.
+ *
+ * Output is captured rather than inherited: the renderer owns the terminal, so a child writing to it
+ * directly would overwrite the frame.
+ *
+ * The child is given a pseudo-terminal rather than pipes. Seeing pipes, a child reports no terminal
+ * and takes whatever silent non-interactive path it has, so an operator could never answer a question
+ * it asks.
+ * @returns - Port that spawns through the operating system.
+ */
+export declare function systemLocalCommand(): TuiLocalCommandPort;
+/**
+ * Build the reconnect scheduler over an explicit timer, so the delay the model asks for is observable.
+ * @param set - Arms one timer for the requested delay and returns the handle that cancels it.
+ * @param clear - Cancels a handle `set` returned, whether or not it has already fired.
+ * @returns Scheduler port whose cancellation callback clears the handle it armed.
+ */
+export declare function createTimerScheduler<Handle>(set: (callback: () => void, delayMs: number) => Handle, clear: (handle: Handle) => void): TuiSchedulerPort;
+/**
+ * Build a bounded native clipboard port from explicit platform command execution.
+ * @param platform - Operating system whose clipboard commands are tried, in order; any other copies nothing.
+ * @param run - Runs one command with the raw text on standard input, reporting success; a throw counts as failure.
+ * @returns Port that reports whether any command copied the text within its time limit.
+ */
+export declare function createNativeClipboardPort(platform: NodeJS.Platform, run: (command: string, arguments_: readonly string[], rawCopy: string, timeoutMs: number) => boolean): TuiNativeClipboardPort;