@xingular/harness 1.0.0 → 1.1.1

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

@@ -0,0 +1,27 @@
+import { BUILTIN_PLUGIN_REGISTRY } from "../../plugins/builtin.js";
+import { parseAnnotate } from "./annotateCommand.js";
+/** Terminal adapters for commands declared by Harness-owned feature plugins. */
+export function createBuiltinPluginCommandHandlers(host, openPage) {
+    const handlers = new Map([
+        ['doctor', async () => openPage('doctor')],
+        ['worktree', async () => openPage('worktree')],
+        ['trajectory', async (argument) => openPage('trajectory', { runId: argument })],
+        ['subagents', async () => openPage('subagents')],
+        ['agents', async () => openPage('agents')],
+        ['notes', async () => openPage('notes')],
+        ['annotate', async (argument) => {
+                const start = parseAnnotate(argument);
+                if (typeof start === 'string')
+                    host.ui.notify(start, 'error');
+                else
+                    await openPage('annotate', { annotate: start });
+            }]
+    ]);
+    const commands = BUILTIN_PLUGIN_REGISTRY.commands();
+    for (const command of commands) {
+        if (!handlers.has(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/questions.d.ts

@@ -4,10 +4,12 @@ export interface TerminalQuestion {
     requestId: string;
     question?: string;
     summary?: string;
+    uiSketch?: true;
     options: {
         label: string;
         description?: string;
         recommended?: boolean;
+        sketch?: string;
     }[];
     multiSelect?: boolean;
     allowText?: boolean;

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

@@ -2,7 +2,7 @@ import { createAgentSession, createAgentSessionRuntime, DefaultResourceLoader, M
 import { closeSync, existsSync, openSync, readSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import terminalExtension from "../piExtension.js";
-import { planModeTools } from "./planMode.js";
+import { normalModeTools, planModeTools, QUESTION_TOOL_NAMES } from "./planMode.js";
 import { claimTerminalControl, controlCall } from "../control.js";
 import { loadPiAdapter } from "./piAdapter.js";
 import { loadPi } from "../../pi/runtime.js";
@@ -197,6 +197,7 @@ export async function createTerminalRuntime(args, host) {
             ...(selected?.model ? { model: selected.model } : {}),
             ...(thinkingLevel ? { thinkingLevel } : {})
         });
+        created.session.setActiveToolsByName(normalModeTools(created.session.getActiveToolNames()));
         const services = { cwd, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] };
         host.resources?.(services);
         return { ...created, services, diagnostics: services.diagnostics };
@@ -296,7 +297,8 @@ export async function createTerminalRuntime(args, host) {
             if (!session.isIdle)
                 throw new Error('A plan request must wait until the current response settles.');
             const originalTools = session.getActiveToolNames();
-            const allowedTools = planModeTools(originalTools);
+            const registeredQuestions = session.getAllTools().map(tool => tool.name).filter(name => QUESTION_TOOL_NAMES.has(name));
+            const allowedTools = planModeTools(originalTools, [], registeredQuestions);
             // The session's own model and effort come back once the plan is done.
             const previous = { model: session.model, effort: session.thinkingLevel };
             planRun.allowedTools = new Set(allowedTools);

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

@@ -3,10 +3,12 @@ import type { TerminalSettingItem } from "./pages/settingsPage.js";
 export interface SettingsModelHost {
     session(): AgentSession;
     ui: ExtensionUIContext;
+    control<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     hotkeys?(): string;
     refresh(): void;
 }
 export declare function createSettingsModel(host: SettingsModelHost): {
     items: () => TerminalSettingItem[];
     apply: (id: string) => Promise<void>;
+    load: () => Promise<void>;
 };

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

@@ -1,5 +1,7 @@
-const GROUP_ORDER = ['Theme', 'Display', 'Images', 'Thinking', 'Recovery', 'Editor', 'Queues', 'Commands', 'Terminal', 'Keyboard', 'Compaction'];
+const PRIVATE_ACCESS_ID = 'browser.allowPrivate';
+const GROUP_ORDER = ['Theme', 'Display', 'Images', 'Thinking', 'Recovery', 'Editor', 'Queues', 'Commands', 'Terminal', 'Keyboard', 'Compaction', 'Network'];
 export function createSettingsModel(host) {
+    let browserSettings = null;
     const booleans = (session) => {
         const settings = session.settingsManager;
         return [
@@ -40,9 +42,37 @@ export function createSettingsModel(host) {
             const split = option.indexOf(':');
             return { id: String(index), tab: locations[index][0], group: locations[index][1], label: split < 0 ? option : option.slice(0, split), value: split < 0 ? '' : option.slice(split + 1).trim(), description: descriptions[index] };
         });
+        if (browserSettings)
+            result.push({
+                id: PRIVATE_ACCESS_ID,
+                tab: 'Browser',
+                group: 'Network',
+                label: 'Private address access',
+                value: browserSettings.allowPrivate ? 'On' : 'Off',
+                description: 'This device-wide setting affects agent browsing and annotation capture. When on, pages can reach localhost and private networks.'
+            });
         return result.sort((a, b) => GROUP_ORDER.indexOf(a.group) - GROUP_ORDER.indexOf(b.group));
     }
+    async function load() {
+        const config = await host.control('terminal.browser.config');
+        if (!config || typeof config.allowPrivate !== 'boolean')
+            throw new Error('The Harness returned invalid browser settings.');
+        browserSettings = { allowPrivate: config.allowPrivate };
+    }
     async function apply(id) {
+        if (id === PRIVATE_ACCESS_ID) {
+            if (!browserSettings)
+                return;
+            const allowPrivate = !browserSettings.allowPrivate;
+            if (allowPrivate && !await host.ui.confirm('Allow private network addresses?', 'This device-wide setting lets pages opened by agent browsing and annotation capture reach localhost and private networks.'))
+                return;
+            const saved = await host.control('terminal.browser.configure', { allowPrivate });
+            if (!saved || typeof saved.allowPrivate !== 'boolean')
+                throw new Error('The Harness returned invalid browser settings.');
+            browserSettings = { allowPrivate: saved.allowPrivate };
+            host.refresh();
+            return;
+        }
         const session = host.session();
         const index = Number(id);
         const switches = booleans(session);
@@ -80,5 +110,5 @@ export function createSettingsModel(host) {
             host.ui.notify(host.hotkeys?.() ?? 'Use /help for commands. Keyboard bindings are managed by the terminal application.', 'info');
         host.refresh();
     }
-    return { items, apply };
+    return { items, apply, load };
 }

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

@@ -1,29 +1,20 @@
-import { type AgentSession, type AgentSessionServices, type Theme } from '@earendil-works/pi-coding-agent';
+import type { Theme } from '@earendil-works/pi-coding-agent';
 import { type Component } from '@earendil-works/pi-tui';
-export declare const SIDE_PROMPT: string;
-export declare const ANSWER_ROWS = 8;
-/**
- * A bounded plain-text excerpt of the main conversation: the last few user and assistant turns, the
- * tools an assistant turn called by name, and whether the reply is still running. Hidden reasoning,
- * tool inputs and results, and images are left out.
- */
-export declare function sideQuestionSnapshot(messages: readonly unknown[], running: boolean): string;
-/** What the controller needs from a session; a Pi `AgentSession` satisfies it through `createSideSession`. */
-export interface SideSession {
-    prompt(text: string): Promise<void>;
-    abort(): Promise<void>;
-    subscribe(listener: () => void): () => void;
-    answer(): string;
-    /** Why the provider ended the turn in error, if it did. */
-    failure(): string | undefined;
-    dispose(): void;
-}
-/** A separate in-memory session on the same account and model, with no tools, extensions, skills or project files. */
-export declare function createSideSession(services: AgentSessionServices, main: AgentSession): Promise<SideSession>;
+import type { SideQuestionContext, SideQuestionRead } from "../../sessions/sideQuestions.js";
 export type SideState = 'thinking' | 'answered' | 'failed';
+type SideQuestionStart = {
+    runId: string;
+    sessionId: string;
+    nativeSessionId: string | null;
+};
+/** Visible native history and tool activity, with hidden reasoning and image bytes omitted. */
+export declare function sideQuestionSnapshot(messages: readonly unknown[], running: boolean): string;
 export interface SideQuestionOptions {
-    create(): Promise<SideSession>;
-    snapshot(): string;
+    context(): SideQuestionContext;
+    start(question: string, context: SideQuestionContext): Promise<SideQuestionStart>;
+    read(runId: string, afterSequence: number): Promise<SideQuestionRead>;
+    interrupt(runId: string): Promise<unknown>;
+    copyText(text: string): Promise<void>;
     theme(): Theme;
     /** Puts the dock above the composer, or takes it away. */
     mount(dock: Component | undefined): void;
@@ -31,23 +22,32 @@ export interface SideQuestionOptions {
 }
 export declare class SideQuestion {
     private readonly options;
-    private session;
-    private unsubscribe;
+    private runId;
     private generation;
+    private pollTimer;
     private question;
     private answerText;
     private error;
     private current;
     private startedAt;
+    private afterSequence;
+    private answerOffset;
     private readonly dock;
     constructor(options: SideQuestionOptions);
     get visible(): boolean;
     get state(): SideState | undefined;
+    get answer(): string;
     /** Asks one question, replacing any earlier one. Empty text dismisses. */
     ask(question: string): Promise<void>;
+    /** Scrolls the answer while it is longer than the dock. */
+    scroll(direction: 'up' | 'down'): void;
+    /** Copies the whole side answer, including any lines outside the dock. */
+    copyAnswer(): Promise<void>;
     /** Interrupts a running side question and removes the dock. */
     dismiss(): Promise<void>;
+    private poll;
     private release;
-    /** The dock: a neutral rule, the inline question, its answer, and a hint, separated by blank rows. */
+    /** The dock: question, a scrollable answer window, and a hint for browsing or copying. */
     private render;
 }
+export {};

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

@@ -1,89 +1,79 @@
-// `/btw <question>`: a side question answered by a separate, tool-free session while the main
-// conversation carries on. It lives in a dock above the composer, never enters the transcript, the
-// queue or the run history, and is gone on dismiss, on a session change, or when a new one replaces it.
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from '@earendil-works/pi-coding-agent';
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { contentWidth, footerRow, neutralRule, padded, safeText } from "./chrome.js";
 import { getWorkingSpinnerFrames, SPINNER_INTERVAL_MS, spinnerFrameAt } from "./workingStatus.js";
-export const SIDE_PROMPT = [
-    'You answer one short side question from a person whose main task is still running in another session.',
-    'You have no tools: you cannot read or change files, run commands, browse, or call anything, and you must not say you did.',
-    'Use the conversation excerpt for context and do not invent what it does not show. Answer briefly and plainly.'
-].join(' ');
-const TURNS = 6;
-const TURN_CHARS = 1_200;
-const TOTAL_CHARS = 6_000;
 const QUESTION_ROWS = 2;
-export const ANSWER_ROWS = 8;
+const ANSWER_ROWS = 8;
+const MAX_CLIENT_CONTEXT_CHARS = 300_000;
+const POLL_INTERVAL_MS = 160;
 function blocks(content) {
     if (typeof content === 'string')
         return [{ type: 'text', text: content }];
     return Array.isArray(content) ? content.filter((block) => typeof block === 'object' && block !== null) : [];
 }
-const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit)}…` : text;
-/**
- * A bounded plain-text excerpt of the main conversation: the last few user and assistant turns, the
- * tools an assistant turn called by name, and whether the reply is still running. Hidden reasoning,
- * tool inputs and results, and images are left out.
- */
+function contentText(content) {
+    return blocks(content).filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
+}
+function serialized(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '[unavailable]';
+    }
+}
+/** Visible native history and tool activity, with hidden reasoning and image bytes omitted. */
 export function sideQuestionSnapshot(messages, running) {
-    const turns = [];
+    const lines = [];
     for (const message of messages) {
-        const { role, content } = (message ?? {});
-        if (role !== 'user' && role !== 'assistant')
-            continue;
-        const parts = blocks(content);
-        const text = parts.filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
-        const tools = [...new Set(parts.filter(block => block.type === 'toolCall' && typeof block.name === 'string').map(block => String(block.name)))];
-        if (!text && !tools.length)
+        if (!message || typeof message !== 'object')
             continue;
-        turns.push(`${role === 'user' ? 'User' : 'Assistant'}: ${clip(safeText(text).replace(/\s+/g, ' ').trim(), TURN_CHARS)}${tools.length ? ` [used tools: ${tools.join(', ')}]` : ''}`);
+        const item = message;
+        const parts = blocks(item.content);
+        if (item.role === 'user' || item.role === 'assistant') {
+            const text = parts.filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
+            if (text)
+                lines.push(`${item.role === 'user' ? 'User' : 'Assistant'}:\n${safeText(text)}`);
+            for (const call of parts.filter(block => block.type === 'toolCall')) {
+                const name = typeof call.name === 'string' ? call.name : 'unknown tool';
+                lines.push(`Assistant tool call (${name}):\n${safeText(serialized(call.arguments))}`);
+            }
+            if (parts.some(block => block.type === 'image'))
+                lines.push(`${item.role === 'user' ? 'User' : 'Assistant'} attached an image; image bytes are omitted.`);
+        }
+        else if (item.role === 'toolResult') {
+            const name = typeof item.toolName === 'string' ? item.toolName : typeof item.name === 'string' ? item.name : 'unknown tool';
+            const output = contentText(item.content);
+            lines.push(`Tool result (${name}${typeof item.toolCallId === 'string' ? `, ${item.toolCallId}` : ''}):\n${safeText(output || '(no text result)')}`);
+            if (parts.some(block => block.type === 'image'))
+                lines.push('Tool result also contained an image; image bytes are omitted.');
+        }
     }
-    let recent = turns.slice(-TURNS);
-    while (recent.length > 1 && recent.join('\n').length > TOTAL_CHARS)
-        recent = recent.slice(1);
-    const lines = ['Conversation excerpt, oldest first:', ...(recent.length ? recent : ['(nothing yet)'])];
+    if (!lines.length)
+        lines.push('(No visible conversation messages yet.)');
     if (running)
-        lines.push('', 'The main reply is still running; its latest turn above may be unfinished.');
-    return lines.join('\n');
+        lines.push('The main reply is still running; its latest message may be unfinished.');
+    const full = lines.join('\n\n');
+    return full.length > MAX_CLIENT_CONTEXT_CHARS
+        ? `[Earlier visible context omitted to fit the side-question request.]\n\n${full.slice(-MAX_CLIENT_CONTEXT_CHARS)}`
+        : full;
 }
-/** A separate in-memory session on the same account and model, with no tools, extensions, skills or project files. */
-export async function createSideSession(services, main) {
-    const model = main.model;
-    if (!model || model.id === 'unknown')
-        throw new Error('Choose a model before asking a side question.');
-    const settingsManager = SettingsManager.inMemory({});
-    const resourceLoader = new DefaultResourceLoader({
-        cwd: services.cwd, agentDir: services.agentDir, settingsManager,
-        noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true, systemPrompt: SIDE_PROMPT
-    });
-    await resourceLoader.reload();
-    const { session } = await createAgentSession({
-        cwd: services.cwd, agentDir: services.agentDir, modelRuntime: services.modelRuntime, settingsManager, resourceLoader,
-        sessionManager: SessionManager.inMemory(services.cwd), model, thinkingLevel: 'off', noTools: 'all'
-    });
-    return {
-        prompt: text => session.prompt(text),
-        abort: () => session.abort(),
-        subscribe: listener => session.subscribe(() => listener()),
-        answer: () => session.getLastAssistantText() ?? '',
-        failure: () => {
-            const last = session.messages.at(-1);
-            return last?.role === 'assistant' && last.stopReason === 'error' ? last.errorMessage ?? 'The provider returned an error.' : undefined;
-        },
-        dispose: () => session.dispose()
-    };
+function payload(event) {
+    return event.payload && typeof event.payload === 'object' ? event.payload : {};
 }
 export class SideQuestion {
     options;
-    session;
-    unsubscribe;
+    runId;
     generation = 0;
+    pollTimer;
     question = '';
     answerText = '';
     error;
     current;
     startedAt = 0;
+    afterSequence = -1;
+    answerOffset = 0;
     dock;
     constructor(options) {
         this.options = options;
@@ -91,6 +81,7 @@ export class SideQuestion {
     }
     get visible() { return this.current !== undefined; }
     get state() { return this.current; }
+    get answer() { return this.answerText; }
     /** Asks one question, replacing any earlier one. Empty text dismisses. */
     async ask(question) {
         const text = question.trim();
@@ -98,73 +89,111 @@ export class SideQuestion {
             await this.dismiss();
             return;
         }
-        await this.release();
         const generation = ++this.generation;
+        await this.release();
         this.question = text;
         this.startedAt = Date.now();
         this.answerText = '';
         this.error = undefined;
+        this.answerOffset = 0;
+        this.afterSequence = -1;
         this.current = 'thinking';
         this.options.mount(this.dock);
         this.options.changed();
         try {
-            const session = await this.options.create();
+            const started = await this.options.start(text, this.options.context());
             if (generation !== this.generation) {
-                session.dispose();
+                await this.options.interrupt(started.runId).catch(() => undefined);
                 return;
             }
-            this.session = session;
-            this.unsubscribe = session.subscribe(() => {
-                if (generation !== this.generation)
-                    return;
-                this.answerText = session.answer();
-                this.options.changed();
-            });
-            await session.prompt(`${this.options.snapshot()}\n\nSide question: ${text}`);
-            if (generation !== this.generation)
-                return;
-            this.answerText = session.answer();
-            const failure = session.failure();
-            if (failure) {
-                this.current = 'failed';
-                this.error = failure;
-            }
-            else
-                this.current = 'answered';
+            this.runId = started.runId;
+            void this.poll(generation);
         }
         catch (error) {
             if (generation !== this.generation)
                 return;
             this.current = 'failed';
             this.error = error instanceof Error ? error.message : String(error);
+            this.options.changed();
         }
+    }
+    /** Scrolls the answer while it is longer than the dock. */
+    scroll(direction) {
+        const step = Math.max(1, ANSWER_ROWS - 2);
+        this.answerOffset = Math.max(0, this.answerOffset + (direction === 'up' ? -step : step));
         this.options.changed();
     }
+    /** Copies the whole side answer, including any lines outside the dock. */
+    async copyAnswer() {
+        if (this.answerText)
+            await this.options.copyText(this.answerText);
+    }
     /** Interrupts a running side question and removes the dock. */
     async dismiss() {
         this.generation++;
-        this.current = undefined;
         await this.release();
+        this.current = undefined;
         this.options.mount(undefined);
         this.options.changed();
     }
-    async release() {
-        const session = this.session;
-        this.session = undefined;
-        this.unsubscribe?.();
-        this.unsubscribe = undefined;
-        if (!session)
+    async poll(generation) {
+        const runId = this.runId;
+        if (!runId || generation !== this.generation)
             return;
         try {
-            await session.abort();
+            const result = await this.options.read(runId, this.afterSequence);
+            if (generation !== this.generation)
+                return;
+            for (const event of result.events) {
+                this.afterSequence = Math.max(this.afterSequence, event.sequence);
+                const data = payload(event);
+                if (event.type === 'message.delta' && typeof data.text === 'string')
+                    this.answerText += data.text;
+                if (event.type === 'message.completed' && data.role === 'assistant' && typeof data.text === 'string')
+                    this.answerText = data.text;
+                if (event.type === 'failed')
+                    this.error = typeof data.message === 'string' ? data.message : 'The side question failed.';
+                if (event.type === 'status.changed' && data.status === 'failed')
+                    this.error = typeof data.reason === 'string' ? data.reason : 'The side question failed.';
+                if (event.type === 'status.changed' && data.status === 'interrupted')
+                    this.error = 'The side question was interrupted.';
+                if (event.type === 'completed')
+                    this.current = 'answered';
+                if (event.type === 'failed' || event.type === 'status.changed' && ['failed', 'interrupted'].includes(String(data.status)))
+                    this.current = 'failed';
+            }
+            if (result.run.status === 'completed')
+                this.current = 'answered';
+            if (result.run.status === 'failed' || result.run.status === 'interrupted') {
+                this.current = 'failed';
+                this.error ??= result.run.terminalReason ?? 'The side question did not complete.';
+            }
+            this.options.changed();
+            if (this.current === 'thinking')
+                this.pollTimer = setTimeout(() => { void this.poll(generation); }, POLL_INTERVAL_MS);
         }
-        catch { /* A side run that cannot be stopped is still dropped. */ }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            this.current = 'failed';
+            this.error = error instanceof Error ? error.message : String(error);
+            this.options.changed();
+        }
+    }
+    async release() {
+        if (this.pollTimer)
+            clearTimeout(this.pollTimer);
+        this.pollTimer = undefined;
+        const runId = this.runId;
+        this.runId = undefined;
+        if (!runId || this.current !== 'thinking')
+            return;
         try {
-            session.dispose();
+            await this.options.interrupt(runId);
         }
-        catch { /* Cleanup cannot keep the dock open. */ }
+        catch { /* The dock can still be dismissed if a run already stopped. */ }
     }
-    /** The dock: a neutral rule, the inline question, its answer, and a hint, separated by blank rows. */
+    /** The dock: question, a scrollable answer window, and a hint for browsing or copying. */
     render(width) {
         if (width < 1 || !this.current)
             return [];
@@ -184,14 +213,18 @@ export class SideQuestion {
             question[QUESTION_ROWS - 1] = truncateToWidth(question[QUESTION_ROWS - 1], inner - 1, '') + theme.fg('muted', '…');
         const text = this.current === 'failed' ? `${this.answerText ? `${this.answerText}\n` : ''}${this.error ?? 'The side question failed.'}` : this.answerText;
         const wrapped = text ? text.split('\n').flatMap(line => line ? wrapTextWithAnsi(safeText(line), inner) : ['']) : [];
-        const shown = wrapped.slice(0, ANSWER_ROWS).map(line => this.current === 'failed' ? theme.fg('error', line) : line);
-        const more = wrapped.length - shown.length;
+        const maxOffset = Math.max(0, wrapped.length - ANSWER_ROWS);
+        this.answerOffset = Math.min(this.answerOffset, maxOffset);
+        const shown = wrapped.slice(this.answerOffset, this.answerOffset + ANSWER_ROWS).map(line => this.current === 'failed' ? theme.fg('error', line) : line);
+        const before = this.answerOffset;
+        const after = Math.max(0, wrapped.length - before - shown.length);
+        const textHint = before || after ? `PgUp/PgDn browse · ${before ? `${before} above` : ''}${before && after ? ' · ' : ''}${after ? `${after} below` : ''} · ` : '';
         return [
             neutralRule(width, theme),
             ...question.map(line => padded(line, width)),
             ...(shown.length ? ['', ...shown.map(line => padded(line, width))] : []),
             '',
-            footerRow(`${more > 0 ? `+${more} more lines · ` : ''}/btw or Esc to dismiss`, width, theme)
+            footerRow(`${textHint}Ctrl+X copy · /btw or Esc dismiss`, width, theme)
         ].map(line => truncateToWidth(line, width, ''));
     }
 }

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

@@ -1,5 +1,6 @@
 import { Theme, type AutocompleteProviderFactory, type ExtensionUIContext, type KeybindingsManager, type WorkingIndicatorOptions } from '@earendil-works/pi-coding-agent';
 import { type AutocompleteProvider, type EditorComponent, type TUI } from '@earendil-works/pi-tui';
+import { type GroupedSelectOption } from "./dialogs.js";
 type EditorFactory = Parameters<ExtensionUIContext['setEditorComponent']>[0];
 type HeaderFactory = Parameters<ExtensionUIContext['setHeader']>[0];
 type FooterFactory = Parameters<ExtensionUIContext['setFooter']>[0];
@@ -37,6 +38,7 @@ export interface TerminalUiOptions {
 export interface TerminalUi extends ExtensionUIContext {
     readonly state: TerminalUiState;
     secretInput: ExtensionUIContext['input'];
+    selectGrouped(title: string, options: readonly GroupedSelectOption[], opts?: Parameters<ExtensionUIContext['select']>[2]): Promise<string | undefined>;
     wrapAutocomplete(provider: AutocompleteProvider): AutocompleteProvider;
     reset(): void;
     setThemes(themes: Theme[]): void;

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

@@ -22,6 +22,7 @@ export function createTerminalUi(options) {
     return {
         state,
         select: (title, items, opts) => dialogs.select(title, items, opts),
+        selectGrouped: (title, items, opts) => dialogs.selectGrouped(title, items, opts),
         confirm: (title, message, opts) => dialogs.confirm(title, message, opts),
         input: (title, placeholder, opts) => dialogs.input(title, placeholder, opts),
         secretInput: (title, placeholder, opts) => dialogs.input(title, placeholder, opts, true),

package/dist/sdk/tools/askUser.js

@@ -1,3 +1,5 @@
+// Asking the person a question and waiting for the answer: part of every session.
+import { QUESTION_SKETCH_MAX_LENGTH, QUESTION_SKETCH_PATTERN, questionSketchError } from "../sessions/contracts.js";
 export const ASK_USER = 'ask_user';
 const MAX_OPTIONS = 6;
 const text = (value) => (typeof value === 'string' ? value.trim() : '');
@@ -16,16 +18,18 @@ export function askUserTool(run) {
     return {
         name: ASK_USER,
         label: 'Ask the user',
-        description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 2–3 word summary and aim to keep each question to 25 words or fewer. ' +
-            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. Use it when you need a decision, not for small talk.',
+        description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 1–2 word label and aim to keep each question to 25 words or fewer. ' +
+            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision, not for small talk.',
         parameters: (Type) => Type.Object({
             questions: Type.Array(Type.Object({
-                summary: Type.String({ description: 'A concise 2–3 word summary label' }),
+                summary: Type.String({ description: 'A concise label of one or two words' }),
                 question: Type.String({ description: 'A clear, standalone question; aim for 25 words or fewer' }),
+                uiSketch: Type.Optional(Type.Literal(true, { description: 'Enable an ASCII sketch preview; when true, every choice must include a sketch.' })),
                 options: Type.Array(Type.Object({
                     label: Type.String({ description: 'A short choice; do not add a recommendation suffix to the label' }),
                     description: Type.String({ description: 'Required. Briefly explain this choice in 25 words or fewer.' }),
-                    recommended: Type.Optional(Type.Boolean({ description: 'Whether to show this choice as a visual recommendation; at least one choice per question must be recommended, it is not preselected, and answers use the original label' }))
+                    recommended: Type.Optional(Type.Boolean({ description: 'Whether to show this choice as a visual recommendation; at least one choice per question must be recommended, it is not preselected, and answers use the original label' })),
+                    sketch: Type.Optional(Type.String({ minLength: 1, maxLength: QUESTION_SKETCH_MAX_LENGTH, pattern: QUESTION_SKETCH_PATTERN, description: 'Literal ASCII UI wireframe: 1–24 LF-separated lines, at most 80 printable ASCII characters per line. Include the affected element and neighboring UI using structured table/panel borders with fixed, matching outer-edge columns on every row. Required for every choice when uiSketch is true.' }))
                 }), {
                     minItems: 1,
                     maxItems: MAX_OPTIONS,
@@ -37,26 +41,33 @@ export function askUserTool(run) {
         execute: async (input) => {
             if (!Array.isArray(input.questions) || input.questions.length < 1 || input.questions.length > 5)
                 return 'Ask between one and five questions.';
+            let invalidSketchMode = false;
+            let invalidSketchValue = false;
             const questions = input.questions.map((raw) => {
                 const item = raw;
                 const summary = text(item.summary);
                 const question = text(item.question);
+                if (item.uiSketch !== undefined && item.uiSketch !== true)
+                    invalidSketchMode = true;
                 const options = (Array.isArray(item.options) ? item.options : [])
                     .map((option) => {
                     const choice = option;
+                    if (choice.sketch !== undefined && typeof choice.sketch !== 'string')
+                        invalidSketchValue = true;
                     return {
                         label: text(choice.label),
                         description: text(choice.description),
-                        ...(choice.recommended === true ? { recommended: true } : {})
+                        ...(choice.recommended === true ? { recommended: true } : {}),
+                        ...(typeof choice.sketch === 'string' ? { sketch: choice.sketch } : {})
                     };
                 })
                     .filter((option) => option.label)
                     .slice(0, MAX_OPTIONS);
                 const multiSelect = options.length > 1 && item.multiSelect === true;
-                return { summary, question, options, multiSelect, allowText: true };
+                return { summary, question, options, ...(item.uiSketch === true ? { uiSketch: true } : {}), multiSelect, allowText: true };
             });
-            if (questions.some((question) => !question.summary || question.summary.length > 100))
-                return 'Each question needs a short summary of no more than 100 characters.';
+            if (questions.some((question) => !question.summary || question.summary.length > 100 || question.summary.split(/\s+/u).filter(Boolean).length > 2))
+                return 'Each question needs a concise 1–2 word summary label of no more than 100 characters.';
             if (questions.some((question) => !question.question))
                 return 'Every question needs a question sentence.';
             if (questions.some((question) => question.options.length === 0))
@@ -67,6 +78,13 @@ export function askUserTool(run) {
                 return 'A single-choice question may recommend at most one option.';
             if (questions.some((question) => question.options.some((option) => !option.description)))
                 return 'Every choice needs a short description. Aim for 25 words or fewer.';
+            if (invalidSketchMode)
+                return 'Set uiSketch to true to enable question sketches.';
+            if (invalidSketchValue)
+                return 'Each choice sketch must be text.';
+            const sketchError = questions.map((question) => questionSketchError(question.uiSketch, question.options)).find(Boolean);
+            if (sketchError)
+                return sketchError;
             const answers = await run.requestAnswers(questions);
             return questions.map((question, index) => `${question.summary}: ${describeAnswer(answers[index])}`).join('\n');
         }