@aiwayds/dsh-tui-pi 0.1.0

package/lib/sessions.js

@@ -0,0 +1,253 @@
+/**
+ * Session TUI overlays: the `/session` info panel and the `/resume`
+ * persisted-session picker — terminal counterparts of the web surface's
+ * session management. Both follow the pi SelectList overlay pattern
+ * (`showOverlay` + `restoreFocus` on close); the info panel is a one-shot
+ * read-only component in the style of settings' ReadOnlyViewer.
+ */
+import { getKeybindings, SelectList, } from '@earendil-works/pi-tui';
+import { basename } from 'node:path';
+import { wrapFramedOverlay } from "./frame.js";
+import { ansiFg, BOLD, RESET } from "./theme/index.js";
+import { clipToWidth, visibleWidth } from "./text.js";
+/** Label column width for the key-value rows (longest: "cache read/write"). */
+const LABEL_WIDTH = 12;
+/** One-shot read-only panel; Esc/Enter hides the overlay and resolves. */
+class SessionInfoPanel {
+    theme;
+    data;
+    onClose;
+    constructor(theme, data, onClose) {
+        this.theme = theme;
+        this.data = data;
+        this.onClose = onClose;
+    }
+    invalidate() { }
+    render(width) {
+        const fg = (hex) => (text) => ansiFg(hex) + text + RESET;
+        const p = this.theme.palette;
+        const lines = [
+            fg(p.accent)(BOLD + 'ⓘ session' + RESET),
+            '',
+        ];
+        const id = this.data.id;
+        if (id === undefined) {
+            lines.push(fg(p.fgDefault)('  no active session — send a prompt or /resume one'));
+        }
+        else {
+            const max = Math.max(2, width - LABEL_WIDTH - 4);
+            const clip = (text) => clipToWidth(text, max);
+            const row = (label, value) => {
+                lines.push(fg(p.fgMuted)(label.padEnd(LABEL_WIDTH)) + fg(p.fgDefault)(clip(value)));
+            };
+            const shortId = clipToWidth(id, 8);
+            row('session', shortId);
+            if (visibleWidth(id) > 8) {
+                lines.push('  ' + ' '.repeat(LABEL_WIDTH) + fg(p.fgSubtle)(clip(id)));
+            }
+            row('cwd', this.data.cwd ?? '—');
+            row('created', this.data.createdAt === undefined ? '—' : new Date(this.data.createdAt).toLocaleString());
+            row('model', this.data.model ?? '—');
+            row('think', this.data.effort ?? '—');
+            row('status', this.data.status === 'running' ? fg(p.accent)(this.data.status) : this.data.status);
+            row('messages', String(this.data.msgCount));
+            row('tool calls', String(this.data.toolCallCount));
+            row('tokens in', String(this.data.inputTokens));
+            row('tokens out', String(this.data.outputTokens));
+            row('cache read', String(this.data.cacheReadTokens));
+            row('cache write', String(this.data.cacheWriteTokens));
+            row('events', this.data.eventCount === undefined ? '—' : String(this.data.eventCount));
+            const parent = this.data.parentSession;
+            row('parent', parent === undefined ? '—' : clipToWidth(parent, 8));
+        }
+        lines.push('');
+        lines.push(fg(p.fgSubtle)('  Esc to close'));
+        return lines;
+    }
+    handleInput(data) {
+        if (getKeybindings().matches(data, 'tui.select.cancel') || getKeybindings().matches(data, 'tui.select.confirm')) {
+            this.onClose();
+        }
+    }
+}
+/**
+ * Open the `/session` info panel; resolves when the user closes it. Focus
+ * returns to `restoreFocus` on close — it must re-focus the CURRENT editor
+ * instance, which may have been rebuilt under a theme hot-swap while the
+ * panel was open (pi-tui's hide would otherwise restore focus to the stale
+ * pre-overlay editor and swallow subsequent input).
+ */
+export async function showSessionInfo(tui, theme, data, restoreFocus) {
+    await new Promise(resolve => {
+        const panel = new SessionInfoPanel(theme, data, () => {
+            overlay.hide();
+            restoreFocus();
+            resolve();
+        });
+        // maxHeight only ever slices (never stretches), and the framed overlay
+        // needs 4 extra rows for its borders: cap high so the bottom border
+        // survives on small terminals (24 rows: 19 panel rows + 4 frame rows).
+        const overlay = tui.showOverlay(wrapFramedOverlay(theme, panel), { width: '70%', maxHeight: '100%' });
+    });
+}
+/**
+ * How many of the most recent candidates get a first-message preview before
+ * the picker opens. Older sessions fall back to the header label, so the
+ * picker stays fast even with a long history.
+ */
+const PREVIEW_SESSION_CAP = 30;
+/** Concurrent `inspect` calls while enriching previews. */
+const PREVIEW_CONCURRENCY = 6;
+/** Hard character cap for a preview string; the list column clips it further. */
+const PREVIEW_MAX_CHARS = 140;
+/** Join the text blocks of a message's content into one trimmed string. */
+function textOfContent(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    let text = '';
+    for (const block of content) {
+        if (block && typeof block === 'object' && block.type === 'text') {
+            const blockText = block.text;
+            if (typeof blockText === 'string')
+                text += blockText + ' ';
+        }
+    }
+    return text.trim();
+}
+/**
+ * The session's "first sentence": the first direct human prompt, falling
+ * back to the first non-injected user-role text (goal/cron/recall prompts),
+ * then the first assistant message. Synthetic context injects (workspace
+ * instructions, runtime reminders) are skipped entirely — they precede the
+ * first real prompt and read as noise.
+ */
+export function previewOfEvents(events) {
+    let fallbackUser;
+    let fallbackAssistant;
+    for (const event of events) {
+        if (event.type === 'user/message') {
+            const message = event.data;
+            const text = textOfContent(message?.content);
+            if (!text)
+                continue;
+            const kind = message?.source?.kind;
+            if (kind === 'user')
+                return text;
+            if (kind === 'tool' || kind === 'plugin' || kind === 'agent-instructions')
+                continue;
+            if (fallbackUser === undefined)
+                fallbackUser = text;
+        }
+        else if (event.type === 'assistant/message') {
+            const message = event.data.message;
+            const text = textOfContent(message?.content);
+            if (text && fallbackAssistant === undefined)
+                fallbackAssistant = text;
+        }
+    }
+    return fallbackUser ?? fallbackAssistant;
+}
+/** Collapse control chars/whitespace and clip a raw message into a one-line preview. */
+export function normalizePreview(text, maxChars = PREVIEW_MAX_CHARS) {
+    const oneLine = text.replace(/[\x00-\x1f\x7f]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return oneLine.length <= maxChars ? oneLine : `${oneLine.slice(0, maxChars)}…`;
+}
+/** Best-effort first-message preview per session id; failures map to undefined. */
+async function loadSessionPreviews(persistence, ids) {
+    const previews = new Map();
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(PREVIEW_CONCURRENCY, ids.length) }, async () => {
+        while (cursor < ids.length) {
+            const index = cursor++;
+            const id = ids[index];
+            let preview;
+            try {
+                const { events } = await persistence.inspect(id);
+                const text = previewOfEvents(events);
+                if (text)
+                    preview = normalizePreview(text);
+            }
+            catch {
+                preview = undefined;
+            }
+            previews.set(String(id), preview);
+        }
+    });
+    await Promise.all(workers);
+    return previews;
+}
+/**
+ * Validate one persisted session's log without publishing it — the /resume
+ * pre-check: a corrupt target must be rejected BEFORE the current live agent
+ * is torn down. Throws when persistence is missing or the log fails to load.
+ */
+export async function inspectPersistedSession(ctx, id) {
+    const persistence = ctx.get('sessionPersistence');
+    if (persistence === undefined) {
+        throw new Error('Session persistence is not configured in this profile.');
+    }
+    return await persistence.inspect(id);
+}
+/**
+ * Open the persisted-session picker. Resolves with the picked session,
+ * `cancelled` when dismissed, or `empty` when no other session exists.
+ * Throws when the profile has no persistence backend. Focus returns to
+ * `restoreFocus` on close.
+ */
+export async function pickPersistedSession(ctx, tui, theme, excludeSessionId, restoreFocus) {
+    const persistence = ctx.get('sessionPersistence');
+    if (persistence === undefined) {
+        throw new Error('Session persistence is not configured in this profile.');
+    }
+    let headers;
+    try {
+        headers = await persistence.list();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to list persisted sessions: ${message}`);
+    }
+    const candidates = headers
+        // Subagent children carry a persisted delegation depth — resuming one as
+        // this TUI's main conversation would misplace it in the recursion budget.
+        .filter(header => header.origin !== 'subagent')
+        .filter(header => String(header.id) !== excludeSessionId)
+        .sort((a, b) => b.createdAt - a.createdAt);
+    if (candidates.length === 0)
+        return { kind: 'empty' };
+    // Enrich the most recent candidates with their first-message preview so the
+    // rows are distinguishable at a glance; older ones fall back to the header
+    // label (cwd + short id).
+    const previews = await loadSessionPreviews(persistence, candidates.slice(0, PREVIEW_SESSION_CAP).map(header => header.id));
+    const items = candidates.map(header => {
+        const id = String(header.id);
+        const preview = previews.get(id);
+        return {
+            value: id,
+            label: preview ?? `${basename(header.cwd ?? '?')} · ${clipToWidth(id, 8)}`,
+            description: `${new Date(header.createdAt).toLocaleString()} · ${clipToWidth(id, 8)} · ${header.cwd ?? 'no cwd'}`,
+        };
+    });
+    return new Promise(resolve => {
+        // Wide primary column so previews (often CJK) get room before the time/cwd
+        // description column starts.
+        const list = new SelectList(items, 12, theme.selectList, { minPrimaryColumnWidth: 24, maxPrimaryColumnWidth: 60 });
+        list.setSelectedIndex(0);
+        // Framed overlay: 13 list rows + 4 frame rows fit inside 75% of 24 rows.
+        const overlay = tui.showOverlay(wrapFramedOverlay(theme, list), { width: '80%', maxHeight: '75%' });
+        const finish = (picked) => {
+            overlay.hide();
+            restoreFocus();
+            resolve(picked === undefined
+                ? { kind: 'cancelled' }
+                : { kind: 'picked', id: picked.id, header: picked });
+        };
+        list.onSelect = item => {
+            finish(candidates.find(header => String(header.id) === item.value));
+        };
+        list.onCancel = () => finish(undefined);
+    });
+}
+//# sourceMappingURL=sessions.js.map

package/lib/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"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"}

package/lib/settings.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Text-based settings browser — the terminal counterpart of the web GUI's
+ * settings surface (schema-form driven there, pi-tui overlays here).
+ *
+ * Walks `ctx.settings.describe()` (registered namespaces → serialized
+ * schemastery schemas → resolved values) and renders it as nested
+ * SettingsList overlays, one level per schema depth:
+ *
+ *   level 0   category list (searchable): general / models / plugins / agent,
+ *             then `other` for unmapped namespaces. Namespace→category comes
+ *             from a static mapping (categorizeNamespaces) mirroring the web
+ *             settings page: the web client slots namespaces into categories
+ *             client-side and the data plane carries no category field, so
+ *             the mapping is maintained here by hand; `other` is hidden when
+ *             empty.
+ *   level 1   namespace list for the chosen category (searchable);
+ *             description shows applies timing. The Models category is
+ *             special-cased: it lists configured llm-pi-ai providers (label,
+ *             model summary, API-key state) instead of the raw namespace —
+ *             the original schema surface is hidden — plus dedicated
+ *             llm-deepseek / agent-default-model rows and an add-provider
+ *             flow (built-in directory → one API key → write)
+ *   level 2+  schema walk, dispatched on node type:
+ *             - object/dict → drill in (nested list; dicts get an add-key row)
+ *             - boolean / all-literal union → Enter cycles the value
+ *             - string/number/mixed union → inline Input editor
+ *             - array / literal / const / unknown → read-only viewer
+ *             - role('secret') fields are masked and edited without prefill
+ *             - every group row resets its subtree to defaults (Esc confirms)
+ *
+ * Writes go through `settings.mutate(ns, pathOps, expectedRevision)` so the
+ * user layer is edited by path without restating sections the UI never saw;
+ * the descriptor (and with it the revision) is re-read after every committed
+ * write, and failed writes revert the on-screen row and surface the error.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SchemaNode } from '@deepseek-ai/dsh-client-schema-form';
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type TuiTheme } from './theme/index.ts';
+export interface SettingsCategory {
+    id: string;
+    label: string;
+    namespaces: readonly string[];
+}
+/**
+ * Static namespace→category mapping, mirroring the web settings page's
+ * client-side slot structure (see the module header): the data plane carries
+ * no category field, so the slots are maintained here by hand. Namespaces not
+ * listed anywhere fall into the trailing `other` category.
+ *
+ * Labels are English-only: pi-tui's SettingsList search matches the label
+ * text, so English queries (model, shell, permission, …) hit directly.
+ */
+export declare const CATEGORY_MAP: readonly SettingsCategory[];
+/** Cap for a category row's member-name description line. */
+export declare const CATEGORY_DESC_MAX = 60;
+/**
+ * Group a describe() namespace list into ordered categories — general, models,
+ * plugins, agent, then `other` for everything unmapped. Categories with no
+ * members are dropped, including `other` when nothing falls into it.
+ *
+ * Defensive: duplicate namespaces in the input count once (a namespace
+ * registered twice must not be listed twice), and the `mapped` guard resolves
+ * CATEGORY_MAP overlap — a namespace listed in several categories goes to the
+ * first one, by category order.
+ */
+export declare function categorizeNamespaces(nses: string[]): SettingsCategory[];
+/**
+ * Description line for a category row: member names joined with ", ", capped
+ * at `max` columns. Namespace names are ASCII, so visible width equals char
+ * count here; the width-aware clip is used anyway so the cap semantics stay
+ * uniform with every other truncation in the TUI (an exactly-fitting string
+ * is kept whole, an ellipsis appears only when a column is free).
+ */
+export declare function categoryDescription(namespaces: readonly string[], max?: number): string;
+/** Human display for a resolved value (row value column; never re-scans anything). */
+export declare function formatValue(value: unknown): string;
+/** Display string for one union literal (the SettingsList cycle vocabulary). */
+export declare function displayValue(value: unknown): string;
+export interface UnionLiterals {
+    /** Raw literal values (strings, numbers, booleans, …) in schema order. */
+    values: unknown[];
+    /** Whether every union branch is a plain literal (cycle-eligible). */
+    all: boolean;
+}
+/** Extract literal branches of a union node (`literal`/`const` members). */
+export declare function unionLiterals(node: SchemaNode): UnionLiterals;
+/** One parsed Input outcome: commit a value, unset (reset), or reject. */
+export type ParseOutcome = {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'unset';
+} | {
+    kind: 'keep';
+} | {
+    kind: 'error';
+    error: string;
+};
+export declare function parseNumberInput(text: string): ParseOutcome;
+export declare function parseStringInput(text: string): ParseOutcome;
+/** Mixed (non-literal) union editing: JSON values, else a raw string branch. */
+export declare function parseUnionInput(text: string, node: SchemaNode): ParseOutcome;
+/** Seed value for a newly added dict key, from the inner schema. */
+export declare function defaultValueFor(node: SchemaNode): unknown;
+/** Description line for one field row (static — built once per row). */
+export declare function fieldDescription(node: SchemaNode, userOverride: boolean): string;
+/**
+ * Outcome of one commit write: an `error` (shown with the ✘ marker and
+ * danger color), a `notice` (shown as a plain hint — the write succeeded but
+ * needs a follow-up, e.g. "provider added, key must come from the
+ * environment"), or `undefined` (clean success → the editor closes). Exactly
+ * one of `error`/`notice` is set.
+ */
+export interface CommitResult {
+    error?: string;
+    notice?: string;
+}
+interface EditOptions {
+    title: string;
+    subtitle: string;
+    initial: string;
+    parse: (text: string) => ParseOutcome;
+    onCommit: (outcome: ParseOutcome) => Promise<CommitResult | undefined>;
+    onDone: () => void;
+    /** Error sink for writes that fail after the editor already closed (Esc). */
+    onError?: (message: string) => void;
+    /**
+     * Masked rendering: the value is shown as a dot row instead of plaintext
+     * (secrets never echo). Editing semantics are unaffected — the internal
+     * Input still owns input/delete/paste/submit.
+     */
+    secret?: boolean;
+}
+/** Inline value editor: title, current-value line, error/notice line, Input. */
+export declare class EditField implements Component {
+    private readonly tui;
+    private readonly options;
+    private readonly input;
+    private error;
+    /** Non-error commit message (success with a follow-up hint, see CommitResult). */
+    private notice;
+    /** Set while a commit write is in flight; extra Enter presses are ignored. */
+    private pending;
+    /** Guards onDone: exactly one terminal transition (submit success/keep/escape). */
+    private done;
+    private readonly fg;
+    private readonly fgMuted;
+    private readonly fgDanger;
+    /** Popup-surface background for the secret mask line. */
+    private readonly maskBg;
+    constructor(tui: TUI, options: EditOptions, theme: TuiTheme);
+    /** Terminal transition — runs the caller's onDone exactly once. */
+    private finish;
+    invalidate(): void;
+    render(width: number): string[];
+    /**
+     * Masked input line for secret fields: a dot row (one dot per visible
+     * column of the value, capped to the popup width) with a `▎` marker at the
+     * cursor position. The real cursor is not rendered — the marker only hints
+     * at the editing position; input semantics live in the internal Input.
+     */
+    private maskLine;
+    handleInput(data: string): void;
+}
+export interface OpenSettingsBrowserOptions {
+    ctx: Context;
+    tui: TUI;
+    theme: TuiTheme;
+    /** Focus target to restore when the browser closes (usually the editor). */
+    restoreFocus: () => void;
+    /** Error sink for writes that fail outside an inline editor (transcript). */
+    onError: (message: string) => void;
+}
+/**
+ * Open the modal settings browser. Resolves when it closes with the number of
+ * committed writes, or -1 when no namespace is registered (nothing to show).
+ */
+export declare function openSettingsBrowser(options: OpenSettingsBrowserOptions): Promise<number>;
+export {};