@alisio/alisio-code 0.1.0-alpha.9 → 0.1.1

package/dist/tui/artifact-preview.d.ts

@@ -0,0 +1,52 @@
+import type { ArtifactRef, UiBlock } from "@alisio/sdk";
+import { type Component } from "@earendil-works/pi-tui";
+export declare const PREVIEW_MAX_BYTES: number;
+export declare const PREVIEW_MAX_LINES = 2000;
+export declare const PREVIEW_MAX_ROWS = 200;
+export declare const PREVIEW_MAX_COLUMNS = 20;
+export type PreviewKind = "markdown" | "table" | "json" | "text";
+/** How an artifact previews in the terminal, or undefined when it only opens externally. */
+export declare function previewKind(artifact: ArtifactRef): PreviewKind | undefined;
+export interface Preview {
+    block: UiBlock;
+    truncated: boolean;
+    /** Table legend: `showing 200 of 12,480 rows · 20 of 31 columns`. */
+    legend?: string;
+}
+/**
+ * RFC 4180 rows (quotes, doubled quotes, newlines inside quotes, CRLF/LF/CR), up to `limit`, with
+ * the same parser the dataset ingestion uses (so the preview and `data_inspect` agree).
+ */
+export declare function parseDelimited(text: string, delimiter: string, limit?: number): {
+    rows: string[][];
+    total: number;
+    complete: boolean;
+};
+/** The preview of an artifact from its leading bytes (the caller reads them, bounded). */
+export declare function buildPreview(artifact: ArtifactRef, bytes: Uint8Array, fileBytes?: number): Preview;
+/** Reads the bytes a preview needs (never the whole of a large file). */
+export declare function loadPreview(artifact: ArtifactRef, path: string): Promise<Preview>;
+/**
+ * A bounded, scrollable preview panel: ↑/↓, PgUp/PgDn, Home/End scroll; `o` opens with the
+ * system app, `c` copies the path, `Esc` or `q` closes. The footer says `truncated` when cut.
+ */
+export declare class ArtifactPreview implements Component {
+    private readonly artifact;
+    private readonly preview;
+    private readonly options;
+    private offset;
+    private lines;
+    private renderedWidth;
+    constructor(artifact: ArtifactRef, preview: Preview, options: {
+        /** Rows available for the body (the panel adds a title and a footer). */
+        height: () => number;
+        open: () => void;
+        copy: () => void;
+        close: () => void;
+    });
+    invalidate(): void;
+    private page;
+    private clamp;
+    handleInput(data: string): void;
+    render(width: number): string[];
+}

package/dist/tui/artifact-preview.js

@@ -0,0 +1,212 @@
+/**
+ * Terminal preview of text-like artifacts (spec §16.4), shown in place of the `/artifacts` picker:
+ * Markdown (first 256 KiB), CSV/TSV as a table (200 rows × 20 columns, with a legend), JSON
+ * pretty-printed (256 KiB) and text/code with highlighting (2 000 lines). Dashboards, PDFs,
+ * images and office files never render here: they only open with the system app.
+ */
+import { open } from "node:fs/promises";
+import { CsvParser, decodeTextBytes, detectDelimiter } from "@alisio/core";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { terminalCapabilities } from "../banner.js";
+import { renderUiBlock } from "./components.js";
+import { style } from "./theme.js";
+export const PREVIEW_MAX_BYTES = 256 * 1024;
+export const PREVIEW_MAX_LINES = 2000;
+export const PREVIEW_MAX_ROWS = 200;
+export const PREVIEW_MAX_COLUMNS = 20;
+/** CSV bytes read to count rows for the legend (beyond: "more than N rows"). */
+const TABLE_SCAN_BYTES = 8 * 1024 * 1024;
+const extension = (name) => {
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+};
+/** How an artifact previews in the terminal, or undefined when it only opens externally. */
+export function previewKind(artifact) {
+    if (artifact.status !== "ready")
+        return undefined;
+    const ext = extension(artifact.fileName);
+    if (artifact.kind === "document" && (ext === "md" || ext === "markdown"))
+        return "markdown";
+    if (artifact.kind === "spreadsheet" && (ext === "csv" || ext === "tsv"))
+        return "table";
+    if (artifact.kind === "data")
+        return "json";
+    if (artifact.kind === "code")
+        return "text";
+    return undefined;
+}
+const LANGUAGES = {
+    py: "python",
+    js: "javascript",
+    ts: "typescript",
+    sql: "sql",
+    yaml: "yaml",
+    yml: "yaml",
+    xml: "xml",
+    r: "r",
+    json: "json",
+    geojson: "json",
+};
+/** Decodes at most `max` bytes as UTF-8 without a broken trailing character. */
+const decode = (bytes, max) => Buffer.from(bytes.subarray(0, max)).toString("utf8").replace(/�+$/, "");
+/**
+ * RFC 4180 rows (quotes, doubled quotes, newlines inside quotes, CRLF/LF/CR), up to `limit`, with
+ * the same parser the dataset ingestion uses (so the preview and `data_inspect` agree).
+ */
+export function parseDelimited(text, delimiter, limit = Number.POSITIVE_INFINITY) {
+    const rows = [];
+    let total = 0;
+    const parser = new CsvParser(delimiter, (row) => {
+        total++;
+        if (rows.length < limit)
+            rows.push(row);
+    });
+    parser.write(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    parser.end();
+    return { rows, total, complete: true };
+}
+const thousands = (n) => n.toLocaleString("en-US");
+/** The preview of an artifact from its leading bytes (the caller reads them, bounded). */
+export function buildPreview(artifact, bytes, fileBytes) {
+    const size = fileBytes ?? bytes.length;
+    const kind = previewKind(artifact) ?? "text";
+    const ext = extension(artifact.fileName);
+    if (kind === "markdown")
+        return {
+            block: { kind: "markdown", text: decode(bytes, PREVIEW_MAX_BYTES) },
+            truncated: size > PREVIEW_MAX_BYTES || bytes.length > PREVIEW_MAX_BYTES,
+        };
+    if (kind === "table") {
+        const scanned = bytes.length >= TABLE_SCAN_BYTES || size > bytes.length;
+        // UTF-8, UTF-16 (BOM) or windows-1252, and `;` or `|` as well as `,` and TAB, like ingestion.
+        const { text } = decodeTextBytes(bytes.subarray(0, TABLE_SCAN_BYTES), scanned);
+        const parsed = parseDelimited(text, ext === "tsv" ? "\t" : detectDelimiter(text.slice(0, 64 * 1024)), PREVIEW_MAX_ROWS + 1);
+        const [header = [], ...body] = parsed.rows;
+        const columns = header.length;
+        const rows = body.slice(0, PREVIEW_MAX_ROWS);
+        const dataRows = Math.max(0, parsed.total - 1);
+        const shownColumns = Math.min(columns, PREVIEW_MAX_COLUMNS);
+        const truncated = dataRows > rows.length || columns > shownColumns || scanned;
+        return {
+            block: {
+                kind: "table",
+                columns: header.slice(0, PREVIEW_MAX_COLUMNS),
+                rows: rows.map((row) => row.slice(0, PREVIEW_MAX_COLUMNS)),
+            },
+            truncated,
+            ...(truncated
+                ? {
+                    legend: `showing ${thousands(rows.length)} of ${scanned ? "more than " : ""}${thousands(dataRows)} rows · ${shownColumns} of ${columns} columns`,
+                }
+                : {}),
+        };
+    }
+    const text = decode(bytes, PREVIEW_MAX_BYTES);
+    const cutBytes = size > PREVIEW_MAX_BYTES || bytes.length > PREVIEW_MAX_BYTES;
+    if (kind === "json") {
+        let code = text;
+        if (!cutBytes)
+            try {
+                code = JSON.stringify(JSON.parse(text), null, 2);
+            }
+            catch {
+                /* Invalid JSON is shown as it is. */
+            }
+        return { block: { kind: "code", lang: "json", code }, truncated: cutBytes };
+    }
+    const lines = text.split(/\r?\n/);
+    const lang = LANGUAGES[ext];
+    return {
+        block: {
+            kind: "code",
+            code: lines.slice(0, PREVIEW_MAX_LINES).join("\n"),
+            ...(lang ? { lang } : {}),
+        },
+        truncated: cutBytes || lines.length > PREVIEW_MAX_LINES,
+    };
+}
+/** Reads the bytes a preview needs (never the whole of a large file). */
+export async function loadPreview(artifact, path) {
+    const handle = await open(path, "r");
+    try {
+        const { size } = await handle.stat();
+        const want = Math.min(size, (previewKind(artifact) === "table" ? TABLE_SCAN_BYTES : PREVIEW_MAX_BYTES) + 4);
+        const buffer = Buffer.alloc(want);
+        const { bytesRead } = await handle.read(buffer, 0, want, 0);
+        return buildPreview(artifact, buffer.subarray(0, bytesRead), size);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * A bounded, scrollable preview panel: ↑/↓, PgUp/PgDn, Home/End scroll; `o` opens with the
+ * system app, `c` copies the path, `Esc` or `q` closes. The footer says `truncated` when cut.
+ */
+export class ArtifactPreview {
+    artifact;
+    preview;
+    options;
+    offset = 0;
+    lines = [];
+    renderedWidth = 0;
+    constructor(artifact, preview, options) {
+        this.artifact = artifact;
+        this.preview = preview;
+        this.options = options;
+    }
+    invalidate() {
+        this.renderedWidth = 0;
+    }
+    page() {
+        return Math.max(3, this.options.height());
+    }
+    clamp() {
+        this.offset = Math.max(0, Math.min(this.offset, Math.max(0, this.lines.length - this.page())));
+    }
+    handleInput(data) {
+        if (matchesKey(data, Key.escape) || data === "q")
+            return this.options.close();
+        if (data === "o")
+            return this.options.open();
+        if (data === "c")
+            return this.options.copy();
+        if (matchesKey(data, Key.down))
+            this.offset++;
+        else if (matchesKey(data, Key.up))
+            this.offset--;
+        else if (matchesKey(data, Key.pageDown))
+            this.offset += this.page() - 1;
+        else if (matchesKey(data, Key.pageUp))
+            this.offset -= this.page() - 1;
+        else if (matchesKey(data, Key.home))
+            this.offset = 0;
+        else if (matchesKey(data, Key.end))
+            this.offset = Number.MAX_SAFE_INTEGER;
+        this.clamp();
+    }
+    render(width) {
+        if (width !== this.renderedWidth) {
+            const { unicode } = terminalCapabilities({ env: process.env, columns: width, tty: true });
+            this.lines = renderUiBlock(this.preview.block, width, unicode).map((line) => truncateToWidth(line, width));
+            this.renderedWidth = width;
+        }
+        this.clamp();
+        const page = this.page();
+        const end = Math.min(this.lines.length, this.offset + page);
+        const position = this.lines.length
+            ? `${this.offset + 1}–${end} of ${this.lines.length}`
+            : "empty";
+        const notes = [
+            position,
+            ...(this.preview.legend ? [this.preview.legend] : []),
+            ...(this.preview.truncated ? ["truncated"] : []),
+        ].join(" · ");
+        return [
+            truncateToWidth(style.bold(style.yellow(`Preview · ${this.artifact.fileName}`)), width),
+            ...this.lines.slice(this.offset, end),
+            truncateToWidth(style.dim(`  ${notes}`), width),
+            truncateToWidth(style.dim("  ↑↓ PgUp/PgDn Home/End · o open · c copy path · Esc close"), width),
+        ];
+    }
+}

package/dist/tui/artifacts.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Terminal presentation of artifacts and saved permissions (spec §16): the two-line announcement
+ * under a tool, `/artifacts` picker rows, filtering, the actions each artifact offers and the
+ * `/permissions` rows. Pure functions; `app.ts` wires them to pickers and the clipboard.
+ */
+import type { ArtifactKind, ArtifactRef, CapabilityGrantWire, InstallPreview } from "@alisio/sdk";
+export declare const kindLabel: (kind: ArtifactKind) => string;
+export declare const ARTIFACTS_HINT = "/artifacts to open, copy or reveal";
+export declare function formatSize(bytes: number): string;
+/** `~` for the home folder, then a cut in the MIDDLE so both ends of the path stay visible. */
+export declare function displayPath(path: string, home: string, max: number): string;
+/**
+ * The announcement of one artifact: `▤ Dashboard  name  48 KB` and, below, the real local path
+ * (or `[D]`-style ASCII icons when the terminal has no Unicode). Colors come from the theme,
+ * which is plain under `NO_COLOR`.
+ */
+export declare function artifactLines(artifact: ArtifactRef, options: {
+    path?: string;
+    width: number;
+    unicode: boolean;
+    home: string;
+}): string[];
+/** `3 min`, `2 h`, `5 d` (or `now`). */
+export declare function age(createdAt: number, now: number): string;
+/** One `/artifacts` picker row: `Dashboard  sales-dashboard.html  48 KB  4 min`. */
+export declare const artifactRow: (artifact: ArtifactRef, now: number) => string;
+/** Case-insensitive match of every filter word against name, title and kind label. */
+export declare function matchArtifact(artifact: ArtifactRef, filter: string): boolean;
+export type ArtifactAction = "preview" | "open" | "copy" | "reveal" | "export" | "sources" | "details" | "rerun" | "delete";
+/**
+ * The actions of the second `/artifacts` picker, only those that apply: `Preview here` for
+ * text-like kinds, `Copy to workspace…` unless `--read-only`, `Reveal analysis sources` for
+ * `python_run` outputs and `Rerun` when `python_run` is available. Dashboards, PDFs and images
+ * only open with the system app. An expired artifact (its folder was removed by retention) keeps
+ * `Details` and `Rerun` (the script and inputs usually remain); a deleted one has no actions.
+ */
+export declare function artifactActions(artifact: ArtifactRef, options?: {
+    readOnly?: boolean;
+    sources?: boolean;
+    rerun?: boolean;
+}): Array<{
+    value: ArtifactAction;
+    label: string;
+}>;
+/** `Details` of an artifact (provenance without paths or code), one `label  value` per row. */
+export declare function detailRows(artifact: ArtifactRef, provenance: Record<string, unknown>): Array<[string, string]>;
+/** `Python analysis · allowed for this session · since 10:42 (web)`. */
+export declare const permissionRow: (grant: CapabilityGrantWire) => string;
+/** Title of the `analysis.install` approval (once or deny only). */
+export declare const installApprovalTitle: (install: InstallPreview) => string;
+/** Body of the `analysis.install` approval: the packages, the download estimate and the network. */
+export declare function installApprovalDetail(install: InstallPreview): string;
+/** Title of a capability approval in the TUI picker. */
+export declare const capabilityApprovalTitle: (runtime: "managed" | "oci" | undefined) => string;

package/dist/tui/artifacts.js

@@ -0,0 +1,207 @@
+import { style } from "./theme.js";
+const LABELS = {
+    dashboard: "Dashboard",
+    document: "Document",
+    spreadsheet: "Spreadsheet",
+    image: "Image",
+    data: "Data",
+    code: "Text",
+    archive: "Archive",
+    file: "File",
+};
+const UNICODE = {
+    dashboard: "▤",
+    document: "¶",
+    spreadsheet: "▦",
+    image: "◩",
+    data: "◇",
+    code: "‹›",
+    archive: "▣",
+    file: "▢",
+};
+const ASCII = {
+    dashboard: "[D]",
+    document: "[M]",
+    spreadsheet: "[T]",
+    image: "[I]",
+    data: "[J]",
+    code: "[C]",
+    archive: "[Z]",
+    file: "[F]",
+};
+export const kindLabel = (kind) => LABELS[kind] ?? "File";
+export const ARTIFACTS_HINT = "/artifacts to open, copy or reveal";
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** `~` for the home folder, then a cut in the MIDDLE so both ends of the path stay visible. */
+export function displayPath(path, home, max) {
+    const sep = path.includes("\\") && !path.includes("/") ? "\\" : "/";
+    let shown = home && (path === home || path.startsWith(`${home}${sep}`))
+        ? `~${path.slice(home.length)}`
+        : path;
+    const chars = [...shown];
+    if (max >= 5 && chars.length > max) {
+        const keep = max - 1;
+        const head = Math.ceil(keep / 2);
+        shown = `${chars.slice(0, head).join("")}…${chars.slice(chars.length - (keep - head)).join("")}`;
+    }
+    return shown;
+}
+/**
+ * The announcement of one artifact: `▤ Dashboard  name  48 KB` and, below, the real local path
+ * (or `[D]`-style ASCII icons when the terminal has no Unicode). Colors come from the theme,
+ * which is plain under `NO_COLOR`.
+ */
+export function artifactLines(artifact, options) {
+    const icon = (options.unicode ? UNICODE : ASCII)[artifact.kind] ?? (options.unicode ? "▢" : "[F]");
+    const status = artifact.status !== "ready"
+        ? ` ${style.yellow(`(${artifact.status})`)}`
+        : artifact.partial
+            ? ` ${style.yellow("(partial)")}`
+            : "";
+    const lines = [
+        `  ${style.cyan(icon)} ${style.bold(kindLabel(artifact.kind))}  ${artifact.fileName}  ${style.gray(formatSize(artifact.bytes))}${status}`,
+    ];
+    if (options.path && artifact.status === "ready")
+        lines.push(`    ${style.gray(displayPath(options.path, options.home, Math.max(10, options.width - 4)))}`);
+    return lines;
+}
+/** `3 min`, `2 h`, `5 d` (or `now`). */
+export function age(createdAt, now) {
+    const seconds = Math.max(0, Math.round((now - createdAt) / 1000));
+    if (seconds < 60)
+        return "now";
+    if (seconds < 3600)
+        return `${Math.round(seconds / 60)} min`;
+    if (seconds < 86_400)
+        return `${Math.round(seconds / 3600)} h`;
+    return `${Math.round(seconds / 86_400)} d`;
+}
+/** One `/artifacts` picker row: `Dashboard  sales-dashboard.html  48 KB  4 min`. */
+export const artifactRow = (artifact, now) => `${kindLabel(artifact.kind).padEnd(11)}  ${artifact.fileName}  ${formatSize(artifact.bytes)}  ${age(artifact.createdAt, now)}${artifact.partial ? "  partial" : ""}${artifact.status === "expired" ? "  Expired" : artifact.status === "deleted" ? "  Deleted" : ""}`;
+/** Case-insensitive match of every filter word against name, title and kind label. */
+export function matchArtifact(artifact, filter) {
+    const haystack = `${artifact.fileName} ${artifact.title} ${kindLabel(artifact.kind)} ${artifact.kind}`.toLowerCase();
+    return filter
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((word) => haystack.includes(word));
+}
+/** Text-like kinds the terminal previews (Markdown, CSV/TSV, JSON, text/code). */
+function previewsHere(artifact) {
+    const ext = artifact.fileName.toLowerCase().split(".").pop() ?? "";
+    return ((artifact.kind === "document" && (ext === "md" || ext === "markdown")) ||
+        (artifact.kind === "spreadsheet" && (ext === "csv" || ext === "tsv")) ||
+        artifact.kind === "data" ||
+        artifact.kind === "code");
+}
+/**
+ * The actions of the second `/artifacts` picker, only those that apply: `Preview here` for
+ * text-like kinds, `Copy to workspace…` unless `--read-only`, `Reveal analysis sources` for
+ * `python_run` outputs and `Rerun` when `python_run` is available. Dashboards, PDFs and images
+ * only open with the system app. An expired artifact (its folder was removed by retention) keeps
+ * `Details` and `Rerun` (the script and inputs usually remain); a deleted one has no actions.
+ */
+export function artifactActions(artifact, options = {}) {
+    if (artifact.status === "deleted")
+        return [];
+    const rerun = options.rerun
+        ? [{ value: "rerun", label: "Rerun (same script and inputs)" }]
+        : [];
+    if (artifact.status !== "ready")
+        return [{ value: "details", label: "Details" }, ...rerun];
+    return [
+        ...(previewsHere(artifact) ? [{ value: "preview", label: "Preview here" }] : []),
+        { value: "open", label: "Open with default app" },
+        { value: "copy", label: "Copy path" },
+        { value: "reveal", label: "Reveal in folder" },
+        ...(options.readOnly ? [] : [{ value: "export", label: "Copy to workspace…" }]),
+        ...(options.sources ? [{ value: "sources", label: "Reveal analysis sources" }] : []),
+        { value: "details", label: "Details" },
+        ...rerun,
+        { value: "delete", label: "Delete" },
+    ];
+}
+/** `Details` of an artifact (provenance without paths or code), one `label  value` per row. */
+export function detailRows(artifact, provenance) {
+    const runtime = provenance.runtime;
+    const inputs = Array.isArray(provenance.inputs)
+        ? provenance.inputs
+        : [];
+    const text = (value) => (typeof value === "string" && value ? value : undefined);
+    const rows = [
+        ["Kind", kindLabel(artifact.kind)],
+        ["Created", new Date(artifact.createdAt).toLocaleString()],
+        [
+            "Size",
+            `${formatSize(artifact.bytes)}${artifact.fileCount > 1 ? ` · ${artifact.fileCount} files` : ""}`,
+        ],
+        ["Model", text(provenance.model)],
+        ["Provider", text(provenance.provider)],
+        [
+            "Runtime",
+            runtime
+                ? [
+                    runtime.mode,
+                    runtime.engine,
+                    runtime.python && `Python ${runtime.python}`,
+                    runtime.image && runtime.image.replace(/(@sha256:[a-f0-9]{12})[a-f0-9]+$/, "$1…"),
+                    runtime.extras?.join(", "),
+                ]
+                    .filter(Boolean)
+                    .join(" · ")
+                : undefined,
+        ],
+        [
+            "Inputs",
+            inputs.length
+                ? inputs.map((i) => `${i.name} (${String(i.sha256 ?? "").slice(0, 12)})`).join(", ")
+                : undefined,
+        ],
+        ["Execution", text(provenance.executionId)],
+        ["Rerun of", text(provenance.rerunOf)],
+        ["Partial", artifact.partial ? "yes" : undefined],
+        [
+            "Status",
+            artifact.status === "ready"
+                ? undefined
+                : artifact.status === "expired"
+                    ? "Expired (files removed by retention)"
+                    : artifact.status,
+        ],
+    ];
+    return rows.filter((row) => !!row[1]);
+}
+const CAPABILITY_LABELS = {
+    "analysis.run": "Python analysis",
+    "analysis.install": "Python packages",
+};
+/** `HH:MM` local time. */
+const clock = (time) => {
+    const date = new Date(time);
+    return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+};
+/** `Python analysis · allowed for this session · since 10:42 (web)`. */
+export const permissionRow = (grant) => `${CAPABILITY_LABELS[grant.capability] ?? grant.capability} · allowed for this session · since ${clock(grant.createdAt)} (${grant.source})`;
+/** Title of the `analysis.install` approval (once or deny only). */
+export const installApprovalTitle = (install) => `Install Python packages (${install.extras}; needs network)?`;
+/** Body of the `analysis.install` approval: the packages, the download estimate and the network. */
+export function installApprovalDetail(install) {
+    return [
+        `Optional Python packages for this analysis: ${install.packages.join(", ")}`,
+        `(+ dependencies: ${install.packageCount} pinned wheels in total).`,
+        `Download: about ${formatSize(install.estimatedBytes)}. This needs network access.`,
+        "Wheels only, hash-verified, installed into a private environment under Alisio's state folder; nothing is compiled.",
+        "This permission is never remembered: it asks every time.",
+    ].join("\n");
+}
+/** Title of a capability approval in the TUI picker. */
+export const capabilityApprovalTitle = (runtime) => runtime === "oci"
+    ? "Run Python analysis (container · no network)?"
+    : "Run Python analysis (managed · not sandboxed)?";

package/dist/tui/btw.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure state of the TUI `/btw` panel: a pending side question, its answer, and browsing earlier
+ * answers of the session. The panel lives in the picker slot and never touches the transcript.
+ *
+ * Keys: ←/→ earlier/later answer, ↑/↓ (and PgUp/PgDn) scroll a long answer, Esc cancels a pending
+ * question or closes the panel.
+ */
+import type { SideQuestionEntry } from "@alisio/sdk";
+import { scrollWindow } from "./scroll.ts";
+export declare const BTW_USAGE = "Usage: /btw <question>";
+export declare const BTW_DESCRIPTION = "Ask a side question about the current session without adding to the conversation.";
+export interface BtwState {
+    entries: SideQuestionEntry[];
+    /** Index of the entry on screen (ignored while `pending`). */
+    index: number;
+    /** A question waiting for its answer. */
+    pending?: {
+        question: string;
+        startedAt: number;
+    };
+    /** Why the last question failed (shown until the user navigates). */
+    error?: {
+        question: string;
+        message: string;
+    };
+    /** First answer line on screen. */
+    scroll: number;
+}
+export type BtwAction = {
+    type: "prev";
+} | {
+    type: "next";
+} | {
+    type: "scroll";
+    lines: number;
+} | {
+    type: "answered";
+    entries: SideQuestionEntry[];
+} | {
+    type: "failed";
+    message: string;
+};
+/** The browser for `/btw` without a question: the newest entry, or undefined when none. */
+export declare function btwBrowser(entries: SideQuestionEntry[]): BtwState | undefined;
+/** The panel while `question` is being answered (earlier entries stay browsable afterwards). */
+export declare function btwPending(entries: SideQuestionEntry[], question: string, now?: number): BtwState;
+export declare function reduceBtw(state: BtwState, action: BtwAction): BtwState;
+/** The entry on screen, if the panel is not pending or showing an error. */
+export declare function btwCurrent(state: BtwState): SideQuestionEntry | undefined;
+/** "2/5" for the entry on screen; empty while pending or on an error. */
+export declare function btwPosition(state: BtwState): string;
+/** Footer hints for the current state. */
+export declare function btwHints(state: BtwState, overflow: boolean): string;
+/** "model · 12 in · 3 out tokens" for an entry. */
+export declare function btwUsageLine(entry: SideQuestionEntry): string;
+/** The visible slice of `lines` for `scroll` (clamped) and whether more lines exist. */
+export declare const btwWindow: typeof scrollWindow;

package/dist/tui/btw.js

@@ -0,0 +1,76 @@
+import { scrollWindow } from "./scroll.js";
+export const BTW_USAGE = "Usage: /btw <question>";
+export const BTW_DESCRIPTION = "Ask a side question about the current session without adding to the conversation.";
+/** The browser for `/btw` without a question: the newest entry, or undefined when none. */
+export function btwBrowser(entries) {
+    return entries.length ? { entries, index: entries.length - 1, scroll: 0 } : undefined;
+}
+/** The panel while `question` is being answered (earlier entries stay browsable afterwards). */
+export function btwPending(entries, question, now = Date.now()) {
+    return {
+        entries,
+        index: Math.max(0, entries.length - 1),
+        pending: { question, startedAt: now },
+        scroll: 0,
+    };
+}
+export function reduceBtw(state, action) {
+    switch (action.type) {
+        case "prev":
+        case "next": {
+            if (state.pending || !state.entries.length)
+                return state;
+            const step = action.type === "prev" ? -1 : 1;
+            // Leaving an error shows the stored entries again (the newest first).
+            const from = state.error ? state.entries.length : state.index;
+            const index = Math.min(state.entries.length - 1, Math.max(0, from + step));
+            if (index === state.index && !state.error)
+                return state;
+            return { entries: state.entries, index, scroll: 0 };
+        }
+        case "scroll":
+            return { ...state, scroll: Math.max(0, state.scroll + action.lines) };
+        case "answered":
+            return {
+                entries: action.entries,
+                index: Math.max(0, action.entries.length - 1),
+                scroll: 0,
+            };
+        case "failed": {
+            const { pending: _pending, ...rest } = state;
+            return {
+                ...rest,
+                error: { question: state.pending?.question ?? "", message: action.message },
+                scroll: 0,
+            };
+        }
+    }
+}
+/** The entry on screen, if the panel is not pending or showing an error. */
+export function btwCurrent(state) {
+    return state.pending || state.error ? undefined : state.entries[state.index];
+}
+/** "2/5" for the entry on screen; empty while pending or on an error. */
+export function btwPosition(state) {
+    return btwCurrent(state) ? `${state.index + 1}/${state.entries.length}` : "";
+}
+/** Footer hints for the current state. */
+export function btwHints(state, overflow) {
+    if (state.pending)
+        return "Esc cancel";
+    const current = btwCurrent(state);
+    const hints = [
+        ...(state.entries.length > 1 || (state.error && state.entries.length)
+            ? ["←/→ earlier/later"]
+            : []),
+        ...(overflow ? ["↑/↓ scroll"] : []),
+        "Esc close",
+    ];
+    return current || state.error ? hints.join(" · ") : "Esc close";
+}
+/** "model · 12 in · 3 out tokens" for an entry. */
+export function btwUsageLine(entry) {
+    return `${entry.model} · ${entry.usage.input} in · ${entry.usage.output} out tokens${entry.truncated ? " · truncated" : ""}`;
+}
+/** The visible slice of `lines` for `scroll` (clamped) and whether more lines exist. */
+export const btwWindow = scrollWindow;