@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/terminal/toolName.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A tool or message id as a person reads it: `todo_write` becomes `TodoWrite`,
+ * `computer-screenshot` becomes `ComputerScreenshot`. Only the first letter of each part is
+ * raised, so a name that already carries capitals keeps them.
+ */
+export declare function toolDisplayName(name: string): string;

package/dist/sdk/terminal/toolName.js

@@ -0,0 +1,12 @@
+/**
+ * A tool or message id as a person reads it: `todo_write` becomes `TodoWrite`,
+ * `computer-screenshot` becomes `ComputerScreenshot`. Only the first letter of each part is
+ * raised, so a name that already carries capitals keeps them.
+ */
+export function toolDisplayName(name) {
+    return name
+        .split(/[^A-Za-z0-9]+/u)
+        .filter(part => part !== '')
+        .map(part => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join('');
+}

package/dist/sdk/terminal/trajectory.d.ts

@@ -0,0 +1,15 @@
+import type { RunEvent, RunRecord, TodoItem } from "../sessions/contracts.js";
+export type TerminalTrajectoryRun = Pick<RunRecord, 'id' | 'mode' | 'goal' | 'startedAt' | 'endedAt' | 'status'>;
+export interface TerminalTrajectorySnapshot {
+    run: TerminalTrajectoryRun;
+    events: RunEvent[];
+}
+/** The native conversation file is the terminal's boundary for this read-only view. */
+export declare function listTerminalTrajectoryRuns(root: string, sessionId: string, nativeSessionId: string | null): TerminalTrajectoryRun[];
+/** The todo of the latest reply in this native conversation, for a host's /todo view. */
+export declare function latestTerminalTodo(root: string, sessionId: string, nativeSessionId: string | null): {
+    runId: string;
+    todo: TodoItem[];
+};
+/** Read a run only when it belongs to both this terminal and its current native conversation. */
+export declare function readTerminalTrajectory(root: string, sessionId: string, nativeSessionId: string | null, runId: string, afterSequence?: number): TerminalTrajectorySnapshot;

package/dist/sdk/terminal/trajectory.js

@@ -0,0 +1,38 @@
+import { notFound } from "../core/errors.js";
+import { findRun, listRuns, readEvents } from "../sessions/runStore.js";
+import { todoOf } from "../tools/todo.js";
+function summary(run) {
+    return {
+        id: run.id,
+        mode: run.mode,
+        goal: run.goal,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        status: run.status
+    };
+}
+/** The native conversation file is the terminal's boundary for this read-only view. */
+export function listTerminalTrajectoryRuns(root, sessionId, nativeSessionId) {
+    if (!nativeSessionId)
+        return [];
+    return listRuns(root, { sessionId })
+        .filter(run => run.nativeSessionId === nativeSessionId)
+        .map(summary);
+}
+/** The todo of the latest reply in this native conversation, for a host's /todo view. */
+export function latestTerminalTodo(root, sessionId, nativeSessionId) {
+    if (!nativeSessionId)
+        return { runId: '', todo: [] };
+    const run = listRuns(root, { sessionId }).find(candidate => candidate.nativeSessionId === nativeSessionId && candidate.trigger !== 'side-question');
+    return run ? { runId: run.id, todo: todoOf(readEvents(root, run.id)) } : { runId: '', todo: [] };
+}
+/** Read a run only when it belongs to both this terminal and its current native conversation. */
+export function readTerminalTrajectory(root, sessionId, nativeSessionId, runId, afterSequence) {
+    if (!nativeSessionId || !Number.isSafeInteger(afterSequence ?? 0) || (afterSequence ?? 0) < 0)
+        throw notFound('Run');
+    const run = findRun(root, runId);
+    if (!run || run.sessionId !== sessionId || run.nativeSessionId !== nativeSessionId)
+        throw notFound('Run');
+    const events = readEvents(root, runId).filter(event => afterSequence === undefined || event.sequence > afterSequence);
+    return { run: summary(run), events };
+}

package/dist/sdk/terminal/tui/annotateCommand.d.ts

@@ -0,0 +1,7 @@
+import type { AnnotateStart } from "./pages/annotatePage.js";
+/** A typed page address: a bare host gets https, localhost gets http. */
+export declare function normalizeAddress(text: string): string;
+/** A typed DevTools port or loopback address. */
+export declare function normalizeDevTools(text: string): string;
+/** `/annotate:` accepts a page address, an app's DevTools port, or the page bridge. */
+export declare function parseAnnotate(argument: string): AnnotateStart | string;

package/dist/sdk/terminal/tui/annotateCommand.js

@@ -0,0 +1,36 @@
+/** A typed page address: a bare host gets https, localhost gets http. */
+export function normalizeAddress(text) {
+    const word = text.trim();
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(word))
+        return word;
+    return /^(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/.test(word) ? `http://${word}` : `https://${word}`;
+}
+/** A typed DevTools port or loopback address. */
+export function normalizeDevTools(text) {
+    const word = text.trim();
+    if (/^\d+$/.test(word))
+        return `http://127.0.0.1:${word}`;
+    if (/^(localhost|127\.0\.0\.1|\[::1\]):\d+$/.test(word))
+        return `http://${word}`;
+    return word;
+}
+/** `/annotate:` accepts a page address, an app's DevTools port, or the page bridge. */
+export function parseAnnotate(argument) {
+    const words = argument.trim().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return { kind: 'web' };
+    if (words[0] === '--app') {
+        const endpoint = words[1];
+        if (!endpoint)
+            return { kind: 'apps' };
+        const name = words.slice(2).join(' ');
+        return { kind: 'cdp', endpoint: normalizeDevTools(endpoint), ...(name ? { name } : {}) };
+    }
+    if (words[0] === '--bridge') {
+        const name = words.slice(1).join(' ');
+        return { kind: 'bridge', ...(name ? { name } : {}) };
+    }
+    if (words.length > 1 || words[0].startsWith('--'))
+        return 'Use /annotate: [url], /annotate: --app [port], or /annotate: --bridge.';
+    return { kind: 'web', url: normalizeAddress(words[0]) };
+}

package/dist/sdk/terminal/tui/annotateSend.d.ts

@@ -0,0 +1,30 @@
+import type { MenuCall } from "../pluginMenu.js";
+import type { Note } from "../../annotations/store.js";
+type SendResult = {
+    state: 'sent';
+    ids: string[];
+} | {
+    state: 'busy';
+    ids: string[];
+} | {
+    state: 'host';
+    ids: string[];
+} | {
+    state: 'empty';
+    ids: [];
+    unconfirmed?: number;
+};
+export interface AnnotateSendUi {
+    confirm(title: string, message: string): Promise<boolean>;
+}
+/** Unsent annotations of `sessionId`, oldest first. */
+export declare function unsent(notes: readonly Note[], sessionId: string | null): Note[];
+/**
+ * Sends every unsent annotation of this terminal's session, with `prompt` after them when given.
+ * Returns what to tell the person.
+ */
+export declare function sendUnsent(call: MenuCall, ui: AnnotateSendUi, options?: {
+    prompt?: string;
+}): Promise<string>;
+export declare function describeSend(result: SendResult, withPrompt?: boolean): string;
+export {};

package/dist/sdk/terminal/tui/annotateSend.js

@@ -0,0 +1,40 @@
+const count = (n) => `${n} annotation${n === 1 ? '' : 's'}`;
+/** Unsent annotations of `sessionId`, oldest first. */
+export function unsent(notes, sessionId) {
+    return notes
+        .filter((note) => note.status === 'open' && note.delivery?.state === 'pending' && note.delivery.sessionId === sessionId)
+        .sort((left, right) => left.delivery.queuedAt.localeCompare(right.delivery.queuedAt));
+}
+/**
+ * Sends every unsent annotation of this terminal's session, with `prompt` after them when given.
+ * Returns what to tell the person.
+ */
+export async function sendUnsent(call, ui, options = {}) {
+    const listed = await call('terminal.annotations.list');
+    const waiting = unsent(listed.notes, listed.sessionId);
+    if (!waiting.length) {
+        return options.prompt
+            ? 'No unsent annotations. Annotate something with /annotate: first, or send your request as a normal message.'
+            : 'Nothing to send. Annotate something first.';
+    }
+    const unconfirmed = waiting.filter((note) => note.delivery?.confirm);
+    if (unconfirmed.length) {
+        const yes = await ui.confirm(`Send ${count(waiting.length)} to the agent?`, `${count(unconfirmed.length)} came from the app's own page scripts, which could have written them. Check that the comments are yours.`);
+        if (!yes)
+            return 'Nothing was sent.';
+        await call('terminal.annotations.confirmAll');
+    }
+    const result = await call('terminal.annotations.send', options.prompt ? { prompt: options.prompt } : {});
+    return describeSend(result, !!options.prompt);
+}
+export function describeSend(result, withPrompt = false) {
+    if (result.state === 'sent')
+        return `Sent ${count(result.ids.length)} to the agent.`;
+    if (result.state === 'busy' && withPrompt)
+        return 'The agent is still working. Submit again when it finishes; your annotations stay unsent.';
+    if (result.state === 'busy')
+        return `The agent is working; ${count(result.ids.length)} go${result.ids.length === 1 ? 'es' : ''} out when it finishes.`;
+    if (result.state === 'host')
+        return `${count(result.ids.length)} handed to the app to send.`;
+    return result.unconfirmed ? `${count(result.unconfirmed)} still wait for your confirmation.` : 'Nothing to send.';
+}

package/dist/sdk/terminal/tui/chrome.d.ts

@@ -0,0 +1,68 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+/** Cells kept clear on each side of a row, the width of the composer's `❯` gutter. */
+export declare const CHROME_PAD = 2;
+/** Rows a frame spends on itself: header, footer and two rules. */
+export declare const CHROME_ROWS = 4;
+export declare const CENTER_DIALOG_PAD = 4;
+/** Terminal rows are roughly twice as tall as character columns, so 2 rows match 4 columns. */
+export declare const CENTER_DIALOG_VERTICAL_PAD = 2;
+export declare function safeText(text: string): string;
+/** Fills a selected row with the shared background without changing its text styling. */
+export declare function selectedRow(line: string, width: number, theme: Theme): string;
+/** Primary text on a selected row, explicit so no accent colour sits on the blue field. */
+export declare function selectionText(theme: Theme, text: string): string;
+/** Secondary text on a selected row: quieter than the label but still readable on the blue. */
+export declare function selectionMuted(theme: Theme, text: string): string;
+/** The width a surface's content is laid out in. */
+export declare function contentWidth(width: number): number;
+/** Content width after the four-cell inset on each side of a centered dialog. */
+export declare function centerDialogContentWidth(width: number): number;
+export declare function centerDialogVerticalPad(rows: number): number;
+/** Header and its following gap, plus fixed top and bottom padding, at the available height. */
+export declare function centerDialogChromeRows(rows: number): number;
+export declare function centerDialogBodyRows(rows: number): number;
+/** A centered dialog: plain title, muted Escape hint, and generous inset with no rules or footer. */
+export declare function centerDialogFrame({ title, body, width, rows, theme }: Pick<FrameInput, 'title' | 'body' | 'width' | 'theme'> & {
+    rows: number;
+}): string[];
+/** The divider above a block: the `warning` amber the slash-command list's divider uses. */
+export declare function blockRule(width: number, theme: Theme): string;
+/** The neutral rule that closes a block and frames a page, like the composer's own rules. */
+export declare function neutralRule(width: number, theme: Theme): string;
+/** A row indented by the chrome padding and clipped to the width. */
+export declare function padded(line: string, width: number): string;
+/** A bold title with an optional dim note at the right edge. */
+export declare function headerRow(title: string, meta: string | undefined, width: number, theme: Theme): string;
+export interface TabInfo {
+    id: string;
+    title: string;
+}
+/**
+ * The topmost row of a console page, or a page's sub-strip. Too narrow for every title, it
+ * collapses to the active one with its place: `‹ Accounts 1/7 ›`. `width` is the content width.
+ */
+export declare function tabIndexAt(tabs: readonly TabInfo[], width: number, x: number, kind?: 'top' | 'sub'): number | undefined;
+export declare function tabStrip(tabs: readonly TabInfo[], activeId: string, width: number, theme: Theme, kind?: 'top' | 'sub', hoveredId?: string): string;
+/** The hint row at the foot of a surface. */
+export declare function footerRow(text: string, width: number, theme: Theme): string;
+export interface FrameInput {
+    title: string;
+    meta?: string;
+    body: readonly string[];
+    footer: string;
+    width: number;
+    theme: Theme;
+}
+/** A block: amber rule, title, body, hint, neutral rule. It is as tall as its body. */
+export declare function blockFrame({ title, meta, body, footer, width, theme }: FrameInput): string[];
+/** Rows a page leaves for its body at a given terminal height. */
+export declare function pageBodyRows(rows: number): number;
+/** A page: title (or `headerLine`, such as a tab strip), rule, body padded to fill the screen, rule, hint. */
+export declare function pageFrame({ title, meta, body, footer, width, rows, theme, headerLine }: FrameInput & {
+    rows: number;
+    headerLine?: string;
+}): string[];
+/** A full-width two-pane list uses a 40/60 split once there is room to read both panes. */
+export declare function inspectorListWidth(width: number): number | undefined;
+/** Joins a list and passive detail pane without drawing a box around either. */
+export declare function splitColumns(left: readonly string[], right: readonly string[], leftWidth: number, width: number, rows: number, theme: Theme): string[];

package/dist/sdk/terminal/tui/chrome.js

@@ -0,0 +1,182 @@
+import { parseColor, stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { SELECTION_COLORS } from "./selection.js";
+/** Cells kept clear on each side of a row, the width of the composer's `❯` gutter. */
+export const CHROME_PAD = 2;
+/** Rows a frame spends on itself: header, footer and two rules. */
+export const CHROME_ROWS = 4;
+export const CENTER_DIALOG_PAD = 4;
+/** Terminal rows are roughly twice as tall as character columns, so 2 rows match 4 columns. */
+export const CENTER_DIALOG_VERTICAL_PAD = 2;
+export function safeText(text) {
+    return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f]/g, ' ');
+}
+/** Fills a selected row with the shared background without changing its text styling. */
+export function selectedRow(line, width, theme) {
+    if (width < 1)
+        return '';
+    const bounded = truncateToWidth(line, width, '');
+    return theme.bg('selectedBg', bounded + ' '.repeat(Math.max(0, width - visibleWidth(bounded))));
+}
+function selectionPalette(theme) {
+    return theme.appearance === 'light' ? SELECTION_COLORS.light : SELECTION_COLORS.dark;
+}
+/** Primary text on a selected row, explicit so no accent colour sits on the blue field. */
+export function selectionText(theme, text) {
+    return theme.style(text, { fg: parseColor(selectionPalette(theme).text) });
+}
+/** Secondary text on a selected row: quieter than the label but still readable on the blue. */
+export function selectionMuted(theme, text) {
+    return theme.style(text, { fg: parseColor(selectionPalette(theme).muted) });
+}
+/** The width a surface's content is laid out in. */
+export function contentWidth(width) {
+    return Math.max(2, width - CHROME_PAD * 2);
+}
+/** Content width after the four-cell inset on each side of a centered dialog. */
+export function centerDialogContentWidth(width) {
+    return Math.max(1, width - CENTER_DIALOG_PAD * 2);
+}
+export function centerDialogVerticalPad(rows) {
+    return Math.min(CENTER_DIALOG_VERTICAL_PAD, Math.max(0, Math.floor((Math.trunc(rows) - 2) / 2)));
+}
+/** Header and its following gap, plus fixed top and bottom padding, at the available height. */
+export function centerDialogChromeRows(rows) {
+    const pad = centerDialogVerticalPad(rows);
+    return pad * 2 + 2;
+}
+export function centerDialogBodyRows(rows) {
+    return Math.max(0, Math.trunc(rows) - centerDialogChromeRows(rows));
+}
+/** A centered dialog: plain title, muted Escape hint, and generous inset with no rules or footer. */
+export function centerDialogFrame({ title, body, width, rows, theme }) {
+    rows = Math.max(0, Math.trunc(rows));
+    if (width < 1 || rows < 1)
+        return [];
+    const pad = Math.min(CENTER_DIALOG_PAD, Math.floor(width / 2));
+    const verticalPad = centerDialogVerticalPad(rows);
+    const room = Math.max(0, width - pad * 2);
+    const name = truncateToWidth(safeText(title), Math.max(0, room - 4), '');
+    const heading = ' '.repeat(pad) + theme.fg('text', name) + ' '.repeat(Math.max(1, room - visibleWidth(name) - 3)) + theme.fg('muted', 'Esc');
+    const shown = body.slice(0, centerDialogBodyRows(rows)).map(line => truncateToWidth(' '.repeat(pad) + line, width, ''));
+    return [
+        ...Array.from({ length: verticalPad }, () => ''),
+        truncateToWidth(heading, width, ''),
+        '',
+        ...shown,
+        ...Array.from({ length: verticalPad }, () => '')
+    ].slice(0, rows);
+}
+/** The divider above a block: the `warning` amber the slash-command list's divider uses. */
+export function blockRule(width, theme) {
+    return width > 0 ? theme.fg('warning', '─'.repeat(width)) : '';
+}
+/** The neutral rule that closes a block and frames a page, like the composer's own rules. */
+export function neutralRule(width, theme) {
+    return width > 0 ? theme.fg('dim', '─'.repeat(width)) : '';
+}
+/** A row indented by the chrome padding and clipped to the width. */
+export function padded(line, width) {
+    return truncateToWidth(' '.repeat(Math.min(CHROME_PAD, width)) + line, width, '');
+}
+/** A bold title with an optional dim note at the right edge. */
+export function headerRow(title, meta, width, theme) {
+    const room = Math.max(0, width - CHROME_PAD * 2);
+    const name = truncateToWidth(safeText(title), room, '');
+    const note = meta ? truncateToWidth(safeText(meta), Math.max(0, room - visibleWidth(name) - 2), '') : '';
+    const gap = Math.max(0, room - visibleWidth(name) - visibleWidth(note));
+    return padded(theme.bold(theme.fg('accent', name)) + ' '.repeat(gap) + (note ? theme.fg('dim', note) : ''), width);
+}
+/**
+ * The topmost row of a console page, or a page's sub-strip. Too narrow for every title, it
+ * collapses to the active one with its place: `‹ Accounts 1/7 ›`. `width` is the content width.
+ */
+export function tabIndexAt(tabs, width, x, kind = 'top') {
+    if (x < 0 || x >= width || tabs.length === 0)
+        return undefined;
+    const labels = tabs.map(tab => kind === 'sub' ? safeText(tab.title) : ` ${safeText(tab.title)} `);
+    const gap = kind === 'sub' ? ' · ' : ' ';
+    const total = labels.reduce((sum, label) => sum + visibleWidth(label), 0) + Math.max(0, tabs.length - 1) * visibleWidth(gap);
+    if (total > width)
+        return undefined;
+    let cursor = 0;
+    for (let index = 0; index < labels.length; index += 1) {
+        const end = cursor + visibleWidth(labels[index]);
+        if (x < end)
+            return index;
+        if (index < labels.length - 1) {
+            const next = end + visibleWidth(gap);
+            if (x < next)
+                return x - end < next - x ? index : index + 1;
+            cursor = next;
+        }
+    }
+    return labels.length - 1;
+}
+export function tabStrip(tabs, activeId, width, theme, kind = 'top', hoveredId) {
+    if (width < 1 || !tabs.length)
+        return '';
+    const active = Math.max(0, tabs.findIndex(tab => tab.id === activeId));
+    const full = tabs.map((tab, index) => {
+        const title = safeText(tab.title);
+        const selected = index === active || tab.id === hoveredId;
+        if (kind === 'sub') {
+            if (index === active)
+                return theme.bold(selectionText(theme, title));
+            return tab.id === hoveredId ? theme.bg('selectedBg', theme.bold(selectionText(theme, title))) : theme.fg('dim', title);
+        }
+        return selected ? theme.bg('selectedBg', theme.bold(selectionText(theme, ` ${title} `))) : theme.fg('muted', ` ${title} `);
+    }).join(kind === 'sub' ? theme.fg('dim', ' · ') : ' ');
+    if (visibleWidth(full) <= width)
+        return full;
+    return truncateToWidth(theme.bg('selectedBg', theme.bold(selectionText(theme, `‹ ${safeText(tabs[active].title)} ${active + 1}/${tabs.length} ›`))), width, '');
+}
+/** The hint row at the foot of a surface. */
+export function footerRow(text, width, theme) {
+    return padded(theme.fg('dim', truncateToWidth(safeText(text), Math.max(0, width - CHROME_PAD * 2), '')), width);
+}
+/** A block: amber rule, title, body, hint, neutral rule. It is as tall as its body. */
+export function blockFrame({ title, meta, body, footer, width, theme }) {
+    if (width < 1)
+        return [];
+    return [
+        blockRule(width, theme),
+        headerRow(title, meta, width, theme),
+        ...body.map(line => padded(line, width)),
+        footerRow(footer, width, theme),
+        neutralRule(width, theme)
+    ];
+}
+/** Rows a page leaves for its body at a given terminal height. */
+export function pageBodyRows(rows) {
+    return Math.max(0, Math.trunc(rows) - CHROME_ROWS);
+}
+/** A page: title (or `headerLine`, such as a tab strip), rule, body padded to fill the screen, rule, hint. */
+export function pageFrame({ title, meta, body, footer, width, rows, theme, headerLine }) {
+    rows = Math.max(0, Math.trunc(rows));
+    if (width < 1 || rows < 1)
+        return [];
+    const room = pageBodyRows(rows);
+    const shown = body.slice(0, room).map(line => padded(line, width));
+    while (shown.length < room)
+        shown.push('');
+    return [
+        headerLine === undefined ? headerRow(title, meta, width, theme) : padded(headerLine, width),
+        neutralRule(width, theme),
+        ...shown,
+        neutralRule(width, theme),
+        footerRow(footer, width, theme)
+    ].slice(0, rows);
+}
+/** A full-width two-pane list uses a 40/60 split once there is room to read both panes. */
+export function inspectorListWidth(width) {
+    return width < 88 ? undefined : Math.max(32, Math.floor((width - 3) * 0.4));
+}
+/** Joins a list and passive detail pane without drawing a box around either. */
+export function splitColumns(left, right, leftWidth, width, rows, theme) {
+    const rightWidth = Math.max(0, width - leftWidth - 3);
+    return Array.from({ length: Math.max(0, Math.trunc(rows)) }, (_, index) => {
+        const leftLine = truncateToWidth(left[index] ?? '', leftWidth, '');
+        const rightLine = truncateToWidth(right[index] ?? '', rightWidth, '');
+        return leftLine + ' '.repeat(Math.max(0, leftWidth - visibleWidth(leftLine))) + theme.fg('dim', ' │ ') + rightLine;
+    });
+}

package/dist/sdk/terminal/tui/clipboardFiles.d.ts

@@ -0,0 +1,11 @@
+export interface ClipboardFileOptions {
+    platform?: NodeJS.Platform;
+    tempRoot?: string;
+    convert?: (source: string, output: string) => Promise<void>;
+}
+export interface StagedClipboardFiles {
+    paths: string[];
+    cleanup?: () => Promise<void>;
+}
+/** Convert Finder-copied HEIC/HEIF paths to images that Pi's terminal reader can consume. */
+export declare function stageClipboardFiles(paths: string[], options?: ClipboardFileOptions): Promise<StagedClipboardFiles>;

package/dist/sdk/terminal/tui/clipboardFiles.js

@@ -0,0 +1,74 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, open, rm, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+function isHeicPath(path) {
+    return /\.hei[cf]$/i.test(path);
+}
+async function convertWithSips(source, output) {
+    await exec('/usr/bin/sips', ['-s', 'format', 'png', source, '--out', output], {
+        timeout: 30_000,
+        maxBuffer: 1024 * 1024
+    });
+}
+async function assertPng(path) {
+    const info = await stat(path);
+    if (!info.isFile() || info.size < PNG_SIGNATURE.length)
+        throw new Error('Conversion did not create an image.');
+    const file = await open(path, 'r');
+    try {
+        const signature = Buffer.alloc(PNG_SIGNATURE.length);
+        const { bytesRead } = await file.read(signature, 0, signature.length, 0);
+        if (bytesRead !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE))
+            throw new Error('Conversion did not create a PNG image.');
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Convert Finder-copied HEIC/HEIF paths to images that Pi's terminal reader can consume. */
+export async function stageClipboardFiles(paths, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== 'darwin' || !paths.some(isHeicPath))
+        return { paths };
+    let directory;
+    try {
+        directory = await mkdtemp(join(options.tempRoot ?? tmpdir(), 'harness-clipboard-'));
+        const stagedPaths = [];
+        for (const [index, path] of paths.entries()) {
+            if (!isHeicPath(path)) {
+                stagedPaths.push(path);
+                continue;
+            }
+            const output = join(directory, `${index}-${randomUUID()}.png`);
+            try {
+                await (options.convert ?? convertWithSips)(path, output);
+                await chmod(output, 0o600);
+                await assertPng(output);
+            }
+            catch {
+                throw new Error(`Could not prepare HEIC image "${basename(path)}" for the terminal.`);
+            }
+            stagedPaths.push(output);
+        }
+        let cleaned = false;
+        return {
+            paths: stagedPaths,
+            cleanup: async () => {
+                if (cleaned || !directory)
+                    return;
+                cleaned = true;
+                await rm(directory, { recursive: true, force: true });
+            }
+        };
+    }
+    catch (error) {
+        if (directory)
+            await rm(directory, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+}

package/dist/sdk/terminal/tui/commandPages.d.ts

@@ -0,0 +1,16 @@
+import type { TerminalPage } from "./page.js";
+import type { TerminalCommandHost } from "./commands.js";
+import { type AnnotateStart } from "./pages/annotatePage.js";
+import { type ContextTab } from "./pages/contextPage.js";
+export type CommandPageId = 'doctor' | 'accounts' | 'permissions' | 'plugins' | 'hub' | 'components' | 'settings' | 'trajectory' | 'log' | 'harness' | 'skills' | 'connections' | 'tools' | 'worktree' | 'notes' | 'annotate' | 'subagents' | 'agents' | 'usage' | 'context' | 'remote-control' | 'follow-up';
+/** Construct one independent full-screen page for a slash command. */
+export declare function createCommandPage(host: TerminalCommandHost, id: CommandPageId, options?: {
+    runId?: string;
+    url?: string;
+    annotate?: AnnotateStart;
+    usageTab?: 'analysis' | 'limit' | 'accounts';
+    usagePeriod?: 'today' | '7d' | '30d' | 'all';
+    contextTab?: ContextTab;
+    close?(): void;
+    navigate?(id: CommandPageId, runId?: string): void;
+}): TerminalPage;