moqi-tui 0.2.0

package/lib/types/tui/export.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Transcript export: turn the in-app message list into a markdown document.
+ *
+ * Pure and free of Harness imports, like everything under `./tui/`, so it can
+ * be tested without a profile.
+ * @module
+ */
+import { type Message } from './state.ts';
+/**
+ * Render a transcript as markdown.
+ *
+ * User turns become `## >`-quoted sections and assistant turns `##` sections.
+ * An assistant turn is written in the order it happened — each tool call as a
+ * checklist line between the prose it came between — because a document that
+ * collects the calls at the end tells you what the agent did but not when, and
+ * the reason it said the next thing is usually what the call returned.
+ */
+export declare function transcriptMarkdown(messages: readonly Message[], title: string): string;

package/lib/types/tui/fleet.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The fleet overview: sessions across every device, in one list.
+ *
+ * This module is pure. It knows nothing about filesystems, SSH, or the
+ * Harness — it takes presence records that someone else collected and turns
+ * them into ordered, rendered rows. That is what keeps the interesting part
+ * (staleness, ranking, what a row says) testable without a second machine.
+ *
+ * The transport is deliberately outside this file: see `src/fleet-sources.ts`.
+ * @module
+ */
+/**
+ * What one device publishes about one of its open sessions.
+ *
+ * A record is written by the app that owns the session and refreshed on a
+ * heartbeat, so its age is the liveness signal. Nothing here is derived from
+ * the session log: the owning app already knows its own status exactly, and
+ * decompressing a log per session per device would not scale over SSH.
+ */
+export interface PresenceRecord {
+    /** Record format version, so an older device's file can be rejected. */
+    v: number;
+    /** Device name, as the overview labels it. */
+    host: string;
+    /** Process that owns the session, for diagnosis only. */
+    pid: number;
+    sessionId: string;
+    title: string;
+    status: PresenceStatus;
+    /** Model the session is using, when known. */
+    model?: string;
+    /** Working directory the session was created in. */
+    cwd?: string;
+    /** Epoch millis of the last heartbeat. */
+    updatedAt: number;
+}
+/**
+ * What a session is doing, as a device reports it.
+ *
+ * Deliberately declared here rather than imported from the session state: the
+ * overview's wire format must not move when the local UI's types do, and it
+ * keeps this module dependency-free apart from rendering helpers.
+ */
+export type PresenceStatus = 'idle' | 'running' | 'ready';
+/** The record version this build writes and accepts. */
+export declare const PRESENCE_VERSION = 1;
+/**
+ * How long a record may go unrefreshed before its device is presumed gone.
+ *
+ * Generous relative to the heartbeat: a laptop that sleeps mid-turn should
+ * read as `stale` rather than flapping, and a slow SSH round trip must not
+ * make a healthy device look dead.
+ */
+export declare const DEFAULT_STALE_AFTER_MS = 30000;
+/** A session's state in the overview, including the one presence cannot claim. */
+export type FleetStatus = PresenceStatus | 'stale';
+/** One row of the overview. */
+export interface FleetSession {
+    host: string;
+    sessionId: string;
+    title: string;
+    status: FleetStatus;
+    model?: string;
+    cwd?: string;
+    updatedAt: number;
+    /** True when this row is the device the overview is running on. */
+    local: boolean;
+    /** Seconds since the last heartbeat, for display. */
+    ageSeconds: number;
+}
+/** What a device's collector returned, including the failure case. */
+export interface FleetSource {
+    host: string;
+    local: boolean;
+    /** Records read from the device, or an empty list when it could not be read. */
+    records: readonly PresenceRecord[];
+    /** Set when the device could not be reached or read. */
+    error?: string;
+}
+/** Whether a record is well-formed enough to display. */
+export declare function isPresenceRecord(value: unknown): value is PresenceRecord;
+/**
+ * Merge every device's records into one ordered list.
+ *
+ * A record older than `staleAfterMs` is reported `stale` whatever it claimed:
+ * a device that stopped heartbeating mid-turn would otherwise sit in the
+ * overview claiming to be running forever.
+ */
+export declare function mergeFleet(sources: readonly FleetSource[], now: number, staleAfterMs?: number): FleetSession[];
+/** A compact age: 8s, 4m, 2h, 3d. */
+export declare function formatAge(seconds: number): string;
+/**
+ * The command that opens a session on the device that owns it.
+ *
+ * A remote session is reached the same way the device itself is: over SSH,
+ * with a TTY, resuming by id. Nothing new is exposed to do it.
+ */
+export declare function jumpCommand(session: FleetSession, profile?: string): string;
+/**
+ * Quote one argument for a POSIX shell.
+ *
+ * A prompt is arbitrary text and is about to travel through `ssh`, which hands
+ * it to the remote shell — so it is single-quoted with the one escape a single
+ * quoted string has. Nothing here trusts the caller.
+ */
+export declare function shellQuote(text: string): string;
+/**
+ * The argv for dispatching a task to a peer's headless profile.
+ *
+ * The prompt is quoted for the remote shell; the profile name and host are
+ * passed as separate argv words so the local shell never interprets them.
+ */
+export declare function dispatchArgv(host: string, profile: string, prompt: string): string[];
+/** Options for {@link renderFleet}. */
+export interface FleetRenderOptions {
+    width: number;
+    /** Index of the highlighted row, or -1 for none. */
+    selectedIndex?: number;
+    spinner?: string;
+    /** Devices that could not be read, reported under the list. */
+    sources?: readonly FleetSource[];
+}
+/**
+ * Render the overview to styled lines.
+ *
+ * Grouped by device, because "which machine is this on" is the question the
+ * overview exists to answer; an unreachable device is named rather than
+ * silently contributing nothing.
+ */
+export declare function renderFleet(sessions: readonly FleetSession[], options: FleetRenderOptions): string[];
+/** A one-line summary for the status bar: how much is running where. */
+export declare function fleetSummary(sessions: readonly FleetSession[]): string;
+/** Colors re-exported so a caller can match the overview's palette. */
+export declare const FLEET_COLORS: {
+    readonly colGreen: import("./theme.ts").AdaptiveColor;
+    readonly colGold: import("./theme.ts").AdaptiveColor;
+    readonly colMuted: import("./theme.ts").AdaptiveColor;
+    readonly colText: import("./theme.ts").AdaptiveColor;
+    readonly ok: (text: string) => string;
+};
+/**
+ * Which rendered line carries row `index`.
+ *
+ * {@link renderFleet} inserts a heading per device and a blank line between
+ * groups, so the selected row's index is not its line. The pane needs the
+ * line to scroll, and duplicating the rule here rather than returning it from
+ * the renderer keeps the renderer a plain function of its inputs. The two must
+ * agree, which is what the smoke test pins.
+ */
+export declare function fleetLineOf(sessions: readonly FleetSession[], index: number): number;
+/**
+ * Whether a string is safe and sensible to use as a peer.
+ *
+ * The value ends up on an `ssh` command line, so this is a gate rather than a
+ * tidy-up: anything a shell would treat as more than one word, or that `ssh`
+ * would read as an option, is refused outright instead of being escaped and
+ * hoped for. What remains is the shape of a host, an alias, or `user@host`.
+ */
+export declare function isValidPeer(host: string): boolean;
+/**
+ * The overview's interaction state: what was collected, and where the cursor is.
+ *
+ * Kept beside the renderer because it is the same concern and equally pure —
+ * it never reads a file or a socket. The app owns collection and hands the
+ * result here.
+ */
+export declare class FleetView {
+    open: boolean;
+    /** True while a collection round is in flight, so the pane can say so. */
+    loading: boolean;
+    sessions: FleetSession[];
+    sources: FleetSource[];
+    selected: number;
+    /**
+     * Set while the pane is asking for a device to add.
+     *
+     * Adding a peer belongs here rather than only on the command line, because
+     * the list is exactly where you notice a device is missing from it.
+     */
+    adding: boolean;
+    /** What has been typed into that prompt so far. */
+    draft: string;
+    show(): void;
+    hide(): void;
+    /**
+     * Install a freshly collected round.
+     *
+     * The cursor follows the session it was on rather than the position it was
+     * at: rows reorder as work starts and finishes, and a refresh that moved the
+     * selection onto a different machine would be a way to open the wrong thing.
+     */
+    setResult(sessions: readonly FleetSession[], sources: readonly FleetSource[]): void;
+    move(delta: number): void;
+    current(): FleetSession | undefined;
+    /** Start asking for a device to add. */
+    beginAdd(): void;
+    /** Abandon the prompt, leaving the list as it was. */
+    cancelAdd(): void;
+    typeAdd(text: string): void;
+    backspaceAdd(): void;
+    /**
+     * Finish the prompt, returning the host to add.
+     *
+     * A rejected name leaves the prompt open with the text intact, so a typo is
+     * corrected rather than retyped.
+     */
+    commitAdd(): string | undefined;
+    private clamp;
+}

package/lib/types/tui/i18n.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Interface language: one catalog, looked up by key.
+ *
+ * The scope is deliberate: the chrome a reader reads — the welcome, the key
+ * reference, the trust panels, and the footer hints. Operational status lines
+ * (what a command just did) stay English because they are diagnostics, not
+ * interface, and translating a moving target is how a UI ends up half in each
+ * language.
+ *
+ * A missing key falls back to English and then to the key itself, so a new
+ * string can never render as blank.
+ * @module
+ */
+/** The languages the interface ships with. */
+export type Lang = 'en' | 'zh-CN';
+/** Every language, in menu order, with the label to show in a picker. */
+export declare const LANGS: readonly {
+    id: Lang;
+    label: string;
+}[];
+/** Whether an untrusted string names a language this build speaks. */
+export declare function isLang(value: string): value is Lang;
+/** Fill `{name}` placeholders; a missing value leaves the placeholder alone. */
+export declare function fill(template: string, params: Record<string, string | number> | undefined): string;
+/** Look a string up in one explicit language. */
+export declare function translate(lang: Lang, key: string, params?: Record<string, string | number>): string;
+/** The language the interface is drawing in. */
+export declare function currentLanguage(): Lang;
+/** Switch the interface language; the caller persists the choice. */
+export declare function setLanguage(lang: Lang): void;
+/** Look a string up in the active language. */
+export declare function t(key: string, params?: Record<string, string | number>): string;
+/** The full key reference in the active language. */
+export declare function helpText(): string;

package/lib/types/tui/jobs.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `/jobs` formatting: a background job list rendered as markdown.
+ *
+ * Pure, like the rest of `tui/`: the app layer hands over snapshots and owns
+ * the registry calls.
+ * @module
+ */
+/** The subset of a job snapshot this module formats. */
+export interface JobLike {
+    id: string;
+    kind: string;
+    label: string;
+    status: 'running' | 'stopping' | 'completed' | 'killed' | 'failed' | string;
+    detail?: string;
+    startedAt: number;
+    finishedAt?: number;
+}
+/** A compact "3s" / "4m" / "2h" duration. */
+export declare function formatDuration(seconds: number): string;
+/** The mark a job's state earns in the list. */
+export declare function jobMark(status: string): string;
+/**
+ * The `/jobs` overlay body.
+ *
+ * Running jobs first, then the settled ones newest-first, because the list
+ * exists to answer "what is still going" before "what happened".
+ */
+export declare function renderJobs(jobs: readonly JobLike[], now?: number): string;

package/lib/types/tui/keys.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Key decoding for raw-mode stdin.
+ *
+ * Node hands the app raw bytes, so escape sequences have to be turned back
+ * into key names. The decoder is chunk-tolerant: a sequence split across two
+ * reads is held until it completes rather than being reported as a stray
+ * escape.
+ * @module
+ */
+/** One decoded keypress. */
+export interface Key {
+    /** Canonical name, e.g. `enter`, `up`, `ctrl+c`, `a`. */
+    name: string;
+    /** Printable text this key contributes, if any. */
+    text: string;
+}
+/**
+ * Decode a buffer into keys, returning the keys and any trailing bytes that
+ * form an incomplete sequence.
+ */
+export declare function decode(input: string): {
+    keys: Key[];
+    rest: string;
+};
+/**
+ * How long a lone escape waits for the rest of a sequence before it is read as
+ * the escape key.
+ *
+ * A terminal sends the same byte for "the user pressed Escape" and for the
+ * first byte of `ESC [ A`; only time tells them apart. Without this, a lone
+ * Escape produced no key at all and the *next* keystroke was misread as an
+ * `alt+` chord, so every documented `esc` — interrupt, close an overlay,
+ * dismiss a menu — was dead. Vim's own `ttimeoutlen` sits in this range.
+ */
+export declare const ESCAPE_DELAY_MS = 50;
+/** A stateful decoder, plus the handles a terminal loop needs to own it. */
+export interface KeyDecoder {
+    /** Decode one chunk; complete keys come back, an unfinished tail is held. */
+    (chunk: string): Key[];
+    /** Read a held lone escape now, as its own key. */
+    flush(): void;
+    /** Cancel any pending timer, so a stopped screen emits nothing more. */
+    dispose(): void;
+}
+/**
+ * A stateful decoder that carries an incomplete sequence between chunks.
+ *
+ * @param emit - receives a key that arrives asynchronously (a flushed lone
+ *   escape), because no further chunk will carry it.
+ * @param escapeDelayMs - how long a lone escape waits; see {@link ESCAPE_DELAY_MS}.
+ */
+export declare function createDecoder(emit?: (key: Key) => void, escapeDelayMs?: number): KeyDecoder;

package/lib/types/tui/markdown.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Markdown to ANSI rendering, plus a small syntax highlighter for fenced code.
+ *
+ * The original Go client leaned on glamour and chroma. This is the same job
+ * done with no dependency: the transcript is re-rendered on every frame and
+ * while a reply streams in, so the renderer must tolerate a half-written
+ * document (an unterminated fence, a dangling emphasis run) without throwing
+ * or swallowing text.
+ * @module
+ */
+/** Render inline spans: code, bold, italic, strikethrough, and links. */
+export declare function renderInline(text: string): string;
+/** Render a markdown document to styled lines at `width` columns. */
+export declare function renderMarkdown(source: string, width: number): string;

package/lib/types/tui/mcp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `/mcp` formatting: which MCP servers' tools are actually mounted.
+ *
+ * The MCP client is a composition-level plugin — servers are declared in the
+ * profile, not registered through a queryable runtime API — so the honest view
+ * is the tool registry filtered to MCP-provided names. This module does the
+ * naming and grouping; the app layer does the probing.
+ * @module
+ */
+/** One MCP server and the tools it contributed. */
+export interface McpServer {
+    name: string;
+    tools: string[];
+}
+/**
+ * The separator conventions MCP bridges use in tool names.
+ *
+ * `mcp__server__tool` is the Claude-style double-underscore form; `server/tool`
+ * and `server:tool` appear in some bridges. Parsing all three means a server
+ * shows up whichever bridge mounted it.
+ */
+export declare function parseMcpToolName(name: string): {
+    server: string;
+    tool: string;
+} | undefined;
+/** Group tool names into their MCP servers, alphabetically by server then tool. */
+export declare function groupMcpTools(toolNames: readonly string[]): McpServer[];
+/**
+ * The `/mcp` overlay body.
+ *
+ * @param servers - grouped MCP tools, from {@link groupMcpTools}.
+ * @param totalTools - every tool the registry offers, for the empty case.
+ */
+export declare function renderMcp(servers: readonly McpServer[], totalTools: number): string;

package/lib/types/tui/panels.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Trust-surface panels: tool approval, `ask_user_question`, and plan review.
+ *
+ * These are the moments the agent stops and asks a human, so they own the
+ * keyboard while open and answer through the Harness waterfall seams. Like the
+ * rest of `tui/`, this module is pure state plus a view shape — the app layer
+ * does the Cordis wiring and the renderer does the drawing.
+ * @module
+ */
+/** One selectable row in a panel. */
+export interface PanelRow {
+    label: string;
+    description?: string;
+    /** Highlighted by the cursor. */
+    selected: boolean;
+    /** Multi-select state; undefined for a single-select row. */
+    checked?: boolean;
+}
+/**
+ * The panel the renderer draws in place of the transcript.
+ *
+ * `detail` is markdown: an approval's reason, a question's supporting text, or
+ * a plan under review.
+ */
+export interface PanelView {
+    kind: 'approval' | 'questions';
+    title: string;
+    detail: string;
+    rows: PanelRow[];
+    hint: string;
+    /** Extra lines under the rows: the free-text line and its draft. */
+    inputLabel?: string;
+    inputText?: string;
+    inputFocused?: boolean;
+}
+/**
+ * Read a spoken (transcribed) answer as an approval decision.
+ *
+ * Deliberately narrow: a misheard sentence must never grant a tool call, so
+ * only unambiguous words decide and anything else returns `undefined`, leaving
+ * the panel waiting. Both shipped interface languages are accepted.
+ */
+export declare function interpretApproval(text: string): ApprovalDecision | undefined;
+/** What the user decided about one approval request. */
+export type ApprovalDecision = 'allowed-once' | 'rejected';
+/**
+ * One pending tool approval.
+ *
+ * There is no persistent grant in the protocol — "allow once" or deny — so the
+ * panel offers exactly those two rows and no "always" temptation.
+ */
+export declare class ApprovalPanel {
+    selected: number;
+    readonly toolName: string;
+    readonly reason: string | undefined;
+    private readonly command;
+    constructor(toolName: string, reason: string | undefined, command: string | undefined);
+    move(delta: number): void;
+    decision(): ApprovalDecision;
+    view(): PanelView;
+}
+/** One question as the answerer receives it. */
+export interface QuestionSpec {
+    id: string;
+    question: string;
+    detail?: string;
+    header?: string;
+    options?: readonly {
+        label: string;
+        description?: string;
+    }[];
+    multiSelect?: boolean;
+    intent?: {
+        kind: 'plan-review';
+        approve: string;
+    };
+}
+/** One answered question, in the shape the Harness expects back. */
+export interface QuestionAnswer {
+    id: string;
+    selected: string[];
+    custom?: string;
+}
+/** Raised when the user backs out of a question set; the service maps it to `ASK_CANCELLED`. */
+export declare const ASK_CANCELLED_CODE = "ASK_CANCELLED";
+/**
+ * The `ask_user_question` flow, question by question.
+ *
+ * Single-select answers on `enter`; multi-select toggles with `space` and
+ * collects with `enter`; `tab` moves to the free-text line, and typing on an
+ * option row combines that option's label with the text, the way a form does.
+ * A plan review is the same shape with a markdown body and an approve label
+ * named by the protocol — approval never carries feedback, because the
+ * protocol reads feedback as "keep planning".
+ */
+export declare class QuestionsPanel {
+    index: number;
+    focus: 'options' | 'custom';
+    private readonly drafts;
+    private readonly questions;
+    constructor(questions: readonly QuestionSpec[]);
+    private get question();
+    private get draft();
+    /** Whether this set is a plan under review rather than a question. */
+    get isPlanReview(): boolean;
+    move(delta: number): void;
+    /** Space toggles the highlighted option on a multi-select question. */
+    toggle(): void;
+    focusCustom(): void;
+    /** Type into the free-text line; on an option row the option joins the answer. */
+    typeText(chunk: string): void;
+    backspaceText(): void;
+    /**
+     * Commit the current question and move on.
+     *
+     * @returns `'next'` when another question follows, `'done'` when the set is
+     *   answered, and `'empty'` when nothing has been chosen yet.
+     */
+    advance(): 'next' | 'done' | 'empty';
+    /** Step back one question, keeping what was already chosen. */
+    back(): boolean;
+    /** The finished answer set, in question order. */
+    answers(): QuestionAnswer[];
+    view(): PanelView;
+}

package/lib/types/tui/screen.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The terminal driver: raw mode, the alternate screen, and frame painting.
+ *
+ * Frames are painted line by line against the previous frame so a streaming
+ * reply only rewrites the lines that actually changed. That keeps a fast token
+ * stream from flickering the whole screen, which a naive full clear-and-redraw
+ * does at any real terminal size.
+ * @module
+ */
+import { type Key } from './keys.ts';
+/** What the screen reports about its size. */
+export interface Size {
+    columns: number;
+    rows: number;
+}
+/**
+ * Clamp a reported terminal size to something drawable.
+ *
+ * A stream can report `0` as well as `undefined` — a pty opened without a
+ * window size does exactly that — and `?? 80` does not catch a zero. Left
+ * alone, the whole frame collapses to zero-width lines and the app paints
+ * nothing but cursor moves, which looks like a hang rather than a sizing
+ * problem.
+ */
+export declare function normalizeSize(columns: number | undefined, rows: number | undefined): Size;
+/** Callbacks the owner supplies. */
+export interface ScreenHandlers {
+    onKey(key: Key): void;
+    onResize(size: Size): void;
+}
+/** Optional screen behavior. */
+export interface ScreenOptions {
+    /**
+     * Report mouse events so the wheel can scroll. Off by default: this is a
+     * keyboard-first app, and terminals suppress their own selection while
+     * reporting is on, which costs copy-paste to buy a wheel most people do not
+     * reach for.
+     */
+    mouse?: boolean;
+}
+/**
+ * Owns stdin/stdout for the lifetime of the app. Construction does not touch
+ * the terminal; {@link Screen.start} does, and {@link Screen.stop} is safe to
+ * call more than once so teardown paths can be blunt.
+ */
+export declare class Screen {
+    private previous;
+    private started;
+    private readonly decode;
+    private readonly onData;
+    private readonly onResize;
+    private cursor;
+    private readonly handlers;
+    private readonly mouse;
+    constructor(handlers: ScreenHandlers, options?: ScreenOptions);
+    /** Current terminal size, with defaults for a non-TTY stdout. */
+    size(): Size;
+    /** Whether this process is attached to a real terminal on both ends. */
+    static isInteractive(): boolean;
+    /** Enter the alternate screen and begin delivering keys. */
+    start(): void;
+    /** Restore the terminal. Safe to call repeatedly and after a failed start. */
+    stop(): void;
+    /**
+     * Place the hardware cursor on the next paint, in 0-indexed screen
+     * coordinates. Passing `undefined` hides it.
+     */
+    setCursor(position: {
+        row: number;
+        column: number;
+    } | undefined): void;
+    /**
+     * Paint a frame. `frame` is the whole screen as lines; missing lines are
+     * treated as blank so the caller need not pad to the window height.
+     */
+    paint(frame: string[]): void;
+    /** Drop the cached frame so the next paint rewrites every line. */
+    invalidate(): void;
+}