@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/terminal/tui/pages/annotatePage.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The annotate pane (`/annotate:` and `/annotate:annotate`, PROP-0018): the person works in a browser window or an app's own
+ * windows, and this page is the panel beside it. With the inspector on, hovering outlines a
+ * component and a click opens a comment popover with three choices: keep it as a note, add it to
+ * this session's queue, or send it to the agent now. The page lists the queue, what was sent and
+ * what the agent says it fixed, and the notes kept on the side.
+ */
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import type { MenuCall, MenuUi } from "../../pluginMenu.js";
+import type { TabInfo } from "../chrome.js";
+import { type ListRow } from "../list.js";
+import type { TerminalMouseInput } from "../mouse.js";
+import type { TerminalPage } from "../page.js";
+import type { Note, NoteTarget } from "../../../annotations/store.js";
+export type AnnotateStart = {
+    kind: 'web';
+    url?: string;
+} | {
+    kind: 'cdp';
+    endpoint: string;
+    name?: string;
+} | {
+    kind: 'bridge';
+    name?: string;
+};
+export interface AnnotatePageOptions {
+    theme(): Theme;
+    call: MenuCall;
+    ui: MenuUi & {
+        input(title: string, placeholder?: string): Promise<string | undefined>;
+    };
+    changed(): void;
+    start: AnnotateStart;
+    /** How often the inspector is asked for the person's next comment, in milliseconds. */
+    pollMs?: number;
+}
+type Row = {
+    kind: 'note';
+    note: Note;
+};
+export declare const ANNOTATE_ACTIONS: {
+    readonly reveal: "Show it in the window";
+    readonly send: "Send to the agent now";
+    readonly confirm: "Confirm sending it (it came from the page)";
+    readonly queue: "Ask the agent to fix it (add to queue)";
+    readonly dequeue: "Take it out of the queue";
+    readonly edit: "Edit the comment";
+    readonly resolve: "Resolve";
+    readonly delete: "Delete";
+};
+export declare function describeTarget(target: NoteTarget): string;
+/** Which section of the panel a note belongs in, for this session; null when it is not shown. */
+export declare function section(note: Note, sessionId: string | null): 'Queue' | 'Sent and fixed' | 'Saved' | null;
+export declare class AnnotatePage implements TerminalPage {
+    private readonly options;
+    presentation: "fullscreen";
+    private notes;
+    private sessionId;
+    private target;
+    private bridgeSnippet;
+    private error;
+    private busy;
+    private disposed;
+    private polling;
+    private timer;
+    private refreshes;
+    private readonly list;
+    constructor(options: AnnotatePageOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    tabs(): readonly TabInfo[];
+    activeTab(): string;
+    hint(): string;
+    activate(): void;
+    dispose(): void;
+    private start;
+    private refreshTarget;
+    reload(): Promise<void>;
+    rows(): ListRow<Row>[];
+    private queued;
+    /** Polls the inspector for the person's next comment, and the notes every few seconds. */
+    private schedule;
+    private tick;
+    private toggleInspect;
+    private attempt;
+    sendQueue(): Promise<void>;
+    private chooseWindow;
+    private noteMenu;
+    handleMouse(event: TerminalMouseInput): import("@earendil-works/pi-tui").TuiMouseEventResult | undefined;
+    handleInput(data: string): boolean;
+    private header;
+    render(width: number, rows: number): string[];
+}
+export {};

package/dist/sdk/terminal/tui/pages/annotatePage.js

@@ -0,0 +1,341 @@
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import { FilterList } from "../list.js";
+const TABS = [{ id: 'annotate', title: 'Annotate' }];
+export const ANNOTATE_ACTIONS = {
+    reveal: 'Show it in the window',
+    send: 'Send to the agent now',
+    confirm: 'Confirm sending it (it came from the page)',
+    queue: 'Ask the agent to fix it (add to queue)',
+    dequeue: 'Take it out of the queue',
+    edit: 'Edit the comment',
+    resolve: 'Resolve',
+    delete: 'Delete'
+};
+const clip = (text, size) => (text.length > size ? `${text.slice(0, size - 1)}…` : text);
+export function describeTarget(target) {
+    if (target.kind === 'text')
+        return `“${clip(target.exact.replace(/\s+/g, ' '), 50)}”`;
+    if (target.kind === 'element')
+        return `<${target.tag}> ${clip(target.name || target.text || target.selector, 40)}`;
+    return 'whole page';
+}
+/** Which section of the panel a note belongs in, for this session; null when it is not shown. */
+export function section(note, sessionId) {
+    if (note.status === 'resolved')
+        return null;
+    const delivery = note.delivery;
+    if (delivery && delivery.sessionId === sessionId)
+        return delivery.state === 'queued' ? 'Queue' : 'Sent and fixed';
+    if (!delivery)
+        return 'Saved';
+    return null;
+}
+export class AnnotatePage {
+    options;
+    presentation = 'fullscreen';
+    notes;
+    sessionId = null;
+    target = null;
+    bridgeSnippet = null;
+    error;
+    busy = false;
+    disposed = false;
+    polling = false;
+    timer = null;
+    refreshes = 0;
+    list;
+    constructor(options) {
+        this.options = options;
+        this.list = new FilterList({
+            theme: options.theme, search: 'never', noun: ['note', 'notes'], empty: 'Nothing here yet. Press i and click a component in the window.',
+            onActivate: row => { if (row.data)
+                void this.noteMenu(row.data.note); }
+        });
+    }
+    get focused() { return this.list.focused; }
+    set focused(value) { this.list.focused = value; }
+    tabs() { return TABS; }
+    activeTab() { return 'annotate'; }
+    hint() {
+        return `${this.target?.inspecting ? 'i stop inspecting' : 'i inspect'} · s send queue · x unqueue · t window · Enter note · Esc close`;
+    }
+    activate() {
+        void this.start();
+    }
+    dispose() {
+        this.disposed = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        void this.options.call('terminal.annotations.stopInspect').catch(() => undefined);
+    }
+    async start() {
+        const { call } = this.options;
+        const start = this.options.start;
+        await this.attempt(async () => {
+            if (start.kind === 'web') {
+                const url = start.url ?? await this.options.ui.input('Page or dev server address', 'http://localhost:5173');
+                if (!url)
+                    return;
+                await call('terminal.annotations.open', { url });
+            }
+            else if (start.kind === 'cdp') {
+                await call('terminal.annotations.attach', { kind: 'cdp', endpoint: start.endpoint, ...(start.name ? { name: start.name } : {}) });
+            }
+            else {
+                const attached = await call('terminal.annotations.attach', { kind: 'bridge', ...(start.name ? { name: start.name } : {}) });
+                this.bridgeSnippet = attached.bridge?.snippet ?? null;
+            }
+            await this.refreshTarget();
+            if (this.target?.windows.length || start.kind !== 'bridge')
+                await this.toggleInspect(true);
+            return start.kind === 'bridge' && !this.target?.windows.length ? 'Load the bridge script in the app (shown at the top), then reload the app.' : undefined;
+        });
+        this.schedule();
+    }
+    async refreshTarget() {
+        this.target = await this.options.call('terminal.annotations.target');
+    }
+    async reload() {
+        try {
+            const result = await this.options.call('terminal.annotations.list');
+            this.notes = result.notes;
+            this.sessionId = result.sessionId;
+            this.error = undefined;
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+        }
+        if (this.disposed)
+            return;
+        this.list.setRows(this.rows());
+        this.options.changed();
+    }
+    rows() {
+        const order = ['Queue', 'Sent and fixed', 'Saved'];
+        const rows = [];
+        for (const group of order) {
+            for (const note of (this.notes ?? []).filter(entry => section(entry, this.sessionId) === group)) {
+                const delivery = note.delivery;
+                const state = !delivery ? describeTarget(note.target)
+                    : delivery.state === 'queued' ? `${describeTarget(note.target)}${delivery.confirm ? ' · confirm to send' : delivery.autoSend ? ' · sends when idle' : ''}`
+                        : delivery.state === 'fixed' ? `fixed: ${clip(delivery.summary ?? '', 50)}` : `sent · ${describeTarget(note.target)}`;
+                rows.push({
+                    id: `note:${note.id}`, label: clip(note.body.replace(/\s+/g, ' '), 60), group: group === 'Queue' ? `Queue (${this.queued().length})` : group,
+                    detail: state,
+                    tone: delivery?.state === 'fixed' ? 'success' : delivery?.confirm ? 'warning' : delivery?.state === 'queued' ? 'accent' : 'muted',
+                    data: { kind: 'note', note }
+                });
+            }
+        }
+        return rows;
+    }
+    queued() {
+        return (this.notes ?? []).filter(note => section(note, this.sessionId) === 'Queue');
+    }
+    /** Polls the inspector for the person's next comment, and the notes every few seconds. */
+    schedule() {
+        if (this.disposed)
+            return;
+        this.timer = setTimeout(() => void this.tick(), this.options.pollMs ?? 400);
+        this.timer.unref?.();
+    }
+    async tick() {
+        if (this.disposed)
+            return;
+        if (!this.polling) {
+            this.polling = true;
+            try {
+                let changed = ++this.refreshes % 5 === 0;
+                if (this.target?.inspecting) {
+                    const step = await this.options.call('terminal.annotations.next');
+                    if (step.message)
+                        this.options.ui.notify(step.message, 'info');
+                    if (step.note)
+                        changed = true;
+                    if (!step.active) {
+                        await this.refreshTarget();
+                        this.options.changed();
+                    }
+                }
+                else if (this.target?.kind === 'bridge' && !this.target.windows.length) {
+                    // Waiting for the app to load the bridge script.
+                    await this.refreshTarget();
+                    if (this.target.windows.length) {
+                        await this.toggleInspect(true);
+                        changed = true;
+                    }
+                }
+                if (changed)
+                    await this.reload();
+            }
+            catch (error) {
+                this.error = error instanceof Error ? error.message : String(error);
+                this.options.changed();
+            }
+            finally {
+                this.polling = false;
+            }
+        }
+        this.schedule();
+    }
+    async toggleInspect(on) {
+        await this.options.call(on ? 'terminal.annotations.inspect' : 'terminal.annotations.stopInspect');
+        await this.refreshTarget();
+        this.options.changed();
+    }
+    async attempt(work) {
+        if (this.busy)
+            return;
+        this.busy = true;
+        try {
+            const message = await work();
+            if (message)
+                this.options.ui.notify(message, 'info');
+            this.error = undefined;
+        }
+        catch (error) {
+            this.options.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+        finally {
+            this.busy = false;
+        }
+        await this.reload();
+    }
+    sendQueue() {
+        return this.attempt(async () => {
+            const waiting = this.queued();
+            if (!waiting.length)
+                return 'The queue is empty.';
+            const unconfirmed = waiting.filter(note => note.delivery?.confirm);
+            if (unconfirmed.length) {
+                if (!await this.options.ui.confirm(`Send ${waiting.length} note(s) to the agent?`, `${unconfirmed.length} came from the page's own scripts. Check that you wrote them.`))
+                    return;
+                for (const note of unconfirmed)
+                    await this.options.call('terminal.annotations.confirm', { id: note.id, expectedVersion: note.version });
+            }
+            const result = await this.options.call('terminal.annotations.send');
+            return result.state === 'sent' ? `Sent ${result.ids.length} note(s) to the agent.` : result.state === 'busy' ? 'The agent is working; the queue goes out when it finishes.' : 'Nothing was sent.';
+        });
+    }
+    chooseWindow() {
+        return this.attempt(async () => {
+            await this.refreshTarget();
+            const windows = this.target?.windows ?? [];
+            if (!windows.length)
+                return 'No window is open.';
+            const labels = windows.map(window => `${window.current ? '● ' : ''}${clip(window.title || window.url, 60)} — ${clip(window.url, 50)}`);
+            const choice = await this.options.ui.select('Inspect which window?', labels);
+            const index = choice ? labels.indexOf(choice) : -1;
+            if (index < 0)
+                return;
+            await this.options.call('terminal.annotations.selectWindow', { window: windows[index].id });
+            await this.refreshTarget();
+        });
+    }
+    async noteMenu(note) {
+        const { call, ui } = this.options;
+        const where = section(note, this.sessionId);
+        const choices = [
+            ANNOTATE_ACTIONS.reveal,
+            ...(where === 'Queue' ? [note.delivery?.confirm ? ANNOTATE_ACTIONS.confirm : ANNOTATE_ACTIONS.send, ANNOTATE_ACTIONS.dequeue] : [ANNOTATE_ACTIONS.queue]),
+            ANNOTATE_ACTIONS.edit,
+            ANNOTATE_ACTIONS.resolve,
+            ANNOTATE_ACTIONS.delete
+        ];
+        const choice = await ui.select(`${clip(note.source.app?.name ?? note.source.title ?? note.source.url, 50)} · ${describeTarget(note.target)}`, choices);
+        const id = note.id;
+        if (choice === ANNOTATE_ACTIONS.reveal)
+            return this.attempt(async () => {
+                const result = await call('terminal.annotations.reveal', { id });
+                return result.state === 'matched' ? 'Marked in the window.' : `The target is ${result.state}${result.reason ? `: ${result.reason}` : ''}.`;
+            });
+        if (choice === ANNOTATE_ACTIONS.queue)
+            return this.attempt(async () => {
+                await call('terminal.annotations.queue', { id, expectedVersion: note.version });
+                return 'Added to the queue.';
+            });
+        if (choice === ANNOTATE_ACTIONS.dequeue)
+            return this.attempt(async () => {
+                await call('terminal.annotations.dequeue', { id, expectedVersion: note.version });
+            });
+        if (choice === ANNOTATE_ACTIONS.confirm || choice === ANNOTATE_ACTIONS.send)
+            return this.attempt(async () => {
+                if (choice === ANNOTATE_ACTIONS.confirm)
+                    await call('terminal.annotations.confirm', { id, expectedVersion: note.version });
+                const result = await call('terminal.annotations.send', { ids: [id] });
+                return result.state === 'sent' ? 'Sent to the agent.' : result.state === 'busy' ? 'It goes to the agent when it finishes.' : undefined;
+            });
+        if (choice === ANNOTATE_ACTIONS.edit)
+            return this.attempt(async () => {
+                const body = await ui.input('Comment', note.body);
+                if (!body?.trim() || body === note.body)
+                    return;
+                await call('terminal.annotations.update', { id, expectedVersion: note.version, patch: { body } });
+            });
+        if (choice === ANNOTATE_ACTIONS.resolve)
+            return this.attempt(async () => {
+                await call('terminal.annotations.update', { id, expectedVersion: note.version, patch: { status: 'resolved' } });
+                return 'Resolved.';
+            });
+        if (choice === ANNOTATE_ACTIONS.delete)
+            return this.attempt(async () => {
+                if (!await ui.confirm('Delete this note?', 'It cannot be restored.'))
+                    return;
+                await call('terminal.annotations.delete', { id, expectedVersion: note.version });
+            });
+    }
+    handleMouse(event) {
+        return this.list.handleMouse(event);
+    }
+    handleInput(data) {
+        if (data === 'i') {
+            void this.attempt(() => this.toggleInspect(!this.target?.inspecting));
+            return true;
+        }
+        if (data === 's') {
+            void this.sendQueue();
+            return true;
+        }
+        if (data === 't') {
+            void this.chooseWindow();
+            return true;
+        }
+        if (data === 'x') {
+            const row = this.list.selected?.data;
+            if (row && section(row.note, this.sessionId) === 'Queue')
+                void this.attempt(async () => { await this.options.call('terminal.annotations.dequeue', { id: row.note.id, expectedVersion: row.note.version }); });
+            return true;
+        }
+        return this.list.handleInput(data);
+    }
+    header(width) {
+        const theme = this.options.theme();
+        const target = this.target;
+        const current = target?.windows.find(window => window.current);
+        const kind = !target ? 'Starting…' : target.kind === 'web' ? 'Browser window' : target.kind === 'cdp' ? `App · ${target.app?.name ?? ''} (DevTools)` : `App · ${target.app?.name ?? ''} (page bridge)`;
+        const lines = [
+            `${theme.bold(kind)}${current ? theme.fg('muted', ` · ${clip(current.title || current.url, 40)} · ${clip(current.url, 60)}`) : ''}`,
+            target?.inspecting
+                ? theme.fg('success', '● Inspecting: hover a component in the window and click it to comment.')
+                : theme.fg('dim', '○ Inspector off. Press i to turn it on.')
+        ];
+        if (this.bridgeSnippet && target?.kind === 'bridge') {
+            lines.push(theme.fg(target.windows.length ? 'dim' : 'warning', `Load in the app while developing: ${this.bridgeSnippet}`));
+        }
+        if (this.error)
+            lines.push(theme.fg('error', this.error));
+        lines.push('');
+        return lines.map(line => truncateToWidth(line, width, ''));
+    }
+    render(width, rows) {
+        const theme = this.options.theme();
+        if (width < 1 || rows < 1)
+            return [];
+        const header = this.header(width);
+        if (!this.notes)
+            return [...header, theme.fg('dim', 'Reading page notes…')].slice(0, rows);
+        const body = this.list.render(width, Math.max(1, rows - header.length));
+        return [...header, ...body].slice(0, rows).map(line => truncateToWidth(line, width, ''));
+    }
+}

package/dist/sdk/terminal/tui/pages/browserPage.d.ts

@@ -0,0 +1,87 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type BrowserRuntime, type BrowserSection, type BrowserSource } from "../../browser.js";
+import { type MenuCall, type MenuUi } from "../../pluginMenu.js";
+import type { TerminalMouseInput } from "../mouse.js";
+import type { TerminalPage } from "../page.js";
+import type { TerminalPermissionState } from "../runtime.js";
+export interface BrowserPageOptions {
+    theme(): Theme;
+    call: MenuCall;
+    ui: MenuUi & {
+        input(title: string, placeholder?: string): Promise<string | undefined>;
+        secretInput(title: string, placeholder?: string): Promise<string | undefined>;
+    };
+    runtime(): BrowserRuntime;
+    permissions(): Promise<TerminalPermissionState>;
+    setGlobalTool(tool: string, allowed: boolean): Promise<void>;
+    useSkill(name: string): void;
+    changed(): void;
+    section?: BrowserSection;
+    source?: BrowserSource;
+}
+export declare class BrowserPage implements TerminalPage {
+    private readonly options;
+    readonly presentation = "fullscreen";
+    readonly ownsNavigation = true;
+    private section;
+    private source;
+    private channel;
+    private local;
+    private focus;
+    private snapshot?;
+    private permissions?;
+    private error?;
+    private busy;
+    private disposed;
+    private generation;
+    private detail?;
+    private content?;
+    private contentOffset;
+    private contentTotal;
+    private contentRows;
+    private saved;
+    private readonly list;
+    private readonly actionList;
+    private toolbarHits;
+    private filterStart;
+    private filterRow;
+    private inspectorActionRow;
+    private actionRow;
+    private pointer;
+    constructor(options: BrowserPageOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    tabs(): {
+        id: "skills" | "tools" | "connections" | "plugins" | "variant" | "library" | "overview" | "foundation";
+        title: string;
+    }[];
+    activeTab(): string;
+    selectTab(id: string): void;
+    hint(): string;
+    activate(): void;
+    dispose(): void;
+    private load;
+    private perform;
+    private resources;
+    private discoverable;
+    private rows;
+    private fill;
+    private navigate;
+    private open;
+    private actionGroup;
+    private groupedActions;
+    private actions;
+    private read;
+    private showContent;
+    private managePlugin;
+    private configurePlugin;
+    private configureConnection;
+    private toolbar;
+    private toolbarActions;
+    private toolbarLabel;
+    handleInput(data: string): boolean;
+    handleMouse(event: TerminalMouseInput): import("@earendil-works/pi-tui").TuiMouseEventResult | undefined;
+    private description;
+    private renderInspector;
+    render(width: number, rows: number): string[];
+}