@xingular/harness 0.1.7 → 1.0.0

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

@@ -0,0 +1,10 @@
+import type { RunEvent, RunRecord } 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[];
+/** 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,30 @@
+import { notFound } from "../core/errors.js";
+import { findRun, listRuns, readEvents } from "../sessions/runStore.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);
+}
+/** 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/chrome.d.ts

@@ -0,0 +1,64 @@
+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[];

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

@@ -0,0 +1,169 @@
+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);
+}

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,7 @@
+import type { TerminalPage } from "./page.js";
+import type { TerminalCommandHost } from "./commands.js";
+export type CommandPageId = 'doctor' | 'accounts' | 'permissions' | 'plugins' | 'hub' | 'components' | 'settings' | 'trajectory' | 'log';
+/** Construct one independent full-screen page for a slash command. */
+export declare function createCommandPage(host: TerminalCommandHost, id: CommandPageId, options?: {
+    runId?: string;
+}): TerminalPage;

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

@@ -0,0 +1,63 @@
+import { DoctorPage } from "./pages/doctorPage.js";
+import { AccountsPage } from "./pages/accountsPage.js";
+import { ComponentsPage } from "./pages/componentsPage.js";
+import { HubPage } from "./pages/hubPage.js";
+import { LogPage, formatRunEventLog } from "./pages/logPage.js";
+import { PermissionsPage } from "./pages/permissionsPage.js";
+import { PluginsPage } from "./pages/pluginsPage.js";
+import { SettingsPage } from "./pages/settingsPage.js";
+import { TrajectoryPage } from "./pages/trajectoryPage.js";
+import { createSettingsModel } from "./settingsModel.js";
+/** Construct one independent full-screen page for a slash command. */
+export function createCommandPage(host, id, options = {}) {
+    const theme = () => host.ui.theme;
+    const notify = (message, type) => host.ui.notify(message, type === 'error' || type === 'warning' ? type : 'info');
+    switch (id) {
+        case 'doctor':
+            return new DoctorPage({ theme, call: host.control, confirm: host.ui.confirm.bind(host.ui), select: host.ui.select.bind(host.ui), changed: host.changed,
+                selection: () => {
+                    const model = host.runtime().snapshot().model;
+                    return { model: model ? `${model.provider}/${model.id}` : null, tools: host.session().getActiveToolNames() };
+                }
+            });
+        case 'accounts':
+            return new AccountsPage({
+                theme, call: host.control, ui: host.ui,
+                session: () => host.runtime().snapshot().account,
+                relaunch: host.shutdown, changed: host.changed
+            });
+        case 'permissions':
+            return new PermissionsPage({
+                theme, permissions: () => host.runtime().permissions(),
+                setFullPermission: enabled => host.runtime().setFullPermission(enabled),
+                setGlobalTool: (tool, allowed) => host.runtime().setGlobalTool(tool, allowed),
+                activeTools: () => host.session().getActiveToolNames(),
+                confirm: (title, message) => host.ui.confirm(title, message), notify, changed: host.changed
+            });
+        case 'plugins':
+            return new PluginsPage({ theme, call: host.control, ui: host.ui, changed: host.changed });
+        case 'hub':
+            return new HubPage({ theme, call: host.control, ui: host.ui, changed: host.changed });
+        case 'components':
+            return new ComponentsPage({ theme, call: host.control, ui: host.ui, notify, changed: host.changed });
+        case 'settings':
+            return new SettingsPage({ theme, ...createSettingsModel(host), notify, changed: host.changed });
+        case 'trajectory':
+            return new TrajectoryPage({
+                theme, runs: host.trajectory.list, read: host.trajectory.read, copy: host.copyText,
+                initialRunId: options.runId || undefined, notify, changed: host.changed
+            });
+        case 'log':
+            return new LogPage({
+                theme, changed: host.changed,
+                load: async () => {
+                    const [diagnostics, runs] = await Promise.all([host.logs.read(), host.trajectory.list()]);
+                    const snapshots = await Promise.all(runs.map(run => host.trajectory.read(run.id)));
+                    return [
+                        { title: 'Diagnostics', text: diagnostics || 'No Harness diagnostics have been captured by this host.' },
+                        { title: 'Run Events', text: formatRunEventLog(snapshots) }
+                    ];
+                }
+            });
+    }
+}

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

@@ -0,0 +1,42 @@
+import { type AgentSession, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { type SkillEntry } from "./skillInvocation.js";
+import type { TerminalRuntime } from "./runtime.js";
+import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from "../trajectory.js";
+export interface TerminalCommandHost {
+    session(): AgentSession;
+    /** Navigation is scope checked by the Harness runtime adapter. */
+    runtime(): Pick<TerminalRuntime, 'newSession' | 'switchSession' | 'fork' | 'importFromJsonl' | 'reload' | 'navigateTree' | 'installationDeviceId' | 'permissions' | 'setFullPermission' | 'setGlobalTool' | 'snapshot' | 'interrupt'>;
+    /** The protected `accounts.*`, `plugins.*` and `hub.*` calls of this session, made with its control key. */
+    /** Protected Harness calls made with this session's control key. */
+    control: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>;
+    ui: ExtensionUIContext;
+    cwd(): string;
+    sessionDirectory(): string;
+    refresh(): void;
+    changed(): void;
+    plan(brief: string): void;
+    /** Asks a side question in its own tool-free session; empty text dismisses the one showing. */
+    btw(question: string): Promise<void>;
+    shutdown(): void;
+    setEditorText(text: string): void;
+    copyText(text: string): Promise<void>;
+    suspend?(): Promise<void>;
+    hotkeys?(): string;
+    logs: {
+        read(): Promise<string>;
+    };
+    trajectory: {
+        list(): Promise<TerminalTrajectoryRun[]>;
+        read(runId: string, afterSequence?: number): Promise<TerminalTrajectorySnapshot>;
+    };
+}
+export interface TerminalCommandCompletion {
+    name: string;
+    description?: string;
+}
+export declare function createTerminalCommands(host: TerminalCommandHost): {
+    execute: (text: string) => Promise<boolean>;
+    completions: () => TerminalCommandCompletion[];
+    skills: () => SkillEntry[];
+    expandSkill: (text: string) => string;
+};