@multiclawcli/dashboard 0.6.3 → 0.7.0

package/dist/tui/components/interaction.d.ts

@@ -0,0 +1,44 @@
+import type { RuntimePermissionRequest, RuntimeQuestionRequest } from "@multiclawcli/core";
+import { type FormField, type FormState } from "../interaction";
+/**
+ * The bar the console docks above the prompt when an agent is blocked on the
+ * user.
+ *
+ * It is *docked* rather than a body overlay on purpose. The old screens replaced
+ * the stream with the question, which took away the one thing needed to answer
+ * it — what the agent had been doing up to the point it asked. Approval is a
+ * decision made *about* the stream, so it belongs next to it, not instead of it.
+ *
+ * Everything here is one row per fact and clipped by the caller, which is why
+ * the row count in `interaction.ts` only has to be an upper bound.
+ */
+export declare function PermissionBar({ request, others, cursor, released, width, }: {
+    request: RuntimePermissionRequest;
+    /** Requests behind this one, shown so "2 waiting" is not a bare number. */
+    others: readonly RuntimePermissionRequest[];
+    /** Highlighted option, or `undefined` when nothing has been picked yet. */
+    cursor: number | undefined;
+    /** The user asked for the keyboard back; only the commands still reach it. */
+    released: boolean;
+    width: number;
+}): import("react").JSX.Element;
+/**
+ * The question, as a form.
+ *
+ * The old path asked for `/respond q1 {"database":"postgres"}` — a hand-written
+ * JSON object matching a schema the user could only read in the same terminal
+ * that was now occupied by what they were typing. Here every field is a row, the
+ * focused row is the one the keystrokes go to, and choices are picked rather
+ * than spelled. The prompt below still does the typing: it already owns the
+ * caret, the wrapping and the paste handling, so a text field reuses it instead
+ * of growing a second editor.
+ */
+export declare function QuestionForm({ request, others, fields, form, draft, width, }: {
+    request: RuntimeQuestionRequest;
+    others: readonly RuntimeQuestionRequest[];
+    fields: FormField[];
+    form: FormState;
+    /** Text in the prompt, which is the focused text field's editor. */
+    draft: string;
+    width: number;
+}): import("react").JSX.Element;

package/dist/tui/components/overlays.d.ts

@@ -1,4 +1,3 @@
-import type { RuntimePermissionRequest, RuntimeQuestionRequest } from "@multiclawcli/core";
 import { type TurnView } from "../state";
 interface HelpGroup {
     title: string;
@@ -44,22 +43,6 @@ export declare function HelpOverlay({ width, maxRows }: {
     width: number;
     maxRows: number;
 }): import("react").JSX.Element;
-export declare function PermissionOverlay({ request, shortId, queued, width, maxRows, }: {
-    request: RuntimePermissionRequest;
-    shortId: string;
-    queued: number;
-    width: number;
-    maxRows: number;
-}): import("react").JSX.Element;
-export declare function questionLines(request: RuntimeQuestionRequest, width: number): string[];
-export declare function QuestionOverlay({ request, shortId, queued, width, maxRows, offset, }: {
-    request: RuntimeQuestionRequest;
-    shortId: string;
-    queued: number;
-    width: number;
-    maxRows: number;
-    offset: number;
-}): import("react").JSX.Element;
 /**
  * The finished turns, newest first.
  *

package/dist/tui/components/prompt.d.ts

@@ -1,6 +1,49 @@
 import type { PaletteRow } from "../commands";
+/** Columns the marker occupies, so a wrapped row can leave exactly that gap. */
+export declare const MARKER_WIDTH: number;
 /**
- * The prompt line.
+ * How many rows a long input may occupy.
+ *
+ * The prompt grows with the text, and the body gives up a row for each one it
+ * takes — so without a ceiling a pasted document would squeeze the stream out
+ * of existence. Past this the prompt scrolls instead of growing.
+ */
+export declare const MAX_PROMPT_ROWS = 5;
+/** One row of the prompt, already broken to the width it will be drawn at. */
+export interface PromptLine {
+    text: string;
+    /**
+     * Where the caret sits inside `text`, as an index into it, or `undefined`
+     * when the caret is on another row.
+     *
+     * An index rather than a column because a wide character is one index and two
+     * columns: splitting the row by column would cut a CJK character in half.
+     */
+    caret?: number;
+}
+/**
+ * Break the input into the rows it will actually be drawn on.
+ *
+ * Broken by *character*, not by word: a terminal input line has no words to
+ * respect, and typing past the last column simply continues on the next row.
+ * Word-wrapping here would move the text under the user's fingers — a space
+ * typed at the end of a row would push a whole word down and take the caret
+ * with it.
+ *
+ * Every character is kept, in order, across the rows: nothing is dropped at a
+ * break, which is what lets the caret be tracked as an index into a row.
+ */
+export declare function promptLines(value: string, cursor: number, width: number): PromptLine[];
+/**
+ * How many rows the prompt is asking for, capped at what it will actually draw.
+ *
+ * Exported because the layout has to know before Ink lays anything out: the
+ * body is given whatever the chrome leaves, and an unbudgeted prompt row shows
+ * up as a stream pane that silently loses its last line.
+ */
+export declare function promptRowCount(value: string, cursor: number, width: number): number;
+/**
+ * The prompt.
  *
  * The terminal's own cursor is hidden while the console owns the screen, so the
  * caret has to be drawn. It sits *between* the text before and after it rather
@@ -11,12 +54,20 @@ import type { PaletteRow } from "../commands";
  * caret that *added* a cell while visible would shove the placeholder one
  * column sideways twice a second. Instead the caret is painted *onto* the ghost
  * text's first character, which is what a real block cursor does.
+ *
+ * The rows are broken here rather than by Ink. Ink would wrap the text happily,
+ * but the caret is a *sibling* of the text, not part of it — so a wrapped line
+ * left the caret stranded at the right end of the first row while the rest of
+ * the text carried on underneath it. Breaking the line first puts the caret on
+ * the row the text actually reached.
  */
-export declare function Prompt({ value, cursor, caretVisible, placeholder, }: {
+export declare function Prompt({ value, cursor, caretVisible, placeholder, width, }: {
     value: string;
     cursor: number;
     caretVisible: boolean;
     placeholder: string;
+    /** Columns the whole prompt line may occupy, marker included. */
+    width: number;
 }): import("react").JSX.Element;
 /**
  * The palette, rendered directly above the prompt.

package/dist/tui/interaction.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The two things an agent can stop and ask for, modelled as something the user
+ * can *point at* instead of something they have to spell out.
+ *
+ * Both used to be answered by command — `/approve p4 1`, `/respond q1
+ * {"database":"postgres"}` — which put three transformations between reading a
+ * question and answering it: remember an internal alias, map a number back onto
+ * a list rendered somewhere else, and hand-write JSON that happens to match a
+ * schema. None of those are the decision. So the rendered question becomes the
+ * thing that is operated on: the option you are looking at is the option you
+ * commit, and the field you are editing is the field that receives the
+ * keystroke.
+ *
+ * Pure on purpose. The keyboard rules are the part of this easiest to get
+ * subtly wrong — a bare key that both selects and types, a required field that
+ * silently submits empty — so they live here, where they can be tested without
+ * rendering a terminal.
+ */
+import type { RuntimePermissionRequest, RuntimeQuestionRequest } from "@multiclawcli/core";
+export type PermissionOptionKind = RuntimePermissionRequest["options"][number]["kind"];
+/** One offered permission option, with the number the bar advertises for it. */
+export interface PermissionChoice {
+    /** The key that selects this row, as printed: "1"…"9". */
+    key: string;
+    optionId: string;
+    label: string;
+    /** A lasting consequence the label alone does not spell out. */
+    note?: string;
+}
+/**
+ * Provider text, made safe to draw.
+ *
+ * Titles and tool inputs arrive from another process and can carry newlines,
+ * escapes and ANSI. Collapsing whitespace is not cosmetic here: every row of
+ * the bar is one row, so an embedded newline would either be drawn literally or
+ * silently shift every row below it.
+ */
+export declare function clean(value: string): string;
+/**
+ * The offered options, numbered in the order they were offered.
+ *
+ * Capped at nine because the key is a single digit and a tenth option would
+ * advertise a key that does not exist. The provider's own wording is kept: it
+ * is what carries the scope ("…and don't ask again for python3 - commands"),
+ * and rewriting it would be guessing at a meaning it already states.
+ */
+export declare function permissionChoices(request: RuntimePermissionRequest): PermissionChoice[];
+/** How many impact rows the bar will draw, so the layout can reserve them. */
+export declare const MAX_IMPACT_ROWS = 2;
+/**
+ * What the tool is about to do that its own one-line title does not say.
+ *
+ * The bar draws `request.title` first: it is the provider's own summary of the
+ * call, and for a shell tool it *is* the command. What it cannot say is how much
+ * is behind that first line — the old overlay dumped `input` as JSON and clipped
+ * it after three rows, which always landed inside the escape sequences, so the
+ * one readable thing was the one thing that had already been said. The facts
+ * here are what is genuinely additional: the size of the script, the size of the
+ * edit.
+ */
+export declare function describeImpact(request: RuntimePermissionRequest, width: number): string[];
+/**
+ * Move the highlighted row, wrapping at both ends.
+ *
+ * `undefined` means nothing is highlighted yet, and that is deliberate: an
+ * `enter` on a bar that already points at something would be a one-keystroke
+ * grant for a request the user never read. Starting with no selection makes
+ * `enter` alone inert, so committing always takes an explicit move first.
+ */
+export declare function moveCursor(cursor: number | undefined, delta: number, total: number): number | undefined;
+/** Jump to a numbered row, or `undefined` when the digit names nothing. */
+export declare function jumpCursor(digit: string, total: number): number | undefined;
+/**
+ * The requests queued behind the one on screen, named.
+ *
+ * "2 pending" alone was the old bar's whole account of the others, which told
+ * the user that something else was waiting without telling them what — so the
+ * count could not be acted on until the front one was decided. Three is the
+ * most that stays readable on one row; the rest collapse into a count.
+ */
+export declare function waitingLine(rest: readonly RuntimePermissionRequest[]): string | undefined;
+/** Rows the permission bar occupies: header, title, impact, options, hint. */
+export declare function permissionBarRows(request: RuntimePermissionRequest, width: number, rest?: readonly RuntimePermissionRequest[]): number;
+export type FormKind = "choice" | "multi" | "boolean" | "number" | "text";
+export interface FormChoice {
+    value: string;
+    title: string;
+    description?: string;
+}
+export interface FormBounds {
+    min?: number;
+    max?: number;
+    minItems?: number;
+    maxItems?: number;
+    minLength?: number;
+    maxLength?: number;
+}
+export interface FormField {
+    key: string;
+    title: string;
+    description?: string;
+    required: boolean;
+    kind: FormKind;
+    choices: FormChoice[];
+    bounds: FormBounds;
+}
+/** A committed field value. Numbers are held as the text typed, converted on submit. */
+export type FormValue = string | boolean | string[];
+export interface FormState {
+    /** Index of the focused field. */
+    field: number;
+    /** Highlighted choice per field, so moving between fields remembers it. */
+    picks: Record<string, number>;
+    values: Record<string, FormValue>;
+}
+/**
+ * The question's schema as a list of fields to edit.
+ *
+ * Order is the schema's own: a form that reorders its questions is asking them
+ * in a different order than the agent wrote them, and the agent wrote them in
+ * the order the answer makes sense in.
+ */
+export declare function formFields(request: RuntimeQuestionRequest): FormField[];
+/** The human form of a field's limits, or `undefined` when it has none. */
+export declare function boundsText(field: FormField): string | undefined;
+export declare function initialForm(): FormState;
+/** The field's value as the row draws it. */
+export declare function formValueText(field: FormField, state: FormState): string;
+/** The highlighted choice index, clamped to the options that exist. */
+export declare function pickFor(state: FormState, field: FormField): number;
+export declare function movePick(state: FormState, field: FormField, delta: number): FormState;
+export declare function jumpPick(state: FormState, field: FormField, digit: string): FormState;
+export declare function toggleChoice(state: FormState, field: FormField): FormState;
+export declare function toggleBoolean(state: FormState, field: FormField): FormState;
+/**
+ * Take the text in the prompt as the focused field's value.
+ *
+ * The prompt *is* the editor for a text field — it already owns the caret, the
+ * wrapping and the paste handling — so there is no second buffer to keep in
+ * sync. The only cost is that the value has to be lifted out of the prompt
+ * before the focus moves away, which is what this does.
+ */
+export declare function withDraft(fields: FormField[], state: FormState, draft: string): FormState;
+/**
+ * Move the focus, handing back the text the new field should show.
+ *
+ * Both halves happen together because they are one operation: a caller that
+ * saved the draft but forgot to load the next field's value would silently
+ * empty a field the user had already answered.
+ */
+export declare function focusField(fields: FormField[], state: FormState, index: number): {
+    state: FormState;
+    draft: string;
+};
+/** Commit a highlighted choice into the value, for fields picked rather than typed. */
+export declare function commitField(fields: FormField[], state: FormState): FormState;
+/** The answer to send, with numbers parsed out of the text they were typed as. */
+export declare function formContent(fields: FormField[], state: FormState): Record<string, string | number | boolean | string[]>;
+export declare function formComplete(fields: FormField[], state: FormState): boolean;
+/** Rows a field list may occupy before it scrolls. */
+export declare const MAX_FORM_FIELDS = 6;
+/** Rows the question form occupies: header, message, fields, detail, hint. */
+export declare function questionBarRows(fields: FormField[]): number;
+/** The one interaction on screen, whichever kind it is. */
+export type InteractionLike = {
+    kind: "permission";
+    request: RuntimePermissionRequest;
+} | {
+    kind: "question";
+    request: RuntimeQuestionRequest;
+};
+/** Rows the docked bar asks the layout for, whichever request is in front. */
+export declare function interactionRows(interactions: readonly InteractionLike[], width: number): number;

package/dist/tui/layout.d.ts

@@ -25,6 +25,23 @@ export declare const MAX_RAIL_ROWS = 2;
 export declare const MAX_MENU_ROWS = 7;
 /** Queued follow-ups sit above the prompt; more than a few would crowd the stream. */
 export declare const MAX_QUEUE_ROWS = 3;
+/**
+ * The most rows the interaction bar is ever allowed to occupy.
+ *
+ * An agent blocked on a permission or a question is the one thing on screen
+ * worth acting on, so its bar is allowed more room than a queue or a palette —
+ * but not unlimited: it is docked *beside* the stream, and a bar tall enough to
+ * push the stream out would undo the reason it was docked.
+ */
+export declare const MAX_INTERACTION_ROWS = 10;
+/**
+ * The fewest rows worth docking the bar for.
+ *
+ * Header, title, one option and the hint is the least that can be read and acted
+ * on. Below that the bar would be a header with no choices under it, which is
+ * worse than leaving the stream alone and deciding by command.
+ */
+export declare const MIN_INTERACTION_ROWS = 4;
 export interface LayoutInput {
     columns: number;
     rows: number;
@@ -36,6 +53,23 @@ export interface LayoutInput {
     menuRows: number;
     /** Rows the queued follow-ups are asking for. */
     queueRows?: number;
+    /**
+     * Rows the interaction bar is asking for.
+     *
+     * It docks above the prompt rather than replacing the body, so its rows come
+     * out of the same budget as every other piece of chrome — an unbudgeted row
+     * here would show up as a stream pane that silently loses its last line.
+     */
+    interactionRows?: number;
+    /**
+     * Rows the prompt is asking for.
+     *
+     * The prompt wraps, so a long input makes it grow — one row per line typed
+     * past the terminal's width. Left out, it is the one row it used to be, so a
+     * caller that has not measured the text keeps the old budget rather than
+     * silently reserving nothing.
+     */
+    promptRows?: number;
     /** Whether a command result is waiting to be shown. */
     notice: boolean;
     /** A past turn is open for reading, which costs a banner row. */
@@ -74,6 +108,7 @@ export interface Layout {
     streamWidth: number;
     menuRows: number;
     queueRows: number;
+    interactionRows: number;
 }
 /**
  * How many rows the rail occupies given the widths of the cells it draws.