@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,17 @@
+import type { Theme, ToolRenderers } from '@earendil-works/pi-coding-agent';
+export interface PiAdapter {
+    setTheme(theme: Theme): void;
+    withBuiltInRenderers(toolName: string, definition: ToolRenderers | undefined): ToolRenderers | undefined;
+    readClipboardText(): Promise<string | null>;
+    readClipboardFilePaths(): Promise<string[] | null>;
+    readClipboardImage(): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+    extensionForImageMimeType(mimeType: string): string | null;
+}
+export declare function assertPiAdapterVersion(version: string): void;
+export declare function loadPiAdapter(): Promise<PiAdapter>;
+/** Initialize once with loadPiAdapter() before rendering native rich tool components. */
+export declare function setPiTheme(theme: Theme): void;
+export declare function withBuiltInRenderers(toolName: string, definition: ToolRenderers | undefined): ToolRenderers | undefined;

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

@@ -0,0 +1,46 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadPi, PINNED_PI_VERSION } from "../../pi/runtime.js";
+let adapter;
+let loading;
+export function assertPiAdapterVersion(version) {
+    if (version !== PINNED_PI_VERSION)
+        throw new Error(`The Harness terminal adapter requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`);
+}
+export function loadPiAdapter() {
+    loading ??= (async () => {
+        const pi = await loadPi();
+        assertPiAdapterVersion(pi.VERSION);
+        const root = pi.getPackageDir();
+        const [theme, renderers, clipboard, images] = await Promise.all([
+            import(pathToFileURL(join(root, 'dist/modes/interactive/theme/theme.js')).href),
+            import(pathToFileURL(join(root, 'dist/core/tools/renderers/index.js')).href),
+            import(pathToFileURL(join(root, 'dist/utils/clipboard.js')).href),
+            import(pathToFileURL(join(root, 'dist/utils/clipboard-image.js')).href)
+        ]);
+        if (typeof theme.setThemeInstance !== 'function' || typeof renderers.withBuiltInRenderers !== 'function' || typeof clipboard.readClipboardText !== 'function' || typeof clipboard.readClipboardFilePaths !== 'function' || typeof images.readClipboardImage !== 'function' || typeof images.extensionForImageMimeType !== 'function') {
+            throw new Error('The pinned Pi terminal adapter no longer exposes its required presentation hooks.');
+        }
+        adapter = {
+            setTheme: theme.setThemeInstance,
+            withBuiltInRenderers: renderers.withBuiltInRenderers,
+            readClipboardText: clipboard.readClipboardText,
+            readClipboardFilePaths: clipboard.readClipboardFilePaths,
+            readClipboardImage: images.readClipboardImage,
+            extensionForImageMimeType: images.extensionForImageMimeType
+        };
+        return adapter;
+    })();
+    return loading;
+}
+/** Initialize once with loadPiAdapter() before rendering native rich tool components. */
+export function setPiTheme(theme) {
+    if (!adapter)
+        throw new Error('Initialize the Pi terminal adapter before setting its theme.');
+    adapter.setTheme(theme);
+}
+export function withBuiltInRenderers(toolName, definition) {
+    if (!adapter)
+        throw new Error('Initialize the Pi terminal adapter before resolving builtin renderers.');
+    return adapter.withBuiltInRenderers(toolName, definition);
+}

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

@@ -0,0 +1,2 @@
+export { normalModeTools, normalToolsForBranch, parseProposedPlan, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "../../sessions/planMode.js";
+export type { ProposedPlan } from "../../sessions/planMode.js";

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

@@ -0,0 +1,2 @@
+// The terminal's plan mode uses the session's read-only tool set.
+export { normalModeTools, normalToolsForBranch, parseProposedPlan, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "../../sessions/planMode.js";

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

@@ -0,0 +1,16 @@
+import type { AnnotateStart } from "./pages/annotatePage.js";
+import type { CommandPageId } from "./commandPages.js";
+import type { TerminalCommandHost } from "./commands.js";
+import { parseAnnotate } from "./annotateCommand.js";
+type PageOptions = {
+    runId?: string;
+    url?: string;
+    annotate?: AnnotateStart;
+    usageTab?: 'analysis' | 'limit' | 'accounts';
+    usagePeriod?: 'today' | '7d' | '30d' | 'all';
+};
+type OpenPage = (id: CommandPageId, options?: PageOptions) => Promise<void>;
+type Handler = (argument: string) => Promise<void>;
+/** Terminal adapters for commands declared by Harness-owned feature plugins. */
+export declare function createBuiltinPluginCommandHandlers(host: TerminalCommandHost, openPage: OpenPage): Map<string, Handler>;
+export { parseAnnotate };

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

@@ -0,0 +1,41 @@
+import { BUILTIN_PLUGIN_REGISTRY } from "../../plugins/builtin.js";
+import { parseAnnotate } from "./annotateCommand.js";
+import { sendUnsent } from "./annotateSend.js";
+/** Terminal adapters for commands declared by Harness-owned feature plugins. */
+export function createBuiltinPluginCommandHandlers(host, openPage) {
+    const handlers = new Map([
+        ['annotations:open', async (argument) => {
+                const start = parseAnnotate(argument);
+                if (typeof start === 'string')
+                    host.ui.notify(start, 'error');
+                else
+                    await openPage('annotate', { annotate: start });
+            }],
+        // The All annotations tab; no capture window opens until the person asks for one.
+        ['annotations:notes', async () => openPage('notes')],
+        ['annotations:submit', async (argument) => {
+                host.ui.notify(await sendUnsent(host.control, host.ui, { prompt: argument.trim() }), 'info');
+            }],
+        ['annotations:clear', async () => {
+                const { notes } = await host.control('terminal.annotations.clear');
+                host.ui.notify(notes.length ? `Resolved ${notes.length} unsent annotation${notes.length === 1 ? '' : 's'}; the agent can no longer read ${notes.length === 1 ? 'it' : 'them'}. Reopen from /annotate:notes.` : 'No unsent annotations to clear.', 'info');
+            }],
+        ['usage:analysis', async (argument) => {
+                const period = argument.trim().toLowerCase();
+                if (period && !['today', '7d', '30d', 'all'].includes(period)) {
+                    host.ui.notify('Use /usage:analysis today, 7d, 30d or all.', 'error');
+                    return;
+                }
+                await openPage('usage', { usageTab: 'analysis', ...(period ? { usagePeriod: period } : {}) });
+            }],
+        ['usage:limit', async () => openPage('usage', { usageTab: 'limit' })],
+        ['usage:accounts', async () => openPage('usage', { usageTab: 'accounts' })]
+    ]);
+    const commands = BUILTIN_PLUGIN_REGISTRY.commands();
+    for (const command of commands) {
+        if (!handlers.has(`${command.pluginId}:${command.name}`))
+            throw new Error(`No terminal handler for built-in plugin command ${command.pluginId}:${command.name}.`);
+    }
+    return handlers;
+}
+export { parseAnnotate };

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

@@ -0,0 +1,4 @@
+/** The modules, `true` for dark, with a quiet zone of light modules around them. */
+export declare function qrModules(text: string): boolean[][];
+/** One line per two module rows; each line is as wide as the code. */
+export declare function qrLines(text: string): string[];

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

@@ -0,0 +1,35 @@
+// A QR code drawn with half-block characters: two modules per terminal row. Colours are fixed
+// black on white, whatever the theme, because phone cameras need dark modules on a light ground.
+import { encode } from 'uqr';
+const QUIET = 2;
+const LIGHT_ON_DARK = '\x1b[38;5;231;48;5;16m';
+const RESET = '\x1b[0m';
+/** The modules, `true` for dark, with a quiet zone of light modules around them. */
+export function qrModules(text) {
+    const { data } = encode(text, { ecc: 'L', border: 0 });
+    const size = data.length + QUIET * 2;
+    const blank = () => Array.from({ length: size }, () => false);
+    return [
+        ...Array.from({ length: QUIET }, blank),
+        ...data.map((row) => [...Array.from({ length: QUIET }, () => false), ...row, ...Array.from({ length: QUIET }, () => false)]),
+        ...Array.from({ length: QUIET }, blank)
+    ];
+}
+/** One line per two module rows; each line is as wide as the code. */
+export function qrLines(text) {
+    const modules = qrModules(text);
+    const lines = [];
+    for (let y = 0; y < modules.length; y += 2) {
+        const top = modules[y];
+        const bottom = modules[y + 1] ?? top.map(() => false);
+        let line = '';
+        for (let x = 0; x < top.length; x += 1) {
+            // The foreground is light and the background dark, so each cell shows its two modules.
+            const a = top[x];
+            const b = bottom[x];
+            line += !a && !b ? '█' : !a && b ? '▀' : a && !b ? '▄' : ' ';
+        }
+        lines.push(`${LIGHT_ON_DARK}${line}${RESET}`);
+    }
+    return lines;
+}

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

@@ -0,0 +1,20 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type TUI } from '@earendil-works/pi-tui';
+import type { QuestionOption } from "../../sessions/contracts.js";
+import { DialogPanel } from "./dialogs.js";
+type DisplayOption = {
+    option: QuestionOption;
+    index: number;
+};
+export type QuestionPickerResult = {
+    type: 'answer';
+    selected: string[];
+} | {
+    type: 'text';
+    selected: string[];
+} | {
+    type: 'cancel';
+};
+export declare function questionOptionsInDisplayOrder(options: readonly QuestionOption[]): DisplayOption[];
+export declare function createQuestionPicker(tui: TUI, theme: Theme, title: string, question: string | undefined, options: readonly QuestionOption[], multiSelect: boolean, allowText: boolean, selected: readonly string[], done: (result: QuestionPickerResult) => void): DialogPanel;
+export {};

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

@@ -0,0 +1,150 @@
+import { SelectList, stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { selectedRow, selectionText } from "./chrome.js";
+import { centeredDialogHost, dialogFits } from "./dialogGeometry.js";
+import { DialogPanel } from "./dialogs.js";
+const RECOMMENDED = '(Recommended)';
+export function questionOptionsInDisplayOrder(options) {
+    const indexed = options.map((option, index) => ({ option, index }));
+    return [...indexed.filter(({ option }) => option.recommended), ...indexed.filter(({ option }) => !option.recommended)];
+}
+function recommendedSelectTheme(theme) {
+    return {
+        selectedPrefix: text => selectionText(theme, text),
+        selectedText: text => {
+            const marker = text.lastIndexOf(RECOMMENDED);
+            if (marker < 0)
+                return selectionText(theme, text.replace(/^→/, '❯'));
+            const afterMarker = marker + RECOMMENDED.length;
+            return selectionText(theme, text.slice(0, marker).replace(/^→/, '❯')) + theme.fg('warning', RECOMMENDED) + selectionText(theme, text.slice(afterMarker));
+        },
+        description: text => theme.fg('muted', text),
+        scrollInfo: text => theme.fg('dim', text),
+        noMatch: text => theme.fg('warning', text.replace('commands', 'options'))
+    };
+}
+class QuestionPickerContent {
+    tui;
+    theme;
+    options;
+    multiSelect;
+    allowText;
+    done;
+    list;
+    selectedIndexes;
+    focusedValue = false;
+    displayOptions;
+    constructor(tui, theme, options, multiSelect, allowText, selected, done) {
+        this.tui = tui;
+        this.theme = theme;
+        this.options = options;
+        this.multiSelect = multiSelect;
+        this.allowText = allowText;
+        this.done = done;
+        this.displayOptions = questionOptionsInDisplayOrder(options);
+        this.selectedIndexes = [];
+        const remaining = [...selected];
+        options.forEach((option, index) => {
+            const selectedIndex = remaining.indexOf(option.label);
+            if (selectedIndex >= 0) {
+                this.selectedIndexes.push(index);
+                remaining.splice(selectedIndex, 1);
+            }
+        });
+        this.rebuild();
+    }
+    get focused() { return this.focusedValue; }
+    set focused(value) { this.focusedValue = value; }
+    labels() {
+        return this.selectedIndexes.map(index => this.options[index].label);
+    }
+    rebuild() {
+        const selectedValue = this.list?.getSelectedItem()?.value;
+        const items = this.displayOptions.map(({ option }, displayIndex) => ({
+            value: `option:${displayIndex}`,
+            label: `${displayIndex + 1}. ${this.selectedIndexes.includes(this.displayOptions[displayIndex].index) ? '✓ ' : ''}${option.label}${option.recommended ? ` ${RECOMMENDED}` : ''}`,
+            description: option.description
+        }));
+        if (this.allowText)
+            items.push({ value: 'write', label: 'Write an answer', description: undefined });
+        if (this.multiSelect)
+            items.push({ value: 'submit', label: 'Submit choices', description: undefined });
+        const maxVisible = Math.min(12, Math.max(1, Math.floor(this.tui.terminal.rows * 0.6) - 5));
+        const theme = recommendedSelectTheme(this.theme);
+        this.list = new SelectList(items, maxVisible, theme, {
+            minPrimaryColumnWidth: 1,
+            maxPrimaryColumnWidth: 60,
+            truncatePrimary: ({ text, maxWidth, isSelected }) => {
+                const marker = text.lastIndexOf(RECOMMENDED);
+                if (marker < 0)
+                    return truncateToWidth(text, maxWidth, '');
+                const label = text.slice(0, marker).trimEnd();
+                const suffix = text.slice(marker);
+                const suffixWidth = visibleWidth(suffix);
+                const shortened = suffixWidth >= maxWidth ? truncateToWidth(suffix, maxWidth, '') : `${truncateToWidth(label, Math.max(1, maxWidth - suffixWidth), '…')} ${suffix}`;
+                if (isSelected)
+                    return shortened;
+                const shortenedMarker = shortened.lastIndexOf(RECOMMENDED);
+                return shortenedMarker < 0
+                    ? shortened
+                    : shortened.slice(0, shortenedMarker) + this.theme.fg('warning', shortened.slice(shortenedMarker));
+            }
+        });
+        if (selectedValue) {
+            const index = items.findIndex(item => item.value === selectedValue);
+            if (index >= 0)
+                this.list.setSelectedIndex(index);
+        }
+        this.list.onSelect = item => {
+            if (item.value === 'write') {
+                this.done({ type: 'text', selected: this.labels() });
+                return;
+            }
+            if (item.value === 'submit') {
+                this.done({ type: 'answer', selected: this.labels() });
+                return;
+            }
+            const displayIndex = Number(item.value.slice('option:'.length));
+            const originalIndex = this.displayOptions[displayIndex]?.index;
+            if (originalIndex === undefined)
+                return;
+            if (!this.multiSelect) {
+                this.done({ type: 'answer', selected: [this.options[originalIndex].label] });
+                return;
+            }
+            const selectedIndex = this.selectedIndexes.indexOf(originalIndex);
+            if (selectedIndex >= 0)
+                this.selectedIndexes.splice(selectedIndex, 1);
+            else
+                this.selectedIndexes.push(originalIndex);
+            this.rebuild();
+            this.tui.requestRender();
+        };
+        this.list.onCancel = () => this.done({ type: 'cancel' });
+    }
+    invalidate() { this.list.invalidate(); }
+    handleInput(data) {
+        if (/^[1-9]$/.test(data)) {
+            const index = Number(data) - 1;
+            if (index >= 0 && index < this.displayOptions.length) {
+                this.list.setSelectedIndex(index);
+                this.list.handleInput('\r');
+                return;
+            }
+        }
+        this.list.handleInput(data === 'j' ? '\x1b[B' : data === 'k' ? '\x1b[A' : data);
+    }
+    render(width) {
+        return this.list.render(width).map(line => {
+            const bounded = truncateToWidth(line, width, '');
+            return stripTerminalSequences(line).startsWith('❯') ? selectedRow(bounded, width, this.theme) : bounded;
+        });
+    }
+}
+export function createQuestionPicker(tui, theme, title, question, options, multiSelect, allowText, selected, done) {
+    const content = new QuestionPickerContent(tui, theme, options, multiSelect, allowText, selected, done);
+    const hint = multiSelect ? '↑/↓ select · Enter toggle · Submit choices · Esc cancel' : '↑/↓ select · Enter choose · Esc cancel';
+    const panel = new DialogPanel(title, content, () => theme, hint, question);
+    panel.centered = centeredDialogHost(tui) && dialogFits(tui.terminal.columns, tui.terminal.rows);
+    panel.maxRows = () => Math.max(3, Math.floor(tui.terminal.rows * 0.8));
+    return panel;
+}

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

@@ -0,0 +1,21 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { QuestionAnswer } from "../../sessions/registry.js";
+export interface TerminalQuestion {
+    requestId: string;
+    question?: string;
+    summary?: string;
+    uiSketch?: true;
+    options: {
+        label: string;
+        description?: string;
+        recommended?: boolean;
+        sketch?: string;
+    }[];
+    multiSelect?: boolean;
+    allowText?: boolean;
+    batchId?: string;
+    batchIndex?: number;
+    batchCount?: number;
+}
+/** Answers stay local until the complete group can be submitted to the registry. */
+export declare function answerTerminalQuestion(ui: ExtensionUIContext, request: TerminalQuestion, signal: AbortSignal): Promise<QuestionAnswer | undefined>;

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

@@ -0,0 +1,42 @@
+import { createQuestionPicker } from "./questionPicker.js";
+/** Answers stay local until the complete group can be submitted to the registry. */
+export async function answerTerminalQuestion(ui, request, signal) {
+    const choices = request.options;
+    const progress = request.batchId ? `${request.batchIndex} of ${request.batchCount} · ` : '';
+    const title = `${progress}${request.summary ?? 'Question'}`;
+    const inputTitle = `${progress}${request.summary ? `${request.summary}: ` : ''}${request.question ?? 'Question'}`;
+    if (!Array.isArray(choices) || choices.length === 0)
+        throw new Error('Every question needs at least one choice.');
+    if (!choices.some(choice => choice.recommended))
+        throw new Error('Every question needs at least one recommended choice.');
+    let selected = [];
+    while (!signal.aborted) {
+        let cancelPicker = () => { };
+        const onAbort = () => cancelPicker();
+        signal.addEventListener('abort', onAbort, { once: true });
+        const picker = ui.custom((tui, theme, _keybindings, done) => {
+            cancelPicker = () => done({ type: 'cancel' });
+            if (signal.aborted)
+                cancelPicker();
+            return createQuestionPicker(tui, theme, title, request.question, choices, request.multiSelect === true, request.allowText !== false, selected, done);
+        });
+        let result;
+        try {
+            result = await picker;
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+        }
+        if (!result || result.type === 'cancel' || signal.aborted)
+            return undefined;
+        selected = result.selected;
+        if (result.type === 'answer')
+            return { selected };
+        const text = await ui.input(inputTitle, undefined, { signal });
+        if (signal.aborted)
+            return undefined;
+        if (text !== undefined)
+            return { selected, text };
+    }
+    return undefined;
+}

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

@@ -0,0 +1,117 @@
+import { type AgentSession, type AgentSessionEventListener, type AgentSessionRuntime, type AgentSessionServices, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { GoalController } from "../../sessions/goal.js";
+import type { SessionAccount } from "../accountsMenu.js";
+import type { QuestionAnswer } from "../../sessions/registry.js";
+import type { TerminalQuestion } from "./questions.js";
+import { type ComposerMode } from "./modeChoices.js";
+export interface TerminalArguments {
+    appendSystemPrompt: string[];
+    extensions: string[];
+    skills: string[];
+    prompts: string[];
+    themes: string[];
+    sessionDir: string;
+    session?: string;
+    model?: string;
+}
+/** The launch specification comes from Terminals.prepare(), never from Pi's own discovery. */
+export declare function parseTerminalArguments(args: string[]): TerminalArguments;
+export interface TerminalRuntimeHost {
+    ui: ExtensionUIContext;
+    shutdown(): void;
+    notify(message: string): void;
+    changed(): void;
+    resources?(services: AgentSessionServices): void;
+}
+type SessionChangeListener = (session: AgentSession) => void | Promise<void>;
+type NewOptions = Parameters<AgentSessionRuntime['newSession']>[0];
+type SwitchOptions = Parameters<AgentSessionRuntime['switchSession']>[1];
+type ForkOptions = Parameters<AgentSessionRuntime['fork']>[1];
+type TreeOptions = Parameters<AgentSession['navigateTree']>[1];
+export interface TerminalSnapshot {
+    readonly sessionId: string;
+    readonly sessionFile?: string;
+    readonly name?: string;
+    readonly cwd: string;
+    readonly account: Readonly<SessionAccount> | null;
+    readonly model?: Readonly<{
+        id: string;
+        provider: string;
+        name: string;
+        reasoning: boolean;
+        contextWindow: number;
+    }>;
+    readonly thinkingLevel: AgentSession['thinkingLevel'];
+    readonly isStreaming: boolean;
+    readonly idle: boolean;
+    readonly hasUserMessages: boolean;
+    readonly hideThinking: boolean;
+    readonly context: Readonly<{
+        percent: number | null;
+        window: number;
+    }>;
+    readonly costUsd: number;
+    readonly subscription: boolean;
+    readonly queue: Readonly<{
+        steering: readonly string[];
+        followUp: readonly string[];
+    }>;
+}
+export interface TerminalDecision extends TerminalQuestion {
+    type: 'approval' | 'question';
+    target?: string;
+    action?: string;
+    rememberable?: boolean;
+}
+export interface TerminalPermissionState {
+    readonly full: boolean;
+    readonly globalTools: readonly string[];
+}
+/** An image the user attached to a prompt, as Pi sends it to the model. */
+export interface TerminalImage {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface TerminalRuntime {
+    pending(): Promise<TerminalDecision[]>;
+    approve(requestId: string, decision: 'approved' | 'denied', alwaysAllowTool?: boolean): Promise<void>;
+    permissions(): Promise<TerminalPermissionState>;
+    setFullPermission(enabled: boolean): Promise<void>;
+    setGlobalTool(tool: string, allowed: boolean): Promise<void>;
+    answer(requestId: string, answer: QuestionAnswer): Promise<void>;
+    answerBatch(batchId: string, answers: Array<{
+        questionId: string;
+        answer: QuestionAnswer;
+    }>): Promise<void>;
+    snapshot(): TerminalSnapshot;
+    /** Images go to the model in the same user message as `text`. */
+    submit(text: string, followUp?: boolean, images?: TerminalImage[]): Promise<void>;
+    submitPlan(text: string, images?: TerminalImage[]): Promise<void>;
+    /** The composer's mode. Its saved model and effort apply now, or when a running turn settles. */
+    setMode(mode: ComposerMode): Promise<void>;
+    readonly session: AgentSession;
+    readonly services: AgentSessionServices;
+    readonly cwd: string;
+    readonly sessionDirectory: string;
+    subscribe(listener: AgentSessionEventListener): () => void;
+    onSessionChange(listener: SessionChangeListener): () => void;
+    onBeforeSessionChange(listener: () => void): () => void;
+    newSession(options?: NewOptions): ReturnType<AgentSessionRuntime['newSession']>;
+    switchSession(path: string, options?: SwitchOptions): ReturnType<AgentSessionRuntime['switchSession']>;
+    fork(entryId: string, options?: ForkOptions): ReturnType<AgentSessionRuntime['fork']>;
+    navigateTree(targetId: string, options?: TreeOptions): ReturnType<AgentSession['navigateTree']>;
+    importFromJsonl(path: string, cwdOverride?: string): ReturnType<AgentSessionRuntime['importFromJsonl']>;
+    installationDeviceId(): Promise<string>;
+    reload(): Promise<void>;
+    interrupt(): Promise<void>;
+    /** This session's /goal (ADR-0072). */
+    readonly goal: GoalController;
+    dispose(): Promise<void>;
+}
+/** Saved native history stays in the prepared project folder, including symlink targets. */
+export declare function assertTerminalHistoryPath(path: string, sessionDirectory: string): void;
+/** Inspect the header before any native switch/import can invalidate a session or copy a file. */
+export declare function assertTerminalSessionScope(path: string, cwd: string, cwdOverride?: string): void;
+export declare function createTerminalRuntime(args: string[], host: TerminalRuntimeHost): Promise<TerminalRuntime>;
+export {};