@xingular/harness 1.0.0 → 1.2.0

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

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

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

@@ -1,2 +1,2 @@
 // The terminal's plan mode uses the session's read-only tool set.
-export { parseProposedPlan, planModeTools } from "../../sessions/planMode.js";
+export { normalModeTools, parseProposedPlan, planModeTools, 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';
+    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,31 @@
+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([
+        ['annotations:notes', async () => openPage('notes')],
+        ['annotations:annotate', async (argument) => {
+                const start = parseAnnotate(argument);
+                if (typeof start === 'string')
+                    host.ui.notify(start, 'error');
+                else
+                    await openPage('annotate', { annotate: start });
+            }],
+        ['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' })]
+    ]);
+    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/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,8 +2,10 @@ 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 { observeProviderResponses } from "../../usage/limits/capture.js";
+import { limitHeaders } from "../../usage/limits/normalize.js";
 import { loadPiAdapter } from "./piAdapter.js";
 import { loadPi } from "../../pi/runtime.js";
 import { sessionUiContext } from "./sessionUi.js";
@@ -101,8 +103,16 @@ export async function createTerminalRuntime(args, host) {
     const identity = await controlCall('accounts.session').catch(() => null);
     const account = identity && typeof identity.accountId === 'string' && typeof identity.label === 'string'
         ? Object.freeze({ accountId: identity.accountId, label: identity.label }) : null;
-    const adapter = await loadPiAdapter();
+    await loadPiAdapter();
     const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, 'auth.json'), modelsPath: join(agentDir, 'models.json') });
+    // This process makes the model requests, so it is where response headers are seen. Only the
+    // limit-bearing headers cross the socket, and the parent throttles what it stores.
+    observeProviderResponses(modelRuntime, (provider, response) => {
+        const headers = limitHeaders(response.headers);
+        if (!Object.keys(headers).length)
+            return;
+        void controlCall('terminal.usage.headers', { provider, status: response.status, headers }).catch(() => undefined);
+    });
     const listeners = new Set();
     const changes = new Set();
     const beforeChanges = new Set();
@@ -157,11 +167,21 @@ export async function createTerminalRuntime(args, host) {
             additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
             additionalThemePaths: prepared.themes,
             extensionFactories: [
-                ...adapter.builtins,
                 { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session), hidden: true },
                 // A model picked in the terminal reaches Pi as this event. A restore is not a pick.
                 { name: 'harness-mode-choices', factory: pi => { pi.on('model_select', event => { if (event.source !== 'restore')
-                        void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true }
+                        void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true },
+                // The bridge registers parent capabilities when delegation is available. Runs without
+                // delegation still need the same frozen snapshot, after the bridge has begun the run.
+                { name: 'harness-run-capabilities', factory: pi => {
+                        pi.on('before_agent_start', async () => {
+                            if (!pi.getAllTools().some(tool => tool.name === 'spawn_subagent')) {
+                                const snapshot = await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), plan: planRun.active });
+                                if (Array.isArray(snapshot.connectors))
+                                    planRun.connectors = snapshot.connectors;
+                            }
+                        });
+                    }, hidden: true }
             ],
             appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
         });
@@ -197,6 +217,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 +317,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/sessionPicker.d.ts

@@ -0,0 +1,40 @@
+import type { SessionInfo, Theme } from '@earendil-works/pi-coding-agent';
+import { type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TerminalPage } from "./page.js";
+import type { TerminalMouseInput } from "./mouse.js";
+export declare function formatSessionRelativeTime(value: Date, now?: number): string;
+export declare function formatSessionSize(bytes: number | undefined): string;
+export interface ResumeSessionsPageOptions {
+    theme: () => Theme;
+    cwd(): string;
+    branch(): string | null;
+    listSessions(signal: AbortSignal): Promise<SessionInfo[]>;
+    select(path: string): void;
+    cancel(): void;
+    changed(): void;
+}
+export declare class ResumeSessionsPage implements TerminalPage {
+    private readonly options;
+    readonly presentation: "fullscreen";
+    private readonly list;
+    private loading;
+    private loaded;
+    private disposed;
+    private error;
+    private abort?;
+    constructor(options: ResumeSessionsPageOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    tabs(): {
+        id: string;
+        title: string;
+    }[];
+    activeTab(): string;
+    hint(): string;
+    activate(): void;
+    dispose(): void;
+    private load;
+    handleInput(data: string): boolean;
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    render(width: number, rows: number): string[];
+}

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

@@ -0,0 +1,141 @@
+import { stat } from 'node:fs/promises';
+import { stripTerminalSequences } from '@earendil-works/pi-tui';
+import { displayProjectName, singleLine } from "./status.js";
+import { FilterList } from "./list.js";
+const RELATIVE_TIME = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+const TIME_UNITS = [
+    [365 * 24 * 60 * 60 * 1000, 'year'],
+    [30 * 24 * 60 * 60 * 1000, 'month'],
+    [7 * 24 * 60 * 60 * 1000, 'week'],
+    [24 * 60 * 60 * 1000, 'day'],
+    [60 * 60 * 1000, 'hour'],
+    [60 * 1000, 'minute'],
+    [1000, 'second']
+];
+export function formatSessionRelativeTime(value, now = Date.now()) {
+    const delta = value.getTime() - now;
+    if (!Number.isFinite(delta))
+        return 'unknown time';
+    const absolute = Math.abs(delta);
+    const unit = TIME_UNITS.find(([size]) => absolute >= size);
+    return unit ? RELATIVE_TIME.format(Math.round(delta / unit[0]), unit[1]) : RELATIVE_TIME.format(0, 'second');
+}
+export function formatSessionSize(bytes) {
+    if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? Math.round(size) : size.toFixed(1)}${units[unit]}`;
+}
+function safe(value) {
+    return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
+}
+export class ResumeSessionsPage {
+    options;
+    presentation = 'fullscreen';
+    list;
+    loading = false;
+    loaded = false;
+    disposed = false;
+    error;
+    abort;
+    constructor(options) {
+        this.options = options;
+        this.list = new FilterList({
+            theme: options.theme,
+            search: 'always',
+            rowGap: 1,
+            noun: ['session', 'sessions'],
+            empty: 'No saved sessions in this project',
+            onCancel: options.cancel,
+            onActivate: row => { if (row.data)
+                options.select(row.data); }
+        });
+    }
+    get focused() { return this.list.focused; }
+    set focused(value) { this.list.focused = value; }
+    tabs() { return [{ id: 'sessions', title: 'Resume session' }]; }
+    activeTab() { return 'sessions'; }
+    hint() { return '↑/↓ select · type to search · Enter resume'; }
+    activate() {
+        if (this.loaded || this.loading || this.disposed)
+            return;
+        this.abort = new AbortController();
+        void this.load(this.abort.signal);
+    }
+    dispose() {
+        this.disposed = true;
+        this.abort?.abort();
+    }
+    async load(signal) {
+        this.loading = true;
+        this.options.changed();
+        try {
+            const sessions = await this.options.listSessions(signal);
+            const branch = singleLine(this.options.branch() ?? '') || '—';
+            const rows = await Promise.all(sessions.map(async (session) => {
+                let bytes;
+                try {
+                    bytes = (await stat(session.path)).size;
+                }
+                catch { /* A removed or unreadable file remains selectable and shows an unknown size. */ }
+                const title = session.name?.trim() || session.firstMessage.trim() || session.id;
+                const project = displayProjectName(session.cwd || this.options.cwd());
+                const modified = formatSessionRelativeTime(session.modified);
+                const subtitle = `${modified} · ${project}:${branch} · ${formatSessionSize(bytes)}`;
+                return {
+                    id: session.path,
+                    label: singleLine(title),
+                    subtitle,
+                    searchText: `${title} ${session.firstMessage} ${session.id} ${subtitle}`,
+                    data: session.path
+                };
+            }));
+            if (this.disposed || signal.aborted)
+                return;
+            this.list.setRows(rows);
+            this.error = undefined;
+        }
+        catch (error) {
+            if (!this.disposed && !signal.aborted)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loaded = true;
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    handleInput(data) {
+        if (!this.list.handleInput(data))
+            return false;
+        this.options.changed();
+        return true;
+    }
+    handleMouse(event) {
+        if (event.type === 'move')
+            return { handled: true, render: false };
+        if (event.type === 'wheel')
+            return undefined;
+        const result = this.list.handleMouse(event);
+        if (result?.render)
+            this.options.changed();
+        return result;
+    }
+    render(width, rows) {
+        if (width < 1 || rows < 1)
+            return [];
+        const theme = this.options.theme();
+        if (this.error)
+            return [theme.fg('error', `Could not read saved sessions: ${safe(this.error)}`)];
+        if (this.loading || !this.loaded)
+            return [theme.fg('dim', 'Loading saved sessions…')];
+        return this.list.render(width, rows);
+    }
+}

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 {};